@nauticana/sail 1.1.13 → 1.1.14

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.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`.
+> **Compatibility:** sail and keel are versioned in lock-step. The current line is **sail v1.1.x ↔ keel v1.2.x**; the agency components in sail v1.1.14 require keel v1.2.41 (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. `passwordPolicyValidator` + `BaseAuthService.ensurePasswordPolicy()` — validate passwords against keel's policy (via `SailGuiConfig.passwordPolicyUrl`); see Configuration reference.
 
@@ -22,13 +22,14 @@ A shared Angular component library for building CRUD-based admin frontends. Prov
 | **Billing** | `PlanSelectorComponent`, `PriceSelectorComponent`, `CheckoutButtonComponent`, `PaymentMethodsComponent`, `PortalButtonComponent`, `UsageMeterComponent`, `StatusChipComponent`, `TrialBannerComponent`, `SeatSelectorComponent`, `DunningBannerComponent` |
 | **Dashboard** | `DashboardShellComponent`, `DataCardComponent`, `LockedOverlayComponent`, `ActionCenterComponent`, `EntitySelectorComponent`, `VerificationFlowComponent` |
 | **Payout** | `PayoutProviderOnboardingComponent`, `PayoutBankInfoFormComponent` |
+| **Agency** | `AgencyClientsComponent`, `AgencyStatusBannerComponent`, `AgencyAcceptComponent`, `AgencyEarningsSummaryComponent`, `CommissionLedgerComponent`, `AgencyPayoutHistoryComponent`, `AgencyPayoutProfileComponent` |
 | **Payments / SCA** | `UserPaymentMethodsComponent`, `ScaConfirmComponent`, `ScaConfirmer` (port), `SCA_CONFIRMER` (token) |
-| **Services** | `BaseAuthService` (OTP / social / push / deleteAccount / logoutEverywhere / profile: `getProfile`, `updateProfile`, `request`+`confirmEmailChange`, `request`+`confirmPhoneChange`), `BillingService`, `BackendService`, `PayoutService`, `UserPaymentMethodService`, `loadScript()`, `authInterceptor`, `apiResponseInterceptor` |
+| **Services** | `BaseAuthService` (OTP / social / push / deleteAccount / logoutEverywhere / profile: `getProfile`, `updateProfile`, `request`+`confirmEmailChange`, `request`+`confirmPhoneChange`), `BillingService`, `AgencyService`, `BackendService`, `PayoutService`, `UserPaymentMethodService`, `loadScript()`, `authInterceptor`, `apiResponseInterceptor` |
 | **Abstracts** | `BaseTable`, `BaseForm`, `BaseView`, `AbstractEditableView`, `BaseAsync`, `BaseRestService` |
 | **Config** | `SAIL_GUI_CONFIG`, `SailGuiConfig`, `configureRestUrls()` |
 | **Models** | `ApplicationData`, `TableDefinition`, `SiudAction`, `ApplicationMenu`, `ConstantValue`, `UserAccount`, `RestReport`, `ReportParam`, `TrustedDevice`, `PublicPlan`, `PlanPrice`, `PaymentMethod`, `Subscription`, `Invoice`, `CheckoutRequest`/`CheckoutResponse`, `PortalResponse`, `UsageMeter`, `ChargeResult`, `UserPaymentMethod`, `TableAction`, `ReusableAccount`, `PayoutOnboardingSession`, `BankInfoFormValue`, `CountryProfile`, `OtpRequest`/`OtpResponse`, `SignupConsent`, `ConsentState`, `ConsentOption`, `SocialProvider`, `PushPlatform`, 2FA types, etc. |
 | **Decorators** | `@IsSailString()`, `@IsSailNumeric()` (class-validator based) |
-| **Utils** | `titleCase()`, `fromPriceLabel()` |
+| **Utils** | `titleCase()`, `fromPriceLabel()`, `formatMinorCurrency()` |
 
 ## Quick start
 
@@ -590,6 +591,74 @@ A complete screen is the pieces above assembled over `BillingService` — no met
 <!-- invoices: render listInvoices() rows directly -->
 ```
 
+## Agency / reseller UI (v1.1.14)
+
+sail v1.1.14 supplies composable, unstyled agency components over keel v1.2.41.
+The app owns routes, route guards, brand copy, global CSS, and any columns that
+refer to an app-specific managed entity.
+
+`AgencyService` covers profile enrollment, invitation staging/acceptance,
+delegation/revocation, per-client referral/wholesale selection, earnings, and
+payout-profile selection. Its DTOs use the upstream names
+`agency_client_invitation`, `agency_client_delegation`, and
+`agency_client_rate`; there is no client-side rule-schedule model.
+The enrollment method is `enroll()`; downstream `enrollReferral()` calls must
+be renamed when adopting this release.
+
+Compose an agency page from the pieces you need:
+
+```html
+<sail-agency-clients
+  [extraColumns]="clientColumns"
+  [showBillingModelControls]="true" />
+<sail-agency-earnings-summary [earnings]="earnings()" [activeClients]="activeClients()" />
+<sail-commission-ledger [entries]="earnings()?.entries ?? []" />
+<sail-agency-payout-history [payouts]="earnings()?.payouts ?? []" />
+<sail-agency-payout-profile />
+```
+
+`AgencyClientsComponent` renders status values through the shared
+`StatusChipComponent` and backend constant catalogues. It accepts app-specific
+columns rather than assuming the managed entity. Accepted clients begin in
+referral mode; wholesale controls appear only when the profile permits them and
+the app opts in with `showBillingModelControls`.
+
+Load keel's v1.2.40 basis seed so status chips receive these canonical domains:
+
+| Domain | Values |
+|---|---|
+| `agency_client_status` | `S` Staged, `I` Invited, `V` Client, `X` Cancelled |
+| `agency_billing_model` | `R` Referral, `W` Wholesale |
+| `agency_commission_status` | `H` Held, `P` Payable, `R` Reserved, `D` Paid, `O` Offset |
+| `agency_payout_status` | `C` Created, `P` Processing, `D` Paid, `F` Failed, `R` Returned, `V` Reversed, `M` Manual review |
+
+Do not substitute app-local domain names such as `billing_model` or
+`commission_status`; a missing canonical domain deliberately renders the raw
+code so configuration drift remains visible.
+
+`AgencyAcceptComponent` keeps consent explicit and persists an invitation token
+when the authenticated user still needs to create a business partner. Consumers
+handle its navigation outputs and route back after business setup. Other 409
+conflicts, such as an existing delegation or self-delegation, remain on the
+invitation screen as errors instead of entering the business-setup flow. The
+branch uses keel's stable RFC 7807 `code: "agency_no_partner"` (keel v1.2.41),
+not error prose.
+
+The payout-profile component composes the existing provider-onboarding surface
+and only allows a fully onboarded destination returned by keel. Mount it only
+for an approved, non-suspended agency; keel intentionally rejects its GET for a
+pending profile. The ledger and payout-history components show default empty
+messages; pass `[emptyMessage]="''"` when a composed page should omit empty
+regions entirely.
+
+All accounting values are integer minor units. `formatMinorCurrency()` uses the
+currency exponent reported by `Intl.NumberFormat`, so zero- and three-decimal
+currencies render correctly; earnings stay separated by currency rather than
+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)
 
 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nauticana/sail",
