@strimz/sdk 0.1.0

package/src/index.ts

@@ -0,0 +1,77 @@
+/**
+ * @strimz/sdk
+ *
+ * Server SDK for the Strimz API. Use `StrimzClient` with a secret key.
+ * For browser code, import `StrimzBrowserClient` from `@strimz/sdk/browser`.
+ * For webhook verification helpers, import from `@strimz/sdk/webhooks`.
+ */
+
+// Primary client.
+export { StrimzClient, type StrimzClientOptions } from './client.js'
+
+// Browser client (also available via `@strimz/sdk/browser`).
+export { StrimzBrowserClient, type StrimzBrowserClientOptions } from './browser-client.js'
+
+// Errors.
+export {
+  StrimzError,
+  StrimzAuthenticationError,
+  StrimzPermissionError,
+  StrimzValidationError,
+  StrimzNotFoundError,
+  StrimzIdempotencyError,
+  StrimzRateLimitError,
+  StrimzNetworkError,
+  StrimzTimeoutError,
+  StrimzModeMismatchError,
+  classifyError,
+  type StrimzErrorCode,
+  type StrimzErrorBody,
+} from './errors.js'
+
+// Pagination.
+export { AutoPagingIterator, type Page, type PaginationParams } from './pagination.js'
+
+// Idempotency.
+export { generateIdempotencyKey, isValidIdempotencyKey } from './idempotency.js'
+
+// Webhook helpers (also at `@strimz/sdk/webhooks`).
+export {
+  signWebhookPayload,
+  verifyWebhookSignature,
+  parseWebhookEvent,
+  type StrimzWebhookEvent,
+} from './webhooks.js'
+
+// Re-export every entity type so consumers don't need to depend on shared-types
+// directly. Apps can `import type { Merchant, PaymentSession } from '@strimz/sdk'`.
+export type {
+  Merchant,
+  ApiKey,
+  Customer,
+  PaymentSession,
+  Transaction,
+  SubscriptionPlan,
+  Subscription,
+  SubscriptionCharge,
+  Refund,
+  WebhookEndpoint,
+  WebhookDelivery,
+  Invoice,
+  Storefront,
+  StorefrontProduct,
+  AgentMerchantConfig,
+  AgentActivityLog,
+  AgentJob,
+  ComplianceLog,
+  WebhookEventName,
+  // Inputs.
+  CreatePaymentSessionInput,
+  CreateSubscriptionPlanInput,
+  CreateSubscriptionInput,
+  CreateRefundInput,
+  CreateInvoiceInput,
+  CreateAgentJobInput,
+  CreateApiKeyInput,
+  CreateWebhookEndpointInput,
+} from '@strimz/shared-types'

package/src/pagination.ts

@@ -0,0 +1,48 @@
+/**
+ * Cursor-based pagination, identical shape to the API's list responses.
+ */
+
+export interface Page<T> {
+  data: T[]
+  nextCursor: string | null
+  hasMore: boolean
+}
+
+export interface PaginationParams {
+  limit?: number
+  cursor?: string | null
+}
+
+/**
+ * Async-iterable wrapper that auto-paginates through every page of a list.
+ *
+ *   for await (const tx of strimz.transactions.listAll()) { ... }
+ */
+export class AutoPagingIterator<T> implements AsyncIterable<T> {
+  constructor(private readonly fetchPage: (cursor: string | null) => Promise<Page<T>>) {}
+
+  async *[Symbol.asyncIterator](): AsyncIterator<T> {
+    let cursor: string | null = null
+    let first = true
+    while (first || cursor !== null) {
+      first = false
+      const page: Page<T> = await this.fetchPage(cursor)
+      for (const item of page.data) {
+        yield item
+      }
+      cursor = page.hasMore ? page.nextCursor : null
+    }
+  }
+
+  async forEach(handler: (item: T) => void | Promise<void>): Promise<void> {
+    for await (const item of this) {
+      await handler(item)
+    }
+  }
+
+  async toArray(): Promise<T[]> {
+    const out: T[] = []
+    for await (const item of this) out.push(item)
+    return out
+  }
+}

package/src/resources/agents.ts

