@businessdash/sdk 0.9.60 → 0.9.70

package/src/portal-core/index.ts

@@ -0,0 +1,1564 @@
+/**
+ * `@businessdash/sdk/portal` — the headless customer-portal controller.
+ *
+ * The portal is the largest surface in the SDK: 34 methods covering work,
+ * quotes, contracts, invoices, orders, downloads, shipping, reviews, referrals,
+ * profile and notification preferences. Until now the only way to render it was
+ * `<Dashboard>`, a BusinessDash-hosted page in an iframe — so a business could
+ * not put their own customer portal on their own domain in their own design.
+ *
+ * This is the native path. Four things about the surface shape the design, and
+ * all of them come from the audit in `Resources/BIAB-Customer-Portal-SDK-Audit.md`.
+ *
+ * ## 1. The session is not optional
+ *
+ * Every portal route requires a signed-in session token AND the scope
+ * `customer_portal:self`. Without `withSession` the client has no identity and
+ * every call is unauthenticated — which fails, but quietly enough to look like
+ * an empty portal. So the token is a REQUIRED constructor argument and the
+ * controller calls `withSession` itself. A consumer cannot forget it.
+ *
+ * ## 2. There are no list endpoints, except orders and payments
+ *
+ * Invoices, quotes, contracts and shipments have detail-by-id routes only.
+ * `getWork()` returns a summary — open job count, unpaid balance — so a portal
+ * can render counts, but "show me all my unpaid invoices" has no single call.
+ * This controller does NOT paper over that with a fake list built from
+ * repeated detail fetches: it exposes what exists, and the gap stays visible
+ * where someone can decide to close it in the API.
+ *
+ * ## 3. Nothing can be deleted
+ *
+ * Every write is a create or an edit. There is deliberately no delete action
+ * anywhere in this controller, because there is none in the API.
+ *
+ * ## 4. Reviews are moderated, not published
+ *
+ * `submitReview` lands `status: "pending"` for staff approval. The controller
+ * does NOT add the new review to `reviews` — showing it back immediately would
+ * tell the author their review is live when the public cannot see it.
+ *
+ * @module
+ */
+
+import type {
+	CustomerContactCompanyInput,
+	CustomerContactCompanyResponse,
+	CustomerContractDetail,
+	CustomerContractListResponse,
+	CustomerContractSignResponse,
+	CustomerDownloadsResponse,
+	CustomerInvoiceDetail,
+	CustomerInvoiceListResponse,
+	CustomerInvoicePayInput,
+	CustomerInvoicePayResponse,
+	CustomerJobActivityResponse,
+	CustomerJobComment,
+	CustomerJobCommentPostInput,
+	CustomerJobCommentsListResponse,
+	CustomerJobDetail,
+	CustomerJobEtaResponse,
+	CustomerNotReceivedResult,
+	CustomerOrderDetail,
+	CustomerOrderListResponse,
+	CustomerPaymentHistoryResponse,
+	CustomerPortalContextResponse,
+	CustomerPortalMessage,
+	CustomerPortalMessageListResponse,
+	CustomerPortalMessagePostInput,
+	CustomerPortalOtherOrgsResponse,
+	CustomerPortalProfile,
+	CustomerPortalUpdateProfileInput,
+	CustomerProductReviewCreated,
+	CustomerProductReviewList,
+	CustomerPushConfig,
+	CustomerQuoteActionResponse,
+	CustomerQuoteDetail,
+	CustomerQuoteListResponse,
+	CustomerReferralHistoryResponse,
+	CustomerReferralPayoutsResponse,
+	CustomerReferralStats,
+	CustomerReturnRequestCreated,
+	CustomerReturnRequestInput,
+	CustomerReturnRequestListResponse,
+	CustomerReviewListResponse,
+	CustomerReviewSubmitInput,
+	CustomerShipmentListResponse,
+	CustomerShipmentTracking,
+	CustomerSubscriberContentResponse,
+	CustomerSubscriptionCancelResponse,
+	CustomerSubscriptionResponse,
+	CustomerWorkBundle,
+	NotificationPreferencesResponse,
+	NotificationPreferencesUpdateInput,
+} from "../contracts.js";
+import {
+	currentPushSubscription,
+	pushSupport,
+	subscribeToPush,
+	unsubscribeFromPush,
+} from "../push-core/index.js";
+
+/** The portal client, after `withSession` has bound an identity to it. */
+export type PortalSessionClient = {
+	context(): Promise<CustomerPortalContextResponse>;
+	getProfile(): Promise<CustomerPortalProfile>;
+	updateProfile(input: CustomerPortalUpdateProfileInput): Promise<unknown>;
+	myOtherCustomerOrgs(): Promise<CustomerPortalOtherOrgsResponse>;
+	getPushConfig(): Promise<CustomerPushConfig>;
+	subscribePush(input: {
+		endpoint: string;
+		p256dh: string;
+		auth: string;
+		userAgent?: string | null;
+		label?: string | null;
+		categories?: string[] | null;
+	}): Promise<{ id: string; created: boolean }>;
+	updatePushDevice(input: {
+		id: string;
+		label?: string | null;
+		categories?: string[] | null;
+	}): Promise<{ ok: boolean }>;
+	unsubscribePush(input: {
+		id?: string;
+		endpoint?: string;
+	}): Promise<{ ok: boolean; deletedId: string | null }>;
+	getNotificationPreferences(): Promise<NotificationPreferencesResponse>;
+	updateNotificationPreferences(
+		input: NotificationPreferencesUpdateInput,
+	): Promise<NotificationPreferencesResponse>;
+	getWork(): Promise<CustomerWorkBundle>;
+	getJob(jobId: string): Promise<CustomerJobDetail>;
+	getJobActivity(jobId: string): Promise<CustomerJobActivityResponse>;
+	getJobEta(jobId: string): Promise<CustomerJobEtaResponse>;
+	listJobComments(jobId: string): Promise<CustomerJobCommentsListResponse>;
+	postJobComment(
+		jobId: string,
+		input: CustomerJobCommentPostInput,
+	): Promise<CustomerJobComment>;
+	getQuote(quoteId: string): Promise<CustomerQuoteDetail>;
+	viewQuote(quoteId: string): Promise<CustomerQuoteDetail>;
+	acceptQuote(quoteId: string): Promise<CustomerQuoteActionResponse>;
+	rejectQuote(quoteId: string): Promise<CustomerQuoteActionResponse>;
+	getInvoice(invoiceId: string): Promise<CustomerInvoiceDetail>;
+	payInvoice(
+		invoiceId: string,
+		opts?: CustomerInvoicePayInput,
+	): Promise<CustomerInvoicePayResponse>;
+	getContract(contractId: string): Promise<CustomerContractDetail>;
+	signContract(contractId: string): Promise<CustomerContractSignResponse>;
+	listMyReviews(): Promise<CustomerReviewListResponse>;
+	submitReview(input: CustomerReviewSubmitInput): Promise<unknown>;
+	listOrders(opts?: { limit?: number }): Promise<CustomerOrderListResponse>;
+	listMessages(opts?: {
+		limit?: number;
+		jobId?: string;
+	}): Promise<CustomerPortalMessageListResponse>;
+	postMessage(
+		input: CustomerPortalMessagePostInput,
+	): Promise<CustomerPortalMessage>;
+	markMessagesRead(): Promise<{ marked: number }>;
+	listReturnRequests(
+		orderId: string,
+	): Promise<CustomerReturnRequestListResponse>;
+	listInvoices(opts?: {
+		limit?: number;
+		status?: string;
+		unpaid?: boolean;
+	}): Promise<CustomerInvoiceListResponse>;
+	listQuotes(opts?: {
+		limit?: number;
+		status?: string;
+	}): Promise<CustomerQuoteListResponse>;
+	listContracts(opts?: {
+		limit?: number;
+		status?: string;
+	}): Promise<CustomerContractListResponse>;
+	listShipments(opts?: {
+		limit?: number;
+		active?: boolean;
+	}): Promise<CustomerShipmentListResponse>;
+	getOrder(orderId: string): Promise<CustomerOrderDetail>;
+	getDownloads(orderId: string): Promise<CustomerDownloadsResponse>;
+	listPayments(opts?: {
+		limit?: number;
+	}): Promise<CustomerPaymentHistoryResponse>;
+	trackShipment(shipmentId: string): Promise<CustomerShipmentTracking>;
+	submitExchangeRequest(
+		orderId: string,
+		input?: Omit<CustomerReturnRequestInput, "kind">,
+	): Promise<unknown>;
+	reportNotReceived(
+		shipmentId: string,
+		input?: { note?: string },
+	): Promise<CustomerNotReceivedResult>;
+	listProductReviews(): Promise<CustomerProductReviewList>;
+	getDispatchStatus(jobId: string): Promise<CustomerJobEtaResponse>;
+	getSubscription(): Promise<CustomerSubscriptionResponse>;
+	cancelSubscription(): Promise<CustomerSubscriptionCancelResponse>;
+	resumeSubscription(): Promise<CustomerSubscriptionCancelResponse>;
+	getSubscriberContent(opts?: {
+		limit?: number;
+	}): Promise<CustomerSubscriberContentResponse>;
+	submitProductReview(input: {
+		productId: string;
+		rating: number;
+		content: string;
+	}): Promise<CustomerProductReviewCreated>;
+	submitReturnRequest(
+		orderId: string,
+		input?: CustomerReturnRequestInput,
+	): Promise<CustomerReturnRequestCreated>;
+	contactCompany(
+		input: CustomerContactCompanyInput,
+	): Promise<CustomerContactCompanyResponse>;
+	myReferralStats(): Promise<CustomerReferralStats>;
+	myReferralHistory(opts?: {
+		limit?: number;
+	}): Promise<CustomerReferralHistoryResponse>;
+	myReferralPayouts(): Promise<CustomerReferralPayoutsResponse>;
+};
+
+export type PortalCoreClient = {
+	/**
+	 * `organizationId` pins every request to that org.
+	 *
+	 * Optional, and omitting it keeps the API key's own org — which is what the
+	 * controller does by default. It exists because a customer can belong to
+	 * SEVERAL orgs, and notification preferences are stored per
+	 * (org, user): editing them for org B from a controller pinned to org A is
+	 * otherwise impossible, so a customer could see their other orgs and change
+	 * nothing about them.
+	 */
+	customerPortal(organizationId?: string): {
+		withSession(sessionToken: string): PortalSessionClient;
+	};
+};
+
+export type PortalStatus = "idle" | "loading" | "ready" | "error";
+
+/**
+ * What the portal renders. Collections that the API can actually list live at
+ * the top; everything else is a detail slot filled by an `open*` action,
+ * because the API has no list route for it.
+ */
+export type PortalSnapshot = {
+	status: PortalStatus;
+
+	/** Session + branding, from `context()`. */
+	context: CustomerPortalContextResponse | null;
+	profile: CustomerPortalProfile | null;
+	/** Summary counts — open jobs, unpaid balance — not a list of invoices. */
+	work: CustomerWorkBundle | null;
+	/**
+	 * Push devices, and the key needed to register a new one.
+	 *
+	 * Not per-org, unlike everything beside it: a push subscription identifies a
+	 * BROWSER, and a customer of three orgs has one browser. Which org may push
+	 * to it lives in that org's `notificationPreferences` instead — so muting
+	 * one company here would be the wrong lever, and is not offered.
+	 */
+	push: CustomerPushConfig | null;
+	notificationPreferences: NotificationPreferencesResponse | null;
+	/**
+	 * Preferences for OTHER orgs this customer belongs to, keyed by org id.
+	 *
+	 * Separate from `notificationPreferences` (this org's) so a dashboard can
+	 * render the current org without waiting on, or failing because of, orgs
+	 * the customer has not expanded yet.
+	 */
+	notificationPreferencesByOrg: Record<string, NotificationPreferencesResponse>;
+	otherOrgs: CustomerPortalOtherOrgsResponse | null;
+
+	/**
+	 * The listable collections.
+	 *
+	 * Invoices, quotes, contracts and shipments joined this set in 0.9.61. Before
+	 * that they were detail-by-id only, and `work` carried the counts with no way
+	 * to enumerate what made them up.
+	 */
+	orders: CustomerOrderListResponse | null;
+	payments: CustomerPaymentHistoryResponse | null;
+	reviews: CustomerReviewListResponse | null;
+	invoices: CustomerInvoiceListResponse | null;
+	quotes: CustomerQuoteListResponse | null;
+	contracts: CustomerContractListResponse | null;
+	shipments: CustomerShipmentListResponse | null;
+
+	/**
+	 * The staff chat thread. Empty until `loadMessages()` — opening a thread
+	 * nobody asked for spends a request on every page load.
+	 */
+	messages: CustomerPortalMessageListResponse | null;
+	/** Staff messages not yet marked read. Drives an unread badge. */
+	unreadMessageCount: number;
+	/** Return requests on the OPEN order. Cleared with the rest of the detail. */
+	returnRequests: CustomerReturnRequestListResponse | null;
+	/** The customer's own product reviews. Null until `loadProductReviews`. */
+	productReviews: CustomerProductReviewList | null;
+	/**
+	 * The subscription with this org, plus the org's offerings. Null until
+	 * `loadSubscription`.
+	 *
+	 * Render entitlement from `subscription.subscription?.hasAccess`, never
+	 * from `status` — a lifetime purchase never expires and a cancelled
+	 * subscription keeps access until the paid period ends.
+	 */
+	subscription: CustomerSubscriptionResponse | null;
+	/**
+	 * Subscriber content. When `entitled` is false these are LOCKED previews,
+	 * not an empty entitlement — show them beside the offer.
+	 */
+	subscriberContent: CustomerSubscriberContentResponse | null;
+	/**
+	 * Set after `submitProductReview` succeeds while the org holds it for
+	 * approval. Render "awaiting review" — silence reads as a lost review.
+	 */
+	productReviewAwaitingModeration: boolean;
+	/**
+	 * The last `reportNotReceived` result. `contested` means the carrier says
+	 * delivered and the customer says otherwise — worth saying out loud, since
+	 * that is the case that needs a carrier claim rather than a reship.
+	 */
+	lastNotReceived: CustomerNotReceivedResult | null;
+
+	referrals: {
+		stats: CustomerReferralStats | null;
+		history: CustomerReferralHistoryResponse | null;
+		payouts: CustomerReferralPayoutsResponse | null;
+	};
+
+	/** Detail slots — one at a time, filled by `open*`. */
+	activeJob: CustomerJobDetail | null;
+	jobActivity: CustomerJobActivityResponse | null;
+	jobEta: CustomerJobEtaResponse | null;
+	jobComments: CustomerJobCommentsListResponse | null;
+	activeOrder: CustomerOrderDetail | null;
+	orderDownloads: CustomerDownloadsResponse | null;
+	activeInvoice: CustomerInvoiceDetail | null;
+	activeQuote: CustomerQuoteDetail | null;
+	activeContract: CustomerContractDetail | null;
+	shipmentTracking: CustomerShipmentTracking | null;
+
+	/**
+	 * Set after `submitReview` succeeds. The review is queued for staff
+	 * approval and is NOT in `reviews` — surfacing this lets a portal say
+	 * "thanks, it's awaiting review" rather than implying it is live.
+	 */
+	reviewAwaitingModeration: boolean;
+
+	error: Error | null;
+	pending: {
+		overview: boolean;
+		orders: boolean;
+		payments: boolean;
+		reviews: boolean;
+		referrals: boolean;
+		detail: boolean;
+		action: boolean;
+	};
+};
+
+/**
+ * What happened when a page asked to turn push on.
+ *
+ * A discriminated union rather than a boolean because the ways this fails are
+ * not interchangeable: `denied` cannot be retried without the visitor digging
+ * through site settings, `dismissed` can be asked again tomorrow, and
+ * `ios-needs-home-screen` is fixed by the visitor in ten seconds if anyone
+ * tells them how. One boolean collapses all three into "didn't work".
+ */
+export type PushEnableResult =
+	| { ok: true; deviceId: string }
+	| {
+			ok: false;
+			reason:
+				| "unsupported"
+				| "ios-needs-home-screen"
+				| "insecure-context"
+				| "denied"
+				| "dismissed"
+				| "not-configured"
+				| "failed";
+			message: string;
+	  };
+
+export type PortalController = {
+	snapshot(): PortalSnapshot;
+	subscribe(callback: (snapshot: PortalSnapshot) => void): () => void;
+
+	/** Context, profile and the work summary — the portal landing state. */
+	load(): Promise<void>;
+	loadOrders(opts?: { limit?: number }): Promise<void>;
+	/** `unpaid: true` is the "everything I owe" view. */
+	loadInvoices(opts?: {
+		limit?: number;
+		status?: string;
+		unpaid?: boolean;
+	}): Promise<void>;
+	loadQuotes(opts?: { limit?: number; status?: string }): Promise<void>;
+	loadContracts(opts?: { limit?: number; status?: string }): Promise<void>;
+	/** `active: true` narrows to parcels still moving. Stored status only. */
+	loadShipments(opts?: { limit?: number; active?: boolean }): Promise<void>;
+	/** The staff chat thread. `jobId` narrows it to one job's conversation. */
+	loadMessages(opts?: { limit?: number; jobId?: string }): Promise<void>;
+	/** Send a message to staff. The thread is re-read afterwards. */
+	postMessage(input: CustomerPortalMessagePostInput): Promise<boolean>;
+	/** Mark staff messages read. One-way — it never un-reads. */
+	markMessagesRead(): Promise<void>;
+	loadPayments(opts?: { limit?: number }): Promise<void>;
+	loadReviews(): Promise<void>;
+	loadReferrals(): Promise<void>;
+	/** Push config plus this browser's registration state. */
+	loadPushConfig(): Promise<void>;
+	/**
+	 * Turn push on for THIS browser, end to end.
+	 *
+	 * Reads the key, registers the service worker, asks permission and records
+	 * the subscription — the whole dance behind one call, because every step of
+	 * it is plumbing and none of it is a design decision the consumer wants.
+	 *
+	 * **Call it from a click.** Permission is asked once per origin and a
+	 * refusal is sticky, so a page that prompts on load spends the only chance
+	 * it gets on someone who has not yet been told what they are agreeing to.
+	 *
+	 * The failure cases are returned rather than thrown, because they are not
+	 * errors so much as answers — "blocked", "add to Home Screen first" — and
+	 * each deserves different copy.
+	 */
+	enablePush(options?: {
+		serviceWorkerPath?: string;
+		scope?: string;
+		label?: string;
+	}): Promise<PushEnableResult>;
+	/**
+	 * Turn push off for this browser: tears the local subscription down AND
+	 * forgets the row, so nothing is left pushing into a dead endpoint.
+	 */
+	disablePush(): Promise<boolean>;
+	/** Rename a device, or narrow what it receives. */
+	updatePushDevice(input: {
+		id: string;
+		label?: string | null;
+		categories?: string[] | null;
+	}): Promise<boolean>;
+	/** Forget one device by id — for revoking a browser you no longer have. */
+	forgetPushDevice(id: string): Promise<boolean>;
+	loadNotificationPreferences(): Promise<void>;
+	/**
+	 * Load notification preferences for ANOTHER org this customer belongs to.
+	 * Pass an org id from `snapshot().otherOrgs`.
+	 */
+	loadNotificationPreferencesFor(orgId: string): Promise<void>;
+	loadOtherOrgs(): Promise<void>;
+
+	/** Job detail plus its activity, ETA and comments, in one call. */
+	openJob(jobId: string): Promise<void>;
+	openOrder(orderId: string): Promise<void>;
+	openInvoice(invoiceId: string): Promise<void>;
+	/** Fetches the quote and marks it viewed, which the org can see. */
+	openQuote(quoteId: string): Promise<void>;
+	openContract(contractId: string): Promise<void>;
+	trackShipment(shipmentId: string): Promise<void>;
+	/** Clear every detail slot. */
+	closeDetail(): void;
+
+	postJobComment(
+		jobId: string,
+		input: CustomerJobCommentPostInput,
+	): Promise<boolean>;
+	acceptQuote(quoteId: string): Promise<boolean>;
+	rejectQuote(quoteId: string): Promise<boolean>;
+	signContract(contractId: string): Promise<boolean>;
+	payInvoice(
+		invoiceId: string,
+		opts?: CustomerInvoicePayInput,
+	): Promise<CustomerInvoicePayResponse | null>;
+	updateProfile(input: CustomerPortalUpdateProfileInput): Promise<boolean>;
+	updateNotificationPreferences(
+		input: NotificationPreferencesUpdateInput,
+	): Promise<boolean>;
+	/** Update preferences for another of the customer's orgs. */
+	updateNotificationPreferencesFor(
+		orgId: string,
+		input: NotificationPreferencesUpdateInput,
+	): Promise<boolean>;
+	/** Queues a review for staff approval. It will NOT appear in `reviews`. */
+	submitReview(input: CustomerReviewSubmitInput): Promise<boolean>;
+	submitReturnRequest(
+		orderId: string,
+		input?: CustomerReturnRequestInput,
+	): Promise<CustomerReturnRequestCreated | null>;
+	/** Ask for a replacement instead of money back. */
+	submitExchangeRequest(
+		orderId: string,
+		input?: Omit<CustomerReturnRequestInput, "kind">,
+	): Promise<CustomerReturnRequestCreated | null>;
+	/**
+	 * Report a parcel as never arrived. Does NOT change carrier status — the
+	 * result carries both the claim and the carrier's own verdict.
+	 */
+	reportNotReceived(
+		shipmentId: string,
+		input?: { note?: string },
+	): Promise<CustomerNotReceivedResult | null>;
+	loadProductReviews(): Promise<void>;
+	/**
+	 * Dispatch status for a job the customer owns.
+	 *
+	 * Lands in `snapshot().jobEta`, which is the same surface `openJob` fills —
+	 * one place for "where is my technician", not two that can disagree.
+	 */
+	loadDispatchStatus(jobId: string): Promise<void>;
+	loadSubscription(): Promise<void>;
+	loadSubscriberContent(opts?: { limit?: number }): Promise<void>;
+	/** Ends the RENEWAL. Access continues until the paid period ends. */
+	cancelSubscription(): Promise<CustomerSubscriptionCancelResponse | null>;
+	/** Clears a pending cancellation. */
+	resumeSubscription(): Promise<CustomerSubscriptionCancelResponse | null>;
+	/** Verified-buyer review. Queued when the org moderates. */
+	submitProductReview(input: {
+		productId: string;
+		rating: number;
+		content: string;
+	}): Promise<boolean>;
+	contactCompany(
+		input: CustomerContactCompanyInput,
+	): Promise<CustomerContactCompanyResponse | null>;
+
+	destroy(): void;
+};
+
+export type CreatePortalControllerOptions = {
+	client: PortalCoreClient;
+	/**
+	 * The signed-in customer's session token. REQUIRED — every portal route
+	 * needs it, and a portal built without one renders as empty rather than as
+	 * signed-out.
+	 */
+	sessionToken: string;
+	onError?: (error: Error) => void;
+};
+
+function toError(cause: unknown, fallback: string): Error {
+	return cause instanceof Error ? cause : new Error(fallback);
+}
+
+export function createPortalController(
+	options: CreatePortalControllerOptions,
+): PortalController {
+	const { onError } = options;
+	if (!options.sessionToken) {
+		throw new Error(
+			"createPortalController requires a `sessionToken`. Every customer-portal route is scoped to the signed-in customer; without one every call is unauthenticated and the portal renders empty rather than signed-out.",
+		);
+	}
+	const portal = options.client
+		.customerPortal()
+		.withSession(options.sessionToken);
+
+	/**
+	 * A portal client pinned to another of the customer's orgs.
+	 *
+	 * Memoised because a dashboard listing five companies would otherwise build
+	 * a client per render. The session token is the same — it identifies the
+	 * PERSON; the org id only says which tenant's data to read, and the server
+	 * still checks they belong to it.
+	 */
+	const orgClients = new Map<string, PortalSessionClient>();
+	const portalFor = (orgId: string): PortalSessionClient => {
+		let pinned = orgClients.get(orgId);
+		if (!pinned) {
+			pinned = options.client
+				.customerPortal(orgId)
+				.withSession(options.sessionToken);
+			orgClients.set(orgId, pinned);
+		}
+		return pinned;
+	};
+
+	let destroyed = false;
+	/** Guards a slow detail fetch landing after the customer navigated on. */
+	let detailToken = 0;
+	const subscribers = new Set<(s: PortalSnapshot) => void>();
+
+	const state: {
+		status: PortalStatus;
+		context: CustomerPortalContextResponse | null;
+		profile: CustomerPortalProfile | null;
+		work: CustomerWorkBundle | null;
+		push: CustomerPushConfig | null;
+		notificationPreferences: NotificationPreferencesResponse | null;
+		notificationPreferencesByOrg: Record<
+			string,
+			NotificationPreferencesResponse
+		>;
+		otherOrgs: CustomerPortalOtherOrgsResponse | null;
+		orders: CustomerOrderListResponse | null;
+		payments: CustomerPaymentHistoryResponse | null;
+		reviews: CustomerReviewListResponse | null;
+		invoices: CustomerInvoiceListResponse | null;
+		quotes: CustomerQuoteListResponse | null;
+		contracts: CustomerContractListResponse | null;
+		shipments: CustomerShipmentListResponse | null;
+		messages: CustomerPortalMessageListResponse | null;
+		returnRequests: CustomerReturnRequestListResponse | null;
+		productReviews: CustomerProductReviewList | null;
+		subscription: CustomerSubscriptionResponse | null;
+		subscriberContent: CustomerSubscriberContentResponse | null;
+		productReviewAwaitingModeration: boolean;
+		lastNotReceived: CustomerNotReceivedResult | null;
+		referrals: PortalSnapshot["referrals"];
+		activeJob: CustomerJobDetail | null;
+		jobActivity: CustomerJobActivityResponse | null;
+		jobEta: CustomerJobEtaResponse | null;
+		jobComments: CustomerJobCommentsListResponse | null;
+		activeOrder: CustomerOrderDetail | null;
+		orderDownloads: CustomerDownloadsResponse | null;
+		activeInvoice: CustomerInvoiceDetail | null;
+		activeQuote: CustomerQuoteDetail | null;
+		activeContract: CustomerContractDetail | null;
+		shipmentTracking: CustomerShipmentTracking | null;
+		reviewAwaitingModeration: boolean;
+		error: Error | null;
+		pending: PortalSnapshot["pending"];
+	} = {
+		status: "idle",
+		context: null,
+		profile: null,
+		work: null,
+		push: null,
+		notificationPreferences: null,
+		notificationPreferencesByOrg: {},
+		otherOrgs: null,
+		orders: null,
+		payments: null,
+		reviews: null,
+		invoices: null,
+		quotes: null,
+		contracts: null,
+		shipments: null,
+		messages: null,
+		returnRequests: null,
+		productReviews: null,
+		subscription: null,
+		subscriberContent: null,
+		productReviewAwaitingModeration: false,
+		lastNotReceived: null,
+		referrals: { stats: null, history: null, payouts: null },
+		activeJob: null,
+		jobActivity: null,
+		jobEta: null,
+		jobComments: null,
+		activeOrder: null,
+		orderDownloads: null,
+		activeInvoice: null,
+		activeQuote: null,
+		activeContract: null,
+		shipmentTracking: null,
+		reviewAwaitingModeration: false,
+		error: null,
+		pending: {
+			overview: false,
+			orders: false,
+			payments: false,
+			reviews: false,
+			referrals: false,
+			detail: false,
+			action: false,
+		},
+	};
+
+	let cached: PortalSnapshot | null = null;
+
+	function snapshot(): PortalSnapshot {
+		if (!cached) {
+			cached = {
+				status: state.status,
+				context: state.context,
+				profile: state.profile,
+				work: state.work,
+				push: state.push,
+				notificationPreferences: state.notificationPreferences,
+				notificationPreferencesByOrg: state.notificationPreferencesByOrg,
+				otherOrgs: state.otherOrgs,
+				orders: state.orders,
+				payments: state.payments,
+				reviews: state.reviews,
+				invoices: state.invoices,
+				quotes: state.quotes,
+				contracts: state.contracts,
+				shipments: state.shipments,
+				messages: state.messages,
+				returnRequests: state.returnRequests,
+				productReviews: state.productReviews,
+				subscription: state.subscription,
+				subscriberContent: state.subscriberContent,
+				productReviewAwaitingModeration: state.productReviewAwaitingModeration,
+				lastNotReceived: state.lastNotReceived,
+				unreadMessageCount: (state.messages?.items ?? []).filter(
+					(m) => m.direction === "outbound" && m.readByCustomerAt === null,
+				).length,
+				referrals: state.referrals,
+				activeJob: state.activeJob,
+				jobActivity: state.jobActivity,
+				jobEta: state.jobEta,
+				jobComments: state.jobComments,
+				activeOrder: state.activeOrder,
+				orderDownloads: state.orderDownloads,
+				activeInvoice: state.activeInvoice,
+				activeQuote: state.activeQuote,
+				activeContract: state.activeContract,
+				shipmentTracking: state.shipmentTracking,
+				reviewAwaitingModeration: state.reviewAwaitingModeration,
+				error: state.error,
+				pending: state.pending,
+			};
+		}
+		return cached;
+	}
+
+	function notify(): void {
+		if (destroyed) return;
+		cached = null;
+		const next = snapshot();
+		for (const cb of subscribers) cb(next);
+	}
+
+	function fail(cause: unknown, fallback: string): void {
+		const error = toError(cause, fallback);
+		state.error = error;
+		if (state.status !== "ready") state.status = "error";
+		onError?.(error);
+	}
+
+	/** Run a read that fills one slice of the snapshot. */
+	async function read(
+		key: keyof PortalSnapshot["pending"],
+		work: () => Promise<void>,
+		fallback: string,
+	): Promise<void> {
+		if (destroyed) return;
+		state.pending[key] = true;
+		notify();
+		try {
+			await work();
+			if (!destroyed) state.status = "ready";
+		} catch (cause) {
+			if (!destroyed) fail(cause, fallback);
+		} finally {
+			if (!destroyed) {
+				state.pending[key] = false;
+				notify();
+			}
+		}
+	}
+
+	/** Run a write. Returns false rather than throwing, so a form can branch. */
+	async function act<T>(
+		work: () => Promise<T>,
+		fallback: string,
+		after?: (result: T) => void,
+	): Promise<T | null> {
+		if (destroyed) return null;
+		state.pending.action = true;
+		state.error = null;
+		notify();
+		try {
+			const result = await work();
+			if (destroyed) return null;
+			after?.(result);
+			return result;
+		} catch (cause) {
+			if (!destroyed) fail(cause, fallback);
+			return null;
+		} finally {
+			if (!destroyed) {
+				state.pending.action = false;
+				notify();
+			}
+		}
+	}
+
+	/** Fill a detail slot, dropping the result if the customer moved on. */
+	async function detail(
+		work: (token: number) => Promise<void>,
+		fallback: string,
+	): Promise<void> {
+		if (destroyed) return;
+		const token = ++detailToken;
+		state.pending.detail = true;
+		state.error = null;
+		notify();
+		try {
+			await work(token);
+		} catch (cause) {
+			if (!destroyed && token === detailToken) fail(cause, fallback);
+		} finally {
+			if (!destroyed && token === detailToken) {
+				state.pending.detail = false;
+				notify();
+			}
+		}
+	}
+
+	return {
+		snapshot,
+
+		subscribe(callback) {
+			subscribers.add(callback);
+			return () => {
+				subscribers.delete(callback);
+			};
+		},
+
+		load() {
+			if (state.status === "idle") state.status = "loading";
+			return read(
+				"overview",
+				async () => {
+					// Context, profile and work are independent, so one failing
+					// should not hide the other two.
+					const [context, profile, work] = await Promise.allSettled([
+						portal.context(),
+						portal.getProfile(),
+						portal.getWork(),
+					]);
+					if (destroyed) return;
+					if (context.status === "fulfilled") state.context = context.value;
+					if (profile.status === "fulfilled") state.profile = profile.value;
+					if (work.status === "fulfilled") state.work = work.value;
+					const firstFailure = [context, profile, work].find(
+						(r) => r.status === "rejected",
+					);
+					if (firstFailure && firstFailure.status === "rejected") {
+						throw firstFailure.reason;
+					}
+				},
+				"Failed to load the portal.",
+			);
+		},
+
+		loadOrders(opts) {
+			return read(
+				"orders",
+				async () => {
+					state.orders = await portal.listOrders(opts);
+				},
+				"Failed to load orders.",
+			);
+		},
+
+		loadInvoices(opts) {
+			return read(
+				"orders",
+				async () => {
+					state.invoices = await portal.listInvoices(opts);
+				},
+				"Failed to load invoices.",
+			);
+		},
+
+		loadQuotes(opts) {
+			return read(
+				"orders",
+				async () => {
+					state.quotes = await portal.listQuotes(opts);
+				},
+				"Failed to load quotes.",
+			);
+		},
+
+		loadContracts(opts) {
+			return read(
+				"orders",
+				async () => {
+					state.contracts = await portal.listContracts(opts);
+				},
+				"Failed to load contracts.",
+			);
+		},
+
+		loadShipments(opts) {
+			return read(
+				"orders",
+				async () => {
+					state.shipments = await portal.listShipments(opts);
+				},
+				"Failed to load shipments.",
+			);
+		},
+
+		loadMessages(opts) {
+			return read(
+				"orders",
+				async () => {
+					state.messages = await portal.listMessages(opts);
+				},
+				"Failed to load your messages.",
+			);
+		},
+
+		async postMessage(input) {
+			const res = await act(
+				() => portal.postMessage(input),
+				"Failed to send your message.",
+			);
+			if (!res) return false;
+			// Re-read rather than append: the stored row carries the author name
+			// and timestamp the server assigned, and a locally-appended message
+			// that later differs is the kind of thing a customer notices.
+			await read(
+				"orders",
+				async () => {
+					state.messages = await portal.listMessages(
+						input.jobId ? { jobId: input.jobId } : undefined,
+					);
+				},
+				"Message sent, but the thread could not be refreshed.",
+			);
+			return true;
+		},
+
+		async markMessagesRead() {
+			await act(
+				() => portal.markMessagesRead(),
+				"Failed to mark your messages read.",
+				() => {
+					// Stamp locally so the badge clears immediately rather than
+					// waiting for a re-read the caller may never do.
+					if (state.messages) {
+						const now = new Date().toISOString();
+						state.messages = {
+							...state.messages,
+							items: state.messages.items.map((m) =>
+								m.direction === "outbound" && m.readByCustomerAt === null
+									? { ...m, readByCustomerAt: now }
+									: m,
+							),
+						};
+					}
+				},
+			);
+		},
+
+		loadPayments(opts) {
+			return read(
+				"payments",
+				async () => {
+					state.payments = await portal.listPayments(opts);
+				},
+				"Failed to load payment history.",
+			);
+		},
+
+		loadReviews() {
+			return read(
+				"reviews",
+				async () => {
+					state.reviews = await portal.listMyReviews();
+				},
+				"Failed to load your reviews.",
+			);
+		},
+
+		loadReferrals() {
+			return read(
+				"referrals",
+				async () => {
+					const [stats, history, payouts] = await Promise.all([
+						portal.myReferralStats(),
+						portal.myReferralHistory(),
+						portal.myReferralPayouts(),
+					]);
+					if (destroyed) return;
+					state.referrals = { stats, history, payouts };
+				},
+				"Failed to load referrals.",
+			);
+		},
+
+		loadPushConfig() {
+			return read(
+				// "overview" rather than a slice of its own: the device list is
+				// small, loads with the rest of a settings page, and one more
+				// pending flag is one more thing every binding has to thread.
+				"overview",
+				async () => {
+					state.push = await portal.getPushConfig();
+				},
+				"Failed to load your notification devices.",
+			);
+		},
+
+		async enablePush(options) {
+			// Support is checked BEFORE the config fetch: on an iPhone in a
+			// normal tab there is nothing a key could enable, and a round trip
+			// that ends in "add this to your Home Screen" is a wasted one.
+			const support = pushSupport();
+			if (!support.supported) {
+				return {
+					ok: false,
+					reason: support.reason === "server" ? "unsupported" : support.reason,
+					message: support.message,
+				};
+			}
+
+			const config = await act(
+				() => portal.getPushConfig(),
+				"Failed to start setting up notifications.",
+			);
+			if (!config) {
+				return {
+					ok: false,
+					reason: "failed",
+					message: "Failed to start setting up notifications.",
+				};
+			}
+			if (!config.enabled || !config.vapidPublicKey) {
+				// The platform has no VAPID pair configured. Nothing the visitor
+				// or the org can do about it, so say so plainly instead of
+				// failing at `subscribe()` with a DOMException nobody can act on.
+				return {
+					ok: false,
+					reason: "not-configured",
+					message: "Push notifications aren't available for this site yet.",
+				};
+			}
+
+			const subscribed = await subscribeToPush({
+				vapidPublicKey: config.vapidPublicKey,
+				...(options?.serviceWorkerPath === undefined
+					? {}
+					: { serviceWorkerPath: options.serviceWorkerPath }),
+				...(options?.scope === undefined ? {} : { scope: options.scope }),
+			});
+			if (!subscribed.ok) {
+				return {
+					ok: false,
+					reason: subscribed.reason,
+					message: subscribed.message,
+				};
+			}
+
+			const saved = await act(
+				() =>
+					portal.subscribePush({
+						endpoint: subscribed.subscription.endpoint,
+						p256dh: subscribed.subscription.p256dh,
+						auth: subscribed.subscription.auth,
+						userAgent: subscribed.subscription.userAgent ?? null,
+						label: options?.label ?? null,
+					}),
+				"Notifications were allowed, but we couldn't finish setting them up.",
+			);
+			if (!saved) {
+				// The browser now holds a subscription the server does not know
+				// about. Roll it back rather than leaving a device that looks
+				// enabled locally and receives nothing — a state whose only
+				// symptom is silence.
+				await unsubscribeFromPush().catch(() => undefined);
+				return {
+					ok: false,
+					reason: "failed",
+					message:
+						"Notifications were allowed, but we couldn't finish setting them up. Try again.",
+				};
+			}
+
+			await this.loadPushConfig();
+			return { ok: true, deviceId: saved.id };
+		},
+
+		async disablePush() {
+			// Read the endpoint BEFORE tearing the local subscription down —
+			// it is what the server keys on, and once `unsubscribe()` has run
+			// there is nothing left to look the row up by.
+			const local = await currentPushSubscription().catch(() => null);
+			const torn = await unsubscribeFromPush().catch(() => ({
+				endpoint: null,
+			}));
+			const endpoint = torn.endpoint ?? local?.endpoint ?? null;
+			if (!endpoint) {
+				// Nothing registered here. Refresh anyway, since a device may
+				// have been removed from somewhere else.
+				await this.loadPushConfig();
+				return true;
+			}
+			const result = await act(
+				() => portal.unsubscribePush({ endpoint }),
+				"Failed to turn notifications off.",
+			);
+			if (result) await this.loadPushConfig();
+			return Boolean(result?.ok);
+		},
+
+		async updatePushDevice(input) {
+			const result = await act(
+				() => portal.updatePushDevice(input),
+				"Failed to update that device.",
+			);
+			if (result?.ok) await this.loadPushConfig();
+			return Boolean(result?.ok);
+		},
+
+		async forgetPushDevice(id) {
+			const result = await act(
+				() => portal.unsubscribePush({ id }),
+				"Failed to remove that device.",
+			);
+			if (result?.ok) await this.loadPushConfig();
+			return Boolean(result?.ok);
+		},
+
+		loadNotificationPreferences() {
+			return read(
+				"overview",
+				async () => {
+					state.notificationPreferences =
+						await portal.getNotificationPreferences();
+				},
+				"Failed to load notification preferences.",
+			);
+		},
+
+		loadOtherOrgs() {
+			return read(
+				"overview",
+				async () => {
+					state.otherOrgs = await portal.myOtherCustomerOrgs();
+				},
+				"Failed to load your other companies.",
+			);
+		},
+
+		loadNotificationPreferencesFor(orgId) {
+			return read(
+				"overview",
+				async () => {
+					const prefs = await portalFor(orgId).getNotificationPreferences();
+					// Replace the whole record rather than mutating in place, so
+					// framework bindings comparing snapshot identity actually see it.
+					state.notificationPreferencesByOrg = {
+						...state.notificationPreferencesByOrg,
+						[orgId]: prefs,
+					};
+				},
+				"Failed to load notification preferences for that company.",
+			);
+		},
+
+		async updateNotificationPreferencesFor(orgId, input) {
+			const res = await act(
+				() => portalFor(orgId).updateNotificationPreferences(input),
+				"Failed to update notification preferences for that company.",
+			);
+			if (res && !destroyed) {
+				// The server merges sparse writes into the stored matrix, so the
+				// authoritative result is what came BACK — echoing the request
+				// would show the customer a matrix the server never agreed to.
+				state.notificationPreferencesByOrg = {
+					...state.notificationPreferencesByOrg,
+					[orgId]: res,
+				};
+				notify();
+			}
+			return res !== null;
+		},
+
+		openJob(jobId) {
+			return detail(async (token) => {
+				const job = await portal.getJob(jobId);
+				if (destroyed || token !== detailToken) return;
+				state.activeJob = job;
+				notify();
+
+				// Activity, ETA and comments are supporting detail. Any of them
+				// failing must not blank the job the customer asked for.
+				const [activity, eta, comments] = await Promise.allSettled([
+					portal.getJobActivity(jobId),
+					portal.getJobEta(jobId),
+					portal.listJobComments(jobId),
+				]);
+				if (destroyed || token !== detailToken) return;
+				state.jobActivity =
+					activity.status === "fulfilled" ? activity.value : null;
+				state.jobEta = eta.status === "fulfilled" ? eta.value : null;
+				state.jobComments =
+					comments.status === "fulfilled" ? comments.value : null;
+			}, "Failed to load the job.");
+		},
+
+		openOrder(orderId) {
+			return detail(async (token) => {
+				const order = await portal.getOrder(orderId);
+				if (destroyed || token !== detailToken) return;
+				state.activeOrder = order;
+				notify();
+
+				// Digital downloads only exist for some orders; a 404 here is
+				// normal and must not look like the order failed to load.
+				// Downloads and returns are both optional detail on an order —
+				// most orders have neither, so a 404 on either is normal and must
+				// not look like the order failed to load.
+				const [downloads, returns] = await Promise.allSettled([
+					portal.getDownloads(orderId),
+					portal.listReturnRequests(orderId),
+				]);
+				if (!destroyed && token === detailToken) {
+					state.orderDownloads =
+						downloads.status === "fulfilled" ? downloads.value : null;
+					state.returnRequests =
+						returns.status === "fulfilled" ? returns.value : null;
+				}
+			}, "Failed to load the order.");
+		},
+
+		openInvoice(invoiceId) {
+			return detail(async (token) => {
+				const invoice = await portal.getInvoice(invoiceId);
+				if (destroyed || token !== detailToken) return;
+				state.activeInvoice = invoice;
+			}, "Failed to load the invoice.");
+		},
+
+		openQuote(quoteId) {
+			return detail(async (token) => {
+				// `viewQuote` both fetches and records that the customer looked,
+				// which the org can see. That is the right call from a portal:
+				// opening a quote IS viewing it.
+				const quote = await portal.viewQuote(quoteId);
+				if (destroyed || token !== detailToken) return;
+				state.activeQuote = quote;
+			}, "Failed to load the quote.");
+		},
+
+		openContract(contractId) {
+			return detail(async (token) => {
+				const contract = await portal.getContract(contractId);
+				if (destroyed || token !== detailToken) return;
+				state.activeContract = contract;
+			}, "Failed to load the contract.");
+		},
+
+		trackShipment(shipmentId) {
+			return detail(async (token) => {
+				const tracking = await portal.trackShipment(shipmentId);
+				if (destroyed || token !== detailToken) return;
+				state.shipmentTracking = tracking;
+			}, "Failed to track the shipment.");
+		},
+
+		closeDetail() {
+			if (destroyed) return;
+			detailToken += 1; // orphan anything in flight
+			state.activeJob = null;
+			state.jobActivity = null;
+			state.jobEta = null;
+			state.jobComments = null;
+			state.activeOrder = null;
+			state.orderDownloads = null;
+			state.returnRequests = null;
+			state.activeInvoice = null;
+			state.activeQuote = null;
+			state.activeContract = null;
+			state.shipmentTracking = null;
+			// Per-shipment, so it belongs to the detail view rather than the
+			// session — leaving it would show a stale claim on the next parcel.
+			state.lastNotReceived = null;
+			notify();
+		},
+
+		async postJobComment(jobId, input) {
+			const res = await act(
+				() => portal.postJobComment(jobId, input),
+				"Failed to post the comment.",
+			);
+			if (!res) return false;
+			// Re-read rather than splice: the thread is the authority on what a
+			// comment looks like once the server has it.
+			await read(
+				"detail",
+				async () => {
+					state.jobComments = await portal.listJobComments(jobId);
+				},
+				"Comment posted, but the thread could not be refreshed.",
+			);
+			return true;
+		},
+
+		async acceptQuote(quoteId) {
+			const res = await act(
+				() => portal.acceptQuote(quoteId),
+				"Failed to accept the quote.",
+				() => {
+					// One-way state change; re-read so the UI shows the new status
+					// rather than the stale one it was rendered from.
+					void portal
+						.getQuote(quoteId)
+						.then((q) => {
+							if (!destroyed) {
+								state.activeQuote = q;
+								notify();
+							}
+						})
+						.catch(() => {});
+				},
+			);
+			return res !== null;
+		},
+
+		async rejectQuote(quoteId) {
+			const res = await act(
+				() => portal.rejectQuote(quoteId),
+				"Failed to reject the quote.",
+				() => {
+					void portal
+						.getQuote(quoteId)
+						.then((q) => {
+							if (!destroyed) {
+								state.activeQuote = q;
+								notify();
+							}
+						})
+						.catch(() => {});
+				},
+			);
+			return res !== null;
+		},
+
+		async signContract(contractId) {
+			const res = await act(
+				() => portal.signContract(contractId),
+				"Failed to sign the contract.",
+				() => {
+					// There is no unsign. Re-reading is the only way the UI learns
+					// the contract is now signed.
+					void portal
+						.getContract(contractId)
+						.then((c) => {
+							if (!destroyed) {
+								state.activeContract = c;
+								notify();
+							}
+						})
+						.catch(() => {});
+				},
+			);
+			return res !== null;
+		},
+
+		payInvoice(invoiceId, opts) {
+			return act(
+				() => portal.payInvoice(invoiceId, opts),
+				"Could not start the payment.",
+			);
+		},
+
+		async updateProfile(input) {
+			const res = await act(
+				() => portal.updateProfile(input),
+				"Failed to save your details.",
+			);
+			if (res === null) return false;
+			await read(
+				"overview",
+				async () => {
+					state.profile = await portal.getProfile();
+				},
+				"Saved, but your details could not be re-read.",
+			);
+			return true;
+		},
+
+		async updateNotificationPreferences(input) {
+			const res = await act(
+				() => portal.updateNotificationPreferences(input),
+				"Failed to save your notification settings.",
+				(next) => {
+					state.notificationPreferences = next;
+				},
+			);
+			return res !== null;
+		},
+
+		async submitReview(input) {
+			const res = await act(
+				() => portal.submitReview(input),
+				"Failed to submit your review.",
+				() => {
+					// Deliberately NOT added to `reviews`. It lands as `pending` for
+					// staff approval, and showing it back would tell the author it is
+					// live when the public cannot see it.
+					state.reviewAwaitingModeration = true;
+				},
+			);
+			return res !== null;
+		},
+
+		submitReturnRequest(orderId, input) {
+			return act(
+				() => portal.submitReturnRequest(orderId, input),
+				"Failed to submit the return request.",
+				() => {
+					// Re-read so the customer immediately sees the request they just
+					// made, with its real status. Submitting into silence is what
+					// made this gap worth closing.
+					void portal
+						.listReturnRequests(orderId)
+						.then((res) => {
+							if (!destroyed) {
+								state.returnRequests = res;
+								notify();
+							}
+						})
+						.catch(() => {});
+				},
+			);
+		},
+
+		submitExchangeRequest(orderId, input) {
+			// Routed through the same method so the re-read, the error copy and
+			// the pending flag stay identical — an exchange is a return request
+			// with a different ask, not a separate flow.
+			return this.submitReturnRequest(orderId, {
+				...(input ?? {}),
+				kind: "exchange",
+			});
+		},
+
+		reportNotReceived(shipmentId, input) {
+			return act(
+				() => portal.reportNotReceived(shipmentId, input),
+				"Failed to report the parcel as not received.",
+			).then((res) => {
+				if (res && !destroyed) {
+					state.lastNotReceived = res;
+					notify();
+				}
+				return res;
+			});
+		},
+
+		loadDispatchStatus(jobId) {
+			return detail(async (token) => {
+				const eta = await portal.getDispatchStatus(jobId);
+				if (destroyed || token !== detailToken) return;
+				state.jobEta = eta;
+			}, "Failed to load the dispatch status.");
+		},
+
+		loadSubscription() {
+			return read(
+				"overview",
+				async () => {
+					state.subscription = await portal.getSubscription();
+				},
+				"Failed to load your subscription.",
+			);
+		},
+
+		loadSubscriberContent(opts) {
+			return read(
+				"overview",
+				async () => {
+					state.subscriberContent = await portal.getSubscriberContent(opts);
+				},
+				"Failed to load your subscriber content.",
+			);
+		},
+
+		async cancelSubscription() {
+			const res = await act(
+				() => portal.cancelSubscription(),
+				"Failed to cancel your subscription.",
+			);
+			if (res && !destroyed) {
+				// Re-read rather than patching the cached row: the provider's
+				// webhook owns `status`, and guessing what it will write is how a
+				// portal ends up showing "cancelled" while the customer still has
+				// — and has paid for — access.
+				void portal
+					.getSubscription()
+					.then((next) => {
+						if (!destroyed) {
+							state.subscription = next;
+							notify();
+						}
+					})
+					.catch(() => {});
+			}
+			return res;
+		},
+
+		async resumeSubscription() {
+			const res = await act(
+				() => portal.resumeSubscription(),
+				"Failed to resume your subscription.",
+			);
+			if (res && !destroyed) {
+				void portal
+					.getSubscription()
+					.then((next) => {
+						if (!destroyed) {
+							state.subscription = next;
+							notify();
+						}
+					})
+					.catch(() => {});
+			}
+			return res;
+		},
+
+		async loadProductReviews() {
+			await act(
+				() => portal.listProductReviews(),
+				"Failed to load your product reviews.",
+				() => {},
+			).then((res) => {
+				if (res && !destroyed) {
+					state.productReviews = res;
+					notify();
+				}
+			});
+		},
+
+		async submitProductReview(input) {
+			const res = await act(
+				() => portal.submitProductReview(input),
+				"Failed to submit your review.",
+				() => {},
+			);
+			if (res && !destroyed) {
+				// Only flag moderation when the org actually held it. Saying
+				// "awaiting review" for a review that is already live is its own
+				// kind of wrong.
+				state.productReviewAwaitingModeration = res.awaitingModeration;
+				// Re-read so the customer sees what they wrote, with its real
+				// approval state, rather than having to trust that it landed.
+				void portal
+					.listProductReviews()
+					.then((list) => {
+						if (!destroyed) {
+							state.productReviews = list;
+							notify();
+						}
+					})
+					.catch(() => {});
+			}
+			return res !== null;
+		},
+
+		contactCompany(input) {
+			return act(
+				() => portal.contactCompany(input),
+				"Failed to send your message.",
+			);
+		},
+
+		destroy() {
+			destroyed = true;
+			subscribers.clear();
+		},
+	};
+}