-  "version": "1.1.13",
+  "version": "1.1.14",
   "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/agency/agency_accept.html

@@ -0,0 +1,33 @@
+@if (loading()) {
+  <mat-spinner diameter="36" aria-label="Loading invitation"></mat-spinner>
+} @else if (complete()) {
+  <div class="agency-accept__complete" role="status">Agency management has been accepted.</div>
+} @else if (invite(); as invitation) {
+  <section class="agency-accept__invitation">
+    <h1>Agency management invitation</h1>
+    <p>
+      <strong>{{ invitation.agencyName }}</strong> invited
+      <strong>{{ invitation.clientName }}</strong>. Accepting grants management access;
+      ownership remains with the client and the delegation can be revoked.
+    </p>
+    @if (invitation.expired) {
+      <p class="agency-accept__error" role="alert">This invitation has expired.</p>
+    }
+    @if (needsBusiness()) {
+      <p role="status">A business must be set up before management can be delegated.</p>
+      <button matButton="filled" type="button" (click)="requestBusinessSetup()">{{ businessSetupLabel() }}</button>
+    } @else if (authenticated()) {
+      <button matButton="filled" type="button" [disabled]="accepting() || invitation.expired" (click)="accept()">
+        Accept management
+      </button>
+    } @else {
+      <button matButton="filled" type="button" (click)="loginRequested.emit()">{{ loginLabel() }}</button>
+      <button matButton type="button" (click)="registrationRequested.emit()">{{ registerLabel() }}</button>
+    }
+    @if (errorMessage()) {
+      <p class="agency-accept__error" role="alert">{{ errorMessage() }}</p>
+    }
+  </section>
+} @else {
+  <p class="agency-accept__error" role="alert">{{ errorMessage() }}</p>
+}

package/src/component/agency/agency_accept.ts

@@ -0,0 +1,94 @@
+import { ChangeDetectionStrategy, Component, OnInit, inject, input, output, signal } from '@angular/core';
+import { MatButtonModule } from '@angular/material/button';
+import { MatProgressSpinnerModule } from '@angular/material/progress-spinner';
+import { AgencyInvite } from '../../model/agency';
+import { AgencyService } from '../../service/agency.service';
+import { errorCode, errorDetail } from '../../util/errors';
+
+const NO_PARTNER_CODE = 'agency_no_partner';
+
+@Component({
+  selector: 'sail-agency-accept',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [MatButtonModule, MatProgressSpinnerModule],
+  templateUrl: './agency_accept.html',
+  host: { class: 'agency-accept' },
+})
+export class AgencyAcceptComponent implements OnInit {
+  readonly token = input('');
+  readonly authenticated = input(false);
+  readonly tokenStorageKey = input('sail.agencyInvite');
+  readonly loginLabel = input('Log in to accept');
+  readonly registerLabel = input('Create an account');
+  readonly businessSetupLabel = input('Set up your business');
+
+  readonly loginRequested = output<void>();
+  readonly registrationRequested = output<void>();
+  readonly businessSetupRequested = output<string>();
+  readonly accepted = output<AgencyInvite>();
+
+  private readonly agency = inject(AgencyService);
+  private activeToken = '';
+
+  readonly loading = signal(true);
+  readonly accepting = signal(false);
+  readonly invite = signal<AgencyInvite | null>(null);
+  readonly errorMessage = signal('');
+  readonly complete = signal(false);
+  readonly needsBusiness = signal(false);
+
+  ngOnInit(): void {
+    this.activeToken = this.token() || localStorage.getItem(this.tokenStorageKey()) || '';
+    if (!this.activeToken) {
+      this.loading.set(false);
+      this.errorMessage.set('The invitation token is missing.');
+      return;
+    }
+    this.agency.inviteInfo(this.activeToken).subscribe({
+      next: (invite) => {
+        this.invite.set(invite);
+        this.loading.set(false);
+      },
+      error: (error: unknown) => {
+        this.loading.set(false);
+        this.errorMessage.set(errorDetail(error, 'The invitation was not found.'));
+      },
+    });
+  }
+
+  accept(): void {
+    const invite = this.invite();
+    if (!invite || invite.expired || this.accepting()) return;
+    this.accepting.set(true);
+    this.needsBusiness.set(false);
+    this.errorMessage.set('');
+    this.agency.accept(this.activeToken).subscribe({
+      next: () => {
+        localStorage.removeItem(this.tokenStorageKey());
+        this.accepting.set(false);
+        this.complete.set(true);
+        this.accepted.emit(invite);
+      },
+      error: (error: unknown) => {
+        this.accepting.set(false);
+        if (this.statusOf(error) === 409 && errorCode(error) === NO_PARTNER_CODE) {
+          localStorage.setItem(this.tokenStorageKey(), this.activeToken);
+          this.needsBusiness.set(true);
+          return;
+        }
+        this.errorMessage.set(errorDetail(error, 'Could not accept the invitation.'));
+      },
+    });
+  }
+
+  requestBusinessSetup(): void {
+    localStorage.setItem(this.tokenStorageKey(), this.activeToken);
+    this.businessSetupRequested.emit(this.activeToken);
+  }
+
+  private statusOf(error: unknown): number | undefined {
+    return typeof error === 'object' && error !== null && 'status' in error
+      ? Number((error as { status?: unknown }).status)
+      : undefined;
+  }
+}

