@shoppexio/storefront-react 0.0.0 → 0.1.0

package/eject/account/account-page.tsx

@@ -0,0 +1,410 @@
+import { useEffect, useState, type ComponentType, type ReactElement, type ReactNode } from 'react';
+import { Link, Navigate, useLocation } from 'react-router-dom';
+import {
+  isAccountTabOffered,
+  type AccountAvailability,
+} from './account-availability';
+import {
+  IMPLEMENTED_ACCOUNT_TABS,
+  accountTabHref,
+  accountTabLabelKey,
+  canonicalAccountPath,
+  resolveAccountView,
+  type AccountTab,
+  type AccountView,
+  type ImplementedAccountTab,
+} from '@shoppexio/storefront-react';
+import { captureAccountResellerInvite } from './account-reseller-invite';
+import {
+  takeAccountSignInPrefill,
+  type AccountSignInPrefill,
+} from './account-signin-link';
+import { callCustomerApi } from './customer-account';
+import { t } from './i18n';
+import {
+  AccountShellProvider,
+  useAccountAvailability,
+  useAccountShellReads,
+} from './dashboard';
+import { AccountDownloads } from './downloads';
+import { AccountFavorites } from './favorites';
+import { AccountLogin } from './login';
+import { AccountOrderDetail, AccountOrders } from './orders';
+import { AccountOverview } from './overview';
+import { AccountReferrals } from './referrals';
+import { AccountReseller } from './reseller';
+import { AccountRewards } from './rewards';
+import { AccountSettings } from './settings';
+import { AccountSubscriptions } from './subscriptions';
+import { AccountSupport } from './support';
+import { AccountEmpty, AccountError, AccountRowsSkeleton, BusySpinner } from './shared';
+
+/**
+ * The customer account, served from this storefront's own build.
+ *
+ * ONE shell under `/dashboard`, with the panel as a path segment below it —
+ * `/dashboard/orders`, `/dashboard/orders/<uniqid>`. That is the platform's
+ * route shape and it is the same on every lane, so a link in an order email
+ * works whether the shop runs a document theme or either code storefront. The
+ * retired `?tab=`/`?order=` spelling is accepted and canonicalized here;
+ * nothing in this template writes it.
+ *
+ * The session is an HttpOnly cookie the Shoppex worker sets on the merchant's
+ * own host. This component cannot read it and does not try: it asks the API who
+ * is signed in, and renders the sign-in form when the answer is nobody.
+ */
+
+type SessionState =
+  | { status: 'checking' }
+  | { status: 'signed-out' }
+  | { status: 'signed-in' }
+  | { status: 'unknown'; message: string };
+
+/**
+ * The prefill for this page load, taken from the cookie the first time it is
+ * asked for.
+ *
+ * Module scope rather than a hook, because the cookie can be read exactly once:
+ * reading it deletes it, and React invokes a `useState` initializer twice under
+ * StrictMode. The second read would find an empty jar and null out a prefill the
+ * first read had already spent.
+ */
+let takenPrefill: AccountSignInPrefill | null | undefined;
+
+export function takeSignInPrefillOnce(): AccountSignInPrefill | null {
+  if (takenPrefill === undefined) takenPrefill = takeAccountSignInPrefill(document);
+  return takenPrefill;
+}
+
+/**
+ * Spend the prefill for good — component state AND the module memo.
+ *
+ * Clearing only the component's copy leaves the pair here for the next mount.
+ * This is a single-page app: the buyer walks off to a product, their session
+ * expires, they navigate back to `/dashboard`, and the page remounts from this
+ * cache — putting the old address and a long-dead code back in the form for
+ * whoever is at the browser.
+ */
+export function spendSignInPrefill(): null {
+  takenPrefill = null;
+  return null;
+}
+
+/** `?tab=` and `?order=` are this route's to drop; everything else is not. */
+function remainingSearch(search: URLSearchParams): string {
+  const kept = new URLSearchParams(search);
+  kept.delete('tab');
+  kept.delete('order');
+  // `invoice` is the portal's spelling for `order` and `canonicalAccountPath`
+  // counts it as legacy too, so leaving it here would re-trigger this very
+  // redirect on the next render — the loop the paragraph above warns about.
+  kept.delete('invoice');
+  const query = kept.toString();
+  return query ? `?${query}` : '';
+}
+
+/** What the host storefront hands the account. */
+export interface AccountPageProps {
+  /**
+   * The storefront's own page chrome around the account: the same column,
+   * gutter and rhythm every other page renders into. The account draws
+   * everything inside it and nothing around it.
+   */
+  frame: ComponentType<{ children: ReactNode }>;
+  /**
+   * What a path under the account that names no account surface renders —
+   * the storefront's own not-found page, so a mistyped link looks like every
+   * other missing page on the shop.
+   */
+  notFound: ReactNode;
+}
+
+export function AccountPage({ frame: Frame, notFound }: AccountPageProps) {
+  const location = useLocation();
+  const search = new URLSearchParams(location.search);
+  const canonical = canonicalAccountPath(location.pathname, search);
+  const view = resolveAccountView(location.pathname, search);
+  const [session, setSession] = useState<SessionState>({ status: 'checking' });
+  const [signOutError, setSignOutError] = useState<string | null>(null);
+  const [signingOut, setSigningOut] = useState(false);
+  const [probeToken, setProbeToken] = useState(0);
+  const [prefill, setPrefill] = useState(takeSignInPrefillOnce);
+
+  useEffect(() => {
+    let active = true;
+
+    // An artifact-owned account receives the reseller invitation in the URL —
+    // the worker only mints the cookie for platform-rendered surfaces. Move it
+    // into the cookie before anything else, so the sign-in navigation that may
+    // follow (a new tab included) cannot lose it. Idempotent under StrictMode.
+    captureAccountResellerInvite(document, window);
+
+    /*
+     * The session probe.
+     *
+     * Only a 401 means "not signed in". A 403, a 5xx, a contract mismatch or a
+     * network error with no status at all means the answer is UNKNOWN, and
+     * showing the sign-in form there tells a buyer whose session is still live
+     * that they have been signed out. Those get an error and a retry.
+     *
+     * The opposite must never happen either: a failed probe treated as a
+     * signed-in customer would render an account shell around data that was
+     * never fetched.
+     */
+    void callCustomerApi((sdk) => sdk.me()).then((result) => {
+      if (!active) return;
+
+      if (result.success) {
+        // Already signed in, so the link's code was never needed — and neither
+        // a later sign-out nor a remount may bring it back.
+        setPrefill(spendSignInPrefill());
+        setSession({ status: 'signed-in' });
+        return;
+      }
+
+      if (result.status === 401) {
+        setSession({ status: 'signed-out' });
+        return;
+      }
+
+      setSession({
+        status: 'unknown',
+        message: result.message?.trim() || t('account.sessionUnknown'),
+      });
+    });
+
+    return () => {
+      active = false;
+    };
+  }, [probeToken]);
+
+  const signOut = async () => {
+    setSigningOut(true);
+    setSignOutError(null);
+    const result = await callCustomerApi((sdk) => sdk.logout());
+    setSigningOut(false);
+
+    // The worker clears the session cookie on every response it produces, even
+    // a 500 from the backend — so an ANSWERED request means the buyer really is
+    // signed out, whatever the status says. Only a result with no status at all
+    // means nothing reached the edge: the cookie is still there, the session is
+    // still live, and a signed-out page would be a lie the next reload exposes.
+    if (!result.success && result.status === undefined) {
+      setSignOutError(result.message?.trim() || t('account.signOutFailed'));
+      return;
+    }
+    setSession({ status: 'signed-out' });
+  };
+
+  /*
+   * A retired spelling is rewritten before anything renders — replace, not
+   * push, so the back button leaves the account rather than bouncing between
+   * two spellings of one panel. Returning the redirect here rather than running
+   * it from an effect also means the panel below mounts once, on the canonical
+   * URL, instead of loading its data twice.
+   */
+  if (canonical !== null) return <Navigate to={`${canonical}${remainingSearch(search)}`} replace />;
+
+  /*
+   * A path naming no account surface is NOT this route (ADR-0064), and it is
+   * answered before anything asks who is signed in. Answering it inside the
+   * account meant a buyer who followed a mistyped link was shown a sign-in form
+   * first and only told the link was broken after they had used it — a password
+   * prompt standing in front of a 404.
+   */
+  if (view.kind === 'unknown-tab') return <>{notFound}</>;
+
+  return (
+    <Frame>
+      <section className="sx-account sxa:space-y-8 sxa:py-6 sxa:md:py-8" data-sx-account-session={session.status}>
+        <div className="sx-account-header sxa:flex sxa:flex-wrap sxa:items-end sxa:justify-between sxa:gap-4">
+          <h1 className="sx-account-title sxa:font-heading sxa:text-h1">
+            {t('account.title')}
+          </h1>
+          {session.status === 'signed-in' ? (
+            <button
+              type="button"
+              onClick={() => void signOut()}
+              disabled={signingOut}
+              aria-busy={signingOut || undefined}
+              className="sx-account-signout sx-account-button sxa:card-button sxa:card-button--add sxa:disabled:cursor-not-allowed sxa:disabled:opacity-50"
+            >
+              {signingOut ? <BusySpinner className="sxa:mr-1.5 sxa:h-3.5 sxa:w-3.5" /> : null}
+              {signingOut ? t('account.signingOut') : t('account.signOut')}
+            </button>
+          ) : null}
+        </div>
+
+        {session.status === 'checking' ? (
+          <AccountRowsSkeleton rows={3} label={t('account.checkingSession')} />
+        ) : null}
+
+        {session.status === 'signed-out' ? (
+          <AccountLogin
+            prefill={prefill}
+            onSignedIn={() => {
+              // Spent. Without this the pair outlives the sign-in — here and in
+              // the module memo behind it — so signing out, or navigating away
+              // and back, remounts the form with the previous buyer's address
+              // and their already-used code.
+              setPrefill(spendSignInPrefill());
+              setSession({ status: 'signed-in' });
+            }}
+          />
+        ) : null}
+
+        {session.status === 'unknown' ? (
+          <div className="sxa:mx-auto sxa:w-full sxa:max-w-md">
+            <AccountError
+              message={session.message}
+              onRetry={() => {
+                setSession({ status: 'checking' });
+                setProbeToken((token) => token + 1);
+              }}
+            />
+          </div>
+        ) : null}
+
+        {session.status === 'signed-in' ? (
+          <SignedInAccount view={view} signOutError={signOutError} />
+        ) : null}
+      </section>
+    </Frame>
+  );
+}
+
+/**
+ * Everything below the sign-in: the shell's two reads, the gated navigation,
+ * and the panel.
+ *
+ * Its own component because the reads have to sit ABOVE both the navigation and
+ * the panel — the navigation gates on them and seven panels are built from the
+ * dashboard payload. They used to be loaded by each panel separately, which is
+ * why the shell had nothing to gate with.
+ */
+function SignedInAccount({
+  view,
+  signOutError,
+}: {
+  view: AccountView;
+  signOutError: string | null;
+}) {
+  /*
+   * The surface being shown, and therefore what the shell's reads are keyed on.
+   * An order detail rides on the orders key: it loads its own order and needs
+   * nothing re-read to show it.
+   */
+  const panelKey = view.kind === 'panel' ? view.tab : 'orders';
+  const reads = useAccountShellReads(panelKey);
+  const availability = useAccountAvailability(reads);
+
+  return (
+    <AccountShellProvider value={reads}>
+      {signOutError ? <AccountError message={signOutError} /> : null}
+      <AccountNav view={view} availability={availability} />
+      <div className="sx-account-panel" data-sx-account-view={view.kind === 'panel' ? view.tab : view.kind}>
+        <AccountPanel view={view} />
+      </div>
+    </AccountShellProvider>
+  );
+}
+
+/**
+ * The tabs this storefront offers this customer.
+ *
+ * Gated, because ADR-0064 names the portal's `visibleSections()` model as
+ * contract and requires it reproduced rather than simplified away — the
+ * document lane reproduces it, so a code storefront that did not would show a
+ * Referrals tab to a buyer whose shop runs no programme while the very same
+ * shop on the other lane hides it. The rules live in `account-availability.ts`;
+ * this only draws what they admit.
+ */
+function AccountNav({
+  view,
+  availability,
+}: {
+  view: AccountView;
+  availability: AccountAvailability | null;
+}) {
+  const activeTab: AccountTab | null = view.kind === 'panel'
+    ? view.tab
+    : view.kind === 'order'
+      ? 'orders'
+      : null;
+
+  return (
+    <nav className="sx-account-nav sxa:flex sxa:flex-wrap sxa:gap-1" aria-label={t('account.sections')}>
+      {IMPLEMENTED_ACCOUNT_TABS
+        .filter((tab) => isAccountTabOffered(tab, availability, activeTab))
+        .map((tab) => (
+          <Link
+            key={tab}
+            to={accountTabHref(tab)}
+            aria-current={activeTab === tab ? 'page' : undefined}
+            className={`sx-account-nav-link sxa:nav-link sxa:rounded-input sxa:px-3 sxa:py-1.5 sxa:text-small ${activeTab === tab ? 'sxa:nav-link--active' : ''}`}
+          >
+            {t(accountTabLabelKey(tab))}
+          </Link>
+        ))}
+    </nav>
+  );
+}
+
+/**
+ * Every implemented tab, and its panel.
+ *
+ * A record rather than a switch with a default: the key type is
+ * `ImplementedAccountTab`, so adding a tab to that list without building its
+ * panel stops the build. A default branch would instead quietly answer the new
+ * tab with the overview, which is the "looks like the link worked" failure the
+ * route module exists to prevent.
+ */
+const ACCOUNT_PANELS: Readonly<Record<ImplementedAccountTab, () => ReactElement>> = {
+  overview: () => <AccountOverview />,
+  orders: () => <AccountOrders />,
+  downloads: () => <AccountDownloads />,
+  subscriptions: () => <AccountSubscriptions />,
+  rewards: () => <AccountRewards />,
+  referrals: () => <AccountReferrals />,
+  favorites: () => <AccountFavorites />,
+  support: () => <AccountSupport />,
+  settings: () => <AccountSettings />,
+  reseller: () => <AccountReseller />,
+};
+
+function AccountPanel({ view }: { view: AccountView }) {
+  switch (view.kind) {
+    case 'panel':
+      return ACCOUNT_PANELS[view.tab]();
+    case 'order':
+      return <AccountOrderDetail orderId={view.orderId} />;
+    case 'not-built':
+      /*
+       * A real platform tab this storefront does not render. Said plainly
+       * rather than answered with the overview, which would look like the link
+       * worked and leave the buyer hunting for something that is not there.
+       */
+      return (
+        <AccountEmpty
+          title={t('account.notBuilt.title', { tab: t(accountTabLabelKey(view.tab)) })}
+          body={t('account.notBuilt.body')}
+          action={<OverviewLink />}
+        />
+      );
+    case 'unknown-tab':
+      // Answered above, before the session is even read. Unreachable here, and
+      // the compiler holds the switch exhaustive so it cannot be dropped.
+      return null;
+  }
+}
+
+function OverviewLink() {
+  return (
+    <Link
+      to={accountTabHref('overview')}
+      className="sx-account-cta sxa:cta-button sxa:inline-flex sxa:h-10 sxa:items-center sxa:px-5 sxa:text-small"
+    >
+      {t('account.goToOverview')}
+    </Link>
+  );
+}

