@nauticana/sail 1.1.24 → 1.1.26

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/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.',
     );
   }
 

package/src/component/table/action_params_dialog.html

@@ -0,0 +1,50 @@
+<h2 mat-dialog-title>{{ action.caption }}</h2>
+<form [formGroup]="form" (ngSubmit)="submit()">
+    <mat-dialog-content>
+        @if (action.confirmMessage) {
+            <p>{{ action.confirmMessage }}</p>
+        }
+        @for (f of fields; track f.param.name) {
+            @switch (f.kind) {
+                @case ('checkbox') {
+                    <mat-checkbox [formControlName]="f.param.name">{{ f.param.caption }}</mat-checkbox>
+                }
+                @case ('file') {
+                    <div class="action-param-file">
+                        <label [for]="'action-param-' + f.param.name">{{ f.param.caption }}@if (f.param.required) { * }</label>
+                        <input type="file" [id]="'action-param-' + f.param.name" [required]="f.param.required"
+                               (change)="pickFile(f.param.name, $event)">
+                        @if (form.controls[f.param.name].touched && form.controls[f.param.name].invalid) {
+                            <p class="action-param-error" role="alert">{{ f.param.caption }} is required</p>
+                        }
+                    </div>
+                }
+                @case ('select') {
+                    <mat-form-field appearance="outline">
+                        <mat-label>{{ f.param.caption }}</mat-label>
+                        <mat-select [formControlName]="f.param.name" [required]="f.param.required">
+                            @if (!f.param.required) {
+                                <mat-option [value]="''">None</mat-option>
+                            }
+                            @for (opt of f.options; track opt.Value) {
+                                <mat-option [value]="opt.Value">{{ opt.Caption }}</mat-option>
+                            }
+                        </mat-select>
+                        <mat-error>{{ f.param.caption }} is required</mat-error>
+                    </mat-form-field>
+                }
+                @default {
+                    <mat-form-field appearance="outline">
+                        <mat-label>{{ f.param.caption }}</mat-label>
+                        <input matInput [type]="f.kind" [formControlName]="f.param.name" [required]="f.param.required">
+                        <mat-error>{{ f.param.caption }} is required</mat-error>
+                    </mat-form-field>
+                }
+            }
+        }
+    </mat-dialog-content>
+    <mat-dialog-actions align="end">
+        <button matButton type="button" mat-dialog-close>Cancel</button>
+        <button matButton="filled" type="submit">{{ action.caption }}</button>
+    </mat-dialog-actions>
+</form>

package/src/component/table/action_params_dialog.ts

