@nauticana/sail 1.1.23 → 1.1.24

package/README.md

@@ -772,14 +772,20 @@ being summed into a misleading total.
 The agency URL defaults use `/api/v1/agency/*`. Apps mounting Keel elsewhere
 must override the `RestURL.agency*URL` values with `configureRestUrls()`.
 
-## Off-session SCA / 3DS confirmation (v1.0.x)
+## Off-session SCA / 3DS confirmation (v1.0.x; refusals v1.1.24)
 
-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.
+When an app charges a rider's **vaulted** card off-session (keel `payment.ChargeClient` / `StripeChargeClient`), the cardholder may have to complete a Strong Customer Authentication (3DS) challenge. keel reports two distinct outcomes on `ChargeResult`, and they need different client operations:
 
-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:
+| `status` | What happened | Client operation |
+|---|---|---|
+| `requires_action` | The PaymentIntent carries a `next_action` to run. | Run it — `actionUrl` redirect, or `confirm(clientSecret)`. |
+| `authentication_required` | The issuer refused the off-session confirmation. The intent is back at `requires_payment_method` with **no `next_action`**. | Re-confirm the same intent on-session with the refused method — `confirmWithMethod(clientSecret, paymentMethodId)`. |
+
+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 dispatches on the status:
 
-- redirects to `ChargeResult.actionUrl` when present (provider-hosted challenge — no SDK needed); else
-- delegates the inline `ChargeResult.clientSecret` to the app-registered `SCA_CONFIRMER`.
+- `authentication_required` → `SCA_CONFIRMER.confirmWithMethod`; else
+- `actionUrl` present → redirect (provider-hosted challenge — no SDK needed); else
+- inline `clientSecret` → `SCA_CONFIRMER.confirm`.
 
 ### Backend contract (app-owned)
 
@@ -788,6 +794,7 @@ Off-session charging is a worker/handler concern, so the **app** owns the charge
 ```jsonc
 // POST /api/<app>/charge  →  200
 { "status": "requires_action", "clientSecret": "pi_..._secret_...", "actionUrl": "" }
+// or { "status": "authentication_required", "clientSecret": "pi_..._secret_...", "paymentMethodId": "pm_..." }
 // or { "status": "succeeded", "providerChargeId": "pi_..." }
 // or { "status": "failed", "error": "card_declined" }
 ```
@@ -811,6 +818,13 @@ export class StripeScaConfirmer implements ScaConfirmer {
     const { error } = await stripe.handleNextAction({ clientSecret });
     return error ? { outcome: 'failed', error: error.message } : { outcome: 'succeeded' };
   }
