@shoppexio/storefront-react 0.0.0 → 0.1.1

package/eject/account/account-rewards.ts

@@ -0,0 +1,104 @@
+import type { SdkCustomerRewardActivity } from '@shoppexio/storefront-react';
+
+/**
+ * The rewards panel's pure half.
+ *
+ * Rewards arrive inside the dashboard payload, already summed by the server.
+ * Nothing here recomputes a balance: the available figure is the buyer's wallet
+ * minus what is on hold, and a storefront adding up the activity list would
+ * produce a second, different number for the same money.
+ */
+
+/**
+ * The coupons a buyer can actually use.
+ *
+ * All three conditions matter. A pending coupon has no code yet, a revoked one
+ * has a code that will be refused at checkout, and a wallet grant is credit
+ * rather than something to paste. Any of them in this list would send a buyer
+ * to checkout with a code that does not work.
+ */
+export interface UsableCoupon extends SdkCustomerRewardActivity {
+  /** Narrowed: a coupon without a code is not in this list at all. */
+  coupon_code: string;
+}
+
+export function usableCoupons(
+  activity: readonly SdkCustomerRewardActivity[],
+): UsableCoupon[] {
+  const coupons: UsableCoupon[] = [];
+  for (const item of activity) {
+    if (item.type !== 'COUPON' || item.status !== 'FULFILLED') continue;
+    if (typeof item.coupon_code !== 'string' || item.coupon_code.length === 0) continue;
+    coupons.push({ ...item, coupon_code: item.coupon_code });
+  }
+  return coupons;
+}
+
+/**
+ * What one reward IS, decided without a word of prose.
+ *
+ * The panel turns this into a sentence, because only the panel knows the
+ * locale and how this shop formats money. Store credit names its amount only
+ * when the server sent BOTH the amount and the currency: a number without its
+ * currency is not money, and printing one beside a currency it was not measured
+ * in is how a buyer reads €5 as $5.
+ */
+export type RewardTitle =
+  | { kind: 'store-credit-amount'; amount: string; currency: string }
+  | { kind: 'store-credit' }
+  | { kind: 'coupon-code'; code: string }
+  | { kind: 'coupon-percent'; percent: string }
+  | { kind: 'coupon' }
+  | { kind: 'other' };
+
+export function rewardTitle(item: SdkCustomerRewardActivity): RewardTitle {
+  if (item.type === 'WALLET_CREDIT') {
+    return item.amount && item.currency
+      ? { kind: 'store-credit-amount', amount: item.amount, currency: item.currency }
+      : { kind: 'store-credit' };
+  }
+
+  if (item.type === 'COUPON') {
+    if (item.coupon_code) return { kind: 'coupon-code', code: item.coupon_code };
+    if (item.amount) return { kind: 'coupon-percent', percent: item.amount };
+    return { kind: 'coupon' };
+  }
+
+  return { kind: 'other' };
+}
+
+const REASON_KEYS: Readonly<Record<string, string>> = {
+  ORDER_COMPLETED: 'rewards.reasonOrderCompleted',
+  ORDER_COUNT_REACHED: 'rewards.reasonOrderCount',
+  SPEND_AMOUNT_REACHED: 'rewards.reasonSpendAmount',
+  POSITIVE_REVIEW_LEFT: 'rewards.reasonReview',
+  FIRST_PURCHASE_COMPLETED: 'rewards.reasonFirstPurchase',
+};
+
+/** Why the buyer earned it. An unknown trigger says "Reward", never its enum. */
+export function rewardReasonKey(reason: string): string {
+  return REASON_KEYS[reason] ?? 'rewards.reasonOther';
+}
+
+const GRANT_STATUS_KEYS: Readonly<Record<string, string>> = {
+  FULFILLED: 'rewards.grantFulfilled',
+  PENDING: 'rewards.grantPending',
+  FAILED: 'rewards.grantFailed',
+  REVOKED: 'rewards.grantRevoked',
+};
+
+/** Null for a status this catalog has never heard of — the caller shows the raw value. */
+export function rewardStatusKey(status: string): string | null {
+  return GRANT_STATUS_KEYS[status] ?? null;
+}
+
+/** Epoch SECONDS — the unit `RewardReadService` emits — to a date. */
+export function epochSecondsToDate(value: number): Date {
+  return new Date(value * 1000);
+}
+
+/** The same, for the fields where `null` means "no date", not "unreadable". */
+export function optionalEpochSecondsToDate(value: number | null): Date | null {
+  return value === null ? null : epochSecondsToDate(value);
+}
+

