@nauticana/sail 1.0.0 → 1.0.2

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 five 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 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).
 
 ### Service
 
@@ -337,6 +337,8 @@ export class PricingPage {
 | `createCheckout(req)` | `POST /api/billing/checkout` | `Observable<CheckoutResponse>` |
 | `getSubscription()` | `GET /api/billing/subscription` | `Observable<Subscription>` |
 | `cancelSubscription()` | `POST /api/billing/subscription/cancel` | `Observable<void>` |
+| `changePlan(planId)` | `POST /api/billing/subscription/change` | `Observable<void>` |
+| `setSeats(seats)` | `POST /api/billing/subscription/seats` | `Observable<void>` |
 | `listInvoices()` | `GET /api/billing/invoices` | `Observable<Invoice[]>` |
 | `listPaymentMethods()` | `GET /api/billing/payment-methods` | `Observable<PaymentMethod[]>` |
 | `createPortalSession()` | `POST /api/billing/portal` | `Observable<PortalResponse>` |
@@ -463,19 +465,134 @@ A `TableAction` with `kind: 'redirect'` makes `BaseTable.executeAction` POST and
 
 > **Response-shape contract.** The generic redirect-action path reads a bare `url` because it's polymorphic — one dispatch for checkout / portal / export / etc., where the action's identity lives in the metadata, not the payload. keel's `WrapTableAction` enforces no shape; your inner handler must return `{ url }`. The *typed* billing endpoints keep specific names instead (`createCheckout()` → `checkoutUrl`, `createPortalSession()` → `portalUrl`). So the same portal concept has two response shapes depending on the path: wire it as `<sail-portal-button>` (typed → `portalUrl`) **or** as a `table_action` redirect (generic → `url`), not both.
 
+### Status chip (v1.0.1)
+
+`<sail-status-chip>` resolves a code to its caption from the client-cache `constant_value` dictionary — no per-app `@switch`. It defaults to the `SUBSCRIPTION_STATUS` domain (so `T` trialing / `X` past-due render with no app code) and works for any constant domain via `[domain]`. The code is exposed as `[attr.data-status]` so the app can colour the chip:
+
+```html
+<sail-status-chip [value]="sub()?.status"></sail-status-chip>
+<sail-status-chip [value]="invoice.status" domain="INVOICE_STATUS"></sail-status-chip>
+```
+
+> Replaces a downstream app's hardcoded status `@switch` (e.g. seo's): captions are backend-authoritative — when a dictionary row is absent the raw code shows, never a fabricated label.
+
+### Trial banner (v1.0.1)
+
+`<sail-trial-banner>` shows "Trial ends in N days" from `Subscription.trialEnd`; it renders nothing when the value is empty, unparseable, or already past, so it can sit unconditionally in the template:
+
+```html
+<sail-trial-banner [trialEnd]="sub()?.trialEnd"></sail-trial-banner>
+```
+
+### Seat selector (v1.0.1)
+
+`<sail-seat-selector>` is a presentational quantity stepper seeded from `Subscription.seats`. Feed the result into checkout (`[quantity]` / metadata) for new subs, or `BillingService.setSeats()` for an existing one:
+
+```html
+<sail-seat-selector [seats]="sub()?.seats ?? 1" [min]="1" (seatsChange)="seats.set($event)"></sail-seat-selector>
+```
+
+### Plan change vs first-time checkout (v1.0.1)
+
+First-time checkout uses `<sail-checkout-button>` (provider-hosted). For an **existing** subscription, upgrade/downgrade is a distinct path — `BillingService.changePlan(planId)` routes to keel's `SubscriptionLifecycle.ChangePlan` via an endpoint the app exposes. Wire the picker's selection to whichever path applies:
+
+```typescript
+onPlanPicked(planId: string) {
+  this.sub() ? this.billing.changePlan(planId).subscribe() : this.startCheckout(planId);
+}
+```
+
+`<sail-plan-selector>` varies its CTA copy by `PublicPlan.activationMode` ("Start trial" for `T`, "Subscribe" for `P`, "Activate" for `F`); override or extend via `[ctaLabels]="{ S: 'Add seats' }"`.
+
+### Dunning banner (v1.0.1)
+
+`<sail-dunning-banner>` shows only when `Subscription.status === 'X'` (past-due / keel `SetDunningState`), prompting the partner to update their card and deep-linking to the provider portal via an embedded `<sail-portal-button>`:
+
+```html
+<sail-dunning-banner [status]="sub()?.status"></sail-dunning-banner>
+```
+
 ### Compose a full Billing screen
 
 A complete screen is the pieces above assembled over `BillingService` — no metadata CRUD (billing data is partner-scoped, read-mostly, money-formatted, with an external-redirect action, which `TableList`/`TableEdit` don't model):
 
 ```html
-<sail-plan-selector [plans]="plans()" [selected]="sub()?.planId" (selectionChange)="selected.set($event)"></sail-plan-selector>
-<sail-checkout-button [priceId]="priceFor(selected())" [successUrl]="okUrl" [cancelUrl]="backUrl"></sail-checkout-button>
+<sail-dunning-banner [status]="sub()?.status"></sail-dunning-banner>
+<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-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-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.0",
+  "version": "1.0.2",
   "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/dunning_banner.html

@@ -0,0 +1,6 @@
+@if (isPastDue()) {
+  <div class="dunning-banner" role="alert">
+    <span class="dunning-message">{{ message() }}</span>
+    <sail-portal-button label="Update your card"></sail-portal-button>
+  </div>
+}

package/src/component/billing/dunning_banner.ts

@@ -0,0 +1,23 @@
+import { ChangeDetectionStrategy, Component, ViewEncapsulation, computed, input } from '@angular/core';
+import { PortalButtonComponent } from './portal_button';
+
+/**
+ * Past-due (dunning) banner. Shows only when the subscription status is the
+ * past-due code 'X' (keel `SetDunningState`), prompting the partner to update
+ * their card and deep-linking to the provider portal via `<sail-portal-button>`.
+ * Renders nothing otherwise, so it can sit unconditionally in the template.
+ */
+@Component({
+  selector: 'sail-dunning-banner',
+  templateUrl: './dunning_banner.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  imports: [PortalButtonComponent],
+})
+export class DunningBannerComponent {
+  /** Subscription.status — the banner shows when this is 'X' (past-due). */
+  readonly status = input<string | undefined>(undefined);
+  readonly message = input('Your payment is past due — please update your card to keep your subscription active.');
+
+  readonly isPastDue = computed(() => this.status() === 'X');
+}

package/src/component/billing/plan_selector.html

@@ -14,7 +14,7 @@
         </ul>
       }
       <button matButton="elevated" class="primary" type="button" (click)="onSelect(plan.id)">
-        @if (plan.id === selected()) { Selected } @else { Choose }
+        @if (plan.id === selected()) { Selected } @else { {{ ctas()[plan.id] }} }
       </button>
     </div>
   }

package/src/component/billing/plan_selector.ts

@@ -1,10 +1,14 @@
-import { ChangeDetectionStrategy, Component, ViewEncapsulation, input, output } from '@angular/core';
+import { ChangeDetectionStrategy, Component, ViewEncapsulation, computed, input, output } from '@angular/core';
 import { MatButtonModule } from '@angular/material/button';
 import { PublicPlan } from '../../model/appdata';
 
 /**
  * Plan picker. Pure presentational component — stateless, no service calls.
  * The caller provides the plans and handles the selection event.
+ *
+ * The per-plan CTA copy varies by `PublicPlan.activationMode` (e.g. 'T' →
+ * "Start trial", 'P' → "Subscribe"); override or extend the mapping via
+ * `[ctaLabels]` (e.g. `{ S: 'Add seats' }`).
  */
 @Component({
   selector: 'sail-plan-selector',
@@ -14,11 +18,30 @@ import { PublicPlan } from '../../model/appdata';
   imports: [MatButtonModule],
 })
 export class PlanSelectorComponent {
+  private static readonly DEFAULT_CTA: Record<string, string> = {
+    T: 'Start trial',
+    F: 'Activate',
+    P: 'Subscribe',
+  };
+
   readonly plans = input<PublicPlan[]>([]);
   readonly selected = input<string | undefined>(undefined);
   readonly features = input<{[planId: string]: string[]}>({});
+  /** activationMode → CTA copy; overrides/extends the built-in defaults. */
+  readonly ctaLabels = input<{[activationMode: string]: string}>({});
   readonly selectionChange = output<string>();
 
+  /** planId → CTA label, resolved from activationMode (override wins). */
+  readonly ctas = computed<Record<string, string>>(() => {
+    const overrides = this.ctaLabels();
+    const out: Record<string, string> = {};
+    for (const plan of this.plans()) {
+      const mode = plan.activationMode ?? '';
+      out[plan.id] = overrides[mode] ?? PlanSelectorComponent.DEFAULT_CTA[mode] ?? 'Choose';
+    }
+    return out;
+  });
+
   onSelect(planId: string): void {
     this.selectionChange.emit(planId);
   }

package/src/component/billing/seat_selector.html

@@ -0,0 +1,15 @@
+<div class="seat-selector" role="group" aria-label="Seats">
+  <button matIconButton type="button"
+          aria-label="Decrease seats"
+          [disabled]="!canDecrease()"
+          (click)="decrease()">
+    <mat-icon>remove</mat-icon>
+  </button>
+  <span class="seat-count" aria-live="polite">{{ seats() }}</span>
+  <button matIconButton type="button"
+          aria-label="Increase seats"
+          [disabled]="!canIncrease()"
+          (click)="increase()">
+    <mat-icon>add</mat-icon>
+  </button>
+</div>

package/src/component/billing/seat_selector.ts

@@ -0,0 +1,54 @@
+import { ChangeDetectionStrategy, Component, ViewEncapsulation, computed, effect, input, output, signal } from '@angular/core';
+import { MatButtonModule } from '@angular/material/button';
+import { MatIconModule } from '@angular/material/icon';
+
+/**
+ * Seat quantity stepper. Presentational — emits the chosen count; the caller
+ * feeds it into `<sail-checkout-button [quantity]>` / checkout metadata or a
+ * `BillingService.setSeats()` call. Seed `[seats]` from `Subscription.seats`.
+ */
+@Component({
+  selector: 'sail-seat-selector',
+  templateUrl: './seat_selector.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  imports: [MatButtonModule, MatIconModule],
+})
+export class SeatSelectorComponent {
+  /** Initial / parent-bound seat count. */
+  readonly seatsInput = input(1, { alias: 'seats' });
+  /** Minimum selectable seats. */
+  readonly min = input(1);
+  /** Maximum selectable seats; unbounded when undefined. */
+  readonly max = input<number | undefined>(undefined);
+  readonly seatsChange = output<number>();
+
+  /** Locally-mutated value, synced from the parent-bound input. */
+  readonly seats = signal(1);
+
+  readonly canDecrease = computed(() => this.seats() > this.min());
+  readonly canIncrease = computed(() => {
+    const max = this.max();
+    return max === undefined || this.seats() < max;
+  });
+
+  constructor() {
+    effect(() => this.seats.set(this.seatsInput()));
+  }
+
+  decrease(): void {
+    this.commit(Math.max(this.min(), this.seats() - 1));
+  }
+
+  increase(): void {
+    const max = this.max();
+    const next = this.seats() + 1;
+    this.commit(max === undefined ? next : Math.min(max, next));
+  }
+
+  private commit(value: number): void {
+    if (value === this.seats()) return;
+    this.seats.set(value);
+    this.seatsChange.emit(value);
+  }
+}

package/src/component/billing/status_chip.html

@@ -0,0 +1,3 @@
+@if (value()) {
+  <span class="status-chip" [attr.data-status]="value()">{{ caption() }}</span>
+}

package/src/component/billing/status_chip.ts

@@ -0,0 +1,39 @@
+import { ChangeDetectionStrategy, Component, ViewEncapsulation, computed, inject, input } from '@angular/core';
+import { toSignal } from '@angular/core/rxjs-interop';
+import { BaseAuthService } from '../../service/auth.service';
+
+/**
+ * Status chip/label that resolves a code to its caption from the client cache
+ * `constant_value` dictionary — no per-app `@switch`. Defaults to the
+ * `SUBSCRIPTION_STATUS` domain (A active / T trialing / X past-due / …) but
+ * works for any constant domain via `[domain]`.
+ *
+ * The caption is backend-authoritative (read from the dictionary); when the
+ * domain row is absent the raw code is shown rather than a fabricated label.
+ * `[attr.data-status]` carries the code so the consuming app can colour the
+ * chip per status (the library ships no CSS).
+ */
+@Component({
+  selector: 'sail-status-chip',
+  templateUrl: './status_chip.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+})
+export class StatusChipComponent {
+  private readonly auth = inject(BaseAuthService);
+
+  /** The code to resolve (e.g. a Subscription.status value). */
+  readonly value = input<string>('');
+  /** Constant-value domain to look the caption up in. */
+  readonly domain = input<string>('SUBSCRIPTION_STATUS');
+
+  // Recompute when the cache (app data) loads or the inputs change.
+  private readonly appData = toSignal(this.auth.getAppData());
+
+  readonly caption = computed<string>(() => {
+    this.appData(); // dependency: re-read the dictionary once the cache is hydrated
+    const code = this.value();
+    const match = this.auth.getDomainValues(this.domain())?.find((v) => v.Value === code);
+    return match?.Caption ?? code;
+  });
+}

package/src/component/billing/trial_banner.html

@@ -0,0 +1,3 @@
+@if (daysLeft() > 0) {
+  <div class="trial-banner" role="status">{{ message() }}</div>
+}

package/src/component/billing/trial_banner.ts

@@ -0,0 +1,30 @@
+import { ChangeDetectionStrategy, Component, ViewEncapsulation, computed, input } from '@angular/core';
+
+/**
+ * "Trial ends in N days" banner, bound to `Subscription.trialEnd`. Renders
+ * nothing when `trialEnd` is empty, unparseable, or already past, so it can be
+ * left in the template unconditionally.
+ */
+@Component({
+  selector: 'sail-trial-banner',
+  templateUrl: './trial_banner.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+})
+export class TrialBannerComponent {
+  /** ISO timestamp the trial ends (Subscription.trialEnd). */
+  readonly trialEnd = input<string | undefined>(undefined);
+
+  readonly daysLeft = computed<number>(() => {
+    const raw = this.trialEnd();
+    if (!raw) return 0;
+    const end = Date.parse(raw);
+    if (Number.isNaN(end)) return 0;
+    return Math.ceil((end - Date.now()) / 86_400_000);
+  });
+
+  readonly message = computed<string>(() => {
+    const d = this.daysLeft();
+    return d === 1 ? 'Trial ends in 1 day' : `Trial ends in ${d} days`;
+  });
+}

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

@@ -34,10 +34,16 @@ export * from './component/billing/checkout_button';
 export * from './component/billing/payment_methods';
 export * from './component/billing/portal_button';
 export * from './component/billing/usage_meter';
+export * from './component/billing/status_chip';
+export * from './component/billing/trial_banner';
+export * from './component/billing/seat_selector';
+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';

package/src/model/appdata.ts

@@ -213,6 +213,13 @@ export interface PublicPlan {
 	// not-yet-priced tiers leave it empty. Pass straight to
 	// `<sail-checkout-button [priceId]>` / `BillingService.createCheckout({ priceId })`.
 	priceId?:    string;
+	// keel `subscription_plan.activation_mode` (SUBSCRIPTION_ACTIVATION_MODE
+	// dictionary, single char — e.g. 'P' paid, 'F' free, 'T' trial). Drives the
+	// picker CTA copy ("Start trial" / "Subscribe" / …). Optional — pre-v1.0.3
+	// backends omit it.
+	activationMode?: string;
+	// Length of the free trial in days when `activationMode === 'T'`.
+	trialDays?:      number;
 }
 
 // ConfirmRegisterResponse — shape returned by POST /public/confirm/register.
@@ -277,6 +284,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> {
@@ -288,12 +314,18 @@ export interface PaginatedList<T> {
 
 export interface Subscription {
 	planId:      string;
-	status:      string;  // 'A' active, 'P' pending-payment, 'C' cancelled, ...
+	status:      string;  // 'A' active, 'P' pending-payment, 'C' cancelled, 'T' trialing, 'X' past-due — caption via SUBSCRIPTION_STATUS dict
 	begda:       string;
 	endda?:      string;
 	monthlyCost: number;
 	currency:    string;
 	autoRenew:   boolean;
+	// ISO timestamp the trial ends (keel `trial_end`); empty/absent when not
+	// trialing. Drives `<sail-trial-banner>`.
+	trialEnd?:   string;
+	// Seat quantity on the active/trial sub (keel `seats`); absent for
+	// non-seat plans. Drives `<sail-seat-selector>`.
+	seats?:      number;
 }
 
 export interface Invoice {

package/src/service/billing.service.ts

@@ -49,6 +49,20 @@ export class BillingService extends BaseRestService {
     return this.http.post<void>(this.url(RestURL.cancelSubURL), {});
   }
 
+  /**
+   * Upgrade / downgrade the current subscription to `planId` — distinct from
+   * first-time checkout. Routes to keel's `SubscriptionLifecycle.ChangePlan`
+   * (atomic close+open) via an endpoint the app exposes.
+   */
+  changePlan(planId: string): Observable<void> {
+    return this.http.post<void>(this.url(RestURL.changePlanURL), { planId });
+  }
+
+  /** Set the seat quantity on the current active/trial subscription. */
+  setSeats(seats: number): Observable<void> {
+    return this.http.post<void>(this.url(RestURL.seatsURL), { seats });
+  }
+
   /** Partner's invoice history. */
   listInvoices(): Observable<Invoice[]> {
     return this.http.get<Invoice[]>(this.url(RestURL.invoicesURL));

package/src/service/rest_url.ts

@@ -20,6 +20,8 @@ export const RestURL = {
   checkoutURL:       '/api/billing/checkout',
   subscriptionURL:   '/api/billing/subscription',
   cancelSubURL:      '/api/billing/subscription/cancel',
+  changePlanURL:     '/api/billing/subscription/change',
+  seatsURL:          '/api/billing/subscription/seats',
   invoicesURL:       '/api/billing/invoices',
   paymentMethodsURL: '/api/billing/payment-methods',
   portalURL:         '/api/billing/portal',

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');