@strimz/sdk 0.1.0

package/src/eip712/index.ts

@@ -0,0 +1,25 @@
+/**
+ * EIP-712 typed-data builders.
+ *
+ * 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.
+ */
+export type { Eip712Domain, Eip712Field, Eip712Types, Eip712TypedData } from './types.js'
+
+export {
+  buildReceiveWithAuthorizationTypedData,
+  RECEIVE_WITH_AUTHORIZATION_TYPES,
+  type ReceiveWithAuthorizationParams,
+} from './receive-with-authorization.js'
+
+export { buildPermitTypedData, PERMIT_TYPES, type PermitParams } from './permit.js'

package/src/eip712/permit.ts

@@ -0,0 +1,74 @@
+import type { Eip712TypedData } from './types.js'
+
+/**
+ * Inputs for the EIP-2612 Permit typed-data.
+ *
+ *  - `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
+ *    the signing wallet.
+ *  - `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
+ *    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.
+ *  - `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.
+ */
+export interface PermitParams {
+  chainId: number
+  token: `0x${string}`
+  tokenName: string
+  tokenVersion: string
+  owner: `0x${string}`
+  spender: `0x${string}`
+  value: bigint
+  nonce: bigint
+  deadline: bigint
+}
+
+/**
+ * EIP-712 type definition for `Permit`. Stable across every EIP-2612
+ * implementation (USDC, EURC, DAI v2, etc.).
+ */
+export const PERMIT_TYPES = {
+  Permit: [
+    { name: 'owner', type: 'address' },
+    { name: 'spender', type: 'address' },
+    { name: 'value', type: 'uint256' },
+    { name: 'nonce', type: 'uint256' },
+    { name: 'deadline', type: 'uint256' },
+  ],
+} as const
+
+/**
+ * Build the typed-data structure for an EIP-2612 `Permit` signature.
+ * Returns the canonical shape compatible with viem, ethers, Privy,
+ * and Reown.
+ */
+export function buildPermitTypedData(params: PermitParams): Eip712TypedData<'Permit'> {
+  return {
+    domain: {
+      name: params.tokenName,
+      version: params.tokenVersion,
+      chainId: params.chainId,
+      verifyingContract: params.token,
+    },
+    types: PERMIT_TYPES,
+    primaryType: 'Permit',
+    message: {
+      owner: params.owner,
+      spender: params.spender,
+      value: params.value,
+      nonce: params.nonce,
+      deadline: params.deadline,
+    },
+  }
+}

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

@@ -0,0 +1,88 @@
+import type { Eip712TypedData } from './types.js'
+
+/**
+ * Inputs for the EIP-3009 ReceiveWithAuthorization typed-data.
+ *
+ *  - `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.
+ *  - `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
+ *    match this address.
+ *  - `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).
+ *  - `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
+ *    5 minutes; integrators may widen this for usage-based billing.
+ *  - `nonce` is a single-use 32-byte value. Generate with crypto.randomBytes
+ *    (server) or crypto.getRandomValues (browser). The token contract
+ *    tracks `(authorizer, nonce) -> used` and rejects replays.
+ */
+export interface ReceiveWithAuthorizationParams {
+  chainId: number
+  token: `0x${string}`
+  tokenName: string
+  tokenVersion: string
+  from: `0x${string}`
+  to: `0x${string}`
+  value: bigint
+  validAfter: bigint
+  validBefore: bigint
+  nonce: `0x${string}`
+}
+
+/**
+ * EIP-712 type definition for `ReceiveWithAuthorization`. Stable —
+ * shared by every EIP-3009 implementation (USDC, EURC, etc.).
+ *
+ * Exported so consumers can introspect or extend with sibling
+ * primitive types (e.g. for x402 batched signing schemes that wrap
+ * multiple authorizations in one signature).
+ */
+export const RECEIVE_WITH_AUTHORIZATION_TYPES = {
+  ReceiveWithAuthorization: [
+    { name: 'from', type: 'address' },
+    { name: 'to', type: 'address' },
+    { name: 'value', type: 'uint256' },
+    { name: 'validAfter', type: 'uint256' },
+    { name: 'validBefore', type: 'uint256' },
+    { name: 'nonce', type: 'bytes32' },
+  ],
+} as const
+
+/**
+ * Build the typed-data structure for an EIP-3009
+ * `ReceiveWithAuthorization` signature. Returns the canonical shape
+ * compatible with viem, ethers, Privy, and Reown.
+ *
+ * Pass the result to `walletClient.signTypedData(typedData)` (viem)
+ * or `signer._signTypedData(domain, types, message)` (ethers) — the
+ * SDK does not bind to a specific signer.
+ */
+export function buildReceiveWithAuthorizationTypedData(
+  params: ReceiveWithAuthorizationParams,
+): Eip712TypedData<'ReceiveWithAuthorization'> {
+  return {
+    domain: {
+      name: params.tokenName,
+      version: params.tokenVersion,
+      chainId: params.chainId,
+      verifyingContract: params.token,
+    },
+    types: RECEIVE_WITH_AUTHORIZATION_TYPES,
+    primaryType: 'ReceiveWithAuthorization',
+    message: {
+      from: params.from,
+      to: params.to,
+      value: params.value,
+      validAfter: params.validAfter,
+      validBefore: params.validBefore,
+      nonce: params.nonce,
+    },
+  }
+}

