@strimz/sdk 0.1.0 → 0.2.0

package/dist/webhooks.d.ts

@@ -4,15 +4,15 @@ export { AgentActionExecutedEvent, AgentJobCompletedEvent, AgentJobDisputedEvent
 export { WEBHOOK_DELIVERY_ID_HEADER, WEBHOOK_MAX_ATTEMPTS, WEBHOOK_RETRY_SCHEDULE_SECONDS, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_SIGNATURE_TOLERANCE_SECONDS } from '@strimz/shared-config';
 
 /**
- * Webhook utilities — re-exports the verified-and-tested Web Crypto
- * primitives from `@strimz/shared-crypto` and the typed event union from
+ * Webhook utilities. Re-exports the verified Web Crypto primitives from
+ * `@strimz/shared-crypto` and the typed event union from
  * `@strimz/shared-types`. Consumers should import from here, not directly
  * from the shared packages.
  */
 
 /**
  * Parse a webhook payload into a typed `StrimzWebhookEvent`.
- * Use after `verifyWebhookSignature` succeeds — never trust raw payloads.
+ * Use after `verifyWebhookSignature` succeeds. Never trust raw payloads.
  */
 declare function parseWebhookEvent(rawJson: string): StrimzWebhookEvent;
 

package/dist/webhooks.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/webhooks.ts"],"names":["webhookEventSchema"],"mappings":";;;;;;AA6DO,SAAS,kBAAkB,OAAA,EAAqC;AACrE,EAAA,OAAOA,kBAAAA,CAAmB,KAAA,CAAM,IAAA,CAAK,KAAA,CAAM,OAAO,CAAC,CAAA;AACrD","file":"webhooks.js","sourcesContent":["/**\n * Webhook utilities — re-exports the verified-and-tested Web Crypto\n * primitives from `@strimz/shared-crypto` and the typed event union from\n * `@strimz/shared-types`. Consumers should import from here, not directly\n * from the shared packages.\n */\n\nexport {\n  signWebhookPayload,\n  verifyWebhookSignature,\n  WEBHOOK_SIGNATURE_VERSION,\n  type SignWebhookOptions,\n  type VerifyWebhookOptions,\n  type VerifyWebhookReason,\n  type VerifyWebhookResult,\n} from '@strimz/shared-crypto'\n\nexport {\n  webhookEventSchema,\n  webhookEventNameSchema,\n  type StrimzWebhookEvent,\n  type WebhookEventName,\n  // Per-event typed payloads.\n  type PaymentCreatedEvent,\n  type PaymentCompletedEvent,\n  type PaymentFailedEvent,\n  type SubscriptionCreatedEvent,\n  type SubscriptionChargedEvent,\n  type SubscriptionChargeFailedEvent,\n  type SubscriptionRecoveryAttemptEvent,\n  type SubscriptionRecoveryOutcomeEvent,\n  type SubscriptionCancelledEvent,\n  type SubscriptionLapsedEvent,\n  type RefundCreatedEvent,\n  type RefundCompletedEvent,\n  type RefundFailedEvent,\n  type InvoiceCreatedEvent,\n  type InvoicePaidEvent,\n  type InvoiceOverdueEvent,\n  type AgentActionExecutedEvent,\n  type AgentJobProposedEvent,\n  type AgentJobCompletedEvent,\n  type AgentJobDisputedEvent,\n  type ComplianceWalletFlaggedEvent,\n  type ComplianceWalletBlockedEvent,\n} from '@strimz/shared-types'\n\nexport {\n  WEBHOOK_RETRY_SCHEDULE_SECONDS,\n  WEBHOOK_MAX_ATTEMPTS,\n  WEBHOOK_SIGNATURE_TOLERANCE_SECONDS,\n  WEBHOOK_SIGNATURE_HEADER,\n  WEBHOOK_DELIVERY_ID_HEADER,\n} from '@strimz/shared-config'\n\nimport { webhookEventSchema, type StrimzWebhookEvent } from '@strimz/shared-types'\n\n/**\n * Parse a webhook payload into a typed `StrimzWebhookEvent`.\n * Use after `verifyWebhookSignature` succeeds — never trust raw payloads.\n */\nexport function parseWebhookEvent(rawJson: string): StrimzWebhookEvent {\n  return webhookEventSchema.parse(JSON.parse(rawJson))\n}\n"]}
+{"version":3,"sources":["../src/webhooks.ts"],"names":["webhookEventSchema"],"mappings":";;;;;;AA6DO,SAAS,kBAAkB,OAAA,EAAqC;AACrE,EAAA,OAAOA,kBAAAA,CAAmB,KAAA,CAAM,IAAA,CAAK,KAAA,CAAM,OAAO,CAAC,CAAA;AACrD","file":"webhooks.js","sourcesContent":["/**\n * Webhook utilities. Re-exports the verified Web Crypto primitives from\n * `@strimz/shared-crypto` and the typed event union from\n * `@strimz/shared-types`. Consumers should import from here, not directly\n * from the shared packages.\n */\n\nexport {\n  signWebhookPayload,\n  verifyWebhookSignature,\n  WEBHOOK_SIGNATURE_VERSION,\n  type SignWebhookOptions,\n  type VerifyWebhookOptions,\n  type VerifyWebhookReason,\n  type VerifyWebhookResult,\n} from '@strimz/shared-crypto'\n\nexport {\n  webhookEventSchema,\n  webhookEventNameSchema,\n  type StrimzWebhookEvent,\n  type WebhookEventName,\n  // Per-event typed payloads.\n  type PaymentCreatedEvent,\n  type PaymentCompletedEvent,\n  type PaymentFailedEvent,\n  type SubscriptionCreatedEvent,\n  type SubscriptionChargedEvent,\n  type SubscriptionChargeFailedEvent,\n  type SubscriptionRecoveryAttemptEvent,\n  type SubscriptionRecoveryOutcomeEvent,\n  type SubscriptionCancelledEvent,\n  type SubscriptionLapsedEvent,\n  type RefundCreatedEvent,\n  type RefundCompletedEvent,\n  type RefundFailedEvent,\n  type InvoiceCreatedEvent,\n  type InvoicePaidEvent,\n  type InvoiceOverdueEvent,\n  type AgentActionExecutedEvent,\n  type AgentJobProposedEvent,\n  type AgentJobCompletedEvent,\n  type AgentJobDisputedEvent,\n  type ComplianceWalletFlaggedEvent,\n  type ComplianceWalletBlockedEvent,\n} from '@strimz/shared-types'\n\nexport {\n  WEBHOOK_RETRY_SCHEDULE_SECONDS,\n  WEBHOOK_MAX_ATTEMPTS,\n  WEBHOOK_SIGNATURE_TOLERANCE_SECONDS,\n  WEBHOOK_SIGNATURE_HEADER,\n  WEBHOOK_DELIVERY_ID_HEADER,\n} from '@strimz/shared-config'\n\nimport { webhookEventSchema, type StrimzWebhookEvent } from '@strimz/shared-types'\n\n/**\n * Parse a webhook payload into a typed `StrimzWebhookEvent`.\n * Use after `verifyWebhookSignature` succeeds. Never trust raw payloads.\n */\nexport function parseWebhookEvent(rawJson: string): StrimzWebhookEvent {\n  return webhookEventSchema.parse(JSON.parse(rawJson))\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strimz/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The Strimz SDK. Typed client for server and edge runtimes. Handles HTTP, retries, idempotency, pagination, EIP-712 typed-data building, and webhook signature verification.",
   "license": "MIT",
   "author": "Strimz <hello@strimz.finance>",
@@ -69,9 +69,9 @@
   ],
   "dependencies": {
     "zod": "^3.24.1",
-    "@strimz/shared-config": "0.1.0",
-    "@strimz/shared-crypto": "0.1.0",
-    "@strimz/shared-types": "0.1.0"
+    "@strimz/shared-config": "0.1.1",
+    "@strimz/shared-crypto": "0.1.1",
+    "@strimz/shared-types": "0.2.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.5",

package/src/browser-client.ts

@@ -1,8 +1,8 @@
 /**
- * StrimzBrowserClient — the publishable-key, browser-safe SDK entry point.
+ * StrimzBrowserClient. The publishable-key, browser-safe SDK entry point.
  *
  * Used by `@strimz/sdk-react` and any other browser code that should
- * never see a secret key. Surfaces a strict subset of resource methods —
+ * never see a secret key. Surfaces a strict subset of resource methods,
  * only those safe to call from a browser with a `pk_test_...` or
  * `pk_live_...` key.
  */
@@ -20,7 +20,7 @@ import {
 } from './resources/tokens.js'
 
 export interface StrimzBrowserClientOptions {
-  /** Publishable key — `pk_test_...` or `pk_live_...`. */
+  /** Publishable key. Either `pk_test_...` or `pk_live_...`. */
   publishableKey: string
   /** Override the API base URL. */
   baseUrl?: string
@@ -36,21 +36,21 @@ const DEFAULT_BASE_URL = 'https://api.strimz.io'
  * Designed for hosted-checkout state polling and the React component
  * family. Read-only on most resources. Refuses a secret key.
  *
- * The `tokens` resource + `selectPaymentPath` / `selectSubscriptionPath`
- * selectors are the core of the capability-detection layer: given a
- * token, the SDK asks the backend which meta-tx flows the token
- * supports, and the selectors map that to a `RelayPath` the checkout
- * UI uses to decide which typed-data to build.
+ * The `tokens` resource and the `selectPaymentPath` /
+ * `selectSubscriptionPath` selectors form the capability-detection
+ * layer. Given a token, the SDK asks the API which meta-tx flows the
+ * token supports, and the selectors map that to a `RelayPath` the
+ * checkout UI uses to decide which typed-data to build.
  */
 export class StrimzBrowserClient {
   public readonly mode: ApiKeyMode
   /**
-   * Public hosted-checkout reads — payment sessions and subscription
+   * Public hosted-checkout reads. Payment sessions and subscription
    * plans by id. Backed by the `/v1/checkout/*` namespace on the API,
    * which is intentionally unauthenticated.
    */
   public readonly checkout: CheckoutResource
-  /** Token metadata + EIP-2612 permit nonce lookup. */
+  /** Token metadata and EIP-2612 permit nonce lookup. */
   public readonly tokens: TokensResource
 
   constructor(options: StrimzBrowserClientOptions) {
@@ -91,7 +91,7 @@ export class StrimzBrowserClient {
   }
 }
 
-// Re-export the selectors + path type so consumers don't need a
+// Re-export the selectors and path type so consumers don't need a
 // second import: `import { StrimzBrowserClient, selectPaymentPath }
 // from '@strimz/sdk/browser'`.
 export { selectPaymentPath, selectSubscriptionPath, type RelayPath }

package/src/client.ts

@@ -1,5 +1,5 @@
 /**
- * StrimzClient — the secret-key, server-side SDK entry point.
+ * StrimzClient. The secret-key, server-side SDK entry point.
  *
  *   const strimz = new StrimzClient({ apiKey: process.env.STRIMZ_SECRET_KEY })
  *   const session = await strimz.paymentSessions.create({ amount: '1000000', currency: 'USDC' })
@@ -24,7 +24,7 @@ import { StorefrontsResource } from './resources/storefronts.js'
 import { AgentsResource } from './resources/agents.js'
 
 export interface StrimzClientOptions {
-  /** Secret key — `sk_test_...` or `sk_live_...`. Mode is auto-detected. */
+  /** Secret key. Either `sk_test_...` or `sk_live_...`. Mode is auto-detected. */
   apiKey: string
   /** Override the API base URL. Defaults to `https://api.strimz.io`. */
   baseUrl?: string
@@ -35,14 +35,14 @@ export interface StrimzClientOptions {
   /** Optional logger callbacks for instrumentation. */
   onRequest?: ConstructorParameters<typeof Fetcher>[0]['onRequest']
   onResponse?: ConstructorParameters<typeof Fetcher>[0]['onResponse']
-  /** Override fetch — use to inject mocks in tests or polyfills in Edge. */
+  /** Override fetch. Use to inject mocks in tests or polyfills in Edge. */
   fetch?: typeof globalThis.fetch
 }
 
 const DEFAULT_BASE_URL = 'https://api.strimz.io'
 
 export class StrimzClient {
-  /** Resolved mode — `test` or `live`. Derived from the API key prefix. */
+  /** Resolved mode, either `test` or `live`. Derived from the API key prefix. */
   public readonly mode: ApiKeyMode
 
   public readonly merchants: MerchantsResource

package/src/eip712/index.ts

@@ -1,18 +1,10 @@
 /**
- * EIP-712 typed-data builders.
+ * EIP-712 typed-data builders. Pure functions; no wallet dependency.
  *
- * Pure functions — no wallet dependency. The returned shape matches
- * the EIP-712 standard and is accepted by every major wallet library:
- *
- *   import { buildReceiveWithAuthorizationTypedData } from '@strimz/sdk/eip712'
- *
- *   const typedData = buildReceiveWithAuthorizationTypedData({ ... })
- *   const signature = await walletClient.signTypedData(typedData)
- *
- * The builders are deliberately granular (one per primitive — EIP-3009,
- * EIP-2612) so the SDK can support future schemes (e.g. x402 batched
- * payments) by adding a sibling builder without touching existing
- * call sites.
+ * Meta-tx flows need TWO signatures — one for the token
+ * (`ReceiveWithAuthorization` or `Permit`) and one Strimz intent
+ * (`PayIntent` or `SubscriptionIntent`) that binds the money-routing
+ * fields the token never sees.
  */
 export type { Eip712Domain, Eip712Field, Eip712Types, Eip712TypedData } from './types.js'
 
@@ -23,3 +15,11 @@ export {
 } from './receive-with-authorization.js'
 
 export { buildPermitTypedData, PERMIT_TYPES, type PermitParams } from './permit.js'
+
+export { buildPayIntentTypedData, PAY_INTENT_TYPES, type PayIntentParams } from './pay-intent.js'
+
+export {
+  buildSubscriptionIntentTypedData,
+  SUBSCRIPTION_INTENT_TYPES,
+  type SubscriptionIntentParams,
+} from './subscription-intent.js'

package/src/eip712/pay-intent.ts

@@ -0,0 +1,54 @@
+import type { Eip712TypedData } from './types.js'
+
+/**
+ * Inputs for the Strimz PayIntent. Payer signs this alongside the
+ * EIP-3009 auth. Without it, a valid auth sig can be redirected to
+ * pay a different merchant.
+ *
+ * Every field must match the corresponding argument the API will
+ * submit on-chain — the contract compares them via ecrecover.
+ */
+export interface PayIntentParams {
+  chainId: number
+  verifyingContract: `0x${string}`
+  merchantId: bigint
+  token: `0x${string}`
+  amount: bigint
+  nonce: `0x${string}`
+  validBefore: bigint
+  ref: `0x${string}`
+}
+
+/** Field order matches `PAY_INTENT_TYPEHASH` in `StrimzPayments.sol`. */
+export const PAY_INTENT_TYPES = {
+  PayIntent: [
+    { name: 'merchantId', type: 'uint256' },
+    { name: 'token', type: 'address' },
+    { name: 'amount', type: 'uint256' },
+    { name: 'nonce', type: 'bytes32' },
+    { name: 'validBefore', type: 'uint256' },
+    { name: 'ref', type: 'bytes32' },
+  ],
+} as const
+
+/** Domain name + version mirror `EIP712("StrimzPayments", "1")`. */
+export function buildPayIntentTypedData(params: PayIntentParams): Eip712TypedData<'PayIntent'> {
+  return {
+    domain: {
+      name: 'StrimzPayments',
+      version: '1',
+      chainId: params.chainId,
+      verifyingContract: params.verifyingContract,
+    },
+    types: PAY_INTENT_TYPES,
+    primaryType: 'PayIntent',
+    message: {
+      merchantId: params.merchantId,
+      token: params.token,
+      amount: params.amount,
+      nonce: params.nonce,
+      validBefore: params.validBefore,
+      ref: params.ref,
+    },
+  }
+}

package/src/eip712/permit.ts

@@ -5,22 +5,22 @@ import type { Eip712TypedData } from './types.js'
  *
  *  - `chainId`, `token`, `tokenName`, `tokenVersion` form the EIP-712
  *    domain (same shape as the EIP-3009 builder).
- *  - `owner` is the token holder authorising the allowance — must match
+ *  - `owner` is the token holder authorising the allowance. Must match
  *    the signing wallet.
- *  - `spender` is the contract that will pull funds — for Strimz
+ *  - `spender` is the contract that will pull funds. For Strimz
  *    subscriptions this is the StrimzSubscriptions contract.
  *  - `value` is the allowance to grant in token base units.
  *    `type(uint256).max` produces an unlimited allowance and is the
  *    common case for subscription enrolment.
  *  - `nonce` is the owner's *current* `nonces(owner)` reading from the
- *    token contract. The SDK does not fetch this — the caller is
+ *    token contract. The SDK does not fetch this. The caller is
  *    expected to have just queried it. Race-free: the token rejects
- *    stale nonces, so a concurrent permit on the same owner just
- *    causes one to fail predictably.
+ *    stale nonces, so a concurrent permit on the same owner causes one
+ *    to fail predictably.
  *  - `deadline` is the unix-second timestamp after which the permit
- *    expires. Strimz default for subscription enrolment is 24h —
- *    enough headroom for a slow merchant submit pipeline without
- *    leaving an indefinite signature window.
+ *    expires. Strimz default for subscription enrolment is 24h. Enough
+ *    headroom for a slow merchant submit pipeline without leaving an
+ *    indefinite signature window.
  */
 export interface PermitParams {
   chainId: number

package/src/eip712/receive-with-authorization.ts

@@ -5,16 +5,16 @@ import type { Eip712TypedData } from './types.js'
  *
  *  - `chainId` is the EVM chain id (Arc Testnet = 5042002).
  *  - `token` is the ERC-20 contract whose `receiveWithAuthorization` is
- *    being invoked — usually USDC at `0x36...` on Arc.
+ *    being invoked. Usually USDC at `0x36...` on Arc.
  *  - `tokenName` and `tokenVersion` form the EIP-712 domain. Real USDC
  *    on most chains uses `name="USD Coin"` and `version="2"`; tests
  *    use whatever the mock token reports. Always read these from the
  *    token contract at runtime to avoid drift.
- *  - `from` is the payer; the wallet that produces the signature must
+ *  - `from` is the payer. The wallet that produces the signature must
  *    match this address.
- *  - `to` is the recipient of the funds — for Strimz this is the
+ *  - `to` is the recipient of the funds. For Strimz this is the
  *    StrimzPayments contract address (the contract pulls funds into
- *    itself, then forwards the fee + net split).
+ *    itself, then forwards the fee and net split).
  *  - `value` is the gross amount in token base units.
  *  - `validAfter` / `validBefore` are unix-second timestamps bounding
  *    the signature's validity. Strimz's default checkout window is
@@ -37,7 +37,7 @@ export interface ReceiveWithAuthorizationParams {
 }
 
 /**
- * EIP-712 type definition for `ReceiveWithAuthorization`. Stable —
+ * EIP-712 type definition for `ReceiveWithAuthorization`. Stable, and
  * shared by every EIP-3009 implementation (USDC, EURC, etc.).
  *
  * Exported so consumers can introspect or extend with sibling
@@ -61,7 +61,7 @@ export const RECEIVE_WITH_AUTHORIZATION_TYPES = {
  * compatible with viem, ethers, Privy, and Reown.
  *
  * Pass the result to `walletClient.signTypedData(typedData)` (viem)
- * or `signer._signTypedData(domain, types, message)` (ethers) — the
+ * or `signer._signTypedData(domain, types, message)` (ethers). The
  * SDK does not bind to a specific signer.
  */
 export function buildReceiveWithAuthorizationTypedData(

package/src/eip712/subscription-intent.ts

@@ -0,0 +1,59 @@
+import type { Eip712TypedData } from './types.js'
+
+/**
+ * Inputs for the Strimz SubscriptionIntent. Payer signs this
+ * alongside the ERC-2612 permit. Without it, a valid permit can be
+ * used to enrol the payer in a plan they never picked.
+ *
+ * `permitDeadline` ties this intent to the accompanying permit —
+ * they expire together.
+ */
+export interface SubscriptionIntentParams {
+  chainId: number
+  verifyingContract: `0x${string}`
+  merchantId: bigint
+  token: `0x${string}`
+  amount: bigint
+  interval: number
+  startAt: bigint
+  endAt: bigint
+  permitDeadline: bigint
+}
+
+/** Field order matches `SUBSCRIPTION_INTENT_TYPEHASH` in the contract. */
+export const SUBSCRIPTION_INTENT_TYPES = {
+  SubscriptionIntent: [
+    { name: 'merchantId', type: 'uint256' },
+    { name: 'token', type: 'address' },
+    { name: 'amount', type: 'uint256' },
+    { name: 'interval', type: 'uint32' },
+    { name: 'startAt', type: 'uint64' },
+    { name: 'endAt', type: 'uint64' },
+    { name: 'permitDeadline', type: 'uint256' },
+  ],
+} as const
+
+/** Domain mirrors `EIP712("StrimzSubscriptions", "1")`. */
+export function buildSubscriptionIntentTypedData(
+  params: SubscriptionIntentParams,
+): Eip712TypedData<'SubscriptionIntent'> {
+  return {
+    domain: {
+      name: 'StrimzSubscriptions',
+      version: '1',
+      chainId: params.chainId,
+      verifyingContract: params.verifyingContract,
+    },
+    types: SUBSCRIPTION_INTENT_TYPES,
+    primaryType: 'SubscriptionIntent',
+    message: {
+      merchantId: params.merchantId,
+      token: params.token,
+      amount: params.amount,
+      interval: params.interval,
+      startAt: params.startAt,
+      endAt: params.endAt,
+      permitDeadline: params.permitDeadline,
+    },
+  }
+}

package/src/eip712/types.ts

@@ -1,13 +1,14 @@
 /**
  * Canonical EIP-712 typed-data shape.
  *
- * Matches the structure every major wallet library accepts —
+ * Matches the structure every major wallet library accepts:
  *   viem's `signTypedData`
  *   ethers' `signer._signTypedData`
  *   Privy's `signTypedData`
  *   Reown AppKit's typed-data RPC
- * — so the SDK can produce typed-data without binding to a specific
- * wallet client. Consumers pipe the result into whichever signer they
+ *
+ * The SDK can produce typed-data without binding to a specific wallet
+ * client. Consumers pipe the result into whichever signer they
  * already use.
  *
  * No viem/ethers dependency on purpose: the SDK stays minimal, and
@@ -34,7 +35,7 @@ export type Eip712Types = Record<string, readonly Eip712Field[]>
  * gets hashed at the top level (the `types` object usually contains
  * additional referenced sub-structs).
  *
- * `bigint` is used for uint values; wallet libs handle the conversion
+ * `bigint` is used for uint values. Wallet libs handle the conversion
  * to hex/decimal at signing time. If a consumer needs to JSON-serialise
  * this object, convert bigints to strings at that boundary.
  */

package/src/errors.ts

@@ -1,9 +1,10 @@
 /**
  * Error hierarchy for the Strimz SDK.
  *
- * Every error thrown by the SDK extends `StrimzError`. The SDK never
- * resolves to `{ ok: false }` — it throws. This matches the Stripe / GitHub
- * SDK convention and keeps call sites linear.
+ * Every error thrown by the SDK extends `StrimzError`. The SDK throws
+ * on failure rather than resolving to `{ ok: false }` so call sites
+ * stay linear and consumers can narrow with `instanceof` on the
+ * exported subclasses.
  */
 
 export type StrimzErrorCode =

package/src/http/fetcher.ts

@@ -38,7 +38,7 @@ export interface FetcherOptions {
     ms: number
     attempt: number
   }) => void
-  /** Override the global fetch (for tests / Edge polyfills). */
+  /** Override the global fetch (for tests or Edge polyfills). */
   fetch?: typeof globalThis.fetch
 }
 
@@ -110,13 +110,13 @@ export class Fetcher {
         const errorBody = await parseErrorBody(res)
         const retryAfterMs = parseRetryAfter(res)
 
-        // 429 — back off and retry up to maxRetries.
+        // 429. Back off and retry up to maxRetries.
         if (res.status === 429 && attempt < this.maxRetries) {
           await delay(retryAfterMs ?? this.backoffFor(attempt))
           attempt++
           continue
         }
-        // 5xx — retry only if idempotent.
+        // 5xx. Retry only if idempotent.
         if (res.status >= 500 && idempotent && attempt < this.maxRetries) {
           await delay(this.backoffFor(attempt))
           attempt++
@@ -171,11 +171,22 @@ export class Fetcher {
 
   private backoffFor(attempt: number): number {
     const expo = this.initialBackoffMs * Math.pow(2, attempt)
-    const jitter = Math.random() * this.initialBackoffMs
-    return Math.min(expo + jitter, 8_000)
+    return Math.min(expo + cryptoJitter(this.initialBackoffMs), 8_000)
   }
 }
 
+// Uses crypto so retry timing does not seed off Math.random in
+// environments where that's been monkey-patched.
+function cryptoJitter(maxMs: number): number {
+  const g = globalThis as { crypto?: { getRandomValues?: (a: Uint32Array) => Uint32Array } }
+  if (g.crypto?.getRandomValues) {
+    const buf = new Uint32Array(1)
+    g.crypto.getRandomValues(buf)
+    return ((buf[0] ?? 0) / 0xffff_ffff) * maxMs
+  }
+  return Math.random() * maxMs
+}
+
 function isIdempotent(spec: RequestSpec): boolean {
   if (spec.method === 'GET' || spec.method === 'DELETE') return true
   return spec.idempotencyKey != null
@@ -183,12 +194,13 @@ function isIdempotent(spec: RequestSpec): boolean {
 
 async function parseErrorBody(res: Response): Promise<StrimzErrorBody> {
   try {
-    const json = (await res.json()) as { error?: StrimzErrorBody } | StrimzErrorBody
-    if (typeof json === 'object' && json !== null && 'error' in json && json.error) {
-      return json.error
-    }
-    if (typeof json === 'object' && json !== null && 'code' in json && 'message' in json) {
-      return json as StrimzErrorBody
+    const json = (await res.json()) as unknown
+    const raw =
+      typeof json === 'object' && json !== null && 'error' in json
+        ? (json as { error: unknown }).error
+        : json
+    if (typeof raw === 'object' && raw !== null && 'code' in raw && 'message' in raw) {
+      return sanitiseErrorBody(raw as Record<string, unknown>)
     }
   } catch {
     // fall through
@@ -196,6 +208,29 @@ async function parseErrorBody(res: Response): Promise<StrimzErrorBody> {
   return { code: 'api_error', message: `HTTP ${res.status}` }
 }
 
+// Whitelist server-provided fields. A bugged endpoint that dumps stack
+// traces or internal metadata into the error payload never reaches SDK
+// consumers.
+const ALLOWED_DETAIL_KEYS = new Set(['issues', 'field', 'reason', 'chargeAttemptId'])
+
+function sanitiseErrorBody(raw: Record<string, unknown>): StrimzErrorBody {
+  const details =
+    typeof raw.details === 'object' && raw.details !== null
+      ? Object.fromEntries(
+          Object.entries(raw.details as Record<string, unknown>).filter(([k]) =>
+            ALLOWED_DETAIL_KEYS.has(k),
+          ),
+        )
+      : undefined
+  return {
+    code: typeof raw.code === 'string' ? (raw.code as StrimzErrorBody['code']) : 'api_error',
+    message: typeof raw.message === 'string' ? raw.message : 'Request failed',
+    param: typeof raw.param === 'string' ? raw.param : undefined,
+    requestId: typeof raw.requestId === 'string' ? raw.requestId : undefined,
+    details: details && Object.keys(details).length > 0 ? details : undefined,
+  }
+}
+
 function parseRetryAfter(res: Response): number | undefined {
   const v = res.headers.get('Retry-After')
   if (!v) return undefined

package/src/http/headers.ts

@@ -1,10 +1,10 @@
 /**
  * Strimz HTTP header conventions.
  *
- * `Authorization: Bearer <secret_key>` — primary auth.
- * `X-Strimz-Idempotency-Key` — mutating calls.
- * `X-Strimz-Sdk` — telemetry.
- * `X-Strimz-Sdk-Version` — telemetry.
+ * `Authorization: Bearer <secret_key>`: primary auth.
+ * `X-Strimz-Idempotency-Key`: mutating calls.
+ * `X-Strimz-Sdk`: telemetry.
+ * `X-Strimz-Sdk-Version`: telemetry.
  */
 
 export const HEADERS = {

package/src/idempotency.ts

@@ -1,9 +1,8 @@
 import { uuid } from '@strimz/shared-crypto'
 
 /**
- * Generate an idempotency key for a mutating SDK call.
- * Stripe convention: a UUID-like value with a stable prefix the merchant
- * can grep for in logs.
+ * Generate an idempotency key for a mutating SDK call. The key is a
+ * UUID with a stable `strimz_` prefix so it stays greppable in logs.
  */
 export function generateIdempotencyKey(): string {
   return `strimz_${uuid()}`

package/src/resources/checkout.ts

@@ -1,6 +1,8 @@
 import {
+  merchantPublicBrandSchema,
   paymentSessionSchema,
   subscriptionPlanSchema,
+  type MerchantPublicBrand,
   type PaymentSession,
   type SubscriptionPlan,
 } from '@strimz/shared-types'
@@ -10,7 +12,7 @@ import { BaseResource } from './base-resource.js'
  * Public hosted-checkout reads.
  *
  * Backed by the `/v1/checkout/*` namespace on the Strimz API, which
- * is intentionally unauthenticated — session and plan records are
+ * is intentionally unauthenticated. Session and plan records are
  * what a merchant offers to payers, so a payer landing on a checkout
  * URL must be able to load the terms without holding any API key.
  *
@@ -20,13 +22,18 @@ import { BaseResource } from './base-resource.js'
  * code with a secret key.
  */
 export class CheckoutResource extends BaseResource {
-  /** Load a payment session by id (public — no merchant scoping). */
+  /** Load a payment session by id (public, no merchant scoping). */
   session(id: string): Promise<PaymentSession> {
     return this.get(`/v1/checkout/sessions/${encodeURIComponent(id)}`, paymentSessionSchema)
   }
 
-  /** Load a subscription plan by id (public — no merchant scoping). */
+  /** Load a subscription plan by id (public, no merchant scoping). */
   plan(id: string): Promise<SubscriptionPlan> {
     return this.get(`/v1/checkout/plans/${encodeURIComponent(id)}`, subscriptionPlanSchema)
   }
+
+  /** Load the merchant's public brand card by id. */
+  merchant(id: string): Promise<MerchantPublicBrand> {
+    return this.get(`/v1/checkout/merchants/${encodeURIComponent(id)}`, merchantPublicBrandSchema)
+  }
 }

package/src/resources/tokens.ts

@@ -7,9 +7,9 @@ import {
 import { BaseResource } from './base-resource.js'
 
 /**
- * Token metadata + capability lookup.
+ * Token metadata and capability lookup.
  *
- * The two endpoints are public on the API (no key required) — token
+ * The two endpoints are public on the API (no key required). Token
  * metadata is purely chain-derived, has no PII, and is what the
  * browser SDK consults to pick which meta-tx path to take for a
  * given token. Bundled here so consumers don't have to write the HTTP
@@ -18,7 +18,7 @@ import { BaseResource } from './base-resource.js'
 export class TokensResource extends BaseResource {
   /**
    * Fetch full metadata for a token. Throws via the underlying fetcher
-   * (404 → `StrimzNotFoundError`) if the token isn't whitelisted.
+   * (404 maps to `StrimzNotFoundError`) if the token isn't whitelisted.
    */
   retrieve(address: string): Promise<TokenMetadata> {
     return this.get(`/v1/tokens/${encodeURIComponent(address.toLowerCase())}`, tokenMetadataSchema)
@@ -26,7 +26,7 @@ export class TokensResource extends BaseResource {
 
   /**
    * Read an owner's current EIP-2612 permit nonce. Call this
-   * immediately before signing a Permit — the token contract rejects
+   * immediately before signing a Permit. The token contract rejects
    * stale nonces, and the value advances on every successful permit.
    */
   permitNonce(address: string, owner: string): Promise<TokenPermitNonce> {
@@ -39,16 +39,15 @@ export class TokensResource extends BaseResource {
 }
 
 /**
- * Path selector — decides which meta-tx flow to take given a token's
+ * Path selector. Decides which meta-tx flow to take given a token's
  * capabilities and the action a merchant wants to perform.
  *
  * The choice is unambiguous in 99% of cases:
- *  - One-shot pay        → EIP-3009 (preferred). Falls back to
- *                          approve+pay if the token has neither.
- *  - Subscription enrol  → EIP-2612 (the only meta-tx path that
- *                          grants the recurring allowance subscribers
- *                          need). If unavailable, the merchant must
- *                          use the classic approve+create flow.
+ *  - One-shot pay. Prefers EIP-3009. Falls back to approve+pay if the
+ *    token has neither.
+ *  - Subscription enrol. Prefers EIP-2612 (the only meta-tx path that
+ *    grants the recurring allowance subscribers need). If unavailable,
+ *    the merchant must use the classic approve+create flow.
  *
  * Returned `path` values are strings (not enums) so future schemes
  * can extend the union without breaking existing call sites.

package/src/webhooks.ts

@@ -1,6 +1,6 @@
 /**
- * Webhook utilities — re-exports the verified-and-tested Web Crypto
- * primitives from `@strimz/shared-crypto` and the typed event union from
+ * Webhook utilities. Re-exports the verified Web Crypto primitives from
+ * `@strimz/shared-crypto` and the typed event union from
  * `@strimz/shared-types`. Consumers should import from here, not directly
  * from the shared packages.
  */
@@ -57,7 +57,7 @@ import { webhookEventSchema, type StrimzWebhookEvent } from '@strimz/shared-type
 
 /**
  * Parse a webhook payload into a typed `StrimzWebhookEvent`.
- * Use after `verifyWebhookSignature` succeeds — never trust raw payloads.
+ * Use after `verifyWebhookSignature` succeeds. Never trust raw payloads.
  */
 export function parseWebhookEvent(rawJson: string): StrimzWebhookEvent {
   return webhookEventSchema.parse(JSON.parse(rawJson))