@shoppexio/storefront-react 0.0.0 → 0.1.0

package/eject/account/account-availability.ts

@@ -0,0 +1,171 @@
+/**
+ * Which account destinations this customer has anything behind.
+ *
+ * ADR-0064 names the gating model from the retired portal's `visibleSections()`
+ * as part of the contract, to be reproduced rather than simplified away, and
+ * the document lane reproduces it in
+ * `packages/storefront-commerce/src/sx/account-nav-core.ts`. This is the same
+ * model for the code lane. It is a separate module, not a few conditions inside
+ * the navigation, because the rules are a contract two lanes have to agree on —
+ * and because a rule inside JSX is a rule no test can read.
+ *
+ * The counters come off the ONE `dashboard()` payload the shell already loads,
+ * so gating costs no request. `reseller` is the exception: it lives behind its
+ * own read and is passed in.
+ *
+ * Two leaves are deliberately ungated, and the reasoning is the portal's:
+ *
+ * - `rewards` — the dashboard assigns the rewards object unconditionally and
+ *   the producer returns a zeroed summary when there is nothing to report, so
+ *   its presence carries no information. Gating it would need a programme flag
+ *   the payload does not send; inferring one is the invented value the repo's
+ *   fallback policy prohibits.
+ * - `favorites` — offered to every customer.
+ */
+
+import type { ResellerProgramState } from './account-reseller';
+import type { AccountTab } from '@shoppexio/storefront-react';
+
+/** The signals a gate is decided on, read off the dashboard payload. */
+export interface AccountAvailabilitySource {
+  licensesCount: number;
+  deliverablesCount: number;
+  subscriptionsCount: number;
+  walletPresent: boolean;
+  affiliateState: string;
+}
+
+export interface AccountAvailability {
+  downloads: boolean;
+  subscriptions: boolean;
+  wallet: boolean;
+  rewards: boolean;
+  referrals: boolean;
+  favorites: boolean;
+  reseller: boolean;
+}
+
+/**
+ * The gate each tab hangs on. `always` is the four leaves every customer has:
+ * the overview, their orders, support and their own settings.
+ *
+ * `wallet` is in the gate set but is NOT a tab — it is the embedded section
+ * inside the overview, gated on the same signal.
+ */
+export type AccountGate =
+  | 'always'
+  | 'downloads'
+  | 'subscriptions'
+  | 'wallet'
+  | 'rewards'
+  | 'referrals'
+  | 'favorites'
+  | 'reseller';
+
+const TAB_GATES: Readonly<Record<AccountTab, AccountGate>> = {
+  overview: 'always',
+  orders: 'always',
+  support: 'always',
+  settings: 'always',
+  downloads: 'downloads',
+  subscriptions: 'subscriptions',
+  rewards: 'rewards',
+  referrals: 'referrals',
+  favorites: 'favorites',
+  reseller: 'reseller',
+};
+
+export function accountTabGate(tab: AccountTab): AccountGate {
+  return TAB_GATES[tab];
+}
+
+export function accountAvailabilityFrom(
+  source: AccountAvailabilitySource,
+  reseller: ResellerProgramState | null,
+): AccountAvailability {
+  return {
+    downloads: source.licensesCount > 0 || source.deliverablesCount > 0,
+    subscriptions: source.subscriptionsCount > 0,
+    wallet: source.walletPresent,
+    rewards: true,
+    referrals: source.affiliateState !== 'not_enrolled',
+    favorites: true,
+    reseller: accountResellerAvailable(reseller),
+  };
+}
+
+/**
+ * A shop with no programme has no wholesale surface. One that enrolls by
+ * invitation only (`MANUAL`) shows the tab to the invited and to nobody else;
+ * an `APPLICATION` or `OPEN` programme shows it to everyone, because applying
+ * is the point of the tab.
+ */
+export function accountResellerAvailable(program: ResellerProgramState | null): boolean {
+  if (!program?.program_enabled) return false;
+  return program.reseller !== null || program.enrollment_mode.toUpperCase() !== 'MANUAL';
+}
+
+/**
+ * What the navigation may offer given what has answered SO FAR.
+ *
+ * Pure, and separate from the hook that calls it, because the sequencing is the
+ * part that was wrong: the dashboard gates were made to wait on the reseller
+ * read, so a slow wholesale endpoint emptied a navigation it has nothing to do
+ * with. Three rules, each of which a test can hold:
+ *
+ * - the dashboard gates are decided the moment the dashboard answers, and never
+ *   wait on anything else;
+ * - a reseller programme that has not answered, or failed to, leaves that one
+ *   gate shut — it is an unanswered question, not a shop without a programme;
+ * - while a revalidation is in flight the last known answer stands, so moving
+ *   between panels does not empty the navigation and refill it.
+ */
+export function availabilityFromShellReads(
+  dashboard: AccountAvailabilitySource | null,
+  program: ResellerProgramState | null,
+  lastKnown: AccountAvailability | null,
+): AccountAvailability | null {
+  if (dashboard === null) return lastKnown;
+
+  const availability = accountAvailabilityFrom(dashboard, program);
+
+  /*
+   * The two reads revalidate together and answer separately. When the dashboard
+   * lands first, this used to recompute the wholesale gate as shut — so an
+   * eligible buyer moving from the overview to their orders watched the
+   * Wholesale tab vanish and come back a moment later. Holding the previous
+   * answer for that one gate is not inventing a value: it is the last thing the
+   * producer actually said, kept until it says otherwise. On a first load there
+   * is nothing to hold and the gate stays shut.
+   */
+  if (program === null && lastKnown !== null) {
+    return { ...availability, reseller: lastKnown.reseller };
+  }
+
+  return availability;
+}
+
+/**
+ * Whether a tab is offered.
+ *
+ * The active tab is never hidden — that rule is named in ADR-0064 and it is
+ * what keeps a buyer who followed a link from an order email from finding the
+ * navigation missing the very page they are standing on. Hiding it would leave
+ * them looking at a panel with no way back to it.
+ */
+export function isAccountTabOffered(
+  tab: AccountTab,
+  availability: AccountAvailability | null,
+  activeTab: AccountTab | null,
+): boolean {
+  if (tab === activeTab) return true;
+
+  const gate = accountTabGate(tab);
+  if (gate === 'always') return true;
+
+  // Nothing has answered yet. A gated leaf stays hidden rather than appearing
+  // and then vanishing under the buyer's cursor a moment later.
+  if (availability === null) return false;
+
+  return availability[gate];
+}