package/src/eip712/types.ts

@@ -0,0 +1,46 @@
+/**
+ * Canonical EIP-712 typed-data shape.
+ *
+ * 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
+ * already use.
+ *
+ * No viem/ethers dependency on purpose: the SDK stays minimal, and
+ * apps can choose their own signing stack.
+ */
+
+export interface Eip712Domain {
+  name?: string
+  version?: string
+  chainId?: number
+  verifyingContract?: `0x${string}`
+  salt?: `0x${string}`
+}
+
+export interface Eip712Field {
+  name: string
+  type: string
+}
+
+export type Eip712Types = Record<string, readonly Eip712Field[]>
+
+/**
+ * EIP-712 typed-data definition. `primaryType` names the struct that
+ * 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
+ * to hex/decimal at signing time. If a consumer needs to JSON-serialise
+ * this object, convert bigints to strings at that boundary.
+ */
+export interface Eip712TypedData<TPrimary extends string = string> {
+  domain: Eip712Domain
+  types: Eip712Types
+  primaryType: TPrimary
+  message: Record<string, unknown>
+}

package/src/errors.ts

@@ -0,0 +1,138 @@
+/**
+ * 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.
+ */
+
+export type StrimzErrorCode =
+  | 'authentication_error'
+  | 'permission_denied'
+  | 'invalid_request'
+  | 'not_found'
+  | 'idempotency_error'
+  | 'rate_limited'
+  | 'mode_mismatch'
+  | 'merchant_not_found'
+  | 'merchant_inactive'
+  | 'token_not_whitelisted'
+  | 'compliance_blocked'
+  | 'session_expired'
+  | 'session_invalid_state'
+  | 'webhook_signature_invalid'
+  | 'api_error'
+  | 'network_error'
+  | 'timeout'
+  | 'parse_error'
+  | 'unknown'
+
+export interface StrimzErrorBody {
+  code: StrimzErrorCode
+  message: string
+  param?: string
+  requestId?: string
+  details?: Record<string, unknown>
+}
+
+export class StrimzError extends Error {
+  public readonly code: StrimzErrorCode
+  public readonly httpStatus: number | undefined
+  public readonly requestId: string | undefined
+  public readonly param: string | undefined
+  public readonly details: Record<string, unknown> | undefined
+
+  constructor(body: StrimzErrorBody, httpStatus?: number) {
+    super(body.message)
+    this.name = 'StrimzError'
+    this.code = body.code
+    this.httpStatus = httpStatus
+    this.requestId = body.requestId
+    this.param = body.param
+    this.details = body.details
+  }
+}
+
+export class StrimzAuthenticationError extends StrimzError {
+  constructor(body: StrimzErrorBody, httpStatus?: number) {
+    super(body, httpStatus)
+    this.name = 'StrimzAuthenticationError'
+  }
+}
+
+export class StrimzPermissionError extends StrimzError {
+  constructor(body: StrimzErrorBody, httpStatus?: number) {
+    super(body, httpStatus)
+    this.name = 'StrimzPermissionError'
+  }
+}
+
+export class StrimzValidationError extends StrimzError {
+  constructor(body: StrimzErrorBody, httpStatus?: number) {
+    super(body, httpStatus)
+    this.name = 'StrimzValidationError'
+  }
+}
+
+export class StrimzNotFoundError extends StrimzError {
+  constructor(body: StrimzErrorBody, httpStatus?: number) {
+    super(body, httpStatus)
+    this.name = 'StrimzNotFoundError'
+  }
+}
+
+export class StrimzIdempotencyError extends StrimzError {
+  constructor(body: StrimzErrorBody, httpStatus?: number) {
+    super(body, httpStatus)
+    this.name = 'StrimzIdempotencyError'
+  }
+}
+
+export class StrimzRateLimitError extends StrimzError {
+  public readonly retryAfterMs: number | undefined
+  constructor(body: StrimzErrorBody, httpStatus?: number, retryAfterMs?: number) {
+    super(body, httpStatus)
+    this.name = 'StrimzRateLimitError'
+    this.retryAfterMs = retryAfterMs
+  }
+}
+
+export class StrimzNetworkError extends StrimzError {
+  public override readonly cause: unknown
+  constructor(message: string, cause: unknown) {
+    super({ code: 'network_error', message })
+    this.name = 'StrimzNetworkError'
+    this.cause = cause
+  }
+}
+
+export class StrimzTimeoutError extends StrimzError {
+  constructor(message: string) {
+    super({ code: 'timeout', message })
+    this.name = 'StrimzTimeoutError'
+  }
+}
+
+export class StrimzModeMismatchError extends StrimzError {
+  constructor(message: string) {
+    super({ code: 'mode_mismatch', message })
+    this.name = 'StrimzModeMismatchError'
+  }
+}
+
+/** Map an HTTP status + body to the right StrimzError subclass. */
+export function classifyError(
+  httpStatus: number,
+  body: StrimzErrorBody,
+  retryAfterMs?: number,
+): StrimzError {
+  if (httpStatus === 401) return new StrimzAuthenticationError(body, httpStatus)
+  if (httpStatus === 403) return new StrimzPermissionError(body, httpStatus)
+  if (httpStatus === 404) return new StrimzNotFoundError(body, httpStatus)
+  if (httpStatus === 409 && body.code === 'idempotency_error') {
+    return new StrimzIdempotencyError(body, httpStatus)
+  }
+  if (httpStatus === 422) return new StrimzValidationError(body, httpStatus)
+  if (httpStatus === 429) return new StrimzRateLimitError(body, httpStatus, retryAfterMs)
+  return new StrimzError(body, httpStatus)
+}

