@jwilleke/ngdpbase-types 5.26.0 → 5.28.0

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

@@ -0,0 +1,284 @@
+/**
+ * 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';
+/**
+ * D11: the original-file choices a receiver offers, and which one is chosen
+ * when the user picks none (#2021). The import screen offers only `allowed`,
+ * and the engine refuses a run asking for any other.
+ */
+export interface IceOriginalChoices {
+    allowed: OriginalChoice[];
+    /** One of `allowed`. Default: `ngdpbase.import.engine.default-original` when allowed, else the first allowed. */
+    default?: OriginalChoice;
+}
+/** 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>;
+    /** The original-file choices this receiver offers (D11). Without it: all three. */
+    originals?: IceOriginalChoices;
+}
+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[];
+}
+/**
+ * A kept original as the ledger remembers it, with the door that kept it
+ * (a receiver's own `keepOriginal`, or `core.files`). A later run of the same
+ * fingerprint through the same door reuses it instead of keeping another copy.
+ */
+export interface LedgerOriginal extends KeptOriginal {
+    door: string;
+}
+/** 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[];
+    /** The original kept for this fingerprint, whatever became of the conversion (D11). */
+    original?: LedgerOriginal;
+}
+/**
+ * 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

@@ -121,8 +121,12 @@ export interface AddonModule {
      * "section was not rendered at all" (addon disabled mid-session, cached
      * form). Without it, absent checkbox fields look identical to "user
      * submitted no such field" and you may silently clobber stored values.
+     *
+     * `ctx` is the signed-in user's own context, forwarded from the request:
+     * pass it to your manager's door (and to the PDP) instead of rebuilding a
+     * subject from `user` (#2018).
      */
-    profileSection?(user: AddonProfileUser): Promise<AddonProfileSection | null> | AddonProfileSection | null;
+    profileSection?(user: AddonProfileUser, ctx: ActorContext): Promise<AddonProfileSection | null> | AddonProfileSection | null;
     /**
      * Optional save handler paired with `profileSection()` (#534).
      *
@@ -238,6 +242,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()`.
@@ -660,7 +677,7 @@ declare class AddonsManager extends BaseManager {
      * Result order follows registration order of the addons map so the
      * displayed section order is stable across renders.
      */
-    getProfileSections(user: AddonProfileUser): Promise<AddonProfileSectionEntry[]>;
+    getProfileSections(user: AddonProfileUser, ctx: ActorContext): Promise<AddonProfileSectionEntry[]>;
     /**
      * #1234: say at load when an addon still implements the pre-#1234 hook.
      *
@@ -676,7 +693,7 @@ declare class AddonsManager extends BaseManager {
      * `saveProfileSection()` handler (#534).
      *
      * Runs SEQUENTIALLY — each addon's read-modify-write of user preferences
-     * (typical implementation: `getUser → merge → updateUser`) must see the
+     * (`updateUser`'s function form, #2025) must see the
      * previous addon's writes. Parallel execution would create a same-snapshot
      * race where two addons read identical preferences, each merge their own
      * keys, and the second writer clobbers the first writer's changes.
@@ -715,8 +732,11 @@ declare class AddonsManager extends BaseManager {
      * 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. */
-    private perPersonAddons;
+    /**
+     * #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/AssetManager.d.ts

@@ -67,10 +67,11 @@ declare class AssetManager extends BaseManager {
     /**
      * Return all AssetRecords referenced by the given page slug.
      *
-     * O(1) index lookup + one getById() call per referenced asset.
+     * O(1) index lookup + one provider lookup per referenced asset.
      * Stale entries (asset deleted or provider removed) are silently filtered out.
+     * Nothing for a caller who may not read assets (`asset-read`, #2018).
      */
-    getAssetsForPage(slug: string): Promise<AssetRecord[]>;
+    getAssetsForPage(ctx: ActorContext, slug: string): Promise<AssetRecord[]>;
     /**
      * Remove a page's entry from the reverse index.
      * Call this when a page is deleted or renamed.
@@ -103,8 +104,11 @@ declare class AssetManager extends BaseManager {
     /**
      * Retrieve a single asset by id.  If providerId is given only that provider
      * is checked; otherwise all providers are tried in registration order.
+     * Null for a caller who may not read assets (`asset-read`, asked of the PDP
+     * with `ctx`, as FileManager asks for the public place; #2018).
      */