+
+  async confirmWithMethod(clientSecret: string, paymentMethodId: 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.confirmCardPayment(clientSecret, { payment_method: paymentMethodId });
+    return error ? { outcome: 'failed', error: error.message } : { outcome: 'succeeded' };
+  }
 }
 ```
 
@@ -834,7 +848,7 @@ providers: [
 </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.
+`<sail-sca-confirm>` renders nothing for `succeeded`, the decline message for `failed`, and a confirm button for both action states. The publishable key is backend-authoritative — read it from the auth/app-data cache, never hardcode a fallback.
 
 ## Consent capture
 
@@ -973,6 +987,13 @@ Analytics clients that need this distinction can call the protected
 `{ rows, source: { status, id } }`, populated from `X-Data-Source-Status` and
 `X-Data-Source`; the existing `analytic<T>()` remains `Observable<T[]>`.
 
+`sourceState(result, sourceName, connectLabel?)` maps an analytic result to
+`{ state, message, cta }` for `[state]`, `[noSourceMessage]`, and `[connectLabel]`.
+`NOT_CONNECTED` offers Connect; `NOT_COLLECTED` explains that collection is not
+live and leaves the CTA empty; `READY` or no header yields `ready` / `empty` from
+the rows. The caller supplies the source name and handles
+the click route.
+
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nauticana/sail",
-  "version": "1.1.23",
+  "version": "1.1.24",
   "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",
   "exports": {

package/src/component/payment/sca_confirm.ts

@@ -4,19 +4,7 @@ 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.
- */
+/** Confirms an off-session charge through a redirect or the injected provider. */
 @Component({
   selector: 'sail-sca-confirm',
   templateUrl: './sca_confirm.html',
@@ -32,23 +20,30 @@ export class ScaConfirmComponent extends BaseAsync {
   readonly confirmed = output<void>();
   readonly failed = output<string>();
 
-  readonly needsAction = computed(() => this.result().status === 'requires_action');
+  readonly needsAction = computed(() => {
+    const status = this.result().status;
+    return status === 'requires_action' || status === 'authentication_required';
+  });
   readonly declined = computed(() => this.result().status === 'failed');
 
   async confirm(): Promise<void> {
+    if (!this.needsAction() || this.loading()) return;
     const res = this.result();
+    const reconfirm = res.status === 'authentication_required';
 
-    // Provider-hosted redirect branch — provider-agnostic; navigates away.
-    if (res.actionUrl) {
+    if (!reconfirm && 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 (reconfirm && !res.paymentMethodId) {
+      this.fail('Missing payment method for re-confirmation.');
+      return;
+    }
     if (!this.confirmer) {
       this.fail('No SCA confirmer is configured. Provide SCA_CONFIRMER (e.g. a Stripe.js wrapper).');
       return;
@@ -57,7 +52,9 @@ export class ScaConfirmComponent extends BaseAsync {
     this.clearMessages();
     this.loading.set(true);
     try {
-      const out = await this.confirmer.confirm(res.clientSecret);
+      const out = reconfirm
+        ? await this.confirmer.confirmWithMethod(res.clientSecret, res.paymentMethodId!)
+        : await this.confirmer.confirm(res.clientSecret);
       this.loading.set(false);
       if (out.outcome === 'succeeded') {
         this.confirmed.emit();

package/src/model/appdata.ts

@@ -325,18 +325,21 @@ export interface UsageMeter {
 // 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';
+// 'authentication_required' is an off-session refusal: no next_action to run —
+// re-confirm the same intent on-session with paymentMethodId.
+export type ChargeStatus = 'succeeded' | 'requires_action' | 'authentication_required' | '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.
+	// Provider client secret for inline confirmation or on-session re-confirmation.
 	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;
+	// The refused stored method, to re-confirm with when
+	// status === 'authentication_required'. Mirrors keel ChargeResult.PaymentMethodID.
+	paymentMethodId?:  string;
 	error?:            string;   // decline / error message when status === 'failed'
 }
 

package/src/service/base_rest.service.ts

@@ -1,6 +1,7 @@
 import { HttpClient, HttpParams } from '@angular/common/http';
 import { inject } from '@angular/core';
 import { map, Observable } from 'rxjs';
+import type { DataCardState } from '../model/dashboard';
 import { RestURL } from './rest_url';
 
 /**
@@ -64,3 +65,20 @@ export interface AnalyticSourceStatus {
   status: string | null;
   id: string | null;
 }
+
+export interface SourceCardState {
+  state: DataCardState;
+  message: string;
+  cta: string;
+}
+
+/** Only keel's two not-ready states gate the card; `READY` or no header falls through to the rows. */
+export function sourceState<T>(result: AnalyticResult<T>, sourceName: string, connectLabel = 'Connect'): SourceCardState {
+  if (result.source.status === 'NOT_COLLECTED') {
+    return { state: 'no-source', message: `${sourceName} collection is not live yet.`, cta: '' };
+  }
+  if (result.source.status === 'NOT_CONNECTED') {
+    return { state: 'no-source', message: `Connect ${sourceName} to see this.`, cta: connectLabel };
+  }
+  return { state: result.rows.length ? 'ready' : 'empty', message: '', cta: '' };
+}

package/src/service/sca_confirmer.ts

@@ -20,10 +20,17 @@ export interface ScaResult {
  *   { provide: SCA_CONFIRMER, useClass: StripeScaConfirmer }
  *
  * The `actionUrl` (provider-hosted redirect) branch needs no confirmer — only
- * the inline `clientSecret` branch delegates here.
+ * the inline `clientSecret` branches delegate here.
  */
 export interface ScaConfirmer {
+  /** Run the intent's `next_action` (Stripe.js `handleNextAction`). */
   confirm(clientSecret: string): Promise<ScaResult>;
+  /**
+   * Re-confirm the intent on-session with the method the issuer refused
+   * off-session (Stripe.js `confirmCardPayment`, stripe-ios
+   * `STPPaymentHandler.confirmPayment`) — there is no `next_action` to run.
+   */
+  confirmWithMethod(clientSecret: string, paymentMethodId: string): Promise<ScaResult>;
 }
 
 export const SCA_CONFIRMER = new InjectionToken<ScaConfirmer>('SailScaConfirmer');