package/eject/account/account-payment-method.ts

@@ -0,0 +1,99 @@
+/**
+ * What the buyer paid with, in the buyer's vocabulary.
+ *
+ * The producer sends two different things: the internal rail (`gateway` —
+ * NATIVE_CRYPTO, NOWPAYMENTS, CRYPTOMUS…) and the concrete method the buyer
+ * actually chose (`apmMethod`, `cryptoGateway`). Someone who paid in USDT
+ * never picked "NOWPAYMENTS" and does not recognise the word — showing the
+ * rail names a company they never dealt with.
+ *
+ * The precedence is the customer portal's, kept identical on purpose: this
+ * account page replaces the portal, and a buyer's order history must not
+ * change wording underneath them at cutover.
+ */
+
+const GATEWAY_LABELS: Record<string, string> = {
+  STRIPE: 'Stripe',
+  PAYPAL: 'PayPal',
+  CASHAPP: 'Cash App',
+  SQUARE: 'Square',
+  BITCOIN: 'Bitcoin',
+  LITECOIN: 'Litecoin',
+  ETHEREUM: 'Ethereum',
+  SOLANA: 'Solana',
+  CONCORDIUM: 'Concordium',
+  NANO: 'Nano',
+  MONERO: 'Monero',
+  BALANCE: 'Store Balance',
+  MOLLIE: 'Mollie',
+  LEX_PAYMENTS: 'Lex Payments',
+  SELLIX_PAY: 'Sellix Pay',
+  // Internal crypto rails — buyers see the coin (via cryptoGateway) or the
+  // generic "Crypto", never rail or provider vocabulary.
+  NATIVE_CRYPTO: 'Crypto',
+  NOWPAYMENTS: 'Crypto',
+  NOWPAYMENTS_WHITELABEL: 'Crypto',
+  OXAPAY: 'Crypto',
+  CRYPTOMUS: 'Crypto',
+};
+
+const CRYPTO_COIN_LABELS: Record<string, string> = {
+  BITCOIN: 'Bitcoin',
+  BITCOIN_CASH: 'Bitcoin Cash',
+  BITCOIN_LN: 'Lightning',
+  LITECOIN: 'Litecoin',
+  ETHEREUM: 'Ethereum',
+  SOLANA: 'Solana',
+  MONERO: 'Monero',
+  TRON: 'Tron',
+  POLYGON: 'Polygon',
+  BINANCE_COIN: 'BNB',
+  RIPPLE: 'Ripple',
+  DOGECOIN: 'Dogecoin',
+  DASH: 'Dash',
+  CRONOS: 'Cronos',
+  NANO: 'Nano',
+};
+
+const NOWPAYMENTS_DYNAMIC_PREFIX = 'NOWPAYMENTS:';
+const NOWPAYMENTS_CURRENCY_CODE = /^[A-Z0-9]{2,12}$/;
+
+/** `NOWPAYMENTS:ton` → `TON`. The prefix is the provider, never buyer-facing. */
+function parseDynamicNowPaymentsCurrency(gateway: string): string | null {
+  const normalized = gateway.trim().toUpperCase();
+  if (!normalized.startsWith(NOWPAYMENTS_DYNAMIC_PREFIX)) return null;
+  const code = normalized.slice(NOWPAYMENTS_DYNAMIC_PREFIX.length);
+  return NOWPAYMENTS_CURRENCY_CODE.test(code) ? code : null;
+}
+
+/** `USDT_TRC20` → `USDT (TRC20)`; known chains map to their display names. */
+export function cryptoCoinLabel(coinKey: string): string {
+  const dynamic = parseDynamicNowPaymentsCurrency(coinKey);
+  if (dynamic) return dynamic;
+  const upper = coinKey.trim().toUpperCase();
+  if (CRYPTO_COIN_LABELS[upper]) return CRYPTO_COIN_LABELS[upper];
+  const [symbol, ...network] = upper.split(/[_:]+/);
+  return network.length > 0 ? `${symbol} (${network.join(' ')})` : symbol;
+}
+
+export type PaymentMethodSource = {
+  /** The internal rail. Only ever shown when nothing more concrete exists. */
+  gateway: string;
+  displayName: string | null;
+  cryptoGateway: string | null;
+  blockchain: string | null;
+  apmMethod: string | null;
+};
+
+/**
+ * displayName → apmMethod → coin → rail label. Each step is more specific
+ * about what the buyer chose than the one after it.
+ */
+export function paymentMethodLabel(payment: PaymentMethodSource): string {
+  if (payment.displayName) return payment.displayName;
+  if (payment.apmMethod) return payment.apmMethod;
+  // Crypto payments show the concrete coin; the rail stays internal.
+  if (payment.cryptoGateway) return cryptoCoinLabel(payment.cryptoGateway);
+  const base = GATEWAY_LABELS[payment.gateway] ?? payment.gateway;
+  return payment.blockchain ? `${base} (${payment.blockchain})` : base;
+}