package/src/component/agency/agency_clients.html

@@ -0,0 +1,97 @@
+@if (loading()) {
+  <mat-spinner diameter="36" aria-label="Loading agency clients"></mat-spinner>
+} @else if (needsEnrollment()) {
+  <section class="agency-clients__enrollment">
+    <h2>{{ enrollmentTitle() }}</h2>
+    <p>{{ enrollmentDescription() }}</p>
+    <button matButton="filled" type="button" (click)="enroll()">{{ enrollmentActionLabel() }}</button>
+  </section>
+} @else {
+  @if (errorMessage()) {
+    <p class="agency-clients__error" role="alert">{{ errorMessage() }}</p>
+  }
+
+  <sail-agency-status-banner [profile]="profile()" />
+
+  <form class="agency-clients__add" [formGroup]="addForm" (ngSubmit)="addClient()">
+    <mat-form-field appearance="outline">
+      <mat-label>Client name</mat-label>
+      <input matInput formControlName="name" required />
+    </mat-form-field>
+    <mat-form-field appearance="outline">
+      <mat-label>Email</mat-label>
+      <input matInput formControlName="email" type="email" />
+    </mat-form-field>
+    <mat-form-field appearance="outline">
+      <mat-label>Website</mat-label>
+      <input matInput formControlName="website" />
+    </mat-form-field>
+    <button matButton="filled" type="submit" [disabled]="addForm.invalid || !canManage()">Add client</button>
+  </form>
+
+  <p class="agency-clients__count">Active clients: {{ activeClients() }}</p>
+
+  @if (clients().length === 0) {
+    <p class="agency-clients__empty">No clients have been staged.</p>
+  } @else {
+    <div class="agency-clients__table-wrap">
+      <table class="agency-clients__table">
+        <thead>
+          <tr>
+            <th>Name</th>
+            <th>Email</th>
+            <th>Website</th>
+            @for (column of extraColumns(); track column.id) {
+              <th>{{ column.caption }}</th>
+            }
+            <th>Status</th>
+            @if (showBillingModelControls()) { <th>Billing model</th> }
+            <th><span class="agency-clients__visually-hidden">Actions</span></th>
+          </tr>
+        </thead>
+        <tbody>
+          @for (client of clients(); track client.id) {
+            <tr>
+              <td>{{ client.name }}</td>
+              <td>{{ client.email }}</td>
+              <td>{{ client.website }}</td>
+              @for (column of extraColumns(); track column.id) {
+                <td>{{ column.value(client) }}</td>
+              }
+              <td>
+                <sail-status-chip domain="agency_client_status" [value]="client.status" />
+                @if (client.expired) { <span class="agency-clients__expired">Expired</span> }
+              </td>
+              @if (showBillingModelControls()) {
+                <td>
+                  @if (client.clientPartnerId) {
+                    <sail-status-chip domain="agency_billing_model" [value]="client.billingModel ?? ''" />
+                    <button matButton type="button" [disabled]="!canManage() || client.billingModel === 'R'"
+                            (click)="setBillingModel(client, 'R')">Referral</button>
+                    @if (profile()?.wholesaleAllowed) {
+                      <button matButton type="button" [disabled]="!canManage() || client.billingModel === 'W'"
+                              (click)="setBillingModel(client, 'W')">Wholesale</button>
+                    }
+                  }
+                </td>
+              }
+              <td>
+                @if (client.status === 'S' || client.status === 'I') {
+                  <button matButton type="button" [disabled]="!canManage()" (click)="invite(client)">
+                    {{ client.status === 'S' ? 'Invite' : 'Re-invite' }}
+                  </button>
+                  <button matButton type="button" [disabled]="!canManage()" (click)="cancel(client)">Cancel</button>
+                }
+                @if (inviteLinks()[client.id]; as link) {
+                  <button matIconButton type="button" aria-label="Copy invitation link" (click)="copy(link)">
+                    <mat-icon>content_copy</mat-icon>
+                  </button>
+                }
+              </td>
+            </tr>
+          }
+        </tbody>
+      </table>
+    </div>
+  }
+}

package/src/component/agency/agency_clients.ts

