@nauticana/sail 0.9.5 → 1.0.0

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 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).
 
 ### Service
 
@@ -339,6 +339,8 @@ export class PricingPage {
 | `cancelSubscription()` | `POST /api/billing/subscription/cancel` | `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 +438,44 @@ 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.
+
+### 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-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.5",
+  "version": "1.0.0",
   "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/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/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,8 @@ 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/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 {
@@ -264,6 +265,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> {

package/src/service/auth.service.ts

@@ -16,6 +16,10 @@ import { CanActivateFn, Router, Routes } from '@angular/router';
 import { SAIL_GUI_CONFIG, SailGuiConfig, DEFAULT_CONFIG } from '../config';
 import { BaseRestService } from './base_rest.service';
 
+/** Sort dropdown options by their visible label so long lookup lists are scannable. */
+const byCaption = (a: ConstantValue, b: ConstantValue) =>
+  (a.Caption ?? '').localeCompare(b.Caption ?? '', undefined, { numeric: true, sensitivity: 'base' });
+
 @Injectable()
 export abstract class BaseAuthService extends BaseRestService {
   protected readonly router = inject(Router);
@@ -416,7 +420,7 @@ export abstract class BaseAuthService extends BaseRestService {
         Value: key,
         Caption: domainMap[key],
         [opField]: 'S',
-    } as unknown as ConstantValue));
+    } as unknown as ConstantValue)).sort(byCaption);
   }
 
   getTableValues(tableName: string): ConstantValue[] | undefined {
@@ -430,7 +434,7 @@ export abstract class BaseAuthService extends BaseRestService {
         Value: key,
         Caption: tableMap[key],
         [opField]: 'S',
-    } as unknown as ConstantValue));
+    } as unknown as ConstantValue)).sort(byCaption);
   }
 
   getMenus(): Observable<ApplicationMenu[]> {

package/src/service/billing.service.ts

@@ -7,8 +7,10 @@ import {
   CheckoutResponse,
   Invoice,
   PaymentMethod,
+  PortalResponse,
   PublicPlan,
   Subscription,
+  UsageMeter,
 } from '../model/appdata';
 
 /**
@@ -56,4 +58,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

@@ -22,6 +22,8 @@ export const RestURL = {
   cancelSubURL:      '/api/billing/subscription/cancel',
   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',