package/eject/account/account-settings.ts

@@ -0,0 +1,181 @@
+/**
+ * The settings panel's pure half: the two payloads it narrows, and the small
+ * rules around what the buyer may change.
+ *
+ * What is deliberately absent: the email address (changing it is gated behind a
+ * fresh code in the backend and has no allowlisted path), a password field
+ * (this account signs in with a code, and `/security/password` is not open to
+ * storefront code), and account deletion (there is no endpoint at all). A
+ * control for any of them would be a control that cannot work.
+ */
+
+export interface EmailList {
+  id: string;
+  name: string;
+  description: string | null;
+  subscribed: boolean;
+}
+
+export interface EmailPreferences {
+  /** True when the buyer is suppressed from every marketing send. */
+  global_unsubscribed: boolean;
+  lists: EmailList[];
+}
+
+export type EmailPreferencesResult =
+  | { ok: true; preferences: EmailPreferences }
+  | { ok: false };
+
+export interface CustomerSession {
+  id: string;
+  created_at: string;
+  expires_at: string;
+  ip_address: string | null;
+  user_agent: string | null;
+  /** The session making the request. Never offered a "sign out" of its own. */
+  current: boolean;
+}
+
+export type CustomerSessionsResult =
+  | { ok: true; sessions: CustomerSession[] }
+  | { ok: false };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function readNullableString(record: Record<string, unknown>, key: string): string | null | undefined {
+  const value = record[key];
+  if (value === null || typeof value === 'string') return value;
+  return undefined;
+}
+
+export function narrowEmailPreferences(payload: unknown): EmailPreferencesResult {
+  if (!isRecord(payload) || typeof payload.global_unsubscribed !== 'boolean') return { ok: false };
+  if (!Array.isArray(payload.lists)) return { ok: false };
+
+  const lists: EmailList[] = [];
+  for (const entry of payload.lists) {
+    if (!isRecord(entry)) return { ok: false };
+    const description = readNullableString(entry, 'description');
+    if (
+      typeof entry.id !== 'string'
+      || typeof entry.name !== 'string'
+      || description === undefined
+      || typeof entry.subscribed !== 'boolean'
+    ) {
+      return { ok: false };
+    }
+    lists.push({ id: entry.id, name: entry.name, description, subscribed: entry.subscribed });
+  }
+
+  return { ok: true, preferences: { global_unsubscribed: payload.global_unsubscribed, lists } };
+}
+
+export function narrowCustomerSessions(payload: unknown): CustomerSessionsResult {
+  if (!isRecord(payload) || !Array.isArray(payload.sessions)) return { ok: false };
+
+  const sessions: CustomerSession[] = [];
+  for (const entry of payload.sessions) {
+    if (!isRecord(entry)) return { ok: false };
+    const ipAddress = readNullableString(entry, 'ip_address');
+    const userAgent = readNullableString(entry, 'user_agent');
+    if (
+      typeof entry.id !== 'string'
+      || typeof entry.created_at !== 'string'
+      || typeof entry.expires_at !== 'string'
+      || ipAddress === undefined
+      || userAgent === undefined
+      || typeof entry.current !== 'boolean'
+    ) {
+      return { ok: false };
+    }
+    sessions.push({
+      id: entry.id,
+      created_at: entry.created_at,
+      expires_at: entry.expires_at,
+      ip_address: ipAddress,
+      user_agent: userAgent,
+      current: entry.current,
+    });
+  }
+
+  return { ok: true, sessions };
+}
+
+/** Whether any device other than this one is signed in. */
+export function hasOtherSessions(sessions: readonly CustomerSession[]): boolean {
+  return sessions.some((session) => !session.current);
+}
+
+/**
+ * A device, in words a buyer recognises.
+ *
+ * Browser and system names are product names, so they are not translated; the
+ * catalog owns the sentence they sit in. Order matters: Edge reports itself as
+ * Chrome, and Chrome reports itself as Safari, so the most specific claim has
+ * to be tested first or every device is a Safari.
+ */
+export function describeUserAgent(
+  userAgent: string | null,
+): { browser: string; os: string | null } | null {
+  const value = userAgent?.trim();
+  if (!value) return null;
+
+  const browser = value.includes('Edg/')
+    ? 'Edge'
+    : value.includes('OPR/') || value.includes('Opera')
+      ? 'Opera'
+      : value.includes('Firefox/')
+        ? 'Firefox'
+        : value.includes('Chrome/')
+          ? 'Chrome'
+          : value.includes('Safari/')
+            ? 'Safari'
+            : null;
+
+  if (!browser) return null;
+
+  const os = value.includes('Windows')
+    ? 'Windows'
+    : value.includes('Android')
+      ? 'Android'
+      : value.includes('iPhone') || value.includes('iPad')
+        ? 'iOS'
+        : value.includes('Mac OS X') || value.includes('Macintosh')
+          ? 'macOS'
+          : value.includes('Linux')
+            ? 'Linux'
+            : null;
+
+  return { browser, os };
+}
+
+/**
+ * The two letters shown while a buyer has no photo.
+ *
+ * The email is the fallback because it is the one thing every account has —
+ * `ensurePortalIdentity` fills the name from it when the buyer never set one.
+ */
+export function profileInitials(name: string, email: string): string {
+  const source = name.trim() || email.split('@')[0]?.trim() || '';
+  const words = source.split(/\s+/).filter(Boolean);
+  if (words.length === 0) return '?';
+  if (words.length === 1) return (words[0] ?? '').slice(0, 2).toLocaleUpperCase();
+  const first = (words[0] ?? '').charAt(0);
+  const last = (words[words.length - 1] ?? '').charAt(0);
+  return `${first}${last}`.toLocaleUpperCase();
+}
+
+/** A name the producer will accept: `CustomerProfileUpdateBodySchema` requires one. */
+export function isSaveableName(value: string): boolean {
+  return value.trim().length >= 2;
+}
+
+/** The producer refuses anything larger, after buffering it. Stop it here. */
+export const MAX_AVATAR_BYTES = 10 * 1024 * 1024;
+
+export function isAcceptableAvatarSize(bytes: number): boolean {
+  return bytes > 0 && bytes <= MAX_AVATAR_BYTES;
+}
+

