@jwilleke/ngdpbase-types 5.25.0 → 5.27.0

package/lib/src/ice/types.d.ts

@@ -0,0 +1,262 @@
+/**
+ * ICE — import, convert, export (#1979): the shapes the engine, its shims and
+ * its receivers share. The design and every decision (D1–D11) are in
+ * docs/planning/ice-planing.md; this file is their code form.
+ *
+ * - A __shim__ knows one outside format and nothing else (D2). It declares
+ *   its direction, what it accepts, what it produces and which receivers it
+ *   may hand to (D3, D7). Shims chain: one's output is the next one's input (D9).
+ * - A __receiver__ is a door that already exists — PageManager for pages, the
+ *   upload door for files, an add-on's own manager for its records (D4). The
+ *   engine hands it each result and never writes storage itself. The receiver
+ *   checks its own existing permission with the context the run carries (D5).
+ * - The __engine__ (ImportManager) owns everything else: sources, unzip, the
+ *   noise filter, fingerprints, skipping unchanged files, per-file status,
+ *   keeping the original, and running the work as a background job.
+ *
+ * Only importing is built in the first slice. `out` / `both` shims and the
+ * `write` half are declared so export (#1974) and feeds (D10) fit later
+ * without changing these shapes.
+ */
+import type { ActorContext } from '../context/ActorContext.js';
+import type { GuardedFetchOptions, GuardedResponse } from '../http/guardedFetch.js';
+/** D3: which way a shim moves data. Most are `in`; PDF (#1974) would be `both`. */
+export type ShimDirection = 'in' | 'out' | 'both';
+/**
+ * The kind of a piece of content moving through the engine. `file` is raw
+ * input bytes; `html` and `ncm` are core's; an add-on's own kinds are named
+ * `<slug>.<kind>`, e.g. `phr.health-record`.
+ */
+export type IceKind = string;
+/** A structured note from a shim, the same shape as a converter's warning. */
+export interface IceWarning {
+    kind: string;
+    detail: string;
+}
+/**
+ * One piece of content: a file the engine read, or what a shim produced from
+ * it. A shim's output becomes the next shim's input, or a receiver's.
+ */
+export interface IceItem {
+    kind: IceKind;
+    /** The name it arrived under: the upload's file name, or `archive.zip/inner/path`. */
+    name: string;
+    mediaType?: string;
+    /** Raw bytes (a `file`, or binary output). */
+    bytes?: Buffer;
+    /** Text content (`html`, `ncm`, an XML document). */
+    text?: string;
+    /** A structured record, for record kinds such as health records. */
+    data?: unknown;
+    /** Facts about the content: a title, an author, a source system's id. */
+    metadata?: Record<string, unknown>;
+    warnings?: IceWarning[];
+    /**
+     * The item's own id or time, for a shim whose duplicates are per item
+     * (a feed entry): an item whose key the engine has seen before is skipped.
+     */
+    itemKey?: string;
+}
+/** What a shim takes. A file matches by extension or media type; a chained input by kind. */
+export interface ShimAccepts {
+    /** Lower-case, with the dot: `['.xml']`. */
+    extensions?: string[];
+    mediaTypes?: string[];
+    /** Kinds produced by another shim that this one reads (D9), e.g. `['html']`. */
+    kinds?: IceKind[];
+    /**
+     * "Can I read this?" (D7), on the content. When present it must answer yes
+     * even for a file whose extension matches; it is also how a file with no
+     * matching extension is claimed.
+     */
+    canRead?(input: IceItem): boolean;
+}
+/** What the engine hands a shim besides its input. */
+export interface ShimTools {
+    /**
+     * Follow-up fetches go through the engine (design rule): the one guarded
+     * path, with the site's egress policy, User-Agent and timeout.
+     */
+    fetch(url: string, options?: Omit<GuardedFetchOptions, 'policy' | 'transport' | 'resolver'>): Promise<GuardedResponse>;
+    /** This shim's options from site configuration (D6): `ngdpbase.import.shims.<id>.options`. */
+    options: Record<string, unknown>;
+}
+/** What a shim's read returns. */
+export interface ShimReadResult {
+    items: IceItem[];
+    /**
+     * Set when the shim read only part of its input (phr's `readCcda` returns
+     * records plus a partial note): the file's status is then `partial`, with this.
+     */
+    partial?: string;
+}
+/**
+ * A shim as its author writes it (D7). `name` is unique within its owner; the
+ * engine names it `<owner>.<name>` — `core.markdown`, `phr.ccda`.
+ */
+export interface IceShim {
+    name: string;
+    /** Shown to people choosing a format. */
+    label?: string;
+    direction: ShimDirection;
+    accepts: ShimAccepts;
+    /** The kind its output items have. */
+    produces: IceKind;
+    /**
+     * Receivers it may hand to directly (ids, `core.pages` or `<slug>.<name>`).
+     * Empty for a shim whose output only feeds another shim.
+     */
+    receivers: string[];
+    /** Two duplicate kinds (design rule): a whole file by fingerprint, or each item by `itemKey`. Default `file`. */
+    duplicates?: 'file' | 'item';
+    /** Inbound: read one input. Required for `in` and `both`. */
+    read?(input: IceItem, tools: ShimTools): Promise<ShimReadResult>;
+    /** Outbound (export, #1974): not run in the first slice. Required for `out` and `both`. */
+    write?(items: IceItem[], tools: ShimTools): Promise<IceItem[]>;
+}
+/** A shim the engine holds: its full id, and who registered it. */
+export interface RegisteredShim extends IceShim {
+    id: string;
+    owner: string;
+}
+/** D11: what the person importing chose to do with the original file. */
+export type OriginalChoice = 'cite' | 'keep' | 'none';
+/** A citation to the origin (D11): the receiver renders it, as a footnote on a page. */
+export interface IceCitation {
+    name: string;
+    sha256: string;
+    importedAt: string;
+}
+/** Where a kept original went (D11). */
+export interface KeptOriginal {
+    name: string;
+    sha256: string;
+    /** The keeping door's own reference: an attachment id, a record id. */
+    ref: string;
+}
+/** What a receiver is told about the item it is handed. */
+export interface ReceiveInfo {
+    runId: string;
+    /** The file the item came from. */
+    source: {
+        name: string;
+        sha256: string;
+    };
+    /** The shims the item passed through, in order. */
+    chain: string[];
+    citation?: IceCitation;
+    original?: KeptOriginal;
+}
+/** A receiver's answer for one item. `refused` is its existing permission saying no (D5). */
+export interface ReceiveOutcome {
+    status: 'stored' | 'duplicate' | 'refused';
+    /** Where it went: a page name, an attachment id, a record id. */
+    ref?: string;
+    message?: string;
+}
+/**
+ * A receiver as its owner writes it (D4). Its doors are the receiver's own
+ * existing ones; each checks its own permission with the context given (D5).
+ */
+export interface IceReceiver {
+    name: string;
+    label?: string;
+    /** The kinds it takes, e.g. `['ncm']`, `['file']`, `['phr.health-record']`. */
+    accepts: IceKind[];
+    /** May this context use this receiver? Its existing permission — the import screen shows only these (D5). */
+    mayUse(ctx: ActorContext): Promise<boolean>;
+    /** Hand one item to the receiver's own door. */
+    receive(item: IceItem, ctx: ActorContext, info: ReceiveInfo): Promise<ReceiveOutcome>;
+    /**
+     * Keep the original file itself (D11: phr keeps originals in its own
+     * store). Without this, `keep` hands the original to the files receiver.
+     */
+    keepOriginal?(original: IceItem, ctx: ActorContext): Promise<ReceiveOutcome>;
+}
+export interface RegisteredReceiver extends IceReceiver {
+    id: string;
+    owner: string;
+}
+/** One file handed to the engine. A `.zip` is unpacked by the engine. */
+export interface IceUpload {
+    name: string;
+    bytes: Buffer;
+    mediaType?: string;
+}
+/**
+ * A source (D1). The first slice reads uploads; a URL fetched on a schedule
+ * (D10, feeds) and a server folder join this union later.
+ */
+export type IceSource = {
+    type: 'upload';
+    files: IceUpload[];
+};
+/** One import, as a caller asks for it. */
+export interface IceRunRequest {
+    source: IceSource;
+    /** The receiver id the results go to: `core.pages`, `phr.health-records`. */
+    receiver: string;
+    /** Pin the first shim (a format the person chose) instead of detecting one. */
+    shim?: string;
+    /** D11. Default `ngdpbase.import.engine.default-original`. */
+    original?: OriginalChoice;
+    /**
+     * Whose fingerprints and item keys this run is checked against. Default
+     * `<receiver>/<username>`: the same file imported again by the same person
+     * into the same receiver is skipped. A caller with its own notion of a
+     * source (phr's source id) passes it.
+     */
+    scope?: string;
+}
+/** Per-file status (first slice). */
+export type IceFileStatus = 'imported' | 'partial' | 'unchanged' | 'duplicate' | 'noise' | 'unreadable' | 'refused' | 'failed';
+export interface IceFileReport {
+    name: string;
+    sha256?: string;
+    size: number;
+    status: IceFileStatus;
+    message?: string;
+    /** The shims the file went through. */
+    chain: string[];
+    /** Where each item went. */
+    refs: string[];
+    /** Items stored, and items skipped as already seen. */
+    stored: number;
+    duplicates: number;
+    original?: KeptOriginal;
+    warnings: IceWarning[];
+}
+export interface IceRunReport {
+    runId: string;
+    receiver: string;
+    scope: string;
+    /** Who it ran as. */
+    username: string;
+    state: 'queued' | 'running' | 'done' | 'failed';
+    startedAt?: string;
+    finishedAt?: string;
+    error?: string;
+    files: IceFileReport[];
+}
+/** What the engine remembers about one file in a scope. */
+export interface LedgerFileEntry {
+    name: string;
+    sha256: string;
+    size: number;
+    status: IceFileStatus;
+    message?: string;
+    at: string;
+    refs: string[];
+}
+/**
+ * Where the engine keeps fingerprints, per-file status and item keys, per
+ * scope. One interface so a database table can replace the file store when
+ * the application database is on.
+ */
+export interface IceLedger {
+    lastFile(scope: string, sha256: string): Promise<LedgerFileEntry | null>;
+    recordFile(scope: string, entry: LedgerFileEntry): Promise<void>;
+    hasItem(scope: string, itemKey: string): Promise<boolean>;
+    recordItem(scope: string, itemKey: string): Promise<void>;
+    files(scope: string): Promise<LedgerFileEntry[]>;
+}