@@ -0,0 +1,182 @@
+import { ChangeDetectionStrategy, Component, OnInit, computed, inject, input, output, signal } from '@angular/core';
+import { FormBuilder, ReactiveFormsModule, Validators } from '@angular/forms';
+import { MatButtonModule } from '@angular/material/button';
+import { MatFormFieldModule } from '@angular/material/form-field';
+import { MatIconModule } from '@angular/material/icon';
+import { MatInputModule } from '@angular/material/input';
+import { MatProgressSpinnerModule } from '@angular/material/progress-spinner';
+import { MatSnackBar } from '@angular/material/snack-bar';
+import { AgencyClient, AgencyClientColumn, AgencyProfile } from '../../model/agency';
+import { AgencyService } from '../../service/agency.service';
+import { errorDetail } from '../../util/errors';
+import { StatusChipComponent } from '../billing/status_chip';
+import { AgencyStatusBannerComponent } from './agency_status_banner';
+
+@Component({
+  selector: 'sail-agency-clients',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [
+    ReactiveFormsModule,
+    MatButtonModule,
+    MatFormFieldModule,
+    MatIconModule,
+    MatInputModule,
+    MatProgressSpinnerModule,
+    StatusChipComponent,
+    AgencyStatusBannerComponent,
+  ],
+  templateUrl: './agency_clients.html',
+  host: { class: 'agency-clients' },
+})
+export class AgencyClientsComponent implements OnInit {
+  readonly extraColumns = input<AgencyClientColumn[]>([]);
+  readonly enrollmentTitle = input('Agency enrollment');
+  readonly enrollmentDescription = input('Apply to manage clients and receive referral commission.');
+  readonly enrollmentActionLabel = input('Apply');
+  readonly showBillingModelControls = input(false);
+
+  readonly enrolled = output<AgencyProfile>();
+  readonly clientAdded = output<AgencyClient>();
+  readonly invited = output<{ client: AgencyClient; inviteLink: string }>();
+  readonly cancelled = output<AgencyClient>();
+  readonly billingModelChanged = output<{ client: AgencyClient; billingModel: 'R' | 'W' }>();
+
+  private readonly agency = inject(AgencyService);
+  private readonly snack = inject(MatSnackBar);
+  private readonly formBuilder = inject(FormBuilder);
+
+  readonly loading = signal(true);
+  readonly errorMessage = signal('');
+  readonly needsEnrollment = signal(false);
+  readonly profile = signal<AgencyProfile | null>(null);
+  readonly clients = signal<AgencyClient[]>([]);
+  readonly activeClients = signal(0);
+  readonly inviteLinks = signal<Record<number, string>>({});
+  readonly canManage = computed(() => {
+    const profile = this.profile();
+    return profile !== null && Boolean(profile.approvedAt) && !profile.suspended;
+  });
+
+  readonly addForm = this.formBuilder.nonNullable.group({
+    name: ['', Validators.required],
+    email: ['', Validators.email],
+    website: [''],
+  });
+
+  ngOnInit(): void {
+    this.reload();
+  }
+
+  reload(afterProfileLoad?: (profile: AgencyProfile) => void): void {
+    this.loading.set(true);
+    this.errorMessage.set('');
+    this.agency.profile().subscribe({
+      next: ({ profile }) => {
+        this.profile.set(profile);
+        this.needsEnrollment.set(profile === null);
+        if (profile === null) {
+          this.clients.set([]);
+          this.activeClients.set(0);
+          this.loading.set(false);
+          return;
+        }
+        afterProfileLoad?.(profile);
+        this.loadClients();
+      },
+      error: (error: unknown) => {
+        this.loading.set(false);
+        this.errorMessage.set(errorDetail(error, 'Could not load the agency profile.'));
+      },
+    });
+  }
+
+  enroll(): void {
+    this.loading.set(true);
+    this.errorMessage.set('');
+    this.agency.enroll().subscribe({
+      next: () => this.reload((profile) => this.enrolled.emit(profile)),
+      error: (error: unknown) => {
+        this.loading.set(false);
+        this.errorMessage.set(errorDetail(error, 'Agency enrollment failed.'));
+      },
+    });
+  }
+
+  addClient(): void {
+    if (this.addForm.invalid || !this.canManage()) return;
+    const value = this.addForm.getRawValue();
+    this.agency.addClients([value]).subscribe({
+      next: () => {
+        this.addForm.reset();
+        this.loadClients((client) => this.clientAdded.emit(client));
+      },
+      error: (error: unknown) => this.snack.open(errorDetail(error, 'Could not add the client.'), 'Dismiss'),
+    });
+  }
+
+  invite(client: AgencyClient): void {
+    if (!this.canManage()) return;
+    this.agency.invite(client.id).subscribe({
+      next: ({ inviteLink }) => {
+        this.inviteLinks.update((links) => ({ ...links, [client.id]: inviteLink }));
+        this.invited.emit({ client, inviteLink });
+        this.copy(inviteLink);
+        this.loadClients();
+      },
+      error: (error: unknown) => this.snack.open(errorDetail(error, 'Could not create the invitation.'), 'Dismiss'),
+    });
+  }
+
+  cancel(client: AgencyClient): void {
+    if (!this.canManage()) return;
+    this.agency.cancel(client.id).subscribe({
+      next: () => {
+        this.cancelled.emit(client);
+        this.loadClients();
+      },
+      error: (error: unknown) => this.snack.open(errorDetail(error, 'Could not cancel the client.'), 'Dismiss'),
+    });
+  }
+
+  setBillingModel(client: AgencyClient, billingModel: 'R' | 'W'): void {
+    if (!this.canManage() || !client.clientPartnerId) return;
+    this.agency.setBillingModel(client.clientPartnerId, billingModel).subscribe({
+      next: () => {
+        this.billingModelChanged.emit({ client, billingModel });
+        this.loadClients();
+      },
+      error: (error: unknown) => this.snack.open(errorDetail(error, 'Could not change the billing model.'), 'Dismiss'),
+    });
+  }
+
+  copy(link: string): void {
+    if (!navigator.clipboard) {
+      this.snack.open(link, 'Dismiss');
+      return;
+    }
+    navigator.clipboard.writeText(link).then(
+      () => this.snack.open('Invitation link copied.', undefined, { duration: 2500 }),
+      () => this.snack.open(link, 'Dismiss'),
+    );
+  }
+
+  private loadClients(afterLoad?: (client: AgencyClient) => void): void {
+    this.agency.clients().subscribe({
+      next: ({ items, activeClients }) => {
+        const previousIDs = new Set(this.clients().map((client) => client.id));
+        const clients = items ?? [];
+        this.clients.set(clients);
+        this.activeClients.set(activeClients ?? 0);
+        this.loading.set(false);
+        if (afterLoad) {
+          const added = clients.find((client) => !previousIDs.has(client.id));
+          if (added) afterLoad(added);
+        }
+      },
+      error: (error: unknown) => {
+        this.loading.set(false);
+        this.errorMessage.set(errorDetail(error, 'Could not load agency clients.'));
+      },
+    });
+  }
+}

package/src/component/agency/agency_earnings_summary.html

