@nauticana/sail 1.1.25 → 1.1.27

package/README.md

@@ -24,11 +24,12 @@ A shared Angular component library for building CRUD-based admin frontends. Prov
 | **Payout** | `PayoutProviderOnboardingComponent`, `PayoutBankInfoFormComponent` |
 | **Agency** | `AgencyClientsComponent`, `AgencyStatusBannerComponent`, `AgencyAcceptComponent`, `AgencyEarningsSummaryComponent`, `CommissionLedgerComponent`, `AgencyPayoutHistoryComponent`, `AgencyPayoutProfileComponent` |
 | **Notifications** | `NotificationCenterComponent`, `NotificationInboxService` |
+| **Documents** | `DocumentUploadComponent`, `PartnerDocumentsComponent`, `DocumentReviewQueueComponent`, `PartnerDocumentService` |
 | **Payments / SCA** | `UserPaymentMethodsComponent`, `ScaConfirmComponent`, `ScaConfirmer` (port), `SCA_CONFIRMER` (token) |
-| **Services** | `BaseAuthService` (OTP / social / push / deleteAccount / logoutEverywhere / profile: `getProfile`, `updateProfile`, `request`+`confirmEmailChange`, `request`+`confirmPhoneChange`), `BillingService`, `AgencyService`, `BackendService`, `PayoutService`, `UserPaymentMethodService`, `NotificationInboxService`, `loadScript()`, `authInterceptor`, `apiResponseInterceptor` |
+| **Services** | `BaseAuthService` (OTP / social / push / deleteAccount / logoutEverywhere / profile: `getProfile`, `updateProfile`, `request`+`confirmEmailChange`, `request`+`confirmPhoneChange`), `BillingService`, `AgencyService`, `BackendService`, `PayoutService`, `UserPaymentMethodService`, `PartnerDocumentService`, `NotificationInboxService`, `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`, `TableActionParameter`, `ReusableAccount`, `PayoutOnboardingSession`, `BankInfoFormValue`, `CountryProfile`, `OtpRequest`/`OtpResponse`, `SignupConsent`, `ConsentState`, `ConsentOption`, `SocialProvider`, `PushPlatform`, `InboxMessage`/`InboxPage`, 2FA types, etc. |
+| **Models** | `ApplicationData`, `TableDefinition`, `SiudAction`, `ApplicationMenu`, `ConstantValue`, `UserAccount`, `RestReport`, `ReportParam`, `TrustedDevice`, `PublicPlan`, `PlanPrice`, `PaymentMethod`, `Subscription`, `Invoice`, `CheckoutRequest`/`CheckoutResponse`, `PortalResponse`, `UsageMeter`, `ChargeResult`, `UserPaymentMethod`, `TableAction`, `TableActionParameter`, `ReusableAccount`, `PayoutOnboardingSession`, `BankInfoFormValue`, `CountryProfile`, `OtpRequest`/`OtpResponse`, `SignupConsent`, `ConsentState`, `ConsentOption`, `SocialProvider`, `PushPlatform`, `InboxMessage`/`InboxPage`, `PartnerDocument`/`DocumentUploadRequest`, 2FA types, etc. |
 | **Decorators** | `@IsSailString()`, `@IsSailNumeric()` (class-validator based) |
 | **Utils** | `titleCase()`, `fromPriceLabel()`, `formatMinorCurrency()` |
 
@@ -269,7 +270,7 @@ this.labels.loadLabels('ride_type').subscribe(() => {
 });
 ```
 
-Concurrent loads share one application-data subscription, completed domains stay cached, and application-data failures can be retried. Missing values fall back to the raw key.
+Concurrent loads share one application-data subscription, completed domains stay cached, and application-data failures can be retried. `getLabel` falls back to the raw key; `requireLabel` throws instead, for values that must not render as a raw code. `options(domain)` returns every `{code, caption}` of a loaded domain, sorted by caption, for picklists.
 
 ## Status-filtered API errors
 
@@ -307,11 +308,24 @@ interface SailGuiConfig {
   defaultPolicyLanguage?: string;     // ISO 639-1 fallback language
   accountDeletedRoute?: string;       // Route after account deletion (default '/login/local')
   passwordPolicyUrl?: string;         // Public route serving keel's password policy (see below)
+  oauthServerUrl?: string;            // Base URL of keel's OAuth authorization server (see below)
+  allowedReturnHosts?: string[];      // Hosts a post-login ?return= may name
 }
 ```
 
 ### Password-policy validation
 
