@strimz/shared-types 0.1.0 → 0.2.0

package/src/api-keys.ts

@@ -12,9 +12,8 @@ export const apiKeyKindSchema = z.enum(['secret', 'publishable'])
 export type ApiKeyKind = z.infer<typeof apiKeyKindSchema>
 
 /**
- * Underscore-separated to match the Prisma `ApiKeyScope` enum (Prisma
- * does not allow `:` in enum values). The DB and the wire format use the
- * same form so there is no boundary translation.
+ * Underscore-separated. The wire format and any database representation
+ * use the same form so there is no boundary translation.
  */
 export const apiKeyScopeSchema = z.enum([
   'sessions_read',
@@ -32,11 +31,16 @@ export const apiKeyScopeSchema = z.enum([
   'storefronts_write',
   'agents_read',
   'agents_write',
-  // Meta-tx relayer — submitting payer-signed EIP-3009 / EIP-2612
+  // Meta-tx relayer. Submitting payer-signed EIP-3009 / EIP-2612
   // authorizations on the merchant's behalf. Granted to keys used by
   // hosted checkout and merchants embedding the SDK.
   'relay_read',
   'relay_write',
+  // Self-service key management from an API key holder. Rarely used
+  // day-to-day; needed for partner onboarding flows that mint scoped
+  // keys per sub-tenant.
+  'api_keys_read',
+  'api_keys_write',
 ])
 export type ApiKeyScope = z.infer<typeof apiKeyScopeSchema>
 
@@ -67,7 +71,7 @@ export type CreateApiKeyInput = z.infer<typeof createApiKeyInputSchema>
 
 export const createApiKeyOutputSchema = z.object({
   apiKey: apiKeySchema,
-  /** Full plaintext key — shown exactly once. */
+  /** Full plaintext key. Shown exactly once. */
   secret: z.string(),
 })
 export type CreateApiKeyOutput = z.infer<typeof createApiKeyOutputSchema>

package/src/common.ts

@@ -89,7 +89,7 @@ export const metadataSchema = z
 export const modeSchema = z.enum(['test', 'live'])
 export type Mode = z.infer<typeof modeSchema>
 
-/** Payment token enum — mirrors `@strimz/shared-config`. */
+/** Payment token enum. */
 export const paymentCurrencySchema = z.enum(['USDC', 'EURC'])
 export type PaymentCurrency = z.infer<typeof paymentCurrencySchema>
 
@@ -97,7 +97,7 @@ export type PaymentCurrency = z.infer<typeof paymentCurrencySchema>
 export const tokenSymbolSchema = z.enum(['USDC', 'EURC', 'USYC'])
 export type TokenSymbol = z.infer<typeof tokenSymbolSchema>
 
-/** Merchant tier enum — mirrors `@strimz/shared-config`. */
+/** Merchant tier enum. */
 export const merchantTierSchema = z.enum(['free', 'growth', 'business', 'enterprise'])
 export type MerchantTier = z.infer<typeof merchantTierSchema>
 

package/src/compliance.ts

@@ -1,5 +1,5 @@
 /**
- * Compliance — sanctions/AML screening log.
+ * Compliance: sanctions/AML screening log.
  *
  * Every wallet address that interacts with Strimz (merchant payout,
  * subscriber, payer) is screened. Results are logged; provider and score

package/src/contact.ts

@@ -0,0 +1,26 @@
+/**
+ * Public marketing contact form. Not an authenticated API resource —
+ * routed straight to a support inbox by the contact module in
+ * `apps/api`. Kept shape-compatible with what the marketing form on
+ * the Strimz landing page already validates client-side.
+ */
+
+import { z } from 'zod'
+import { emailSchema } from './common.js'
+
+export const contactTopicSchema = z.enum(['sales', 'support', 'partnership', 'security', 'other'])
+export type ContactTopic = z.infer<typeof contactTopicSchema>
+
+export const contactRequestInputSchema = z.object({
+  name: z.string().min(2).max(120),
+  email: emailSchema,
+  company: z.string().min(1).max(120).optional(),
+  topic: contactTopicSchema,
+  message: z.string().min(20).max(4000),
+})
+export type ContactRequestInput = z.infer<typeof contactRequestInputSchema>
+
+export const contactRequestOutputSchema = z.object({
+  ok: z.literal(true),
+})
+export type ContactRequestOutput = z.infer<typeof contactRequestOutputSchema>

package/src/customers.ts

@@ -1,5 +1,5 @@
 /**
- * Customer — the payer on the merchant's side.
+ * Customer. The payer on the merchant's side.
  *
  * Customers are uniquely identified by (merchantId, walletAddress). Email and
  * externalRef are optional; merchants can associate their own customer id.

package/src/index.ts

@@ -21,3 +21,5 @@ export * from './storefronts.js'
 export * from './invoices.js'
 export * from './events.js'
 export * from './tokens.js'
+export * from './contact.js'
+export * from './notifications.js'

package/src/invoices.ts

@@ -1,5 +1,5 @@
 /**
- * Invoices — shareable, expirable payment requests with structured line items.
+ * Invoices. Shareable, expirable payment requests with structured line items.
  */
 
 import { z } from 'zod'

package/src/merchants.ts

@@ -30,6 +30,8 @@ export const merchantSchema = z.object({
   tier: merchantTierSchema,
   status: merchantStatusSchema,
   payoutAddress: evmAddressSchema.nullable(),
+  walletAddress: evmAddressSchema.nullable(),
+  onboardingCompleted: z.boolean(),
   defaultCurrency: z.enum(['USDC', 'EURC']),
   countryCode: z.string().length(2).nullable(),
   websiteUrl: z.string().url().nullable(),
@@ -52,6 +54,23 @@ export const createMerchantInputSchema = z.object({
 })
 export type CreateMerchantInput = z.infer<typeof createMerchantInputSchema>
 
+/**
+ * Merchant email opt-outs, persisted at `Merchant.metadata.emailPrefs`.
+ * Both default to true. Welcome, refunds, and admin broadcasts always send.
+ */
+export const merchantEmailPrefsSchema = z.object({
+  /** "You received X USDC" one-off payment notifications. */
+  paymentReceived: z.boolean(),
+  /** "You were paid X for subscription Y" per-charge notifications. */
+  subscriptionCharged: z.boolean(),
+})
+export type MerchantEmailPrefs = z.infer<typeof merchantEmailPrefsSchema>
+
+export const DEFAULT_MERCHANT_EMAIL_PREFS: MerchantEmailPrefs = {
+  paymentReceived: true,
+  subscriptionCharged: true,
+}
+
 export const updateMerchantInputSchema = z
   .object({
     businessName: z.string().min(2).max(120),
@@ -61,6 +80,7 @@ export const updateMerchantInputSchema = z
     logoUrl: z.string().url().nullable(),
     countryCode: z.string().length(2).nullable(),
     metadata: metadataSchema,
+    emailPrefs: merchantEmailPrefsSchema.partial(),
   })
   .partial()
 export type UpdateMerchantInput = z.infer<typeof updateMerchantInputSchema>
@@ -70,6 +90,70 @@ export const changeTierInputSchema = z.object({
 })
 export type ChangeTierInput = z.infer<typeof changeTierInputSchema>
 
+/**
+ * Self-attested onboarding form the dashboard collects after a
+ * merchant first logs in via Privy. On success the API stamps
+ * `onboardingCompleted: true` on the row, and the dashboard exits
+ * the wizard. Shared here so the API's DTO and the web client's
+ * hook can enforce the same shape.
+ */
+export const onboardMerchantInputSchema = z.object({
+  businessName: z.string().min(2).max(120),
+  businessSector: z.string().min(2).max(80),
+  countryCode: z
+    .string()
+    .length(2)
+    .regex(/^[A-Z]{2}$/, 'must be a 2-letter ISO country code'),
+  websiteUrl: z.string().url().optional(),
+  logoUrl: z.string().url().optional(),
+  phone: z.string().min(6).max(20).optional(),
+  payoutAddress: evmAddressSchema,
+  defaultCurrency: z.enum(['USDC', 'EURC']).optional(),
+})
+export type OnboardMerchantInput = z.infer<typeof onboardMerchantInputSchema>
+
+export const merchantPublicBrandSchema = z.object({
+  id: idSchema,
+  businessName: z.string().min(2).max(120),
+  logoUrl: z.string().url().nullable(),
+  walletAddress: evmAddressSchema.nullable(),
+})
+export type MerchantPublicBrand = z.infer<typeof merchantPublicBrandSchema>
+
+/**
+ * On-chain balance view for the withdraw page. Strimz is
+ * non-custodial: payments settle directly into the merchant's
+ * `payoutAddress`, and "withdrawal" means the merchant transferring
+ * out with their own wallet. This shape reports current on-chain
+ * state so the dashboard renders live balances + decides whether to
+ * offer the signing UI.
+ */
+export const merchantBalanceSchema = z.object({
+  /** Payout wallet, checksummed; null when the merchant hasn't set one. */
+  payoutAddress: evmAddressSchema.nullable(),
+  /** Privy embedded wallet, checksummed if resolvable. */
+  walletAddress: evmAddressSchema.nullable(),
+  /**
+   * True when `payoutAddress === walletAddress`, i.e. the merchant
+   * can sign a transfer from the dashboard via Privy. False for
+   * merchants using an external wallet as payout — the UI falls back
+   * to "copy the address, transfer with your wallet."
+   */
+  canSignFromDashboard: z.boolean(),
+  balances: z.array(
+    z.object({
+      currency: z.enum(['USDC', 'EURC']),
+      contractAddress: evmAddressSchema,
+      /** Base-6 integer as string. */
+      raw: z.string(),
+      /** Human-formatted, e.g. `1234.56`. */
+      formatted: z.string(),
+      decimals: z.number().int().min(0).max(30),
+    }),
+  ),
+})
+export type MerchantBalanceView = z.infer<typeof merchantBalanceSchema>
+
 // ---------- Team members ----------
 
 export const merchantMemberSchema = z.object({

package/src/notifications.ts

@@ -0,0 +1,88 @@
+/**
+ * Dashboard notifications. Derived server-side from recent activity
+ * (confirmed payment sessions, new subscribers, processed refunds).
+ * Read state is tracked on the merchant record via
+ * `notificationsLastReadAt` — `event.createdAt <= that timestamp` is
+ * "read", anything newer is "unread". No dedicated notifications
+ * table because the source rows already exist; a separate table would
+ * just be a denormalised copy.
+ */
+
+import { z } from 'zod'
+import { idSchema, isoTimestampSchema } from './common.js'
+
+export const notificationKindSchema = z.enum([
+  'payment_received',
+  'subscription_started',
+  'refund_processed',
+  /** Message an admin broadcast to this merchant (or all merchants). */
+  'admin_broadcast',
+])
+export type NotificationKind = z.infer<typeof notificationKindSchema>
+
+// ---------- Admin broadcasts ----------
+
+export const broadcastAudienceSchema = z.enum(['all', 'merchant'])
+export type BroadcastAudience = z.infer<typeof broadcastAudienceSchema>
+
+export const createBroadcastInputSchema = z
+  .object({
+    title: z.string().min(4).max(160),
+    body: z.string().min(4).max(4000),
+    audience: broadcastAudienceSchema.default('all'),
+    /** Required when `audience === 'merchant'`; ignored otherwise. */
+    merchantId: z.string().optional(),
+  })
+  .refine((v) => v.audience !== 'merchant' || !!v.merchantId, {
+    message: 'merchantId is required when audience is merchant',
+    path: ['merchantId'],
+  })
+export type CreateBroadcastInput = z.infer<typeof createBroadcastInputSchema>
+
+export const broadcastSchema = z.object({
+  id: idSchema,
+  title: z.string(),
+  body: z.string(),
+  audience: broadcastAudienceSchema,
+  merchantId: idSchema.nullable(),
+  merchantEmail: z.string().nullable(),
+  senderId: idSchema,
+  senderEmail: z.string(),
+  emailedAt: isoTimestampSchema.nullable(),
+  createdAt: isoTimestampSchema,
+})
+export type Broadcast = z.infer<typeof broadcastSchema>
+
+export const broadcastListResponseSchema = z.object({
+  data: z.array(broadcastSchema),
+})
+export type BroadcastListResponse = z.infer<typeof broadcastListResponseSchema>
+
+export const notificationSchema = z.object({
+  /** Deterministic client id — `{kind}:{sourceId}`. Safe for React keys. */
+  id: z.string().min(1),
+  kind: notificationKindSchema,
+  title: z.string().min(1),
+  detail: z.string(),
+  /** Dashboard route the tray links to. */
+  href: z.string().min(1),
+  /** ISO timestamp of the source event; drives sort + read comparison. */
+  createdAt: isoTimestampSchema,
+  /** Server-derived from the merchant's `notificationsLastReadAt`. */
+  read: z.boolean(),
+  /** Optional foreign key back to the source row (for deep-linking). */
+  sourceId: idSchema.optional(),
+})
+export type NotificationView = z.infer<typeof notificationSchema>
+
+export const notificationListResponseSchema = z.object({
+  data: z.array(notificationSchema),
+  unreadCount: z.number().int().min(0),
+  lastReadAt: isoTimestampSchema.nullable(),
+})
+export type NotificationListResponse = z.infer<typeof notificationListResponseSchema>
+
+export const markNotificationsReadResponseSchema = z.object({
+  lastReadAt: isoTimestampSchema,
+})
+export type MarkNotificationsReadResponse = z.infer<typeof markNotificationsReadResponseSchema>

package/src/payment-sessions.ts

@@ -1,5 +1,5 @@
 /**
- * Payment session — a one-shot checkout intent.
+ * Payment session. A one-shot checkout intent.
  *
  * State machine:
  *   created → awaiting_payment → submitted → confirmed
@@ -31,6 +31,28 @@ export const paymentSessionStatusSchema = z.enum([
 ])
 export type PaymentSessionStatus = z.infer<typeof paymentSessionStatusSchema>
 
+/**
+ * Merchant-supplied callback URL. The hosted checkout dispatches with
+ * `window.location.href = redirectUrl` on completion / cancellation,
+ * so we MUST reject anything other than `http://` and `https://`.
+ *
+ * Why this is a real risk: Zod's `.url()` validates RFC syntax, which
+ * accepts `javascript:`, `data:`, `vbscript:`, `file:`, blob:`, etc.
+ * A compromised merchant integration or an XSS upstream could ship a
+ * session whose redirect URL executes script (or exfiltrates session
+ * tokens) on every payer's browser. The damage is per-payer, but the
+ * blast radius is "every checkout the merchant runs."
+ *
+ * Mailto / tel and other handler protocols are also rejected — there
+ * is no legitimate flow on a payment checkout that would benefit.
+ */
+export const callbackUrlSchema = z
+  .string()
+  .url()
+  .refine((v) => v.startsWith('https://') || v.startsWith('http://'), {
+    message: 'must be an http:// or https:// URL',
+  })
+
 export const paymentSessionSchema = z.object({
   id: idSchema,
   merchantId: idSchema,
@@ -63,8 +85,8 @@ export const paymentSessionSchema = z.object({
   description: z.string().max(500).nullable(),
   payerWalletAddress: evmAddressSchema.nullable(),
   payerEmail: z.string().email().nullable(),
-  successUrl: z.string().url().nullable(),
-  cancelUrl: z.string().url().nullable(),
+  successUrl: callbackUrlSchema.nullable(),
+  cancelUrl: callbackUrlSchema.nullable(),
   sourceChain: z
     .enum(['arc', 'ethereum', 'base', 'polygon', 'arbitrum', 'optimism', 'avalanche', 'solana'])
     .nullable(),

package/src/refunds.ts

@@ -1,5 +1,5 @@
 /**
- * Refund — a merchant-initiated return of funds to a payer.
+ * Refund. A merchant-initiated return of funds to a payer.
  *
  * Refunds are executed off-chain (from the merchant's wallet to the payer's
  * wallet). Strimz records the intent, validates constraints, and reconciles
@@ -66,3 +66,22 @@ export const submitRefundSignatureInputSchema = z.object({
   refundTxHash: evmTxHashSchema,
 })
 export type SubmitRefundSignatureInput = z.infer<typeof submitRefundSignatureInputSchema>
+
+/**
+ * Response envelope for `POST /v1/refunds`. The API returns the newly
+ * created refund plus the concrete ERC-20 transfer the merchant now
+ * has to sign from their payout wallet.
+ */
+export const refundSigningInstructionsSchema = z.object({
+  token: evmAddressSchema,
+  to: evmAddressSchema,
+  amount: tokenAmountSchema,
+  note: z.string(),
+})
+export type RefundSigningInstructions = z.infer<typeof refundSigningInstructionsSchema>
+
+export const refundCreateOutputSchema = z.object({
+  refund: refundSchema,
+  signingInstructions: refundSigningInstructionsSchema,
+})
+export type RefundCreateOutput = z.infer<typeof refundCreateOutputSchema>

package/src/storefronts.ts

@@ -1,5 +1,5 @@
 /**
- * Storefronts — hosted product catalog with checkout baked in.
+ * Storefronts. Hosted product catalog with checkout baked in.
  */
 
 import { z } from 'zod'
@@ -87,3 +87,27 @@ export const createStorefrontProductInputSchema = storefrontProductSchema
     imageUrl: httpsUrlSchema.optional(),
   })
 export type CreateStorefrontProductInput = z.infer<typeof createStorefrontProductInputSchema>
+
+/**
+ * Payload for the public `/store/:slug/products/:id/checkout` endpoint.
+ * Optional customer email flows through into the payment session so
+ * the receipt lands in the buyer's inbox after the tx confirms.
+ * `returnPath` is used to synthesise the success + cancel URLs when
+ * the merchant hasn't wired their own.
+ */
+export const storefrontCheckoutInputSchema = z.object({
+  customerEmail: z.string().email().optional(),
+  returnPath: z.string().max(200).optional(),
+})
+export type StorefrontCheckoutInput = z.infer<typeof storefrontCheckoutInputSchema>
+
+/** Response shape from the public product-checkout endpoint. */
+export const storefrontCheckoutResponseSchema = z.object({
+  /** Fully-qualified checkout URL — payer redirects here to sign. */
+  checkoutUrl: z.string().url(),
+  /** Payment-session id (one-time) or plan id (subscription). */
+  ref: idSchema,
+  /** Which downstream checkout the URL points at. */
+  kind: z.enum(['payment_session', 'subscription_plan']),
+})
+export type StorefrontCheckoutResponse = z.infer<typeof storefrontCheckoutResponseSchema>

package/src/subscriptions.ts

@@ -1,5 +1,5 @@
 /**
- * Subscriptions — plans, active subscriptions, and individual charges.
+ * Subscriptions: plans, active subscriptions, and individual charges.
  *
  * Design notes:
  * - A SubscriptionPlan is the template a merchant defines.
@@ -39,7 +39,7 @@ export const subscriptionPlanSchema = z.object({
   /**
    * On-chain StrimzRegistry merchant id (uint96) as a decimal string.
    * See `paymentSessionSchema.chainMerchantId`. Null when the merchant
-   * hasn't been registered on-chain yet — the hosted enrolment page
+   * hasn't been registered on-chain yet. The hosted enrolment page
    * refuses to take signatures in that state.
    */
   chainMerchantId: z
@@ -47,7 +47,7 @@ export const subscriptionPlanSchema = z.object({
     .regex(/^[0-9]+$/u, 'must be a non-negative decimal integer string')
     .nullable(),
   /**
-   * ERC-20 token contract address resolved from `currency` — the
+   * ERC-20 token contract address resolved from `currency`. This is the
    * EIP-2612 `verifyingContract` the wallet signs over.
    */
   tokenAddress: evmAddressSchema.nullable(),

package/src/tokens.ts

@@ -3,16 +3,16 @@
  *
  * Read by the SDK's BrowserClient to (1) pick the right meta-tx path
  * for a given token and (2) build the EIP-712 typed-data domain. The
- * shape is intentionally derived from on-chain reads — name / version
- * from the token's ERC-5267 `eip712Domain()` (falling back to a
- * default), capabilities from Strimz's TokenWhitelist contract.
+ * shape is derived from on-chain reads. Name and version come from the
+ * token's ERC-5267 `eip712Domain()` (falling back to a default), and
+ * capabilities come from Strimz's TokenWhitelist contract.
  *
  * `capabilities.permit2612` means the token implements EIP-2612 (the
  * gasless allowance + subscription enrolment path).
  * `capabilities.transferAuth3009` means the token implements EIP-3009
  * (the gasless one-shot payment path).
  *
- * Tokens may have one capability or both — USDC and EURC on Arc
+ * Tokens may have one capability or both. USDC and EURC on Arc
  * advertise both.
  */
 
@@ -34,8 +34,8 @@ export const tokenMetadataSchema = z.object({
   symbol: z.string(),
   /**
    * EIP-712 domain version. Read from ERC-5267 `eip712Domain()` when
-   * available; otherwise defaults to "1". Used by typed-data builders
-   * — domain mismatch produces a different digest and the contract's
+   * available; otherwise defaults to "1". Used by typed-data builders.
+   * A domain mismatch produces a different digest, so the contract's
    * ecrecover would recover a different address.
    */
   version: z.string(),
@@ -46,7 +46,7 @@ export type TokenMetadata = z.infer<typeof tokenMetadataSchema>
 
 /**
  * Owner-specific permit nonce. The EIP-2612 standard tracks a per-
- * owner monotonic counter — every successful permit consumes one,
+ * owner monotonic counter, and every successful permit consumes one,
  * so signers must read the current value immediately before signing.
  *
  * Returned as a decimal string to avoid JS number truncation on the

package/src/transactions.ts

@@ -1,8 +1,8 @@
 /**
- * Transaction — the record of a confirmed on-chain payment.
+ * Transaction. The record of a confirmed on-chain payment.
  *
  * Every transaction corresponds to either a paid PaymentSession, a
- * SubscriptionCharge, or a Refund. The indexer writes these from the
+ * SubscriptionCharge, or a Refund. Records are derived from the
  * `PaymentExecuted`, `SubscriptionCharged`, and `RefundRecorded` events.
  */
 

package/src/webhooks.ts

@@ -12,8 +12,8 @@ import { httpsUrlSchema, idSchema, isoTimestampSchema, modeSchema } from './comm
 // ---------- Event name ----------
 
 /**
- * Every webhook event name in the system. Listed here (not imported from
- * `@strimz/shared-config`) so Zod can produce a concrete string union.
+ * Every webhook event name in the system. Listed inline so Zod can
+ * produce a concrete string union.
  */
 export const webhookEventNameSchema = z.enum([
   'payment.created',
@@ -71,7 +71,7 @@ export type CreateWebhookEndpointInput = z.infer<typeof createWebhookEndpointInp
 
 export const createWebhookEndpointOutputSchema = z.object({
   endpoint: webhookEndpointSchema,
-  /** Full signing secret — shown exactly once. */
+  /** Full signing secret. Shown exactly once. */
   signingSecret: z.string(),
 })
 export type CreateWebhookEndpointOutput = z.infer<typeof createWebhookEndpointOutputSchema>
@@ -103,6 +103,18 @@ export const webhookDeliverySchema = z.object({
 })
 export type WebhookDelivery = z.infer<typeof webhookDeliverySchema>
 
+/**
+ * Detail projection returned by GET /v1/webhook-deliveries/:id.
+ * Carries the payload envelope, response body, and the deliveryId
+ * header the receiver saw. Kept separate so list responses stay slim.
+ */
+export const webhookDeliveryDetailSchema = webhookDeliverySchema.extend({
+  deliveryId: z.string(),
+  responseBody: z.string().nullable(),
+  requestPayload: z.record(z.string(), z.unknown()),
+})
+export type WebhookDeliveryDetail = z.infer<typeof webhookDeliveryDetailSchema>
+
 export const replayDeliveryInputSchema = z.object({
   id: idSchema,
 })