gilde

← All craftbooks

Typed SDK Wrapper for an External API

Build: software and codeevalv1.0.1released 2026-07-16workflow: build-loop

Wrap a third-party HTTP API as a clean, typed client library — studying the real API surface first so the wrapper matches reality, not guesses. Studies the API FIRST — endpoints, auth, request/response shapes, rate limits, error formats, and pagination from the actual docs — then builds a typed client with sensible methods and error handling, then tests each method against a mocked API including auth and error paths. Covers reading API docs, typed request/response models, auth handling, retry/rate-limit awareness, pagination helpers, error mapping, and a mockable client.

Steps

Entry step: api-study. Each step names the specialist role it wants; the full working prompt is expandable.

  1. Study the APIresearcherentry

    extract endpoints, auth, shapes, limits from the docs

    Show working prompt
    Study the real external API before writing a client — the wrapper must match reality, not a guess. Step 1: From the API's documentation, list the endpoints you will wrap with their methods, paths, and required params. Step 2: Capture the AUTH scheme (API key header, OAuth bearer, etc.) and how it is attached to requests. Step 3: Record the request and response JSON shapes for each endpoint, the error response format and status codes, the pagination scheme, and any rate limits. Step 4: Note quirks (snake_case fields, nullable fields, enum values). Step 5: Write a numbered acceptance-criteria checklist of 5-9 items (e.g. 'each wrapped endpoint has a typed method matching the real shape', 'auth is attached correctly', 'API errors map to a typed client error', 'pagination is handled'). `write_task_note` the API study (endpoints + shapes + auth + errors) + checklist and write the same to the produces path.
  2. Build the clientdeveloper

    implement the typed client to the study

    Show working prompt
    Implement the typed client to the API study. Step 1: Define request/response types matching the real shapes (including the API's casing and nullability), and a typed error type. Step 2: Write a client class/factory that takes config (base URL, credentials) and attaches auth to every request as studied. Step 3: Implement one method per wrapped endpoint with typed params and a typed return; parse responses into the typed models. Step 4: Map non-2xx responses to the typed client error (do not leak raw HTTP), and add a pagination helper and basic retry/backoff for rate limits if the API needs it. Step 5: Make the transport injectable so it can be mocked in tests. Write the client to the produces path. On a loop-back, fix only the named gaps. `write_task_note` the file path and which criteria now pass.
  3. Test against a mockdeveloper

    test each method, auth, errors, pagination

    Show working prompt
    Write tests against a mocked transport (no live network). Step 1: For each method, mock the API's documented success response and assert the client returns the correctly-typed parsed result. Step 2: Assert auth headers/credentials are attached to outgoing requests. Step 3: Mock error responses (4xx/5xx) and assert they surface as the typed client error, not a raw HTTP throw. Step 4: Assert the pagination helper walks multiple pages, and retry/backoff fires on a rate-limit response if implemented. `write_task_note` the test file path and pass/fail count.
  4. Evaluatereviewer

    Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.

    Show working prompt
    Run the tests against the mocked API. For EACH acceptance criterion: confirm each method returns the correctly-typed result for the documented response, confirm auth is attached, confirm API errors map to a typed client error (no raw HTTP leak), and confirm pagination/retry behave. Write PASS/FAIL per criterion; a method whose types do not match the real API shape is a FAIL.

Then route — this is the whole point of the loop:

- **Every criterion PASSES →** call `advance_task_step({ ref, stepId: "evaluate", next: "finish" })`.
- **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: "evaluate", next: "build" })` to loop back. The builder fixes exactly those gaps.

Never route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in.
  5. Finishdeveloper

    All acceptance criteria met. Stamp a short summary and report DONE.

    Show working prompt
    Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.

Triggers

Phrases that suggest this craftbook to a crew.

Source

View this craftbook on GitHub · MIT license