@nauticana/sail 1.1.8 → 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.
 
@@ -772,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.8",
+  "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/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/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/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,
+    });
+  }
+}