@@ -0,0 +1,24 @@
+@if (earnings(); as value) {
+  <div class="agency-earnings-summary__metric">
+    <span class="agency-earnings-summary__label">Active clients</span>
+    <span class="agency-earnings-summary__value">{{ activeClients() }}</span>
+  </div>
+  <div class="agency-earnings-summary__metric">
+    <span class="agency-earnings-summary__label">Paying clients</span>
+    <span class="agency-earnings-summary__value">{{ value.payingClients }}</span>
+  </div>
+  @for (balance of value.balances; track balance.currency) {
+    <div class="agency-earnings-summary__metric" [attr.data-currency]="balance.currency">
+      <span class="agency-earnings-summary__label">Held ({{ balance.currency }})</span>
+      <span class="agency-earnings-summary__value">{{ format(balance.heldMinor, balance.currency) }}</span>
+    </div>
+    <div class="agency-earnings-summary__metric" [attr.data-currency]="balance.currency">
+      <span class="agency-earnings-summary__label">Due ({{ balance.currency }})</span>
+      <span class="agency-earnings-summary__value">{{ format(balance.dueMinor, balance.currency) }}</span>
+    </div>
+    <div class="agency-earnings-summary__metric" [attr.data-currency]="balance.currency">
+      <span class="agency-earnings-summary__label">Paid ({{ balance.currency }})</span>
+      <span class="agency-earnings-summary__value">{{ format(balance.paidMinor, balance.currency) }}</span>
+    </div>
+  }
+}

package/src/component/agency/agency_earnings_summary.ts

@@ -0,0 +1,15 @@
+import { ChangeDetectionStrategy, Component, input } from '@angular/core';
+import { AgencyEarnings } from '../../model/agency';
+import { formatMinorCurrency } from '../../util/money';
+
+@Component({
+  selector: 'sail-agency-earnings-summary',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  templateUrl: './agency_earnings_summary.html',
+  host: { class: 'agency-earnings-summary' },
+})
+export class AgencyEarningsSummaryComponent {
+  readonly earnings = input<AgencyEarnings | null>(null);
+  readonly activeClients = input(0);
+  readonly format = formatMinorCurrency;
+}

package/src/component/agency/agency_payout_history.html

@@ -0,0 +1,19 @@
+@if (payouts().length > 0) {
+  <div class="agency-payout-history__table-wrap">
+    <table class="agency-payout-history__table">
+      <thead><tr><th>Cycle</th><th>Amount</th><th>Status</th><th>Paid</th></tr></thead>
+      <tbody>
+        @for (payout of payouts(); track payout.id) {
+          <tr>
+            <td>{{ payout.cutoffAt | date: 'yyyy-MM':'UTC' }}</td>
+            <td>{{ format(payout.amountMinor, payout.currency) }}</td>
+            <td><sail-status-chip domain="agency_payout_status" [value]="payout.status" /></td>
+            <td>{{ payout.paidAt ? (payout.paidAt | date: 'mediumDate':'UTC') : '' }}</td>
+          </tr>
+        }
+      </tbody>
+    </table>
+  </div>
+} @else if (emptyMessage()) {
+  <p class="agency-payout-history__empty">{{ emptyMessage() }}</p>
+}

package/src/component/agency/agency_payout_history.ts

@@ -0,0 +1,18 @@
+import { DatePipe } from '@angular/common';
+import { ChangeDetectionStrategy, Component, input } from '@angular/core';
+import { AgencyPayout } from '../../model/agency';
+import { formatMinorCurrency } from '../../util/money';
+import { StatusChipComponent } from '../billing/status_chip';
+
+@Component({
+  selector: 'sail-agency-payout-history',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [DatePipe, StatusChipComponent],
+  templateUrl: './agency_payout_history.html',
+  host: { class: 'agency-payout-history' },
+})
+export class AgencyPayoutHistoryComponent {
+  readonly payouts = input<AgencyPayout[]>([]);
+  readonly emptyMessage = input('No agency payouts yet.');
+  readonly format = formatMinorCurrency;
+}

package/src/component/agency/agency_payout_profile.html

@@ -0,0 +1,49 @@
+@if (loading()) {
+  <mat-spinner diameter="36" aria-label="Loading payout profile"></mat-spinner>
+} @else {
+  <section class="agency-payout-profile__selection">
+    <h2>Payout destination</h2>
+    @if (profile(); as current) {
+      <p class="agency-payout-profile__current" role="status">
+        Current: {{ current.countryCode }} / {{ current.currency }} ({{ current.provider }})
+      </p>
+    }
+
+    @if (destinations().length > 0) {
+      <mat-form-field appearance="outline">
+        <mat-label>Destination</mat-label>
+        <mat-select [value]="selectedDestinationID()" (selectionChange)="choose($event)">
+          @for (destination of destinations(); track destination.userBankInfoId) {
+            <mat-option [value]="destination.userBankInfoId">
+              {{ destination.countryCode }} / {{ destination.currency }} ({{ destination.provider }})
+            </mat-option>
+          }
+        </mat-select>
+      </mat-form-field>
+      <button matButton="filled" type="button" [disabled]="!selectedDestinationID() || saving()" (click)="save()">
+        Use for agency payouts
+      </button>
+    } @else if (!onboarding()) {
+      <p>No fully onboarded payout destination is available for this business.</p>
+    }
+
+    <button matButton type="button" [disabled]="saving()" (click)="onboarding.set(!onboarding())">
+      {{ onboarding() ? 'Hide account setup' : 'Set up a payout account' }}
+    </button>
+
+    @if (pending()) {
+      <p role="status">The provider is waiting for account confirmation.</p>
+    }
+    @if (errorMessage()) {
+      <p class="agency-payout-profile__error" role="alert">{{ errorMessage() }}</p>
+    }
+  </section>
+
+  @if (onboarding()) {
+    <sail-payout-provider-onboarding
+      [showBack]="false"
+      (linked)="onboardingComplete()"
+      (pending)="pending.set(true)"
+      (skipped)="onboarding.set(false)" />
+  }
+}

package/src/component/agency/agency_payout_profile.ts

