@nauticana/sail 0.9.6 → 1.0.1

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 three 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,8 +337,12 @@ 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>` |
+| `listUsage()` | `GET /api/billing/usage` | `Observable<UsageMeter[]>` |
 
 ### Components
 
@@ -436,6 +440,95 @@ Add to `src/styles.css` to match the rest of the library:
 .checkout-button { display: flex; flex-direction: column; gap: .5rem; }
 ```
 
+### Customer portal (v1.0.0)
+
+`createPortalSession()` + `<sail-portal-button>` mirror checkout — POST `/api/billing/portal`, then redirect to the provider-hosted customer portal where the partner manages their payment method / subscription:
+
+```html
+<sail-portal-button [label]="'Manage billing'"></sail-portal-button>
+```
+
+### Usage meters (v1.0.0)
+
+`listUsage()` returns `UsageMeter[]` (`{ resource, used, limit }`, matching keel's `UsageItem`); `<sail-usage-meter>` renders one progress bar per resource (a `limit < 0` shows "Unlimited"):
+
+```typescript
+readonly meters = toSignal(this.billing.listUsage(), { initialValue: [] });
+```
+```html
+<sail-usage-meter [meters]="meters()"></sail-usage-meter>
+```
+
+### Redirect-action (v1.0.0)
+
+A `TableAction` with `kind: 'redirect'` makes `BaseTable.executeAction` POST and then follow the returned `{ url }` instead of refreshing — so checkout / portal / any provider-hosted handoff can be declared as a basis `table_action` row with **no bespoke component**. The backend action handler returns `{ "url": "https://…" }`.
+
+> **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-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 -->
+```
+
 ## 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": "0.9.6",
+  "version": "1.0.1",
   "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/abstract/base_table.ts

@@ -114,8 +114,17 @@ export abstract class BaseTable {
         if (!this.beforeExecuteAction(action, record)) return;
         if (action.confirmMessage && !confirm(action.confirmMessage)) return;
         const body = action.recordSpecific && record ? this.primaryKeyValues(record) : {};
-        this.backendService.executeAction(action.method, body).subscribe({
-            next: () => this.onActionSuccess(action, record),
+        this.backendService.executeAction<{ url?: string }>(action.method, body).subscribe({
+            next: (resp) => {
+                // A 'redirect' action POSTs then follows the returned {url}
+                // (provider-hosted checkout / portal / any external handoff
+                // declared as basis table_action metadata — no component).
+                if (action.kind === 'redirect' && resp?.url) {
+                    window.location.href = resp.url;
+                    return;
+                }
+                this.onActionSuccess(action, record);
+            },
             error: (err) => {
                 console.error(`Action ${action.action} failed`, err);
                 alert(err?.error?.detail ?? `Failed to ${action.caption}`);

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/portal_button.html

@@ -0,0 +1,10 @@
+<div class="portal-button">
+  <button matButton="elevated" class="primary" type="button"
+          [disabled]="loading()"
+          (click)="openPortal()">
+    @if (loading()) { Opening… } @else { {{ label() }} }
+  </button>
+  @if (errorMessage()) {
+    <div class="auth-error" role="alert">{{ errorMessage() }}</div>
+  }
+</div>

package/src/component/billing/portal_button.ts

@@ -0,0 +1,31 @@
+import { ChangeDetectionStrategy, Component, ViewEncapsulation, inject, input } from '@angular/core';
+import { MatButtonModule } from '@angular/material/button';
+import { BaseAsync } from '../abstract/base_async';
+import { BillingService } from '../../service/billing.service';
+
+/**
+ * Button that opens a provider customer-portal session and redirects the
+ * browser to the returned URL — the partner manages their payment method /
+ * subscription on the provider's hosted page. Mirrors CheckoutButtonComponent;
+ * uses BaseAsync for loading/error state.
+ */
+@Component({
+  selector: 'sail-portal-button',
+  templateUrl: './portal_button.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  imports: [MatButtonModule],
+})
+export class PortalButtonComponent extends BaseAsync {
+  private readonly billing = inject(BillingService);
+
+  readonly label = input('Manage billing');
+
+  openPortal(): void {
+    this.run(
+      this.billing.createPortalSession(),
+      (resp) => { window.location.href = resp.portalUrl; },
+      'Could not open the billing portal. Please try again.',
+    );
+  }
+}

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/billing/usage_meter.html

@@ -0,0 +1,20 @@
+<div class="usage-meter">
+  @for (r of rows(); track r.resource) {
+    <div class="usage-row">
+      <div class="usage-label">{{ r.resource }}</div>
+      @if (r.hasBar) {
+        <div class="usage-bar" role="progressbar"
+             [attr.aria-label]="r.resource"
+             [attr.aria-valuemin]="0"
+             [attr.aria-valuemax]="r.ariaMax"
+             [attr.aria-valuenow]="r.ariaNow"
+             [attr.aria-valuetext]="r.valueText">
+          <div class="usage-fill" [style.width.%]="r.percent"></div>
+        </div>
+      }
+      <div class="usage-value">{{ r.valueText }}</div>
+    </div>
+  } @empty {
+    <div class="usage-empty">No usage data.</div>
+  }
+</div>

package/src/component/billing/usage_meter.ts

@@ -0,0 +1,44 @@
+import { ChangeDetectionStrategy, Component, ViewEncapsulation, computed, input } from '@angular/core';
+import { UsageMeter } from '../../model/appdata';
+
+/** Per-row view model derived from a UsageMeter for accessible rendering. */
+interface UsageRow {
+  resource:  string;
+  hasBar:    boolean;   // limit > 0 → determinate progress bar; else text-only
+  percent:   number;    // fill width 0..100 (clamped)
+  ariaMax:   number;    // limit (only meaningful when hasBar)
+  ariaNow:   number;    // used, clamped to [0, limit] for a valid progressbar
+  valueText: string;    // "used / limit", "used / Unlimited" (<0), or "used / 0"
+}
+
+/**
+ * Presentational usage meters — one progress bar per resource (used / limit).
+ * Stateless; the caller (or BillingService.listUsage) supplies the data.
+ *
+ * Limit semantics mirror keel's UsageItem: `limit < 0` = unlimited (keel's
+ * documented sentinel), `limit === 0` = a real zero / unprovisioned cap. Only
+ * `limit > 0` renders a determinate progress bar; the other two are text-only.
+ */
+@Component({
+  selector: 'sail-usage-meter',
+  templateUrl: './usage_meter.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+})
+export class UsageMeterComponent {
+  readonly meters = input<UsageMeter[]>([]);
+
+  readonly rows = computed<UsageRow[]>(() =>
+    this.meters().map((m) => {
+      const hasBar = m.limit > 0;
+      return {
+        resource:  m.resource,
+        hasBar,
+        percent:   hasBar ? Math.min(100, Math.round((m.used / m.limit) * 100)) : 0,
+        ariaMax:   m.limit,
+        ariaNow:   hasBar ? Math.min(m.used, m.limit) : m.used,
+        valueText: `${m.used} / ${m.limit < 0 ? 'Unlimited' : m.limit}`,
+      };
+    }),
+  );
+}

package/src/index.ts

@@ -32,6 +32,12 @@ export * from './component/security/trusted_devices';
 export * from './component/billing/plan_selector';
 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';

package/src/model/appdata.ts

@@ -83,6 +83,7 @@ export interface TableAction {
   confirmMessage?:  string;
   authorityObject:  string;   // uppercased table_name — for canExecute()
   authorityCheck:   string;   // uppercased action_name — for canExecute()
+  kind?:            'post' | 'redirect'; // 'redirect' = POST then follow the returned {url}; default 'post'
 }
 
 export interface ForeignKey {
@@ -212,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.
@@ -264,6 +272,18 @@ export interface CheckoutResponse {
 	checkoutUrl: string;
 }
 
+/** Response of BillingService.createPortalSession — the provider customer-portal URL. */
+export interface PortalResponse {
+	portalUrl: string;
+}
+
+/** One resource's current-period usage vs its plan limit (matches keel UsageItem). */
+export interface UsageMeter {
+	resource: string;
+	used:     number;
+	limit:    number;
+}
+
 // REST list endpoints return paginated wrappers. `BackendService.list<T>()`
 // unwraps to the array; use `listPaginated<T>()` to get the metadata.
 export interface PaginatedList<T> {
@@ -275,12 +295,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

@@ -7,8 +7,10 @@ import {
   CheckoutResponse,
   Invoice,
   PaymentMethod,
+  PortalResponse,
   PublicPlan,
   Subscription,
+  UsageMeter,
 } from '../model/appdata';
 
 /**
@@ -47,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));
@@ -56,4 +72,18 @@ export class BillingService extends BaseRestService {
   listPaymentMethods(): Observable<PaymentMethod[]> {
     return this.http.get<PaymentMethod[]>(this.url(RestURL.paymentMethodsURL));
   }
+
+  /**
+   * Create a provider customer-portal session; caller redirects to the URL so
+   * the partner can manage their payment method / subscription on the
+   * provider's hosted page.
+   */
+  createPortalSession(): Observable<PortalResponse> {
+    return this.http.post<PortalResponse>(this.url(RestURL.portalURL), {});
+  }
+
+  /** Current-period usage per resource (used vs plan limit). */
+  listUsage(): Observable<UsageMeter[]> {
+    return this.http.get<UsageMeter[]>(this.url(RestURL.usageURL));
+  }
 }

package/src/service/rest_url.ts

@@ -20,8 +20,12 @@ 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',
+  usageURL:          '/api/billing/usage',
   // OTP / social / push / account-lifecycle endpoints
   otpSendURL:          '/public/otp/send',
   otpVerifyURL:        '/public/otp/verify',