@shoppexio/storefront-react 0.3.0 → 0.5.0

package/eject/account/account-downloads.ts

@@ -1,4 +1,5 @@
-import type { SdkCustomerDeliverable, SdkCustomerLicense } from '@shoppexio/storefront-react';
+import type { SdkCustomerDeliverable, SdkCustomerFileAccess, SdkCustomerLicense } from '@shoppexio/storefront-react';
+import { getActiveLocale, t } from './i18n';
 
 /**
  * The downloads panel's pure half.
@@ -116,3 +117,90 @@ export function offersRenewal(license: SdkCustomerLicense): boolean {
   return license.renewable && license.expires_at !== null;
 }
 
+
+/** What one file still allows, as the row says it (Design Batch 2, F1). */
+export interface FileAccessCopy {
+  /** What is left and until when, or why it stopped. Null: nothing to say (unlimited, no end date). */
+  text: string | null;
+  /** The file no longer downloads, so the row offers no Download. */
+  refused: boolean;
+  /** The buyer can ask the shop to open it again. A refund closed it for a reason the shop already decided. */
+  canAsk: boolean;
+}
+
+/**
+ * A file's end date, as a day in the SHOP's calendar.
+ *
+ * The producer sends an instant and the shop's IANA zone. An end at 23:30 in
+ * Berlin is already the next day in UTC and still the same day in New York, so
+ * formatting in the viewer's zone would name a day the shop never set.
+ */
+export function fileAccessDate(endsAt: string, timeZone: string): string {
+  const date = new Date(endsAt);
+  if (Number.isNaN(date.getTime())) return endsAt;
+  return new Intl.DateTimeFormat(getActiveLocale(), {
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+    timeZone,
+  }).format(date);
+}
+
+/**
+ * The same sentences as the hosted portal's `describeFileAccess`. An open file
+ * names only the parts the producer sent: no limit and no end date says
+ * nothing at all rather than "unlimited".
+ */
+export function describeFileAccess(access: SdkCustomerFileAccess): FileAccessCopy {
+  const until = access.ends_at ? fileAccessDate(access.ends_at, access.time_zone) : null;
+  switch (access.state) {
+    case 'open': {
+      const parts: string[] = [];
+      if (access.downloads_left !== null) {
+        parts.push(t(
+          access.downloads_left === 1 ? 'downloads.accessLeftOne' : 'downloads.accessLeftOther',
+          { count: access.downloads_left },
+        ));
+      }
+      if (until) parts.push(t('downloads.accessUntil', { date: until }));
+      return { text: parts.length > 0 ? parts.join(' · ') : null, refused: false, canAsk: false };
+    }
+    case 'limit_reached':
+      return {
+        text: access.download_limit === null
+          ? t('downloads.accessLimitReached')
+          : t(
+            access.download_limit === 1 ? 'downloads.accessLimitReachedOne' : 'downloads.accessLimitReachedOther',
+            { count: access.download_limit },
+          ),
+        refused: true,
+        canAsk: true,
+      };
+    case 'expired':
+      return {
+        text: until ? t('downloads.accessExpired', { date: until }) : t('downloads.accessExpiredUndated'),
+        refused: true,
+        canAsk: true,
+      };
+    case 'revoked':
+      return { text: t('downloads.accessRevoked'), refused: true, canAsk: true };
+    case 'refunded':
+      return { text: t('downloads.accessRefunded'), refused: true, canAsk: false };
+  }
+}
+
+/**
+ * The ticket "Ask for access" opens: on the order, naming the file and why it
+ * stopped, so the shop can extend, reset or restore it from the order page.
+ */
+export function accessRequestTicket(
+  file: Pick<SdkCustomerDeliverable, 'label' | 'product_title' | 'invoice_uniqid'>,
+  reason: string | null,
+): { title: string; message: string; invoice_id: string } {
+  const message = t('downloads.accessRequestMessage', { file: file.label, product: file.product_title });
+  return {
+    title: t('downloads.accessRequestTitle', { file: file.label }).slice(0, 120),
+    message: reason ? `${message} ${t('downloads.accessRequestReason', { reason })}` : message,
+    invoice_id: file.invoice_uniqid,
+  };
+}

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