package/src/http/fetcher.ts

@@ -0,0 +1,226 @@
+/**
+ * Fetch wrapper with retry, idempotency, and Strimz error parsing.
+ *
+ * Retries on:
+ *   - Network failures (TypeError on fetch).
+ *   - 5xx responses for idempotent methods (GET, POST with idempotency key).
+ *   - 429 with Retry-After.
+ *
+ * Does NOT retry on:
+ *   - 4xx other than 429 (caller's bug).
+ *   - 5xx for non-idempotent calls without an idempotency key.
+ */
+
+import {
+  classifyError,
+  StrimzError,
+  StrimzNetworkError,
+  StrimzTimeoutError,
+  type StrimzErrorBody,
+} from '../errors.js'
+import { HEADERS } from './headers.js'
+
+export interface FetcherOptions {
+  baseUrl: string
+  baseHeaders: Record<string, string>
+  /** Default timeout per attempt, milliseconds. */
+  timeoutMs?: number
+  /** How many retries before giving up. */
+  maxRetries?: number
+  /** Initial backoff in ms; doubled with jitter on each retry. */
+  initialBackoffMs?: number
+  /** Optional logger. */
+  onRequest?: (info: { method: string; url: string; attempt: number }) => void
+  onResponse?: (info: {
+    method: string
+    url: string
+    status: number
+    ms: number
+    attempt: number
+  }) => void
+  /** Override the global fetch (for tests / Edge polyfills). */
+  fetch?: typeof globalThis.fetch
+}
+
+export interface RequestSpec {
+  method: 'GET' | 'POST' | 'PATCH' | 'DELETE'
+  path: string
+  query?: Record<string, string | number | boolean | null | undefined>
+  body?: unknown
+  idempotencyKey?: string
+  /** Per-call timeout override. */
+  timeoutMs?: number
+}
+
+const DEFAULT_TIMEOUT_MS = 30_000
+const DEFAULT_MAX_RETRIES = 3
+const DEFAULT_INITIAL_BACKOFF_MS = 250
+
+export class Fetcher {
+  private readonly baseUrl: string
+  private readonly baseHeaders: Record<string, string>
+  private readonly timeoutMs: number
+  private readonly maxRetries: number
+  private readonly initialBackoffMs: number
+  private readonly onRequest: FetcherOptions['onRequest']
+  private readonly onResponse: FetcherOptions['onResponse']
+  private readonly fetchImpl: typeof globalThis.fetch
+
+  constructor(opts: FetcherOptions) {
+    this.baseUrl = opts.baseUrl.replace(/\/$/, '')
+    this.baseHeaders = opts.baseHeaders
+    this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS
+    this.maxRetries = opts.maxRetries ?? DEFAULT_MAX_RETRIES
+    this.initialBackoffMs = opts.initialBackoffMs ?? DEFAULT_INITIAL_BACKOFF_MS
+    this.onRequest = opts.onRequest
+    this.onResponse = opts.onResponse
+    this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis)
+  }
+
+  async request<T>(spec: RequestSpec): Promise<T> {
+    const url = this.buildUrl(spec.path, spec.query)
+    const idempotent = isIdempotent(spec)
+    const headers: Record<string, string> = { ...this.baseHeaders }
+    if (spec.body != null) headers['Content-Type'] = 'application/json'
+    if (spec.idempotencyKey) headers[HEADERS.idempotencyKey] = spec.idempotencyKey
+
+    let attempt = 0
+    let lastErr: unknown
+    while (attempt <= this.maxRetries) {
+      try {
+        this.onRequest?.({ method: spec.method, url, attempt })
+        const start = Date.now()
+        const res = await this.fetchWithTimeout(
+          url,
+          {
+            method: spec.method,
+            headers,
+            body: spec.body == null ? undefined : JSON.stringify(spec.body),
+          },
+          spec.timeoutMs ?? this.timeoutMs,
+        )
+        const ms = Date.now() - start
+        this.onResponse?.({ method: spec.method, url, status: res.status, ms, attempt })
+
+        if (res.ok) {
+          if (res.status === 204) return undefined as T
+          return (await res.json()) as T
+        }
+
+        const errorBody = await parseErrorBody(res)
+        const retryAfterMs = parseRetryAfter(res)
+
+        // 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.
+        if (res.status >= 500 && idempotent && attempt < this.maxRetries) {
+          await delay(this.backoffFor(attempt))
+          attempt++
+          continue
+        }
+
+        throw classifyError(res.status, errorBody, retryAfterMs)
+      } catch (err) {
+        if (err instanceof StrimzError) throw err
+        lastErr = err
+        if (!isNetworkLike(err) || attempt >= this.maxRetries) {
+          if (err instanceof StrimzTimeoutError) throw err
+          throw new StrimzNetworkError(`Network error: ${describe(err)}`, err)
+        }
+        await delay(this.backoffFor(attempt))
+        attempt++
+      }
+    }
+    throw new StrimzNetworkError(`Network error after ${this.maxRetries} retries`, lastErr)
+  }
+
+  private async fetchWithTimeout(
+    url: string,
+    init: RequestInit,
+    timeoutMs: number,
+  ): Promise<Response> {
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), timeoutMs)
+    try {
+      return await this.fetchImpl(url, { ...init, signal: controller.signal })
+    } catch (err) {
+      if (isAbortError(err)) {
+        throw new StrimzTimeoutError(`Request timed out after ${timeoutMs}ms`)
+      }
+      throw err
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+
+  private buildUrl(path: string, query?: RequestSpec['query']): string {
+    const base = `${this.baseUrl}${path.startsWith('/') ? path : `/${path}`}`
+    if (!query) return base
+    const usp = new URLSearchParams()
+    for (const [k, v] of Object.entries(query)) {
+      if (v == null) continue
+      usp.append(k, String(v))
+    }
+    const qs = usp.toString()
+    return qs ? `${base}?${qs}` : base
+  }
+
+  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)
+  }
+}
+
+function isIdempotent(spec: RequestSpec): boolean {
+  if (spec.method === 'GET' || spec.method === 'DELETE') return true
+  return spec.idempotencyKey != null
+}
+
+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
+    }
+  } catch {
+    // fall through
+  }
+  return { code: 'api_error', message: `HTTP ${res.status}` }
+}
+
+function parseRetryAfter(res: Response): number | undefined {
+  const v = res.headers.get('Retry-After')
+  if (!v) return undefined
+  const n = Number(v)
+  if (Number.isFinite(n)) return Math.max(0, n) * 1_000
+  const date = Date.parse(v)
+  if (Number.isFinite(date)) return Math.max(0, date - Date.now())
+  return undefined
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+function isAbortError(err: unknown): boolean {
+  return err instanceof Error && err.name === 'AbortError'
+}
+
+function isNetworkLike(err: unknown): boolean {
+  if (err instanceof TypeError) return true // fetch network failures
+  if (err instanceof Error && /fetch|network|econn/i.test(err.message)) return true
+  return false
+}
+
+function describe(err: unknown): string {
+  if (err instanceof Error) return err.message
+  return String(err)
+}

package/src/http/headers.ts

@@ -0,0 +1,32 @@
+/**
+ * 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.
+ */
+
+export const HEADERS = {
+  authorization: 'Authorization',
+  idempotencyKey: 'X-Strimz-Idempotency-Key',
+  requestId: 'X-Strimz-Request-Id',
+  sdkName: 'X-Strimz-Sdk',
+  sdkVersion: 'X-Strimz-Sdk-Version',
+  sdkRuntime: 'X-Strimz-Sdk-Runtime',
+} as const
+
+export const SDK_NAME = '@strimz/sdk'
+
+/** The SDK version. Updated by the build pipeline if a version is published. */
+export const SDK_VERSION = '0.0.0'
+
+export function buildBaseHeaders(apiKey: string, runtime: string): Record<string, string> {
+  return {
+    [HEADERS.authorization]: `Bearer ${apiKey}`,
+    [HEADERS.sdkName]: SDK_NAME,
+    [HEADERS.sdkVersion]: SDK_VERSION,
+    [HEADERS.sdkRuntime]: runtime,
+    Accept: 'application/json',
+  }
+}

package/src/idempotency.ts

@@ -0,0 +1,20 @@
+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.
+ */
+export function generateIdempotencyKey(): string {
+  return `strimz_${uuid()}`
+}
+
+/** RFC 4122 UUID-shaped, optionally with the strimz_ prefix. */
+const IDEMPOTENCY_KEY_PATTERN =
+  /^(strimz_)?[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/
+
+export function isValidIdempotencyKey(key: string): boolean {
+  if (typeof key !== 'string') return false
+  if (key.length > 255) return false
+  return IDEMPOTENCY_KEY_PATTERN.test(key)
+}