-    getById(id: string, providerId?: string): Promise<AssetRecord | null>;
+    getById(ctx: ActorContext, id: string, providerId?: string): Promise<AssetRecord | null>;
+    private lookup;
     /**
      * Generate or retrieve a cached thumbnail.
      * Requires the provider to declare the 'thumbnail' capability.

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

@@ -20,17 +20,34 @@
  * running count, not one per email. `send()` still rejects, so a caller with
  * a person waiting can tell them.
  *
+ * `sendTo(ctx, …, { attachments })` attaches files, a PDF from
+ * `ExportManager.htmlToPdf` for one (#1974), up to
+ * `ngdpbase.mail.attachments.max-bytes` in total. A log line names how many
+ * files and bytes, never their names or content.
+ *
  * @see docs/admin/email-setup.md for operator setup instructions
  * @see {@link https://github.com/jwilleke/ngdpbase/issues/456}
  */
 import BaseManager from './BaseManager.js';
 import type { BackupData } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
-import type { MailMessage, MailProvider } from '../mail/MailProvider.js';
+import type { MailAttachment, MailMessage, MailProvider } from '../mail/MailProvider.js';
+import type { ActorContext } from '../context/ActorContext.js';
+export type { MailAttachment } from '../mail/MailProvider.js';
 /** The degraded reason while sends fail; cleared by the next success. */
 export declare const SEND_FAILING_REASON = "outbound email is failing \u2014 see the server log and the administrator notification";
 /** Title of the administrator notice. */
 export declare const SEND_FAILING_TITLE = "Email could not be sent";