package/eject/account/account-downloads.ts

@@ -0,0 +1,118 @@
+import type { SdkCustomerDeliverable, SdkCustomerLicense } from '@shoppexio/storefront-react';
+
+/**
+ * The downloads panel's pure half.
+ *
+ * The panel renders two lists that arrive as one: `deliverables` is what the
+ * shop handed over (keys, files, codes), `licenses` is the standing of each
+ * license behind those keys. They are joined on the `license:<uniqid>` id the
+ * producer builds in `buildCustomerPortalDeliverables`, and that join is the
+ * only place the two payloads meet.
+ */
+
+export const LICENSE_DELIVERABLE_PREFIX = 'license:';
+
+export interface LicenseDownload {
+  deliverable: SdkCustomerDeliverable;
+  license: SdkCustomerLicense;
+}
+
+/** A file deliverable, narrowed: a file with nothing to fetch never gets here. */
+export interface FileDownload extends SdkCustomerDeliverable {
+  href: string;
+}
+
+export interface DownloadGroups {
+  /** License keys, each paired with the license row that describes it. */
+  licenses: LicenseDownload[];
+  /** Files, each with a same-origin download path. */
+  files: FileDownload[];
+  /** Codes and access links delivered with an order. */
+  codes: SdkCustomerDeliverable[];
+}
+
+/**
+ * Why a payload could not be listed.
+ *
+ * Both cases are the producer contradicting itself, not a buyer with nothing
+ * to download: a license key whose license is missing, and a file with nothing
+ * to fetch. Neither is rendered as a blank row — a buyer told "here is your
+ * file" with no way to get it has been lied to, and a licence with no expiry
+ * shown might be an expiry that was never read.
+ */
+export type DownloadContractError =
+  | { reason: 'license-missing'; id: string }
+  | { reason: 'file-without-link'; id: string };
+
+export type DownloadGroupsResult =
+  | { ok: true; groups: DownloadGroups }
+  | { ok: false; error: DownloadContractError };
+
+/** The license uniqid a `license:` deliverable names, or null for other kinds. */
+export function licenseUniqidFromDeliverable(deliverable: SdkCustomerDeliverable): string | null {
+  if (deliverable.kind !== 'license') return null;
+  if (!deliverable.id.startsWith(LICENSE_DELIVERABLE_PREFIX)) return null;
+  const uniqid = deliverable.id.slice(LICENSE_DELIVERABLE_PREFIX.length);
+  return uniqid.length > 0 ? uniqid : null;
+}
+
+export function buildDownloadGroups(
+  deliverables: readonly SdkCustomerDeliverable[],
+  licenses: readonly SdkCustomerLicense[],
+): DownloadGroupsResult {
+  const licensesByUniqid = new Map(licenses.map((license) => [license.uniqid, license]));
+  const groups: DownloadGroups = { licenses: [], files: [], codes: [] };
+
+  for (const deliverable of deliverables) {
+    if (deliverable.kind === 'license') {
+      const uniqid = licenseUniqidFromDeliverable(deliverable);
+      const license = uniqid === null ? undefined : licensesByUniqid.get(uniqid);
+      if (!license) return { ok: false, error: { reason: 'license-missing', id: deliverable.id } };
+      groups.licenses.push({ deliverable, license });
+      continue;
+    }
+
+    if (deliverable.kind === 'file') {
+      if (!deliverable.href) {
+        return { ok: false, error: { reason: 'file-without-link', id: deliverable.id } };
+      }
+      groups.files.push({ ...deliverable, href: deliverable.href });
+      continue;
+    }
+
+    groups.codes.push(deliverable);
+  }
+
+  return { ok: true, groups };
+}
+
+export function isEmptyDownloadGroups(groups: DownloadGroups): boolean {
+  return groups.licenses.length === 0 && groups.files.length === 0 && groups.codes.length === 0;
+}
+
+/**
+ * A license's end date.
+ *
+ * `expires_at` is EPOCH SECONDS and `null` means the license never ends — a
+ * different statement from "we could not read the expiry", which is why this
+ * returns `null` only for the first and nothing else can produce it.
+ */
+export function licenseExpiryDate(license: SdkCustomerLicense): Date | null {
+  if (license.expires_at === null) return null;
+  return new Date(license.expires_at * 1000);
+}
+
+/**
+ * Whether to offer the buyer a way to renew.
+ *
+ * Both halves are required. `renewable` alone would offer a renewal on a
+ * perpetual license, which would hand it an end date it never had; an expiry
+ * alone would offer one for a product that has stopped selling.
+ *
+ * The offer is a link into the store, never a call: a renewal is a purchase,
+ * and purchases carry their authorisation in checkout (ADR-0064).
+ */
+export function offersRenewal(license: SdkCustomerLicense): boolean {
+  return license.renewable && license.expires_at !== null;
+}
+

