@nauticana/sail 1.0.0 → 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 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,13 +465,64 @@ 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>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nauticana/sail",
-  "version": "1.0.0",
+  "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/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/index.ts

@@ -34,6 +34,10 @@ 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

@@ -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.
@@ -288,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

@@ -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',