@nauticana/sail 1.1.7 → 1.1.9

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.0.x ↔ keel v1.0.x**. 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.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.
 
@@ -144,7 +144,9 @@ bootstrapApplication(App, {
 });
 ```
 
-> **Auth-loop breaker.** `authInterceptor` carries a built-in circuit breaker: after 5 `401`/`403`s on token-bearing keel API calls within 10s it opens for 30s and refuses those requests **locally** (never sent), so a stale/rejected session can't drive the app to hammer the API and the edge/CDN. A later success closes it; login (no bearer) is never blocked, so recovery works. No wiring needed beyond registering `authInterceptor`.
+> **Auth-loop breaker.** `authInterceptor` carries a built-in circuit breaker: after 5 `401`s on token-bearing keel API calls within 10s it opens for 30s and refuses those requests **locally** (never sent), so a stale/rejected session can't drive the app to hammer the API and the edge/CDN. Only `401` counts — a `403` is a legitimate permission denial, not a session failure. A later success **or accepting a new token** (login) closes it, so a freshly authenticated session is never blocked. No wiring needed beyond registering `authInterceptor`.
+
+> **Phone-number change (opt-in).** `ProfileEditorComponent` and `MyAccountComponent` gate phone change behind a `phoneChangeEnabled` input (default `false`, since it needs an SMS provider — keel returns 503 without `Notify`). Enable it once your backend has SMS wired: `<sail-my-account [phoneChangeEnabled]="true" />` or `<sail-profile-editor [phoneChangeEnabled]="true" />`.
 
 ### 5. Create the root component
 
@@ -506,7 +508,7 @@ readonly meters = toSignal(this.billing.listUsage(), { initialValue: [] });
 
 ### Redirect-action (v1.0.0)
 
-A `TableAction` with `kind: 'redirect'` makes `BaseTable.executeAction` POST and then follow the returned `{ url }` instead of refreshing — so checkout / portal / any provider-hosted handoff can be declared as a basis `table_action` row with **no bespoke component**. The backend action handler returns `{ "url": "https://…" }`.
+A `TableAction` with `kind: 'R'` (redirect — the `constant_value` code) makes `BaseTable.executeAction` POST and then follow the returned `{ url }` instead of refreshing — so checkout / portal / any provider-hosted handoff can be declared as a basis `table_action` row with **no bespoke component**. The backend action handler returns `{ "url": "https://…" }`.
 
 > **Response-shape contract.** The generic redirect-action path reads a bare `url` because it's polymorphic — one dispatch for checkout / portal / export / etc., where the action's identity lives in the metadata, not the payload. keel's `WrapTableAction` enforces no shape; your inner handler must return `{ url }`. The *typed* billing endpoints keep specific names instead (`createCheckout()` → `checkoutUrl`, `createPortalSession()` → `portalUrl`). So the same portal concept has two response shapes depending on the path: wire it as `<sail-portal-button>` (typed → `portalUrl`) **or** as a `table_action` redirect (generic → `url`), not both.
 
@@ -770,6 +772,37 @@ Horizontal building blocks for an entitlement-aware dashboard. All are presentat
 
 Models: `DataCardState`, `ActionItem`, `EntityOption`, `VerificationStep`.
 
+## Provider connections (v1.1.9)
+
+`ConnectionPanel` is the drop-in UI for keel's `oauth/connect` layer — connect a
+partner to external providers (Google, GBP, Meta, Shopify, or any API-key service),
+then test / disconnect. Presentational and CSS-free; the app owns the provider
+catalog and any routing via the outputs.
+
+- **`OAuthConnectionPanelComponent`** (`sail-oauth-connection-panel`) — renders a card per
+  `[providers]: OAuthProviderDescriptor[]` with connect / test / reconnect / disconnect.
+  Providers with `fields` or a `connectNote` open an inline form/consent step first (API-key
+  credentials, a Shopify `shop`, or a "you'll be redirected to…" note); a bare field-less OAuth
+  provider redirects straight to consent. `[entityId]` scopes per-business connections and
+  reloads on change (0 = tenant-wide). Emits `connected` / `disconnected`.
+  Ships no CSS — style `.connections`, `.connection-card`, `.connection-card__{head,title,status,actions}`,
+  `.connection-form`, `.connection-panel__error`, and `.status--{connected,error,pending}`.
+- Each `OAuthProviderField` has a **`role`**: `credential` (sealed secret), `endpoint` (stored
+  as `api_endpoint`), or `param` (OAuth authorize query param) — so field order is
+  irrelevant. `icon` is a Material name or an image URL.
+- **`OAuthConnectionService`** — `startOAuth(provider, extra)` → consent URL,
+  `testConnection`, `list(entityId)` / `disconnect` (generic `partner_credential` REST), and
+  `saveApiKey` (POSTs the sealed `/api/oauth/apikey`).
+
+```html
+<sail-oauth-connection-panel [providers]="providers" [entityId]="businessId()"
+  (connected)="reload()" (disconnected)="reload()"></sail-oauth-connection-panel>
+```
+
+The app supplies the descriptor list (which providers, icons, copy, api-key fields);
+keel owns the flow and sealed storage. Models: `OAuthProviderDescriptor`,
+`PartnerCredential`, `OAuthConnectionView`, `OAuthConnectionStatus`.
+
 ## Adding a new domain table
 
 When your project owns a table that isn't part of basis (e.g. `favorite_location`, `support_ticket`, `vehicle`), follow the pattern below so the row plays nicely with keel's generic CRUD endpoints and the sail `<table-edit>` / `<table-list>` components.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nauticana/sail",
-  "version": "1.1.7",
+  "version": "1.1.9",
   "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/account/my_account.html

@@ -2,7 +2,7 @@
   <div class="auth-card">
     <h2 class="auth-title">My Account</h2>
 
-    <sail-profile-editor></sail-profile-editor>
+    <sail-profile-editor [phoneChangeEnabled]="phoneChangeEnabled()"></sail-profile-editor>
 
     <section class="account-section">
       <h3>Security</h3>

package/src/component/account/my_account.ts

@@ -1,4 +1,4 @@
-import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { ChangeDetectionStrategy, Component, input } from '@angular/core';
 import { RouterLink } from '@angular/router';
 import { MatButtonModule } from '@angular/material/button';
 import { ProfileEditorComponent } from './profile_editor';
@@ -12,4 +12,8 @@ import { ProfileEditorComponent } from './profile_editor';
   changeDetection: ChangeDetectionStrategy.OnPush,
   imports: [RouterLink, MatButtonModule, ProfileEditorComponent],
 })
-export class MyAccountComponent {}
+export class MyAccountComponent {
+  /** Opt-in: set true once the host's backend has an SMS provider, to expose
+   *  phone-number change in the embedded profile editor. */
+  readonly phoneChangeEnabled = input(false);
+}

package/src/component/account/profile_editor.html

@@ -45,6 +45,26 @@
 
 <section class="account-section">
   <h3>Phone</h3>
-  <p>{{ phone() || 'Not set' }}</p>
-  @if (!phoneChangeEnabled) { <p class="auth-instructions">Phone change is coming soon.</p> }
+  @if (!phoneChangeEnabled()) {
+    <p>{{ phone() || 'Not set' }}</p>
+  } @else if (phonePhase() === 'idle') {
+    <p>{{ phone() || 'Not set' }}</p>
+    <button matButton (click)="startPhoneChange()">Change phone</button>
+  } @else if (phonePhase() === 'enter') {
+    <mat-form-field appearance="outline">
+      <mat-label>New phone</mat-label>
+      <input matInput type="tel" [formControl]="newPhone" required>
+    </mat-form-field>
+    <button matButton="elevated" class="primary" (click)="sendPhoneCode()" [disabled]="newPhone.invalid || loading()">Send code</button>
+    <button matButton (click)="cancelPhoneChange()">Cancel</button>
+  } @else {
+    @if (phoneMsg()) { <p>{{ phoneMsg() }}</p> }
+    <mat-form-field appearance="outline">
+      <mat-label>Confirmation code</mat-label>
+      <input matInput [formControl]="phoneCode" inputmode="numeric" required>
+    </mat-form-field>
+    <button matButton="elevated" class="primary" (click)="confirmPhoneChange()" [disabled]="phoneCode.invalid || loading()">Confirm</button>
+    <button matButton (click)="cancelPhoneChange()">Cancel</button>
+  }
+  @if (phoneErr()) { <div class="auth-error" role="alert">{{ phoneErr() }}</div> }
 </section>

package/src/component/account/profile_editor.ts

@@ -1,4 +1,4 @@
-import { ChangeDetectionStrategy, Component, OnInit, inject, signal } from '@angular/core';
+import { ChangeDetectionStrategy, Component, OnInit, inject, input, signal } from '@angular/core';
 import { FormBuilder, FormControl, ReactiveFormsModule, Validators } from '@angular/forms';
 import { MatButtonModule } from '@angular/material/button';
 import { MatFormFieldModule } from '@angular/material/form-field';
@@ -6,9 +6,9 @@ import { MatInputModule } from '@angular/material/input';
 import { BaseAuthService } from '../../service/auth.service';
 import { UserProfile } from '../../model/auth';
 
-// Self-service profile editor: name/locale save immediately; email change is
-// verify-before-apply (code to the new address). Phone change is gated until
-// the backend has an SMS provider.
+// Self-service profile editor: name/locale save immediately; email and phone
+// change are verify-before-apply (code to the new value). Phone change is shown
+// only when the host enables phoneChangeEnabled (its backend has an SMS provider).
 @Component({
   selector: 'sail-profile-editor',
   templateUrl: './profile_editor.html',
@@ -19,8 +19,8 @@ export class ProfileEditorComponent implements OnInit {
   private readonly auth = inject(BaseAuthService);
   private readonly fb = inject(FormBuilder);
 
-  // Flip true once the backend wires an SMS provider for phone codes.
-  readonly phoneChangeEnabled = false;
+  // Set by the host once its backend wires an SMS provider for phone codes.
+  readonly phoneChangeEnabled = input(false);
 
   readonly loading = signal(false);
   readonly profileMsg = signal('');
@@ -40,6 +40,12 @@ export class ProfileEditorComponent implements OnInit {
   readonly newEmail = new FormControl('', [Validators.required, Validators.email]);
   readonly emailCode = new FormControl('', [Validators.required]);
 
+  readonly phonePhase = signal<'idle' | 'enter' | 'code'>('idle');
+  readonly phoneMsg = signal('');
+  readonly phoneErr = signal('');
+  readonly newPhone = new FormControl('', [Validators.required]);
+  readonly phoneCode = new FormControl('', [Validators.required]);
+
   ngOnInit(): void {
     this.auth.getProfile().subscribe({
       next: (p: UserProfile) => {
@@ -95,6 +101,38 @@ export class ProfileEditorComponent implements OnInit {
     });
   }
 
+  startPhoneChange(): void {
+    this.phonePhase.set('enter');
+    this.phoneMsg.set('');
+    this.phoneErr.set('');
+  }
+
+  cancelPhoneChange(): void {
+    this.phonePhase.set('idle');
+    this.newPhone.reset();
+    this.phoneCode.reset();
+  }
+
+  sendPhoneCode(): void {
+    if (this.newPhone.invalid) return;
+    this.loading.set(true);
+    this.phoneErr.set('');
+    this.auth.requestPhoneChange(this.newPhone.value!).subscribe({
+      next: () => { this.loading.set(false); this.phonePhase.set('code'); this.phoneMsg.set('We sent a code to your new number.'); },
+      error: (e) => { this.loading.set(false); this.phoneErr.set(this.msg(e, 'Could not send a code.')); },
+    });
+  }
+
+  confirmPhoneChange(): void {
+    if (this.phoneCode.invalid) return;
+    this.loading.set(true);
+    this.phoneErr.set('');
+    this.auth.confirmPhoneChange(this.newPhone.value!, Number(this.phoneCode.value)).subscribe({
+      next: () => { this.loading.set(false); this.phone.set(this.newPhone.value!); this.cancelPhoneChange(); this.profileMsg.set('Phone updated.'); },
+      error: (e) => { this.loading.set(false); this.phoneErr.set(this.msg(e, 'Invalid or expired code.')); },
+    });
+  }
+
   private msg(e: { error?: { detail?: string; message?: string } }, fallback: string): string {
     return e?.error?.detail || e?.error?.message || fallback;
   }

package/src/component/dashboard/entity_selector.ts

@@ -19,22 +19,24 @@ export class EntitySelectorComponent {
   readonly entities = input<EntityOption[]>([]);
   readonly selected = input<string | undefined>(undefined);
   readonly label = input<string>('Business');
-  readonly selectionChange = output<string>();
+  readonly selectionChange = output<string | undefined>();
 
   readonly value = signal<string | undefined>(undefined);
 
   constructor() {
     // Explicit selection wins; else keep the current pick if still valid; else the
-    // first active entity. Emit whenever the resolved value actually changes.
+    // first active entity. "Valid" means present AND active, so a scope that goes
+    // inactive (or vanishes) is dropped. Emit on every change, including a clear
+    // (undefined) when no active option remains, so the host stops showing stale data.
     effect(() => {
       const opts = this.entities();
-      const want = this.selected();
+      const isActive = (id?: string) => !!id && opts.some((e) => e.id === id && e.active !== false);
       const cur = this.value();
       const resolved =
-        want && opts.some((e) => e.id === want) ? want
-          : cur && opts.some((e) => e.id === cur) ? cur
+        isActive(this.selected()) ? this.selected()
+          : isActive(cur) ? cur
             : opts.find((e) => e.active !== false)?.id;
-      if (resolved && resolved !== cur) {
+      if (resolved !== cur) {
         this.value.set(resolved);
         this.selectionChange.emit(resolved);
       }

package/src/component/login/login_component.html

@@ -9,6 +9,9 @@
     @if (loggedOut) {
       <p class="auth-message" role="status" aria-live="polite">You have been logged out successfully.</p>
     }
+    @if (sessionHandoffError()) {
+      <p class="auth-error" role="alert">{{ sessionHandoffError() }}</p>
+    }
     <form [formGroup]="loginForm" (ngSubmit)="login()" class="auth-form">
       <mat-form-field appearance="outline">
         <mat-label>Username</mat-label>

package/src/component/login/login_component.ts

@@ -1,7 +1,7 @@
 import { ChangeDetectionStrategy, Component, computed, inject, ViewEncapsulation } from '@angular/core';
 import { FormBuilder, ReactiveFormsModule, Validators } from '@angular/forms';
 import { BaseAuthService } from '../../service/auth.service';
-import { ActivatedRoute, Router, RouterLink } from '@angular/router';
+import { ActivatedRoute, RouterLink } from '@angular/router';
 import { MatButtonModule } from '@angular/material/button';
 import { MatFormFieldModule } from "@angular/material/form-field";
 import { MatInputModule } from '@angular/material/input';
@@ -25,10 +25,11 @@ import { SocialLoginComponent } from './social_login';
 })
 export class LoginComponent {
   private auth = inject(BaseAuthService);
-  private router = inject(Router);
   protected fb = inject(FormBuilder);
   protected readonly guiConfig: SailGuiConfig = inject(SAIL_GUI_CONFIG, {optional: true}) ?? DEFAULT_CONFIG;
   protected readonly loggedOut = inject(ActivatedRoute).snapshot.queryParamMap.get('loggedOut') === 'true';
+  /** OAuth session-cookie handoff failure from BaseAuthService, shown below. */
+  protected readonly sessionHandoffError = this.auth.sessionHandoffError;
 
   /**
    * Auto-show the embedded SocialLoginComponent whenever at least one
@@ -58,14 +59,12 @@ export class LoginComponent {
   }
 
   /**
-   * SocialLoginComponent emits the response after BaseAuthService.loginSocial
-   * persists the JWT internally. Mirror the same post-login navigation that
-   * password-login uses (root route by default; consumers override via
-   * BaseAuthService.navigateToRoleHome when role-aware routing lands).
+   * loginSocial already ran completeLogin, which owns post-login navigation
+   * (route init, or the OAuth cookie handoff). Handlers must NOT navigate here —
+   * doing so abandons a pending handoff before its cookie is set. Downstream
+   * social-login handlers should follow the same rule.
    */
-  protected onSocialSuccess(_: LoginResponseSocial): void {
-    this.router.navigateByUrl('/');
-  }
+  protected onSocialSuccess(_: LoginResponseSocial): void {}
 
   protected onSocialError(err: Error): void {
     console.error('social login failed:', err);

package/src/component/oauth_connection/oauth_connection_panel.html

@@ -0,0 +1,68 @@
+@if (error()) {
+  <p class="connection-panel__error" role="alert">{{ error() }}</p>
+}
+
+@if (loading()) {
+  <p>Loading connections…</p>
+} @else {
+  <div class="connections">
+    @for (v of views(); track v.provider.code) {
+      <mat-card class="connection-card">
+        <div class="connection-card__head">
+          @if (v.provider.icon) {
+            @if (isIconUrl(v.provider.icon)) {
+              <img class="connection-card__icon" [ngSrc]="v.provider.icon" alt="" width="24" height="24" />
+            } @else {
+              <mat-icon>{{ v.provider.icon }}</mat-icon>
+            }
+          }
+          <h3 class="connection-card__title">{{ v.provider.name }}</h3>
+          <span
+            class="connection-card__status"
+            [class.status--connected]="v.status === 'connected'"
+            [class.status--error]="v.status === 'error'"
+            [class.status--pending]="v.status === 'pending'"
+          >{{ v.status }}</span>
+        </div>
+
+        @if (v.provider.description) {
+          <p class="connection-card__desc">{{ v.provider.description }}</p>
+        }
+
+        <div class="connection-card__actions">
+          @if (v.status === 'disconnected') {
+            <button matButton="filled" [disabled]="busy() === v.provider.code" (click)="connect(v)">
+              Connect
+            </button>
+          } @else {
+            <button matButton [disabled]="busy() === v.provider.code" (click)="test(v)">Test</button>
+            <button matButton [disabled]="busy() === v.provider.code" (click)="connect(v)">Reconnect</button>
+            <button matButton [disabled]="busy() === v.provider.code" (click)="disconnect(v)">Disconnect</button>
+          }
+        </div>
+
+        @if (expanded() === v.provider.code) {
+          @if (v.provider.connectNote) {
+            <p class="connection-card__note">{{ v.provider.connectNote }}</p>
+          }
+          <div class="connection-form">
+            @for (f of v.provider.fields; track f.key) {
+              <mat-form-field>
+                <mat-label>{{ f.label }}</mat-label>
+                <input
+                  matInput
+                  [type]="f.type ?? 'text'"
+                  [placeholder]="f.placeholder ?? ''"
+                  (input)="setField(v.provider.code, f.key, $event)"
+                />
+              </mat-form-field>
+            }
+            <button matButton="filled" [disabled]="busy() === v.provider.code" (click)="submit(v)">
+              {{ v.provider.authType === 'oauth' ? 'Continue' : 'Save' }}
+            </button>
+          </div>
+        }
+      </mat-card>
+    }
+  </div>
+}

package/src/component/oauth_connection/oauth_connection_panel.ts

@@ -0,0 +1,231 @@
+import { ChangeDetectionStrategy, Component, OnInit, computed, effect, inject, input, output, signal } from '@angular/core';
+import { NgOptimizedImage } from '@angular/common';
+import { Subscription } from 'rxjs';
+import { MatButtonModule } from '@angular/material/button';
+import { MatCardModule } from '@angular/material/card';
+import { MatIconModule } from '@angular/material/icon';
+import { MatFormFieldModule } from '@angular/material/form-field';
+import { MatInputModule } from '@angular/material/input';
+import { OAuthConnectionService } from '../../service/oauth_connection.service';
+import { OAuthConnectionStatus, OAuthConnectionView, PartnerCredential, OAuthProviderDescriptor, OAuthProviderFieldRole } from '../../model/oauth_connection';
+
+/**
+ * ConnectionPanel — drop-in UI for keel oauth/connect. Renders a card per
+ * app-supplied OAuthProviderDescriptor with connect / disconnect / test. Providers
+ * that need inputs (API-key credentials, Shopify's shop) open an inline form;
+ * field-less OAuth providers redirect on one click. Ships no CSS — style the
+ * documented `.connection-*` hooks. `entityId` scopes per-business connections
+ * (0 = tenant-wide). Selector: <sail-oauth-connection-panel>.
+ */
+@Component({
+  selector: 'sail-oauth-connection-panel',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [MatButtonModule, MatCardModule, MatIconModule, MatFormFieldModule, MatInputModule, NgOptimizedImage],
+  templateUrl: './oauth_connection_panel.html',
+})
+export class OAuthConnectionPanelComponent implements OnInit {
+  readonly providers = input<OAuthProviderDescriptor[]>([]);
+  readonly entityId = input(0);
+
+  readonly connected = output<string>();
+  readonly disconnected = output<string>();
+
+  private readonly svc = inject(OAuthConnectionService);
+
+  readonly connections = signal<PartnerCredential[]>([]);
+  readonly loading = signal(true);
+  readonly error = signal('');
+  readonly expanded = signal(''); // provider code whose input form is open
+  readonly busy = signal(''); // provider code with an action in flight
+  private readonly fieldValues = signal<Record<string, Record<string, string>>>({});
+  private readonly pendingSuccess = signal<Set<string>>(new Set());
+  private reloadSub?: Subscription;
+
+  // The list is already scoped to entityId(), so a per-provider match is correct.
+  readonly views = computed<OAuthConnectionView[]>(() => {
+    const byProvider = new Map(this.connections().map((c) => [c.Provider, c]));
+    return this.providers().map((provider) => ({
+      provider,
+      connection: byProvider.get(provider.code),
+      status: this.toStatus(byProvider.get(provider.code)),
+    }));
+  });
+
+  constructor() {
+    // Reload on init and whenever the entity scope changes.
+    effect(() => this.reload(this.entityId()));
+  }
+
+  // After an OAuth round-trip keel redirects back with ?<provider>=success. Record
+  // the codes (configured providers only), strip them — preserving the hash — and
+  // emit `connected` once the reload confirms the row exists (confirmSuccess).
+  ngOnInit(): void {
+    const q = new URLSearchParams(window.location.search);
+    const known = new Set(this.providers().map((p) => p.code));
+    const succeeded = new Set<string>();
+    q.forEach((value, key) => {
+      if (value === 'success' && known.has(key)) succeeded.add(key);
+    });
+    if (!succeeded.size) return;
+    this.pendingSuccess.set(succeeded);
+    for (const code of succeeded) q.delete(code);
+    const qs = q.toString();
+    window.history.replaceState({}, '', window.location.pathname + (qs ? '?' + qs : '') + window.location.hash);
+  }
+
+  private reload(entityId: number): void {
+    this.reloadSub?.unsubscribe(); // cancel any in-flight load so a slow old entity can't overwrite the new one
+    this.loading.set(true);
+    this.expanded.set('');
+    this.fieldValues.set({}); // never carry a typed credential across a reload / entity change
+    this.reloadSub = this.svc.list(entityId).subscribe({
+      next: (rows) => {
+        this.connections.set(rows ?? []);
+        this.loading.set(false);
+        this.confirmSuccess();
+      },
+      error: (e) => {
+        this.error.set(this.msg(e, 'Could not load your connections.'));
+        this.loading.set(false);
+      },
+    });
+  }
+
+  // Emit `connected` only for a returned provider whose row is actually present now.
+  private confirmSuccess(): void {
+    const pending = this.pendingSuccess();
+    if (!pending.size) return;
+    const present = new Set(this.connections().map((c) => c.Provider));
+    for (const code of pending) if (present.has(code)) this.connected.emit(code);
+    this.pendingSuccess.set(new Set());
+  }
+
+  isIconUrl(icon?: string): boolean {
+    return !!icon && (icon.includes('/') || icon.includes('.'));
+  }
+
+  private toStatus(c?: PartnerCredential): OAuthConnectionStatus {
+    if (!c) return 'disconnected';
+    if (c.Status === 'A') return 'connected';
+    if (c.Status === 'E') return 'error';
+    if (c.Status === 'P') return 'pending';
+    return 'disconnected';
+  }
+
+  // Providers with inputs or a consent note open a form first; a bare field-less
+  // OAuth provider connects on one click.
+  connect(v: OAuthConnectionView): void {
+    const needsForm = (v.provider.fields ?? []).length > 0 || !!v.provider.connectNote;
+    if (needsForm && this.expanded() !== v.provider.code) {
+      this.clearFields(v.provider.code); // open blank — never a stale credential
+      this.expanded.set(v.provider.code);
+      this.error.set('');
+      return;
+    }
+    this.submit(v);
+  }
+
+  private clearFields(code: string): void {
+    const all = { ...this.fieldValues() };
+    delete all[code];
+    this.fieldValues.set(all);
+  }
+
+  // Submit collected inputs: OAuth → authorize redirect (fields ride as params);
+  // API-key → save the role-tagged credential + endpoint.
+  submit(v: OAuthConnectionView): void {
+    const fields = v.provider.fields ?? [];
+    const vals = this.fieldValues()[v.provider.code] ?? {};
+    const missing = fields.filter((f) => f.required !== false && !vals[f.key]);
+    if (missing.length) {
+      this.error.set('Missing ' + missing.map((f) => f.label).join(', '));
+      return;
+    }
+    this.busy.set(v.provider.code);
+    this.error.set('');
+
+    if (v.provider.authType === 'oauth') {
+      // Only 'param' fields belong in the authorize URL — never a credential/endpoint.
+      const extra: Record<string, string> = { entity_id: String(this.entityId()) };
+      for (const f of fields) if (f.role === 'param') extra[f.key] = vals[f.key] ?? '';
+      this.svc.startOAuth(v.provider.code, extra).subscribe({
+        next: (url) => this.redirect(url),
+        error: (e) => {
+          this.busy.set('');
+          this.error.set(this.msg(e, 'Could not start the connection.'));
+        },
+      });
+      return;
+    }
+
+    const credRef = this.roleValue(v, vals, 'credential');
+    const apiEndpoint = this.roleValue(v, vals, 'endpoint');
+    this.svc.saveApiKey(v.provider.code, credRef, apiEndpoint, this.entityId()).subscribe({
+      next: () => {
+        this.busy.set('');
+        this.connected.emit(v.provider.code);
+        this.reload(this.entityId());
+      },
+      error: (e) => {
+        this.busy.set('');
+        this.error.set(this.msg(e, 'Could not save the key.'));
+      },
+    });
+  }
+
+  private roleValue(v: OAuthConnectionView, vals: Record<string, string>, role: OAuthProviderFieldRole): string {
+    const f = (v.provider.fields ?? []).find((x) => x.role === role);
+    return f ? (vals[f.key] ?? '') : '';
+  }
+
+  setField(code: string, key: string, ev: Event): void {
+    const value = (ev.target as HTMLInputElement).value;
+    const all = { ...this.fieldValues() };
+    all[code] = { ...(all[code] ?? {}), [key]: value };
+    this.fieldValues.set(all);
+  }
+
+  test(v: OAuthConnectionView): void {
+    if (!v.connection) return;
+    this.busy.set(v.provider.code);
+    this.error.set('');
+    this.svc.testConnection(v.provider.code, this.entityId()).subscribe({
+      // keel returns HTTP 200 with {status:'error', message} for a failed test —
+      // surface the message, then reload to reflect the status it just recorded.
+      next: (res) => {
+        this.busy.set('');
+        if (res.status !== 'ok') this.error.set(res.message || 'Connection test failed.');
+        this.reload(this.entityId());
+      },
+      error: (e) => {
+        this.busy.set('');
+        this.error.set(this.msg(e, 'Could not test the connection.'));
+      },
+    });
+  }
+
+  disconnect(v: OAuthConnectionView): void {
+    if (!v.connection?.Id) return;
+    this.busy.set(v.provider.code);
+    this.svc.disconnect(v.connection.Id).subscribe({
+      next: () => {
+        this.busy.set('');
+        this.disconnected.emit(v.provider.code);
+        this.reload(this.entityId());
+      },
+      error: (e) => {
+        this.busy.set('');
+        this.error.set(this.msg(e, 'Could not disconnect.'));
+      },
+    });
+  }
+
+  protected redirect(url: string): void {
+    window.location.href = url;
+  }
+
+  private msg(e: unknown, fallback: string): string {
+    const err = e as { error?: { detail?: string; message?: string } };
+    return err?.error?.detail ?? err?.error?.message ?? fallback;
+  }
+}

package/src/index.ts

@@ -3,6 +3,7 @@ export * from './model/appdata';
 export * from './model/auth';
 export * from './model/common';
 export * from './model/dashboard';
+export * from './model/oauth_connection';
 export * from './model/decorator';
 export * from './component/abstract/base_table';
 export * from './component/dashboard/dashboard_shell';
@@ -11,6 +12,7 @@ export * from './component/dashboard/locked_overlay';
 export * from './component/dashboard/action_center';
 export * from './component/dashboard/entity_selector';
 export * from './component/dashboard/verification_flow';
+export * from './component/oauth_connection/oauth_connection_panel';
 export * from './component/abstract/base_form';
 export * from './component/abstract/base_view';
 export * from './component/abstract/base_async';
@@ -56,6 +58,7 @@ export * from './service/auth.service';
 export * from './service/sca_confirmer';
 export * from './service/billing.service';
 export * from './service/payout.service';
+export * from './service/oauth_connection.service';
 export * from './service/user_payment_method.service';
 export * from './service/script_loader';
 export * from './service/auth.interceptor';

package/src/model/appdata.ts

@@ -83,7 +83,7 @@ export interface TableAction {
   confirmMessage?:  string;
   authorityObject:  string;   // uppercased table_name — for canExecute()
   authorityCheck:   string;   // uppercased action_name — for canExecute()
-  kind?:            'P' | 'R' | 'V'; // P post (default) / R redirect (follow {url}) / V reveal (show returned secret once)
+  kind?:            'P' | 'R' | 'V'; // constant_value codes: P post (default) / R redirect (follow {url}) / V reveal (show returned secret once)
 }
 
 export interface ForeignKey {

package/src/model/oauth_connection.ts

@@ -0,0 +1,50 @@
+// Partner→external-provider connections (keel oauth/connect). The app supplies a
+// OAuthProviderDescriptor[] catalog; sail's ConnectionPanel renders/manages them.
+
+/** Mirrors keel partner_credential (the browser never sees the sealed cred_ref). */
+export interface PartnerCredential {
+  Id?: number;
+  PartnerId?: number;
+  /** 0 = tenant-wide; >0 = a specific business/entity. */
+  EntityId?: number;
+  Provider: string;
+  /** 'O' = OAuth, 'A' = API key. */
+  ConnectionType: 'O' | 'A';
+  /** 'A' active, 'E' error, 'P' pending, 'I' inactive. */
+  Status: 'A' | 'E' | 'P' | 'I';
+  ApiEndpoint?: string;
+  LastChecked?: string;
+}
+
+// credential = sealed secret; endpoint = api_endpoint; param = OAuth authorize query param.
+export type OAuthProviderFieldRole = 'credential' | 'endpoint' | 'param';
+
+// role is explicit so field order can't mistake a URL for the credential.
+export interface OAuthProviderField {
+  key: string;
+  label: string;
+  role: OAuthProviderFieldRole;
+  placeholder?: string;
+  type?: 'text' | 'password';
+  required?: boolean;
+}
+
+/** App-supplied catalog entry the ConnectionPanel renders. */
+export interface OAuthProviderDescriptor {
+  code: string;
+  name: string;
+  icon?: string; // Material icon name or an image URL (assets/icons/x.svg)
+  authType: 'oauth' | 'api_key';
+  description?: string;
+  connectNote?: string;
+  fields?: OAuthProviderField[]; // API-key: credential (+ endpoint); OAuth: param fields (Shopify shop)
+}
+
+export type OAuthConnectionStatus = 'connected' | 'disconnected' | 'error' | 'pending';
+
+/** A descriptor joined with its current stored connection + derived status. */
+export interface OAuthConnectionView {
+  provider: OAuthProviderDescriptor;
+  connection?: PartnerCredential;
+  status: OAuthConnectionStatus;
+}

package/src/service/auth.interceptor.ts

@@ -2,12 +2,11 @@ import { HttpErrorResponse, HttpEventType, HttpInterceptorFn } from '@angular/co
 import { catchError, tap, throwError } from 'rxjs';
 import { isKeelApiUrl } from './rest_url';
 
-// Auth-loop breaker: repeated 401/403s on token-bearing API calls (a stale or
-// rejected session) can drive the app to hammer the API — and the edge/CDN in
-// front of it — indefinitely. After AUTH_FAIL_THRESHOLD failures within
-// AUTH_FAIL_WINDOW_MS the circuit opens for AUTH_CIRCUIT_COOLDOWN_MS: authed API
-// requests are refused locally (never sent) so the storm stops at the browser. A
-// later success closes it; login (no bearer) is never blocked, so recovery works.
+// 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
+// requests are refused locally. Only 401 counts (403 is a permission denial); a
+// success or accepting a new token closes it.
 const AUTH_FAIL_WINDOW_MS = 10_000;
 const AUTH_FAIL_THRESHOLD = 5;
 const AUTH_CIRCUIT_COOLDOWN_MS = 30_000;
@@ -36,7 +35,7 @@ export const authInterceptor: HttpInterceptorFn = (req, next) => {
       }
     }),
     catchError((err: HttpErrorResponse) => {
-      if (authedApi && (err.status === 401 || err.status === 403)) {
+      if (authedApi && err.status === 401) {
         recordAuthFailure();
       }
       return throwError(() => err);
@@ -70,3 +69,9 @@ function clearAuthFailures(): void {
   sessionStorage.removeItem(FAIL_KEY);
   sessionStorage.removeItem(OPEN_KEY);
 }
+
+/** Close the circuit on accepting a new token, so a freshly logged-in session
+ *  isn't blocked by failures from a prior stale session. */
+export function resetAuthCircuit(): void {
+  clearAuthFailures();
+}

package/src/service/auth.service.ts

@@ -16,6 +16,7 @@ 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';
 
 /** Sort dropdown options by their visible label so long lookup lists are scannable. */
 const byCaption = (a: ConstantValue, b: ConstantValue) =>
@@ -61,6 +62,10 @@ export abstract class BaseAuthService extends BaseRestService {
   token: string | null = null;
   readonly isLoggedIn = signal(false);
 
+  /** Set when the OAuth session-cookie handoff fails; the UI shows it and lets the
+   *  user retry instead of being redirected into a cookieless login loop. */
+  readonly sessionHandoffError = signal<string | null>(null);
+
   /**
    * Multi-role app support. Consumers that distinguish rider/driver/admin
    * (or any equivalent split) call setRole() after login, then
@@ -117,15 +122,22 @@ export abstract class BaseAuthService extends BaseRestService {
     this.token = token;
     this.isLoggedIn.set(true);
     localStorage.setItem('jwt', token);
+    resetAuthCircuit(); // a new session must not inherit a prior session's open circuit
     const ret = this.validatedReturnUrl();
     if (ret && this.guiConfig.sessionCookieUrl) {
       // OAuth flow: mirror the bearer into a cookie, then hand off to the
-      // (cross-origin) authorization server via a full navigation.
+      // (cross-origin) authorization server via a full navigation. Only hand off
+      // once the cookie is actually set — redirecting after a failed cookie request
+      // sends the user on without a session and loops them back to login.
+      this.sessionHandoffError.set(null);
       this.http.post(this.url(this.guiConfig.sessionCookieUrl), {}, { withCredentials: true })
           .pipe(take(1))
           .subscribe({
             next: () => window.location.assign(ret),
-            error: () => window.location.assign(ret),
+            error: (err) => {
+              console.error('Session cookie handoff failed:', err);
+              this.sessionHandoffError.set('Could not complete sign-in. Please try again.');
+            },
           });
       return;
     }

package/src/service/oauth_connection.service.ts

@@ -0,0 +1,56 @@
+import { Injectable, inject } from '@angular/core';
+import { Observable } from 'rxjs';
+import { map } from 'rxjs/operators';
+import { BaseRestService } from './base_rest.service';
+import { BackendService } from './rest_service';
+import { PartnerCredential } from '../model/oauth_connection';
+
+/**
+ * OAuthConnectionService — frontend client for keel oauth/connect.
+ *
+ * OAuth flow endpoints live under /api/oauth/*; the stored connection rows are
+ * read/removed through the generic REST `partner_credential` API. entityId (0 =
+ * tenant-wide, >0 = a specific business) scopes per-entity connections.
+ */
+@Injectable({ providedIn: 'root' })
+export class OAuthConnectionService extends BaseRestService {
+  private readonly backend = inject(BackendService);
+  private readonly crudApi = 'partner_credential';
+
+  /** Start an OAuth connect flow; resolves to the provider consent URL to redirect to. */
+  startOAuth(provider: string, extra: Record<string, string> = {}): Observable<string> {
+    const qs = new URLSearchParams(extra).toString();
+    const path = `/api/oauth/${provider}/authorize${qs ? '?' + qs : ''}`;
+    return this.http.get<{ url: string }>(this.url(path)).pipe(map((r) => r.url));
+  }
+
+  /** Re-validate a stored connection (POST — it makes an outbound call and updates
+   * status). entityId selects which one (0 = tenant-wide). */
+  testConnection(provider: string, entityId = 0): Observable<{ status: string; message?: string }> {
+    return this.http.post<{ status: string; message?: string }>(
+      this.url(`/api/oauth/${provider}/test?entity_id=${entityId}`),
+      {},
+    );
+  }
+
+  /** The partner's stored connections for one entity scope (0 = tenant-wide).
+   * Filters by entity so the panel never shows another business's connections. */
+  list(entityId = 0): Observable<PartnerCredential[]> {
+    return this.backend.list<PartnerCredential>(this.crudApi, { EntityId: String(entityId) });
+  }
+
+  /** Remove a stored connection by id. */
+  disconnect(id: number): Observable<{ message: string }> {
+    return this.backend.delete(this.crudApi, { Id: String(id) });
+  }
+
+  /** Save an API-key connection (sealed server-side by the connect handler). */
+  saveApiKey(provider: string, credRef: string, apiEndpoint = '', entityId = 0): Observable<{ status: string }> {
+    return this.http.post<{ status: string }>(this.url('/api/oauth/apikey'), {
+      provider,
+      cred_ref: credRef,
+      api_endpoint: apiEndpoint,
+      entity_id: entityId,
+    });
+  }
+}