@nauticana/sail 1.1.16 → 1.1.18

package/README.md

@@ -2,7 +2,7 @@
 
 A shared Angular component library for building CRUD-based admin frontends. Provides table management, form handling, navigation, authentication, two-factor authentication, and trusted device management — all driven by metadata from a [keel](https://github.com/nauticana/keel) Go backend.
 
-> **Compatibility:** sail and keel are versioned in lock-step. The current line is **sail v1.1.x ↔ keel v1.2.x**; the agency components in sail v1.1.14 require keel v1.2.41 (sail v1.1.9 needs keel v1.2.16 for the OAuth-connect layer). Earlier lines: **sail v0.5.x ↔ keel v0.5.x**, **sail v0.6.x / v0.7.x ↔ keel v0.7.x**, **sail v0.8.x ↔ keel v0.8.x**, **sail v0.9.x ↔ keel v0.9.x**. Newer sail releases extend the contract — older keel servers reject unknown endpoints with HTTP 404 / 400. The v0.8.x line additionally ships the `table_action` framework (per-table custom buttons surfaced in `TableList` / `TableSearch` / `TableEdit` / `TableDetail`); see the [Migrating to v0.7.0 §5 — TableAction](#migrating-to-v070--payout-user-payment-methods-table-actions) section for the seed shape (basis `table_action` + `authorization_object` + `authorization_object_action` rows) and the [keel/README Table Actions](https://github.com/nauticana/keel#table-actions) section for backend wiring via `handler.WrapTableAction`.
+> **Compatibility:** sail and keel are versioned in lock-step. The current line is **sail v1.1.x ↔ keel v1.2.x**; sail v1.1.18 adopts keel v1.2.58 (refresh-token rotation, `/public/logout`, setup intents, the realtime hub), the agency components in sail v1.1.14 require keel v1.2.41 (sail v1.1.9 needs keel v1.2.16 for the OAuth-connect layer). Earlier lines: **sail v0.5.x ↔ keel v0.5.x**, **sail v0.6.x / v0.7.x ↔ keel v0.7.x**, **sail v0.8.x ↔ keel v0.8.x**, **sail v0.9.x ↔ keel v0.9.x**. Newer sail releases extend the contract — older keel servers reject unknown endpoints with HTTP 404 / 400. The v0.8.x line additionally ships the `table_action` framework (per-table custom buttons surfaced in `TableList` / `TableSearch` / `TableEdit` / `TableDetail`); see the [Migrating to v0.7.0 §5 — TableAction](#migrating-to-v070--payout-user-payment-methods-table-actions) section for the seed shape (basis `table_action` + `authorization_object` + `authorization_object_action` rows) and the [keel/README Table Actions](https://github.com/nauticana/keel#table-actions) section for backend wiring via `handler.WrapTableAction`.
 
 **Recent additions:** `BaseAuthService.acceptToken(jwt)` — adopt an externally-minted JWT (registration / SSO-handoff flows) and run the full post-login sequence (store under the canonical `jwt` key, load appdata, init routes); apps must use this instead of writing `localStorage` directly. `BaseRestService.analytic<T>(endpoint, params?)` — GET a keel `analytic/<endpoint>` report and return its rows. `passwordPolicyValidator` + `BaseAuthService.ensurePasswordPolicy()` — validate passwords against keel's policy (via `SailGuiConfig.passwordPolicyUrl`); see Configuration reference.
 
@@ -240,17 +240,41 @@ keel REST list responses are paginated:
 { "items": [...], "limit": 100, "offset": 0, "total": 12345 }
 ```
 
-`BackendService.list<T>()` continues to return `Observable<T[]>` — sail unwraps `items` for you. To access the metadata, use `listPaginated<T>()`:
+`BackendService.list<T>()` continues to return `Observable<T[]>` — sail unwraps `items` for you. Both list methods accept a typed `PageRequest` after the filter map. To access the metadata, use `listPaginated<T>()`:
 
 ```typescript
-this.backend.listPaginated<MyRow>('orders', { _limit: '50', _offset: '0' })
+this.backend.listPaginated<MyRow>('orders', { Status: 'open' }, {
+    limit: 50,
+    offset: 0,
+    orderBy: 'created_at DESC',
+})
     .subscribe((page) => {
       this.rows.set(page.items);
       this.total.set(page.total);   // total rows matching the filter
     });
 ```
 
-Default page size is 100, capped at 1000 server-side. Pass `_limit` / `_offset` in the filter map to control paging.
+Default page size is 100, capped at 1000 server-side. Sail maps `limit`, `offset`, and `orderBy` to keel's `_limit`, `_offset`, and `_order` query controls. Existing callers that put those string controls in the filter map remain compatible; explicit `PageRequest` values take precedence.
+
+## Backend-driven constant captions
+
+`LabelService` loads one keel `constant_value` domain from the backend-provided `ApplicationData.ConstantCache` and caches its value-to-caption map. The domain is the backend `constant_id` (for example `ride_type`), not a locale: keel's constant catalogue does not contain a language column. It does not call generic `constant_value` CRUD, which is normally restricted to administrative roles.
+
+```typescript
+this.labels.loadLabels('ride_type').subscribe(() => {
+  this.rideTypeCaption.set(this.labels.getLabel('ride_type', ride.type));
+});
+```
+
+Concurrent loads share one application-data subscription, completed domains stay cached, and application-data failures can be retried. Missing values fall back to the raw key.
+
+## Status-filtered API errors
+
+Pass an optional status allowlist when backend detail is safe to show only for selected responses. Other HTTP statuses return the caller's generic fallback:
+
+```typescript
+errorDetail(error, 'Could not save.', [400, 409]);
+```
 
 ## Configuration reference
 
@@ -304,6 +328,9 @@ Omit the URL to skip client-side policy checks. The server stays the authoritati
 | `POST /public/otp/resend` | Re-issue OTP for an existing `otpToken` |
 | `POST /public/2fa/verify` | Login-time TOTP verification (uses `loginToken`) |
 | `POST /public/2fa/backup-verify` | Login-time backup-code verification |
+| `POST /public/token/refresh` | Rotate `{refreshToken}` → new `{token, refreshToken}`; 401 ends the session |
+| `POST /public/logout` | Revoke `{refreshToken}` (called by `BaseAuthService.logout()`) |
+| `GET /public/ws` | keel realtime hub handshake (`RealtimeService`; JWT via `?token=`) |
 | `GET /api/config/appdata` | Metadata (menus, permissions, table definitions) |
 | `POST/GET/DELETE /api/{version}/{table}/list\|get\|post\|delete` | CRUD operations (paginated `list`) |
 | `POST /api/user/2fa/setup` | Generate TOTP secret, QR URI, and backup codes — **requires re-auth** |
@@ -316,6 +343,7 @@ Omit the URL to skip client-side policy checks. The server stays the authoritati
 | `POST /api/push/register` | Register an FCM / APNs token |
 | `POST /api/push/revoke` | Revoke an FCM / APNs token |
 | `POST /api/billing/checkout` | Create provider-hosted checkout session — **JWT-gated, allowlist-validated** |
+| `POST /api/billing/setup-intent` | Provider setup intent for on-device card capture (`BillingService.createSetupIntent()`) |
 | `GET /public/plans` | Subscription plan catalog (unauthenticated) |
 | `GET /api/billing/subscription` | Active subscription for the partner |
 | `POST /api/billing/subscription/cancel` | Cancel auto-renew |
@@ -358,7 +386,15 @@ If "trust this device" appears to do nothing (user is 2FA-prompted on every logi
 
 ### Session token storage
 
-The session JWT and the short-lived `loginToken` are kept in `localStorage` (the trusted-device secret is the only HttpOnly cookie). This is a deliberate trade-off for a token-based SPA, but it means any XSS in the consuming app can read the session token. Harden accordingly: ship a strict `Content-Security-Policy`, keep third-party script surface minimal, and prefer short JWT lifetimes on the keel side.
+The session JWT, the refresh token, and the short-lived `loginToken` are kept in `localStorage` (the trusted-device secret is the only HttpOnly cookie). This is a deliberate trade-off for a token-based SPA, but it means any XSS in the consuming app can read the session token. Harden accordingly: ship a strict `Content-Security-Policy`, keep third-party script surface minimal, and prefer short JWT lifetimes on the keel side — refresh rotation makes short lifetimes free for the user.
+
+### Refresh-token rotation
+
+Every keel login response (keel v1.2.57+) carries `refreshToken` beside `token`; `completeLogin` stores both. When an authenticated call answers 401, `authInterceptor` calls `BaseAuthService.refreshSession()` — one shared `POST /public/token/refresh` per burst — stores the rotated pair and replays the request with the new JWT. A 401 from the refresh itself (revoked, expired, already rotated) clears the session and lands on `login?sessionExpired=true`; any other refresh failure keeps the session and lets the 401 count toward the circuit breaker. `logout()` posts the refresh token to `/public/logout` before clearing local state. `acceptToken(token, refreshToken?)` accepts the pair for handoff flows. No wiring beyond registering `authInterceptor`.
+
+### Realtime
+
+`RealtimeService` (root-provided) is the client for keel's `realtime.Hub`. `connect()` opens `RestURL.realtimeURL` (`/public/ws`) on the configured backend host with the stored JWT, reconnects with backoff, and re-subscribes every channel after a reconnect. `channel<T>(name)` returns the payloads keel broadcasts on that channel; `userFrames<T>()` returns payloads addressed to the user; `send(frame)` forwards an application frame to the hub's `OnMessage`. A subscription keel's `CanSubscribe` rejects is logged and exposed on `lastError`. Channel names and payload shapes are app-owned.
 
 ## Billing
 
@@ -1163,10 +1199,10 @@ Wherever you stored the OTP `sessionId`, swap it for `otpToken: string`.
 
 `BackendService.list<T>()` returns `Observable<T[]>` (unchanged). It now expects keel to return paginated `{items, limit, offset, total}` and has dropped the legacy "bare array" fallback. If you have an in-house wrapper that calls keel `list` endpoints directly, expect the wrapper shape.
 
-For pagination metadata, use `listPaginated<T>()`:
+For pagination metadata, use `listPaginated<T>()` with a typed `PageRequest`:
 
 ```typescript
-backend.listPaginated<MyRow>('orders', { _limit: '50', _offset: '0' })
+backend.listPaginated<MyRow>('orders', undefined, { limit: 50, offset: 0 })
   .subscribe(page => {
     this.rows.set(page.items);
     this.total.set(page.total);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nauticana/sail",
-  "version": "1.1.16",
+  "version": "1.1.18",
   "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",
   "scripts": {

package/src/component/payment/user_payment_methods.ts

@@ -13,8 +13,8 @@ import { UserPaymentMethod } from '../../model/appdata';
  * + delete actions. Inherits loading/error state from BaseAsync.
  *
  * Customise the heading and "add" CTA via inputs; emit (addClicked) so
- * the consumer routes to its own SetupIntent flow (sail does not bundle
- * a SetupIntent UI today — providers vary too much).
+ * the consumer routes to its own SetupIntent flow: BillingService.createSetupIntent()
+ * returns the client secret; the provider payment sheet stays app-owned.
  *
  * Ships no CSS — the consuming app styles the classes globally.
  *

package/src/component/table/table_list.ts

@@ -103,12 +103,11 @@ export class TableList extends AbstractEditableView implements OnInit {
     }
 
     private loadPage(): Observable<unknown> {
-        const filter = {
-            ...this.searchTerms(),
-            _limit: String(this.pageSize()),
-            _offset: String(this.pageIndex() * this.pageSize()),
-        };
-        return this.backendService.listPaginated<Record<string, unknown>>(this.apiName(), filter).pipe(
+        return this.backendService.listPaginated<Record<string, unknown>>(
+            this.apiName(),
+            this.searchTerms(),
+            { limit: this.pageSize(), offset: this.pageIndex() * this.pageSize() },
+        ).pipe(
             tap((page) => {
                 this.records.set(page.items ?? []);
                 this.total.set(page.total ?? page.items?.length ?? 0);

package/src/index.ts

@@ -72,6 +72,7 @@ export * from './service/oauth_connection.service';
 export * from './service/user_payment_method.service';
 export * from './service/script_loader';
 export * from './service/auth.interceptor';
+export * from './service/realtime.service';
 export * from './service/api-response.interceptor';
 export * from './service/rest_service';
 export * from './service/rest_url';

package/src/model/appdata.ts

@@ -140,8 +140,18 @@ export interface RestReport {
 
 // 2FA / Trusted device types
 
+/** POST /public/token/refresh response; every login response carries the same pair. */
+export interface TokenPair {
+  token:        string;
+  refreshToken: string;
+  userId?:      number;
+  partnerId?:   number;
+}
+
 export interface LoginResponse2FA {
   token: string;
+  /** keel v1.2.57+: rotated at /public/token/refresh when the JWT expires. */
+  refreshToken?: string;
   twoFactorRequired: boolean;
   loginToken?: string;
   userId?: number;
@@ -168,6 +178,7 @@ export interface TwoFactorVerifyRequest {
 export interface TwoFactorVerifyResponse {
   valid: boolean;
   token?: string;
+  refreshToken?: string;
 }
 
 export interface TrustedDevice {
@@ -286,6 +297,14 @@ export interface CheckoutRequest {
 	metadata?:   { [key: string]: string };
 }
 
+/** POST /api/billing/setup-intent — open the provider's payment sheet with these. */
+export interface SetupIntentResponse {
+  setupIntentId: string;
+  clientSecret:  string;
+  customerId:    string;
+  ephemeralKey:  string;
+}
+
 export interface CheckoutResponse {
 	checkoutUrl: string;
 }
@@ -330,6 +349,13 @@ export interface PaginatedList<T> {
 	total:  number;
 }
 
+/** Typed controls for keel REST list pagination and ordering. */
+export interface PageRequest {
+	limit?:   number;
+	offset?:  number;
+	orderBy?: string;
+}
+
 export interface Subscription {
 	planId:      string;
 	status:      string;  // 'A' active, 'P' pending-payment, 'C' cancelled, 'T' trialing, 'X' past-due — caption via SUBSCRIPTION_STATUS dict

package/src/model/auth.ts

@@ -93,6 +93,7 @@ export interface OtpVerifyRequest {
 
 export interface OtpVerifyResponse {
   token:      string;
+  refreshToken?: string;
   userId?:    number;
   partnerId?: number;
 }
@@ -137,6 +138,7 @@ export interface SocialLoginRequest {
 
 export interface LoginResponseSocial {
   token:                   string;
+  refreshToken?:           string;
   userId?:                 number;
   partnerId?:              number;
   isNewUser:               boolean;

package/src/service/auth.interceptor.ts

@@ -1,9 +1,13 @@
-import { HttpErrorResponse, HttpEventType, HttpInterceptorFn } from '@angular/common/http';
+import { HttpErrorResponse, HttpEvent, HttpEventType, HttpHandlerFn, HttpInterceptorFn, HttpRequest } from '@angular/common/http';
 import { inject, Injector } from '@angular/core';
-import { catchError, tap, throwError } from 'rxjs';
+import { Observable, catchError, switchMap, tap, throwError } from 'rxjs';
 import { isKeelApiUrl } from './rest_url';
-import { BaseAuthService } from './auth.service';
+import { BaseAuthService, RefreshSupersededError } from './auth.service';
 
+// A 401 on an authed call first tries one refresh-token rotation (keel
+// /public/token/refresh) and replays the request with the new JWT; only when
+// no refresh token is stored or keel rejects it does the 401 count below.
+//
 // Auth-loop breaker: repeated 401s on token-bearing API calls (a stale session) can
 // drive the app to hammer the API/CDN. After AUTH_FAIL_THRESHOLD within
 // AUTH_FAIL_WINDOW_MS the circuit opens for AUTH_CIRCUIT_COOLDOWN_MS — authed
@@ -25,7 +29,8 @@ export const authInterceptor: HttpInterceptorFn = (req, next) => {
   // → interceptors) and so an open circuit clears the dead session even when it
   // was opened by a previous page load.
   const injector = inject(Injector);
-  const expireSession = () => injector.get(BaseAuthService, null, { optional: true })?.sessionExpired();
+  const auth = () => injector.get(BaseAuthService, null, { optional: true });
+  const expireSession = () => auth()?.sessionExpired();
 
   const token = localStorage.getItem('jwt');
   const authedApi = !!token && isKeelApiUrl(req.url);
@@ -46,6 +51,11 @@ export const authInterceptor: HttpInterceptorFn = (req, next) => {
     }));
   }
 
+  const countFailure = (err: HttpErrorResponse) => {
+    if (recordAuthFailure()) expireSession();
+    return throwError(() => err);
+  };
+
   return next(req).pipe(
     tap((event) => {
       if (authedApi && event.type === HttpEventType.Response) {
@@ -53,14 +63,33 @@ export const authInterceptor: HttpInterceptorFn = (req, next) => {
       }
     }),
     catchError((err: HttpErrorResponse) => {
-      if (authedApi && err.status === 401 && recordAuthFailure()) {
-        expireSession();
-      }
-      return throwError(() => err);
+      if (!authedApi || err.status !== 401) return throwError(() => err);
+      const service = auth();
+      if (!service || !localStorage.getItem('refreshToken')) return countFailure(err);
+      return service.refreshSession().pipe(
+        catchError((refreshErr: unknown) => {
+          if (refreshErr instanceof RefreshSupersededError) {
+            return throwError(() => err);   // another session took over; it is not ours to expire
+          }
+          if (refreshErr instanceof HttpErrorResponse && refreshErr.status !== 401) {
+            return countFailure(err);       // transient refresh failure: keep the session, count the 401
+          }
+          expireSession();                  // keel rejected the refresh token: the session is dead
+          return throwError(() => err);
+        }),
+        switchMap((token) => replay(req, next, token)),   // replay errors surface as-is
+      );
     }),
   );
 };
 
+/** Re-send the request once with the rotated JWT; a second 401 is a real denial. */
+function replay(req: HttpRequest<unknown>, next: HttpHandlerFn, token: string): Observable<HttpEvent<unknown>> {
+  return next(req.clone({ setHeaders: { Authorization: `Bearer ${token}` } })).pipe(
+    tap((event) => { if (event.type === HttpEventType.Response) clearAuthFailures(); }),
+  );
+}
+
 function authCircuitOpen(): boolean {
   return Date.now() < Number(sessionStorage.getItem(OPEN_KEY) ?? 0);
 }

package/src/service/auth.service.ts

@@ -1,8 +1,8 @@
 import { Injectable, WritableSignal, inject, signal } from '@angular/core';
 import { HttpErrorResponse, HttpParams } from '@angular/common/http';
-import { filter, map, mergeMap, take, tap } from 'rxjs/operators';
+import { filter, finalize, map, mergeMap, shareReplay, take, tap } from 'rxjs/operators';
 import { PasswordRules } from '../util/password_policy';
-import { ApplicationData, ConfirmRegisterResponse, DictionaryPath, LoginResponse2FA, PartnerRegistration, RestReport, TableDefinition, TrustedDevice, TwoFactorSetupResponse, TwoFactorVerifyRequest, TwoFactorVerifyResponse } from '../model/appdata';
+import { ApplicationData, ConfirmRegisterResponse, DictionaryPath, LoginResponse2FA, PartnerRegistration, RestReport, TableDefinition, TokenPair, TrustedDevice, TwoFactorSetupResponse, TwoFactorVerifyRequest, TwoFactorVerifyResponse } from '../model/appdata';
 import {
   LoginResponseSocial,
   OtpRequest, OtpResendRequest, OtpResponse, OtpVerifyRequest, OtpVerifyResponse,
@@ -12,13 +12,19 @@ import {
   UserProfile,
 } from '../model/auth';
 import { RestURL } from './rest_url';
-import { BehaviorSubject, Observable, ReplaySubject, catchError, defer, merge, of, throwError } from 'rxjs';
+import { BehaviorSubject, EMPTY, Observable, ReplaySubject, catchError, defer, merge, of, throwError } from 'rxjs';
 import { ApplicationMenu, ConstantValue } from '../model/common';
 import { CanActivateFn, CanDeactivateFn, Router, Routes } from '@angular/router';
 import { SAIL_GUI_CONFIG, SailGuiConfig, DEFAULT_CONFIG } from '../config';
 import { BaseRestService } from './base_rest.service';
 import { resetAuthCircuit } from './auth.interceptor';
 
+/** Thrown by refreshSession() when the session changed while the rotation was in
+ *  flight; the result was discarded and the current session is untouched. */
+export class RefreshSupersededError extends Error {
+  constructor() { super('session changed during refresh'); this.name = 'RefreshSupersededError'; }
+}
+
 /** 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' });
@@ -65,6 +71,8 @@ export abstract class BaseAuthService extends BaseRestService {
   // before a subclass constructor can call configureRestUrls().
   protected get appdataUrl()               { return this.url(RestURL.appdataURL); }
   protected get loginUrl()                 { return this.url(RestURL.loginURL); }
+  protected get tokenRefreshUrl()          { return this.url(RestURL.tokenRefreshURL); }
+  protected get logoutUrl()                { return this.url(RestURL.logoutURL); }
   protected get registerUrl()              { return this.url(RestURL.registerURL); }
   protected get chpassUrl()                { return this.url(RestURL.chpassURL); }
   protected get confirmRegisterUrl()       { return this.url(RestURL.confirmRegisterURL); }
@@ -94,6 +102,8 @@ export abstract class BaseAuthService extends BaseRestService {
 
   token: string | null = null;
   readonly isLoggedIn = signal(false);
+  /** In-flight rotation shared by every caller so one expired JWT triggers one refresh. */
+  private refreshInFlight: Observable<string> | null = null;
 
   /** keel password policy for pre-submit validation; undefined until loaded
    *  (or when guiConfig.passwordPolicyUrl is unset). Fed via ensurePasswordPolicy(). */
@@ -176,14 +186,23 @@ export abstract class BaseAuthService extends BaseRestService {
   /** Adopt an externally-minted JWT (registration/SSO handoff flows) and run the
    * full post-login sequence — store under the canonical key, load appdata, init
    * routes. Apps must use this instead of writing localStorage directly. */
-  acceptToken(token: string) {
-    this.completeLogin(token);
+  acceptToken(token: string, refreshToken?: string) {
+    this.completeLogin(token, refreshToken);
   }
 
-  private completeLogin(token: string) {
+  /** A pair with no refresh token also drops the stored one: it may belong to a different account. */
+  private storeTokens(token: string, refreshToken?: string) {
     this.token = token;
-    this.isLoggedIn.set(true);
     localStorage.setItem('jwt', token);
+    if (refreshToken) localStorage.setItem('refreshToken', refreshToken);
+    else localStorage.removeItem('refreshToken');
+  }
+
+  private completeLogin(token: string, refreshToken?: string) {
+    this.refreshInFlight = null;         // a rotation started under the previous session must not land
+    this.sessionGeneration++;
+    this.storeTokens(token, refreshToken);
+    this.isLoggedIn.set(true);
     resetAuthCircuit(); // a new session must not inherit a prior session's open circuit
     const ret = this.validatedReturnUrl();
     if (ret && this.guiConfig.sessionCookieUrl) {
@@ -231,10 +250,34 @@ export abstract class BaseAuthService extends BaseRestService {
         localStorage.setItem('loginToken', res.loginToken);
         this.router.navigate(['/login/2fa']);
     } else {
-        this.completeLogin(res.token);
+        this.completeLogin(res.token, res.refreshToken);
     }
   }
 
+  /**
+   * Rotate the stored refresh token at keel's /public/token/refresh and emit the
+   * new JWT. Concurrent callers share one request. Errors when no refresh token
+   * is stored or keel rejects it (401: revoked, expired, or already rotated) —
+   * the caller decides whether that ends the session (the auth interceptor does).
+   */
+  refreshSession(): Observable<string> {
+    if (this.refreshInFlight) return this.refreshInFlight;
+    const refreshToken = localStorage.getItem('refreshToken');
+    if (!refreshToken) return throwError(() => new Error('no refresh token stored'));
+    const generation = this.sessionGeneration;
+    const inFlight = this.http.post<TokenPair>(this.tokenRefreshUrl, { refreshToken }).pipe(
+      map((res) => {
+        if (generation !== this.sessionGeneration) throw new RefreshSupersededError();
+        this.storeTokens(res.token, res.refreshToken);
+        return res.token;
+      }),
+      finalize(() => { if (this.refreshInFlight === inFlight) this.refreshInFlight = null; }),
+      shareReplay(1),
+    );
+    this.refreshInFlight = inFlight;
+    return inFlight;
+  }
+
   /**
    * POST credentials; success completes the login (or routes to 2FA). Callers
    * subscribe and handle the error channel to surface failures in the UI.
@@ -288,7 +331,7 @@ export abstract class BaseAuthService extends BaseRestService {
         tap((res) => {
             if (res.valid && res.token) {
                 localStorage.removeItem('loginToken');
-                this.completeLogin(res.token);
+                this.completeLogin(res.token, res.refreshToken);
             }
         }),
     );
@@ -301,7 +344,7 @@ export abstract class BaseAuthService extends BaseRestService {
         tap((res) => {
             if (res.valid && res.token) {
                 localStorage.removeItem('loginToken');
-                this.completeLogin(res.token);
+                this.completeLogin(res.token, res.refreshToken);
             }
         }),
     );
@@ -379,11 +422,22 @@ export abstract class BaseAuthService extends BaseRestService {
     }
   }
 
+  /** Revoke the refresh token server-side (best effort: the local session is
+   *  cleared regardless), then land on the login screen. */
   logout() {
+    this.revokeRefreshToken().subscribe();
     this.clearSession();
     this.router.navigate(['/login/local'], { queryParams: { loggedOut: 'true' } });
   }
 
+  private revokeRefreshToken(): Observable<unknown> {
+    const refreshToken = localStorage.getItem('refreshToken');
+    if (!refreshToken) return EMPTY;
+    return this.http.post(this.logoutUrl, { refreshToken }).pipe(
+      catchError((err) => { console.warn('refresh token revocation failed:', err); return EMPTY; }),
+    );
+  }
+
   register(reg: PartnerRegistration) {
     return this.http.post<PartnerRegistration>(this.registerUrl, reg);
   }
@@ -423,7 +477,7 @@ export abstract class BaseAuthService extends BaseRestService {
     return this.http.post<OtpVerifyResponse>(this.otpVerifyUrl, req).pipe(
       tap((res) => {
         if (res?.token) {
-          this.completeLogin(res.token);
+          this.completeLogin(res.token, res.refreshToken);
           if (role) this.setRole(role);
         }
       }),
@@ -441,7 +495,7 @@ export abstract class BaseAuthService extends BaseRestService {
   ): Observable<LoginResponseSocial> {
     const payload: SocialLoginRequest = { provider, token: idToken, ...consent };
     return this.http.post<LoginResponseSocial>(this.loginSocialUrl, payload).pipe(
-      tap((res) => { if (res?.token) this.completeLogin(res.token); }),
+      tap((res) => { if (res?.token) this.completeLogin(res.token, res.refreshToken); }),
     );
   }
 
@@ -503,13 +557,15 @@ export abstract class BaseAuthService extends BaseRestService {
     this.token = null;
     this.isLoggedIn.set(false);
     localStorage.removeItem('jwt');
+    localStorage.removeItem('refreshToken');
     localStorage.removeItem('menu');
     localStorage.removeItem('loginToken');
     this.clearRole();
     this.cache = undefined;
     this.authIndex.clear();
     this.appDataError.set(null);
-    this.sessionGeneration++;           // in-flight loads from this session are ignored
+    this.refreshInFlight = null;
+    this.sessionGeneration++;           // in-flight loads and refreshes from this session are ignored
     this.appData$.next(null);           // live subscribers see menus clear; identity stays stable
     this.appDataFail$.complete();
     this.appDataFail$ = new ReplaySubject<unknown>(1);

package/src/service/billing.service.ts

@@ -9,6 +9,7 @@ import {
   PaymentMethod,
   PortalResponse,
   PublicPlan,
+  SetupIntentResponse,
   Subscription,
   UsageMeter,
 } from '../model/appdata';
@@ -73,6 +74,15 @@ export class BillingService extends BaseRestService {
     return this.http.get<PaymentMethod[]>(this.url(RestURL.paymentMethodsURL));
   }
 
+  /**
+   * Create a provider setup intent for on-device card capture (keel v1.2.57
+   * AbstractPaymentHandler.CreateSetupIntent). Identity comes from the JWT; the
+   * response feeds the provider's payment sheet. Persist customerId on first use.
+   */
+  createSetupIntent(): Observable<SetupIntentResponse> {
+    return this.http.post<SetupIntentResponse>(this.url(RestURL.setupIntentURL), {});
+  }
+
   /**
    * Create a provider customer-portal session; caller redirects to the URL so
    * the partner can manage their payment method / subscription on the

package/src/service/label.service.ts

@@ -1,19 +1,44 @@
-import { Injectable } from "@angular/core";
+import { inject, Injectable } from "@angular/core";
+import { Observable, map, of, shareReplay, take, tap } from "rxjs";
+import { BaseAuthService } from "./auth.service";
 
-// TODO: Implement translated captions service
-// - loadLabels(langcode) should fetch labels from the backend
-// - getLabel(langcode, key) should return the translated caption for a given key
-// - BaseTable.colCaption() and related methods should use this service for i18n
 @Injectable({ providedIn: 'root' })
 export class LabelService {
+    private readonly auth = inject(BaseAuthService);
     protected labels: Map<string, Map<string, string>> = new Map();
+    private readonly pendingLoads = new Map<string, Observable<void>>();
 
-    /** Falls back to the key itself so a missing translation is visible, not a blank caption. */
-    getLabel(langcode: string, key: string): string {
-        return this.labels.get(langcode)?.get(key) ?? key;
+    /** Return a caption from a constant domain, falling back visibly to its raw value. */
+    getLabel(constantId: string, key: string): string {
+        return this.labels.get(constantId)?.get(key) ?? key;
     }
 
-    loadLabels(_langcode: string) {
-        // TODO: fetch from backend and populate this.labels
+    /**
+     * Load one backend-provided `constant_value` domain from ApplicationData.
+     * Completed and concurrent requests are cached; a failed application-data
+     * load is evicted so a later call can retry.
+     */
+    loadLabels(constantId: string): Observable<void> {
+        const domain = constantId.trim();
+        if (!domain) throw new Error('sail: a constant id is required to load labels.');
+        if (this.labels.has(domain)) return of(undefined);
+
+        const pending = this.pendingLoads.get(domain);
+        if (pending) return pending;
+
+        const request = this.auth.getAppData().pipe(
+            take(1),
+            tap({
+                next: (data) => this.labels.set(
+                    domain,
+                    new Map(Object.entries(data.ConstantCache?.[domain] ?? {})),
+                ),
+                error: () => this.pendingLoads.delete(domain),
+            }),
+            map(() => undefined),
+            shareReplay({ bufferSize: 1, refCount: false }),
+        );
+        this.pendingLoads.set(domain, request);
+        return request;
     }
 }

package/src/service/realtime.service.ts

@@ -0,0 +1,142 @@
+import { DestroyRef, Injectable, inject, signal } from '@angular/core';
+import { Observable, Subject, filter, map } from 'rxjs';
+import { RestURL } from './rest_url';
+
+/** Frame published on a channel by keel's realtime.Hub (Broadcast / PublishChannel). */
+export interface RealtimeChannelFrame<T = unknown> {
+  channel: string;
+  data:    T;
+}
+
+/** Control frames of the keel realtime wire protocol. */
+interface ControlFrame {
+  op:       'subscribed' | 'unsubscribed' | 'error';
+  channel?: string;
+  reason?:  string;
+}
+
+const RECONNECT_MIN_MS = 1_000;
+const RECONNECT_MAX_MS = 30_000;
+
+/**
+ * RealtimeService — client for keel's realtime.Hub (`GET /public/ws`).
+ *
+ * Owns the socket lifecycle: JWT handshake via `?token=`, reconnect with
+ * backoff, and re-subscription of every channel after a reconnect. Channel
+ * names and payload schemas are the app's; sail only carries the frames.
+ * Relay delivery is fire-and-forget on the server, so keep a REST read path for
+ * state a client may have missed while disconnected.
+ */
+@Injectable({ providedIn: 'root' })
+export class RealtimeService {
+  private readonly destroyRef = inject(DestroyRef);
+  private socket: WebSocket | null = null;
+  private wanted = false;
+  private reconnectDelay = RECONNECT_MIN_MS;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private readonly channels = new Set<string>();
+  private readonly frames$ = new Subject<unknown>();
+
+  readonly connected = signal(false);
+  /** Last subscription rejected by keel's CanSubscribe, as `{channel, reason}`. */
+  readonly lastError = signal<{ channel?: string; reason?: string } | null>(null);
+
+  constructor() {
+    this.destroyRef.onDestroy(() => this.disconnect());
+  }
+
+  /** Open the socket with the stored JWT. Reconnects on drop until disconnect(). */
+  connect(): void {
+    this.wanted = true;
+    if (this.socket) return;
+    const token = localStorage.getItem('jwt');
+    if (!token) throw new Error('RealtimeService.connect: no session token stored');
+    const ws = new WebSocket(`${socketUrl(RestURL.realtimeURL)}?token=${encodeURIComponent(token)}`);
+    this.socket = ws;
+    ws.onopen = () => {
+      if (this.socket !== ws) return;
+      this.reconnectDelay = RECONNECT_MIN_MS;
+      this.connected.set(true);
+      for (const channel of this.channels) this.sendFrame({ op: 'subscribe', channel });
+    };
+    ws.onmessage = (ev: MessageEvent<string>) => { if (this.socket === ws) this.onFrame(ev.data); };
+    ws.onclose = () => {
+      if (this.socket !== ws) return;   // superseded by disconnect()/connect(); ignore its close
+      this.socket = null;
+      this.connected.set(false);
+      if (this.wanted) this.scheduleReconnect();
+    };
+    ws.onerror = () => ws.close();
+  }
+
+  disconnect(): void {
+    this.wanted = false;
+    if (this.reconnectTimer) { clearTimeout(this.reconnectTimer); this.reconnectTimer = null; }
+    this.socket?.close();
+    this.socket = null;
+    this.connected.set(false);
+  }
+
+  /** Frames published on `channel`; subscribes on first use and survives reconnects. */
+  channel<T = unknown>(channel: string): Observable<T> {
+    if (!this.channels.has(channel)) {
+      this.channels.add(channel);
+      if (this.connected()) this.sendFrame({ op: 'subscribe', channel });
+    }
+    return this.frames$.pipe(
+      filter((f): f is RealtimeChannelFrame<T> => isChannelFrame(f) && f.channel === channel),
+      map((f) => f.data),
+    );
+  }
+
+  unsubscribe(channel: string): void {
+    if (this.channels.delete(channel) && this.connected()) this.sendFrame({ op: 'unsubscribe', channel });
+  }
+
+  /** Payloads keel delivers to this user directly (SendToUser / PublishUser). */
+  userFrames<T = unknown>(): Observable<T> {
+    return this.frames$.pipe(filter((f): f is T => !isChannelFrame(f) && !isControlFrame(f)));
+  }
+
+  /** Send an application frame; keel passes anything but subscribe/unsubscribe to OnMessage. */
+  send(frame: object): void {
+    if (!this.connected()) throw new Error('RealtimeService.send: socket not connected');
+    this.sendFrame(frame);
+  }
+
+  private sendFrame(frame: object): void {
+    this.socket?.send(JSON.stringify(frame));
+  }
+
+  private onFrame(raw: string): void {
+    let frame: unknown;
+    try { frame = JSON.parse(raw); } catch { console.error('realtime: non-JSON frame dropped'); return; }
+    if (isControlFrame(frame) && frame.op === 'error') {
+      this.lastError.set({ channel: frame.channel, reason: frame.reason });
+      console.error(`realtime: subscribe ${frame.channel} rejected: ${frame.reason}`);
+    }
+    this.frames$.next(frame);
+  }
+
+  private scheduleReconnect(): void {
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      if (this.wanted) this.connect();
+    }, this.reconnectDelay);
+    this.reconnectDelay = Math.min(this.reconnectDelay * 2, RECONNECT_MAX_MS);
+  }
+}
+
+function isChannelFrame(f: unknown): f is RealtimeChannelFrame {
+  return !!f && typeof f === 'object' && 'channel' in f && 'data' in f && !('op' in f);
+}
+
+function isControlFrame(f: unknown): f is ControlFrame {
+  return !!f && typeof f === 'object' && 'op' in f;
+}
+
+/** ws(s):// form of the configured backend host plus `path`; same-origin when no host is set. */
+function socketUrl(path: string): string {
+  const base = RestURL.httpHost || window.location.origin;
+  return base.replace(/^http/, 'ws') + path;
+}

package/src/service/rest_service.ts

@@ -1,7 +1,7 @@
 import { HttpErrorResponse, HttpParams } from "@angular/common/http";
 import { inject, Injectable } from "@angular/core";
 import { catchError, map, Observable, switchMap, take, throwError } from "rxjs";
-import { ApplicationData, PaginatedList } from "../model/appdata";
+import { ApplicationData, PageRequest, PaginatedList } from "../model/appdata";
 import { RestURL } from "./rest_url";
 import { BaseAuthService } from "./auth.service";
 import { BaseRestService } from "./base_rest.service";
@@ -83,15 +83,19 @@ export class BackendService extends BaseRestService {
         return this.http.request<T>(method, this.apiUrl(path), { body }).pipe(catchError((err) => this.handleError(err)));
     }
 
-    /** Build query params from a flat string-string map; skips undefined/null values. */
-    private toParams(filter?: {[key: string]: string}): HttpParams {
+    /** Build query params from filters plus keel's underscore-prefixed paging aliases. */
+    private toParams(filter?: {[key: string]: string}, page?: PageRequest): HttpParams {
         let params = new HttpParams();
-        if (!filter) return params;
-        for (const key in filter) {
-            if (Object.prototype.hasOwnProperty.call(filter, key) && filter[key] != null) {
-                params = params.set(key, filter[key]);
+        if (filter) {
+            for (const key in filter) {
+                if (Object.prototype.hasOwnProperty.call(filter, key) && filter[key] != null) {
+                    params = params.set(key, filter[key]);
+                }
             }
         }
+        if (page?.limit != null) params = params.set('_limit', page.limit);
+        if (page?.offset != null) params = params.set('_offset', page.offset);
+        if (page?.orderBy) params = params.set('_order', page.orderBy);
         return params;
     }
 
@@ -100,16 +104,16 @@ export class BackendService extends BaseRestService {
         return this.auth.getAppData().pipe(take(1));
     }
 
-    /** Unwraps `{items, limit, offset, total}` to the items array. Pass `_limit` / `_offset` in `filter` to control paging (defaults: 100 / 0). */
-    list<T>(apiName: string, filter?: {[key: string]: string}) : Observable<T[]> {
-        return this.listPaginated<T>(apiName, filter).pipe(map((page) => page.items));
+    /** Unwraps `{items, limit, offset, total}` to the items array. */
+    list<T>(apiName: string, filter?: {[key: string]: string}, page?: PageRequest) : Observable<T[]> {
+        return this.listPaginated<T>(apiName, filter, page).pipe(map((result) => result.items));
     }
 
-    listPaginated<T>(apiName: string, filter?: {[key: string]: string}) : Observable<PaginatedList<T>> {
+    listPaginated<T>(apiName: string, filter?: {[key: string]: string}, page?: PageRequest) : Observable<PaginatedList<T>> {
         return this.appDataReady().pipe(
             switchMap(() => this.http.get<PaginatedList<T>>(
                 this.crudUrl(apiName, 'list'),
-                {params: this.toParams(filter)},
+                {params: this.toParams(filter, page)},
             )),
             catchError((err) => this.handleError(err)),
         );

package/src/service/rest_url.ts

@@ -3,6 +3,9 @@ export const RestURL = {
   api_prefix: '/api/',
   appdataURL: '/api/config/appdata',
   loginURL: '/public/login/local',
+  tokenRefreshURL: '/public/token/refresh',   // rotates {refreshToken} → new {token, refreshToken}
+  logoutURL: '/public/logout',                // revokes {refreshToken}
+  realtimeURL: '/public/ws',                  // keel realtime.Hub handshake; JWT via ?token=
   loginGoogleURL: '/public/login/google',
   registerURL: '/public/register',
   chpassURL: '/public/login/chpass',
@@ -25,6 +28,7 @@ export const RestURL = {
   invoicesURL:       '/api/billing/invoices',
   paymentMethodsURL: '/api/billing/payment-methods',
   portalURL:         '/api/billing/portal',
+  setupIntentURL:    '/api/billing/setup-intent',
   usageURL:          '/api/billing/usage',
   // OTP / social / push / account-lifecycle endpoints
   otpSendURL:          '/public/otp/send',

package/src/util/errors.ts

@@ -39,9 +39,15 @@ export function isTransportFailure(err: unknown): boolean {
  * `detail` did not come from the API: either nothing reached it (status 0) or
  * something in front of it replied with a body we cannot read. Both used to
  * collapse into the caller's fallback, which reads as a backend rejection and
- * hides the real fault; they are now reported distinctly.
+ * hides the real fault; they are now reported distinctly. When `statuses` is
+ * supplied, HTTP statuses outside that allowlist return `fallback` without
+ * exposing their response text.
  */
-export function errorDetail(err: unknown, fallback: string): string {
+export function errorDetail(err: unknown, fallback: string, statuses?: readonly number[]): string {
+  const status = statusOf(err);
+  if (statuses && status !== undefined && !statuses.includes(status)) {
+    return fallback;
+  }
   if (isTransportFailure(err)) {
     return 'Cannot reach the server — the network or a CORS rule blocked the response.';
   }
@@ -53,7 +59,6 @@ export function errorDetail(err: unknown, fallback: string): string {
   if (err instanceof Error && err.message) {
     return err.message;
   }
-  const status = statusOf(err);
   return status ? `${fallback} (HTTP ${status})` : fallback;
 }