@@ -0,0 +1,64 @@
+import {
+  agentMerchantConfigSchema,
+  updateAgentConfigInputSchema,
+  agentActivityLogSchema,
+  agentJobSchema,
+  createAgentJobInputSchema,
+  type AgentMerchantConfig,
+  type UpdateAgentConfigInput,
+  type AgentActivityLog,
+  type AgentJob,
+  type CreateAgentJobInput,
+} from '@strimz/shared-types'
+import type { PaginationParams, Page } from '../pagination.js'
+import { BaseResource, type RequestOptions } from './base-resource.js'
+
+export class AgentsResource extends BaseResource {
+  /** Retrieve the merchant's AutoPay Agent config. */
+  retrieveConfig(): Promise<AgentMerchantConfig> {
+    return this.get('/v1/agents/config', agentMerchantConfigSchema)
+  }
+
+  updateConfig(
+    input: UpdateAgentConfigInput,
+    options?: RequestOptions,
+  ): Promise<AgentMerchantConfig> {
+    updateAgentConfigInputSchema.parse(input)
+    return this.patch('/v1/agents/config', input, agentMerchantConfigSchema, options)
+  }
+
+  listActivity(
+    params?: PaginationParams & {
+      capability?: string
+      outcome?: string
+      from?: string
+      to?: string
+    },
+  ): Promise<Page<AgentActivityLog>> {
+    return this.listPage('/v1/agents/activity', agentActivityLogSchema, params)
+  }
+
+  // ----- ERC-8183 jobs -----
+
+  listJobs(params?: PaginationParams & { status?: string }): Promise<Page<AgentJob>> {
+    return this.listPage('/v1/agents/jobs', agentJobSchema, params)
+  }
+
+  retrieveJob(id: string): Promise<AgentJob> {
+    return this.get(`/v1/agents/jobs/${encodeURIComponent(id)}`, agentJobSchema)
+  }
+
+  createJob(input: CreateAgentJobInput, options?: RequestOptions): Promise<AgentJob> {
+    createAgentJobInputSchema.parse(input)
+    return this.post('/v1/agents/jobs', input, agentJobSchema, options)
+  }
+
+  approveJob(id: string, options?: RequestOptions): Promise<AgentJob> {
+    return this.post(
+      `/v1/agents/jobs/${encodeURIComponent(id)}/approve`,
+      {},
+      agentJobSchema,
+      options,
+    )
+  }
+}

package/src/resources/api-keys.ts

@@ -0,0 +1,29 @@
+import {
+  apiKeySchema,
+  createApiKeyInputSchema,
+  createApiKeyOutputSchema,
+  type ApiKey,
+  type CreateApiKeyInput,
+  type CreateApiKeyOutput,
+} from '@strimz/shared-types'
+import type { PaginationParams, Page } from '../pagination.js'
+import { BaseResource, type RequestOptions } from './base-resource.js'
+
+export class ApiKeysResource extends BaseResource {
+  list(params?: PaginationParams): Promise<Page<ApiKey>> {
+    return this.listPage('/v1/api-keys', apiKeySchema, params)
+  }
+
+  retrieve(id: string): Promise<ApiKey> {
+    return this.get(`/v1/api-keys/${encodeURIComponent(id)}`, apiKeySchema)
+  }
+
+  create(input: CreateApiKeyInput, options?: RequestOptions): Promise<CreateApiKeyOutput> {
+    createApiKeyInputSchema.parse(input)
+    return this.post('/v1/api-keys', input, createApiKeyOutputSchema, options)
+  }
+
+  revoke(id: string, options?: RequestOptions): Promise<ApiKey> {
+    return this.post(`/v1/api-keys/${encodeURIComponent(id)}/revoke`, {}, apiKeySchema, options)
+  }
+}

package/src/resources/base-resource.ts