+/** An attachment the message cannot carry (#1974): refused before sending, so it is not a delivery failure. */
+export declare class AttachmentRefusedError extends Error {
+    readonly code = "ATTACHMENT_REFUSED";
+    constructor(message: string);
+}
+/** What a caller may add after the body (#1974). */
+export interface SendOptions {
+    /** Files to attach, e.g. a PDF from `ExportManager.htmlToPdf`. */
+    attachments?: MailAttachment[];
+}
 declare class EmailManager extends BaseManager implements MailProvider {
     private provider;
     private providerName;
@@ -39,6 +56,7 @@ declare class EmailManager extends BaseManager implements MailProvider {
     private noticeWindowMs;
     private notice;
     private failuresSinceSuccess;
+    private attachmentMaxBytes;
     constructor(engine: WikiEngine);
     initialize(config?: Record<string, unknown>): Promise<void>;
     /**
@@ -49,16 +67,25 @@ declare class EmailManager extends BaseManager implements MailProvider {
      */
     send(message: MailMessage): Promise<void>;
     /**
-     * Convenience wrapper — build and send a message in one call.
+     * Build and send a message in one call.
+     *
+     * @param ctx - Who is sending (security-posture P1); named in the log line when the message carries attachments
+     * @param to - Recipient address
+     * @param subject - Subject line
+     * @param text - Plain-text body
+     * @param html - Optional HTML body
+     * @param options - Attachments (#1974); their total is capped by `ngdpbase.mail.attachments.max-bytes`
      */
-    sendTo(to: string, subject: string, text: string, html?: string): Promise<void>;
+    sendTo(ctx: ActorContext, to: string, subject: string, text: string, html?: string, options?: SendOptions): Promise<void>;
     /**
      * Send without waiting, for a sender nobody is waiting on (a form's copy, a
      * reservation notice). Never rejects: a failure is already logged and
      * reported to administrators by `send()` (#1916), so there is nothing left
-     * for the caller to do with it.
+     * for the caller to do with it. An attachment over the limit is logged here.
      */
-    sendInBackground(to: string, subject: string, text: string, html?: string): void;
+    sendInBackground(ctx: ActorContext, to: string, subject: string, text: string, html?: string, options?: SendOptions): void;
+    /** Refuse attachments a mail relay would choke on, or that are not what they say. */
+    private checkAttachments;
     /** Whether sends are failing right now: degraded by a failed send, not yet cleared by a success. */
     isDeliveryFailing(): boolean;
     private reportFailure;

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

@@ -1,6 +1,16 @@
 import type { ActorContext } from '../context/ActorContext.js';
 import BaseManager from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
+import { PdfUnavailableError, type PdfJob, type PdfJobResult, type PdfOptions, type ChromiumResolution } from '../export/pdfEngine.js';
+import type { Transport } from '../http/guardedFetch.js';
+export { PdfUnavailableError };
+export type { PdfOptions, PdfMargin, PdfPageSize } from '../export/pdfEngine.js';
+/**
+ * The needs-attention reason while PDF export has no engine (#1974). Set only
+ * when something asked for a PDF and could not have one; cleared by the next
+ * render that works.
+ */
+export declare const PDF_UNAVAILABLE_REASON = "PDF export unavailable: choose a PDF provider (local-chrome or chrome-service) in ngdpbase.export.pdf.provider, or fix the one chosen (the server log says why)";
 /**
  * Export file metadata interface
  */
@@ -41,6 +51,14 @@ export interface PageForExport {
 }
 declare class ExportManager extends BaseManager {
     private exportDirectory;
+    /** What the providers call out to; replaced in tests. A site never sets these. */
+    protected pdfRenderer: (job: PdfJob) => Promise<PdfJobResult>;
+    protected chromiumResolver: (configuredPath: string) => Promise<ChromiumResolution>;
+    protected pdfServiceTransport: Transport | undefined;
+    protected pdfNormalizer: (pdf: Uint8Array, timeoutMs: number) => Promise<Uint8Array>;
+    /** Renders running now, and renders waiting for a slot (`ngdpbase.export.pdf.max-concurrent`). */
+    private pdfActive;
+    private pdfWaiting;
     /**
      * Creates a new ExportManager instance
      *
@@ -70,6 +88,50 @@ declare class ExportManager extends BaseManager {
      * @returns The CSV document
      */
     toCsv(headers: readonly string[], rows: readonly (readonly unknown[])[]): string;
+    /**
+     * A rendered HTML document (print CSS and all) as PDF bytes (#1974).
+     *
+     * - __A provider renders it:__ `ngdpbase.export.pdf.provider` — `none`
+     *   (default), `local-chrome` (a Chromium on this machine) or
+     *   `chrome-service` (a Chromium service by URL, e.g. Gotenberg); see
+     *   `src/export/PdfProvider.ts`. Read on every render, so a change applies
+     *   without a restart.
+     * - __Sandboxed:__ `local-chrome` runs Chromium with JavaScript off and every
+     *   request refused except `data:` URIs, so images, stylesheets and fonts
+     *   must be inlined. A `chrome-service` is reached through the egress policy,
+     *   and what its Chromium may load is the service's own setting.
+     * - __Deterministic:__ the same HTML on the same core version, provider and
+     *   engine version gives the same bytes (no dates, no random ID), so an
+     *   add-on can store the document's SHA-256.
+     * - __Off the request path:__ a local render, and the metadata pass on a
+     *   service's PDF, each run in a child process; everything is bounded by
+     *   `ngdpbase.export.pdf.timeout-ms`, and at most
+     *   `ngdpbase.export.pdf.max-concurrent` run at once while the rest wait.
+     * - __Optional:__ with no engine (provider `none`, or the chosen one cannot
+     *   be used) it throws `PdfUnavailableError` (`code: 'PDF_UNAVAILABLE'`),
+     *   logs why, and this manager shows "needs attention" on the admin
+     *   dashboard until a render works. A site that never asks for a PDF is
+     *   never flagged.
+     *
+     * Records no audit event: it reads nothing and changes nothing. The caller
+     * that issues the document records that, with its own event.
+     *
+     * @param ctx - Who is asking; named in the log line
+     * @param html - A complete HTML document
+     * @param options - Page size, margins, printBackground; an `@page` rule in the HTML wins
+     * @returns The PDF
+     */
+    htmlToPdf(ctx: ActorContext, html: string, options?: PdfOptions): Promise<Buffer>;
+    /**
+     * The provider `ngdpbase.export.pdf.provider` names, built for this render
+     * from the current settings. A name that is not a provider is unavailable,
+     * with the reason, as `none` is.
+     */
+    private pdfProvider;
+    /** Log why, flag the manager (unless something worse is already shown), and refuse. */
+    private pdfUnavailable;
+    private acquirePdfSlot;
+    private releasePdfSlot;
     /**
      * Initialize the ExportManager
      *