package/eject/account/account-signin-link.ts

@@ -0,0 +1,122 @@
+/**
+ * The OTP email's sign-in link, handed to the account page in a cookie
+ * (ADR-0064 S11).
+ *
+ * **Following the link verifies nothing.** It carries the email and the code
+ * the buyer was just sent, and everything here does with them is put them in
+ * the form. No request is made, nothing is consumed, and no session is created
+ * — a corporate mail scanner that fetches the URL leaves the code exactly as
+ * valid as it found it, which is the property ADR-0052 chose codes to protect
+ * and the reason this link is allowed to exist beside them.
+ *
+ * The link's `sx_login_email` / `sx_login_code` parameters never reach the
+ * browser. The Shoppex edge worker injects merchant analytics — Google
+ * Analytics, GTM, Meta Pixel, TikTok — synchronously into `<head>`, and those
+ * run before this storefront's bundle does, so a page-view beacon would carry a
+ * live one-time code to a third party whatever this page did with the URL a
+ * moment later. The worker therefore answers the link with a redirect to the
+ * clean URL and puts the pair in the cookie named below. That worker is the
+ * only producer: there is no query-string path here, because a URL carrying
+ * these values is one the browser is never supposed to see.
+ *
+ * The cookie is deliberately readable by JavaScript — this page has to read it
+ * — which is why the worker gives it two minutes and why the read below deletes
+ * it on the way out. It holds a credential for exactly one navigation.
+ *
+ * The document lane reads the same cookie in
+ * `packages/storefront-commerce/src/sx/account-signin-link.ts`. This template is
+ * built standalone against the published SDK and cannot import from the
+ * monorepo, so it carries its own copy and pins the name and value shape in
+ * `tests/account-signin-link.test.ts` — the same arrangement the document lane
+ * uses for the same reason.
+ *
+ * Neither value is judged beyond "is it usable as a form value". The backend is
+ * the authority on whether a code is valid, and a client that decided the shape
+ * of a code would be inventing a contract the producer never promised.
+ */
+
+/** The worker's cookie name, pinned here because it cannot be imported. */
+export const ACCOUNT_SIGN_IN_PREFILL_COOKIE = '__Host-sx_signin_prefill';
+
+const MAX_EMAIL_LENGTH = 254;
+const MAX_CODE_LENGTH = 64;
+
+/**
+ * Deleting a cookie is a write, and the `__Host-` prefix makes the browser
+ * REJECT a write that is not `Secure` with `Path=/` and no `Domain`. A delete
+ * that dropped those attributes would silently do nothing and leave the code in
+ * the jar for the rest of its two minutes, so the attributes mirror the
+ * worker's exactly.
+ */
+const CLEAR_PREFILL_COOKIE = `${ACCOUNT_SIGN_IN_PREFILL_COOKIE}=; Path=/; Secure; SameSite=Lax; Max-Age=0`;
+
+export interface AccountSignInPrefill {
+  email: string;
+  code: string;
+}
+
+/** The two things this needs from `document`: read the jar, write one cookie back. */
+export interface AccountCookieJar {
+  cookie: string;
+}
+
+/** A form value has to be one line and non-empty to be worth putting in a field. */
+function usable(raw: unknown, maxLength: number): string {
+  const value = typeof raw === 'string' ? raw.trim() : '';
+  if (!value || value.length > maxLength) return '';
+  return /\s/.test(value) ? '' : value;
+}
+
+/** The raw, still-encoded value of one cookie in a `document.cookie` string. */
+function cookieValue(jar: string, name: string): string | null {
+  for (const entry of jar.split(';')) {
+    const separator = entry.indexOf('=');
+    if (separator < 0) continue;
+    if (entry.slice(0, separator).trim() !== name) continue;
+    return entry.slice(separator + 1).trim();
+  }
+  return null;
+}
+
+/**
+ * The email and code to put in the login form, or null when the cookie does not
+ * carry a usable pair. Half a pair is not a prefill: filling one field and
+ * leaving the other empty is worse than leaving the form untouched.
+ */
+function parsePrefill(raw: string): AccountSignInPrefill | null {
+  let value: unknown;
+  try {
+    value = JSON.parse(decodeURIComponent(raw));
+  } catch {
+    return null;
+  }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+
+  const record = value as Record<string, unknown>;
+  const email = usable(record.email, MAX_EMAIL_LENGTH);
+  const code = usable(record.code, MAX_CODE_LENGTH);
+  if (!email || !code) return null;
+  return { email, code };
+}
+
+/**
+ * Read the prefill and delete the cookie, in that one step.
+ *
+ * Reading and deleting are the same operation on purpose: a caller that could
+ * read without deleting would leave a credential in a JavaScript-readable
+ * cookie for every script on the page to find, for two minutes, on a surface
+ * where merchants install their own analytics.
+ *
+ * The delete happens BEFORE the value is parsed, so a malformed cookie — the
+ * only kind this page cannot use — is removed just as surely as a good one.
+ * An absent cookie is the ordinary case (a buyer who typed the URL) and is
+ * neither a prefill nor a reason to write anything.
+ */
+export function takeAccountSignInPrefill(jar: AccountCookieJar): AccountSignInPrefill | null {
+  const raw = cookieValue(jar.cookie, ACCOUNT_SIGN_IN_PREFILL_COOKIE);
+  if (raw === null) return null;
+
+  jar.cookie = CLEAR_PREFILL_COOKIE;
+  return parsePrefill(raw);
+}
+

