feat(core): parse Retry-After / Ratelimit headers and honor them in retry policy

[sam-goodwin]

Summary

Standardizes how SDKs surface server-provided retry hints. Stacks on top of #225.

• Core defines an opaque retryAfter: Duration.Duration field on every retryable error (TooManyRequests, Locked, InternalServerError, BadGateway, ServiceUnavailable, GatewayTimeout).
• Core ships parsing primitives: parseRetryAfter (RFC 7231 §7.1.3 — delay-seconds or HTTP-date), parseRatelimit (IETF httpapi-ratelimit-headers — r=0, t=30), and parseServerRetryHint (try one then the other).
• Each SDK's matchError now accepts an optional headers arg and is responsible for deriving a Duration from whatever the service actually returns. Cloudflare, GCP, Kubernetes, plus all 15 scaffolded SDKs (turso, planetscale, neon, stripe, axiom, posthog, supabase, coinbase, fly-io, mongodb-atlas, typesense, workos, prisma-postgres, azure, expo-eas) populate retryAfter via parseServerRetryHint(headers) for the standard cases. The scripts/create-sdk.ts template emits the same wiring so newly scaffolded SDKs honor server hints by default.
• Default retry policy (makeDefault) and the new throttlingFactory / transientFactory honor error.retryAfter with precedence over the exponential backoff, capped at 60s so a misbehaving server can't park us forever.
• AWS untouched — uses its own retry stack.
• Pipeline awareness: prompts in scripts/error-discovery.ts and scripts/generate-tests.ts teach sub-agents to preserve the headers parameter on matchError and pass retryAfter into retryable error constructors when patching, so the convention sticks across regeneration.

Override seam

If a service uses bespoke headers or body fields for cooldown, edit the SDK's matchError:

const retryAfter =
  parseServerRetryHint(headers) ??
  parseFooBespokeHeader(headers["x-foo-cooldown"]) ??
  parseFooBodyField(errorBody);
return Effect.fail(new TooManyRequests({ message, retryAfter }));

Test plan

• bun run test in packages/core — 29 new unit tests pass (header parsing edge cases + policy honoring retryAfter)
• bunx tsgo --noEmit clean for cloudflare, kubernetes, turso, planetscale, neon, stripe, axiom, posthog, supabase, coinbase, fly-io, mongodb-atlas, typesense, workos, prisma-postgres, azure, expo-eas
• bunx oxlint src clean across all 18 SDKs
• GCP shows pre-existing readonly-array errors only (also present on main, out of scope)

Made with Cursor

[alchemy-version-bot]

Install the packages built from this commit:

@distilled.cloud/core

bun add https://pkg.distilled.cloud/core/fc76631

@distilled.cloud/aws

bun add https://pkg.distilled.cloud/aws/fc76631

@distilled.cloud/cloudflare

bun add https://pkg.distilled.cloud/cloudflare/fc76631

@distilled.cloud/gcp

bun add https://pkg.distilled.cloud/gcp/fc76631

@distilled.cloud/neon

bun add https://pkg.distilled.cloud/neon/fc76631

@distilled.cloud/planetscale

bun add https://pkg.distilled.cloud/planetscale/fc76631

@distilled.cloud/prisma-postgres

bun add https://pkg.distilled.cloud/prisma-postgres/fc76631

@distilled.cloud/stripe

bun add https://pkg.distilled.cloud/stripe/fc76631

@distilled.cloud/supabase

bun add https://pkg.distilled.cloud/supabase/fc76631

@distilled.cloud/posthog

bun add https://pkg.distilled.cloud/posthog/fc76631

@distilled.cloud/axiom

bun add https://pkg.distilled.cloud/axiom/fc76631

@distilled.cloud/azure

bun add https://pkg.distilled.cloud/azure/fc76631

@distilled.cloud/kubernetes

bun add https://pkg.distilled.cloud/kubernetes/fc76631

@distilled.cloud/coinbase

bun add https://pkg.distilled.cloud/coinbase/fc76631

@distilled.cloud/mongodb-atlas

bun add https://pkg.distilled.cloud/mongodb-atlas/fc76631

@distilled.cloud/fly-io

bun add https://pkg.distilled.cloud/fly-io/fc76631

@distilled.cloud/turso

bun add https://pkg.distilled.cloud/turso/fc76631

@distilled.cloud/typesense

bun add https://pkg.distilled.cloud/typesense/fc76631

@distilled.cloud/workos

bun add https://pkg.distilled.cloud/workos/fc76631

@distilled.cloud/expo-eas

bun add https://pkg.distilled.cloud/expo-eas/fc76631