@strimz/sdk 0.1.0 → 0.1.1

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/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++

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

@@ -10,7 +10,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,12 +20,12 @@ 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)
   }

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))