@@ -0,0 +1,107 @@
+import { ChangeDetectionStrategy, Component, inject } from "@angular/core";
+import { FormControl, FormGroup, ReactiveFormsModule, ValidatorFn, Validators } from "@angular/forms";
+import { MAT_DIALOG_DATA, MatDialogModule, MatDialogRef } from "@angular/material/dialog";
+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 { TableAction, TableActionParameter } from "../../model/appdata";
+import { ConstantValue } from "../../model/common";
+import { BaseAuthService } from "../../service/auth.service";
+
+type ParamKind = 'checkbox' | 'number' | 'date' | 'datetime-local' | 'file' | 'text';
+
+interface ParamField {
+    param:    TableActionParameter;
+    kind:     ParamKind | 'select';
+    /** From dataType; a lookup dropdown still posts a number when the column is numeric. */
+    wireKind: ParamKind;
+    options?: ConstantValue[];
+}
+
+/** Collects a table action's declared parameters; closes with the typed values, or undefined on cancel. */
+@Component({
+    selector: "sail-action-params-dialog",
+    changeDetection: ChangeDetectionStrategy.OnPush,
+    imports: [
+        ReactiveFormsModule,
+        MatDialogModule,
+        MatButtonModule,
+        MatCheckboxModule,
+        MatFormFieldModule,
+        MatInputModule,
+        MatSelectModule,
+    ],
+    templateUrl: "./action_params_dialog.html",
+})
+export class ActionParamsDialog {
+    private readonly auth = inject(BaseAuthService);
+    private readonly dialogRef = inject(MatDialogRef<ActionParamsDialog, Record<string, unknown>>);
+    readonly action = inject<TableAction>(MAT_DIALOG_DATA);
+
+    readonly fields: ParamField[] = (this.action.parameters ?? []).map((param) => {
+        const options = param.lookupTable ? this.auth.getTableValues(param.lookupTable) : undefined;
+        const wireKind = kindOf(param.dataType);
+        return { param, kind: options ? 'select' : wireKind, wireKind, options };
+    });
+
+    readonly form = new FormGroup(Object.fromEntries(this.fields.map((f) => {
+        const validators: ValidatorFn[] = f.param.required && f.kind !== 'checkbox' ? [Validators.required] : [];
+        const initial: unknown = f.kind === 'checkbox' ? false : '';
+        return [f.param.name, new FormControl(initial, validators)];
+    })));
+
+    submit(): void {
+        if (this.form.invalid) {
+            this.form.markAllAsTouched();
+            return;
+        }
+        const values: Record<string, unknown> = {};
+        for (const f of this.fields) {
+            const raw = this.form.controls[f.param.name].value;
+            if (raw === '' || raw == null) continue;
+            values[f.param.name] = toWire(f.wireKind, raw);
+        }
+        this.dialogRef.close(values);
+    }
+
+    pickFile(name: string, event: Event): void {
+        const control = this.form.controls[name];
+        control.setValue((event.target as HTMLInputElement).files?.[0] ?? '');
+        control.markAsTouched();
+    }
+}
+
+function kindOf(dataType: string): ParamKind {
+    switch ((dataType || '').toLowerCase()) {
+        case 'boolean':
+            return 'checkbox';
+        case 'int':
+        case 'integer':
+        case 'number':
+        case 'numeric':
+        case 'float':
+        case 'decimal':
+            return 'number';
+        case 'date':
+            return 'date';
+        case 'datetime':
+        case 'timestamp':
+            return 'datetime-local';
+        case 'file':
+            return 'file';
+        default:
+            return 'text';
+    }
+}
+
+function toWire(kind: ParamKind, raw: unknown): unknown {
+    if (kind === 'number') return Number(raw);
+    // datetime-local holds local wall-clock time; keel expects a UTC instant.
+    if (kind === 'datetime-local') {
+        const d = new Date(String(raw));
+        return isNaN(d.getTime()) ? raw : d.toISOString();
+    }
+    return raw;
+}

package/src/index.ts

@@ -5,11 +5,13 @@ export * from './model/common';
 export * from './model/dashboard';
 export * from './model/oauth_connection';
 export * from './model/notification';
+export * from './model/document';
 export * from './model/agency';
 export * from './model/decorator';
 export * from './component/abstract/base_table';
 export * from './component/dashboard/dashboard_shell';
 export * from './component/dashboard/data_card';
+export * from './component/dashboard/stat_tile';
 export * from './component/dashboard/locked_overlay';
 export * from './component/dashboard/no_source_overlay';
 export * from './component/dashboard/action_center';
@@ -69,6 +71,9 @@ 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 './component/document/document_upload';
+export * from './component/document/partner_documents';
+export * from './component/document/document_review_queue';
 export * from './service/auth.service';
 export * from './service/sca_confirmer';
 export * from './service/domain_verifier';
@@ -78,6 +83,7 @@ export * from './service/agency.service';
 export * from './service/oauth_connection.service';
 export * from './service/notification_inbox.service';
 export * from './service/user_payment_method.service';
+export * from './service/partner_document.service';
 export * from './service/script_loader';
 export * from './service/auth.interceptor';
 export * from './service/realtime.service';

package/src/model/appdata.ts