package/eject/account/account-subscriptions.ts

@@ -0,0 +1,130 @@
+import type { SdkCustomerSubscription } from '@shoppexio/storefront-react';
+
+/**
+ * The subscriptions panel's pure half: which date matters, how the plan bills,
+ * what cancelling actually does, and the shape of the billing history.
+ */
+
+/**
+ * The one date worth showing, and what it means.
+ *
+ * Order matters and is not cosmetic. A cancelled subscription that still has a
+ * period end would otherwise read "Renews 1 Apr" — the opposite of the truth —
+ * and a subscription already set to stop must say so rather than advertise the
+ * renewal it will never take.
+ */
+export type SubscriptionTiming =
+  | { kind: 'canceled'; date: string }
+  | { kind: 'ends'; date: string }
+  | { kind: 'trial'; date: string }
+  | { kind: 'renews'; date: string };
+
+export function subscriptionTiming(subscription: SdkCustomerSubscription): SubscriptionTiming {
+  if (subscription.status.toUpperCase() === 'CANCELED' && subscription.canceled_at) {
+    return { kind: 'canceled', date: subscription.canceled_at };
+  }
+  if (subscription.cancel_at_period_end) {
+    return { kind: 'ends', date: subscription.current_period_end };
+  }
+  if (subscription.status.toUpperCase() === 'TRIALING' && subscription.trial_end) {
+    return { kind: 'trial', date: subscription.trial_end };
+  }
+  return { kind: 'renews', date: subscription.current_period_end };
+}
+
+/** The catalog key for a timing, so the panel never spells one itself. */
+export function subscriptionTimingKey(timing: SubscriptionTiming): string {
+  return `subscriptions.${timing.kind}`;
+}
+
+const KNOWN_INTERVALS: ReadonlySet<string> = new Set(['day', 'week', 'month', 'year']);
+
+/**
+ * How often the plan bills, as a catalog key plus its parameters.
+ *
+ * Singular and plural are separate keys rather than one string with a number in
+ * it: "every 1 months" is wrong in English and worse in the languages that
+ * decline the noun. An interval the gateway spells in a way this catalog does
+ * not know keeps the raw word instead of being renamed into one that is close.
+ */
+export function billingMessage(
+  plan: NonNullable<SdkCustomerSubscription['plan']>,
+): { key: string; params: { count: number; interval: string } } {
+  const interval = plan.interval.trim().toLowerCase();
+  // A gateway that reports 0 or a negative count still bills once per interval.
+  const count = plan.interval_count > 0 ? plan.interval_count : 1;
+  const params = { count, interval: plan.interval };
+
+  if (!KNOWN_INTERVALS.has(interval)) {
+    return { key: 'subscriptions.billingOther', params };
+  }
+
+  const suffix = count === 1 ? 'One' : 'Other';
+  const name = interval.charAt(0).toUpperCase() + interval.slice(1);
+  return { key: `subscriptions.billing${name}${suffix}`, params };
+}
+
+/**
+ * Whether a cancellation lets the buyer keep the time they already paid for.
+ *
+ * PayPal cannot end a billing agreement at the period boundary, so a PayPal
+ * cancellation takes effect at once. Every other gateway can, and does — which
+ * is why the confirmation copy differs: telling a PayPal buyer they keep access
+ * until April would be a promise this template cannot keep.
+ */
+export function cancelsAtPeriodEnd(gateway: string): boolean {
+  return gateway.trim().toUpperCase() !== 'PAYPAL';
+}
+
+export interface BillingHistoryInvoice {
+  uniqid: string;
+  total: string;
+  currency: string;
+  status: string;
+  created_at: string;
+}
+
+export type BillingHistoryResult =
+  | { ok: true; invoices: BillingHistoryInvoice[] }
+  | { ok: false };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function readString(record: Record<string, unknown>, key: string): string | null {
+  const value = record[key];
+  return typeof value === 'string' ? value : null;
+}
+
+/**
+ * `GET /subscriptions/:uniqid/billing-history`, narrowed.
+ *
+ * The SDK hands this back as `unknown` because `@shoppex/contracts` defines no
+ * schema for it, so the narrowing lives here — with a test against the shape
+ * `SubscriptionService.getBillingHistory` really emits. A row missing any of
+ * these fields fails the whole read rather than rendering an invoice with a
+ * blank amount, which is the one thing a billing history must never do.
+ */
+export function narrowBillingHistory(payload: unknown): BillingHistoryResult {
+  if (!isRecord(payload) || !Array.isArray(payload.invoices)) return { ok: false };
+
+  const invoices: BillingHistoryInvoice[] = [];
+  for (const entry of payload.invoices) {
+    if (!isRecord(entry)) return { ok: false };
+
+    const uniqid = readString(entry, 'uniqid');
+    const total = readString(entry, 'total');
+    const currency = readString(entry, 'currency');
+    const status = readString(entry, 'status');
+    const createdAt = readString(entry, 'created_at');
+    if (uniqid === null || total === null || currency === null || status === null || createdAt === null) {
+      return { ok: false };
+    }
+
+    invoices.push({ uniqid, total, currency, status, created_at: createdAt });
+  }
+
+  return { ok: true, invoices };
+}
+