@@ -0,0 +1,101 @@
+import { ChangeDetectionStrategy, Component, OnInit, inject, output, signal } from '@angular/core';
+import { MatButtonModule } from '@angular/material/button';
+import { MatFormFieldModule } from '@angular/material/form-field';
+import { MatProgressSpinnerModule } from '@angular/material/progress-spinner';
+import { MatSelectChange, MatSelectModule } from '@angular/material/select';
+import { AgencyPayoutDestination, AgencyPayoutProfile } from '../../model/agency';
+import { AgencyService } from '../../service/agency.service';
+import { errorDetail } from '../../util/errors';
+import { PayoutProviderOnboardingComponent } from '../payout/provider_onboarding';
+
+/**
+ * Self-service selection of the fully onboarded destination that receives
+ * agency commission payouts. Routes and page composition remain app-owned.
+ */
+@Component({
+  selector: 'sail-agency-payout-profile',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [
+    MatButtonModule,
+    MatFormFieldModule,
+    MatProgressSpinnerModule,
+    MatSelectModule,
+    PayoutProviderOnboardingComponent,
+  ],
+  templateUrl: './agency_payout_profile.html',
+  host: { class: 'agency-payout-profile' },
+})
+export class AgencyPayoutProfileComponent implements OnInit {
+  readonly selected = output<AgencyPayoutProfile>();
+
+  private readonly agency = inject(AgencyService);
+
+  readonly loading = signal(true);
+  readonly saving = signal(false);
+  readonly onboarding = signal(false);
+  readonly pending = signal(false);
+  readonly errorMessage = signal('');
+  readonly profile = signal<AgencyPayoutProfile | null>(null);
+  readonly destinations = signal<AgencyPayoutDestination[]>([]);
+  readonly selectedDestinationID = signal<number | null>(null);
+
+  ngOnInit(): void {
+    this.reload();
+  }
+
+  reload(): void {
+    this.loading.set(true);
+    this.errorMessage.set('');
+    this.agency.payoutProfile().subscribe({
+      next: ({ profile, destinations }) => {
+        const available = destinations ?? [];
+        this.profile.set(profile);
+        this.destinations.set(available);
+        this.selectedDestinationID.set(
+          available.some((item) => item.userBankInfoId === profile?.userBankInfoId)
+            ? profile!.userBankInfoId
+            : available[0]?.userBankInfoId ?? null,
+        );
+        this.loading.set(false);
+      },
+      error: (error: unknown) => {
+        this.loading.set(false);
+        this.errorMessage.set(errorDetail(error, 'Could not load the payout profile.'));
+      },
+    });
+  }
+
+  choose(event: MatSelectChange): void {
+    this.selectedDestinationID.set(Number(event.value));
+  }
+
+  save(): void {
+    const destinationID = this.selectedDestinationID();
+    if (!destinationID || this.saving()) return;
+    this.saving.set(true);
+    this.errorMessage.set('');
+    this.agency.setPayoutProfile(destinationID).subscribe({
+      next: () => {
+        this.saving.set(false);
+        this.agency.payoutProfile().subscribe({
+          next: ({ profile, destinations }) => {
+            this.profile.set(profile);
+            this.destinations.set(destinations ?? []);
+            if (profile) this.selected.emit(profile);
+          },
+          error: (error: unknown) => this.errorMessage.set(errorDetail(error, 'The destination was saved, but its status could not be refreshed.')),
+        });
+      },
+      error: (error: unknown) => {
+        this.saving.set(false);
+        this.errorMessage.set(errorDetail(error, 'Could not select the payout destination.'));
+      },
+    });
+  }
+
+  onboardingComplete(): void {
+    this.onboarding.set(false);
+    this.pending.set(false);
+    this.reload();
+  }
+}

package/src/component/agency/agency_status_banner.html

@@ -0,0 +1,9 @@
+@if (pending()) {
+  <div class="agency-status-banner__notice" data-agency-status="pending" role="status">
+    {{ pendingMessage() }}
+  </div>
+} @else if (suspended()) {
+  <div class="agency-status-banner__notice" data-agency-status="suspended" role="alert">
+    {{ suspendedMessage() }}
+  </div>
+}

package/src/component/agency/agency_status_banner.ts

@@ -0,0 +1,24 @@
+import { ChangeDetectionStrategy, Component, computed, input } from '@angular/core';
+import { AgencyProfile } from '../../model/agency';
+
+@Component({
+  selector: 'sail-agency-status-banner',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  templateUrl: './agency_status_banner.html',
+  host: { class: 'agency-status-banner' },
+})
+export class AgencyStatusBannerComponent {
+  readonly profile = input<AgencyProfile | null>(null);
+  readonly pendingMessage = input('Agency approval is pending. Client management is read-only until approval.');
+  readonly suspendedMessage = input('Agency access is suspended. New invitations and earnings are paused.');
+
+  readonly pending = computed(() => {
+    const profile = this.profile();
+    return profile !== null && !profile.approvedAt && !profile.suspended;
+  });
+  readonly suspended = computed(() => this.profile()?.suspended === true);
+  readonly canManage = computed(() => {
+    const profile = this.profile();
+    return profile !== null && Boolean(profile.approvedAt) && !profile.suspended;
+  });
+}

package/src/component/agency/commission_ledger.html

@@ -0,0 +1,19 @@
+@if (entries().length > 0) {
+  <div class="commission-ledger__table-wrap">
+    <table class="commission-ledger__table">
+      <thead><tr><th>Client</th><th>Service period</th><th>Amount</th><th>Status</th></tr></thead>
+      <tbody>
+        @for (entry of entries(); track entry.id) {
+          <tr [class.commission-ledger__reversal]="entry.entryType === 'R'">
+            <td>{{ entry.clientName }}</td>
+            <td>{{ entry.periodStart | date: 'yyyy-MM-dd':'UTC' }} – {{ entry.periodEnd | date: 'yyyy-MM-dd':'UTC' }}</td>
+            <td>{{ format(entry.amountMinor, entry.currency) }}</td>
+            <td><sail-status-chip domain="agency_commission_status" [value]="entry.status" /></td>
+          </tr>
+        }
+      </tbody>
+    </table>
+  </div>
+} @else if (emptyMessage()) {
+  <p class="commission-ledger__empty">{{ emptyMessage() }}</p>
+}

package/src/component/agency/commission_ledger.ts

@@ -0,0 +1,18 @@
+import { DatePipe } from '@angular/common';
+import { ChangeDetectionStrategy, Component, input } from '@angular/core';
+import { AgencyEarningEntry } from '../../model/agency';
+import { formatMinorCurrency } from '../../util/money';
+import { StatusChipComponent } from '../billing/status_chip';
+
+@Component({
+  selector: 'sail-commission-ledger',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [DatePipe, StatusChipComponent],
+  templateUrl: './commission_ledger.html',
+  host: { class: 'commission-ledger' },
+})
+export class CommissionLedgerComponent {
+  readonly entries = input<AgencyEarningEntry[]>([]);
+  readonly emptyMessage = input('No commission activity yet.');
+  readonly format = formatMinorCurrency;
+}