@@ -15,6 +15,7 @@
 const GATEWAY_LABELS: Record<string, string> = {
   STRIPE: 'Stripe',
   PAYPAL: 'PayPal',
+  PAYPAL_FF: 'PayPal F&F',
   CASHAPP: 'Cash App',
   SQUARE: 'Square',
   BITCOIN: 'Bitcoin',

package/eject/account/account-referrals.ts

@@ -1,4 +1,4 @@
-import type { SdkCustomerAffiliateLink, SdkCustomerAffiliateSummary } from '@shoppexio/storefront-react';
+import type { SdkCustomerAffiliateLink, SdkCustomerAffiliateRates, SdkCustomerAffiliateSummary } from '@shoppexio/storefront-react';
 
 /**
  * The referrals panel's pure half.
@@ -239,3 +239,72 @@ export function referralLinkInput(draft: ReferralLinkDraft): ReferralLinkInputRe
     },
   };
 }
+
+/** A catalog key and its values, translated by the panel. */
+export interface ReferralMessage {
+  key: string;
+  params?: Record<string, string>;
+}
+
+export interface ReferralRateRow {
+  id: 'rate' | 'order' | 'binding';
+  title: ReferralMessage;
+  detail: ReferralMessage | null;
+}
+
+/**
+ * "Your rates" (Design Batch 3 F2), the same rows as the Easy-lane account
+ * block: the rate and the products that earn nothing, the cap and minimum per
+ * order, and how long a referred buyer stays. A part shows only when the shop
+ * set it. One rate per link was not true once products, a cap and a minimum
+ * could pay less.
+ */
+export function referralRateRows(
+  rates: SdkCustomerAffiliateRates,
+  format: {
+    money: (usd: string) => string;
+    /** "A, B and C" in the reader's language. */
+    list: (names: string[]) => string;
+    /** "2 more", for the No Commission products past the three named. */
+    more: (count: number) => string;
+  },
+): ReferralRateRow[] {
+  const percent = String(rates.percent);
+  const more = rates.disabled_product_count - rates.disabled_products.length;
+  const names = more > 0 ? [...rates.disabled_products, format.more(more)] : rates.disabled_products;
+  const disabled: ReferralMessage | null = rates.disabled_product_count === 0
+    ? null
+    : rates.disabled_product_count === 1
+      ? { key: 'referrals.ratesProductEarnsNothing', params: { product: format.list(names) } }
+      : { key: 'referrals.ratesProductsEarnNothing', params: { products: format.list(names) } };
+  // A product with its own rate pays that instead of this one, so "every product" would overpromise.
+  const customRate: ReferralMessage | null = rates.custom_rate_product_count === 0 ? null : { key: 'referrals.ratesCustomRateProducts' };
+  const rows: ReferralRateRow[] = [{
+    id: 'rate',
+    title: { key: disabled || customRate ? 'referrals.ratesMostProducts' : 'referrals.ratesEveryProduct', params: { percent } },
+    detail: disabled ?? customRate,
+  }];
+  const minimum: ReferralMessage | null = rates.minimum_order_usd === null
+    ? null
+    : { key: 'referrals.ratesMinimum', params: { amount: format.money(rates.minimum_order_usd) } };
+  if (rates.cap_usd !== null) {
+    rows.push({ id: 'order', title: { key: 'referrals.ratesCap', params: { amount: format.money(rates.cap_usd) } }, detail: minimum });
+  } else if (minimum) {
+    rows.push({ id: 'order', title: minimum, detail: null });
+  }
+  if (rates.binding_mode !== 'PER_ORDER') {
+    rows.push({
+      id: 'binding',
+      title: rates.binding_days === null
+        ? { key: 'referrals.ratesBindingForever' }
+        : { key: 'referrals.ratesBindingDays', params: { days: String(rates.binding_days) } },
+      detail: { key: 'referrals.ratesBindingDetail' },
+    });
+  }
+  return rows;
+}
+
+/** A link names its rate only when it earns another one than "Your rates" says. */
+export function linkCommissionDiffers(link: SdkCustomerAffiliateLink, rates: SdkCustomerAffiliateRates | null): boolean {
+  return rates === null || link.effective_commission_percent !== rates.percent;
+}

package/eject/account/account-reseller.ts

@@ -1,5 +1,5 @@
 /**
- * Pure wire narrowing and basket quote helpers for the wholesale account tab.
+ * Pure wire narrowing for the wholesale account tab.
  *
  * The shapes below follow the mapper functions in
  * `apps/backend-elysia/src/routes/v1/customer-reseller.ts` exactly. They do not
@@ -38,6 +38,8 @@ export interface ResellerProgramState {
   enrollment_mode: ResellerEnrollmentMode;
   application_message: string | null;
   require_application_note: boolean;
+  /** The shop hands out delivery URLs; the "Delivery URL" link shows only then. */
+  delivery_url_enabled: boolean;
   reseller: ResellerRelationship | null;
 }
 