package/eject/account/account-favorites.ts

@@ -0,0 +1,99 @@
+/**
+ * The favorites panel's pure half.
+ *
+ * `GET /favorites` is one of the endpoints `@shoppex/contracts` does not
+ * describe, so the SDK answers `unknown` and the narrowing is here, written
+ * against what `customer-favorites.ts` actually selects. Every field it sends
+ * is required: a saved product with no title and no price is not a favorite the
+ * buyer can act on, and rendering it as an empty card would hide the fault.
+ */
+
+export interface CustomerFavorite {
+  product_uniqid: string;
+  title: string;
+  /** Null for a product with no slug — such a product has no page to open. */
+  slug: string | null;
+  image_url: string | null;
+  price_display: number;
+  /** True once the merchant deletes the product. The row stays, the link goes. */
+  unavailable: boolean;
+  created_at: string;
+}
+
+export type FavoritesResult =
+  | { ok: true; favorites: CustomerFavorite[] }
+  | { 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 narrowFavorites(payload: unknown): FavoritesResult {
+  if (!isRecord(payload) || !Array.isArray(payload.favorites)) return { ok: false };
+
+  const favorites: CustomerFavorite[] = [];
+  for (const entry of payload.favorites) {
+    if (!isRecord(entry)) return { ok: false };
+
+    const productUniqid = entry.product_uniqid;
+    const title = entry.title;
+    const slug = readNullableString(entry, 'slug');
+    const imageUrl = readNullableString(entry, 'image_url');
+    const priceDisplay = entry.price_display;
+    const unavailable = entry.unavailable;
+    const createdAt = entry.created_at;
+
+    if (
+      typeof productUniqid !== 'string'
+      || typeof title !== 'string'
+      || slug === undefined
+      || imageUrl === undefined
+      || typeof priceDisplay !== 'number'
+      || !Number.isFinite(priceDisplay)
+      || typeof unavailable !== 'boolean'
+      || typeof createdAt !== 'string'
+    ) {
+      return { ok: false };
+    }
+
+    favorites.push({
+      product_uniqid: productUniqid,
+      title,
+      slug,
+      image_url: imageUrl,
+      price_display: priceDisplay,
+      unavailable,
+      created_at: createdAt,
+    });
+  }
+
+  return { ok: true, favorites };
+}
+
+/**
+ * Where a saved product lives in this storefront, or null when it has nowhere
+ * to go.
+ *
+ * A product the merchant deleted keeps its row so the buyer can clear it, but
+ * it must not keep its link: `/product/<slug>` would answer with the storefront's
+ * not-found page, which reads as a broken shop rather than a removed product.
+ */
+export function favoriteProductHref(favorite: CustomerFavorite): string | null {
+  if (favorite.unavailable || !favorite.slug) return null;
+  return `/product/${encodeURIComponent(favorite.slug)}`;
+}
+
+/** Drops one product from a list, used after the server confirms the removal. */
+export function withoutFavorite(
+  favorites: readonly CustomerFavorite[],
+  productUniqid: string,
+): CustomerFavorite[] {
+  return favorites.filter((favorite) => favorite.product_uniqid !== productUniqid);
+}
+

package/eject/account/account-loyalty.ts

@@ -0,0 +1,241 @@
+import type { SdkCustomerLoyalty, SdkCustomerLoyaltyTransactionType } from '@shoppexio/storefront-react';
+
+/**
+ * The points section's pure half.
+ *
+ * Every figure here is the server's. Nothing recomputes a balance from the
+ * activity list: the list is capped at fifty entries, so adding it up would
+ * produce a second, smaller number for the same points and the two would
+ * disagree on every account older than fifty transactions.
+ *
+ * The one number this module does compute is the redeem PREVIEW, and it is
+ * labelled as an estimate wherever it is shown. The server converts the points
+ * and answers with the amount it actually credited; that answer is what the
+ * buyer is told afterwards.
+ */
+
+/** The balance the server holds. No account yet is zero points, not "unknown". */
+export function loyaltyPointsBalance(account: SdkCustomerLoyalty['account']): number {
+  return account?.points_balance ?? 0;
+}
+
+export function loyaltyLifetimePoints(account: SdkCustomerLoyalty['account']): number {
+  return account?.lifetime_points ?? 0;
+}
+
+/**
+ * Why a row exists, as a message key.
+ *
+ * The four types are a CLOSED set on this wire — the SDK validates the payload
+ * against them, so a type invented upstream fails the whole read rather than
+ * arriving here. That is why this map is total and has no "something else"
+ * branch: an unreachable one would be a label nobody could ever see.
+ */
+const TRANSACTION_KEYS: Readonly<Record<SdkCustomerLoyaltyTransactionType, string>> = {
+  EARN_ORDER: 'rewards.pointsFromOrder',
+  EARN_REVIEW: 'rewards.pointsFromReview',
+  REDEEM: 'rewards.pointsConverted',
+  ADJUST: 'rewards.pointsAdjusted',
+};
+
+export function loyaltyTransactionKey(type: SdkCustomerLoyaltyTransactionType): string {
+  return TRANSACTION_KEYS[type];
+}
+
+/**
+ * `+120` for points that arrived, `-500` for points that were spent.
+ *
+ * The sign is the producer's: REDEEM and a negative ADJUST already carry a
+ * negative number, so nothing here decides direction. The plus is added because
+ * a bare `120` beside a `-500` reads as two unrelated figures.
+ */
+export function signedPoints(points: number): string {
+  return points > 0 ? `+${points}` : String(points);
+}
+
+/**
+ * Whether the buyer can convert points at all, and on what terms.
+ *
+ * A shop with no settings, or points worth nothing per point, runs no
+ * conversion: nothing is offered and nothing is said, because there is no
+ * conversion to talk about. The control is removed rather than disabled — a
+ * disabled button still promises that pressing it would have worked.
+ *
+ * A balance under the minimum is a THIRD answer, not the same as the first two.
+ * The form would be a control the route refuses, but the number it refuses
+ * below is the whole point of collecting points, so the caller keeps it and
+ * names it. A balance with nothing beside it tells the buyer nothing about what
+ * they are collecting towards.
+ *
+ * The minimum is floored at one because the route refuses anything below it: a
+ * shop that set `min_redeem_points` to zero has not made zero points
+ * convertible, it has left the field at its default.
+ */
+export type RedeemOffer =
+  | { kind: 'hidden' }
+  | { kind: 'below-minimum'; balance: number; minimumPoints: number }
+  | { kind: 'offered'; balance: number; minimumPoints: number; valuePerPoint: number };
+
+export function redeemOffer(loyalty: SdkCustomerLoyalty): RedeemOffer {
+  const settings = loyalty.settings;
+  if (settings === null) return { kind: 'hidden' };
+  if (settings.redeem_value_per_point <= 0) return { kind: 'hidden' };
+
+  const minimumPoints = Math.max(1, settings.min_redeem_points);
+  const balance = loyaltyPointsBalance(loyalty.account);
+  if (balance < minimumPoints) return { kind: 'below-minimum', balance, minimumPoints };
+
+  return {
+    kind: 'offered',
+    balance,
+    minimumPoints,
+    valuePerPoint: settings.redeem_value_per_point,
+  };
+}
+
+/**
+ * What the typed amount is worth, or why it is not an amount yet.
+ *
+ * The wire takes a whole number of one or more, so `1.5`, `-20` and `2e3` are
+ * refused HERE rather than sent and rejected: a buyer who mistyped learns it
+ * while the field is still under their cursor.
+ *
+ * `below-minimum` and `above-balance` are separate answers because they need
+ * different sentences — one names the floor the shop set, the other names the
+ * points the buyer actually has.
+ */
+export type RedeemPreview =
+  | { kind: 'empty' }
+  | { kind: 'not-a-number' }
+  | { kind: 'below-minimum'; minimumPoints: number }
+  | { kind: 'above-balance'; balance: number }
+  | { kind: 'zero-value' }
+  | { kind: 'ready'; points: number; amount: string };
+
+export function redeemPreview(
+  input: string,
+  offer: { balance: number; minimumPoints: number; valuePerPoint: number },
+): RedeemPreview {
+  const typed = input.trim();
+  if (typed.length === 0) return { kind: 'empty' };
+  if (!/^\d+$/.test(typed)) return { kind: 'not-a-number' };
+
+  const points = Number(typed);
+  if (!Number.isSafeInteger(points) || points < 1) return { kind: 'not-a-number' };
+  if (points < offer.minimumPoints) return { kind: 'below-minimum', minimumPoints: offer.minimumPoints };
+  if (points > offer.balance) return { kind: 'above-balance', balance: offer.balance };
+
+  const amount = storeCreditAmount(points, offer.valuePerPoint);
+  // A rate low enough that this many points still round to nothing. The offer
+  // itself is real — the shop converts, and a larger amount would be worth
+  // something — so this is a fact about the number typed, not about the shop,
+  // and it is refused the way any other unusable entry is.
+  if (!(Number(amount) > 0)) return { kind: 'zero-value' };
+
+  return { kind: 'ready', points, amount };
+}
+
+/**
+ * Points as a decimal string in the SHOP currency, which is the currency
+ * `redeem_value_per_point` is measured in.
+ *
+ * A STRING because that is what this template's money formatter takes
+ * everywhere else, and because a float carried to the screen is how `5` becomes
+ * `5.000000000000001`. Two decimals, and the buyer is told the figure is
+ * approximate: the server holds the authoritative rounding and answers with the
+ * amount it credited.
+ */
+export function storeCreditAmount(points: number, valuePerPoint: number): string {
+  return (points * valuePerPoint).toFixed(2);
+}
+
+/**
+ * A loyalty movement's timestamp as a Date for display, or the string as it
+ * came when it cannot be read — the panel's formatter then prints the
+ * original rather than "Invalid Date". Same UTC rule as the warranty dates:
+ * the producer's naive PostgreSQL timestamp is UTC, not the buyer's local
+ * zone, and the space-separated form is not something every engine parses.
+ */
+export function loyaltyDate(value: string): Date | string {
+  const trimmed = value.trim();
+  if (!trimmed) return value;
+  const hasTimezone = /(?:Z|[+-]\d{2}(?::?\d{2})?)$/i.test(trimmed);
+  const hasTimePart = trimmed.includes(' ') || trimmed.includes('T');
+  const normalized = hasTimezone || !hasTimePart ? trimmed : `${trimmed.replace(' ', 'T')}Z`;
+  const parsed = Date.parse(normalized);
+  return Number.isFinite(parsed) ? new Date(parsed) : value;
+}
+
+/** A unique per-intent seed. randomUUID where available, otherwise hex from
+ *  getRandomValues — the derived key stamps its own RFC 4122 shape, so the
+ *  seed only has to be unique, and minting must never throw during render. */
+export function mintRedeemSeed(): string {
+  if (typeof crypto.randomUUID === 'function') return crypto.randomUUID();
+  const bytes = crypto.getRandomValues(new Uint8Array(16));
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * The idempotency key for one redeem intent, derived from a per-intent seed
+ * and the amount instead of minted per keystroke. Any way the buyer arrives
+ * back at the same amount — retype, clear-and-repeat, edit-and-undo — yields
+ * the SAME key while the seed lives, so a retry after a dropped connection can
+ * never spend the points twice; the seed is rotated only when the server has
+ * answered success. A different amount derives a different key, so a stale key
+ * can never replay the wrong conversion.
+ */
+export async function deriveRedeemIdempotencyKey(seed: string, points: number): Promise<string> {
+  // A deliberate, checked use of the global: this derivation is pure — it takes
+  // the seed it is handed and returns a string — so it owns no window state.
+  // The seed still arrives through the React seam. `crypto.subtle` exists only
+  // in a secure context, and a storefront that is not one has to say so rather
+  // than throw a DOM exception at the buyer.
+  if (!globalThis.crypto?.subtle) throw new Error('Redeeming points needs Web Crypto (a secure context).');
+  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(`${seed}:${points}`));
+  const bytes = new Uint8Array(digest).slice(0, 16);
+  // RFC 4122 shape (version + variant bits): the route validates the key with
+  // `format: 'uuid'`.
+  bytes[6] = (bytes[6] & 0x0f) | 0x40;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+/**
+ * The redeem intent's state, at MODULE level on purpose: a buyer who
+ * navigates to another account tab unmounts the rewards view, and a
+ * component-held key for a committed-but-unanswered conversion would die
+ * with it — retrying after coming back would derive a fresh key and debit
+ * the points a second time. Module state lives as long as the page, the
+ * same lifetime the document lane's panel surface has.
+ *
+ * A different signed-in buyer reusing a leftover key is harmless: the
+ * producer scopes idempotency to the account, so an unknown key simply
+ * executes as a first attempt.
+ */
+let redeemSeed = '';
+const pendingRedeemKeys = new Map<number, string>();
+
+/**
+ * The submission key for this amount: the remembered one while the amount
+ * is still unanswered, otherwise derived from the current seed and
+ * remembered until `resolveRedeemKey` drops it on success.
+ */
+export async function redeemSubmissionKey(points: number): Promise<string> {
+  const pending = pendingRedeemKeys.get(points);
+  if (pending !== undefined) return pending;
+  if (redeemSeed === '') redeemSeed = mintRedeemSeed();
+  const key = await deriveRedeemIdempotencyKey(redeemSeed, points);
+  pendingRedeemKeys.set(points, key);
+  return key;
+}
+
+/**
+ * THIS amount answered success: its key is dropped so the same amount can
+ * be a genuinely new conversion later, and the seed rotates lazily — the
+ * next submission mints its own. Unanswered amounts keep their keys.
+ */
+export function resolveRedeemKey(points: number): void {
+  pendingRedeemKeys.delete(points);
+  redeemSeed = '';
+}