@nauticana/sail 0.5.7 → 0.6.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nauticana/sail",
-  "version": "0.5.7",
-  "description": "Metadata-driven Angular component library for CRUD admin frontends backed by the keel Go backend. Tables, forms, navigation, OTP/2FA/social auth, billing.",
+  "version": "0.6.1",
+  "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": [
     "src/",

package/src/component/payment/user_payment_methods.ts

@@ -0,0 +1,159 @@
+import { ChangeDetectionStrategy, Component, EventEmitter, Input, OnInit, Output, ViewEncapsulation, inject, signal } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { MatButtonModule } from '@angular/material/button';
+import { MatCardModule } from '@angular/material/card';
+import { MatIconModule } from '@angular/material/icon';
+import { BaseAsync } from '../abstract/base_async';
+import { UserPaymentMethodService } from '../../service/user_payment_method.service';
+import { UserPaymentMethod } from '../../model/appdata';
+
+/**
+ * End-user saved payment methods.
+ *
+ * Drop-in screen that lists the caller's cards/wallets, with set-default
+ * + 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).
+ *
+ * Selector: <sail-user-payment-methods>
+ */
+@Component({
+  selector: 'sail-user-payment-methods',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  imports: [CommonModule, MatButtonModule, MatCardModule, MatIconModule],
+  template: `
+    <div class="user-payment-methods">
+      <h2 class="user-payment-methods__title">{{ title }}</h2>
+
+      @if (showAdd) {
+        <button mat-raised-button color="accent"
+                class="user-payment-methods__add"
+                (click)="addClicked.emit()">
+          <mat-icon>add</mat-icon> {{ addLabel }}
+        </button>
+      }
+
+      @if (methods().length === 0 && !loading()) {
+        <p class="user-payment-methods__empty">{{ emptyLabel }}</p>
+      }
+
+      @for (m of methods(); track m.Id) {
+        <mat-card class="user-payment-methods__item">
+          <mat-card-content>
+            <div class="user-payment-methods__row">
+              <div class="user-payment-methods__info">
+                <mat-icon>{{ iconFor(m) }}</mat-icon>
+                <span class="user-payment-methods__brand">{{ m.Brand || m.MethodType }}</span>
+                @if (m.LastFour) {
+                  <span class="user-payment-methods__last4">•••• {{ m.LastFour }}</span>
+                }
+                @if (m.IsDefault) {
+                  <span class="user-payment-methods__default">Default</span>
+                }
+              </div>
+              <div class="user-payment-methods__actions">
+                @if (!m.IsDefault) {
+                  <button mat-button (click)="setDefault(m)">Set default</button>
+                }
+                <button mat-icon-button (click)="remove(m)" aria-label="Delete payment method">
+                  <mat-icon>delete</mat-icon>
+                </button>
+              </div>
+            </div>
+          </mat-card-content>
+        </mat-card>
+      }
+
+      @if (errorMsg()) {
+        <p class="user-payment-methods__error">{{ errorMsg() }}</p>
+      }
+    </div>
+  `,
+  styles: `
+    .user-payment-methods { display: flex; flex-direction: column; gap: 12px; }
+    .user-payment-methods__title { margin: 0; }
+    .user-payment-methods__add { align-self: flex-start; }
+    .user-payment-methods__empty { color: var(--mat-app-on-surface-variant, #555); }
+    .user-payment-methods__item { background: var(--mat-app-surface, #fff); }
+    .user-payment-methods__row { display: flex; justify-content: space-between; align-items: center; gap: 12px; }
+    .user-payment-methods__info { display: flex; align-items: center; gap: 8px; }
+    .user-payment-methods__brand { font-weight: 600; }
+    .user-payment-methods__last4 { color: var(--mat-app-on-surface-variant, #555); }
+    .user-payment-methods__default { color: var(--mat-app-primary, #1976d2); margin-left: 8px; font-size: 12px; font-weight: 600; }
+    .user-payment-methods__actions { display: flex; align-items: center; gap: 4px; }
+    .user-payment-methods__error { color: var(--mat-app-error, #b00020); font-size: 13px; margin: 0; }
+  `,
+})
+export class UserPaymentMethodsComponent extends BaseAsync implements OnInit {
+  @Input() title = 'Payment Methods';
+  @Input() addLabel = 'Add Payment Method';
+  @Input() emptyLabel = 'No saved payment methods yet.';
+  @Input() showAdd = true;
+
+  /** Emitted when the "Add" button is tapped. Consumer routes to its SetupIntent flow. */
+  @Output() addClicked = new EventEmitter<void>();
+  /** Emitted after a successful set-default flip. */
+  @Output() defaultChanged = new EventEmitter<UserPaymentMethod>();
+  /** Emitted after a successful delete. */
+  @Output() deleted = new EventEmitter<UserPaymentMethod>();
+
+  private readonly service = inject(UserPaymentMethodService);
+
+  readonly methods = signal<UserPaymentMethod[]>([]);
+  readonly errorMsg = signal<string>('');
+
+  ngOnInit(): void {
+    this.load();
+  }
+
+  load(): void {
+    this.run(
+      this.service.list(),
+      (rows) => {
+        // Sort default-first locally — keel's generic CRUD doesn't
+        // honour a sort hint without rest_api_header config.
+        const sorted = [...(rows ?? [])].sort((a, b) =>
+          Number(b.IsDefault) - Number(a.IsDefault),
+        );
+        this.methods.set(sorted);
+      },
+      'Failed to load payment methods.',
+    );
+  }
+
+  setDefault(m: UserPaymentMethod): void {
+    this.service.setDefault(m.Id).subscribe({
+      next: () => {
+        this.methods.update((list) =>
+          list.map((row) => ({ ...row, IsDefault: row.Id === m.Id })),
+        );
+        this.defaultChanged.emit(m);
+      },
+      error: (err) => this.errorMsg.set(err?.error?.detail ?? 'Failed to set default'),
+    });
+  }
+
+  remove(m: UserPaymentMethod): void {
+    this.service.delete(m.Id).subscribe({
+      next: () => {
+        this.methods.update((list) => list.filter((row) => row.Id !== m.Id));
+        this.deleted.emit(m);
+      },
+      error: (err) => this.errorMsg.set(err?.error?.detail ?? 'Failed to delete'),
+    });
+  }
+
+  iconFor(m: UserPaymentMethod): string {
+    switch (m.MethodType) {
+      case 'card':       return 'credit_card';
+      case 'bank':       return 'account_balance';
+      case 'apple_pay':
+      case 'google_pay':
+      case 'wallet':     return 'wallet';
+      default:           return 'credit_card';
+    }
+  }
+}

package/src/component/payout/bank_info_form.ts

@@ -0,0 +1,176 @@
+import { ChangeDetectionStrategy, Component, EventEmitter, Input, Output, computed, inject, signal } from '@angular/core';
+import { FormBuilder, ReactiveFormsModule, Validators } from '@angular/forms';
+import { MatButtonModule } from '@angular/material/button';
+import { MatCheckboxModule } from '@angular/material/checkbox';
+import { MatFormFieldModule } from '@angular/material/form-field';
+import { MatInputModule } from '@angular/material/input';
+import { MatSelectModule } from '@angular/material/select';
+import { BankInfoFormValue, CountryProfile } from '../../model/appdata';
+
+/**
+ * Default country profiles bundled with sail. Covers CA / US / EU; downstream
+ * apps can pass a different list via the `[countryProfiles]` input.
+ *
+ * Codes match basis constant_header `tax_id_type` seeded by keel:
+ *   S = SIN (CA), N = SSN (US), E = EIN (US business), V = VAT (EU), O = Other.
+ */
+export const DEFAULT_COUNTRY_PROFILES: CountryProfile[] = [
+  { code: 'CA', label: 'Canada',         currency: 'CAD', taxIdType: 'S', taxIdLabel: 'SIN',        taxIdPlaceholder: '123456789',   taxIdHint: 'Social Insurance Number — shared with the tax authority for annual reporting' },
+  { code: 'US', label: 'United States',  currency: 'USD', taxIdType: 'N', taxIdLabel: 'SSN or EIN', taxIdPlaceholder: '123-45-6789', taxIdHint: 'SSN for an individual recipient, EIN for an incorporated recipient' },
+  { code: 'DE', label: 'Germany (EU)',   currency: 'EUR', taxIdType: 'V', taxIdLabel: 'VAT number', taxIdPlaceholder: 'DE123456789', taxIdHint: 'VAT registration number' },
+];
+
+/**
+ * Payout bank-info form.
+ *
+ * Captures the basis `user_bank_info` fields (country, currency, account
+ * holder, tax id, billing address, agreement). Emits the form value via
+ * `(submitted)` — the consumer decides whether to POST directly to
+ * /api/v1/user_bank_info or pipe through its own registration service.
+ *
+ * `[provider]` defaults to "AW" (Airwallex) to match keel/payout's
+ * default --payout_provider flag. Override per deployment if needed.
+ *
+ * Selector: <sail-payout-bank-info-form>
+ */
+@Component({
+  selector: 'sail-payout-bank-info-form',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [
+    ReactiveFormsModule, MatButtonModule, MatCheckboxModule,
+    MatFormFieldModule, MatInputModule, MatSelectModule,
+  ],
+  template: `
+    <div class="bank-info-form">
+      <h2 class="bank-info-form__title">{{ title }}</h2>
+
+      @if (intro) {
+        <p class="bank-info-form__intro">{{ intro }}</p>
+      }
+
+      <form [formGroup]="form" (ngSubmit)="submit()">
+        <mat-form-field appearance="outline" class="full-width">
+          <mat-label>Country *</mat-label>
+          <mat-select formControlName="countryCode">
+            @for (c of countryProfiles; track c.code) {
+              <mat-option [value]="c.code">{{ c.label }} ({{ c.currency }})</mat-option>
+            }
+          </mat-select>
+        </mat-form-field>
+        <p class="hint">Sets your tax ID format + payout currency</p>
+
+        <mat-form-field appearance="outline" class="full-width">
+          <mat-label>Account holder name *</mat-label>
+          <input matInput formControlName="accountHolderName">
+        </mat-form-field>
+        <p class="hint">Legal name on the bank account (must match government ID)</p>
+
+        <mat-form-field appearance="outline" class="full-width">
+          <mat-label>{{ taxIdLabel() }} *</mat-label>
+          <input matInput formControlName="taxId" [placeholder]="taxIdPlaceholder()">
+        </mat-form-field>
+        <p class="hint">{{ taxIdHint() }}</p>
+
+        <mat-form-field appearance="outline" class="full-width">
+          <mat-label>Billing address *</mat-label>
+          <input matInput formControlName="billingAddress">
+        </mat-form-field>
+        <p class="hint">Business or home address — used for tax correspondence</p>
+
+        <p class="provider-note">
+          Bank routing details (account number + institution / ABA /
+          IBAN) are collected by the payout provider in the next step;
+          this application does not store them.
+        </p>
+
+        <mat-checkbox formControlName="providerAgreement" class="agreement">
+          {{ agreementLabel }}
+        </mat-checkbox>
+
+        <div class="nav-buttons">
+          @if (showBack) {
+            <button mat-stroked-button class="pill-btn" type="button" (click)="back.emit()">
+              &lt; Back
+            </button>
+          }
+          <button mat-flat-button class="pill-btn primary-btn" type="submit"
+                  [disabled]="form.invalid">
+            {{ submitLabel }}
+          </button>
+        </div>
+      </form>
+    </div>
+  `,
+  styles: `
+    .bank-info-form { display: flex; flex-direction: column; gap: 4px; padding: 0 24px 32px; }
+    .bank-info-form__title { margin: 0 0 16px; }
+    .bank-info-form__intro { font-size: 14px; color: var(--mat-app-on-surface-variant, #555); margin: 0 0 16px; }
+    .full-width { width: 100%; }
+    .hint { font-size: 12px; color: var(--mat-app-on-surface-variant, #555); margin: -4px 0 8px; }
+    .provider-note { font-size: 13px; color: var(--mat-app-on-surface-variant, #555); background: rgba(0,0,0,0.04); padding: 12px; border-radius: 4px; margin: 12px 0; }
+    .agreement { margin: 12px 0 16px; font-size: 14px; }
+    .nav-buttons { display: flex; gap: 12px; margin-top: 8px; }
+    .pill-btn { border-radius: 24px; height: 48px; font-size: 15px; font-weight: 600; flex: 1; }
+    .primary-btn { background: var(--mat-app-primary, #1976d2); color: white; }
+  `,
+})
+export class PayoutBankInfoFormComponent {
+  /** Step title rendered above the form. */
+  @Input() title = 'Payment and Tax';
+  /** Optional explainer rendered below the title. */
+  @Input() intro = 'Tax + payout details. Bank account itself is set up with the payout provider in a separate step — only tax-reporting and dispute-correspondence fields are collected here.';
+  /** Override the list of supported countries — keep the default for most apps. */
+  @Input() countryProfiles: CountryProfile[] = DEFAULT_COUNTRY_PROFILES;
+  /** Provider code persisted on user_bank_info.provider. Default AW (Airwallex) matches keel's default --payout_provider. */
+  @Input() provider = 'AW';
+  /** Wording on the provider-agreement checkbox. Override to name the live provider. */
+  @Input() agreementLabel = 'I agree to the payout provider account agreement';
+  /** Submit-button label — wizards usually use "Next >". */
+  @Input() submitLabel = 'Next >';
+  /** When true, the back button renders alongside submit. */
+  @Input() showBack = true;
+
+  /** Emitted on submit; payload maps 1:1 to basis user_bank_info columns. */
+  @Output() submitted = new EventEmitter<BankInfoFormValue>();
+  /** Emitted when the user clicks Back. */
+  @Output() back = new EventEmitter<void>();
+
+  private readonly fb = inject(FormBuilder);
+
+  readonly form = this.fb.group({
+    countryCode:       ['CA', Validators.required],
+    accountHolderName: ['', Validators.required],
+    taxId:             ['', Validators.required],
+    billingAddress:    ['', Validators.required],
+    providerAgreement: [false, Validators.requiredTrue],
+  });
+
+  private readonly selectedCountry = signal<CountryProfile>(this.countryProfiles[0]);
+
+  readonly taxIdLabel       = computed(() => this.selectedCountry().taxIdLabel);
+  readonly taxIdPlaceholder = computed(() => this.selectedCountry().taxIdPlaceholder);
+  readonly taxIdHint        = computed(() => this.selectedCountry().taxIdHint);
+
+  constructor() {
+    this.form.controls.countryCode.valueChanges.subscribe((code) => {
+      const profile = this.countryProfiles.find((c) => c.code === code) ?? this.countryProfiles[0];
+      this.selectedCountry.set(profile);
+    });
+  }
+
+  submit() {
+    if (this.form.invalid) return;
+    const v = this.form.value;
+    const country = this.selectedCountry();
+    this.submitted.emit({
+      countryCode:       country.code,
+      currency:          country.currency,
+      accountHolderName: v.accountHolderName!,
+      billingAddress:    v.billingAddress!,
+      taxIdType:         country.taxIdType,
+      taxId:             v.taxId!,
+      provider:          this.provider,
+      providerAgreement: v.providerAgreement!,
+    });
+  }
+}

package/src/component/payout/provider_onboarding.ts

@@ -0,0 +1,182 @@
+import { ChangeDetectionStrategy, Component, EventEmitter, Input, OnInit, Output, inject, signal } from '@angular/core';
+import { MatButtonModule } from '@angular/material/button';
+import { MatCardModule } from '@angular/material/card';
+import { MatIconModule } from '@angular/material/icon';
+import { MatRadioModule } from '@angular/material/radio';
+import { PayoutService } from '../../service/payout.service';
+import { ReusableAccount } from '../../model/appdata';
+
+/**
+ * Payout provider onboarding step.
+ *
+ * Drop-in screen for any keel-backed app that uses keel/payout. Renders
+ * two paths:
+ *   1. Reuse an existing provider account from another partner row
+ *      (zero-KYC; calls /api/v1/payout/reusable/link).
+ *   2. Launch the provider's hosted-KYC page in a new tab
+ *      (/api/v1/payout/onboard/start).
+ *
+ * Routing is consumer-owned via the `(linked)` / `(skipped)` outputs —
+ * the component itself never calls Router. Optional `title` and
+ * `skipLabel` inputs cover the common UX strings.
+ *
+ * Selector: <sail-payout-provider-onboarding>
+ */
+@Component({
+  selector: 'sail-payout-provider-onboarding',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [MatButtonModule, MatCardModule, MatIconModule, MatRadioModule],
+  template: `
+    <div class="payout-onboarding">
+      <h2 class="payout-onboarding__title">{{ title }}</h2>
+
+      <p class="payout-onboarding__intro">
+        Bank routing details are collected by the payout provider, not
+        this application. After this step the provider will run KYC and
+        notify us when the account is ready for payouts.
+      </p>
+
+      @if (reusable().length > 0) {
+        <mat-card class="reuse-card">
+          <mat-card-header>
+            <mat-card-title>Reuse an existing account</mat-card-title>
+          </mat-card-header>
+          <mat-card-content>
+            <p class="hint">
+              You already have a payout account on
+              {{ reusable().length === 1 ? 'another partner' : 'other partners' }}.
+              You can reuse it here (no KYC redo) if the currency matches.
+            </p>
+            <mat-radio-group [value]="selectedAccountId()" (change)="selectAccount($any($event.value))">
+              @for (acc of reusable(); track acc.providerAccountId) {
+                <mat-radio-button [value]="acc.providerAccountId" class="reuse-option">
+                  <strong>{{ acc.partnerCaption }}</strong>
+                  — {{ acc.countryCode }} / {{ acc.currency }} ({{ acc.provider }})
+                </mat-radio-button>
+              }
+            </mat-radio-group>
+            <button mat-flat-button class="payout-onboarding__btn payout-onboarding__btn--primary"
+                    [disabled]="!selectedAccountId() || busy()"
+                    (click)="linkExisting()">
+              Use this account
+            </button>
+          </mat-card-content>
+        </mat-card>
+      }
+
+      <mat-card>
+        <mat-card-header>
+          <mat-card-title>Set up a new account</mat-card-title>
+        </mat-card-header>
+        <mat-card-content>
+          <p class="hint">
+            Opens the provider's secure onboarding page. You'll be asked
+            for bank routing details and government ID. The process
+            usually takes a few minutes.
+          </p>
+          @if (errorMsg()) {
+            <p class="payout-onboarding__error">{{ errorMsg() }}</p>
+          }
+          <button mat-flat-button class="payout-onboarding__btn payout-onboarding__btn--primary"
+                  [disabled]="busy()"
+                  (click)="startProviderKyc()">
+            <mat-icon>open_in_new</mat-icon>
+            Start onboarding
+          </button>
+        </mat-card-content>
+      </mat-card>
+
+      <div class="payout-onboarding__nav">
+        @if (showBack) {
+          <button mat-stroked-button class="payout-onboarding__btn" type="button" (click)="back.emit()">
+            &lt; Back
+          </button>
+        }
+        <button mat-stroked-button class="payout-onboarding__btn" type="button" (click)="skipped.emit()">
+          {{ skipLabel }}
+        </button>
+      </div>
+    </div>
+  `,
+  styles: `
+    .payout-onboarding { display: flex; flex-direction: column; gap: 16px; padding: 0 24px 32px; }
+    .payout-onboarding__title { margin: 0; }
+    .payout-onboarding__intro { font-size: 14px; color: var(--mat-app-on-surface-variant, #555); margin: 0; }
+    .reuse-card { background: var(--mat-app-surface-variant, #f5f5f5); }
+    .reuse-option { display: block; margin: 8px 0; }
+    .hint { font-size: 13px; color: var(--mat-app-on-surface-variant, #555); margin: 0 0 12px; }
+    .payout-onboarding__error { color: var(--mat-app-error, #b00020); font-size: 13px; margin: 0 0 12px; }
+    .payout-onboarding__nav { display: flex; gap: 12px; margin-top: 8px; }
+    .payout-onboarding__btn { border-radius: 24px; height: 48px; font-size: 15px; font-weight: 600; flex: 1; }
+    .payout-onboarding__btn--primary { background: var(--mat-app-primary, #1976d2); color: white; }
+  `,
+})
+export class PayoutProviderOnboardingComponent implements OnInit {
+  /** Step title — defaults match the most common payout-step framing. */
+  @Input() title = 'Bank Account Setup';
+  /** Skip-button label — covers wizards where skipping returns to the parent flow. */
+  @Input() skipLabel = "I'll do this later";
+  /** When true, the back button renders alongside skip. */
+  @Input() showBack = true;
+
+  /** Emitted after a successful reuse-link operation. */
+  @Output() linked = new EventEmitter<void>();
+  /** Emitted when the user dismisses the step (skip). */
+  @Output() skipped = new EventEmitter<void>();
+  /** Emitted when the user clicks Back. */
+  @Output() back = new EventEmitter<void>();
+  /** Emitted after the hosted page is opened in a new tab. Consumers can route away or show a "waiting on provider" screen. */
+  @Output() started = new EventEmitter<void>();
+
+  private readonly payoutService = inject(PayoutService);
+
+  readonly reusable = signal<ReusableAccount[]>([]);
+  readonly selectedAccountId = signal<string>('');
+  readonly busy = signal<boolean>(false);
+  readonly errorMsg = signal<string>('');
+
+  ngOnInit() {
+    this.payoutService.listReusable().subscribe({
+      next: ({ accounts }) => this.reusable.set(accounts ?? []),
+      error: () => this.reusable.set([]),
+    });
+  }
+
+  selectAccount(id: string) {
+    this.selectedAccountId.set(id);
+  }
+
+  linkExisting() {
+    const id = this.selectedAccountId();
+    if (!id) return;
+    this.busy.set(true);
+    this.payoutService.linkReusable(id).subscribe({
+      next: () => {
+        this.busy.set(false);
+        this.linked.emit();
+      },
+      error: (err) => {
+        this.errorMsg.set(err?.error?.detail ?? 'Failed to link existing account');
+        this.busy.set(false);
+      },
+    });
+  }
+
+  startProviderKyc() {
+    this.busy.set(true);
+    this.payoutService.startOnboarding().subscribe({
+      next: (res) => {
+        this.busy.set(false);
+        // Open in the platform browser. Mobile webview wrappers
+        // intercept this and pop the system browser so the provider
+        // page works in its expected environment.
+        window.open(res.url, '_blank');
+        this.started.emit();
+      },
+      error: (err) => {
+        this.errorMsg.set(err?.error?.detail ?? 'Failed to start onboarding');
+        this.busy.set(false);
+      },
+    });
+  }
+}

package/src/index.ts

@@ -32,8 +32,13 @@ export * from './component/security/trusted_devices';
 export * from './component/billing/plan_selector';
 export * from './component/billing/checkout_button';
 export * from './component/billing/payment_methods';
+export * from './component/payout/provider_onboarding';
+export * from './component/payout/bank_info_form';
+export * from './component/payment/user_payment_methods';
 export * from './service/auth.service';
 export * from './service/billing.service';
+export * from './service/payout.service';
+export * from './service/user_payment_method.service';
 export * from './service/script_loader';
 export * from './service/auth.interceptor';
 export * from './service/api-response.interceptor';

package/src/model/appdata.ts

@@ -274,3 +274,81 @@ export interface Invoice {
 	issuedAt: string;
 	paidAt?:  string;
 }
+
+// ── Payout types ──
+// See keel/payout for the backend contract. user_bank_info is owned by
+// basis; these types mirror keel/payout's ReusableAccount and
+// StartOnboardingResult one-to-one.
+
+// One provider account the user already has on a different partner.
+// PayoutService.listReusable() returns these so multi-partner users can
+// pick an existing account instead of redoing KYC.
+export interface ReusableAccount {
+	partnerId:         number;
+	partnerCaption:    string;
+	provider:          string;  // 'AW' Airwallex, 'SC' Stripe Connect, 'WI' Wise
+	providerAccountId: string;
+	countryCode:       string;  // ISO 3166-1 alpha-2
+	currency:          string;  // ISO 4217
+	onboardedAt:       string;
+}
+
+// Result of PayoutService.startOnboarding(). url is opened in a webview /
+// external browser; the provider posts back via webhook when activation
+// lands.
+export interface PayoutOnboardingSession {
+	url:               string;
+	externalAccountId: string;
+	expiresAt:         string;
+}
+
+// Payload the bank-info form emits. Maps 1:1 to basis user_bank_info
+// columns. The consumer decides where to POST it — typically a direct
+// generic-CRUD insert against /api/v1/user_bank_info.
+export interface BankInfoFormValue {
+	countryCode:       string;
+	currency:          string;
+	accountHolderName: string;
+	billingAddress:    string;
+	taxIdType:         string;  // 'S' SIN, 'N' SSN, 'E' EIN, 'V' VAT, 'O' other
+	taxId:             string;
+	provider:          string;
+	providerAgreement: boolean;
+}
+
+// CountryProfile drives the country dropdown in the bank-info form.
+// Each profile bundles ISO codes + tax-id labelling so the form's
+// hint/placeholder text follows the country selection.
+export interface CountryProfile {
+	code:             string;  // ISO 3166-1 alpha-2
+	label:            string;
+	currency:         string;  // ISO 4217
+	taxIdType:        string;  // matches basis constant_header 'tax_id_type'
+	taxIdLabel:       string;
+	taxIdPlaceholder: string;
+	taxIdHint:        string;
+}
+
+// ── User payment methods ──
+// Consumer-side saved cards/wallets. Mirrors basis user_payment_method
+// one-to-one. Distinct from PaymentMethod (partner-scoped SaaS billing
+// card).
+//
+// PascalCase fields match keel's generic REST CRUD response shape —
+// list and delete go through that path (the table is UserSpecific so
+// the auto-filter scopes reads + owner-locks DELETE). Only set-default
+// has a custom endpoint because it needs atomic multi-row UPDATE.
+
+export interface UserPaymentMethod {
+	Id:           number;
+	UserId?:      number;
+	MethodType:   string;   // matches basis constant_header 'payment_method_type' — card / bank / wallet / apple_pay / google_pay
+	Provider:     string;   // 'stripe', ...
+	LastFour?:    string;
+	Brand?:       string;
+	ExpiryMonth?: number;
+	ExpiryYear?:  number;
+	Currency:     string;
+	IsDefault:    boolean;
+	CreatedAt:    string;
+}

package/src/service/payout.service.ts

@@ -0,0 +1,48 @@
+import { inject, Injectable } from '@angular/core';
+import { HttpClient } from '@angular/common/http';
+import { Observable } from 'rxjs';
+import { RestURL } from './rest_url';
+import {
+  PayoutOnboardingSession,
+  ReusableAccount,
+} from '../model/appdata';
+
+/**
+ * PayoutService — shared API client for keel/payout.
+ *
+ * Mirrors keel/payout/OnboardingService on the frontend: hosted-KYC
+ * launch, status check, and the multi-partner reuse flow that lets a
+ * user share one provider_account_id across more than one
+ * (user, partner) row in user_bank_info.
+ *
+ * Endpoints live under /api/v1/payout/* — paths configurable via
+ * RestURL.payout*URL.
+ */
+@Injectable({ providedIn: 'root' })
+export class PayoutService {
+  private readonly http = inject(HttpClient);
+
+  private url(path: string): string {
+    return RestURL.httpHost + path;
+  }
+
+  /** Launch the hosted-KYC flow. Returns a URL to open + provider-side handle. */
+  startOnboarding(): Observable<PayoutOnboardingSession> {
+    return this.http.post<PayoutOnboardingSession>(this.url(RestURL.payoutOnboardStartURL), {});
+  }
+
+  /** List provider accounts the user already has on OTHER partners. */
+  listReusable(): Observable<{ accounts: ReusableAccount[] }> {
+    return this.http.post<{ accounts: ReusableAccount[] }>(this.url(RestURL.payoutReusableURL), {});
+  }
+
+  /** Copy an existing provider_account_id onto the calling partner's row. */
+  linkReusable(providerAccountId: string): Observable<{ message: string }> {
+    return this.http.post<{ message: string }>(this.url(RestURL.payoutReusableLinkURL), { providerAccountId });
+  }
+
+  /** True when the calling user has a populated provider_account_id on the active partner row. */
+  status(): Observable<{ complete: boolean }> {
+    return this.http.post<{ complete: boolean }>(this.url(RestURL.payoutStatusURL), {});
+  }
+}

package/src/service/rest_url.ts

@@ -31,6 +31,15 @@ export const RestURL = {
   deleteAccountURL:    '/api/user/account',
   pushRegisterURL:     '/api/push/register',
   pushRevokeURL:       '/api/push/revoke',
+  // Payout — keel/payout endpoints.
+  payoutOnboardStartURL: '/api/v1/payout/onboard/start',
+  payoutReusableURL:     '/api/v1/payout/reusable',
+  payoutReusableLinkURL: '/api/v1/payout/reusable/link',
+  payoutStatusURL:       '/api/v1/payout/status',
+  // User payment methods — list/delete go through keel's generic REST
+  // CRUD against the UserSpecific basis table; only set-default has a
+  // custom endpoint (atomic multi-row UPDATE).
+  paymentMethodSetDefaultURL: '/api/v1/payment-methods/set-default',
 };
 
 /** Call this at app startup to set the backend host URL */

package/src/service/user_payment_method.service.ts

@@ -0,0 +1,48 @@
+import { inject, Injectable } from '@angular/core';
+import { HttpClient } from '@angular/common/http';
+import { Observable } from 'rxjs';
+import { RestURL } from './rest_url';
+import { BackendService } from './rest_service';
+import { UserPaymentMethod } from '../model/appdata';
+
+/**
+ * UserPaymentMethodService — consumer-side saved-payment-methods API.
+ *
+ * list and delete go through keel's generic REST CRUD against the
+ * basis user_payment_method table — that table is UserSpecific (FK
+ * column `user_id`), so the auto-filter scopes reads + owner-locks
+ * DELETE without any custom server-side glue. setDefault has a custom
+ * endpoint because it needs an atomic multi-row UPDATE
+ * (`SET is_default = (id = ?) WHERE user_id = session`) that abstract
+ * single-row CRUD can't express.
+ */
+@Injectable({ providedIn: 'root' })
+export class UserPaymentMethodService {
+  private readonly http = inject(HttpClient);
+  private readonly backend = inject(BackendService);
+
+  /**
+   * List the caller's saved payment methods. Returns rows with PascalCase
+   * fields per the generic-CRUD convention; the default row sorts first
+   * server-side (filter ordering is set on rest_api_header).
+   */
+  list(): Observable<UserPaymentMethod[]> {
+    return this.backend.list<UserPaymentMethod>('user_payment_method');
+  }
+
+  /** Delete a saved payment method. user_id is auto-scoped by keel. */
+  delete(id: number): Observable<{ message: string }> {
+    return this.backend.delete('user_payment_method', { Id: String(id) });
+  }
+
+  /**
+   * Mark one row as default; clears every other row in the same call.
+   * Custom endpoint — see service-class doc for the rationale.
+   */
+  setDefault(id: number): Observable<{ message: string }> {
+    return this.http.post<{ message: string }>(
+      RestURL.httpHost + RestURL.paymentMethodSetDefaultURL,
+      { id },
+    );
+  }
+}