Distilled SDK Patch

Recipes

Undocumented error status that maps to a standard class. OpenAPI convert turns 400/403/404/409/422 responses into BadRequest, Forbidden, NotFound, Conflict and UnprocessableEntity, and treats 401/429/500/503 as global. Add the response to the spec:

{ "op": "add",
  "path": "/paths/~1databases~1{id}/delete/responses/422",
  "value": { "description": "Unprocessable Entity" } }

Error that needs its own class — the status is shared by several failures, the status is not in the map above, or the API reports failure inside a 2xx. Add an error shape with matchers and append it to the operation's errors:

{ "op": "add",
  "path": "/shapes/com.flyio.machines#NetworkNotFound",
  "value": {
    "type": "structure",
    "members": { "message": { "target": "smithy.api#String" } },
    "traits": {
      "smithy.api#error": "client",
      "com.distilled.openapi#errorMatchers": [
        { "status": 400, "message": { "includes": "network not found" } }
      ] } } },
{ "op": "add",
  "path": "/shapes/com.flyio.machines#CreateAppIPAssignment/errors/-",
  "value": { "target": "com.flyio.machines#NetworkNotFound" } }

• The trait id is whatever the package's generate.ts passes as errorMatchersTrait (com.distilled.openapi#errorMatchers for OpenAPI packages; com.cloudflare.protocols#…, com.gcp.protocols#… elsewhere). A generator that sets none ignores matchers — check before relying on them.
• A matcher's fields all have to match; separate matchers on one class are alternatives. Fields are code, status, message (exact string, or { includes } / { matches }), body (JSON pointer → scalar or text matcher, e.g. { "/success": false }), and headers (name → text matcher). The most specific match across the operation's classes wins, one point per field, so a message matcher beats a bare status matcher on the same status. Match on the stable part of the response — a numeric code or an error type — before free text.
• The error's category (BadRequestError, ServerError, RetryableError, …) comes from smithy.api#httpError and smithy.api#retryable (errorCategories in packages/core/src/codegen/generator.ts), and retry policies act on those categories. Set them deliberately: a client error that arrives as a 5xx should not be retried as a server error.

Field is null or missing on the wire. In the spec: x-nullable: true (Swagger 2.0), nullable: true (OpenAPI 3.0), or null in the type array (3.1). Being nullable and being required are independent: a field that is always present but sometimes null keeps its required entry; a field that is sometimes absent leaves the required list (a replace of the whole list — say which fields left in the description).

Secret without a sensitive mark. x-sensitive: true on the string property. Convert already marks names matching its default patterns (password, api_token, plain_text, …; isSensitiveProperty in packages/core/src/codegen/openapi.ts), so check the generated type is not already Redacted before adding one.

One operation returns more than the shared schema promises. Copy the schema to a new name, change the copy, and re-point only that operation's response — the PlanetScale password-with-secret patch gives create and renew a plain_text that is never null while get and list keep the shared nullable one. A response schema that is simply wrong gets its $ref replaced.

Step 4 — regenerate

pnpm generate <pkg>

Always regenerate with pnpm generate <pkg>, even for one service. It converts, generates and formats; a bare convert (with or without --resource) leaves .generated-specs/ unformatted, and the diff then shows every file as changed.

Do not add a per-package test for the patch. The generated diff in the next step shows what the patch changes, and the behaviour it relies on (error matchers, nullability, sensitive members) is tested once in packages/core. When updating an existing patch PR that added one, delete that test in the same update.

Step 5 — check the change

git diff origin/main -- packages/<pkg>/.generated-specs packages/<pkg>/src/services

Diff against origin/main so a patch already committed on a PR branch still shows up. Read the diff against the description:

• exactly the shapes and members meant changed — done.
• nothing changed — the spec already says this (drop the patch), or the pointer landed somewhere convert does not read.
• more changed than intended — the patch reaches further than meant (a shared shape, say); narrow it.

Do not run pnpm patches:audit here. A patch is written to change the model, and the diff above already shows whether it did. The audit rebuilds the whole model once per patch file (minutes for cloudflare) and only answers a question once the spec has moved underneath existing patches. That is the distilled-sdk-update skill's job.

Then check the generated TypeScript reads the way a caller needs, run pnpm exec tsc -b packages/<pkg> --noCheck false, and commit the patch with the src/services/ it produced (and .generated-specs/ for a convert-stage package), as fix(<pkg>): … naming what callers gain ("type 422s observed on the live API").