@@ -79,6 +79,16 @@ export interface TableAction {
   authorityObject:  string;   // uppercased table_name — for canExecute()
   authorityCheck:   string;   // uppercased action_name — for canExecute()
   kind?:            'P' | 'R' | 'V'; // constant_value codes: P post (default) / R redirect (follow {url}) / V reveal (show returned secret once)
+  parameters?:      TableActionParameter[];
+}
+
+/** A value collected in a dialog before the action posts; merged into the body beside the record key. */
+export interface TableActionParameter {
+  name:         string;
+  caption:      string;
+  dataType:     string;
+  required:     boolean;
+  lookupTable?: string;   // offer this table's cached rows as choices
 }
 
 export interface ForeignKey {

package/src/model/document.ts

@@ -0,0 +1,36 @@
+/** One `partner_document` row in Sail's generic REST field shape. */
+export interface PartnerDocument {
+  Id:             number;
+  ContrepId:      string;
+  DocKey:         string;
+  PartnerId:      number;
+  /** null means the partner itself. */
+  UserId:         number | null;
+  DocumentType:   string;
+  Title:          string;
+  FileName:       string;
+  VersionNo:      number;
+  DocumentNumber: string | null;
+  ExpiresOn:      string | null;
+  OriginIp:       string | null;
+  UploadedBy:     number | null;
+  UploadedAt:     string;
+  /** `partner_document_status`: P pending, Y approved, N rejected, X superseded, R retired. */
+  Status:         string;
+  ReviewerId:     number | null;
+  ReviewedAt:     string | null;
+  ReviewerNotes:  string | null;
+  SupersededAt:   string | null;
+  RetiredAt:      string | null;
+  PurgedAt:       string | null;
+}
+
+export interface DocumentUploadRequest {
+  documentType:    string;
+  title?:          string;
+  documentNumber?: string;
+  /** YYYY-MM-DD. */
+  expiresOn?:      string;
+  /** The member the document is about; omitted = the partner. */
+  userId?:         number;
+}

package/src/service/label.service.ts

@@ -2,6 +2,11 @@ import { inject, Injectable } from "@angular/core";
 import { Observable, map, of, shareReplay, take, tap } from "rxjs";
 import { BaseAuthService } from "./auth.service";
 
+export interface LabelOption {
+    code: string;
+    caption: string;
+}
+
 @Injectable({ providedIn: 'root' })
 export class LabelService {
     private readonly auth = inject(BaseAuthService);
@@ -13,6 +18,23 @@ export class LabelService {
         return this.labels.get(constantId)?.get(key) ?? key;
     }
 
+    /** Caption of a backend-sourced value; throws when the domain is not loaded or lacks the key. */
+    requireLabel(constantId: string, key: string): string {
+        const domain = this.labels.get(constantId);
+        if (!domain) throw new Error(`sail: constant domain "${constantId}" is not loaded.`);
+        const caption = domain.get(key);
+        if (caption === undefined) throw new Error(`sail: constant domain "${constantId}" has no value "${key}".`);
+        return caption;
+    }
+
+    /** Every value of a loaded domain, by caption (keel's ConstantCache carries no display order). */
+    options(constantId: string): LabelOption[] {
+        const domain = this.labels.get(constantId);
+        if (!domain) throw new Error(`sail: constant domain "${constantId}" is not loaded.`);
+        return [...domain].map(([code, caption]) => ({ code, caption }))
+            .sort((a, b) => a.caption.localeCompare(b.caption));
+    }
+
     /**
      * Load one backend-provided `constant_value` domain from ApplicationData.
      * Completed and concurrent requests are cached; a failed application-data

package/src/service/notification_inbox.service.ts

@@ -1,16 +1,24 @@
-import { Injectable, Signal, signal } from '@angular/core';
+import { Injectable, Signal, inject, signal } from '@angular/core';
 import { HttpParams } from '@angular/common/http';
-import { Observable, tap } from 'rxjs';
+import { EMPTY, Observable, Subscription, catchError, filter, switchMap, tap } from 'rxjs';
 import { BaseRestService } from './base_rest.service';
+import { RealtimeService } from './realtime.service';
 import { RestURL } from './rest_url';
 import { InboxMessage, InboxPage } from '../model/notification';
 
 export const INBOX_MAX_PAGE_SIZE = 100;
 export const INBOX_DEFAULT_PAGE_SIZE = 20;
 
-/** Stateful client for keel's `InboxHandler` (v1.2.71+). Call `reset()` on logout. */
+/**
+ * Stateful client for keel's `InboxHandler` (v1.2.71+). After `load()` it re-fetches
+ * the newest page on each realtime `notification` frame (keel `realtime.UserDispatcher`).
+ * Call `reset()` on logout.
+ */
 @Injectable({ providedIn: 'root' })
 export class NotificationInboxService extends BaseRestService {
+  private readonly realtime = inject(RealtimeService);
+  private live: Subscription | null = null;
+  private pageSize = INBOX_DEFAULT_PAGE_SIZE;
   private readonly cached = signal<InboxMessage[]>([]);
   private readonly unread = signal(0);
   private readonly older = signal(false);
@@ -20,17 +28,25 @@ export class NotificationInboxService extends BaseRestService {
   readonly hasMore: Signal<boolean> = this.older.asReadonly();
 
   load(limit = INBOX_DEFAULT_PAGE_SIZE): Observable<InboxPage> {
-    return this.fetch('', limit).pipe(tap((page) => this.cached.set(page.messages)));
+    this.pageSize = pageSizeOf(limit);
+    return this.fetch('', limit).pipe(tap((page) => {
+      this.cached.set(page.messages);
+      this.older.set(this.isFull(page, limit));
+      this.follow();
+    }));
   }
 
   loadMore(limit = INBOX_DEFAULT_PAGE_SIZE): Observable<InboxPage> {
     const loaded = this.cached();
     const oldest = loaded.length ? loaded[loaded.length - 1].id : '';
     return this.fetch(oldest, limit).pipe(
-      tap((page) => this.cached.update((rows) => {
-        const ids = new Set(rows.map((message) => message.id));
-        return rows.concat(page.messages.filter((message) => !ids.has(message.id)));
-      })),
+      tap((page) => {
+        this.older.set(this.isFull(page, limit));
+        this.cached.update((rows) => {
+          const ids = new Set(rows.map((message) => message.id));
+          return rows.concat(page.messages.filter((message) => !ids.has(message.id)));
+        });
+      }),
     );
   }
 
@@ -54,23 +70,46 @@ export class NotificationInboxService extends BaseRestService {
   }
 
   reset(): void {
+    this.live?.unsubscribe();
+    this.live = null;
     this.cached.set([]);
     this.unread.set(0);
     this.older.set(false);
   }
 
+  /** The frame carries no message id, so the newest page is re-fetched and merged over the cache head. */
+  private follow(): void {
+    if (this.live) return;
+    this.live = this.realtime.userFrames<{ op?: unknown }>().pipe(
+      filter((frame) => frame?.op === 'notification'),
+      switchMap(() => this.fetch('', this.pageSize).pipe(
+        catchError((err) => {
+          console.error('notification inbox: refresh after realtime frame failed', err);
+          return EMPTY;
+        }),
+      )),
+    ).subscribe((page) => {
+      const fresh = new Set(page.messages.map((message) => message.id));
+      this.cached.update((rows) => page.messages.concat(rows.filter((message) => !fresh.has(message.id))));
+    });
+  }
+
   private fetch(before: string, limit: number): Observable<InboxPage> {
-    const requested = Number.isFinite(limit) ? Math.trunc(limit) : INBOX_DEFAULT_PAGE_SIZE;
-    const size = Math.min(Math.max(1, requested), INBOX_MAX_PAGE_SIZE);
-    let params = new HttpParams().set('limit', size);
+    let params = new HttpParams().set('limit', pageSizeOf(limit));
     if (before) params = params.set('before', before);
     return this.http.get<InboxPage>(this.url(RestURL.notificationsURL), { params }).pipe(
-      tap((page) => {
-        this.unread.set(page.unreadCount);
-        this.older.set(page.messages.length >= size);
-      }),
+      tap((page) => this.unread.set(page.unreadCount)),
     );
   }
+
+  private isFull(page: InboxPage, limit: number): boolean {
+    return page.messages.length >= pageSizeOf(limit);
+  }
+}
+
+function pageSizeOf(limit: number): number {
+  const requested = Number.isFinite(limit) ? Math.trunc(limit) : INBOX_DEFAULT_PAGE_SIZE;
+  return Math.min(Math.max(1, requested), INBOX_MAX_PAGE_SIZE);
 }
 
 function nowIso(): string {

package/src/service/partner_document.service.ts

@@ -0,0 +1,111 @@
+import { inject, Injectable } from '@angular/core';
+import { HttpEvent, HttpEventType, HttpParams, HttpResponse } from '@angular/common/http';
+import { Observable, map } from 'rxjs';
+import { BaseRestService } from './base_rest.service';
+import { BackendService } from './rest_service';
+import { RestURL } from './rest_url';
+import { DocumentUploadRequest, PartnerDocument } from '../model/document';
+
+interface DocumentHandlerResponse {
+  ID: number;
+  ContRepID: string;
+  DocKey: string;
+  PartnerID: number;
+  UserID: number;
+  DocumentType: string;
+  Title: string;
+  FileName: string;
+  VersionNo: number;
+  DocumentNumber: string;
+  ExpiresOn: string;
+  OriginIP: string;
+  UploadedBy: number;
+  UploadedAt: string;
+  Status: string;
+  ReviewerID: number;
+  ReviewedAt: string;
+  ReviewerNotes: string;
+  SupersededAt: string;
+  RetiredAt: string;
+  PurgedAt: string;
+}
+
+/** Client for keel's `handler.DocumentHandler` and `partner_document` REST table. */
+@Injectable({ providedIn: 'root' })
+export class PartnerDocumentService extends BaseRestService {
+  private readonly backend = inject(BackendService);
+
+  list(userId?: number): Observable<PartnerDocument[]> {
+    const filter = userId === undefined ? undefined : { UserId: String(userId) };
+    return this.backend.list<PartnerDocument>('partner_document', filter);
+  }
+
+  pending(): Observable<PartnerDocument[]> {
+    return this.backend.list<PartnerDocument>('partner_document', { Status: 'P' });
+  }
+
+  /** Multipart upload with progress events; the final response carries the stored document. */
+  upload(file: File, request: DocumentUploadRequest): Observable<HttpEvent<PartnerDocument>> {
+    const form = new FormData();
+    form.append('file', file);
+    form.append('document_type', request.documentType);
+    if (request.title) form.append('title', request.title);
+    if (request.documentNumber) form.append('document_number', request.documentNumber);
+    if (request.expiresOn) form.append('expires_on', request.expiresOn);
+    if (request.userId) form.append('user_id', String(request.userId));
+    return this.http.post<DocumentHandlerResponse>(this.url(RestURL.partnerDocumentUploadURL), form, {
+      reportProgress: true,
+      observe: 'events',
+    }).pipe(map((event) => normalizeUploadEvent(event)));
+  }
+
+  /** Short-lived signed read URL. */
+  previewUrl(id: number): Observable<string> {
+    const params = new HttpParams().set('id', id);
+    return this.http.get<{ url: string }>(this.url(RestURL.partnerDocumentPreviewURL), { params })
+      .pipe(map((resp) => resp.url));
+  }
+
+  review(id: number, approve: boolean, notes = ''): Observable<void> {
+    // keel decodes the id with `json:"id,string"`.
+    return this.http.post<void>(this.url(RestURL.partnerDocumentReviewURL), { id: String(id), approve, notes });
+  }
+}
+
+function normalizeUploadEvent(event: HttpEvent<DocumentHandlerResponse>): HttpEvent<PartnerDocument> {
+  if (event.type !== HttpEventType.Response) return event;
+  return (event as HttpResponse<DocumentHandlerResponse>).clone({
+    body: event.body ? normalizeDocument(event.body) : null,
+  });
+}
+
+/** DocumentHandler answers with keel's Go struct: zero values stand for the row's NULLs. */
+function normalizeDocument(doc: DocumentHandlerResponse): PartnerDocument {
+  return {
+    Id: doc.ID,
+    ContrepId: doc.ContRepID,
+    DocKey: doc.DocKey,
+    PartnerId: doc.PartnerID,
+    UserId: doc.UserID || null,
+    DocumentType: doc.DocumentType,
+    Title: doc.Title,
+    FileName: doc.FileName,
+    VersionNo: doc.VersionNo,
+    DocumentNumber: doc.DocumentNumber || null,
+    ExpiresOn: timeOrNull(doc.ExpiresOn),
+    OriginIp: doc.OriginIP || null,
+    UploadedBy: doc.UploadedBy || null,
+    UploadedAt: doc.UploadedAt,
+    Status: doc.Status,
+    ReviewerId: doc.ReviewerID || null,
+    ReviewedAt: timeOrNull(doc.ReviewedAt),
+    ReviewerNotes: doc.ReviewerNotes || null,
+    SupersededAt: timeOrNull(doc.SupersededAt),
+    RetiredAt: timeOrNull(doc.RetiredAt),
+    PurgedAt: timeOrNull(doc.PurgedAt),
+  };
+}
+
+function timeOrNull(value: string): string | null {
+  return !value || value.startsWith('0001-01-01') ? null : value;
+}