+**OAuth sign-in hand-off (v1.1.27, keel v1.2.89).** When the login page is opened with
+`?return=<authorize URL>` and both `oauthServerUrl` and `allowedReturnHosts` are set,
+`completeLogin` posts `{"return": <raw value>}` with the bearer JWT to
+`{oauthServerUrl}/oauth/session/handoff` and then leaves the SPA with a full navigation to the
+`redirect` keel answers. keel sets the authorization server's own HttpOnly cookie while
+redeeming that URL; sail does not opt into cross-origin cookies or send a CSRF token. A
+`return` whose host is not in `allowedReturnHosts`, or a `redirect` outside `oauthServerUrl`'s
+origin, is not followed. Failures set `BaseAuthService.sessionHandoffError` (rendered by
+`<sail-login>`) and never redirect: 400 means keel rejected the return URL, 401 means the user
+signs in again to retry. The authorization server must allow the SPA origin by CORS.
+
 Set `passwordPolicyUrl` to the app's public route for keel's `PublicHandler.GetPasswordPolicy`
 (e.g. `'/public/v1/auth/password/policy'`). `BaseAuthService.ensurePasswordPolicy()` fetches it
 once into the `passwordRules` signal, and `passwordPolicyValidator(() => auth.passwordRules())`
@@ -400,7 +414,7 @@ Every keel login response (keel v1.2.57+) carries `refreshToken` beside `token`;
 
 ### Realtime
 
-`RealtimeService` (root-provided) is the client for keel's `realtime.Hub`. `connect()` opens `RestURL.realtimeURL` (`/public/ws`) on the configured backend host with the stored JWT, reconnects with backoff, and re-subscribes every channel after a reconnect. `channel<T>(name)` returns the payloads keel broadcasts on that channel; `userFrames<T>()` returns payloads addressed to the user; `send(frame)` forwards an application frame to the hub's `OnMessage`. A subscription keel's `CanSubscribe` rejects is logged and exposed on `lastError`. Channel names and payload shapes are app-owned.
+`RealtimeService` (root-provided) is the client for keel's `realtime.Hub`. `connect()` opens `RestURL.realtimeURL` (`/public/ws`) on the configured backend host with the stored JWT, reconnects with backoff, and re-subscribes every channel after a reconnect. `channel<T>(name)` returns the payloads keel broadcasts on that channel; `userFrames<T>()` returns payloads addressed to the user, including keel's `{op: "notification"}` frames; `send(frame)` forwards an application frame to the hub's `OnMessage`. A subscription keel's `CanSubscribe` rejects is logged and exposed on `lastError`. Channel names and payload shapes are app-owned.
 
 ## Billing
 