package/src/index.ts

@@ -4,6 +4,7 @@ export * from './model/auth';
 export * from './model/common';
 export * from './model/dashboard';
 export * from './model/oauth_connection';
+export * from './model/agency';
 export * from './model/decorator';
 export * from './component/abstract/base_table';
 export * from './component/dashboard/dashboard_shell';
@@ -53,12 +54,20 @@ export * from './component/billing/seat_selector';
 export * from './component/billing/dunning_banner';
 export * from './component/payout/provider_onboarding';
 export * from './component/payout/bank_info_form';
+export * from './component/agency/agency_status_banner';
+export * from './component/agency/agency_clients';
+export * from './component/agency/agency_accept';
+export * from './component/agency/agency_earnings_summary';
+export * from './component/agency/commission_ledger';
+export * from './component/agency/agency_payout_history';
+export * from './component/agency/agency_payout_profile';
 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/agency.service';
 export * from './service/oauth_connection.service';
 export * from './service/user_payment_method.service';
 export * from './service/script_loader';

package/src/model/agency.ts

@@ -0,0 +1,109 @@
+export interface AgencyProfile {
+  agencyPartnerId: number;
+  wholesaleAllowed: boolean;
+  defaultCommissionRateBp?: number;
+  approvedAt?: string;
+  suspended: boolean;
+}
+
+export interface AgencyClientInput {
+  name: string;
+  email?: string;
+  website?: string;
+}
+
+export interface AgencyClient {
+  id: number;
+  name: string;
+  email?: string;
+  website?: string;
+  status: string;
+  clientPartnerId?: number;
+  acceptedBy?: number;
+  invitedAt?: string;
+  acceptedAt?: string;
+  expired?: boolean;
+  billingModel?: string;
+}
+
+export interface AgencyInvite {
+  invitationId: number;
+  agencyName: string;
+  clientName: string;
+  status: string;
+  expired?: boolean;
+}
+
+export interface AgencyDelegation {
+  id: number;
+  clientPartnerId: number;
+  clientName: string;
+  agencyPartnerId: number;
+  agencyName: string;
+  billingModel?: string;
+  grantedAt: string;
+}
+
+export interface AgencyEarningsBalance {
+  currency: string;
+  heldMinor: number;
+  dueMinor: number;
+  paidMinor: number;
+}
+
+export interface AgencyEarningEntry {
+  id: number;
+  clientName: string;
+  periodStart: string;
+  periodEnd: string;
+  amountMinor: number;
+  currency: string;
+  entryType: string;
+  status: string;
+  earnedAt: string;
+}
+
+export interface AgencyPayout {
+  id: number;
+  amountMinor: number;
+  currency: string;
+  status: string;
+  cutoffAt: string;
+  paidAt?: string;
+}
+
+export interface AgencyPayoutProfile {
+  agencyPartnerId: number;
+  userBankInfoId: number;
+  countryCode: string;
+  currency: string;
+  provider: string;
+  providerAccountId: string;
+  status: string;
+}
+
+export interface AgencyPayoutDestination {
+  userBankInfoId: number;
+  countryCode: string;
+  currency: string;
+  provider: string;
+  providerAccountId: string;
+}
+
+export interface AgencyPayoutProfileOptions {
+  profile: AgencyPayoutProfile | null;
+  destinations: AgencyPayoutDestination[];
+}
+
+export interface AgencyEarnings {
+  balances: AgencyEarningsBalance[];
+  entries: AgencyEarningEntry[];
+  payouts: AgencyPayout[];
+  payingClients: number;
+}
+
+export interface AgencyClientColumn {
+  id: string;
+  caption: string;
+  value: (client: AgencyClient) => string;
+}

package/src/service/agency.service.ts

@@ -0,0 +1,76 @@
+import { Injectable } from '@angular/core';
+import { Observable } from 'rxjs';
+import {
+  AgencyClient,
+  AgencyClientInput,
+  AgencyDelegation,
+  AgencyEarnings,
+  AgencyInvite,
+  AgencyPayoutProfileOptions,
+  AgencyProfile,
+} from '../model/agency';
+import { BaseRestService } from './base_rest.service';
+import { RestURL } from './rest_url';
+
+/** Thin REST client for keel/agency. */
+@Injectable({ providedIn: 'root' })
+export class AgencyService extends BaseRestService {
+  enroll(): Observable<{ message: string }> {
+    return this.http.post<{ message: string }>(this.url(RestURL.agencyEnrollURL), {});
+  }
+
+  profile(): Observable<{ profile: AgencyProfile | null }> {
+    return this.http.get<{ profile: AgencyProfile | null }>(this.url(RestURL.agencyProfileURL));
+  }
+
+  clients(): Observable<{ items: AgencyClient[]; activeClients: number }> {
+    return this.http.get<{ items: AgencyClient[]; activeClients: number }>(this.url(RestURL.agencyClientsURL));
+  }
+
+  addClients(clients: AgencyClientInput[]): Observable<{ added: number }> {
+    return this.http.post<{ added: number }>(this.url(RestURL.agencyClientsURL), { clients });
+  }
+
+  invite(invitationId: number): Observable<{ inviteLink: string }> {
+    return this.http.post<{ inviteLink: string }>(this.url(RestURL.agencyInviteClientURL), { invitationId });
+  }
+
+  cancel(invitationId: number): Observable<{ status: string }> {
+    return this.http.post<{ status: string }>(this.url(RestURL.agencyCancelClientURL), { invitationId });
+  }
+
+  setBillingModel(clientPartnerId: number, billingModel: 'R' | 'W'): Observable<{ billingModel: string }> {
+    return this.http.post<{ billingModel: string }>(this.url(RestURL.agencyBillingModelURL), {
+      clientPartnerId,
+      billingModel,
+    });
+  }
+
+  earnings(): Observable<AgencyEarnings> {
+    return this.http.get<AgencyEarnings>(this.url(RestURL.agencyEarningsURL));
+  }
+
+  payoutProfile(): Observable<AgencyPayoutProfileOptions> {
+    return this.http.get<AgencyPayoutProfileOptions>(this.url(RestURL.agencyPayoutProfileURL));
+  }
+
+  setPayoutProfile(userBankInfoId: number): Observable<{ status: string }> {
+    return this.http.post<{ status: string }>(this.url(RestURL.agencyPayoutProfileURL), { userBankInfoId });
+  }
+
+  inviteInfo(token: string): Observable<AgencyInvite> {
+    return this.http.get<AgencyInvite>(this.url(RestURL.agencyInviteInfoURL), { params: { token } });
+  }
+
+  accept(token: string): Observable<{ status: string }> {
+    return this.http.post<{ status: string }>(this.url(RestURL.agencyAcceptInviteURL), { token });
+  }
+
+  delegation(): Observable<{ delegation: AgencyDelegation | null }> {
+    return this.http.get<{ delegation: AgencyDelegation | null }>(this.url(RestURL.agencyDelegationURL));
+  }
+
+  revokeDelegation(clientPartnerId = 0): Observable<{ status: string }> {
+    return this.http.post<{ status: string }>(this.url(RestURL.agencyRevokeDelegationURL), { clientPartnerId });
+  }
+}

