@businessdash/sdk 0.9.60 → 0.9.80

package/src/contracts.ts

@@ -541,21 +541,44 @@ export const chatbotFormFieldSchema = z
 	.passthrough();
 export type ChatbotFormField = z.infer<typeof chatbotFormFieldSchema>;
 
-export const chatbotFormDefinitionSchema = z.object({
-	id: z.string(),
-	slug: z.string(),
-	name: z.string(),
-	description: z.string(),
-	fields: z.array(chatbotFormFieldSchema),
-	addsInquiry: z.boolean(),
-	addsLead: z.boolean(),
-});
+export const chatbotFormDefinitionSchema = z
+	.object({
+		id: z.string(),
+		slug: z.string(),
+		name: z.string(),
+		description: z.string(),
+		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 type ChatbotFormDefinition = z.infer<typeof chatbotFormDefinitionSchema>;
 
 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({
@@ -573,8 +596,14 @@ export type ChatbotFormSubmitInput = z.infer<
 
 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(),
 });
 export type ChatbotFormSubmitResponse = z.infer<
 	typeof chatbotFormSubmitResponseSchema
@@ -966,6 +995,44 @@ export const customerPortalProfileSchema = z
 	})
 	.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 type CustomerPortalQuizResult = z.infer<
+	typeof customerPortalQuizResultSchema
+>;
+
+export const customerPortalQuizResultsResponseSchema = z.object({
+	items: z.array(customerPortalQuizResultSchema),
+});
+export type CustomerPortalQuizResultsResponse = z.infer<
+	typeof customerPortalQuizResultsResponseSchema
+>;
+
 export const customerPortalUpdateProfileInputSchema = z.object({
 	displayName: z.string().min(1).max(120).optional(),
 	profile: z.record(z.unknown()).optional(),
@@ -1496,6 +1563,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(
@@ -1542,6 +1619,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
@@ -1559,6 +1646,372 @@ 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,
+});
+
+export type LegalPresentation = z.infer<typeof legalPresentationSchema>;
+export type LegalDocumentSummary = z.infer<typeof legalDocumentSummarySchema>;
+export type LegalListResponse = z.infer<typeof legalListResponseSchema>;
+export type LegalDocument = z.infer<typeof legalDocumentSchema>;
+
+/** 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),
+});
+
+export type CustomerPushDevice = z.infer<typeof customerPushDeviceSchema>;
+export type CustomerPushConfig = z.infer<typeof customerPushConfigSchema>;
+
+/** 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(),
+});
+
+export type CustomerInviteResendResponse = z.infer<
+	typeof customerInviteResendResponseSchema
+>;
+
+// ── 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();
+
+export type SchedulingEventTypeContract = z.infer<
+	typeof schedulingEventTypeSchema
+>;
+export type SchedulingEventTypeList = z.infer<
+	typeof schedulingEventTypeListSchema
+>;
+export type SchedulingEventTypeDetail = z.infer<
+	typeof schedulingEventTypeDetailSchema
+>;
+export type SchedulingSlotsResponse = z.infer<
+	typeof schedulingSlotsResponseSchema
+>;
+export type SchedulingBookingView = z.infer<typeof schedulingBookingViewSchema>;
+export type SchedulingBookingResult = z.infer<
+	typeof schedulingBookingResultSchema
+>;
+export type SchedulingRescheduleResult = z.infer<
+	typeof schedulingRescheduleResultSchema
+>;
+export type SchedulingCancelResult = z.infer<
+	typeof schedulingCancelResultSchema
+>;
+
+/** 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(),
 });
 
@@ -1615,6 +2068,32 @@ export type CustomerReturnRequestInput = z.infer<
 export type CustomerReturnRequestCreated = z.infer<
 	typeof customerReturnRequestCreatedSchema
 >;
+export type CustomerNotReceivedResult = z.infer<
+	typeof customerNotReceivedResultSchema
+>;
+export type CustomerProductReview = z.infer<typeof customerProductReviewSchema>;
+export type CustomerProductReviewList = z.infer<
+	typeof customerProductReviewListSchema
+>;
+export type CustomerProductReviewCreated = z.infer<
+	typeof customerProductReviewCreatedSchema
+>;
+export type CustomerSubscriptionOffering = z.infer<
+	typeof customerSubscriptionOfferingSchema
+>;
+export type CustomerSubscription = z.infer<typeof customerSubscriptionSchema>;
+export type CustomerSubscriptionResponse = z.infer<
+	typeof customerSubscriptionResponseSchema
+>;
+export type CustomerSubscriptionCancelResponse = z.infer<
+	typeof customerSubscriptionCancelResponseSchema
+>;
+export type CustomerSubscriberContentItem = z.infer<
+	typeof customerSubscriberContentItemSchema
+>;
+export type CustomerSubscriberContentResponse = z.infer<
+	typeof customerSubscriberContentResponseSchema
+>;
 export type CustomerDownload = z.infer<typeof customerDownloadSchema>;
 export type CustomerDownloadsResponse = z.infer<
 	typeof customerDownloadsResponseSchema
@@ -1646,6 +2125,148 @@ export type CustomerInvoicePayment = z.infer<
 export type CustomerPaymentHistoryEntry = z.infer<
 	typeof customerPaymentHistoryEntrySchema
 >;
+// ── 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),
+});
+
+export type CustomerInvoiceListResponse = z.infer<
+	typeof customerInvoiceListResponseSchema
+>;
+export type CustomerQuoteListResponse = z.infer<
+	typeof customerQuoteListResponseSchema
+>;
+export type CustomerContractListResponse = z.infer<
+	typeof customerContractListResponseSchema
+>;
+export type CustomerShipmentSummary = z.infer<
+	typeof customerShipmentSummarySchema
+>;
+export type CustomerShipmentListResponse = z.infer<
+	typeof customerShipmentListResponseSchema
+>;
+
+// ── 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(),
+});
+
+export type CustomerPortalMessage = z.infer<typeof customerPortalMessageSchema>;
+export type CustomerPortalMessageListResponse = z.infer<
+	typeof customerPortalMessageListResponseSchema
+>;
+export type CustomerPortalMessagePostInput = z.infer<
+	typeof customerPortalMessagePostInputSchema
+>;
+export type CustomerPortalMessagesMarkReadResponse = z.infer<
+	typeof customerPortalMessagesMarkReadResponseSchema
+>;
+
+// ── 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),
+});
+
+export type CustomerReturnRequestStatus = z.infer<
+	typeof customerReturnRequestStatusSchema
+>;
+export type CustomerReturnRequestListResponse = z.infer<
+	typeof customerReturnRequestListResponseSchema
+>;
+
 export type CustomerPaymentHistoryResponse = z.infer<
 	typeof customerPaymentHistoryResponseSchema
 >;
@@ -1752,7 +2373,19 @@ export type CustomerContactCompanyResponse = z.infer<
 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(),
@@ -1763,6 +2396,35 @@ export const customerJobEtaAssignmentSchema = z.object({
 });
 
 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({
@@ -1973,6 +2635,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();
@@ -1982,6 +2668,75 @@ export const storefrontListProductsResponseSchema = z.object({
 	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 type Coupon = z.infer<typeof couponSchema>;
+
+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(),
+});
+export type CouponCreateInput = z.input<typeof couponCreateInputSchema>;
+
+/**
+ * `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 type CouponCreateResponse = z.infer<typeof couponCreateResponseSchema>;
+
+export const couponListResponseSchema = z.object({
+	coupons: z.array(couponSchema),
+});
+export type CouponListResponse = z.infer<typeof couponListResponseSchema>;
+
+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 type StorefrontSyncToStripeResponse = z.infer<
+	typeof storefrontSyncToStripeResponseSchema
+>;
+
 export const storefrontProductDetailSchema = storefrontProductRowSchema.and(
 	z.object({
 		variants: z.array(z.record(z.string(), z.unknown())),
@@ -2799,6 +3554,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(),