@businessdash/sdk 0.9.60 → 0.9.80

package/dist/contracts.js

@@ -417,7 +417,8 @@ export const chatbotFormFieldSchema = z
     options: z.array(z.string()).optional(),
 })
     .passthrough();
-export const chatbotFormDefinitionSchema = z.object({
+export const chatbotFormDefinitionSchema = z
+    .object({
     id: z.string(),
     slug: z.string(),
     name: z.string(),
@@ -425,11 +426,33 @@ export const chatbotFormDefinitionSchema = z.object({
     fields: z.array(chatbotFormFieldSchema),
     addsInquiry: z.boolean(),
     addsLead: z.boolean(),
-});
+    /**
+     * The RENDER contract — animation, multi-step + progress style, exit
+     * confirmation, URL safety. The server has always sent this; the schema
+     * dropped it, so anyone building a form UI on the typed client got a
+     * bare field list and none of the behaviour the dashboard configured.
+     */
+    settings: z.record(z.unknown()).nullish(),
+    /** Org avatar for the form header, when the form opts in. */
+    orgIcon: z.string().nullish(),
+    /** Public action previews ("submitting adds you to the list"). */
+    actions: z.array(z.record(z.unknown())).nullish(),
+    /** Non-sensitive business functions so `calculation` fields compute. */
+    businessFunctions: z.array(z.record(z.unknown())).nullish(),
+})
+    // Additive server fields reach consumers instead of being silently dropped
+    // — the failure this schema just demonstrated.
+    .passthrough();
 export const chatbotFormSubmitInputSchema = z.object({
     data: z.record(z.unknown()),
     submitterEmail: z.string().email().optional(),
     submitterName: z.string().optional(),
+    /** Validate and run the full pipeline WITHOUT persisting. */
+    dryRun: z.boolean().optional(),
+    /** Provenance the route accepts and this schema previously omitted. */
+    source: z.string().max(200).optional(),
+    referrer: z.string().max(500).optional(),
+    metadata: z.record(z.unknown()).optional(),
     priorChat: z
         .array(z.object({
         role: z.string().min(1).max(40),
@@ -441,8 +464,14 @@ export const chatbotFormSubmitInputSchema = z.object({
 });
 export const chatbotFormSubmitResponseSchema = z.object({
     success: z.literal(true),
-    submissionId: z.string(),
+    /**
+     * NULL on a dry run — the submission validated but was deliberately not
+     * persisted. Requiring a string here made every test submit throw.
+     */
+    submissionId: z.string().nullable(),
     slug: z.string(),
+    /** True when nothing was written. Pairs with a null `submissionId`. */
+    dryRun: z.boolean().optional(),
 });
 // ── Front Desk programmatic surface (Batch JJ, 0.9.0) ────────────────
 export const chatbotPersistedSessionInputSchema = z.object({
@@ -684,6 +713,36 @@ export const customerPortalProfileSchema = z
     joinedAt: timestampSchema.nullable(),
 })
     .nullable();
+/**
+ * One quiz outcome for the signed-in customer. `scoreWithheld` marks an
+ * interview-mode quiz: the attempt exists, the verdict is staff-only —
+ * render "completed" and nothing else.
+ */
+export const customerPortalQuizResultSchema = z.object({
+    invitationId: z.string(),
+    quizName: z.string(),
+    competency: z.string().nullable(),
+    status: z.string(),
+    completedAt: z.string().nullable(),
+    scoreWithheld: z.boolean(),
+    result: z
+        .object({
+        status: z.string(),
+        scorePercent: z.number().nullable(),
+        provisionalScorePercent: z.number().nullable(),
+        passed: z.boolean().nullable(),
+        pointsEarned: z.number().nullable(),
+        pointsPossible: z.number().nullable(),
+        passingScore: z.number(),
+        results: z.array(z.record(z.unknown())),
+        submittedAt: z.string().nullable(),
+        durationSeconds: z.number().nullable(),
+    })
+        .nullable(),
+});
+export const customerPortalQuizResultsResponseSchema = z.object({
+    items: z.array(customerPortalQuizResultSchema),
+});
 export const customerPortalUpdateProfileInputSchema = z.object({
     displayName: z.string().min(1).max(120).optional(),
     profile: z.record(z.unknown()).optional(),
@@ -1045,6 +1104,16 @@ export const customerReturnRequestSchema = z.object({
      * are separate enums and each is spelled as the database spells it.
      */
     status: openEnum("requested", "approved", "denied", "refunded", "cancelled"),
+    /**
+     * What was asked for: money back, or a replacement. Mirrors
+     * `order_return_request_kind`. Rows created before this existed read
+     * `refund`, which is what they were.
+     */
+    kind: openEnum("refund", "exchange"),
+    /** On an exchange: the variant wanted instead, when one was chosen. */
+    exchangeForVariantId: z.string().nullable(),
+    /** Set once a replacement ships — track it like any other shipment. */
+    exchangeShipmentId: z.string().nullable(),
     reason: z.string().nullable(),
     items: z
         .array(z.object({
@@ -1078,6 +1147,16 @@ export const customerOrderDetailSchema = z.object({
 });
 /** Input for `submitReturnRequest`. Omit `items` for a whole-order request. */
 export const customerReturnRequestInputSchema = z.object({
+    /**
+     * `refund` returns the money; `exchange` asks for a replacement. Defaults
+     * to `refund`, so an omitted field means what it always meant.
+     */
+    kind: z.enum(["refund", "exchange"]).optional(),
+    /**
+     * On an exchange, the variant wanted instead. Optional even then — "a
+     * different size" is a real request that needs a conversation first.
+     */
+    exchangeForVariantId: z.string().uuid().optional(),
     reason: z.string().max(120).optional(),
     customerNote: z.string().max(2000).optional(),
     items: z
@@ -1092,6 +1171,292 @@ export const customerReturnRequestCreatedSchema = z.object({
     id: z.string().nullable(),
     /** Mirrors the `order_return_request_status` pg enum. */
     status: openEnum("requested", "approved", "denied", "refunded", "cancelled"),
+    /** Echoes back what was opened, so a UI need not assume. */
+    kind: openEnum("refund", "exchange"),
+    createdAt: z.string().nullable(),
+});
+/**
+ * Result of reporting that a parcel never arrived.
+ *
+ * `carrierStatus` is the carrier's own verdict, UNTOUCHED by the report — the
+ * two facts travel together on purpose. When `contested` is true the carrier
+ * says delivered and the customer says otherwise, which is the case an org
+ * needs to see first.
+ */
+export const customerNotReceivedResultSchema = z.object({
+    id: z.string(),
+    /** True when a claim was already open; the original report is unchanged. */
+    alreadyOpen: z.boolean(),
+    reportedAt: z.string(),
+    carrierStatus: openEnum("pending", "label_created", "in_transit", "delivered", "returned"),
+    carrierDeliveredAt: z.string().nullable(),
+    contested: z.boolean().optional(),
+});
+/** How an org's legal pages are dressed. Shared by all of them. */
+export const legalPresentationSchema = z.object({
+    /** Already resolved against the company logo — render as given. */
+    logoUrl: z.string().nullable(),
+    showLogoInHeader: z.boolean(),
+    showLogoInFooter: z.boolean(),
+    headerHtml: z.string().nullable(),
+    footerHtml: z.string().nullable(),
+});
+/** A legal page in a list — enough for a footer, without the body. */
+export const legalDocumentSummarySchema = z.object({
+    /** The URL path, without a leading slash: `privacy`, `terms`, … */
+    slug: z.string(),
+    title: z.string(),
+    version: z.number(),
+    /** ISO 8601. Render as "Last updated". */
+    effectiveDate: z.string().nullable(),
+    showInFooter: z.boolean(),
+    updatedAt: z.string(),
+});
+export const legalListResponseSchema = z.object({
+    items: z.array(legalDocumentSummarySchema),
+    presentation: legalPresentationSchema,
+});
+/** One legal page, body included. */
+export const legalDocumentSchema = legalDocumentSummarySchema.extend({
+    /** Sanitised server-side on write, so this is safe to render as HTML. */
+    contentHtml: z.string(),
+    presentation: legalPresentationSchema,
+});
+/** One browser a customer has registered for push. */
+export const customerPushDeviceSchema = z.object({
+    id: z.string(),
+    endpoint: z.string(),
+    userAgent: z.string().nullable(),
+    label: z.string().nullable(),
+    /** Null = every category. `[]` = none, but the device stays registered. */
+    categories: z.array(z.string()).nullable(),
+    lastSeenAt: z.string().nullable(),
+    createdAt: z.string(),
+});
+/**
+ * Push config plus this customer's devices.
+ *
+ * `vapidPublicKey` rides along because a page cannot call `subscribe()` without
+ * it, and a second round trip for one string is one nobody remembers to make.
+ * `enabled: false` means the platform has no key configured — render nothing
+ * rather than a button that cannot work.
+ */
+export const customerPushConfigSchema = z.object({
+    vapidPublicKey: z.string().nullable(),
+    enabled: z.boolean(),
+    devices: z.array(customerPushDeviceSchema),
+});
+/** Result of handing a customer-portal invite link out again. */
+export const customerInviteResendResponseSchema = z.object({
+    id: z.string(),
+    /** The NEW link. The previous one no longer works. */
+    url: z.string(),
+    expiresAt: z.string().nullable(),
+    /** Includes this send, so a list can show "sent 3 times". */
+    sendCount: z.number(),
+});
+// ── Scheduling / conference calls ─────────────────────────────────────
+//
+// The booking surface: what an org offers, when it is free, and the three
+// token-gated things an invitee can do afterwards.
+//
+// `conferenceLink` is the conference-call half — a Meet/Zoom/Teams URL minted
+// when the event type has a provider. It is null until the booking is
+// confirmed, and re-minted on reschedule, so a UI must read it back after
+// either rather than caching the one it first saw.
+export const schedulingEventTypeSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    slug: z.string(),
+    description: z.string().nullable(),
+    durationMinutes: z.number(),
+    locationType: z.string(),
+    /** google_meet | zoom | teams | null when the meeting is in person. */
+    meetingProvider: z.string().nullable(),
+    color: z.string().nullable(),
+    /** When true a booking lands `pending`, not `confirmed`. */
+    requiresApproval: z.boolean(),
+});
+export const schedulingQuestionSchema = z
+    .object({
+    id: z.string(),
+    label: z.string(),
+})
+    .passthrough();
+export const schedulingEventTypeListSchema = z.object({
+    eventTypes: z.array(schedulingEventTypeSchema),
+});
+export const schedulingEventTypeDetailSchema = z.object({
+    eventType: schedulingEventTypeSchema,
+    questions: z.array(schedulingQuestionSchema),
+});
+export const schedulingSlotSchema = z.object({
+    startAt: z.string(),
+    endAt: z.string(),
+});
+export const schedulingSlotsResponseSchema = z.object({
+    slots: z.array(schedulingSlotSchema),
+});
+export const schedulingBookingStatusSchema = openEnum("pending", "confirmed", "canceled", "rescheduled");
+export const schedulingBookingViewSchema = z.object({
+    booking: z.object({
+        id: z.string(),
+        startAt: z.string(),
+        endAt: z.string(),
+        status: schedulingBookingStatusSchema,
+        title: z.string(),
+        notes: z.string().nullable(),
+        /** The conference URL, once there is one. */
+        conferenceLink: z.string().nullable(),
+    }),
+    invitee: z
+        .object({ name: z.string(), email: z.string(), timezone: z.string() })
+        .nullable(),
+});
+export const schedulingBookingResultSchema = z
+    .object({
+    bookingId: z.string(),
+    status: schedulingBookingStatusSchema,
+    /**
+     * Three separate signed tokens, deliberately.
+     *
+     * A cancel link in an email must not also be able to reschedule, and
+     * neither should read the whole booking. Handing out one token for all
+     * three would make every emailed link as powerful as the strongest
+     * action it enables.
+     */
+    manageToken: z.string(),
+    rescheduleToken: z.string(),
+    cancelToken: z.string(),
+})
+    .passthrough();
+export const schedulingRescheduleResultSchema = z
+    .object({
+    bookingId: z.string(),
+    startAt: z.string(),
+    endAt: z.string(),
+    /** Re-minted on reschedule — read it back rather than reusing the old one. */
+    conferenceLink: z.string().nullable().optional(),
+})
+    .passthrough();
+export const schedulingCancelResultSchema = z
+    .object({ ok: z.boolean() })
+    .passthrough();
+/** One of the org's live subscription offerings. */
+export const customerSubscriptionOfferingSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    description: z.string().nullable(),
+    imageUrl: z.string().nullable(),
+    amountCents: z.number(),
+    interval: z.string(),
+});
+/** The customer's subscription state with one org. */
+export const customerSubscriptionSchema = z.object({
+    /** active | expired | cancelled | pending | failed */
+    status: openEnum("active", "expired", "cancelled", "pending", "failed"),
+    /** trial | monthly_subscribed | annual_subscribed | lifetime */
+    type: openEnum("trial", "monthly_subscribed", "annual_subscribed", "lifetime").nullable(),
+    /**
+     * The entitlement decision, computed server-side by the same function the
+     * content gates use.
+     *
+     * **Render from this, not from `status`.** Two cases break a naive
+     * `status === "active"` check: a lifetime purchase has no period to expire,
+     * and a cancelled subscription keeps access until the period already paid
+     * for runs out.
+     */
+    hasAccess: z.boolean(),
+    /**
+     * Cancelled, but the paid period has not ended. The honest label is
+     * "active until {expiresAt}" — not "cancelled".
+     */
+    cancelledButActive: z.boolean(),
+    startedAt: z.string().nullable(),
+    /** End of the paid period. Null for lifetime. */
+    expiresAt: z.string().nullable(),
+    cancelledAt: z.string().nullable(),
+    renewedAt: z.string().nullable(),
+    trialEndsAt: z.string().nullable(),
+    trialUsed: z.boolean(),
+    provider: z.string().nullable(),
+    /** The offering they are on, when it still exists. */
+    plan: customerSubscriptionOfferingSchema.nullable(),
+    /** Null means the plan includes no service calls at all. */
+    includedServiceCallsPerPeriod: z.number().nullable(),
+    serviceCallsUsedInPeriod: z.number(),
+    periodStartedAt: z.string().nullable(),
+});
+export const customerSubscriptionResponseSchema = z.object({
+    /** Null when this customer has never subscribed to this org. */
+    subscription: customerSubscriptionSchema.nullable(),
+    /** The org's live offerings, cheapest first. */
+    offerings: z.array(customerSubscriptionOfferingSchema),
+});
+/** Result of cancelling — or un-cancelling — a subscription. */
+export const customerSubscriptionCancelResponseSchema = z.object({
+    /** True when a cancellation is now pending at the end of the period. */
+    cancelAtPeriodEnd: z.boolean(),
+    resumed: z.boolean(),
+    /**
+     * Access continues until this moment. Say "active until {this}", because
+     * that is what is true — cancelling ends the renewal, not the access.
+     */
+    accessUntil: z.string().nullable(),
+    /**
+     * The stored status still reads its old value until the provider's webhook
+     * lands. Render from `cancelAtPeriodEnd`, not from a re-read.
+     */
+    statusPending: z.boolean(),
+});
+/** One piece of subscriber-gated content. */
+export const customerSubscriberContentItemSchema = z.object({
+    id: z.string(),
+    slug: z.string(),
+    title: z.string(),
+    /** The pitch. Travels even when locked — the BODY never does. */
+    excerpt: z.string().nullable(),
+    featuredImageUrl: z.string().nullable(),
+    publishedAt: z.string().nullable(),
+    tags: z.array(z.string()),
+    accessLevel: z.string(),
+    downloadAccessLevel: z.string(),
+    /** False when the post is readable but its downloads are not. */
+    downloadsAvailable: z.boolean(),
+});
+export const customerSubscriberContentResponseSchema = z.object({
+    items: z.array(customerSubscriberContentItemSchema),
+    /**
+     * False means these are LOCKED previews, not an empty entitlement. Show
+     * them with the offer — an empty list would hide the pitch at exactly the
+     * moment it is most relevant.
+     */
+    entitled: z.boolean(),
+});
+/** One product review the customer has written. */
+export const customerProductReviewSchema = z.object({
+    id: z.string(),
+    productId: z.string(),
+    productName: z.string(),
+    rating: z.number(),
+    content: z.string(),
+    /**
+     * False means QUEUED for the org to approve, not rejected. Surface it as
+     * "awaiting review" — a customer who thinks their review vanished writes it
+     * again, or writes to support.
+     */
+    isApproved: z.boolean(),
+    createdAt: z.string(),
+});
+export const customerProductReviewListSchema = z.object({
+    items: z.array(customerProductReviewSchema),
+});
+/** Result of submitting a product review from the portal. */
+export const customerProductReviewCreatedSchema = z.object({
+    id: z.string().nullable(),
+    isApproved: z.boolean(),
+    /** The inverse of `isApproved`, named for what the UI should say. */
+    awaitingModeration: z.boolean(),
     createdAt: z.string().nullable(),
 });
 /** One downloadable digital deliverable for a paid order (P10d). */
@@ -1134,6 +1499,100 @@ export const siteBrandingSchema = z.object({
     orgName: z.string().nullable(),
     orgIcon: z.string().nullable(),
 });
+// ── Customer portal: list endpoints (0.9.61) ──────────────────────────
+//
+// The portal had detail-by-id routes for invoices, quotes, contracts and
+// shipments and no way to LIST any of them, so "show me everything I owe" had
+// no call behind it.
+//
+// The rows reuse the existing `customer*SummarySchema` shapes rather than
+// defining parallel ones — those already carry the right open enums, and two
+// definitions of "an invoice summary" would drift.
+export const customerInvoiceListResponseSchema = z.object({
+    items: z.array(customerInvoiceSummarySchema),
+});
+export const customerQuoteListResponseSchema = z.object({
+    items: z.array(customerQuoteSummarySchema),
+});
+export const customerContractListResponseSchema = z.object({
+    items: z.array(customerContractSummarySchema),
+});
+/** No summary shape existed for shipments, so this is the first one. */
+export const customerShipmentSummarySchema = z.object({
+    id: z.string(),
+    orderId: z.string(),
+    orderNumber: z.string().nullable(),
+    carrier: z.string().nullable(),
+    trackingNumber: z.string().nullable(),
+    trackingUrl: z.string().nullable(),
+    serviceName: z.string().nullable(),
+    status: z.string(),
+    /** A date STRING, not a timestamp — the column is text. */
+    estimatedDelivery: z.string().nullable(),
+    shippedAt: z.string().nullable(),
+    deliveredAt: z.string().nullable(),
+});
+export const customerShipmentListResponseSchema = z.object({
+    items: z.array(customerShipmentSummarySchema),
+});
+// ── Customer portal: staff chat (0.9.61) ──────────────────────────────
+//
+// `org_customer_messages` has always carried a `portal` channel and staff have
+// always read and written it from the CRM timeline. What was missing was any
+// package-api route, so a customer could be messaged and had no way to read it
+// back or reply. Both directions land in the SAME table the staff timeline
+// reads — a reply appears in the CRM beside everything else about that
+// customer, not in a parallel inbox nobody watches.
+export const customerPortalMessageSchema = z.object({
+    id: z.string(),
+    /** `inbound` = the customer wrote it; `outbound` = staff did. */
+    direction: openEnum("inbound", "outbound"),
+    channel: openEnum("portal", "email", "sms"),
+    authorName: z.string().nullable(),
+    body: z.string(),
+    attachment: z
+        .object({
+        url: z.string(),
+        name: z.string(),
+        mimeType: z.string(),
+        sizeBytes: z.number(),
+    })
+        .nullable(),
+    jobId: z.string().nullable(),
+    readByCustomerAt: z.string().nullable(),
+    createdAt: z.string(),
+});
+export const customerPortalMessageListResponseSchema = z.object({
+    items: z.array(customerPortalMessageSchema),
+});
+export const customerPortalMessagePostInputSchema = z.object({
+    body: z.string().min(1).max(4000),
+    /** Thread the message under a specific job. */
+    jobId: z.string().uuid().optional(),
+});
+export const customerPortalMessagesMarkReadResponseSchema = z.object({
+    marked: z.number(),
+});
+// ── Customer portal: return status readback (0.9.61) ──────────────────
+//
+// Closes the audit's gap #5. The submit route existed and nothing read the
+// status back, so a customer could start a return and then had no way to see
+// what happened to it — which is the exact moment they pick up the phone.
+export const customerReturnRequestStatusSchema = z.object({
+    id: z.string(),
+    /** Mirrors the `order_return_request_status` pg enum. */
+    status: openEnum("requested", "approved", "denied", "refunded", "cancelled"),
+    reason: z.string().nullable(),
+    customerNote: z.string().nullable(),
+    /** Staff's answer. The whole point when a return is denied. */
+    resolutionNote: z.string().nullable(),
+    items: z.array(z.record(z.string(), z.unknown())).nullable(),
+    resolvedAt: z.string().nullable(),
+    createdAt: z.string(),
+});
+export const customerReturnRequestListResponseSchema = z.object({
+    items: z.array(customerReturnRequestStatusSchema),
+});
 // ── Customer-portal: first-party reviews ──────────────────────────────
 export const customerReviewSummarySchema = z.object({
     id: z.string(),
@@ -1190,7 +1649,12 @@ export const customerContactCompanyResponseSchema = z.object({
 export const customerJobEtaAssignmentSchema = z.object({
     displayName: z.string(),
     role: z.string().nullable(),
-    dispatchStatus: z.string(),
+    /**
+     * This technician's own stage. `openEnum` because the column is TEXT and
+     * an org's board can grow a value before the SDK knows about it — an
+     * unknown status should render as itself, not break the response.
+     */
+    dispatchStatus: openEnum("pending", "en_route", "on_site", "in_progress", "completed", "declined"),
     lastKnownLocation: z
         .object({
         lat: z.number(),
@@ -1200,6 +1664,28 @@ export const customerJobEtaAssignmentSchema = z.object({
         .nullable(),
 });
 export const customerJobEtaResponseSchema = z.object({
+    /**
+     * Where the JOB is — promoted from the assignees by the dispatch board,
+     * NOT the same as any one technician's status.
+     *
+     * The promotion rules are why this is returned rather than left to the
+     * consumer: `en_route`/`arrived`/`started` land on the FIRST assignee to
+     * reach them, while `completed` waits for the LAST. Aggregating that
+     * client-side gets it wrong in the direction that tells a customer the work
+     * is finished when one of three techs has packed up.
+     */
+    dispatchStatus: openEnum("unscheduled", "scheduled", "en_route", "arrived", "started", "completed"),
+    /**
+     * When each stage happened. A customer reading "en route" wants to know
+     * since when — a status with no timestamp is why people phone to ask.
+     */
+    timeline: z.object({
+        scheduledStartAt: z.string().nullable(),
+        enRouteAt: z.string().nullable(),
+        arrivedAt: z.string().nullable(),
+        startedAt: z.string().nullable(),
+        completedAt: z.string().nullable(),
+    }),
     assignments: z.array(customerJobEtaAssignmentSchema),
     eta: z
         .object({
@@ -1355,6 +1841,30 @@ export const storefrontProductRowSchema = z
     /** Resolved category (name/description), when the product is categorized. */
     category: storefrontProductCategorySchema.nullable().optional(),
     images: z.array(z.string()).nullable().optional(),
+    /**
+     * Web-renderable 3D model — `.glb`, `.gltf`, `.obj` or `.stl`.
+     *
+     * All four fields below are ABSENT (not null) unless the org has the
+     * `ecommerce.product_3d` add-on. Absence is the normal case: most
+     * businesses do not sell anything with a model. Use
+     * `@businessdash/sdk/model3d` to turn these into something renderable.
+     */
+    model3dUrl: z.string().nullable().optional(),
+    /** Apple AR Quick Look companion, `.usdz`. iOS/iPadOS/visionOS Safari. */
+    model3dUsdzUrl: z.string().nullable().optional(),
+    /**
+     * True when the org attached a CAD file (`.step`/`.iges`/native).
+     *
+     * The URL itself is deliberately NOT here. CAD files are the largest
+     * thing the platform serves and are the org's intellectual property, so
+     * they are issued by `GET storefront/products/{id}/cad`, which requires
+     * cookies, rate-limits the caller and re-checks the entitlement.
+     * Publishing the raw URL in a payload any visitor can fetch would route
+     * around all three.
+     */
+    model3dCadAvailable: z.boolean().optional(),
+    /** Filename for the download link — "bracket-v3.step". */
+    model3dCadName: z.string().nullable().optional(),
     createdAt: z.string(),
 })
     .passthrough();
@@ -1362,6 +1872,61 @@ export const storefrontListProductsResponseSchema = z.object({
     items: z.array(storefrontProductRowSchema),
     nextCursor: z.number().nullable(),
 });
+/**
+ * Result of pushing the catalog to the org's own Stripe account.
+ * Per-product outcomes rather than one all-or-nothing verdict: a single bad
+ * product shouldn't abandon a batch, and the caller needs to know which.
+ */
+export const couponSchema = z.object({
+    id: z.string(),
+    code: z.string(),
+    discountType: z.string(),
+    value: z.number(),
+    isActive: z.boolean(),
+    maxUses: z.number().nullable(),
+    usedCount: z.number(),
+    validUntil: z.string().nullable(),
+    stripeCouponId: z.string().nullable(),
+    stripePromotionCodeId: z.string().nullable(),
+});
+export const couponCreateInputSchema = z.object({
+    code: z.string().min(3).max(64),
+    discountType: z.enum(["percent", "amount"]),
+    value: z.number().positive(),
+    validFrom: z.coerce.date().optional(),
+    validUntil: z.coerce.date().nullish(),
+    maxUses: z.number().int().positive().nullish(),
+    isActive: z.boolean().optional(),
+    duration: z.enum(["once", "forever", "repeating"]).optional(),
+    durationInMonths: z.number().int().positive().nullish(),
+    appliesTo: z.enum(["order", "shipping", "both"]).optional(),
+});
+/**
+ * `stripeSynced: false` means the coupon EXISTS locally but is not yet live in
+ * Stripe — reported rather than thrown, so the caller can retry the sync
+ * without re-creating the row.
+ */
+export const couponCreateResponseSchema = z.object({
+    coupon: couponSchema,
+    stripeSynced: z.boolean(),
+    stripeError: z.string().nullable(),
+});
+export const couponListResponseSchema = z.object({
+    coupons: z.array(couponSchema),
+});
+export const storefrontSyncToStripeResponseSchema = z.object({
+    synced: z.array(z.object({
+        productId: z.string(),
+        stripeProductId: z.string(),
+        /** Variant combinations that got a Stripe Price. */
+        combinationsSynced: z.number(),
+    })),
+    failed: z.array(z.object({ productId: z.string(), error: z.string() })),
+    /** Products still unsynced after this call — keep calling until 0. */
+    remaining: z.number(),
+    /** Connected account written to; null means the platform account. */
+    connectedAccountId: z.string().nullable(),
+});
 export const storefrontProductDetailSchema = storefrontProductRowSchema.and(z.object({
     variants: z.array(z.record(z.string(), z.unknown())),
     productImages: z.array(z.record(z.string(), z.unknown())),
@@ -1969,6 +2534,8 @@ const bundleCompanySchema = z.object({
 });
 const bundleGalleryItemSchema = z.object({
     id: z.string(),
+    /** Sent by the server on every item and dropped here until now. */
+    description: z.string().nullish(),
     type: z.enum(["image", "video"]),
     src: z.string(),
     width: z.number().nullable(),