Docs inside the package
The SDK ships a generated markdown reference so a coding agent (or you) can
find the right operation by reading files in node_modules — no network, no
extra tooling:
docs/catalog.md — one grep-friendly line per operation, grouped by domain.docs/operations/<domain>/<operationId>.md — variables, a call example,
gateway notes (idempotency, result caps, org guards), and the exact
response shape.- Field-level types are TypeScript — grep the type name from the operation
page in
dist/generated/operationTypes.d.ts.
Point your coding agent at itThe tree is generated from the same operation manifest the gateway
executes, so it can never drift from what the client actually does. If an
AI agent is writing your integration, telling it to read
node_modules/@goliath-data/sdk/docs/catalog.md first is the fastest path
to a correct call.
Live discovery endpoints
The API also documents itself at runtime, which covers the two things static
docs cannot — your key’s actual authorization, and operations newer than your
installed SDK:
GET /api/v1/operations — the catalog as JSON, with a per-key
authorized flag on every operation.GET /api/v1/operations/:operationId — full detail for one operation,
including operations added after your SDK release. Input-object variables are
expanded to their nested fields, so a mutation’s variable shape is spelled
out rather than left as an opaque type name.GET /api/v1/help — the whole API as one markdown document (no key
required).
Untyped escape hatch
Operations added to the API after your SDK version still work — untyped:
Versioning
The SDK’s typed surface is generated from the same operation catalog the API
executes, and the package version follows semver for that surface — an added
operation is a minor release, a changed or removed one is a major. If a method
you expect is missing, your installed release predates the operation: use
execute() now, and pick up the types with the next SDK upgrade.