@nauticana/sail 1.1.17 → 1.1.19

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.
 
@@ -328,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** |
@@ -340,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 |
@@ -382,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
 
@@ -864,8 +876,9 @@ For backward compatibility, the older OAuth-code flow `BaseAuthService.loginWith
 Horizontal building blocks for an entitlement-aware dashboard. All are presentational (signals in, events out) and ship no CSS — the app styles the documented class hooks and supplies the metric data, chart, and action logic.
 
 - **`DashboardShellComponent`** (`sail-dashboard-shell`) — responsive card-grid layout. `[heading]` + a `[dashboardActions]` projection slot for the header; project cards into the default slot. Styles: `.dashboard-shell` / `.dashboard-header` / `.dashboard-grid`.
-- **`DataCardComponent`** (`sail-data-card`) — card chrome for one visualization with `[state]` ∈ `loading | ready | empty | error | locked`. The chart is supplied as an `<ng-template>` and instantiated **only** in `ready`, so during loading/error/locked it never exists (no hidden canvas). `description` (required) is the screen-reader text alternative; `[tableHeaders]`/`[tableRows]` render a visually-hidden (`.sr-only`) data table. Emits `upgrade` / `retry`.
+- **`DataCardComponent`** (`sail-data-card`) — card chrome for one visualization with `[state]` ∈ `loading | ready | empty | error | locked | no-source`. The chart is supplied as an `<ng-template>` and instantiated **only** in `ready`, so during loading/error/locked/no-source it never exists (no hidden canvas). `description` (required) is the screen-reader text alternative; `[tableHeaders]`/`[tableRows]` render a visually-hidden (`.sr-only`) data table. Emits `upgrade`, `connect`, and `retry`.
 - **`LockedOverlayComponent`** (`sail-locked-overlay`) — entitlement gate. Wraps protected content given as an `<ng-template>`; when `[locked]` the template is never instantiated, so **no data exists behind the gate** (DOM, canvas, or network) — the strict free-tier rule. Emits `upgrade`.
+- **`NoSourceOverlayComponent`** (`sail-no-source-overlay`) — source-readiness gate. Takes `[sourceName]` and emits `connect`; while `[unavailable]`, its protected `<ng-template>` is never instantiated. Use this for included features whose provider is not connected or whose collector is unavailable—never show an upgrade prompt for this state.
 - **`ActionCenterComponent`** (`sail-action-center`) — prioritized next-best-action list from `[actions]: ActionItem[]` (sorted by `priority`, done items show a check). Emits `act`.
 - **`EntitySelectorComponent`** (`sail-entity-selector`) — scope dropdown over `[entities]: EntityOption[]`; resolves `[selected]` or the first active entity and emits `selectionChange`.
 - **`VerificationFlowComponent`** (`sail-verification-flow`) — self-service request → enter-code → verified UI (a 2FA sibling), backend-agnostic: emits `requestVerification` / `confirmCode`, driven by `[step]` + `[errorMessage]` the host feeds back.
@@ -878,6 +891,36 @@ Horizontal building blocks for an entitlement-aware dashboard. All are presentat
 
 Models: `DataCardState`, `ActionItem`, `EntityOption`, `VerificationStep`.
 
+Analytics clients that need this distinction can call the protected
+`analyticWithStatus<T>()` on `BaseRestService`. It returns
+`{ rows, source: { status, id } }`, populated from `X-Data-Source-Status` and
+`X-Data-Source`; the existing `analytic<T>()` remains `Observable<T[]>`.
+
+When the app and its API are on different origins the browser hides both headers
+unless the backend sends
+`Access-Control-Expose-Headers: X-Data-Source-Status, X-Data-Source`; without it
+`source.status` is `null` and a missing source is indistinguishable from an
+empty result.
+
+## Grouped review actions and diffs (v1.1.19)
+
+`GroupedBulkActionComponent` (`sail-grouped-bulk-action`) groups eligible rows
+with the consumer's `[groupBy]` function and renders an app-chosen bounded
+`[sampleSize]` through a projected `<ng-template>`. The app supplies all domain
+copy and an `[execute]` function returning `{ attempted, succeeded }`. When
+`succeeded < attempted`, the component visibly renders the app's
+`[partialSuccessMessage]`; it never reports a partial operation as complete.
+The outcome message renders above the groups (`role="alert"`,
+`.grouped-bulk-action__message--partial` / `--error`) and stays until the next
+action, so it survives the row refresh that removes its group. Group headings
+are `role="heading"` at `[headingLevel]` (default 3).
+
+`BeforeAfterDiffComponent` (`sail-before-after-diff`) renders a
+whitespace-preserving word-level LCS diff. `[maxTokens]` defaults to 2000; above
+the cap it skips the quadratic comparison and shows the whole new value as an
+addition. Additions and deletions are `<ins class="diff-add">` /
+`<del class="diff-del">`, unchanged text `<span class="diff-same">`. The pure `wordDiff()` helper is also exported for custom layouts.
+
 ## Provider connections (v1.1.9)
 
 `ConnectionPanel` is the drop-in UI for keel's `oauth/connect` layer — connect a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nauticana/sail",
-  "version": "1.1.17",
+  "version": "1.1.19",
   "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/dashboard/data_card.html

@@ -33,5 +33,12 @@
         <button matButton="elevated" type="button" class="primary" (click)="upgrade.emit()">{{ ctaLabel() }}</button>
       </div>
     }
+    @case ('no-source') {
+      <div class="data-card-no-source" role="group" [attr.aria-label]="(heading() || 'Insight') + ' — source unavailable'">
+        <p class="no-source-name">{{ sourceName() }}</p>
+        <p class="no-source-message">{{ noSourceMessage() }}</p>
+        <button matButton="elevated" type="button" class="primary" (click)="connect.emit()">{{ connectLabel() }}</button>
+      </div>
+    }
   }
 </section>

package/src/component/dashboard/data_card.ts

@@ -30,10 +30,14 @@ export class DataCardComponent {
   readonly errorMessage = input<string>('Could not load this data.');
   readonly emptyMessage = input<string>('No data yet.');
   readonly lockedMessage = input<string>('Upgrade to unlock this insight.');
+  readonly sourceName = input<string>('data source');
+  readonly noSourceMessage = input<string>('Connect the required data source to see this insight.');
   readonly ctaLabel = input<string>('Upgrade');
+  readonly connectLabel = input<string>('Connect');
   readonly tableHeaders = input<string[]>([]);
   readonly tableRows = input<(string | number)[][]>([]);
   readonly upgrade = output<void>();
+  readonly connect = output<void>();
   readonly retry = output<void>();
 
   /** The chart, provided as a single <ng-template>; instantiated only when ready. */

package/src/component/dashboard/no_source_overlay.html

@@ -0,0 +1,9 @@
+@if (unavailable()) {
+  <div class="no-source-overlay" role="group" [attr.aria-label]="sourceName() + ' — source unavailable'">
+    <p class="no-source-name">{{ sourceName() }}</p>
+    <p class="no-source-message">{{ message() }}</p>
+    <button matButton="elevated" type="button" class="primary" (click)="connect.emit()">{{ ctaLabel() }}</button>
+  </div>
+} @else if (content(); as tpl) {
+  <ng-container [ngTemplateOutlet]="tpl"></ng-container>
+}

package/src/component/dashboard/no_source_overlay.ts

@@ -0,0 +1,21 @@
+import { NgTemplateOutlet } from '@angular/common';
+import { ChangeDetectionStrategy, Component, TemplateRef, ViewEncapsulation, contentChild, input, output } from '@angular/core';
+import { MatButtonModule } from '@angular/material/button';
+
+/** Source-readiness sibling of LockedOverlayComponent: the template is never instantiated while unavailable. */
+@Component({
+  selector: 'sail-no-source-overlay',
+  templateUrl: './no_source_overlay.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  imports: [NgTemplateOutlet, MatButtonModule],
+})
+export class NoSourceOverlayComponent {
+  readonly unavailable = input.required<boolean>();
+  readonly sourceName = input.required<string>();
+  readonly message = input<string>('Connect this data source to continue.');
+  readonly ctaLabel = input<string>('Connect');
+  readonly connect = output<void>();
+
+  readonly content = contentChild(TemplateRef);
+}

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

@@ -0,0 +1 @@
+<pre class="before-after-diff">@for (token of tokens(); track $index) {@switch (token.kind) {@case ('add') {<ins class="diff-add">{{ token.text }}</ins>}@case ('del') {<del class="diff-del">{{ token.text }}</del>}@default {<span class="diff-same">{{ token.text }}</span>}}}</pre>

package/src/component/table/before_after_diff.ts

@@ -0,0 +1,54 @@
+import { ChangeDetectionStrategy, Component, ViewEncapsulation, computed, input } from '@angular/core';
+
+export type DiffTokenKind = 'same' | 'add' | 'del';
+
+export interface DiffToken {
+  text: string;
+  kind: DiffTokenKind;
+}
+
+/** Whitespace-preserving word-level LCS diff with a bounded work limit. */
+export function wordDiff(before: string, after: string, maxTokens = 2000): DiffToken[] {
+  const left = before.split(/(\s+)/).filter((token) => token.length > 0);
+  const right = after.split(/(\s+)/).filter((token) => token.length > 0);
+  if (left.length > maxTokens || right.length > maxTokens) return [{ text: after, kind: 'add' }];
+
+  const matrix = Array.from({ length: left.length + 1 }, () => new Uint32Array(right.length + 1));
+  for (let i = left.length - 1; i >= 0; i--) {
+    for (let j = right.length - 1; j >= 0; j--) {
+      matrix[i][j] = left[i] === right[j]
+        ? matrix[i + 1][j + 1] + 1
+        : Math.max(matrix[i + 1][j], matrix[i][j + 1]);
+    }
+  }
+
+  const tokens: DiffToken[] = [];
+  let i = 0;
+  let j = 0;
+  while (i < left.length && j < right.length) {
+    if (left[i] === right[j]) {
+      tokens.push({ text: left[i++], kind: 'same' });
+      j++;
+    } else if (matrix[i + 1][j] >= matrix[i][j + 1]) {
+      tokens.push({ text: left[i++], kind: 'del' });
+    } else {
+      tokens.push({ text: right[j++], kind: 'add' });
+    }
+  }
+  while (i < left.length) tokens.push({ text: left[i++], kind: 'del' });
+  while (j < right.length) tokens.push({ text: right[j++], kind: 'add' });
+  return tokens;
+}
+
+@Component({
+  selector: 'sail-before-after-diff',
+  templateUrl: './before_after_diff.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+})
+export class BeforeAfterDiffComponent {
+  readonly before = input.required<string>();
+  readonly after = input.required<string>();
+  readonly maxTokens = input<number>(2000);
+  readonly tokens = computed(() => wordDiff(this.before(), this.after(), this.maxTokens()));
+}

package/src/component/table/grouped_bulk_action.html

@@ -0,0 +1,36 @@
+@if (message(); as outcome) {
+  <p class="grouped-bulk-action__message"
+     [class.grouped-bulk-action__message--partial]="outcome.kind === 'partial'"
+     [class.grouped-bulk-action__message--error]="outcome.kind === 'error'"
+     role="alert">{{ outcome.text }}</p>
+}
+
+@for (group of groups(); track group.key) {
+  <section class="grouped-bulk-action" [attr.data-group-key]="group.key">
+    <header class="grouped-bulk-action__header">
+      <div class="grouped-bulk-action__heading" role="heading" [attr.aria-level]="headingLevel()">{{ heading()(group) }}</div>
+      <button matButton="filled" type="button"
+              [disabled]="busyKey() !== null"
+              (click)="run(group)">
+        {{ actionLabel()(group, busyKey() === group.key) }}
+      </button>
+    </header>
+
+    @if (description()(group); as text) {
+      <p class="grouped-bulk-action__description">{{ text }}</p>
+    }
+
+    @if (sampleTemplate(); as template) {
+      <div class="grouped-bulk-action__sample">
+        @for (row of group.sample; track $index) {
+          <ng-container [ngTemplateOutlet]="template"
+                        [ngTemplateOutletContext]="{ $implicit: row, group: group }"></ng-container>
+        }
+      </div>
+    }
+
+    @if (group.count > group.sample.length) {
+      <p class="grouped-bulk-action__remainder">{{ remainderLabel()(group.count - group.sample.length, group) }}</p>
+    }
+  </section>
+}

package/src/component/table/grouped_bulk_action.ts

@@ -0,0 +1,120 @@
+import { NgTemplateOutlet } from '@angular/common';
+import { ChangeDetectionStrategy, Component, DestroyRef, TemplateRef, ViewEncapsulation, computed, contentChild, inject, input, output, signal } from '@angular/core';
+import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
+import { MatButtonModule } from '@angular/material/button';
+import { finalize, Observable } from 'rxjs';
+
+export type BulkGroupKey = string | number;
+
+export interface BulkActionGroup<T> {
+  key: BulkGroupKey;
+  rows: readonly T[];
+  sample: readonly T[];
+  count: number;
+}
+
+/** Generic outcome used to detect and report partial completion. */
+export interface BulkActionResult {
+  attempted: number;
+  succeeded: number;
+}
+
+export interface BulkActionCompletion<T> {
+  group: BulkActionGroup<T>;
+  result: BulkActionResult;
+}
+
+interface OutcomeMessage {
+  text: string;
+  kind: 'partial' | 'error';
+}
+
+/** The projected template receives each sample row as `$implicit` and its group as `group`. */
+@Component({
+  selector: 'sail-grouped-bulk-action',
+  templateUrl: './grouped_bulk_action.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  imports: [NgTemplateOutlet, MatButtonModule],
+})
+export class GroupedBulkActionComponent<T> {
+  readonly rows = input.required<readonly T[]>();
+  readonly groupBy = input.required<(row: T) => BulkGroupKey | null | undefined>();
+  readonly eligible = input<(row: T) => boolean>(() => true);
+  readonly sampleSize = input.required<number>();
+  readonly minimumGroupSize = input<number>(2);
+  readonly execute = input.required<(group: BulkActionGroup<T>) => Observable<BulkActionResult>>();
+
+  readonly heading = input.required<(group: BulkActionGroup<T>) => string>();
+  readonly headingLevel = input<number>(3);
+  readonly description = input<(group: BulkActionGroup<T>) => string>(() => '');
+  readonly actionLabel = input.required<(group: BulkActionGroup<T>, busy: boolean) => string>();
+  readonly remainderLabel = input.required<(remaining: number, group: BulkActionGroup<T>) => string>();
+  readonly partialSuccessMessage = input.required<(result: BulkActionResult, group: BulkActionGroup<T>) => string>();
+  readonly failureMessage = input.required<(error: unknown, group: BulkActionGroup<T>) => string>();
+  readonly sortGroups = input<(left: BulkActionGroup<T>, right: BulkActionGroup<T>) => number>(() => 0);
+
+  readonly finished = output<BulkActionCompletion<T>>();
+  readonly failed = output<{ group: BulkActionGroup<T>; error: unknown }>();
+
+  readonly busyKey = signal<BulkGroupKey | null>(null);
+  /** Held outside the groups: a refresh after the action usually removes the group it concerns. */
+  readonly message = signal<OutcomeMessage | null>(null);
+  readonly sampleTemplate = contentChild<TemplateRef<unknown>>(TemplateRef);
+  readonly groups = computed(() => this.buildGroups());
+
+  private readonly destroyRef = inject(DestroyRef);
+
+  run(group: BulkActionGroup<T>): void {
+    if (this.busyKey() !== null) return;
+    this.busyKey.set(group.key);
+    this.message.set(null);
+    let request: Observable<BulkActionResult>;
+    try {
+      request = this.execute()(group);
+    } catch (error) {
+      this.handleFailure(group, error);
+      return;
+    }
+    request.pipe(
+      takeUntilDestroyed(this.destroyRef),
+      finalize(() => this.busyKey.set(null)),
+    ).subscribe({
+      next: (result) => {
+        if (result.succeeded < result.attempted) {
+          this.message.set({ text: this.partialSuccessMessage()(result, group), kind: 'partial' });
+        }
+        this.finished.emit({ group, result });
+      },
+      error: (error: unknown) => this.handleFailure(group, error),
+    });
+  }
+
+  private buildGroups(): BulkActionGroup<T>[] {
+    const grouped = new Map<BulkGroupKey, T[]>();
+    for (const row of this.rows()) {
+      if (!this.eligible()(row)) continue;
+      const key = this.groupBy()(row);
+      if (key === null || key === undefined || key === '') continue;
+      const groupRows = grouped.get(key) ?? [];
+      groupRows.push(row);
+      grouped.set(key, groupRows);
+    }
+    const sampleSize = Math.max(0, this.sampleSize());
+    return [...grouped.entries()]
+      .filter(([, groupRows]) => groupRows.length >= this.minimumGroupSize())
+      .map(([key, groupRows]) => ({
+        key,
+        rows: groupRows,
+        sample: groupRows.slice(0, sampleSize),
+        count: groupRows.length,
+      }))
+      .sort(this.sortGroups());
+  }
+
+  private handleFailure(group: BulkActionGroup<T>, error: unknown): void {
+    this.busyKey.set(null);
+    this.message.set({ text: this.failureMessage()(error, group), kind: 'error' });
+    this.failed.emit({ group, error });
+  }
+}

package/src/index.ts

@@ -10,6 +10,7 @@ export * from './component/abstract/base_table';
 export * from './component/dashboard/dashboard_shell';
 export * from './component/dashboard/data_card';
 export * from './component/dashboard/locked_overlay';
+export * from './component/dashboard/no_source_overlay';
 export * from './component/dashboard/action_center';
 export * from './component/dashboard/entity_selector';
 export * from './component/dashboard/verification_flow';
@@ -26,6 +27,8 @@ export * from './component/table/table_edit';
 export * from './component/table/table_detail';
 export * from './component/table/table_lookup';
 export * from './component/table/table_report';
+export * from './component/table/grouped_bulk_action';
+export * from './component/table/before_after_diff';
 export * from './component/navigation/navigation';
 export * from './component/login/login_component';
 export * from './component/login/register_component';
@@ -72,6 +75,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;
 }

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/model/dashboard.ts

@@ -1,5 +1,5 @@
 /** Lifecycle state of a data/chart card (sail-data-card). */
-export type DataCardState = 'loading' | 'ready' | 'empty' | 'error' | 'locked';
+export type DataCardState = 'loading' | 'ready' | 'empty' | 'error' | 'locked' | 'no-source';
 
 /** A prioritized, completable next-best-action (sail-action-center, FR-008). */
 export interface ActionItem {

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/base_rest.service.ts

@@ -1,6 +1,6 @@
 import { HttpClient, HttpParams } from '@angular/common/http';
 import { inject } from '@angular/core';
-import { Observable } from 'rxjs';
+import { map, Observable } from 'rxjs';
 import { RestURL } from './rest_url';
 
 /**
@@ -22,10 +22,45 @@ export abstract class BaseRestService {
   /** GET an analytic endpoint (`{host}{api_prefix}analytic/<endpoint>`), returning
    * its rows. Optional flat string params become the query string. */
   protected analytic<T>(endpoint: string, params?: Record<string, string>): Observable<T[]> {
-    let p = new HttpParams();
-    for (const k in params) {
-      if (Object.prototype.hasOwnProperty.call(params, k)) p = p.set(k, params[k]);
+    return this.http.get<T[]>(this.analyticUrl(endpoint), { params: this.analyticParams(params) });
+  }
+
+  /** `analytic()` plus the `X-Data-Source-Status` / `X-Data-Source` response headers, so an
+   * empty result can be told apart from a missing source. `analytic()` stays array-valued. */
+  protected analyticWithStatus<T>(endpoint: string, params?: Record<string, string>): Observable<AnalyticResult<T>> {
+    return this.http.get<T[]>(this.analyticUrl(endpoint), {
+      params: this.analyticParams(params),
+      observe: 'response',
+    }).pipe(
+      map((response) => ({
+        rows: response.body ?? [],
+        source: {
+          status: response.headers.get('X-Data-Source-Status'),
+          id: response.headers.get('X-Data-Source'),
+        },
+      })),
+    );
+  }
+
+  private analyticUrl(endpoint: string): string {
+    return this.url(RestURL.api_prefix + 'analytic/' + endpoint);
+  }
+
+  private analyticParams(params?: Record<string, string>): HttpParams {
+    let result = new HttpParams();
+    for (const key in params) {
+      if (Object.prototype.hasOwnProperty.call(params, key)) result = result.set(key, params[key]);
     }
-    return this.http.get<T[]>(this.url(RestURL.api_prefix + 'analytic/' + endpoint), { params: p });
+    return result;
   }
 }
+
+export interface AnalyticResult<T> {
+  rows: T[];
+  source: AnalyticSourceStatus;
+}
+
+export interface AnalyticSourceStatus {
+  status: string | null;
+  id: string | null;
+}

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/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_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',