Changelog & versioning

Versioning policy

The SDK follows strict SemVer: MAJOR.MINOR.PATCH.

• MAJOR — bumped on either trigger: the API's path version changes (/api/v1/ → /api/v2/), or the SDK introduces its own breaking change with no API change at all (a renamed export, a changed return shape).
• MINOR — additive, backward-compatible: a new resource, a new optional parameter, a new non-breaking field.
• PATCH — fixes only, no contract change of any kind.

Anything removed is deprecated one minor ahead with a documented warning, removed only at the next major — no feature is ever removed in a minor or patch release.

Compatibility table

1.1.0 - 2026-09-24

Added

• customers.create({ phone, fullName?, email?, address? }) — records a customer without opening a subscription. A phone you already hold updates that customer instead, so it's safe to retry yourself; the SDK never retries it automatically.
• customers.update(id, { fullName?, email?, address? }) — updates only the given fields; "" clears one. The phone can't be changed.
• CreateCustomerParams, UpdateCustomerParams and ProductImage types exported.

Changed

• Breaking: Customer.id is a string (e.g. "cus_1ce18d624"), not a number — the API never sent an integer, and the number type made customers.retrieve() uncallable with a real id. Upgrading: switch customer ids typed as number to string.
• Breaking: Customer.address added (string | null) — it was on the wire but missing from the type. Upgrading: add address: null to any Customer objects you build yourself.
• Breaking: Product.productImage is ProductImage[] ({ image, imageOrder }), not string[] — the API sends image objects. 1.0.0 passed them through untouched as { image, image_order }; 1.1.0 types them and renames image_order to imageOrder. Upgrading: use productImage[i].image where you used productImage[i] as a URL, and imageOrder where you read image_order.

Fixed

• customers.retrieve() / update() reject an empty, "." or ".." id with SuqoConfigError instead of silently hitting the wrong endpoint.
• Missing buyerPhone/buyerEmail/fullName/address keys come back as null, never undefined.

1.0.0 - 2026-09-11

Added

• SuqoClient — environment (sandbox/live) inferred automatically from the API key prefix, with SuqoConfigError thrown before any request on a malformed key or a conflicting baseUrl override.
• products.list() / .autoPaging() — browse the seller's product catalog. Works before KYC.
• subscriptions.list() / .create() / .cancel() / .updateBillingCycle() / .resume() / .autoPaging() — full subscription lifecycle, including create-time reuse of an inactive/expired subscription for the same buyer + product + billing period.
• customers.list() / .retrieve() — read-only access to the seller's customer records.
• webhooks.verify() — HMAC-SHA256 signature verification for inbound webhook deliveries, with replay protection via a configurable timestamp tolerance. Makes no network call.
• Automatic retries with exponential backoff and jitter for read operations, on NetworkError, 429, and 5xx — honoring a Retry-After header when present. Writes are never auto-retried (no idempotency-key support yet on the backend — see Idempotency).
• Full SuqoError hierarchy (SuqoConfigError, AuthenticationError, KycRequiredError, ValidationError, NotFoundError, RateLimitError, ServerError, NetworkError) — every documented failure mode normalized to a class, never a wire-shape check.
• Dual ESM + CommonJS build with bundled .d.ts, zero runtime dependencies.

Fixed

• Corrected the sandbox base URL (test.be.suqo.ai, which did not resolve) to the real sandbox host, test-be.suqo.ai.