@@ -433,6 +447,11 @@ export class PricingPage {
 | `createPortalSession()` | `POST /api/billing/portal` | `Observable<PortalResponse>` |
 | `listUsage()` | `GET /api/billing/usage` | `Observable<UsageMeter[]>` |
 
+`cancelSubscription()`, `changePlan()` and `createPortalSession()` answer 403 (keel v1.2.89)
+unless the user holds `PARTNER_PLAN_SUBSCRIPTION` `CANCEL` / `CHANGE` / `PORTAL`, seeded for
+`PARTNER_ADMIN`. Test a failure with `isPermissionDenied(err)` and report it as not permitted;
+`<sail-portal-button>` does.
+
 ### Components
 
 **Plan picker** — pure presentational, no API calls:
@@ -570,7 +589,7 @@ A `TableAction` with `kind: 'R'` (redirect — the `constant_value` code) makes
 
 ### Action parameters (v1.1.25)
 
-An action with `parameters` (keel v1.2.75 `table_action_parameter`) opens a dialog before posting: one field per parameter, typed by `dataType` (`boolean` checkbox, numeric, `date`, `timestamp`, otherwise text), or a dropdown when `lookupTable` names a table in the client cache (a `foreign_key_lookup` dropdown table); a numeric `dataType` still posts the chosen key as a number. The dialog shows `confirmMessage` in place of the native prompt and posts `{...primaryKeyValues(record), ...values}`; empty optional values are left out. An action without parameters behaves as before.
+An action with `parameters` (keel v1.2.75 `table_action_parameter`) opens a dialog before posting: one field per parameter, typed by `dataType` (`boolean` checkbox, numeric, `date`, `timestamp`, `file`, otherwise text), or a dropdown when `lookupTable` names a table in the client cache (a `foreign_key_lookup` dropdown table); a numeric `dataType` still posts the chosen key as a number. The dialog shows `confirmMessage` in place of the native prompt and posts `{...primaryKeyValues(record), ...values}`; empty optional values are left out. A `file` parameter turns the post into `multipart/form-data`, so a table-level `upload` action whose parameters are `file`, `document_type` (lookup `document_type`), `title`, … posts straight to keel's `DocumentHandler.Upload`. An action without parameters behaves as before.
 
 ### Status chip (v1.0.1)
 
@@ -773,6 +792,15 @@ 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.
 
+**Delegation roles (v1.1.27, keel v1.2.89).** `AgencyDelegation.roles` (always present) and
+`AgencyClient.roles` carry `AgencyRoleGrant { role, expiresAt? }`; no `expiresAt` is
+open-ended, and a delegation without roles grants no access.
+`AgencyService.setDelegationRoles(roles, clientPartnerId = 0)` replaces the whole set — an
+empty list removes access without revoking the delegation. Role codes and captions come from
+the `agency_delegation_role` constant catalogue (`LabelService.options('agency_delegation_role')`);
+do not hardcode them. keel answers 422 for an unknown, duplicate or blank role, more than 32
+roles, or an expiry not in the future, and 403 without `AGENCY_DELEGATION` / `SET_ROLE`.
+
 The agency URL defaults use `/api/v1/agency/*`. Apps mounting Keel elsewhere
 must override the `RestURL.agency*URL` values with `configureRestUrls()`.
 
@@ -1080,8 +1108,10 @@ readonly unread = inject(NotificationInboxService).unreadCount;   // Signal<numb
 | `load(limit)` / `loadMore(limit)` | Default 20; keel caps a page at 100 and the client clamps to match. |
 
 Message ids are server-side `BIGINT`s serialized as strings. Both mark-read routes
-return `204`, so the service updates its cache locally. Call `load()` to pick up new
-messages and `reset()` on logout.
+return `204`, so the service updates its cache locally. After the first successful `load()`, each
+`{op: "notification"}` frame from keel's `realtime.UserDispatcher` (v1.2.79+) on a
+connected `RealtimeService` re-fetches the newest page into the cache. Call `reset()`
+on logout.
 
 ```html
 <sail-notification-center
@@ -1105,6 +1135,31 @@ Ships no CSS — style
 `.notification-item`, `.notification-item--unread` and
 `.notification-item__{select,static,title,body,time,read}`.
 
+## Partner documents (v1.1.26)
+
+`PartnerDocumentService` covers generic `partner_document` reads plus keel's
+`handler.DocumentHandler` (keel **v1.2.79+**): `list(userId?)`, `pending()`,
+`upload(file, request)` (progress events), `previewUrl(id)` and `review(id, approve,
+notes)`. The defaults assume the handler is mounted at
+`/api/v1/partner_document/{upload,preview,review}`; override the three
+`partnerDocument*URL` values otherwise. Authorization stays in keel's hooks.
+
+```html
+<sail-document-upload documentType="driver_license" [maxBytes]="10485760"
+    [canUpload]="attested()" (uploaded)="onUploaded($event)" (failed)="onFailed($event)">
+  <!-- app-specific attestations -->
+</sail-document-upload>
+```
+
+Images preview inline, PDFs open in a new tab. `(failed)` hands over the raw error;
+branch on `errorCode(err)` for keel's `document_*` codes. Status captions come from
+the `partner_document_status` domain through `LabelService`.
+
+`<sail-partner-documents>` shows the latest version per type and offers replacement
+uploads for rejected or expiring documents. `<sail-document-review-queue>` lists
+pending rows with an inline preview and approve/reject controls. Both rely on the
+app's generic `partner_document` read grants and the handler authorization hooks.
+
 ## Grouped review actions and diffs (v1.1.19)
 
 `GroupedBulkActionComponent` (`sail-grouped-bulk-action`) groups eligible rows
@@ -1481,8 +1536,8 @@ The v0.6 / v0.7 line introduced three additive feature groups against keel v0.7.
 | `@nauticana/sail` | `PayoutService` | keel/payout API client — onboarding, reuse, status, bank-version replacement, beneficiary registration |
 | `@nauticana/sail` | `PayoutProviderOnboardingComponent` (`<sail-payout-provider-onboarding>`) | Drop-in onboarding step with reuse picker, hosted-KYC handoff, and asynchronous-confirmation output |
 | `@nauticana/sail` | `PayoutBankInfoFormComponent` (`<sail-payout-bank-info-form>`) | Tax + payout details form (country / currency / tax ID / billing address / agreement) |
-| `@nauticana/sail` | `UserPaymentMethodService` | Saved-card list / delete / set-default API client |
-| `@nauticana/sail` | `UserPaymentMethodsComponent` (`<sail-user-payment-methods>`) | List of saved cards/wallets with set-default + delete |
+| `@nauticana/sail` | `UserPaymentMethodService` | Saved-card list / remove / set-default API client |
+| `@nauticana/sail` | `UserPaymentMethodsComponent` (`<sail-user-payment-methods>`) | List of saved cards/wallets with set-default + remove |
 | `@nauticana/sail` | `TableAction`, `ReusableAccount`, `PayoutOnboardingSession`, `BankInfoFormValue`, `CountryProfile`, `UserPaymentMethod`, `DEFAULT_COUNTRY_PROFILES` | Model types / defaults |
 
 ### 2. New keel endpoints
@@ -1497,10 +1552,11 @@ Make sure your keel deployment exposes these — they're all under `/api/v1/`:
 | `/api/v1/payout/status` | POST | `{ complete: true }` once the active partner's row has a `providerAccountId` |
 | `/api/v1/payout/bank/replace` | POST | Supersede the active bank-info version and insert its replacement atomically; the app must wire the handler's `SealTaxID` hook |
 | `/api/v1/payout/beneficiary/register` | POST | Create and link a provider beneficiary from provider-collected details |
-| `/api/v1/payment-methods/set-default` | POST | Atomic multi-row UPDATE — sets one row as default, clears the rest |
+| `/api/v1/user_payment_method/set_default` | POST | `{id}` — sets one row as default, clears the rest |
+| `/api/v1/user_payment_method/remove` | POST | `{id}` — detaches the method at the provider, then deletes the row (keel v1.2.79) |
 | `/api/v1/{table}/{action_name}` | POST | Per-table custom actions resolved from `basis.table_action` |
 
-`list` / `delete` for the `user_payment_method` table go through keel's generic REST CRUD (`/api/v1/user_payment_method/list|delete`) — `user_payment_method` is a UserSpecific basis table, so keel auto-scopes reads to the caller and owner-locks DELETE. No custom endpoint needed for those two.
+`list` for `user_payment_method` is keel's generic REST CRUD, auto-scoped to the caller. keel grants no generic DELETE on the table, so removal goes through `remove`.
 
 ### 3. Payout onboarding wiring
 
@@ -1539,7 +1595,7 @@ For apps that operate on a single keel partner, the reuse picker stays empty and
     [title]="'Payment Methods'"
     (addClicked)="goToSetupIntent()"
     (defaultChanged)="onDefaultChanged($event)"
-    (deleted)="onDeleted($event)">
+    (removed)="onRemoved($event)">
 </sail-user-payment-methods>
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nauticana/sail",
-  "version": "1.1.25",
+  "version": "1.1.27",
   "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": {
@@ -52,6 +52,7 @@
     "@angular/core": "^21.0.0",
     "@angular/forms": "^21.0.0",
     "@angular/material": "^21.0.0",
+    "@angular/platform-browser": "^21.0.0",
     "@angular/router": "^21.0.0",
     "class-validator": "^0.15.1",
     "rxjs": "~7.8.0"

package/src/component/billing/portal_button.ts

@@ -2,12 +2,14 @@ import { ChangeDetectionStrategy, Component, ViewEncapsulation, inject, input }
 import { MatButtonModule } from '@angular/material/button';
 import { BaseAsync } from '../abstract/base_async';
 import { BillingService } from '../../service/billing.service';
+import { isPermissionDenied } from '../../util/errors';
 
 /**
  * Button that opens a provider customer-portal session and redirects the
  * browser to the returned URL — the partner manages their payment method /
  * subscription on the provider's hosted page. Mirrors CheckoutButtonComponent;
- * uses BaseAsync for loading/error state.
+ * uses BaseAsync for loading/error state. A 403 (no PARTNER_PLAN_SUBSCRIPTION /
+ * PORTAL grant) reads as not permitted rather than as a provider failure.
  */
 @Component({
   selector: 'sail-portal-button',
@@ -26,6 +28,9 @@ export class PortalButtonComponent extends BaseAsync {
       this.billing.createPortalSession(),
       (resp) => { window.location.href = resp.portalUrl; },
       'Could not open the billing portal. Please try again.',
+      (err) => {
+        if (isPermissionDenied(err)) this.errorMessage.set('You are not permitted to manage billing.');
+      },
     );
   }
 }

package/src/component/document/document_review_queue.html

@@ -0,0 +1,24 @@
+<section class="document-review-queue" [attr.aria-busy]="loading()">
+  @if (errorMessage()) { <p class="document-review-queue__error" role="alert">{{ errorMessage() }}</p> }
+  @if (!loading() && !documents().length) {
+    <p class="document-review-queue__empty">No documents are awaiting review.</p>
+  }
+  @for (doc of documents(); track doc.Id) {
+    <article class="document-review">
+      <h3>{{ doc.Title || doc.DocumentType }}</h3>
+      <p>{{ doc.FileName }} · version {{ doc.VersionNo }}</p>
+      <button matButton type="button" (click)="showPreview(doc)">Preview</button>
+      @if (preview()?.id === doc.Id) {
+        <iframe class="document-review__preview" [src]="preview()!.url" [title]="'Preview of ' + (doc.Title || doc.FileName)"></iframe>
+      }
+      <mat-form-field appearance="outline">
+        <mat-label>Review notes</mat-label>
+        <textarea matInput [value]="notes()[doc.Id]" (input)="setNotes(doc.Id, $event)"></textarea>
+      </mat-form-field>
+      <div class="document-review__actions">
+        <button matButton="filled" type="button" [disabled]="reviewing() === doc.Id" (click)="review(doc, true)">Approve</button>
+        <button matButton type="button" [disabled]="reviewing() === doc.Id" (click)="review(doc, false)">Reject</button>
+      </div>
+    </article>
+  }
+</section>

package/src/component/document/document_review_queue.ts

@@ -0,0 +1,67 @@
+import { ChangeDetectionStrategy, Component, OnInit, SecurityContext, ViewEncapsulation, inject, signal } from '@angular/core';
+import { DomSanitizer, SafeResourceUrl } from '@angular/platform-browser';
+import { MatButtonModule } from '@angular/material/button';
+import { MatFormFieldModule } from '@angular/material/form-field';
+import { MatInputModule } from '@angular/material/input';
+import { BaseAsync } from '../abstract/base_async';
+import { PartnerDocument } from '../../model/document';
+import { PartnerDocumentService } from '../../service/partner_document.service';
+
+@Component({
+  selector: 'sail-document-review-queue',
+  templateUrl: './document_review_queue.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  imports: [MatButtonModule, MatFormFieldModule, MatInputModule],
+})
+export class DocumentReviewQueueComponent extends BaseAsync implements OnInit {
+  private readonly service = inject(PartnerDocumentService);
+  private readonly sanitizer = inject(DomSanitizer);
+
+  readonly documents = signal<PartnerDocument[]>([]);
+  readonly preview = signal<{ id: number; url: SafeResourceUrl } | null>(null);
+  readonly reviewing = signal<number | null>(null);
+  readonly notes = signal<Record<number, string>>({});
+
+  ngOnInit(): void {
+    this.reload();
+  }
+
+  reload(): void {
+    this.run(this.service.pending(), (rows) => this.documents.set(rows), 'Could not load pending documents.');
+  }
+
+  showPreview(doc: PartnerDocument): void {
+    this.service.previewUrl(doc.Id).subscribe({
+      next: (url) => {
+        const safe = this.sanitizer.sanitize(SecurityContext.URL, url);
+        if (!safe) {
+          this.errorMessage.set('The document preview URL is invalid.');
+          return;
+        }
+        this.preview.set({ id: doc.Id, url: this.sanitizer.bypassSecurityTrustResourceUrl(safe) });
+      },
+      error: (err) => this.setError(err, 'Could not preview the document.'),
+    });
+  }
+
+  setNotes(id: number, event: Event): void {
+    const value = (event.target as HTMLTextAreaElement).value;
+    this.notes.update((notes) => ({ ...notes, [id]: value }));
+  }
+
+  review(doc: PartnerDocument, approve: boolean): void {
+    this.reviewing.set(doc.Id);
+    this.service.review(doc.Id, approve, this.notes()[doc.Id] ?? '').subscribe({
+      next: () => {
+        this.documents.update((rows) => rows.filter((row) => row.Id !== doc.Id));
+        if (this.preview()?.id === doc.Id) this.preview.set(null);
+        this.reviewing.set(null);
+      },
+      error: (err) => {
+        this.reviewing.set(null);
+        this.setError(err, 'Could not review the document.');
+      },
+    });
+  }
+}

package/src/component/document/document_upload.html

@@ -0,0 +1,31 @@
+<div class="document-upload">
+  @if (!file()) {
+    <button matButton="outlined" type="button" class="document-upload__pick" (click)="picker.click()">
+      <mat-icon>upload_file</mat-icon> {{ label() }}
+    </button>
+  } @else {
+    <div class="document-upload__preview">
+      @if (imageUrl(); as src) {
+        <img [src]="src" [alt]="file()!.name" class="document-upload__image">
+      } @else if (pdfUrl(); as src) {
+        <a [href]="src" target="_blank" rel="noopener" class="document-upload__pdf">Open preview</a>
+      }
+      <span class="document-upload__name">{{ file()!.name }}</span>
+    </div>
+
+    <ng-content />
+
+    <div class="document-upload__actions">
+      <button matButton="filled" type="button" (click)="upload()" [disabled]="!canUpload() || uploading()">Upload</button>
+      <button matButton="outlined" type="button" (click)="picker.click()" [disabled]="uploading()">Choose another</button>
+    </div>
+  }
+  <input #picker type="file" hidden [accept]="accept()" (change)="pick($event)" [attr.aria-label]="label()">
+
+  @if (progress() !== null) {
+    <mat-progress-bar mode="determinate" [value]="progress()" aria-label="Upload progress" />
+  }
+  @if (errorMessage()) {
+    <p class="document-upload__error" role="alert">{{ errorMessage() }}</p>
+  }
+</div>

package/src/component/document/document_upload.ts

@@ -0,0 +1,113 @@
+import { ChangeDetectionStrategy, Component, DestroyRef, ViewEncapsulation, computed, inject, input, output, signal } from '@angular/core';
+import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
+import { HttpEventType } from '@angular/common/http';
+import { MatButtonModule } from '@angular/material/button';
+import { MatIconModule } from '@angular/material/icon';
+import { MatProgressBarModule } from '@angular/material/progress-bar';
+import { PartnerDocumentService } from '../../service/partner_document.service';
+import { PartnerDocument } from '../../model/document';
+import { errorDetail } from '../../util/errors';
+
+/**
+ * Picks, previews and uploads one keel partner document. App-specific
+ * attestations are projected content; bind `[canUpload]` to their state.
+ * Ships no CSS — style the `.document-upload*` classes globally.
+ */
+@Component({
+  selector: 'sail-document-upload',
+  templateUrl: './document_upload.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  imports: [MatButtonModule, MatIconModule, MatProgressBarModule],
+})
+export class DocumentUploadComponent {
+  private readonly documents = inject(PartnerDocumentService);
+  private readonly destroyRef = inject(DestroyRef);
+
+  readonly documentType = input.required<string>();
+  readonly title = input('');
+  readonly documentNumber = input('');
+  /** YYYY-MM-DD. */
+  readonly expiresOn = input('');
+  readonly userId = input<number | undefined>(undefined);
+  readonly accept = input('image/*,application/pdf');
+  /** Client-side size cap; 0 leaves the limit to keel's document type. */
+  readonly maxBytes = input(0);
+  readonly label = input('Choose file');
+  readonly canUpload = input(true);
+
+  readonly uploaded = output<PartnerDocument>();
+  /** The raw error; branch on `errorCode(err)` (keel's `document_*` codes). */
+  readonly failed = output<unknown>();
+
+  readonly file = signal<File | null>(null);
+  readonly progress = signal<number | null>(null);
+  readonly errorMessage = signal('');
+  private readonly objectUrl = signal<string | null>(null);
+
+  readonly isImage = computed(() => this.file()?.type.startsWith('image/') ?? false);
+  readonly imageUrl = computed(() => (this.isImage() ? this.objectUrl() : null));
+  readonly pdfUrl = computed(() => (this.file()?.type === 'application/pdf' ? this.objectUrl() : null));
+  readonly uploading = computed(() => this.progress() !== null);
+
+  constructor() {
+    this.destroyRef.onDestroy(() => this.revokePreview());
+  }
+
+  pick(event: Event): void {
+    const input = event.target as HTMLInputElement;
+    const file = input.files?.[0] ?? null;
+    input.value = '';
+    this.errorMessage.set('');
+    this.revokePreview();
+    this.file.set(null);
+    if (!file) return;
+    const max = this.maxBytes();
+    if (max > 0 && file.size > max) {
+      this.errorMessage.set(`The file exceeds the ${(max / 1048576).toFixed(1)} MB limit.`);
+      return;
+    }
+    this.file.set(file);
+    this.objectUrl.set(URL.createObjectURL(file));
+  }
+
+  upload(): void {
+    const file = this.file();
+    if (!file || !this.canUpload() || this.uploading()) return;
+    this.errorMessage.set('');
+    this.progress.set(0);
+    this.documents.upload(file, {
+      documentType: this.documentType(),
+      title: this.title() || undefined,
+      documentNumber: this.documentNumber() || undefined,
+      expiresOn: this.expiresOn() || undefined,
+      userId: this.userId(),
+    }).pipe(takeUntilDestroyed(this.destroyRef)).subscribe({
+      next: (event) => {
+        if (event.type === HttpEventType.UploadProgress && event.total) {
+          this.progress.set(Math.round((100 * event.loaded) / event.total));
+        } else if (event.type === HttpEventType.Response && event.body) {
+          this.progress.set(null);
+          this.clear();
+          this.uploaded.emit(event.body);
+        }
+      },
+      error: (err) => {
+        this.progress.set(null);
+        this.errorMessage.set(errorDetail(err, 'Upload failed.'));
+        this.failed.emit(err);
+      },
+    });
+  }
+
+  clear(): void {
+    this.revokePreview();
+    this.file.set(null);
+  }
+
+  private revokePreview(): void {
+    const url = this.objectUrl();
+    if (url) URL.revokeObjectURL(url);
+    this.objectUrl.set(null);
+  }
+}

package/src/component/document/partner_documents.html

@@ -0,0 +1,33 @@
+<section class="partner-documents" [attr.aria-busy]="loading()">
+  @if (heading()) { <h2 class="partner-documents__title">{{ heading() }}</h2> }
+  @if (errorMessage()) { <p class="partner-documents__error" role="alert">{{ errorMessage() }}</p> }
+
+  @if (!loading() && !latest().length) {
+    <p class="partner-documents__empty">{{ emptyMessage() }}</p>
+  } @else {
+    <ul class="partner-documents__list">
+      @for (doc of latest(); track doc.Id) {
+        <li class="partner-document" [class.partner-document--rejected]="doc.Status === 'N'">
+          <div class="partner-document__details">
+            <strong>{{ doc.Title || doc.DocumentType }}</strong>
+            <span>{{ status(doc.Status) }} · version {{ doc.VersionNo }}</span>
+            @if (doc.ExpiresOn) { <span>Expires {{ doc.ExpiresOn | date }}</span> }
+            @if (doc.ReviewerNotes) { <span>{{ doc.ReviewerNotes }}</span> }
+          </div>
+          <div class="partner-document__actions">
+            <button matButton type="button" (click)="preview(doc)">
+              <mat-icon>visibility</mat-icon> Preview
+            </button>
+            @if (canReupload(doc)) {
+              <button matButton type="button" (click)="reuploading.set(doc)">Upload replacement</button>
+            }
+          </div>
+          @if (reuploading()?.Id === doc.Id) {
+            <sail-document-upload [documentType]="doc.DocumentType" [title]="doc.Title"
+                [documentNumber]="doc.DocumentNumber ?? ''" [userId]="doc.UserId ?? undefined" (uploaded)="uploaded()" />
+          }
+        </li>
+      }
+    </ul>
+  }
+</section>

package/src/component/document/partner_documents.ts

@@ -0,0 +1,92 @@
+import { ChangeDetectionStrategy, Component, OnInit, ViewEncapsulation, computed, inject, input, signal } from '@angular/core';
+import { DatePipe } from '@angular/common';
+import { MatButtonModule } from '@angular/material/button';
+import { MatIconModule } from '@angular/material/icon';
+import { forkJoin } from 'rxjs';
+import { BaseAsync } from '../abstract/base_async';
+import { PartnerDocument } from '../../model/document';
+import { LabelService } from '../../service/label.service';
+import { PartnerDocumentService } from '../../service/partner_document.service';
+import { DocumentUploadComponent } from './document_upload';
+
+@Component({
+  selector: 'sail-partner-documents',
+  templateUrl: './partner_documents.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  imports: [DatePipe, MatButtonModule, MatIconModule, DocumentUploadComponent],
+})
+export class PartnerDocumentsComponent extends BaseAsync implements OnInit {
+  private readonly service = inject(PartnerDocumentService);
+  private readonly labels = inject(LabelService);
+
+  readonly userId = input<number | undefined>(undefined);
+  readonly heading = input('Documents');
+  readonly emptyMessage = input('No documents uploaded.');
+  readonly expiringWithinDays = input(30);
+
+  readonly documents = signal<PartnerDocument[]>([]);
+  readonly reuploading = signal<PartnerDocument | null>(null);
+  readonly statusesReady = signal(false);
+  readonly latest = computed(() => latestByType(this.documents()));
+
+  ngOnInit(): void {
+    this.run(forkJoin({
+      labels: this.labels.loadLabels('partner_document_status'),
+      documents: this.service.list(this.userId()),
+    }), ({ documents }) => {
+      this.statusesReady.set(true);
+      this.documents.set(documents);
+    }, 'Could not load documents.');
+  }
+
+  reload(): void {
+    this.run(this.service.list(this.userId()), (rows) => this.documents.set(rows), 'Could not load documents.');
+  }
+
+  status(status: string): string {
+    return this.statusesReady() ? this.labels.requireLabel('partner_document_status', status) : '';
+  }
+
+  canReupload(doc: PartnerDocument): boolean {
+    return doc.Status === 'N' || isExpiring(doc.ExpiresOn, this.expiringWithinDays());
+  }
+
+  preview(doc: PartnerDocument): void {
+    // Opened synchronously so the popup blocker allows it; 'noopener' would return null.
+    const tab = window.open('', '_blank');
+    if (tab) tab.opener = null;
+    this.service.previewUrl(doc.Id).subscribe({
+      next: (url) => {
+        if (tab) tab.location.href = url;
+        else window.open(url, '_blank', 'noopener');
+      },
+      error: (err) => {
+        tab?.close();
+        this.setError(err, 'Could not open the document.');
+      },
+    });
+  }
+
+  uploaded(): void {
+    this.reuploading.set(null);
+    this.reload();
+  }
+}
+
+function latestByType(rows: PartnerDocument[]): PartnerDocument[] {
+  const latest = new Map<string, PartnerDocument>();
+  for (const row of rows) {
+    const key = `${row.UserId ?? ''}:${row.DocumentType}`;
+    const current = latest.get(key);
+    if (!current || row.VersionNo > current.VersionNo) latest.set(key, row);
+  }
+  return [...latest.values()].sort((a, b) => a.DocumentType.localeCompare(b.DocumentType));
+}
+
+function isExpiring(value: string | null, withinDays: number): boolean {
+  if (!value || withinDays < 0) return false;
+  const expires = new Date(`${value.slice(0, 10)}T00:00:00`);
+  if (Number.isNaN(expires.getTime())) return false;
+  return expires.getTime() <= Date.now() + withinDays * 86400000;
+}

package/src/component/login/login_component.ts

@@ -29,7 +29,7 @@ export class LoginComponent extends BaseAsync {
   protected fb = inject(FormBuilder);
   protected readonly guiConfig: SailGuiConfig = inject(SAIL_GUI_CONFIG, {optional: true}) ?? DEFAULT_CONFIG;
   protected readonly loggedOut = inject(ActivatedRoute).snapshot.queryParamMap.get('loggedOut') === 'true';
-  /** OAuth session-cookie handoff failure from BaseAuthService, shown below. */
+  /** OAuth session hand-off failure from BaseAuthService, shown below. */
   protected readonly sessionHandoffError = this.auth.sessionHandoffError;
 
   /**
@@ -64,8 +64,8 @@ export class LoginComponent extends BaseAsync {
 
   /**
    * loginSocial already ran completeLogin, which owns post-login navigation
-   * (route init, or the OAuth cookie handoff). Handlers must NOT navigate here —
-   * doing so abandons a pending handoff before its cookie is set. Downstream
+   * (route init, or the OAuth session hand-off). Handlers must NOT navigate here —
+   * doing so abandons a pending hand-off before it redirects. Downstream
    * social-login handlers should follow the same rule.
    */
   protected onSocialSuccess(_: LoginResponseSocial): void {}

package/src/component/payment/user_payment_methods.html

@@ -31,7 +31,7 @@
             @if (!m.IsDefault) {
               <button matButton (click)="setDefault(m)">Set default</button>
             }
-            <button matIconButton (click)="remove(m)" aria-label="Delete payment method">
+            <button matIconButton (click)="remove(m)" aria-label="Remove payment method">
               <mat-icon>delete</mat-icon>
             </button>
           </div>

package/src/component/payment/user_payment_methods.ts

@@ -10,7 +10,7 @@ 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.
+ * + remove 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: BillingService.createSetupIntent()
@@ -37,8 +37,8 @@ export class UserPaymentMethodsComponent extends BaseAsync implements OnInit {
   readonly addClicked = output<void>();
   /** Emitted after a successful set-default flip. */
   readonly defaultChanged = output<UserPaymentMethod>();
-  /** Emitted after a successful delete. */
-  readonly deleted = output<UserPaymentMethod>();
+  /** Emitted after a method is detached and removed. */
+  readonly removed = output<UserPaymentMethod>();
 
   private readonly service = inject(UserPaymentMethodService);
 
@@ -78,12 +78,12 @@ export class UserPaymentMethodsComponent extends BaseAsync implements OnInit {
 
   remove(m: UserPaymentMethod): void {
     this.run(
-      this.service.delete(m.Id),
+      this.service.remove(m.Id),
       () => {
         this.methods.update((list) => list.filter((row) => row.Id !== m.Id));
-        this.deleted.emit(m);
+        this.removed.emit(m);
       },
-      'Failed to delete.',
+      'Failed to remove.',
     );
   }