TS Sdk Usage

SUQO TypeScript SDK — usage

@suqo/sdk, server-side only — it holds a full-access API key and must never be bundled into browser code. Node ≥18, zero runtime dependencies (fetch and node:crypto are both built in), strict TypeScript, dual ESM/CJS build.

Not yet published. npm view @suqo/sdk 404s against the real npm registry today (package.json is 0.0.1; specs/versioning.md's 1.0.0 row is "Pending — this ticket's release," not shipped). Don't write npm install @suqo/sdk as a working command — see references/client-setup.md for what actually works right now (installing from a local build/tarball).

Workflow

1. Name the task — checkout flow, subscription dashboard, webhook endpoint, cancellation route, sync job.
2. Load only the reference you need from references/. Never load them all. references/api-surface.md is the authority on signatures; load it before writing any SDK call.
3. Start from a template in templates/ when one is close, rather than writing from scratch.
4. Write against documented methods only. If a reference doesn't cover something, say so — do not invent a method, parameter, or property. In particular: there is no subscriptions.retrieve(id) at all; RateLimitError exists but the live API has never thrown one; rate-limiting and idempotency are both explicitly "planned," not implemented, in the SDK's own docs.
5. Verify — tsc --noEmit against the real SDK types, then the project's own test/lint command. If a sandbox key is available, exercise the code for real; otherwise say plainly that it was only typechecked, not run against the API.

The whole callable surface

There is no subscriptions.retrieve(). Everything above is the complete surface — references/api-surface.md lists exactly what's deliberately not exported too (internal client/auth stubs, the HTTP layer, every serialize*/deserialize* helper).

Rules that trip people up

Apply these without being asked — most bugs against this SDK are one of them.

• Decimal fields are strings. price, vatPercentage, totalSubscribers, every amount. Never coerce to number.
• customer on the SDK is client on the wire — renamed because client collides with the SDK's own client object. Only the root key is renamed; nested billing.* fields get a billing_ wire prefix on write, shipping.* fields don't, and neither is prefixed on read. See references/subscriptions.md — this is the single easiest field-mapping mistake in the SDK.
• Trailing slash is mandatory on every route the SDK calls — the SDK handles this for you, but don't hand-build a URL to bypass it.
• Writes never auto-retry. create, cancel, updateBillingCycle, resume — none of them retry, ever, regardless of maxRetries. No idempotency-key support exists yet. A NetworkError from a write means it may or may not have landed; reconcile with list(), don't resend blindly.
• Two different 400 shapes exist and ValidationError normalizes both — field-keyed (fieldErrors) and detail-shaped (message only). See references/errors.md.
• customers is real here, unlike its stub-only counterpart in other SUQO SDKs' specs. The SDK repo's own specs/SDK-SPEC.md/typescript-addendum.md are stale on this point — source, tests, and docs/user/customers.md all confirm it's a fully working resource. See references/customers.md.

Webhooks

suqo.webhooks.verify() needs no network call and the API key plays no role in verification — but it's still a method on an already-constructed SuqoClient (there's no standalone export for it). Never throws; every failure mode returns false.

const secret = process.env.SUQO_WEBHOOK_SECRET;
// verify() itself handles a missing secret fine (returns false, doesn't throw) — check it
// explicitly anyway so a misconfigured deployment gets a distinct, loud signal instead of
// blending into ordinary bad-signature noise.
if (!secret) throw new Error("SUQO_WEBHOOK_SECRET is not set");

const signature = req.header("x-suqo-signature");
const timestamp = req.header("x-suqo-timestamp");
if (!signature || !timestamp) throw new Error("Missing signature/timestamp header"); // 400 and stop, in real code

const verified = suqo.webhooks.verify({
  rawBody,                                          // the exact bytes received — see below
  signature,
  timestamp,
  secret,
  toleranceSec: 300,                                // optional, default 300
});

Pass the raw bytes

A body re-serialized from a parse verifies only by luck. Per framework:

// Express: express.raw() scoped to just this route, never mounted globally
router.post("/webhooks/suqo", express.raw({ type: "application/json" }), handler);

// Next.js App Router
const rawBody = await req.text();

// Fastify: no drop-in equivalent — override addContentTypeParser() inside
// this route's own plugin scope (fastify.register(...)), not on the root
// instance, or every other route loses JSON parsing too.

// Plain Node — buffer the chunks yourself before parsing anything

Handler checklist

1. Read the raw body first, before any parsing.
2. Verify, and on false return 400 and stop. Don't parse, don't process.
3. Parse only after verifying — in its own try/catch. A verified signature proves the bytes came from SUQO, not that they're valid JSON; on plain http.ServerResponse this genuinely crashes the process if the 2xx already went out and the parse failure reaches a handler that tries to send a second response (confirmed, not hypothetical — see references/webhooks.md).
4. Return 2xx fast, then process out of band — a slow handler gets retried and duplicated. On a serverless/edge runtime (Vercel, Lambda, ...) that pattern is unsafe: the function can be frozen the instant the response is sent, silently dropping unawaited work — await the processing there instead, or use the platform's own keep-alive (after(), waitUntil). See templates/webhook-nextjs-route.ts.
5. Be idempotent, keyed on subscription_id (checkout/status events) or api_key_id (api_key.* events) — no event has a field literally named id. Redelivery is normal; there's no replay store.
6. Never echo the body back, and never treat a field inside it as an authorization decision on its own — verification confirms it came from SUQO, not that its contents are safe to act on blindly.

Exact signed-payload format, the event type catalogue (stays snake_case on purpose), and the dashboard's test-event quirk are in references/webhooks.md.

Reference index

Templates index

Testing SDK code

Stub the global fetch, the same way the SDK's own test suite does (test/http/HttpClient.test.ts) — no extra dependency needed:

import { vi } from "vitest";

vi.stubGlobal("fetch", vi.fn());
vi.mocked(fetch).mockResolvedValueOnce(
  new Response(JSON.stringify({ /* wire-shaped body */ }), { status: 201 }),
);

Every layer above the network — the auth header, retry/backoff, error mapping, pagination — still runs for real; only the raw Response is faked. msw is the route/URL-level alternative the SDK's own test/contract/ suite uses.

Don't reach for SuqoClientOptions.dispatcher for this, even though it's a real, documented option forwarded into every fetch() call. Passing a MockAgent/MockPool from a separately npm-installed undici package as that per-call dispatcher is not reliably recognized by Node's built-in global fetch — confirmed here to silently fall through to a real network attempt (and hang) rather than intercept, since the two are different module realms. undici's own setGlobalDispatcher(mockAgent) (not the per-call option) is cross-realm-safe if you want that layer specifically, but vi.stubGlobal is simpler and needs nothing extra installed.

Notes for maintainers

Update the Reference index and Templates index tables above whenever a file is added to references/ or templates/ — this skill's own history has already drifted out of sync with itself more than once from a table edit getting missed.

Never mock SuqoClient or a resource directly — mocking the thing under test tests the mock instead of the integration, the same rule PHP's skill holds to for HttpClientInterface.