package/eject/account/account-referrals.ts

@@ -0,0 +1,68 @@
+import type { SdkCustomerAffiliateLink, SdkCustomerAffiliateSummary } from '@shoppexio/storefront-react';
+
+/**
+ * The referrals panel's pure half.
+ *
+ * Read-only by design. Converting a referral balance into store credit and
+ * requesting a payout both move money toward the buyer, and ADR-0064 keeps
+ * money paths off the account API for good — theme code shares the origin with
+ * the session cookie, so an allowlisted payout endpoint would be a transaction
+ * primitive sitting next to untrusted markup. The panel therefore shows what
+ * has been earned and says where the payout is arranged.
+ *
+ * Nothing here adds two balances together either. The server sends five
+ * figures; summing them into a friendlier one produces a number no other
+ * surface agrees with.
+ */
+
+/**
+ * Whether the buyer is in the programme at all.
+ *
+ * `not_enrolled` is the availability gate the hosted portal used to hide the
+ * whole tab. This template keeps the tab reachable — its link may already be in
+ * a sent email — and answers with the state instead, which tells the buyer
+ * something true rather than showing an empty balance sheet.
+ */
+export function isEnrolledInReferrals(summary: SdkCustomerAffiliateSummary): boolean {
+  return summary.state !== 'not_enrolled';
+}
+
+/**
+ * The link a buyer shares, or null when the server built none.
+ *
+ * The URL is the server's: it knows the shop's own storefront host. Assembling
+ * one here out of the current origin would hand out a link that works from
+ * wherever the buyer happens to be standing, including a preview host.
+ */
+export function referralShareUrl(link: SdkCustomerAffiliateLink): string | null {
+  const url = link.url?.trim();
+  return url ? url : null;
+}
+
+/** A link the shop has not approved yet earns nothing if it is shared today. */
+export function isAwaitingApproval(link: SdkCustomerAffiliateLink): boolean {
+  return link.status === 'pending';
+}
+
+const CLAIM_TYPE_KEYS: Readonly<Record<string, string>> = {
+  STORE_CREDIT: 'referrals.claimStoreCredit',
+  CRYPTO_PAYOUT_REQUEST: 'referrals.claimCryptoPayout',
+  MIGRATION_ADJUSTMENT: 'referrals.claimAdjustment',
+};
+
+/** Null for a claim type this catalog does not know — the raw value is shown. */
+export function claimTypeKey(type: string): string | null {
+  return CLAIM_TYPE_KEYS[type] ?? null;
+}
+
+/**
+ * Whether the referral balance is held in a different currency than the shop
+ * prices in, which is worth saying before a buyer compares the two numbers.
+ */
+export function isForeignBalanceCurrency(
+  summary: SdkCustomerAffiliateSummary,
+  shopCurrency: string,
+): boolean {
+  return summary.balance_currency.toUpperCase() !== shopCurrency.toUpperCase();
+}
+