@@ -0,0 +1,116 @@
+/**
+ * Base class every resource extends. Centralises endpoint plumbing so
+ * resource classes are tiny declarative wrappers.
+ */
+
+import type { z } from 'zod'
+import type { Fetcher, RequestSpec } from '../http/fetcher.js'
+import { generateIdempotencyKey } from '../idempotency.js'
+import { AutoPagingIterator, type Page, type PaginationParams } from '../pagination.js'
+
+type AnySchema = z.ZodTypeAny
+type Inferred<S extends AnySchema> = z.output<S>
+
+export interface ResourceContext {
+  fetcher: Fetcher
+}
+
+export interface RequestOptions {
+  /** Override or supply the idempotency key for a mutating call. */
+  idempotencyKey?: string
+  /** Per-request timeout in ms. */
+  timeoutMs?: number
+}
+
+export abstract class BaseResource {
+  constructor(protected readonly ctx: ResourceContext) {}
+
+  protected async get<S extends AnySchema>(
+    path: string,
+    schema?: S,
+    query?: RequestSpec['query'],
+  ): Promise<Inferred<S>> {
+    const data = await this.ctx.fetcher.request<unknown>({ method: 'GET', path, query })
+    return parse(data, schema)
+  }
+
+  protected async post<S extends AnySchema>(
+    path: string,
+    body: unknown,
+    schema?: S,
+    options?: RequestOptions,
+  ): Promise<Inferred<S>> {
+    const data = await this.ctx.fetcher.request<unknown>({
+      method: 'POST',
+      path,
+      body,
+      idempotencyKey: options?.idempotencyKey ?? generateIdempotencyKey(),
+      timeoutMs: options?.timeoutMs,
+    })
+    return parse(data, schema)
+  }
+
+  protected async patch<S extends AnySchema>(
+    path: string,
+    body: unknown,
+    schema?: S,
+    options?: RequestOptions,
+  ): Promise<Inferred<S>> {
+    const data = await this.ctx.fetcher.request<unknown>({
+      method: 'PATCH',
+      path,
+      body,
+      idempotencyKey: options?.idempotencyKey ?? generateIdempotencyKey(),
+      timeoutMs: options?.timeoutMs,
+    })
+    return parse(data, schema)
+  }
+
+  protected async delete<S extends AnySchema>(path: string, schema?: S): Promise<Inferred<S>> {
+    const data = await this.ctx.fetcher.request<unknown>({ method: 'DELETE', path })
+    return parse(data, schema)
+  }
+
+  protected listPage<S extends AnySchema>(
+    path: string,
+    itemSchema: S,
+    params?: PaginationParams | Record<string, ScalarParam>,
+  ): Promise<Page<Inferred<S>>> {
+    return this.ctx.fetcher
+      .request<unknown>({ method: 'GET', path, query: toQuery(params) })
+      .then((raw) => parsePage(raw, itemSchema))
+  }
+
+  protected listAuto<S extends AnySchema>(
+    path: string,
+    itemSchema: S,
+    params?: Record<string, ScalarParam>,
+  ): AutoPagingIterator<Inferred<S>> {
+    return new AutoPagingIterator((cursor) =>
+      this.listPage(path, itemSchema, { ...params, cursor }),
+    )
+  }
+}
+
+type ScalarParam = string | number | boolean | null | undefined
+
+function toQuery(
+  params: PaginationParams | Record<string, ScalarParam> | undefined,
+): Record<string, ScalarParam> {
+  if (!params) return {}
+  return params as Record<string, ScalarParam>
+}
+
+function parse<S extends AnySchema>(data: unknown, schema?: S): Inferred<S> {
+  return (schema ? schema.parse(data) : data) as Inferred<S>
+}
+
+function parsePage<S extends AnySchema>(raw: unknown, itemSchema: S): Page<Inferred<S>> {
+  const obj = raw as { data?: unknown[]; nextCursor?: string | null; hasMore?: boolean }
+  const items = (obj?.data ?? []).map((d) => itemSchema.parse(d) as Inferred<S>)
+  return {
+    data: items,
+    nextCursor: obj?.nextCursor ?? null,
+    hasMore: obj?.hasMore === true,
+  }
+}

package/src/resources/checkout.ts

