integration-builder

Integration builder

Produce a production-level craftos_integrations provider for one vendor.

The mechanical part of an integration — file layout, envelope, decorator shape, tag conventions — is maybe 30% of the work and is already specified in craftos_integrations/README.md. The other 70% is judgment: which endpoint groups an agent would realistically use, whether the vendor's auth pools identity or quota, what the canonical identifier shape is, which "delete" is really a PATCH.

So: the machine owns the inventory, the checklist and the verification. You own the scope and auth decisions. Nothing here decides what to expose. It decides whether you wrote down a defensible answer and whether the output passes the gates.

Do not skip to stage 5. Stages 1–4 are what stop you generating 60 plausible methods against endpoints that don't exist.

---

Stage 1 — Acquire the API surface

Get a machine-readable endpoint list before writing anything.

In preference order:

1. An OpenAPI/Swagger schema. Most vendors publish one. Download it and parse it locally — do not read it through a doc-fetching tool.

   curl -sSL -o "$SCRATCH/<name>_schema.json" "https://<vendor>/api/schema/?format=json"
   

   Then group the paths by resource with a short Python script: for each path, the methods available. This is the inventory everything else hangs off.

2. An in-repo API reference. Check skills/<name>-api/SKILL.md and skills/api-gateway/references/<name>.md first — several vendors already have one, written against the live API, and they record quirks the spec does not (PostHog's soft-delete rule came from there).

3. The official REST reference docs, last. Cross-check the version and base URL.

Hard-won: vendor doc pages truncate when fetched and will silently give you a partial endpoint list. The schema does not. If you find yourself fetching a fourth doc page, stop and go get the schema.