api-fetch-wrapper
Wrap a public HTTP API (Open-Meteo weather as the demo) with credential handling, error normalisation, and a single retry on transient network failures. Demonstrates the production-shaped baseline for any "skill that calls an external service" — env-based secrets, structured erro
Install
npx skills add https://github.com/ChronoAIProject/Ornn/tree/develop/examples/api-fetch-wrapper
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install chronoaiproject-ornn@llmmart
git clone https://github.com/ChronoAIProject/Ornn.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole chronoaiproject/ornn collection as a plugin from our marketplace. Git is the plain clone.
README
api-fetch-wrapper
Call a public HTTP API with retries, structured errors, and no-leak credential handling. Demo target is Open-Meteo (keyless, so the example runs out of the box).
Run: echo '{"latitude":52.52,"longitude":13.41}' | bun run src/index.ts
Adapt: swap the upstream URL + shape; add Authorization header reading from env. The retry-and-error-mapping skeleton is the load-bearing part — don't drop it.
See SKILL.md for the full contract.
Skill manifest
api-fetch-wrapper
The case that breaks first in production — a skill that hits an external service. This example covers the four things every such skill needs: secret handling, retry policy, error normalisation, and no-leak-on-failure logging.
Contract
Input (stdin, JSON):
{ "latitude": 52.52, "longitude": 13.41 }
Output (stdout, JSON):
{
"temperatureC": 18.4,
"windSpeedKmh": 12.6,
"fetchedAt": "2026-05-19T08:00:00.000Z"
}
Errors — written to stderr as {"error": "...", "cause": "..."} and exit code 1. Error messages NEVER include the raw upstream response body (it might echo a secret); they include the upstream status code and a short canonical reason.
Required environment
| Var | Purpose |
|---|---|
OPEN_METEO_URL |
Optional override of the upstream host. Defaults to https://api.open-meteo.com. |
| (none for auth) | Open-Meteo is keyless. For an auth'd API, the same skeleton reads process.env.YOUR_API_KEY and passes it via Authorization header. |
Run locally
cd examples/api-fetch-wrapper
bun install
echo '{"latitude":52.52,"longitude":13.41}' | bun run src/index.ts
Adapt this
- Different API — replace the URL, query params, and response shape. The retry / error-mapping skeleton stays.
- API-key auth — read
process.env.YOUR_API_KEYonce at the top, pass it viaAuthorization: Bearer ${apiKey}, and ensure the key never appears in error messages. - Stronger retry — bump
MAX_ATTEMPTS, add exponential backoff with jitter, or distinguish 5xx (retry) vs 4xx (do not retry) explicitly. - Cache — wrap the fetch in a TTL cache when the upstream rate-limits.
Files (ornn)
-
src
-
index.ts 3.6 KB
Loading…
-
-
package.json 282 B
Loading… -
README.md 470 B
# api-fetch-wrapper Call a public HTTP API with retries, structured errors, and no-leak credential handling. Demo target is Open-Meteo (keyless, so the example runs out of the box). **Run:** `echo '{"latitude":52.52,"longitude":13.41}' | bun run src/index.ts` **Adapt:** swap the upstream URL + shape; add `Authorization` header reading from env. The retry-and-error-mapping skeleton is the load-bearing part — don't drop it. See `SKILL.md` for the full contract. -
SKILL.md 2.4 KB
--- name: api-fetch-wrapper description: Wrap a public HTTP API (Open-Meteo weather as the demo) with credential handling, error normalisation, and a single retry on transient network failures. Demonstrates the production-shaped baseline for any "skill that calls an external service" — env-based secrets, structured error output, no leaked API keys in logs, and a deliberate retry policy. The Open-Meteo endpoint used here is keyless on purpose so the example runs without setup; replace `OPEN_METEO_URL` with your own host and add `process.env.MY_API_KEY` for an auth'd version. version: "1.0" license: MIT metadata: category: integration tag: - example - http - external-api - typescript --- # api-fetch-wrapper The case that breaks first in production — a skill that hits an external service. This example covers the four things every such skill needs: secret handling, retry policy, error normalisation, and no-leak-on-failure logging. ## Contract **Input** (stdin, JSON): ```json { "latitude": 52.52, "longitude": 13.41 } ``` **Output** (stdout, JSON): ```json { "temperatureC": 18.4, "windSpeedKmh": 12.6, "fetchedAt": "2026-05-19T08:00:00.000Z" } ``` **Errors** — written to stderr as `{"error": "...", "cause": "..."}` and exit code `1`. Error messages NEVER include the raw upstream response body (it might echo a secret); they include the upstream status code and a short canonical reason. ## Required environment | Var | Purpose | |---|---| | `OPEN_METEO_URL` | Optional override of the upstream host. Defaults to `https://api.open-meteo.com`. | | *(none for auth)* | Open-Meteo is keyless. For an auth'd API, the same skeleton reads `process.env.YOUR_API_KEY` and passes it via `Authorization` header. | ## Run locally ```bash cd examples/api-fetch-wrapper bun install echo '{"latitude":52.52,"longitude":13.41}' | bun run src/index.ts ``` ## Adapt this - **Different API** — replace the URL, query params, and response shape. The retry / error-mapping skeleton stays. - **API-key auth** — read `process.env.YOUR_API_KEY` once at the top, pass it via `Authorization: Bearer ${apiKey}`, and ensure the key never appears in error messages. - **Stronger retry** — bump `MAX_ATTEMPTS`, add exponential backoff with jitter, or distinguish 5xx (retry) vs 4xx (do not retry) explicitly. - **Cache** — wrap the fetch in a TTL cache when the upstream rate-limits.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.