@@ -0,0 +1,32 @@
+import {
+  paymentSessionSchema,
+  subscriptionPlanSchema,
+  type PaymentSession,
+  type SubscriptionPlan,
+} from '@strimz/shared-types'
+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
+ * 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.
+ *
+ * Use this resource (via `StrimzBrowserClient.checkout`) from the
+ * browser. The merchant-scoped `paymentSessions` / `subscriptionPlans`
+ * resources on `StrimzClient` remain the right call from server-side
+ * code with a secret key.
+ */
+export class CheckoutResource extends BaseResource {
+  /** 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). */
+  plan(id: string): Promise<SubscriptionPlan> {
+    return this.get(`/v1/checkout/plans/${encodeURIComponent(id)}`, subscriptionPlanSchema)
+  }
+}

package/src/resources/customers.ts

@@ -0,0 +1,25 @@
+import {
+  customerSchema,
+  upsertCustomerInputSchema,
+  type Customer,
+  type UpsertCustomerInput,
+} from '@strimz/shared-types'
+import type { PaginationParams, Page } from '../pagination.js'
+import { BaseResource, type RequestOptions } from './base-resource.js'
+
+export class CustomersResource extends BaseResource {
+  retrieve(id: string): Promise<Customer> {
+    return this.get(`/v1/customers/${encodeURIComponent(id)}`, customerSchema)
+  }
+
+  list(
+    params?: PaginationParams & { externalRef?: string; walletAddress?: string },
+  ): Promise<Page<Customer>> {
+    return this.listPage('/v1/customers', customerSchema, params)
+  }
+
+  upsert(input: UpsertCustomerInput, options?: RequestOptions): Promise<Customer> {
+    upsertCustomerInputSchema.parse(input)
+    return this.post('/v1/customers', input, customerSchema, options)
+  }
+}

package/src/resources/invoices.ts

@@ -0,0 +1,31 @@
+import {
+  invoiceSchema,
+  createInvoiceInputSchema,
+  type Invoice,
+  type CreateInvoiceInput,
+} from '@strimz/shared-types'
+import type { PaginationParams, Page } from '../pagination.js'
+import { BaseResource, type RequestOptions } from './base-resource.js'
+
+export class InvoicesResource extends BaseResource {
+  create(input: CreateInvoiceInput, options?: RequestOptions): Promise<Invoice> {
+    createInvoiceInputSchema.parse(input)
+    return this.post('/v1/invoices', input, invoiceSchema, options)
+  }
+
+  retrieve(id: string): Promise<Invoice> {
+    return this.get(`/v1/invoices/${encodeURIComponent(id)}`, invoiceSchema)
+  }
+
+  list(params?: PaginationParams & { status?: string }): Promise<Page<Invoice>> {
+    return this.listPage('/v1/invoices', invoiceSchema, params)
+  }
+
+  send(id: string, options?: RequestOptions): Promise<Invoice> {
+    return this.post(`/v1/invoices/${encodeURIComponent(id)}/send`, {}, invoiceSchema, options)
+  }
+
+  void(id: string, options?: RequestOptions): Promise<Invoice> {
+    return this.post(`/v1/invoices/${encodeURIComponent(id)}/void`, {}, invoiceSchema, options)
+  }
+}

package/src/resources/merchants.ts

@@ -0,0 +1,26 @@
+import {
+  merchantSchema,
+  updateMerchantInputSchema,
+  changeTierInputSchema,
+  type Merchant,
+  type UpdateMerchantInput,
+  type ChangeTierInput,
+} from '@strimz/shared-types'
+import { BaseResource, type RequestOptions } from './base-resource.js'
+
+export class MerchantsResource extends BaseResource {
+  /** The merchant the API key belongs to. */
+  me(): Promise<Merchant> {
+    return this.get('/v1/merchants/me', merchantSchema)
+  }
+
+  update(input: UpdateMerchantInput, options?: RequestOptions): Promise<Merchant> {
+    updateMerchantInputSchema.parse(input)
+    return this.patch('/v1/merchants/me', input, merchantSchema, options)
+  }
+
+  changeTier(input: ChangeTierInput, options?: RequestOptions): Promise<Merchant> {
+    changeTierInputSchema.parse(input)
+    return this.post('/v1/merchants/me/tier', input, merchantSchema, options)
+  }
+}

package/src/resources/payment-sessions.ts

