@strimz/sdk 0.1.0

package/src/resources/tokens.ts

@@ -0,0 +1,70 @@
+import {
+  tokenMetadataSchema,
+  tokenPermitNonceSchema,
+  type TokenMetadata,
+  type TokenPermitNonce,
+} from '@strimz/shared-types'
+import { BaseResource } from './base-resource.js'
+
+/**
+ * Token metadata + capability lookup.
+ *
+ * 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
+ * fetch themselves.
+ */
+export class TokensResource extends BaseResource {
+  /**
+   * Fetch full metadata for a token. Throws via the underlying fetcher
+   * (404 → `StrimzNotFoundError`) if the token isn't whitelisted.
+   */
+  retrieve(address: string): Promise<TokenMetadata> {
+    return this.get(`/v1/tokens/${encodeURIComponent(address.toLowerCase())}`, tokenMetadataSchema)
+  }
+
+  /**
+   * Read an owner's current EIP-2612 permit nonce. Call this
+   * 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> {
+    return this.get(
+      `/v1/tokens/${encodeURIComponent(address.toLowerCase())}/permit-nonce`,
+      tokenPermitNonceSchema,
+      { owner: owner.toLowerCase() },
+    )
+  }
+}
+
+/**
+ * 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.
+ *
+ * Returned `path` values are strings (not enums) so future schemes
+ * can extend the union without breaking existing call sites.
+ */
+export type RelayPath =
+  | 'pay_with_authorization'
+  | 'permit_and_create_subscription'
+  | 'approve_then_pay'
+  | 'approve_then_create_subscription'
+
+export function selectPaymentPath(meta: TokenMetadata): RelayPath {
+  return meta.capabilities.transferAuth3009 ? 'pay_with_authorization' : 'approve_then_pay'
+}
+
+export function selectSubscriptionPath(meta: TokenMetadata): RelayPath {
+  return meta.capabilities.permit2612
+    ? 'permit_and_create_subscription'
+    : 'approve_then_create_subscription'
+}

package/src/resources/transactions.ts

@@ -0,0 +1,20 @@
+import { transactionSchema, type Transaction } from '@strimz/shared-types'
+import type { PaginationParams, Page } from '../pagination.js'
+import { BaseResource } from './base-resource.js'
+
+export class TransactionsResource extends BaseResource {
+  retrieve(id: string): Promise<Transaction> {
+    return this.get(`/v1/transactions/${encodeURIComponent(id)}`, transactionSchema)
+  }
+
+  list(
+    params?: PaginationParams & {
+      kind?: string
+      status?: string
+      from?: string
+      to?: string
+    },
+  ): Promise<Page<Transaction>> {
+    return this.listPage('/v1/transactions', transactionSchema, params)
+  }
+}

package/src/resources/webhook-deliveries.ts

@@ -0,0 +1,29 @@
+import { webhookDeliverySchema, type WebhookDelivery } from '@strimz/shared-types'
+import type { PaginationParams, Page } from '../pagination.js'
+import { BaseResource, type RequestOptions } from './base-resource.js'
+
+export class WebhookDeliveriesResource extends BaseResource {
+  retrieve(id: string): Promise<WebhookDelivery> {
+    return this.get(`/v1/webhook-deliveries/${encodeURIComponent(id)}`, webhookDeliverySchema)
+  }
+
+  list(
+    params?: PaginationParams & {
+      endpointId?: string
+      status?: string
+      eventName?: string
+    },
+  ): Promise<Page<WebhookDelivery>> {
+    return this.listPage('/v1/webhook-deliveries', webhookDeliverySchema, params)
+  }
+
+  /** Manually replay a permanently-failed delivery. */
+  replay(id: string, options?: RequestOptions): Promise<WebhookDelivery> {
+    return this.post(
+      `/v1/webhook-deliveries/${encodeURIComponent(id)}/replay`,
+      {},
+      webhookDeliverySchema,
+      options,
+    )
+  }
+}

package/src/resources/webhook-endpoints.ts

@@ -0,0 +1,56 @@
+import {
+  webhookEndpointSchema,
+  createWebhookEndpointInputSchema,
+  createWebhookEndpointOutputSchema,
+  type WebhookEndpoint,
+  type CreateWebhookEndpointInput,
+  type CreateWebhookEndpointOutput,
+} from '@strimz/shared-types'
+import type { PaginationParams, Page } from '../pagination.js'
+import { BaseResource, type RequestOptions } from './base-resource.js'
+
+export class WebhookEndpointsResource extends BaseResource {
+  create(
+    input: CreateWebhookEndpointInput,
+    options?: RequestOptions,
+  ): Promise<CreateWebhookEndpointOutput> {
+    createWebhookEndpointInputSchema.parse(input)
+    return this.post('/v1/webhook-endpoints', input, createWebhookEndpointOutputSchema, options)
+  }
+
+  retrieve(id: string): Promise<WebhookEndpoint> {
+    return this.get(`/v1/webhook-endpoints/${encodeURIComponent(id)}`, webhookEndpointSchema)
+  }
+
+  list(params?: PaginationParams): Promise<Page<WebhookEndpoint>> {
+    return this.listPage('/v1/webhook-endpoints', webhookEndpointSchema, params)
+  }
+
+  disable(id: string, options?: RequestOptions): Promise<WebhookEndpoint> {
+    return this.post(
+      `/v1/webhook-endpoints/${encodeURIComponent(id)}/disable`,
+      {},
+      webhookEndpointSchema,
+      options,
+    )
+  }
+
+  enable(id: string, options?: RequestOptions): Promise<WebhookEndpoint> {
+    return this.post(
+      `/v1/webhook-endpoints/${encodeURIComponent(id)}/enable`,
+      {},
+      webhookEndpointSchema,
+      options,
+    )
+  }
+
+  /** Rotates the signing secret. Returns the new full secret exactly once. */
+  rotateSecret(id: string, options?: RequestOptions): Promise<CreateWebhookEndpointOutput> {
+    return this.post(
+      `/v1/webhook-endpoints/${encodeURIComponent(id)}/rotate-secret`,
+      {},
+      createWebhookEndpointOutputSchema,
+      options,
+    )
+  }
+}

package/src/webhooks.ts

@@ -0,0 +1,64 @@
+/**
+ * Webhook utilities — re-exports the verified-and-tested 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.
+ */
+
+export {
+  signWebhookPayload,
+  verifyWebhookSignature,
+  WEBHOOK_SIGNATURE_VERSION,
+  type SignWebhookOptions,
+  type VerifyWebhookOptions,
+  type VerifyWebhookReason,
+  type VerifyWebhookResult,
+} from '@strimz/shared-crypto'
+
+export {
+  webhookEventSchema,
+  webhookEventNameSchema,
+  type StrimzWebhookEvent,
+  type WebhookEventName,
+  // Per-event typed payloads.
+  type PaymentCreatedEvent,
+  type PaymentCompletedEvent,
+  type PaymentFailedEvent,
+  type SubscriptionCreatedEvent,
+  type SubscriptionChargedEvent,
+  type SubscriptionChargeFailedEvent,
+  type SubscriptionRecoveryAttemptEvent,
+  type SubscriptionRecoveryOutcomeEvent,
+  type SubscriptionCancelledEvent,
+  type SubscriptionLapsedEvent,
+  type RefundCreatedEvent,
+  type RefundCompletedEvent,
+  type RefundFailedEvent,
+  type InvoiceCreatedEvent,
+  type InvoicePaidEvent,
+  type InvoiceOverdueEvent,
+  type AgentActionExecutedEvent,
+  type AgentJobProposedEvent,
+  type AgentJobCompletedEvent,
+  type AgentJobDisputedEvent,
+  type ComplianceWalletFlaggedEvent,
+  type ComplianceWalletBlockedEvent,
+} from '@strimz/shared-types'
+
+export {
+  WEBHOOK_RETRY_SCHEDULE_SECONDS,
+  WEBHOOK_MAX_ATTEMPTS,
+  WEBHOOK_SIGNATURE_TOLERANCE_SECONDS,
+  WEBHOOK_SIGNATURE_HEADER,
+  WEBHOOK_DELIVERY_ID_HEADER,
+} from '@strimz/shared-config'
+
+import { webhookEventSchema, type StrimzWebhookEvent } from '@strimz/shared-types'
+
+/**
+ * Parse a webhook payload into a typed `StrimzWebhookEvent`.
+ * Use after `verifyWebhookSignature` succeeds — never trust raw payloads.
+ */
+export function parseWebhookEvent(rawJson: string): StrimzWebhookEvent {
+  return webhookEventSchema.parse(JSON.parse(rawJson))
+}