@nauticana/sail 1.0.1 → 1.0.3

package/README.md

@@ -315,7 +315,7 @@ If "trust this device" appears to do nothing (user is 2FA-prompted on every logi
 
 ## Billing
 
-sail ships a shared `BillingService` and nine billing components backed by keel's payment endpoints (see [keel/SHARED_PAYMENT.md](https://github.com/nauticana/keel/blob/main/SHARED_PAYMENT.md) for the provider contract — Stripe by default, pluggable).
+sail ships a shared `BillingService` and ten billing components backed by keel's payment endpoints (see [keel/SHARED_PAYMENT.md](https://github.com/nauticana/keel/blob/main/SHARED_PAYMENT.md) for the provider contract — Stripe by default, pluggable).
 
 ### Service
 
@@ -356,10 +356,24 @@ export class PricingPage {
 </sail-plan-selector>
 ```
 
-**Checkout button** — calls `createCheckout()` and redirects to the provider-hosted URL. `PublicPlan.priceId` lets you wire the picker directly to checkout without a local mapping table:
+**Offer / price picker (v1.0.5)** — a plan no longer has a single price. keel v1.0.5 sells per-plan **offers** in the `subscription_plan_price` table (billing cycle × commitment term, each with its own `provider_price_id`), surfaced as `PublicPlan.prices: PlanPrice[]`. The customer picks an offer **at checkout**; its `priceId` is what flows to `<sail-checkout-button>`:
+
+```html
+<sail-price-selector
+    [prices]="selectedPlan().prices ?? []"
+    [selected]="offer()?.priceId"
+    (selectionChange)="offer.set($event)">
+</sail-price-selector>
+```
+
+`<sail-price-selector>` is presentational (a `radiogroup` of offers), formats each amount with `Intl` from the offer's currency (so JPY/BHD render with the right number of decimals), and maps PERIOD_TYPE codes to copy via `[cycleLabels]`. It emits the full `PlanPrice` so you keep the chosen terms, not just the id.
+
+> **Migration.** The flat `PublicPlan.priceId` is deprecated (keel v1.0.5 dropped `subscription_plan.provider_price_id`) — read the id from the selected offer (`offer().priceId`). **keel v1.0.7 also removed `PublicPlan.monthlyCost`/`annualCost`** from both `/public/plans` and the billing catalog, so any plan-card code reading them now gets `undefined`. Derive a display price from the offers with `fromPriceLabel(plan.prices)` (used by `<sail-plan-selector>`), or render the per-offer amounts via `<sail-price-selector>`. These fields are removed from sail's `PublicPlan` type so the compiler flags any remaining references.
+
+**Checkout button** — calls `createCheckout()` and redirects to the provider-hosted URL. Feed it the chosen offer's `priceId`:
 ```html
 <sail-checkout-button
-    [priceId]="selectedPlan().priceId!"
+    [priceId]="offer()!.priceId!"
     [mode]="'subscription'"
     [successUrl]="'https://app.example.com/billing/done'"
     [cancelUrl]="'https://app.example.com/billing'"
@@ -521,14 +535,79 @@ A complete screen is the pieces above assembled over `BillingService` — no met
 <sail-trial-banner [trialEnd]="sub()?.trialEnd"></sail-trial-banner>
 <sail-status-chip [value]="sub()?.status"></sail-status-chip>
 <sail-plan-selector [plans]="plans()" [selected]="sub()?.planId" (selectionChange)="onPlanPicked($event)"></sail-plan-selector>
+<sail-price-selector [prices]="selectedPlan()?.prices ?? []" [selected]="offer()?.priceId" (selectionChange)="offer.set($event)"></sail-price-selector>
 <sail-seat-selector [seats]="sub()?.seats ?? 1" (seatsChange)="seats.set($event)"></sail-seat-selector>
-<sail-checkout-button [priceId]="priceFor(selected())" [quantity]="seats()" [successUrl]="okUrl" [cancelUrl]="backUrl"></sail-checkout-button>
+<sail-checkout-button [priceId]="offer()!.priceId!" [quantity]="seats()" [successUrl]="okUrl" [cancelUrl]="backUrl"></sail-checkout-button>
 <sail-usage-meter [meters]="usage()"></sail-usage-meter>
 <sail-payment-methods></sail-payment-methods>
 <sail-portal-button></sail-portal-button>
 <!-- invoices: render listInvoices() rows directly -->
 ```
 
+## Off-session SCA / 3DS confirmation (v1.0.x)
+
+When an app charges a rider's **vaulted** card off-session (keel `payment.ChargeClient` / `StripeChargeClient`), the provider may return `requires_action` — the cardholder must complete a Strong Customer Authentication (3DS) challenge. keel surfaces the hooks on `ChargeResult` (`ClientSecret`, `ActionURL`); sail standardizes the **client-side** confirmation so it isn't rebuilt per app.
+
+sail stays provider-agnostic: it ships **no payment-provider SDK** and **no default confirmer**. It provides a port (`ScaConfirmer`), the `SCA_CONFIRMER` injection token, and `<sail-sca-confirm>`, which:
+
+- redirects to `ChargeResult.actionUrl` when present (provider-hosted challenge — no SDK needed); else
+- delegates the inline `ChargeResult.clientSecret` to the app-registered `SCA_CONFIRMER`.
+
+### Backend contract (app-owned)
+
+Off-session charging is a worker/handler concern, so the **app** owns the charge endpoint. Have it call keel's `ChargeClient.Charge` and return the normalized result as camelCase JSON matching sail's `ChargeResult`:
+
+```jsonc
+// POST /api/<app>/charge  →  200
+{ "status": "requires_action", "clientSecret": "pi_..._secret_...", "actionUrl": "" }
+// or { "status": "succeeded", "providerChargeId": "pi_..." }
+// or { "status": "failed", "error": "card_declined" }
+```
+
+> `ChargeRequest.Metadata` (keel v1.0.4) carries `ride_id` / `user_id` / `tip_amount` through to the settled charge's `PaymentEvent.Metadata`, so the webhook can correlate and split the fare — set it on the backend, not the client.
+
+### Frontend adoption (downstream projects)
+
+**1. Implement the provider confirmer** (Stripe shown; lives in the app, behind an *optional* `@stripe/stripe-js` peer dep — non-Stripe apps skip it):
+
+```typescript
+import { Injectable } from '@angular/core';
+import { loadStripe } from '@stripe/stripe-js';
+import { ScaConfirmer, ScaResult } from '@nauticana/sail';
+
+@Injectable({ providedIn: 'root' })
+export class StripeScaConfirmer implements ScaConfirmer {
+  async confirm(clientSecret: string): Promise<ScaResult> {
+    const stripe = await loadStripe(/* publishable key from backend cache */);
+    if (!stripe) return { outcome: 'failed', error: 'Stripe.js failed to load' };
+    const { error } = await stripe.handleNextAction({ clientSecret });
+    return error ? { outcome: 'failed', error: error.message } : { outcome: 'succeeded' };
+  }
+}
+```
+
+**2. Register it at composition time** (`app.config.ts` / `main.ts`):
+
+```typescript
+import { SCA_CONFIRMER } from '@nauticana/sail';
+
+providers: [
+  { provide: SCA_CONFIRMER, useExisting: StripeScaConfirmer },
+]
+```
+
+**3. Drop the component into the post-charge flow** — bind the charge response and react to the outcome:
+
+```html
+<sail-sca-confirm
+    [result]="charge()"
+    (confirmed)="onPaid()"
+    (failed)="onScaFailed($event)">
+</sail-sca-confirm>
+```
+
+`<sail-sca-confirm>` renders nothing for `succeeded`, the decline message for `failed`, and a confirm button for `requires_action`. The publishable key is backend-authoritative — read it from the auth/app-data cache, never hardcode a fallback.
+
 ## Consent capture
 
 `ConsentGateComponent` is a reusable signup-consent primitive that mirrors keel's `user.SignupConsent` structure. It always renders two required checkboxes (`privacy_policy`, `cross_border`) and lets you declare any number of optional consents.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nauticana/sail",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Metadata-driven Angular component library for CRUD admin frontends backed by the keel Go backend. Tables, forms, navigation, OTP/2FA/social auth, billing, payout onboarding.",
   "main": "src/index.ts",
   "files": [

package/src/component/billing/plan_selector.html

@@ -2,10 +2,11 @@
   @for (plan of plans(); track plan.id) {
     <div class="plan-card" [class.plan-selected]="plan.id === selected()">
       <h3 class="plan-caption">{{ plan.caption }}</h3>
-      <div class="plan-price">
-        <span class="plan-amount">{{ plan.monthlyCost }}</span>
-        <span class="plan-period">/ month</span>
-      </div>
+      @if (priceLabels()[plan.id]; as priceLabel) {
+        <div class="plan-price">
+          <span class="plan-amount">{{ priceLabel }}</span>
+        </div>
+      }
       @if (featuresFor(plan.id).length > 0) {
         <ul class="plan-features">
           @for (feature of featuresFor(plan.id); track feature) {

package/src/component/billing/plan_selector.ts

@@ -1,6 +1,7 @@
 import { ChangeDetectionStrategy, Component, ViewEncapsulation, computed, input, output } from '@angular/core';
 import { MatButtonModule } from '@angular/material/button';
 import { PublicPlan } from '../../model/appdata';
+import { fromPriceLabel } from '../../util/money';
 
 /**
  * Plan picker. Pure presentational component — stateless, no service calls.
@@ -42,6 +43,13 @@ export class PlanSelectorComponent {
     return out;
   });
 
+  /** planId → indicative "from" price derived from the plan's offers ('' = none). */
+  readonly priceLabels = computed<Record<string, string>>(() => {
+    const out: Record<string, string> = {};
+    for (const plan of this.plans()) out[plan.id] = fromPriceLabel(plan.prices);
+    return out;
+  });
+
   onSelect(planId: string): void {
     this.selectionChange.emit(planId);
   }

package/src/component/billing/price_selector.html

@@ -0,0 +1,17 @@
+<div class="price-selector" role="radiogroup" aria-label="Billing options">
+  @for (offer of offers(); track offer.key) {
+    <button class="price-offer" type="button"
+            role="radio"
+            [class.price-selected]="offer.key === selected()"
+            [attr.aria-checked]="offer.key === selected()"
+            (click)="onSelect(offer)">
+      <span class="price-amount">{{ offer.amountText }}</span>
+      <span class="price-cycle">/ {{ offer.cycleText }}</span>
+      @if (offer.termText) {
+        <span class="price-term">{{ offer.termText }}</span>
+      }
+    </button>
+  } @empty {
+    <p class="empty-state">No billing options available.</p>
+  }
+</div>

package/src/component/billing/price_selector.ts

@@ -0,0 +1,66 @@
+import { ChangeDetectionStrategy, Component, ViewEncapsulation, computed, input, output } from '@angular/core';
+import { PlanPrice } from '../../model/appdata';
+import { formatCurrency } from '../../util/money';
+
+/** Per-offer view model for accessible, currency-formatted rendering. */
+interface OfferRow {
+  key:        string;   // stable id for tracking / selection (priceId or composite)
+  price:      PlanPrice;
+  amountText: string;   // currency-formatted major amount
+  cycleText:  string;   // "Monthly" / "Annual" / …
+  termText:   string;   // commitment note, '' when the term is a single cycle
+}
+
+/**
+ * Offer picker for a plan's `subscription_plan_price` rows (keel v1.0.5). A plan
+ * sells several offers (billing cycle × commitment term); the customer picks one
+ * at checkout, then its `priceId` feeds `<sail-checkout-button [priceId]>`.
+ *
+ * Pure presentational — stateless. Amounts are formatted with `Intl` from each
+ * offer's currency, so non-2-decimal currencies (JPY 0, BHD 3) render correctly.
+ * Period codes map to copy via `[cycleLabels]` (override/extend the defaults).
+ */
+@Component({
+  selector: 'sail-price-selector',
+  templateUrl: './price_selector.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+})
+export class PriceSelectorComponent {
+  private static readonly DEFAULT_CYCLE: Record<string, string> = {
+    D: 'Daily',
+    W: 'Weekly',
+    M: 'Monthly',
+    Q: 'Quarterly',
+    A: 'Annual',
+  };
+
+  readonly prices = input<PlanPrice[]>([]);
+  /** Selected offer key — a `priceId`, or the composite key when priceId is empty. */
+  readonly selected = input<string | undefined>(undefined);
+  /** PERIOD_TYPE code → label; overrides/extends the built-in defaults. */
+  readonly cycleLabels = input<{[periodCode: string]: string}>({});
+  readonly selectionChange = output<PlanPrice>();
+
+  readonly offers = computed<OfferRow[]>(() => {
+    const labels = this.cycleLabels();
+    const cycleLabel = (code: string) =>
+      labels[code] ?? PriceSelectorComponent.DEFAULT_CYCLE[code] ?? code;
+    return this.prices().map((p) => {
+      const singleCycle = p.termCount === 1 && p.termType === p.billingCycle;
+      return {
+        key:        p.priceId || `${p.billingCycle}-${p.termType}-${p.termCount}`,
+        price:      p,
+        amountText: formatCurrency(p.amount, p.currency),
+        cycleText:  cycleLabel(p.billingCycle),
+        termText:   singleCycle
+          ? ''
+          : `${p.termCount} ${cycleLabel(p.termType)}${p.termCount > 1 ? 's' : ''} commitment`,
+      };
+    });
+  });
+
+  onSelect(offer: OfferRow): void {
+    this.selectionChange.emit(offer.price);
+  }
+}

package/src/component/login/register_component.html

@@ -46,7 +46,7 @@
         <mat-select formControlName="PlanID" required>
           @for (p of plans(); track p.id) {
             <mat-option [value]="p.id">
-              {{ p.caption }}@if (p.monthlyCost > 0) { — \${{ p.monthlyCost }}/mo }
+              {{ p.caption }}@if (priceHint(p); as hint) { — {{ hint }} }
             </mat-option>
           }
         </mat-select>

package/src/component/login/register_component.ts

@@ -13,6 +13,7 @@ import { firstValueFrom, map, merge } from 'rxjs';
 import { HttpClient } from '@angular/common/http';
 import { PartnerRegistration, PublicPlan } from '../../model/appdata';
 import { SAIL_GUI_CONFIG, SailGuiConfig, DEFAULT_CONFIG } from '../../config';
+import { fromPriceLabel } from '../../util/money';
 
 @Component({
   selector: 'sail-register',
@@ -76,6 +77,11 @@ export class RegisterComponent implements OnInit {
     return this.guiConfig.googleMapsApiKey ?? '';
   }
 
+  /** Indicative "from" price for a plan option, derived from its offers ('' = free/none). */
+  protected priceHint(plan: PublicPlan): string {
+    return fromPriceLabel(plan.prices);
+  }
+
   ngOnInit() {
     this.billing.listPlans().subscribe({
       next: (list) => this.plans.set(list ?? []),

package/src/component/payment/sca_confirm.html

@@ -0,0 +1,14 @@
+@if (needsAction()) {
+  <div class="sca-confirm">
+    <button matButton="elevated" class="primary" type="button"
+            [disabled]="loading()"
+            (click)="confirm()">
+      @if (loading()) { Confirming… } @else { {{ label() }} }
+    </button>
+  </div>
+} @else if (declined()) {
+  <div class="auth-error" role="alert">{{ result().error ?? 'Your payment was declined.' }}</div>
+}
+@if (errorMessage()) {
+  <div class="auth-error" role="alert">{{ errorMessage() }}</div>
+}

package/src/component/payment/sca_confirm.ts

@@ -0,0 +1,77 @@
+import { ChangeDetectionStrategy, Component, ViewEncapsulation, computed, inject, input, output } from '@angular/core';
+import { MatButtonModule } from '@angular/material/button';
+import { BaseAsync } from '../abstract/base_async';
+import { ChargeResult } from '../../model/appdata';
+import { SCA_CONFIRMER } from '../../service/sca_confirmer';
+
+/**
+ * Drives the SCA / 3DS confirmation for an off-session `ChargeResult`.
+ *
+ * Two confirmation paths, mirroring keel's `ChargeResult`:
+ *  - `actionUrl` present → redirect to the provider-hosted challenge
+ *    (provider-agnostic; the page navigates away).
+ *  - otherwise `clientSecret` → delegate to the injected `SCA_CONFIRMER`
+ *    (the app's provider SDK wrapper). No confirmer is bundled in sail.
+ *
+ * Renders nothing for a `succeeded` result; shows the decline message for
+ * `failed`; shows a confirm button for `requires_action`. Emits `(confirmed)`
+ * on success and `(failed)` with a message on any error — never silently.
+ */
+@Component({
+  selector: 'sail-sca-confirm',
+  templateUrl: './sca_confirm.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  imports: [MatButtonModule],
+})
+export class ScaConfirmComponent extends BaseAsync {
+  private readonly confirmer = inject(SCA_CONFIRMER, { optional: true });
+
+  readonly result = input.required<ChargeResult>();
+  readonly label = input('Confirm your payment');
+  readonly confirmed = output<void>();
+  readonly failed = output<string>();
+
+  readonly needsAction = computed(() => this.result().status === 'requires_action');
+  readonly declined = computed(() => this.result().status === 'failed');
+
+  async confirm(): Promise<void> {
+    const res = this.result();
+
+    // Provider-hosted redirect branch — provider-agnostic; navigates away.
+    if (res.actionUrl) {
+      window.location.href = res.actionUrl;
+      return;
+    }
+
+    // Inline confirmation branch — delegates to the app's provider impl.
+    if (!res.clientSecret) {
+      this.fail('Missing client secret for SCA confirmation.');
+      return;
+    }
+    if (!this.confirmer) {
+      this.fail('No SCA confirmer is configured. Provide SCA_CONFIRMER (e.g. a Stripe.js wrapper).');
+      return;
+    }
+
+    this.clearMessages();
+    this.loading.set(true);
+    try {
+      const out = await this.confirmer.confirm(res.clientSecret);
+      this.loading.set(false);
+      if (out.outcome === 'succeeded') {
+        this.confirmed.emit();
+      } else {
+        this.fail(out.error ?? 'Payment confirmation was not completed.');
+      }
+    } catch (e: unknown) {
+      this.loading.set(false);
+      this.fail(e instanceof Error ? e.message : 'Payment confirmation failed.');
+    }
+  }
+
+  private fail(message: string): void {
+    this.errorMessage.set(message);
+    this.failed.emit(message);
+  }
+}

package/src/index.ts

@@ -30,6 +30,7 @@ export * from './component/security/twofactor_setup';
 export * from './component/security/twofactor_verify';
 export * from './component/security/trusted_devices';
 export * from './component/billing/plan_selector';
+export * from './component/billing/price_selector';
 export * from './component/billing/checkout_button';
 export * from './component/billing/payment_methods';
 export * from './component/billing/portal_button';
@@ -41,7 +42,9 @@ export * from './component/billing/dunning_banner';
 export * from './component/payout/provider_onboarding';
 export * from './component/payout/bank_info_form';
 export * from './component/payment/user_payment_methods';
+export * from './component/payment/sca_confirm';
 export * from './service/auth.service';
+export * from './service/sca_confirmer';
 export * from './service/billing.service';
 export * from './service/payout.service';
 export * from './service/user_payment_method.service';
@@ -53,3 +56,4 @@ export * from './service/rest_url';
 export * from './service/label.service';
 export * from './service/base_rest.service';
 export * from './util/text';
+export * from './util/money';

package/src/model/appdata.ts

@@ -201,17 +201,39 @@ export interface PartnerRegistration {
 	PlanID:               string;
 }
 
+// One purchasable offer for a plan — a (billing cycle × commitment term) row of
+// keel's `subscription_plan_price` table (v1.0.5). A plan sells several; the
+// customer picks one at checkout via `<sail-price-selector>`. Mirrors keel
+// `billing.PlanPrice`.
+export interface PlanPrice {
+	billingCycle: string;   // PERIOD_TYPE code (D/W/M/A) — how often charged
+	termCount:    number;   // commitment length, in termType units
+	termType:     string;   // PERIOD_TYPE code — commitment/pricing unit
+	amountMinor:  number;   // price per termType unit, in minor units (cents)
+	amount:       number;   // same amount in major units (currency-exponent applied)
+	currency:     string;   // ISO 4217
+	// Provider price id (Stripe Price). Empty for free/unpriced offers; pass to
+	// `<sail-checkout-button [priceId]>` / `createCheckout({ priceId })`.
+	priceId?:     string;
+}
+
 // PublicPlan — shape returned by GET /public/plans. Used on the registration
 // page to render the plan picker and to drive `<sail-checkout-button>` flows.
 export interface PublicPlan {
 	id:          string;
 	caption:     string;
-	monthlyCost: number;
-	annualCost:  number;
-	// Stripe price ID (or provider-equivalent). Optional because keel only
-	// populates it when a plan is wired to a billing provider; FREE plans and
-	// not-yet-priced tiers leave it empty. Pass straight to
-	// `<sail-checkout-button [priceId]>` / `BillingService.createCheckout({ priceId })`.
+	// NOTE: keel v1.0.7 REMOVED the flat `monthlyCost`/`annualCost` from the plan
+	// JSON (both `/public/plans` and the billing catalog). Price lives per-offer
+	// in `prices[]`; derive a display price with `fromPriceLabel(plan.prices)`.
+	// Purchasable offers (keel v1.0.5 `subscription_plan_price`, nested under the
+	// plan). The source of truth for checkout — feed a chosen offer's `priceId`
+	// to `<sail-checkout-button>`. Returned by `/public/plans` as of keel v1.0.6
+	// (so `<sail-price-selector>` works on the registration page too); absent on
+	// pre-v1.0.6 backends.
+	prices?:     PlanPrice[];
+	// @deprecated keel v1.0.5 moved per-offer prices into `prices[]`
+	// (`subscription_plan.provider_price_id` was dropped). Use
+	// `prices?.[…].priceId`. Kept optional for pre-v1.0.5 backends.
 	priceId?:    string;
 	// keel `subscription_plan.activation_mode` (SUBSCRIPTION_ACTIVATION_MODE
 	// dictionary, single char — e.g. 'P' paid, 'F' free, 'T' trial). Drives the
@@ -284,6 +306,25 @@ export interface UsageMeter {
 	limit:    number;
 }
 
+// Normalized outcome of an off-session charge — the camelCase JSON shape an app
+// returns from its own charge endpoint, mirroring keel `payment.ChargeResult`.
+// 'requires_action' means the rider must complete an SCA / 3DS confirmation
+// (drive it with `<sail-sca-confirm>`).
+export type ChargeStatus = 'succeeded' | 'requires_action' | 'failed';
+
+export interface ChargeResult {
+	status:            ChargeStatus;
+	providerChargeId?: string;   // PaymentIntent / charge id (pi_xxx)
+	// Provider client secret — present when status === 'requires_action' and the
+	// SCA challenge must be confirmed inline (provider SDK). Mirrors keel
+	// ChargeResult.ClientSecret.
+	clientSecret?:     string;
+	// Provider-hosted redirect URL when one exists (often empty for off-session
+	// 3DS). When present it's the simplest, provider-agnostic confirmation path.
+	actionUrl?:        string;
+	error?:            string;   // decline / error message when status === 'failed'
+}
+
 // REST list endpoints return paginated wrappers. `BackendService.list<T>()`
 // unwraps to the array; use `listPaginated<T>()` to get the metadata.
 export interface PaginatedList<T> {
@@ -301,6 +342,9 @@ export interface Subscription {
 	monthlyCost: number;
 	currency:    string;
 	autoRenew:   boolean;
+	// PERIOD_TYPE code (D/W/M/A) the sub is charged on, copied from the chosen
+	// offer (keel `billing_cycle`); absent on pre-v1.0.5 backends.
+	billingCycle?: string;
 	// ISO timestamp the trial ends (keel `trial_end`); empty/absent when not
 	// trialing. Drives `<sail-trial-banner>`.
 	trialEnd?:   string;

package/src/service/sca_confirmer.ts

@@ -0,0 +1,29 @@
+import { InjectionToken } from '@angular/core';
+
+/** Outcome of a client-side SCA / 3DS confirmation attempt. */
+export type ScaOutcome = 'succeeded' | 'failed' | 'cancelled';
+
+export interface ScaResult {
+  outcome: ScaOutcome;
+  error?:  string;
+}
+
+/**
+ * Provider-agnostic port for confirming a Strong Customer Authentication (3DS)
+ * challenge on a `client_secret` returned by an off-session charge.
+ *
+ * sail ships NO provider SDK and NO default implementation — each app provides
+ * one for its payment provider (e.g. a thin Stripe.js wrapper calling
+ * `stripe.handleNextAction({ clientSecret })`) and registers it at composition
+ * time, keeping the provider choice out of the shared library:
+ *
+ *   { provide: SCA_CONFIRMER, useClass: StripeScaConfirmer }
+ *
+ * The `actionUrl` (provider-hosted redirect) branch needs no confirmer — only
+ * the inline `clientSecret` branch delegates here.
+ */
+export interface ScaConfirmer {
+  confirm(clientSecret: string): Promise<ScaResult>;
+}
+
+export const SCA_CONFIRMER = new InjectionToken<ScaConfirmer>('SailScaConfirmer');

package/src/util/money.ts

@@ -0,0 +1,29 @@
+import { PlanPrice } from '../model/appdata';
+
+/**
+ * Format a major-unit amount in its currency, honouring the currency exponent
+ * (JPY 0 decimals, BHD 3, …) via `Intl`. Falls back to "<amount> <currency>"
+ * for an unknown currency code rather than throwing.
+ */
+export function formatCurrency(amount: number, currency: string): string {
+  try {
+    return new Intl.NumberFormat(undefined, { style: 'currency', currency }).format(amount);
+  } catch {
+    return `${amount} ${currency}`;
+  }
+}
+
+/**
+ * "From" price teaser for a plan card / dropdown — the lowest priced offer,
+ * currency-formatted, prefixed "from " when the plan sells more than one priced
+ * offer. Returns '' when the plan has no priced offers (free/trial), so callers
+ * can omit the price line entirely. The exact offer is chosen later via
+ * `<sail-price-selector>`.
+ */
+export function fromPriceLabel(prices: PlanPrice[] | undefined): string {
+  const priced = (prices ?? []).filter((p) => p.amount > 0);
+  if (priced.length === 0) return '';
+  const lowest = priced.reduce((a, b) => (b.amount < a.amount ? b : a));
+  const formatted = formatCurrency(lowest.amount, lowest.currency);
+  return priced.length > 1 ? `from ${formatted}` : formatted;
+}