@@ -0,0 +1,41 @@
+import {
+  paymentSessionSchema,
+  createPaymentSessionInputSchema,
+  type PaymentSession,
+  type CreatePaymentSessionInput,
+} from '@strimz/shared-types'
+import type { PaginationParams, Page } from '../pagination.js'
+import { BaseResource, type RequestOptions } from './base-resource.js'
+
+export class PaymentSessionsResource extends BaseResource {
+  create(input: CreatePaymentSessionInput, options?: RequestOptions): Promise<PaymentSession> {
+    createPaymentSessionInputSchema.parse(input)
+    return this.post('/v1/payment-sessions', input, paymentSessionSchema, options)
+  }
+
+  retrieve(id: string): Promise<PaymentSession> {
+    return this.get(`/v1/payment-sessions/${encodeURIComponent(id)}`, paymentSessionSchema)
+  }
+
+  list(params?: PaginationParams & { status?: string }): Promise<Page<PaymentSession>> {
+    return this.listPage('/v1/payment-sessions', paymentSessionSchema, params)
+  }
+
+  cancel(id: string, options?: RequestOptions): Promise<PaymentSession> {
+    return this.post(
+      `/v1/payment-sessions/${encodeURIComponent(id)}/cancel`,
+      {},
+      paymentSessionSchema,
+      options,
+    )
+  }
+
+  expire(id: string, options?: RequestOptions): Promise<PaymentSession> {
+    return this.post(
+      `/v1/payment-sessions/${encodeURIComponent(id)}/expire`,
+      {},
+      paymentSessionSchema,
+      options,
+    )
+  }
+}

package/src/resources/refunds.ts

@@ -0,0 +1,36 @@
+import {
+  refundSchema,
+  createRefundInputSchema,
+  submitRefundSignatureInputSchema,
+  type Refund,
+  type CreateRefundInput,
+  type SubmitRefundSignatureInput,
+} from '@strimz/shared-types'
+import type { PaginationParams, Page } from '../pagination.js'
+import { BaseResource, type RequestOptions } from './base-resource.js'
+
+export class RefundsResource extends BaseResource {
+  create(input: CreateRefundInput, options?: RequestOptions): Promise<Refund> {
+    createRefundInputSchema.parse(input)
+    return this.post('/v1/refunds', input, refundSchema, options)
+  }
+
+  retrieve(id: string): Promise<Refund> {
+    return this.get(`/v1/refunds/${encodeURIComponent(id)}`, refundSchema)
+  }
+
+  list(params?: PaginationParams & { status?: string }): Promise<Page<Refund>> {
+    return this.listPage('/v1/refunds', refundSchema, params)
+  }
+
+  /** Record the on-chain refund tx after the merchant signs from their wallet. */
+  submitSignature(input: SubmitRefundSignatureInput, options?: RequestOptions): Promise<Refund> {
+    submitRefundSignatureInputSchema.parse(input)
+    return this.post(
+      `/v1/refunds/${encodeURIComponent(input.id)}/signature`,
+      input,
+      refundSchema,
+      options,
+    )
+  }
+}

package/src/resources/storefronts.ts