package/eject/account/account-support.ts

@@ -0,0 +1,155 @@
+/**
+ * The support panel's pure half: the ticket thread's shape, what closes a
+ * ticket, and what counts as a message worth sending.
+ */
+
+export type SupportMessageRole = 'CUSTOMER' | 'MERCHANT' | 'SYSTEM';
+
+export interface SupportMessage {
+  id: string;
+  /** 'CUSTOMER' | 'MERCHANT' | 'SYSTEM' as the producer stores it. */
+  role: SupportMessageRole;
+  message: string;
+  created_at: string;
+}
+
+export interface SupportTicket {
+  uniqid: string;
+  /** Null when the ticket was opened without one. */
+  title: string | null;
+  status: string;
+  /** The order this ticket is about, when the buyer named one. */
+  invoice_id: string | null;
+  created_at: string;
+  updated_at: string;
+  messages: SupportMessage[];
+}
+
+export type SupportTicketResult =
+  | { ok: true; ticket: SupportTicket }
+  | { ok: false };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function readNullableString(record: Record<string, unknown>, key: string): string | null | undefined {
+  const value = record[key];
+  if (value === null || typeof value === 'string') return value;
+  return undefined;
+}
+
+function isSupportMessageRole(value: unknown): value is SupportMessageRole {
+  return value === 'CUSTOMER' || value === 'MERCHANT' || value === 'SYSTEM';
+}
+
+/**
+ * `GET /tickets/:uniqid`, narrowed.
+ *
+ * The producer nests the ticket one level down (`{ ticket: { … } }`) and its
+ * messages come back as a flat, already-ordered array. A thread that cannot be
+ * read completely is not shown at all: a conversation missing a message reads
+ * as the merchant never answering.
+ */
+export function narrowSupportTicket(payload: unknown): SupportTicketResult {
+  if (!isRecord(payload) || !isRecord(payload.ticket)) return { ok: false };
+
+  const raw = payload.ticket;
+  const uniqid = raw.uniqid;
+  const title = readNullableString(raw, 'title');
+  const status = raw.status;
+  const invoiceId = readNullableString(raw, 'invoice_id');
+  const createdAt = raw.created_at;
+  const updatedAt = raw.updated_at;
+
+  if (
+    typeof uniqid !== 'string'
+    || title === undefined
+    || typeof status !== 'string'
+    || invoiceId === undefined
+    || typeof createdAt !== 'string'
+    || typeof updatedAt !== 'string'
+    || !Array.isArray(raw.messages)
+  ) {
+    return { ok: false };
+  }
+
+  const messages: SupportMessage[] = [];
+  for (const entry of raw.messages) {
+    if (!isRecord(entry)) return { ok: false };
+    const { id, role, message, created_at: messageCreatedAt } = entry;
+    if (
+      typeof id !== 'string'
+      || !isSupportMessageRole(role)
+      || typeof message !== 'string'
+      || typeof messageCreatedAt !== 'string'
+    ) {
+      return { ok: false };
+    }
+    messages.push({ id, role, message, created_at: messageCreatedAt });
+  }
+
+  return {
+    ok: true,
+    ticket: {
+      uniqid,
+      title,
+      status,
+      invoice_id: invoiceId,
+      created_at: createdAt,
+      updated_at: updatedAt,
+      messages,
+    },
+  };
+}
+
+/**
+ * A closed ticket takes no replies — the producer answers 400 for one — so the
+ * form is replaced rather than left to fail on submit.
+ */
+export function isTicketClosed(status: string): boolean {
+  return status.trim().toUpperCase() === 'CLOSED';
+}
+
+/**
+ * Whether there is a message here at all.
+ *
+ * Two characters, matching the hosted portal, and measured after trimming: a
+ * field holding three spaces is an empty ticket that costs the merchant a
+ * notification and the buyer an answer to nothing.
+ */
+export function isSendableMessage(value: string): boolean {
+  return value.trim().length >= 2;
+}
+
+/** The title to send, or nothing at all when the buyer left it blank. */
+export function ticketTitleToSend(value: string): string | undefined {
+  const title = value.trim();
+  return title.length > 0 ? title : undefined;
+}
+
+/** Who wrote a message, as a catalog key. */
+export function messageAuthorKey(role: SupportMessageRole): string {
+  if (role === 'CUSTOMER') return 'support.fromYou';
+  if (role === 'SYSTEM') return 'support.fromSystem';
+  return 'support.fromMerchant';
+}
+
+/**
+ * The id of a ticket that was just created, or null when the response did not
+ * carry one.
+ *
+ * `POST /tickets` answers `{ uniqid }` and the panel opens that thread next.
+ * Without an id there is nothing to open, and guessing one would send the buyer
+ * to somebody else's ticket or to a 404 dressed as their own.
+ */
+export function readCreatedTicketUniqid(data: unknown): string | null {
+  if (!isRecord(data)) return null;
+  const uniqid = data.uniqid;
+  return typeof uniqid === 'string' && uniqid.length > 0 ? uniqid : null;
+}
+
+/** Whether this message sits on the buyer's side of the thread. */
+export function isOwnMessage(role: SupportMessageRole): boolean {
+  return role === 'CUSTOMER';
+}