package/src/service/rest_service.ts

@@ -11,6 +11,7 @@ export interface ProblemDetail {
     title?: string;
     detail?: string;
     status?: number;
+    code?: string;
     [key: string]: unknown;
 }
 

package/src/service/rest_url.ts

@@ -55,6 +55,20 @@ export const RestURL = {
   payoutStatusURL:       '/api/v1/payout/status',
   payoutBankReplaceURL:  '/api/v1/payout/bank/replace',
   payoutBeneficiaryURL:  '/api/v1/payout/beneficiary/register',
+  // Agency — keel/agency endpoints. The authenticated paths follow the same
+  // conventional /api/v1 mount as payout; inviteInfo is intentionally public.
+  agencyEnrollURL:           '/api/v1/agency/enroll',
+  agencyProfileURL:          '/api/v1/agency/profile',
+  agencyClientsURL:          '/api/v1/agency/clients',
+  agencyInviteClientURL:     '/api/v1/agency/clients/invite',
+  agencyCancelClientURL:     '/api/v1/agency/clients/cancel',
+  agencyBillingModelURL:     '/api/v1/agency/billing-model',
+  agencyEarningsURL:         '/api/v1/agency/earnings',
+  agencyPayoutProfileURL:    '/api/v1/agency/payout-profile',
+  agencyInviteInfoURL:       '/public/agency/invite',
+  agencyAcceptInviteURL:     '/api/v1/agency/invite/accept',
+  agencyDelegationURL:       '/api/v1/agency/delegation',
+  agencyRevokeDelegationURL: '/api/v1/agency/delegation/revoke',
   // User payment methods — list/delete go through keel's generic REST
   // CRUD against the UserSpecific basis table; set-default is a
   // TableAction (basis table_action row), mounted at the conventional

package/src/util/errors.ts

@@ -1,20 +1,37 @@
-import { HttpErrorResponse } from '@angular/common/http';
-import { SailApiError } from '../service/rest_service';
+type ProblemShape = { title?: unknown; detail?: unknown; message?: unknown; code?: unknown };
+
+// Structural extraction, not instanceof: bundling can produce two class
+// identities for HttpErrorResponse (see api-response.interceptor.ts), so match
+// by shape — SailApiError carries `problem`, an HTTP error a numeric `status`
+// plus an `error` body.
+function problemOf(err: unknown): ProblemShape | undefined {
+  if (!err || typeof err !== 'object') return undefined;
+  const e = err as { problem?: unknown; status?: unknown; error?: unknown };
+  const body = e.problem ?? (typeof e.status === 'number' && 'error' in e ? e.error : undefined);
+  return body && typeof body === 'object' ? (body as ProblemShape) : undefined;
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === 'string' && value ? value : undefined;
+}
 
 /**
  * Human-readable message from any sail error shape — SailApiError (BackendService),
  * raw HttpErrorResponse (direct HttpClient calls), or plain Error.
  */
 export function errorDetail(err: unknown, fallback: string): string {
-  if (err instanceof SailApiError) {
-    return err.problem?.detail ?? err.problem?.title ?? err.message ?? fallback;
-  }
-  if (err instanceof HttpErrorResponse) {
-    const body = err.error as { detail?: string; message?: string } | null;
-    return body?.detail ?? body?.message ?? fallback;
+  const problem = problemOf(err);
+  if (problem) {
+    const message = asString(problem.detail) ?? asString(problem.title) ?? asString(problem.message);
+    if (message) return message;
   }
   if (err instanceof Error && err.message) {
     return err.message;
   }
   return fallback;
 }
+
+/** Stable machine-readable discriminator from a keel RFC 7807 response. */
+export function errorCode(err: unknown): string | undefined {
+  return asString(problemOf(err)?.code);
+}

package/src/util/money.ts

@@ -13,6 +13,21 @@ export function formatCurrency(amount: number, currency: string): string {
   }
 }
 
+/**
+ * Format an integer minor-unit amount using the currency's exponent reported
+ * by Intl (JPY 0, USD 2, BHD 3, ...). No hardcoded /100 assumption.
+ */
+export function formatMinorCurrency(minor: number, currency: string): string {
+  const code = currency.trim().toUpperCase();
+  try {
+    const formatter = new Intl.NumberFormat(undefined, { style: 'currency', currency: code });
+    const exponent = formatter.resolvedOptions().maximumFractionDigits ?? 2;
+    return formatter.format(minor / 10 ** exponent);
+  } catch {
+    return `${minor} ${code}`;
+  }
+}
+
 /** PERIOD_TYPE code vocabulary — the single source for cycle labels/durations. */
 export const PERIOD_TYPE_INFO: Record<string, { label: string; noun: string; suffix: string; months: number }> = {
   D: { label: 'Daily',     noun: 'day',     suffix: '/day', months: 1 / 30 },