@strimz/sdk 0.1.0 → 0.1.1

package/README.md

@@ -1,13 +1,41 @@
 # @strimz/sdk
 
-Server-side SDK for the Strimz API. Stripe-shaped: typed resources,
-automatic idempotency, retries, cursor pagination, and webhook
-signature verification.
-
-## Installation
+> The official Strimz Node SDK. Typed resources, automatic idempotency, retries, cursor pagination, EIP-712 typed-data builders, and webhook signature verification.
+
+[![npm version](https://img.shields.io/npm/v/@strimz/sdk.svg?color=02C76A)](https://www.npmjs.com/package/@strimz/sdk)
+[![npm downloads](https://img.shields.io/npm/dm/@strimz/sdk.svg)](https://www.npmjs.com/package/@strimz/sdk)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/@strimz/sdk.svg?label=size)](https://bundlephobia.com/package/@strimz/sdk)
+[![types](https://img.shields.io/npm/types/@strimz/sdk.svg)](https://www.npmjs.com/package/@strimz/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-02C76A.svg)](./LICENSE)
+
+The server-side client for the
+[Strimz API](https://strimz.finance/docs/api/overview). Typed
+resources for every endpoint, end-to-end TypeScript types derived
+from the
+[`@strimz/shared-types`](https://www.npmjs.com/package/@strimz/shared-types)
+Zod schemas, and a webhook verifier you can drop into any handler.
+Built for Node 22, Vercel Edge, and Cloudflare Workers from the same
+code path.
+
+## Table of contents
+
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Resources](#resources)
+- [Behaviour](#behaviour)
+- [Webhook verification](#webhook-verification)
+- [Browser client](#browser-client)
+- [Error handling](#error-handling)
+- [Runtime support](#runtime-support)
+- [Links](#links)
+- [License](#license)
+
+## Install
 
 ```sh
 pnpm add @strimz/sdk
+# npm install @strimz/sdk
+# yarn add @strimz/sdk
 ```
 
 ## Quick start
@@ -27,9 +55,18 @@ const session = await strimz.paymentSessions.create({
 console.log(session.checkoutUrl)
 ```
 
-## Modules
+Redirect the customer to `session.checkoutUrl`. They connect a wallet,
+sign one EIP-3009 authorisation, and the Strimz relayer broadcasts
+the on-chain transaction. Your webhook receives `payment.completed`
+the moment it confirms.
+
+## Resources
 
-| Resource            | Path                                                                                                             |
+Every API resource is exposed as a property on the client. Method
+signatures and response types come from
+[`@strimz/shared-types`](https://www.npmjs.com/package/@strimz/shared-types).
+
+| Resource            | Methods                                                                                                          |
 | ------------------- | ---------------------------------------------------------------------------------------------------------------- |
 | `merchants`         | `me`, `update`, `changeTier`                                                                                     |
 | `apiKeys`           | `list`, `retrieve`, `create`, `revoke`                                                                           |
@@ -47,11 +84,11 @@ console.log(session.checkoutUrl)
 
 ## Behaviour
 
-- **Mode is auto-detected** from the API key prefix (`sk_test_` ↔ `sk_live_`). The client refuses publishable keys; use `StrimzBrowserClient` from `@strimz/sdk/browser` for those.
-- **Idempotency** is automatic. Every mutating call generates an idempotency key (`strimz_<uuid>`) so a network retry doesn't double-charge a merchant. Override with `{ idempotencyKey }` in the second arg.
-- **Retries**: network failures and 5xx (idempotent calls only) and 429 are retried up to 3 times with exponential backoff and jitter. `Retry-After` is respected on 429.
-- **Pagination**: `list(...)` returns a single page; `listAuto(...)` (where exposed) returns an `AutoPagingIterator` that you can `for await` over.
-- **Errors are typed**. The SDK throws on failure rather than resolving to `{ ok: false }`. Catch `StrimzAuthenticationError`, `StrimzNotFoundError`, `StrimzValidationError`, `StrimzRateLimitError`, etc., or the base `StrimzError`.
+- **Mode auto-detection.** Live versus test mode is derived from the API key prefix (`sk_test_` or `sk_live_`). The server client refuses publishable keys; use the [browser client](#browser-client) for those.
+- **Automatic idempotency.** Every mutating call ships an idempotency key (`strimz_<uuid>`) so a network retry won't double-charge. Override with `{ idempotencyKey }` in the second argument if you want to dedupe across separate calls.
+- **Retries.** Network errors, `5xx` responses on idempotent calls, and `429`s are retried up to 3 times with exponential backoff and jitter. `Retry-After` is respected on 429.
+- **Pagination.** `list(...)` returns one page (`{ data, nextCursor, hasMore }`). `listAuto(...)` (where exposed) returns an async iterator you can `for await` over.
+- **Typed errors.** The SDK throws on failure rather than returning `{ ok: false }`. Catch the base `StrimzError` or narrow with `instanceof` (see [Error handling](#error-handling)).
 
 ## Webhook verification
 
@@ -80,7 +117,12 @@ export async function POST(req: Request) {
 }
 ```
 
-## Browser
+`verifyWebhookSignature` does a constant-time comparison and rejects
+any timestamp older than 5 minutes by default. `parseWebhookEvent`
+returns a discriminated union, so a `switch` over `event.type` is
+exhaustively checked by TypeScript.
+
+## Browser client
 
 ```ts
 import { StrimzBrowserClient } from '@strimz/sdk/browser'
@@ -92,20 +134,64 @@ const strimz = new StrimzBrowserClient({
 const session = await strimz.paymentSessions.retrieve(sessionId)
 ```
 
-The browser client exposes a strict subset of resource methods. It will refuse a secret key.
+The browser client exposes a strict subset of read-only resource
+methods. It refuses secret keys at construction time so a
+misconfigured environment fails loud.
+
+For a full hosted-checkout UX with components and hooks, use
+[`@strimz/sdk-react`](https://www.npmjs.com/package/@strimz/sdk-react).
+
+## Error handling
+
+Every error thrown by the SDK is a typed subclass of `StrimzError`:
+
+```ts
+import {
+  StrimzError,
+  StrimzAuthenticationError,
+  StrimzValidationError,
+  StrimzRateLimitError,
+  StrimzNotFoundError,
+} from '@strimz/sdk/errors'
+
+try {
+  await strimz.refunds.create({ ... })
+} catch (err) {
+  if (err instanceof StrimzValidationError) {
+    console.error('validation failed on', err.param, ':', err.message)
+  } else if (err instanceof StrimzRateLimitError) {
+    await sleep(err.retryAfterMs)
+    // … retry
+  } else if (err instanceof StrimzError) {
+    // unknown Strimz error
+  } else {
+    // not a Strimz error
+  }
+}
+```
+
+The full code list is documented at
+[strimz.finance/docs/errors](https://strimz.finance/docs/errors).
 
 ## Runtime support
 
 | Runtime            | Supported                                            |
 | ------------------ | ---------------------------------------------------- |
-| Node 22+           | ✓ (primary)                                          |
-| Vercel Edge        | ✓ (uses Web Crypto + fetch)                          |
-| Cloudflare Workers | ✓                                                    |
-| Deno / Bun         | should work; not regularly tested                    |
-| Browsers           | use `StrimzBrowserClient` from `@strimz/sdk/browser` |
+| Node 22+           | Yes (primary)                                        |
+| Vercel Edge        | Yes (uses Web Crypto + `fetch`)                      |
+| Cloudflare Workers | Yes                                                  |
+| Deno               | Should work, not regularly tested                    |
+| Bun                | Should work, not regularly tested                    |
+| Browsers           | Use `StrimzBrowserClient` from `@strimz/sdk/browser` |
+
+## Links
+
+- [Documentation](https://strimz.finance/docs)
+- [API reference](https://strimz.finance/docs/api/overview)
+- [Repository](https://github.com/StrimzLab/Strimz/tree/main/packages/sdk)
+- [Changelog](./CHANGELOG.md)
+- [Issues](https://github.com/StrimzLab/Strimz/issues)
 
-## Boundaries
+## License
 
-- **No business logic.** The SDK validates inputs against `@strimz/shared-types` and forwards to the API.
-- **No persistent state.** The client is safe to instantiate per-request or reuse across requests.
-- **No secrets logged.** Diagnostics never include the API key. Webhook signatures are verified with constant-time compare via `@strimz/shared-crypto`.
+[MIT](./LICENSE) © Strimz

package/dist/{browser-client-DlZg0Aae.d.cts → browser-client-D6VUs85b.d.cts}

@@ -36,7 +36,7 @@ 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;
 }
 interface RequestSpec {
@@ -121,7 +121,7 @@ type ScalarParam = string | number | boolean | null | undefined;
  * 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.
  *
@@ -131,16 +131,16 @@ type ScalarParam = string | number | boolean | null | undefined;
  * code with a secret key.
  */
 declare 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>;
-    /** 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>;
 }
 
 /**
- * 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
@@ -149,27 +149,26 @@ declare class CheckoutResource extends BaseResource {
 declare 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>;
     /**
      * 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>;
 }
 /**
- * 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.
@@ -179,16 +178,16 @@ declare function selectPaymentPath(meta: TokenMetadata): RelayPath;
 declare function selectSubscriptionPath(meta: TokenMetadata): RelayPath;
 
 /**
- * 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.
  */
 
 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;
@@ -201,21 +200,21 @@ interface StrimzBrowserClientOptions {
  * 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.
  */
 declare class StrimzBrowserClient {
     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.
      */
     readonly checkout: CheckoutResource;
-    /** Token metadata + EIP-2612 permit nonce lookup. */
+    /** Token metadata and EIP-2612 permit nonce lookup. */
     readonly tokens: TokensResource;
     constructor(options: StrimzBrowserClientOptions);
 }

package/dist/{browser-client-DlZg0Aae.d.ts → browser-client-D6VUs85b.d.ts}

@@ -36,7 +36,7 @@ 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;
 }
 interface RequestSpec {
@@ -121,7 +121,7 @@ type ScalarParam = string | number | boolean | null | undefined;
  * 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.
  *
@@ -131,16 +131,16 @@ type ScalarParam = string | number | boolean | null | undefined;
  * code with a secret key.
  */
 declare 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>;
-    /** 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>;
 }
 
 /**
- * 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
@@ -149,27 +149,26 @@ declare class CheckoutResource extends BaseResource {
 declare 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>;
     /**
      * 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>;
 }
 /**
- * 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.
@@ -179,16 +178,16 @@ declare function selectPaymentPath(meta: TokenMetadata): RelayPath;
 declare function selectSubscriptionPath(meta: TokenMetadata): RelayPath;
 
 /**
- * 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.
  */
 
 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;
@@ -201,21 +200,21 @@ interface StrimzBrowserClientOptions {
  * 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.
  */
 declare class StrimzBrowserClient {
     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.
      */
     readonly checkout: CheckoutResource;
-    /** Token metadata + EIP-2612 permit nonce lookup. */
+    /** Token metadata and EIP-2612 permit nonce lookup. */
     readonly tokens: TokensResource;
     constructor(options: StrimzBrowserClientOptions);
 }

package/dist/browser-client.cjs

@@ -351,11 +351,11 @@ function parsePage(raw, itemSchema) {
 
 // src/resources/checkout.ts
 var CheckoutResource = class extends BaseResource {
-  /** Load a payment session by id (public — no merchant scoping). */
+  /** Load a payment session by id (public, no merchant scoping). */
   session(id) {
     return this.get(`/v1/checkout/sessions/${encodeURIComponent(id)}`, sharedTypes.paymentSessionSchema);
   }
-  /** Load a subscription plan by id (public — no merchant scoping). */
+  /** Load a subscription plan by id (public, no merchant scoping). */
   plan(id) {
     return this.get(`/v1/checkout/plans/${encodeURIComponent(id)}`, sharedTypes.subscriptionPlanSchema);
   }
@@ -363,14 +363,14 @@ var CheckoutResource = class extends BaseResource {
 var TokensResource = class 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) {
     return this.get(`/v1/tokens/${encodeURIComponent(address.toLowerCase())}`, sharedTypes.tokenMetadataSchema);
   }
   /**
    * 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, owner) {
@@ -393,12 +393,12 @@ var DEFAULT_BASE_URL = "https://api.strimz.io";
 var StrimzBrowserClient = class {
   mode;
   /**
-   * 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.
    */
   checkout;
-  /** Token metadata + EIP-2612 permit nonce lookup. */
+  /** Token metadata and EIP-2612 permit nonce lookup. */
   tokens;
   constructor(options) {
     const key = options.publishableKey;