@@ -45,7 +47,6 @@ export interface ResellerCatalogVariant {
   variant_id: string;
   title: string;
   stock: number;
-  supplier_backed: boolean;
   orderable: boolean;
   base_price: string;
   unit_price: string;
@@ -59,7 +60,6 @@ export interface ResellerCatalogItem {
   title: string;
   type: string;
   stock: number;
-  supplier_backed: boolean;
   orderable: boolean;
   volume_discount_enabled: boolean;
   base_price: string;
@@ -82,13 +82,7 @@ export interface ResellerCatalogPayload {
   catalog: ResellerCatalog;
 }
 
-export interface ResellerOrderItemInput {
-  product_id: string;
-  variant_id?: string;
-  quantity: number;
-}
-
-/** Producer limits from `ResellerOrderItemSchema`. Quantities are units, not fractions. */
+/** Producer limits from `ResellerOrderItemSchema`. Quantities are units, not fractions; an order line is read against them. */
 export const RESELLER_QUANTITY_MIN_UNITS = 1;
 export const RESELLER_QUANTITY_MAX_UNITS = 100_000;
 
@@ -98,31 +92,6 @@ export function isValidResellerQuantity(value: number): boolean {
     && value <= RESELLER_QUANTITY_MAX_UNITS;
 }
 
-export interface ResellerQuoteItem {
-  product_id: string;
-  product_title: string;
-  product_type: string;
-  variant_id: string | null;
-  variant_title: string | null;
-  quantity: number;
-  base_price: string;
-  discount_percent: number;
-  unit_price: string;
-  line_total: string;
-  applied_override: ResellerAppliedOverride;
-  volume_discount_applied: string;
-}
-
-export interface ResellerQuote {
-  currency: string;
-  tier: { id: string; name: string; discount_percent: number };
-  items: ResellerQuoteItem[];
-  subtotal: string;
-  volume_discount_total: string;
-  total: string;
-  savings: string;
-}
-
 export interface ResellerOrderListItem {
   uniqid: string;
   status: string;
@@ -287,6 +256,7 @@ export function narrowResellerProgram(
     !isEnrollmentMode(payload.enrollment_mode) ||
     !isNullableString(payload.application_message) ||
     typeof payload.require_application_note !== "boolean" ||
+    typeof payload.delivery_url_enabled !== "boolean" ||
     reseller === undefined
   ) {
     return { ok: false };
@@ -298,6 +268,7 @@ export function narrowResellerProgram(
       enrollment_mode: payload.enrollment_mode,
       application_message: payload.application_message,
       require_application_note: payload.require_application_note,
+      delivery_url_enabled: payload.delivery_url_enabled,
       reseller,
     },
   };
@@ -318,7 +289,6 @@ function narrowCatalogVariant(value: unknown): ResellerCatalogVariant | null {
     typeof value.variant_id !== "string" ||
     typeof value.title !== "string" ||
     !isFiniteNumber(value.stock) ||
-    typeof value.supplier_backed !== "boolean" ||
     typeof value.orderable !== "boolean" ||
     typeof value.base_price !== "string" ||
     typeof value.unit_price !== "string" ||
@@ -343,7 +313,6 @@ function narrowCatalogItem(value: unknown): ResellerCatalogItem | null {
     typeof value.title !== "string" ||
     typeof value.type !== "string" ||
     !isFiniteNumber(value.stock) ||
-    typeof value.supplier_backed !== "boolean" ||
     typeof value.orderable !== "boolean" ||
     typeof value.volume_discount_enabled !== "boolean" ||
     typeof value.base_price !== "string" ||
@@ -358,7 +327,6 @@ function narrowCatalogItem(value: unknown): ResellerCatalogItem | null {
     title: value.title,
     type: value.type,
     stock: value.stock,
-    supplier_backed: value.supplier_backed,
     orderable: value.orderable,
     volume_discount_enabled: value.volume_discount_enabled,
     base_price: value.base_price,
@@ -412,69 +380,6 @@ export function narrowResellerCatalog(
   };
 }
 
-function narrowQuoteItem(value: unknown): ResellerQuoteItem | null {
-  if (!isRecord(value)) return null;
-  if (
-    typeof value.product_id !== "string" ||
-    typeof value.product_title !== "string" ||
-    typeof value.product_type !== "string" ||
-    !isNullableString(value.variant_id) ||
-    !isNullableString(value.variant_title) ||
-    !isValidResellerQuantity(value.quantity as number) ||
-    typeof value.base_price !== "string" ||
-    !isFiniteNumber(value.discount_percent) ||
-    typeof value.unit_price !== "string" ||
-    typeof value.line_total !== "string" ||
-    !isAppliedOverride(value.applied_override) ||
-    typeof value.volume_discount_applied !== "string"
-  )
-    return null;
-  return value as unknown as ResellerQuoteItem;
-}
-
-/** `POST /reseller/orders/quote`, written against mapQuote. */
-export function narrowResellerQuote(
-  payload: unknown,
-): NarrowResult<ResellerQuote> {
-  if (!isRecord(payload) || !isRecord(payload.quote)) return { ok: false };
-  const raw = payload.quote;
-  const tier = narrowTier(raw.tier);
-  if (
-    !tier ||
-    typeof tier.name !== "string" ||
-    typeof tier.discount_percent !== "number" ||
-    typeof raw.currency !== "string" ||
-    !Array.isArray(raw.items) ||
-    typeof raw.subtotal !== "string" ||
-    typeof raw.volume_discount_total !== "string" ||
-    typeof raw.total !== "string" ||
-    typeof raw.savings !== "string"
-  )
-    return { ok: false };
-  const items: ResellerQuoteItem[] = [];
-  for (const entry of raw.items) {
-    const item = narrowQuoteItem(entry);
-    if (!item) return { ok: false };
-    items.push(item);
-  }
-  return {
-    ok: true,
-    data: {
-      currency: raw.currency,
-      tier: {
-        id: tier.id,
-        name: tier.name,
-        discount_percent: tier.discount_percent,
-      },
-      items,
-      subtotal: raw.subtotal,
-      volume_discount_total: raw.volume_discount_total,
-      total: raw.total,
-      savings: raw.savings,
-    },
-  };
-}
-
 function narrowOrderListItem(value: unknown): ResellerOrderListItem | null {
   if (!isRecord(value)) return null;
   if (
@@ -627,35 +532,6 @@ export function narrowResellerApiKeys(
   return { ok: true, data: keys };
 }
 
-/** Stable identity of one basket version. Order is normalized for comparison. */
-export function resellerBasketKey(
-  items: readonly ResellerOrderItemInput[],
-): string {
-  for (const item of items) {
-    if (!isValidResellerQuantity(item.quantity)) {
-      throw new RangeError(
-        `Wholesale quantity must be a whole number from ${RESELLER_QUANTITY_MIN_UNITS} to ${RESELLER_QUANTITY_MAX_UNITS} units; received ${String(item.quantity)}.`,
-      );
-    }
-  }
-
-  return JSON.stringify(
-    [...items]
-      .map((item) => ({
-        product_id: item.product_id,
-        variant_id: item.variant_id ?? null,
-        quantity: item.quantity,
-      }))
-      .sort((left, right) => {
-        const product = left.product_id.localeCompare(right.product_id);
-        return (
-          product ||
-          (left.variant_id ?? "").localeCompare(right.variant_id ?? "")
-        );
-      }),
-  );
-}
-
 /**
  * The one way into the program this buyer actually has.
  *
@@ -673,13 +549,3 @@ export function resellerEntryMode(
     ? "MANUAL"
     : program.enrollment_mode;
 }
-
-/** A quote is displayed only for the basket it priced. */
-export function quoteMatchesBasket(
-  quotedBasketKey: string | null,
-  items: readonly ResellerOrderItemInput[],
-): boolean {
-  return (
-    quotedBasketKey !== null && quotedBasketKey === resellerBasketKey(items)
-  );
-}

package/eject/account/account-subscriptions.ts

@@ -1,4 +1,4 @@
-import type { SdkCustomerSubscription } from '@shoppexio/storefront-react';
+import type { SdkCustomerOpenRenewal, SdkCustomerPauseOptions, SdkCustomerSubscription } from '@shoppexio/storefront-react';
 
 /**
  * The subscriptions panel's pure half: which date matters, how the plan bills,
@@ -14,17 +14,38 @@ import type { SdkCustomerSubscription } from '@shoppexio/storefront-react';
  * renewal it will never take.
  */
 export type SubscriptionTiming =
+  | { kind: 'ended'; date: string }
   | { kind: 'canceled'; date: string }
   | { kind: 'ends'; date: string }
+  /** A renewal on hold or past its date: the deadline to pay it, not a renewal date already gone. */
+  | { kind: 'payBy'; date: string }
+  | { kind: 'pauses'; date: string }
+  | { kind: 'resumes'; date: string }
+  /** Paused by the merchant or the API without a resume date. */
+  | { kind: 'pausedOpenEnded'; date: string }
   | { kind: 'trial'; date: string }
   | { kind: 'renews'; date: string };
 
 export function subscriptionTiming(subscription: SdkCustomerSubscription): SubscriptionTiming {
+  if (endedAfterHold(subscription) && subscription.canceled_at) {
+    return { kind: 'ended', date: subscription.canceled_at };
+  }
   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 };
+  const renewal = openRenewalState(subscription);
+  if (subscription.open_renewal && (renewal === 'held' || renewal === 'due')) {
+    return { kind: 'payBy', date: subscription.open_renewal.pay_by };
+  }
+  // The producer's one "set to end" fact: cancelled at the period end, or a voided renewal.
+  if (subscription.ends_at) {
+    return { kind: 'ends', date: subscription.ends_at };
+  }
+  // A paused or pausing plan bills nothing at its period end; it bills again when it resumes.
+  const pause = subscription.pause;
+  if (pause?.state === 'scheduled') return { kind: 'pauses', date: pause.starts_at };
+  if (pause?.state === 'paused') {
+    return pause.resume_at === null ? { kind: 'pausedOpenEnded', date: '' } : { kind: 'resumes', date: pause.resume_at };
   }
   if (subscription.status.toUpperCase() === 'TRIALING' && subscription.trial_end) {
     return { kind: 'trial', date: subscription.trial_end };
@@ -34,7 +55,24 @@ export function subscriptionTiming(subscription: SdkCustomerSubscription): Subsc
 
 /** The catalog key for a timing, so the panel never spells one itself. */
 export function subscriptionTimingKey(timing: SubscriptionTiming): string {
-  return `subscriptions.${timing.kind}`;
+  return timing.kind === 'ended' ? 'subscriptions.endedOn' : `subscriptions.${timing.kind}`;
+}
+
+/**
+ * A subscription that ended with its renewal still unpaid (the hold ran out, or the
+ * shop ended it during the hold): CANCELED with the `hold_ends_at` the hold left on
+ * the row. `ranOut` is read from the two producer timestamps, never from the date today.
+ */
+export function endedAfterHold(subscription: SdkCustomerSubscription): { ranOut: boolean } | null {
+  if (subscription.status.toUpperCase() !== 'CANCELED' || !subscription.hold_ends_at || !subscription.canceled_at) return null;
+  const canceledAt = producerTimestamp(subscription.canceled_at);
+  const holdEndsAt = producerTimestamp(subscription.hold_ends_at);
+  return { ranOut: canceledAt !== null && holdEndsAt !== null && canceledAt >= holdEndsAt };
+}
+
+/** The catalog key of the ended note's sentence. */
+export function endedNoteKey(ended: { ranOut: boolean }): string {
+  return ended.ranOut ? 'subscriptions.endedHoldRanOut' : 'subscriptions.endedShopEnded';
 }
 
 const KNOWN_INTERVALS: ReadonlySet<string> = new Set(['day', 'week', 'month', 'year']);
@@ -82,6 +120,44 @@ export interface BillingHistoryInvoice {
   currency: string;
   status: string;
   created_at: string;
+  /** What the invoice billed: the order that started the plan, a renewal, or a plan change. */
+  kind: 'first_order' | 'renewal' | 'plan_change';
+  /** The plan change it paid for; null on a renewal or a first order. Days are null when the producer did not count them. */
+  plan_change: { from_plan_name: string; to_plan_name: string; days_left: number | null; days_total: number | null } | null;
+}
+
+const BILLING_KINDS: ReadonlyArray<BillingHistoryInvoice['kind']> = ['first_order', 'renewal', 'plan_change'];
+
+function readCount(record: Record<string, unknown>, key: string): number | null | undefined {
+  const value = record[key];
+  if (value === null) return null;
+  return typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : undefined;
+}
+
+function readPlanChange(value: unknown): BillingHistoryInvoice['plan_change'] | undefined {
+  if (value === null) return null;
+  if (!isRecord(value)) return undefined;
+  const from = readString(value, 'from_plan_name');
+  const to = readString(value, 'to_plan_name');
+  const daysLeft = readCount(value, 'days_left');
+  const daysTotal = readCount(value, 'days_total');
+  if (from === null || to === null || daysLeft === undefined || daysTotal === undefined) return undefined;
+  return { from_plan_name: from, to_plan_name: to, days_left: daysLeft, days_total: daysTotal };
+}
+
+/** What a billing history row billed (Design Batch 9, C3), as a catalog key: "Renewal", "First order", "Plan change, Basic to Pro". */
+export function billingEntryTitle(invoice: BillingHistoryInvoice): { key: string; params?: { from: string; to: string } } {
+  if (invoice.plan_change) {
+    return { key: 'subscriptions.historyPlanChange', params: { from: invoice.plan_change.from_plan_name, to: invoice.plan_change.to_plan_name } };
+  }
+  return { key: invoice.kind === 'first_order' ? 'subscriptions.historyFirstOrder' : 'subscriptions.historyRenewal' };
+}
+
+/** "for 12 of 30 days" beside a plan change's date, or null when there is nothing to count. */
+export function billingEntryDays(invoice: BillingHistoryInvoice): { key: string; params: { days: number; total: number } } | null {
+  const change = invoice.plan_change;
+  if (!change || change.days_left === null || change.days_total === null) return null;
+  return { key: 'subscriptions.historyDays', params: { days: change.days_left, total: change.days_total } };
 }
 
 export type BillingHistoryResult =
@@ -118,13 +194,89 @@ export function narrowBillingHistory(payload: unknown): BillingHistoryResult {
     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) {
+    // A kind this build does not know fails the read: a row that guesses what it billed could misname a charge.
+    const kind = BILLING_KINDS.find((known) => known === entry.kind);
+    const planChange = readPlanChange(entry.plan_change);
+    if (uniqid === null || total === null || currency === null || status === null || createdAt === null || !kind || planChange === undefined) {
       return { ok: false };
     }
 
-    invoices.push({ uniqid, total, currency, status, created_at: createdAt });
+    invoices.push({ uniqid, total, currency, status, created_at: createdAt, kind, plan_change: planChange });
   }
 
   return { ok: true, invoices };
 }
 
+/** The length the pause dialog opens with: one month when the shop offers it, else the longest it offers. */
+export function defaultPauseLength(options: SdkCustomerPauseOptions): SdkCustomerPauseOptions['lengths'][number]['days'] | null {
+  if (options.lengths.some((length) => length.days === 30)) return 30;
+  return options.lengths[options.lengths.length - 1]?.days ?? null;
+}
+
+/** "You can pause {n} more times…" as a catalog key and its count. */
+export function pausesLeftMessage(left: number): { key: string; params: { count: number } } {
+  const key = left <= 0 ? 'subscriptions.pauseLeftNone' : left === 1 ? 'subscriptions.pauseLeftOne' : 'subscriptions.pauseLeftMany';
+  return { key, params: { count: left } };
+}
+
+/**
+ * Whether "Resume now" bills a new period today (`resumedPeriodEnd` in subscriptionPause.ts):
+ * a pause from the period end left no paid days, a "right away" pause gives the days left back.
+ */
+export function resumeBillsToday(subscription: SdkCustomerSubscription): boolean {
+  const pause = subscription.pause;
+  if (pause?.state !== 'paused') return false;
+  const periodEnd = producerTimestamp(subscription.current_period_end);
+  const startedAt = producerTimestamp(pause.starts_at);
+  return periodEnd !== null && startedAt !== null && periodEnd <= startedAt;
+}
+
+/**
+ * Where the open renewal stands, read only from the producer's `open_renewal`
+ * and `hold_ends_at`, never from guessed dates:
+ * - `held`: on hold (PAST_DUE with a hold end), access is off until the buyer pays;
+ * - `ready`: invoiced ahead, the renewal date is still to come;
+ * - `due`: the renewal date passed and the time to pay runs.
+ * Null when nothing is open, and on an ended subscription.
+ */
+export type OpenRenewalState = 'held' | 'due' | 'ready';
+
+const NOTE_INTERVALS: Readonly<Record<string, string>> = { DAY: 'Day', WEEK: 'Week', MONTH: 'Month', YEAR: 'Year' };
+
+/**
+ * The unit inside a renewal note ("a new month"), from the plan the renewal invoice bills
+ * (a scheduled interval change bills its target before the subscription's own plan moves):
+ * only a plan that bills once per unit names it. Several units or an unknown unit read as
+ * the generic billing period, never as a unit the producer did not send.
+ */
+export function noteIntervalKey(open: SdkCustomerOpenRenewal, note: 'hold' | 'ready'): string {
+  const unit = open.interval_count === 1 ? NOTE_INTERVALS[open.interval.trim().toUpperCase()] : undefined;
+  return `subscriptions.${note}Interval${unit ?? 'Other'}`;
+}
+
+export function openRenewalState(subscription: SdkCustomerSubscription, now: number = Date.now()): OpenRenewalState | null {
+  const status = subscription.status.toUpperCase();
+  if (!subscription.open_renewal || status === 'CANCELED') return null;
+  if (status === 'PAST_DUE' && subscription.hold_ends_at) return 'held';
+  const renewsAt = producerTimestamp(subscription.current_period_end);
+  return renewsAt !== null && renewsAt > now ? 'ready' : 'due';
+}
+
+/**
+ * The renewal date for display: naive PostgreSQL strings ("2026-08-10 00:00:00.000")
+ * are UTC, not the buyer's local zone. An unreadable value comes back as it came.
+ */
+export function renewalDate(value: string): Date | string {
+  const parsed = producerTimestamp(value);
+  return parsed === null ? value : new Date(parsed);
+}
+
+function producerTimestamp(value: string): number | null {
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  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) ? parsed : null;
+}