@nauticana/sail 1.1.25 → 1.1.27

package/src/component/table/action_params_dialog.html

@@ -9,6 +9,16 @@
                 @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>

package/src/component/table/action_params_dialog.ts

@@ -10,7 +10,7 @@ import { TableAction, TableActionParameter } from "../../model/appdata";
 import { ConstantValue } from "../../model/common";
 import { BaseAuthService } from "../../service/auth.service";
 
-type ParamKind = 'checkbox' | 'number' | 'date' | 'datetime-local' | 'text';
+type ParamKind = 'checkbox' | 'number' | 'date' | 'datetime-local' | 'file' | 'text';
 
 interface ParamField {
     param:    TableActionParameter;
@@ -65,6 +65,12 @@ export class ActionParamsDialog {
         }
         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 {
@@ -83,6 +89,8 @@ function kindOf(dataType: string): ParamKind {
         case 'datetime':
         case 'timestamp':
             return 'datetime-local';
+        case 'file':
+            return 'file';
         default:
             return 'text';
     }

package/src/config.ts

@@ -67,11 +67,11 @@ export interface SailGuiConfig {
   accountDeletedRoute?: string;
 
   // ── OAuth authorization-flow bridge (for an OAuth AS on a different host) ──
-  /** Backend path that mirrors the bearer JWT into an HttpOnly session cookie so
-   * a cross-site OAuth `/authorize` can see the session, e.g. '/api/v1/auth/session-cookie'.
-   * When set, login POSTs here before handing off to an allowed ?return= host. */
-  sessionCookieUrl?: string;
-  /** Hostnames a post-login `?return=` may redirect to (open-redirect allowlist),
+  /** Base URL of keel's OAuth authorization server, e.g. 'https://mcp.example.com'.
+   * When set, a login carrying an allowed ?return= POSTs it to
+   * `{oauthServerUrl}/oauth/session/handoff` and navigates to the URL keel answers. */
+  oauthServerUrl?: string;
+  /** Hostnames a post-login `?return=` may name (open-redirect allowlist),
    * e.g. ['mcp.example.com']. Anything not listed is ignored. */
   allowedReturnHosts?: string[];
 

package/src/index.ts

@@ -5,6 +5,7 @@ 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';
@@ -70,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';
@@ -79,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/agency.ts

@@ -24,6 +24,7 @@ export interface AgencyClient {
   acceptedAt?: string;
   expired?: boolean;
   billingModel?: string;
+  roles?: AgencyRoleGrant[];
 }
 
 export interface AgencyInvite {
@@ -42,6 +43,13 @@ export interface AgencyDelegation {
   agencyName: string;
   billingModel?: string;
   grantedAt: string;
+  roles: AgencyRoleGrant[];
+}
+
+/** One `agency_delegation_role` code a client grants its agency; no expiresAt is open-ended. */
+export interface AgencyRoleGrant {
+  role: string;
+  expiresAt?: string;
 }
 
 export interface AgencyEarningsBalance {

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/agency.service.ts

@@ -8,6 +8,7 @@ import {
   AgencyInvite,
   AgencyPayoutProfileOptions,
   AgencyProfile,
+  AgencyRoleGrant,
 } from '../model/agency';
 import { BaseRestService } from './base_rest.service';
 import { RestURL } from './rest_url';
@@ -73,4 +74,10 @@ export class AgencyService extends BaseRestService {
   revokeDelegation(clientPartnerId = 0): Observable<{ status: string }> {
     return this.http.post<{ status: string }>(this.url(RestURL.agencyRevokeDelegationURL), { clientPartnerId });
   }
+
+  /** Replace the whole role set the client grants its agency; an empty list
+   *  removes access without revoking the delegation. */
+  setDelegationRoles(roles: AgencyRoleGrant[], clientPartnerId = 0): Observable<{ status: string }> {
+    return this.http.post<{ status: string }>(this.url(RestURL.agencyDelegationRolesURL), { clientPartnerId, roles });
+  }
 }

package/src/service/auth.service.ts

@@ -25,6 +25,20 @@ export class RefreshSupersededError extends Error {
   constructor() { super('session changed during refresh'); this.name = 'RefreshSupersededError'; }
 }
 
+function handoffErrorMessage(status: number): string {
+  if (status === 400) return 'This sign-in link is not valid. Start again from the application you were connecting.';
+  if (status === 401) return 'Your session was not accepted. Please sign in again.';
+  return 'Could not complete sign-in. Please try again.';
+}
+
+function sameOrigin(a: string, b: string): boolean {
+  try {
+    return new URL(a, window.location.origin).origin === new URL(b, window.location.origin).origin;
+  } catch {
+    return false;
+  }
+}
+
 /** Sort dropdown options by their visible label so long lookup lists are scannable. */
 const byCaption = (a: ConstantValue, b: ConstantValue) =>
   (a.Caption ?? '').localeCompare(b.Caption ?? '', undefined, { numeric: true, sensitivity: 'base' });
@@ -124,8 +138,8 @@ export abstract class BaseAuthService extends BaseRestService {
   /** Last appdata load failure (null when none). */
   readonly appDataError = signal<unknown>(null);
 
-  /** Set when the OAuth session-cookie handoff fails; the UI shows it and lets the
-   *  user retry instead of being redirected into a cookieless login loop. */
+  /** Set when the OAuth session hand-off fails; the UI shows it and the user
+   *  signs in again to retry instead of being redirected without a session. */
   readonly sessionHandoffError = signal<string | null>(null);
 
   /**
@@ -203,42 +217,61 @@ export abstract class BaseAuthService extends BaseRestService {
     this.sessionGeneration++;
     this.storeTokens(token, refreshToken);
     this.isLoggedIn.set(true);
+    this.sessionHandoffError.set(null);
     resetAuthCircuit(); // a new session must not inherit a prior session's open circuit
     const ret = this.validatedReturnUrl();
-    if (ret && this.guiConfig.sessionCookieUrl) {
-      // OAuth flow: mirror the bearer into a cookie, then hand off to the
-      // (cross-origin) authorization server via a full navigation. Only hand off
-      // once the cookie is actually set — redirecting after a failed cookie request
-      // sends the user on without a session and loops them back to login.
-      this.sessionHandoffError.set(null);
-      this.http.post(this.url(this.guiConfig.sessionCookieUrl), {}, { withCredentials: true })
-          .pipe(take(1))
-          .subscribe({
-            next: () => window.location.assign(ret),
-            error: (err) => {
-              console.error('Session cookie handoff failed:', err);
-              this.sessionHandoffError.set('Could not complete sign-in. Please try again.');
-            },
-          });
+    const oauthServer = this.oauthServerBase();
+    if (ret && oauthServer) {
+      this.handOffSession(oauthServer, ret, token);
       return;
     }
     this.loadAppData();
     this.initRoutes();
   }
 
-  /** A post-login `?return=` URL, only when its host is in allowedReturnHosts and
-   * the scheme is https (or loopback) — an open-redirect guard. '' otherwise. */
+  /** Exchange the bearer session for the authorization server's own cookie session
+   * (keel POST /oauth/session/handoff), then leave the SPA for the URL it returns.
+   * Any failure stays on the login page; the browser is never sent elsewhere. */
+  private handOffSession(oauthServer: string, ret: string, token: string): void {
+    this.http.post<{ data?: { redirect?: unknown } }>(
+        oauthServer + '/oauth/session/handoff',
+        { return: ret },
+        { headers: { Authorization: `Bearer ${token}` } },
+    ).pipe(take(1)).subscribe({
+      next: (res) => {
+        const redirect = res?.data?.redirect;
+        if (typeof redirect !== 'string' || !sameOrigin(redirect, oauthServer)) {
+          console.error('Session handoff returned an unexpected redirect:', redirect);
+          this.sessionHandoffError.set('Could not complete sign-in. Please try again.');
+          return;
+        }
+        window.location.assign(redirect);
+      },
+      error: (err: HttpErrorResponse) => {
+        console.error('Session handoff failed:', err);
+        this.sessionHandoffError.set(handoffErrorMessage(err.status));
+      },
+    });
+  }
+
+  /** guiConfig.oauthServerUrl without trailing slashes; '' when unset. */
+  private oauthServerBase(): string {
+    return (this.guiConfig.oauthServerUrl ?? '').replace(/\/+$/, '');
+  }
+
+  /** The raw post-login `?return=` value, only when its host is in allowedReturnHosts
+   * and the scheme is https (or loopback) — an open-redirect guard. '' otherwise. */
   private validatedReturnUrl(): string {
     const raw = new URLSearchParams(window.location.search).get('return');
     if (!raw) return '';
     try {
-      const u = new URL(raw, window.location.origin);
+      const u = new URL(raw);
       if (u.username || u.password) return '';   // reject userinfo ("user@host") spoofing
       const host = u.hostname.toLowerCase();
       const okScheme = u.protocol === 'https:' || host === 'localhost' || host === '127.0.0.1';
       const allowed = (this.guiConfig.allowedReturnHosts ?? []).some((h) => h.toLowerCase() === host);
       if (okScheme && allowed) {
-        return u.toString();
+        return raw;
       }
     } catch { /* malformed → reject */ }
     return '';
@@ -564,6 +597,7 @@ export abstract class BaseAuthService extends BaseRestService {
     this.cache = undefined;
     this.authIndex.clear();
     this.appDataError.set(null);
+    this.sessionHandoffError.set(null);
     this.refreshInFlight = null;
     this.sessionGeneration++;           // in-flight loads and refreshes from this session are ignored
     this.appData$.next(null);           // live subscribers see menus clear; identity stays stable

package/src/service/billing.service.ts

@@ -45,7 +45,7 @@ export class BillingService extends BaseRestService {
     return this.http.get<Subscription>(this.url(RestURL.subscriptionURL));
   }
 
-  /** Cancel auto-renew on the current subscription. */
+  /** Cancel auto-renew on the current subscription. 403 without PARTNER_PLAN_SUBSCRIPTION / CANCEL. */
   cancelSubscription(): Observable<void> {
     return this.http.post<void>(this.url(RestURL.cancelSubURL), {});
   }
@@ -53,7 +53,7 @@ export class BillingService extends BaseRestService {
   /**
    * Upgrade / downgrade the current subscription to `planId` — distinct from
    * first-time checkout. Routes to keel's `SubscriptionLifecycle.ChangePlan`
-   * (atomic close+open) via an endpoint the app exposes.
+   * (atomic close+open). 403 without PARTNER_PLAN_SUBSCRIPTION / CHANGE.
    */
   changePlan(planId: string): Observable<void> {
     return this.http.post<void>(this.url(RestURL.changePlanURL), { planId });
@@ -86,7 +86,7 @@ export class BillingService extends BaseRestService {
   /**
    * Create a provider customer-portal session; caller redirects to the URL so
    * the partner can manage their payment method / subscription on the
-   * provider's hosted page.
+   * provider's hosted page. 403 without PARTNER_PLAN_SUBSCRIPTION / PORTAL.
    */
   createPortalSession(): Observable<PortalResponse> {
     return this.http.post<PortalResponse>(this.url(RestURL.portalURL), {});

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;
+}

package/src/service/realtime.service.ts

@@ -8,9 +8,11 @@ export interface RealtimeChannelFrame<T = unknown> {
   data:    T;
 }
 
+const CONTROL_OPS = ['subscribed', 'unsubscribed', 'error'] as const;
+
 /** Control frames of the keel realtime wire protocol. */
 interface ControlFrame {
-  op:       'subscribed' | 'unsubscribed' | 'error';
+  op:       typeof CONTROL_OPS[number];
   channel?: string;
   reason?:  string;
 }
@@ -93,7 +95,7 @@ export class RealtimeService {
     if (this.channels.delete(channel) && this.connected()) this.sendFrame({ op: 'unsubscribe', channel });
   }
 
-  /** Payloads keel delivers to this user directly (SendToUser / PublishUser). */
+  /** Payloads keel delivers to this user directly (SendToUser / PublishUser), e.g. `{op: 'notification', ...}`. */
   userFrames<T = unknown>(): Observable<T> {
     return this.frames$.pipe(filter((f): f is T => !isChannelFrame(f) && !isControlFrame(f)));
   }
@@ -132,7 +134,7 @@ function isChannelFrame(f: unknown): f is RealtimeChannelFrame {
 }
 
 function isControlFrame(f: unknown): f is ControlFrame {
-  return !!f && typeof f === 'object' && 'op' in f;
+  return !!f && typeof f === 'object' && CONTROL_OPS.includes((f as { op?: unknown }).op as ControlFrame['op']);
 }
 
 /** ws(s):// form of the configured backend host plus `path`; same-origin when no host is set. */

package/src/service/rest_service.ts

@@ -153,8 +153,18 @@ export class BackendService extends BaseRestService {
      * the call will POST to {host}{api_prefix}{actionPath} with the
      * supplied body. For record-specific actions the body carries the
      * primary key values; for table-level actions it is typically `{}`.
+     * A body carrying a File/Blob posts as `multipart/form-data`.
      */
     executeAction<T = unknown>(actionPath: string, body: Record<string, unknown> = {}): Observable<T> {
-        return this.http.post<T>(this.apiUrl(actionPath), body).pipe(catchError((err) => this.handleError(err)));
+        return this.http.post<T>(this.apiUrl(actionPath), multipartWhenFile(body)).pipe(catchError((err) => this.handleError(err)));
     }
 }
+
+function multipartWhenFile(body: Record<string, unknown>): Record<string, unknown> | FormData {
+    if (!Object.values(body).some((value) => value instanceof Blob)) return body;
+    const form = new FormData();
+    for (const [key, value] of Object.entries(body)) {
+        if (value != null) form.append(key, value instanceof Blob ? value : String(value));
+    }
+    return form;
+}

package/src/service/rest_url.ts

@@ -77,11 +77,15 @@ export const RestURL = {
   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
-  // URL POST /api/v1/user_payment_method/set_default.
+  agencyDelegationRolesURL:  '/api/v1/agency/delegation/roles',
+  // User payment methods — list is keel's generic REST CRUD; set_default and
+  // remove are keel UserPaymentMethodHandler table actions.
   paymentMethodSetDefaultURL: '/api/v1/user_payment_method/set_default',
+  paymentMethodRemoveURL:     '/api/v1/user_payment_method/remove',
+  // Partner documents — keel DocumentHandler, mounted at its TableActionPath shape.
+  partnerDocumentUploadURL:  '/api/v1/partner_document/upload',
+  partnerDocumentPreviewURL: '/api/v1/partner_document/preview',
+  partnerDocumentReviewURL:  '/api/v1/partner_document/review',
 };
 
 /** Call this at app startup to set the backend host URL */