@strimz/shared-types 0.1.1 → 0.3.0

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

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

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

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

@@ -119,6 +119,13 @@ export const subscriptionSchema = z.object({
 })
 export type Subscription = z.infer<typeof subscriptionSchema>
 
+/** Whether a wallet already subscribes to a given plan, and which one. */
+export const subscriptionStatusResultSchema = z.object({
+  active: z.boolean(),
+  subscriptionId: idSchema.nullable(),
+})
+export type SubscriptionStatusResult = z.infer<typeof subscriptionStatusResultSchema>
+
 export const createSubscriptionInputSchema = z.object({
   planId: idSchema,
   customer: z.object({

package/src/webhooks.ts

@@ -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,
 })