@@ -0,0 +1,62 @@
+import {
+  storefrontSchema,
+  createStorefrontInputSchema,
+  storefrontProductSchema,
+  createStorefrontProductInputSchema,
+  type Storefront,
+  type CreateStorefrontInput,
+  type StorefrontProduct,
+  type CreateStorefrontProductInput,
+} from '@strimz/shared-types'
+import type { PaginationParams, Page } from '../pagination.js'
+import { BaseResource, type RequestOptions } from './base-resource.js'
+
+export class StorefrontsResource extends BaseResource {
+  /** Retrieve the merchant's own storefront. */
+  retrieve(): Promise<Storefront> {
+    return this.get('/v1/storefront', storefrontSchema)
+  }
+
+  upsert(input: CreateStorefrontInput, options?: RequestOptions): Promise<Storefront> {
+    createStorefrontInputSchema.parse(input)
+    return this.post('/v1/storefront', input, storefrontSchema, options)
+  }
+
+  publish(options?: RequestOptions): Promise<Storefront> {
+    return this.post('/v1/storefront/publish', {}, storefrontSchema, options)
+  }
+
+  archive(options?: RequestOptions): Promise<Storefront> {
+    return this.post('/v1/storefront/archive', {}, storefrontSchema, options)
+  }
+
+  // ----- Products -----
+
+  listProducts(params?: PaginationParams): Promise<Page<StorefrontProduct>> {
+    return this.listPage('/v1/storefront/products', storefrontProductSchema, params)
+  }
+
+  createProduct(
+    input: CreateStorefrontProductInput,
+    options?: RequestOptions,
+  ): Promise<StorefrontProduct> {
+    createStorefrontProductInputSchema.parse(input)
+    return this.post('/v1/storefront/products', input, storefrontProductSchema, options)
+  }
+
+  retrieveProduct(productId: string): Promise<StorefrontProduct> {
+    return this.get(
+      `/v1/storefront/products/${encodeURIComponent(productId)}`,
+      storefrontProductSchema,
+    )
+  }
+
+  archiveProduct(productId: string, options?: RequestOptions): Promise<StorefrontProduct> {
+    return this.post(
+      `/v1/storefront/products/${encodeURIComponent(productId)}/archive`,
+      {},
+      storefrontProductSchema,
+      options,
+    )
+  }
+}

package/src/resources/subscription-plans.ts

@@ -0,0 +1,32 @@
+import {
+  subscriptionPlanSchema,
+  createSubscriptionPlanInputSchema,
+  type SubscriptionPlan,
+  type CreateSubscriptionPlanInput,
+} from '@strimz/shared-types'
+import type { PaginationParams, Page } from '../pagination.js'
+import { BaseResource, type RequestOptions } from './base-resource.js'
+
+export class SubscriptionPlansResource extends BaseResource {
+  create(input: CreateSubscriptionPlanInput, options?: RequestOptions): Promise<SubscriptionPlan> {
+    createSubscriptionPlanInputSchema.parse(input)
+    return this.post('/v1/subscription-plans', input, subscriptionPlanSchema, options)
+  }
+
+  retrieve(id: string): Promise<SubscriptionPlan> {
+    return this.get(`/v1/subscription-plans/${encodeURIComponent(id)}`, subscriptionPlanSchema)
+  }
+
+  list(params?: PaginationParams & { status?: string }): Promise<Page<SubscriptionPlan>> {
+    return this.listPage('/v1/subscription-plans', subscriptionPlanSchema, params)
+  }
+
+  archive(id: string, options?: RequestOptions): Promise<SubscriptionPlan> {
+    return this.post(
+      `/v1/subscription-plans/${encodeURIComponent(id)}/archive`,
+      {},
+      subscriptionPlanSchema,
+      options,
+    )
+  }
+}

package/src/resources/subscriptions.ts

@@ -0,0 +1,37 @@
+import {
+  subscriptionSchema,
+  createSubscriptionInputSchema,
+  cancelSubscriptionInputSchema,
+  type Subscription,
+  type CreateSubscriptionInput,
+  type CancelSubscriptionInput,
+} from '@strimz/shared-types'
+import type { PaginationParams, Page } from '../pagination.js'
+import { BaseResource, type RequestOptions } from './base-resource.js'
+
+export class SubscriptionsResource extends BaseResource {
+  create(input: CreateSubscriptionInput, options?: RequestOptions): Promise<Subscription> {
+    createSubscriptionInputSchema.parse(input)
+    return this.post('/v1/subscriptions', input, subscriptionSchema, options)
+  }
+
+  retrieve(id: string): Promise<Subscription> {
+    return this.get(`/v1/subscriptions/${encodeURIComponent(id)}`, subscriptionSchema)
+  }
+
+  list(
+    params?: PaginationParams & { status?: string; planId?: string },
+  ): Promise<Page<Subscription>> {
+    return this.listPage('/v1/subscriptions', subscriptionSchema, params)
+  }
+
+  cancel(input: CancelSubscriptionInput, options?: RequestOptions): Promise<Subscription> {
+    cancelSubscriptionInputSchema.parse(input)
+    return this.post(
+      `/v1/subscriptions/${encodeURIComponent(input.id)}/cancel`,
+      input,
+      subscriptionSchema,
+      options,
+    )
+  }
+}