package/eject/account/account-reseller-invite.ts

@@ -0,0 +1,88 @@
+/**
+ * The reseller invitation token, carried across sign-in as a cookie.
+ *
+ * On an artifact-owned account the edge worker deliberately leaves
+ * `reseller_invite` in the URL — this bundle is immutable merchant code, and an
+ * older build would otherwise watch the worker strip a token nobody reads.
+ * `captureAccountResellerInvite` is therefore this template's own handoff: it
+ * moves the token from the URL into the same `__Host-` cookie the worker mints
+ * for platform-rendered accounts, and scrubs the parameter before it can linger
+ * in history or a copied link.
+ *
+ * Reading is deliberately not consumption. A reload, a sign-in link opened in a
+ * new tab, or a session for another email must leave the token available while
+ * its one-hour cookie lives. Callers clear it explicitly after an accept
+ * attempt.
+ */
+
+/** Pinned to `workers/storefront/src/reseller-invite-link.ts`. */
+export const ACCOUNT_RESELLER_INVITE_COOKIE = '__Host-sx_reseller_invite';
+
+/** Pinned to the email producer (`ResellerEnrollmentEmailService`). */
+export const ACCOUNT_RESELLER_INVITE_PARAM = 'reseller_invite';
+
+const INVITE_TTL_SECONDS = 3600;
+
+const CLEAR_RESELLER_INVITE_COOKIE = `${ACCOUNT_RESELLER_INVITE_COOKIE}=; Path=/; Secure; SameSite=Lax; Max-Age=0`;
+
+export interface AccountResellerInviteCookieJar {
+  cookie: string;
+}
+
+/** The slice of `window` the capture needs; a seam for tests. */
+export interface AccountResellerInviteLocation {
+  location: { search: string; pathname: string; hash: string };
+  history: { replaceState(data: unknown, unused: string, url: string): void };
+}
+
+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;
+}
+
+function usableInviteToken(raw: string | null): string | null {
+  if (!raw || !/^[A-Za-z0-9_-]+$/.test(raw)) return null;
+  return raw;
+}
+
+/**
+ * Move a URL-borne invitation into the cookie, scrubbing the parameter.
+ *
+ * The scrub happens even for an unusable value — a malformed token has no
+ * business staying in the address bar either. Idempotent: a second call finds
+ * no parameter and does nothing, so a StrictMode double-mount is harmless.
+ */
+export function captureAccountResellerInvite(
+  jar: AccountResellerInviteCookieJar,
+  win: AccountResellerInviteLocation,
+): void {
+  const params = new URLSearchParams(win.location.search);
+  if (!params.has(ACCOUNT_RESELLER_INVITE_PARAM)) return;
+
+  const token = usableInviteToken(params.get(ACCOUNT_RESELLER_INVITE_PARAM));
+  params.delete(ACCOUNT_RESELLER_INVITE_PARAM);
+  const query = params.toString();
+  win.history.replaceState(
+    null,
+    '',
+    `${win.location.pathname}${query ? `?${query}` : ''}${win.location.hash}`,
+  );
+
+  if (!token) return;
+  jar.cookie = `${ACCOUNT_RESELLER_INVITE_COOKIE}=${token}; Path=/; Secure; SameSite=Lax; Max-Age=${INVITE_TTL_SECONDS}`;
+}
+
+/** Read without consuming; the producer's base64url token is already cookie-safe. */
+export function peekAccountResellerInvite(jar: AccountResellerInviteCookieJar): string | null {
+  return usableInviteToken(cookieValue(jar.cookie, ACCOUNT_RESELLER_INVITE_COOKIE));
+}
+
+/** Clear after an accept attempt, with the same `__Host-` attributes as the producer. */
+export function clearAccountResellerInvite(jar: AccountResellerInviteCookieJar): void {
+  jar.cookie = CLEAR_RESELLER_INVITE_COOKIE;
+}