package/lib/src/mail/MailProvider.d.ts

@@ -20,7 +20,22 @@ export interface MailMessage {
     text: string;
     /** Optional HTML body */
     html?: string;
+    /** Files sent with the message (#1974); their total is capped by `ngdpbase.mail.attachments.max-bytes`. */
+    attachments?: MailAttachment[];
 }
+/**
+ * One file attached to a message (#1974), as Nodemailer takes it. The content
+ * is never logged: a log line says how many files and how many bytes.
+ */
+export interface MailAttachment {
+    /** The name the recipient sees, e.g. `invoice-2026-0042.pdf`. */
+    filename: string;
+    /** Its media type, e.g. `application/pdf`. */
+    contentType: string;
+    content: Buffer;
+}
+/** How many files and bytes a message carries — the only thing a log line says about attachments. */
+export declare function describeAttachments(attachments: MailAttachment[] | undefined): string;
 /**
  * Common interface for all mail transports.
  */

package/lib/src/mail/NodemailerMailProvider.d.ts

@@ -9,7 +9,7 @@
  *   ngdpbase.mail.provider.smtp.pass
  *   ngdpbase.mail.provider.smtp.from
  */
-import type { MailMessage, MailProvider } from './MailProvider.js';
+import { type MailMessage, type MailProvider } from './MailProvider.js';
 export interface SmtpConfig {
     host: string;
     port: number;

package/lib/src/managers/AddonsManager.d.ts

@@ -11,12 +11,14 @@
  * @see {@link https://github.com/jwilleke/ngdpbase/issues/158}
  */
 import { type ActorContext } from '../context/ActorContext.js';
+import type { BackupFolder } from './BaseManager.js';
 import BaseManager from './BaseManager.js';
 import type { BackupData } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
 import type { User } from '../types/User.js';
 import { type StoreOwnerState } from '../utils/privateStoreDoor.js';
 import { type AddonHost } from '../utils/addonHost.js';
+import { ConsentRequiredError } from '../types/Consent.js';
 /**
  * Type passed to `AddonModule.profileSection()` (#534). Matches what
  * `UserManager.getUser()` returns at runtime — `User` minus the password
@@ -76,6 +78,14 @@ export interface AddonModule {
      * frozen. An add-on that takes two arguments keeps working until it moves.
      */
     register(engine: WikiEngine, config: Record<string, unknown>, host?: AddonHost): Promise<void> | void;
+    /**
+     * Folders it keeps data in besides its `dataPath` (#1985), given its
+     * configuration. Its `dataPath` is backed up and restored without being
+     * declared; an add-on declares only further folders, and writes no backup
+     * code. BackupManager archives each one, stages it in a site restore, and
+     * puts it in place before `register()` runs at the next start.
+     */
+    backupFolders?(config: Record<string, unknown>): BackupFolder[];
     /**
      * Optional health check returning add-on status details.
      */
@@ -228,6 +238,19 @@ export interface AddonManifest {
     family?: string;
     /** #1965: `false` keeps plumbing (e.g. elasticsearch) out of the add-on listings. */
     listed?: boolean;
+    /**
+     * #1979 (ICE, D6): the names of the import shims this add-on registers at
+     * load with `host.registerShim`, e.g. `["ccda", "fhir"]` (ids `<slug>.ccda`,
+     * `<slug>.fhir`). The host refuses a shim not named here. Site configuration
+     * switches each one: `ngdpbase.import.shims.<slug>.<name>.enabled`.
+     */
+    shims?: string[];
+    /**
+     * #1979 (ICE, D4): the names of the receivers this add-on registers with
+     * `host.registerReceiver` — its own manager's door for what shims produce,
+     * e.g. `["health-records"]`. The host refuses a receiver not named here.
+     */
+    receivers?: string[];
 }
 /**
  * One add-on as the listings show it (#1965), from `AddonsManager.listedAddons()`.
@@ -464,6 +487,20 @@ declare class AddonsManager extends BaseManager {
      * not registered yet says nothing about whether it still provides it.
      */
     addonsLoaded(): boolean;
+    /**
+     * An add-on's folders (#1985): its `dataPath` — `ngdpbase.addons.<slug>.dataPath`,
+     * or `<FAST_STORAGE>/<slug>` when that is not set, as the bundled add-ons
+     * read it — under the part name of its slug, then any further folders its
+     * module declares. A `dataPath` that is the instance data folder, or holds
+     * it, is never one: a restore would swap the whole site's data.
+     */
+    private addonFolders;
+    /** Each loaded add-on's `dataPath` and declared folders (#1985), in load order: what BackupManager backs up for it. */
+    addonBackupFolders(): Array<{
+        slug: string;
+        dataPath: string | null;
+        folders: BackupFolder[];
+    }>;
     /**
      * Get add-on specific configuration
      */
@@ -671,16 +708,31 @@ declare class AddonsManager extends BaseManager {
      *
      * Errors are caught per-addon and logged so one bad addon cannot block
      * other addons' saves or the core-preferences save.
+     *
+     * #1603: an add-on whose switch was refused because its documents are not
+     * accepted yet (`ConsentRequiredError`) is returned, so the route can tell
+     * the person what to accept instead of the save failing silently.
      */
-    saveProfileSections(ctx: ActorContext, body: Record<string, unknown>): Promise<void>;
+    saveProfileSections(ctx: ActorContext, body: Record<string, unknown>): Promise<{
+        consentRequired: ConsentRequiredError[];
+    }>;
     /**
      * The add-ons the site's listings show (#1965): enabled, and not
      * `listed: false` in their manifest, in load order. Cheap: it calls no
      * add-on's status(), so a page can render it.
      */
     listedAddons(): AddonListing[];
-    /** #1963: the loaded add-ons whose manifest says `perPerson: true`, in load order. */
-    private perPersonAddons;
+    /**
+     * Whether `slug` is an add-on whose manifest says `perPerson: true` (#1963),
+     * loaded or still loading. ConsentManager asks it when an add-on registers
+     * documents: they guard the per-person switch, so only such an add-on has any.
+     */
+    isPerPerson(slug: string): boolean;
+    /**
+     * #1963: the loaded add-ons whose manifest says `perPerson: true`, in load
+     * order — every slug an `addon:<slug>` page audience can match (#1964).
+     */
+    perPersonAddons(): string[];
     /**
      * The per-person add-ons this subject has turned on (#1963): each loaded
      * add-on whose manifest says `perPerson: true` and whose switch, the

package/lib/src/managers/AttachmentManager.d.ts

@@ -1,6 +1,5 @@
-import BaseManager, { BackupData, type ManagerBackupOptions, type ManagerRestoreOptions, type ManagerStats } from './BaseManager.js';
+import BaseManager, { BackupData, type BackupArchiveTarget, type ManagerBackupOptions, type ManagerRestoreOptions, type ManagerStats, type SiteRestoreStaging, type StagedRestoreAtStart } from './BaseManager.js';
 import type { AttachmentFilesBackupData, AttachmentFilesBackupOutcome } from '../providers/attachmentFilesBackup.js';
-import type { PartOutcome } from '../utils/siteRestore.js';
 import { type ActorContext } from '../context/ActorContext.js';
 /**
  * Marks an error as "the audit record could not be written", not "the action
@@ -36,11 +35,11 @@ interface BaseAttachmentProvider {
     backup(): Promise<unknown>;
     restore(backupData: unknown): Promise<void>;
     /** #1876: the files themselves beside the backup document, and their staged restore. */
-    backupFiles?(directory: string, stem: string): Promise<AttachmentFilesBackupOutcome>;
-    stageFilesRestore?(providerBackup: Record<string, unknown>, files: AttachmentFilesBackupData, directory: string, siteRestore: string): Promise<{
+    backupFiles?(archive: (part: string) => BackupArchiveTarget): Promise<AttachmentFilesBackupOutcome>;
+    stageFilesRestore?(providerBackup: Record<string, unknown>, files: AttachmentFilesBackupData, readArchive: NonNullable<ManagerRestoreOptions['readArchive']>, siteRestore: SiteRestoreStaging): Promise<{
         skippedVaults: string[];
     }>;
-    takeRestoreAtStart?(): PartOutcome | null;
+    takeRestoreAtStart?(): StagedRestoreAtStart | null;
     shutdown(): Promise<void>;
     getProviderInfo(): {
         features: string[];