@nauticana/sail 1.0.1 → 1.0.2

package/README.md

@@ -529,6 +529,70 @@ A complete screen is the pieces above assembled over `BillingService` — no met
 <!-- invoices: render listInvoices() rows directly -->
 ```
 
+## Off-session SCA / 3DS confirmation (v1.0.x)
+
+When an app charges a rider's **vaulted** card off-session (keel `payment.ChargeClient` / `StripeChargeClient`), the provider may return `requires_action` — the cardholder must complete a Strong Customer Authentication (3DS) challenge. keel surfaces the hooks on `ChargeResult` (`ClientSecret`, `ActionURL`); sail standardizes the **client-side** confirmation so it isn't rebuilt per app.
+
+sail stays provider-agnostic: it ships **no payment-provider SDK** and **no default confirmer**. It provides a port (`ScaConfirmer`), the `SCA_CONFIRMER` injection token, and `<sail-sca-confirm>`, which:
+
+- redirects to `ChargeResult.actionUrl` when present (provider-hosted challenge — no SDK needed); else
+- delegates the inline `ChargeResult.clientSecret` to the app-registered `SCA_CONFIRMER`.
+
+### Backend contract (app-owned)
+
+Off-session charging is a worker/handler concern, so the **app** owns the charge endpoint. Have it call keel's `ChargeClient.Charge` and return the normalized result as camelCase JSON matching sail's `ChargeResult`:
+
+```jsonc
+// POST /api/<app>/charge  →  200
+{ "status": "requires_action", "clientSecret": "pi_..._secret_...", "actionUrl": "" }
+// or { "status": "succeeded", "providerChargeId": "pi_..." }
+// or { "status": "failed", "error": "card_declined" }
+```
+
+> `ChargeRequest.Metadata` (keel v1.0.4) carries `ride_id` / `user_id` / `tip_amount` through to the settled charge's `PaymentEvent.Metadata`, so the webhook can correlate and split the fare — set it on the backend, not the client.
+
+### Frontend adoption (downstream projects)
+
+**1. Implement the provider confirmer** (Stripe shown; lives in the app, behind an *optional* `@stripe/stripe-js` peer dep — non-Stripe apps skip it):
+
+```typescript
+import { Injectable } from '@angular/core';
+import { loadStripe } from '@stripe/stripe-js';
+import { ScaConfirmer, ScaResult } from '@nauticana/sail';
+
+@Injectable({ providedIn: 'root' })
+export class StripeScaConfirmer implements ScaConfirmer {
+  async confirm(clientSecret: string): Promise<ScaResult> {
+    const stripe = await loadStripe(/* publishable key from backend cache */);
+    if (!stripe) return { outcome: 'failed', error: 'Stripe.js failed to load' };
+    const { error } = await stripe.handleNextAction({ clientSecret });
+    return error ? { outcome: 'failed', error: error.message } : { outcome: 'succeeded' };
+  }
+}
+```
+
+**2. Register it at composition time** (`app.config.ts` / `main.ts`):
+
+```typescript
+import { SCA_CONFIRMER } from '@nauticana/sail';
+
+providers: [
+  { provide: SCA_CONFIRMER, useExisting: StripeScaConfirmer },
+]
+```
+
+**3. Drop the component into the post-charge flow** — bind the charge response and react to the outcome:
+
+```html
+<sail-sca-confirm
+    [result]="charge()"
+    (confirmed)="onPaid()"
+    (failed)="onScaFailed($event)">
+</sail-sca-confirm>
+```
+
+`<sail-sca-confirm>` renders nothing for `succeeded`, the decline message for `failed`, and a confirm button for `requires_action`. The publishable key is backend-authoritative — read it from the auth/app-data cache, never hardcode a fallback.
+
 ## Consent capture
 
 `ConsentGateComponent` is a reusable signup-consent primitive that mirrors keel's `user.SignupConsent` structure. It always renders two required checkboxes (`privacy_policy`, `cross_border`) and lets you declare any number of optional consents.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nauticana/sail",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Metadata-driven Angular component library for CRUD admin frontends backed by the keel Go backend. Tables, forms, navigation, OTP/2FA/social auth, billing, payout onboarding.",
   "main": "src/index.ts",
   "files": [

package/src/component/payment/sca_confirm.html

@@ -0,0 +1,14 @@
+@if (needsAction()) {
+  <div class="sca-confirm">
+    <button matButton="elevated" class="primary" type="button"
+            [disabled]="loading()"
+            (click)="confirm()">
+      @if (loading()) { Confirming… } @else { {{ label() }} }
+    </button>
+  </div>
+} @else if (declined()) {
+  <div class="auth-error" role="alert">{{ result().error ?? 'Your payment was declined.' }}</div>
+}
+@if (errorMessage()) {
+  <div class="auth-error" role="alert">{{ errorMessage() }}</div>
+}

package/src/component/payment/sca_confirm.ts

@@ -0,0 +1,77 @@
+import { ChangeDetectionStrategy, Component, ViewEncapsulation, computed, inject, input, output } from '@angular/core';
+import { MatButtonModule } from '@angular/material/button';
+import { BaseAsync } from '../abstract/base_async';
+import { ChargeResult } from '../../model/appdata';
+import { SCA_CONFIRMER } from '../../service/sca_confirmer';
+
+/**
+ * Drives the SCA / 3DS confirmation for an off-session `ChargeResult`.
+ *
+ * Two confirmation paths, mirroring keel's `ChargeResult`:
+ *  - `actionUrl` present → redirect to the provider-hosted challenge
+ *    (provider-agnostic; the page navigates away).
+ *  - otherwise `clientSecret` → delegate to the injected `SCA_CONFIRMER`
+ *    (the app's provider SDK wrapper). No confirmer is bundled in sail.
+ *
+ * Renders nothing for a `succeeded` result; shows the decline message for
+ * `failed`; shows a confirm button for `requires_action`. Emits `(confirmed)`
+ * on success and `(failed)` with a message on any error — never silently.
+ */
+@Component({
+  selector: 'sail-sca-confirm',
+  templateUrl: './sca_confirm.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  imports: [MatButtonModule],
+})
+export class ScaConfirmComponent extends BaseAsync {
+  private readonly confirmer = inject(SCA_CONFIRMER, { optional: true });
+
+  readonly result = input.required<ChargeResult>();
+  readonly label = input('Confirm your payment');
+  readonly confirmed = output<void>();
+  readonly failed = output<string>();
+
+  readonly needsAction = computed(() => this.result().status === 'requires_action');
+  readonly declined = computed(() => this.result().status === 'failed');
+
+  async confirm(): Promise<void> {
+    const res = this.result();
+
+    // Provider-hosted redirect branch — provider-agnostic; navigates away.
+    if (res.actionUrl) {
+      window.location.href = res.actionUrl;
+      return;
+    }
+
+    // Inline confirmation branch — delegates to the app's provider impl.
+    if (!res.clientSecret) {
+      this.fail('Missing client secret for SCA confirmation.');
+      return;
+    }
+    if (!this.confirmer) {
+      this.fail('No SCA confirmer is configured. Provide SCA_CONFIRMER (e.g. a Stripe.js wrapper).');
+      return;
+    }
+
+    this.clearMessages();
+    this.loading.set(true);
+    try {
+      const out = await this.confirmer.confirm(res.clientSecret);
+      this.loading.set(false);
+      if (out.outcome === 'succeeded') {
+        this.confirmed.emit();
+      } else {
+        this.fail(out.error ?? 'Payment confirmation was not completed.');
+      }
+    } catch (e: unknown) {
+      this.loading.set(false);
+      this.fail(e instanceof Error ? e.message : 'Payment confirmation failed.');
+    }
+  }
+
+  private fail(message: string): void {
+    this.errorMessage.set(message);
+    this.failed.emit(message);
+  }
+}

package/src/index.ts

@@ -41,7 +41,9 @@ export * from './component/billing/dunning_banner';
 export * from './component/payout/provider_onboarding';
 export * from './component/payout/bank_info_form';
 export * from './component/payment/user_payment_methods';
+export * from './component/payment/sca_confirm';
 export * from './service/auth.service';
+export * from './service/sca_confirmer';
 export * from './service/billing.service';
 export * from './service/payout.service';
 export * from './service/user_payment_method.service';

package/src/model/appdata.ts

@@ -284,6 +284,25 @@ export interface UsageMeter {
 	limit:    number;
 }
 
+// Normalized outcome of an off-session charge — the camelCase JSON shape an app
+// returns from its own charge endpoint, mirroring keel `payment.ChargeResult`.
+// 'requires_action' means the rider must complete an SCA / 3DS confirmation
+// (drive it with `<sail-sca-confirm>`).
+export type ChargeStatus = 'succeeded' | 'requires_action' | 'failed';
+
+export interface ChargeResult {
+	status:            ChargeStatus;
+	providerChargeId?: string;   // PaymentIntent / charge id (pi_xxx)
+	// Provider client secret — present when status === 'requires_action' and the
+	// SCA challenge must be confirmed inline (provider SDK). Mirrors keel
+	// ChargeResult.ClientSecret.
+	clientSecret?:     string;
+	// Provider-hosted redirect URL when one exists (often empty for off-session
+	// 3DS). When present it's the simplest, provider-agnostic confirmation path.
+	actionUrl?:        string;
+	error?:            string;   // decline / error message when status === 'failed'
+}
+
 // REST list endpoints return paginated wrappers. `BackendService.list<T>()`
 // unwraps to the array; use `listPaginated<T>()` to get the metadata.
 export interface PaginatedList<T> {

package/src/service/sca_confirmer.ts

@@ -0,0 +1,29 @@
+import { InjectionToken } from '@angular/core';
+
+/** Outcome of a client-side SCA / 3DS confirmation attempt. */
+export type ScaOutcome = 'succeeded' | 'failed' | 'cancelled';
+
+export interface ScaResult {
+  outcome: ScaOutcome;
+  error?:  string;
+}
+
+/**
+ * Provider-agnostic port for confirming a Strong Customer Authentication (3DS)
+ * challenge on a `client_secret` returned by an off-session charge.
+ *
+ * sail ships NO provider SDK and NO default implementation — each app provides
+ * one for its payment provider (e.g. a thin Stripe.js wrapper calling
+ * `stripe.handleNextAction({ clientSecret })`) and registers it at composition
+ * time, keeping the provider choice out of the shared library:
+ *
+ *   { provide: SCA_CONFIRMER, useClass: StripeScaConfirmer }
+ *
+ * The `actionUrl` (provider-hosted redirect) branch needs no confirmer — only
+ * the inline `clientSecret` branch delegates here.
+ */
+export interface ScaConfirmer {
+  confirm(clientSecret: string): Promise<ScaResult>;
+}
+
+export const SCA_CONFIRMER = new InjectionToken<ScaConfirmer>('SailScaConfirmer');