@jwilleke/ngdpbase-types 5.40.0 → 5.41.1

package/lib/packages/media-date/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Filename → capture-date parser, the one implementation of it.
+ *
+ * ngdpbase uses it when a media file carries no usable EXIF/QuickTime date, and
+ * mjs-media-handling uses a built copy of it to place and stamp files. Both must read a name the same way, which is why it is one package.
+ *
+ * It is a pure function of the name: no filesystem, no network, no server.
+ *
+ * Missing parts are filled with fixed, documented values — see FAKE_MONTH below
+ * and README.md. Callers that must know what was real read `parseFilenameDate`,
+ * whose `month`/`day`/`time` are null where the name did not carry them.
+ */
+/** Written when the name gives a year but no month. */
+export declare const FAKE_MONTH = 6;
+/** Written when the name gives no day of the month. */
+export declare const FAKE_DAY = 15;
+/** Written when the name gives no time of day. */
+export declare const FAKE_TIME = "11:59:00";
+/** What a filename said, with null for each part it did not say. */
+export interface FilenameDate {
+    year: number;
+    month: number | null;
+    day: number | null;
+    /** `HH:MM:SS`, only when the name carried a valid time. */
+    time: string | null;
+    /** Which rule matched, e.g. `filename:YYYY-MM-DD`. */
+    source: string;
+}
+/** What the name itself says, nothing filled in. Null when it says nothing. */
+export declare function parseFilenameDate(filename: string): FilenameDate | null;
+/** `YYYY-MM-DD HH:MM:SS`, with FAKE_MONTH, FAKE_DAY and FAKE_TIME where missing. */
+export declare function fillFilenameDate(date: FilenameDate): string;
+/** The capture date a filename gives, filled in; null when it gives none. */
+export declare function parseDateFromFilename(filename: string): string | null;

package/lib/packages/ngdpbase-types/index.d.ts

@@ -40,7 +40,7 @@ export type { PageAction } from '../../src/utils/pageUrl.js';
 export type { default as ConsentManager, ConsentScopeStatus } from '../../src/managers/ConsentManager.js';
 export type { AddonConsentRegistration, ConsentDocument, ConsentRecord, ConsentRequiredError, ConsentScope, ConsentSeen, ConsentStatus } from '../../src/types/Consent.js';
 export type { default as ImportManager } from '../../src/managers/ImportManager.js';
-export type { IceShim, IceReceiver, IceItem, IceKind, IceWarning, ShimDirection, ShimAccepts, ShimTools, ShimReadResult, ReceiveInfo, ReceiveOutcome, IceCitation, KeptOriginal, OriginalChoice, IceOriginalChoices, OriginalKeep, IceUpload, IceSource, IceUrlSource, IceRunRequest, IceRecordData, FileDoneInfo, IceRunReport, IceFileReport, IceFileStatus, RecentImport } from '../../src/ice/types.js';
+export type { IceShim, IceReceiver, IceItem, IceKind, IceWarning, ShimDirection, ShimAccepts, ShimTools, ShimReadResult, ReceiveInfo, ReceiveOutcome, IceCitation, KeptOriginal, OriginalChoice, IceOriginalChoices, OriginalKeep, IceUpload, IceSource, IceUrlSource, IceRunRequest, IceRecordData, FileDoneInfo, IceTarget, IceArchiveView, IceRunReport, IceFileReport, IceFileStatus, RecentImport } from '../../src/ice/types.js';
 export type { default as UserManager, UserUpdateInput, UserUpdateFn } from '../../src/managers/UserManager.js';
 export type { User, UserPreferences } from '../../src/types/User.js';
 export type { default as AuthManager, InviteOutcome, InvitationView } from '../../src/managers/AuthManager.js';

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

@@ -41,8 +41,13 @@ export declare function isZip(upload: IceUpload): boolean;
  * with the type its request gave it. Limits are per archive (`ZipReadLimits`), so a small
  * archive that expands enormously stops at the budget. An archive that cannot
  * be read is returned in `unreadable`, with why; the rest go on.
+ *
+ * With `innerZipsAsFiles` (#2118), only the uploads themselves are unpacked:
+ * a zip inside one is passed on as a file, like any other member.
  */
-export declare function expandUploads(uploads: readonly IceUpload[], limits: ZipReadLimits, maxDepth: number, depth?: number): {
+export declare function expandUploads(uploads: readonly IceUpload[], limits: ZipReadLimits, maxDepth: number, options?: {
+    innerZipsAsFiles?: boolean;
+}, depth?: number): {
     files: IceUpload[];
     unreadable: Array<{
         name: string;

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

@@ -0,0 +1,41 @@
+import type { ExportShimTools, IceItem, IceKind, RegisteredShim } from './types.js';
+/** Core's page export source: pages, read through PageManager's door. */
+export declare const PAGES_EXPORT_SOURCE = "core.pages";
+/** Configuration an export reads (each a key under `ngdpbase.export.engine.`). */
+export interface IceExportSettings {
+    /** The most bytes an export's source, or any step of its chain, may hold. */
+    maxBytes: number;
+    /** The most shims one export runs through (`ngdpbase.import.engine.max-chain-depth`, shared with import). */
+    maxChainDepth: number;
+}
+/** An export that cannot be made, with the reason a user is shown. */
+export declare class IceExportFailed extends Error {
+    constructor(message: string);
+}
+/**
+ * The formats that can be made from items of this kind: for each `out`
+ * shim that makes a file, the shortest chain of `out` shims that reaches it
+ * from `kind`, at most `maxChainDepth` long. Shims are tried in registration
+ * order, so between two chains of one length the first registered wins.
+ *
+ * @returns The file-making shim's id → the chain, ending with it
+ */
+export declare function exportChains(shims: readonly RegisteredShim[], kind: IceKind, maxChainDepth: number): Map<string, RegisteredShim[]>;
+/** The bytes items hold, their text counted as UTF-8. */
+export declare function exportSize(items: readonly IceItem[]): number;
+/**
+ * Refuse items larger than the export limit.
+ *
+ * @throws IceExportFailed when they are
+ */
+export declare function checkExportSize(items: readonly IceItem[], maxBytes: number): void;
+/**
+ * Run the source's items through the chain, each shim's output the next
+ * one's input, and return the one file the last shim made. What came before
+ * travels with each item while a shim keeps the count: earlier metadata
+ * under later, as an import's chain does.
+ *
+ * @throws IceExportFailed when a step holds more than `maxBytes`, a shim
+ *   makes something other than what it declares, or the end is not one file
+ */
+export declare function runExportChain(items: IceItem[], chain: readonly RegisteredShim[], tools: (shim: RegisteredShim) => ExportShimTools, settings: IceExportSettings): Promise<IceItem>;

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

@@ -41,10 +41,11 @@ export declare const SCOPE_FORM = "ice2";
  * The scope a run's fingerprints, per-file status and item keys live in
  * (#2013): bound to the receiver and to the user the run is for, by their
  * identity `@id` (else their username, #2041). The engine works it out from
- * the caller's context; a request cannot name another user's. A caller's own
- * `sub` (phr's source id) narrows it within that user's scope, never outside.
+ * the caller's context; a request cannot name another user's. What follows
+ * narrows it within that user's scope, never outside: the place within the
+ * receiver (#2118), then a caller's own sub-scope (phr's source id).
  */
-export declare function boundScope(receiverId: string, owner: string, sub?: string): string;
+export declare function boundScope(receiverId: string, owner: string, ...subs: Array<string | undefined>): string;
 /** Does this shim list the receiver, by id or as any receiver (`'*'`, #2109)? */
 export declare function handsTo(shim: Pick<RegisteredShim, 'receivers'>, receiverId: string): boolean;
 export interface ChainLeaf {
@@ -64,9 +65,10 @@ export interface ChainSpec {
 /**
  * Run a shim, then the shims after it (D9), until each item is done. What
  * came before travels with each item: earlier metadata under later, earlier
- * warnings first. Partial notes are collected into `partial`.
+ * warnings first. Partial notes are collected into `partial`; a shim's note
+ * that the file holds nothing to import on its own (#2118) into `skipped`.
  */
-export declare function convertChain(shim: RegisteredShim, input: IceItem, chain: string[], spec: ChainSpec, partial: string[]): Promise<ChainLeaf[]>;
+export declare function convertChain(shim: RegisteredShim, input: IceItem, chain: string[], spec: ChainSpec, partial: string[], skipped?: string[]): Promise<ChainLeaf[]>;
 /**
  * The name the user gave this file (#2130), as the engine applies it: none
  * when the receiver names things itself (it declares no `names`) or the user
@@ -85,6 +87,13 @@ export declare function resolveGivenName(upload: IceUpload, receiver: Registered
 export declare function receiverLink(receiver: RegisteredReceiver, ref: string | undefined, ctx: ActorContext): Promise<string | undefined>;
 /** What a file's status says when a name the user gave was not applied: the file is already here under another (#2130). */
 export declare function alreadyHereAs(name: string): string;
+/**
+ * Is an import into this receiver confidential (#2110)? Only when its
+ * destination is encrypted: a receiver that keeps into a sealed store
+ * (`keepsEncrypted`), or whose own door writes into one (`writesEncrypted`,
+ * #2118). No receiver can declare itself so otherwise.
+ */
+export declare function isConfidentialReceiver(receiver: Pick<RegisteredReceiver, 'keepsEncrypted' | 'writesEncrypted'> | undefined): boolean;
 /** Does this run keep its originals during the upload (#2034)? */
 export declare function keepsAtUpload(receiver: RegisteredReceiver | undefined, original: OriginalChoice): boolean;
 /** What keeping at upload did: how many it kept, or the first file it could not keep. */
@@ -110,10 +119,10 @@ export interface UploadKeepResult {
  * then queues nothing. Originals kept before it stay kept, and recorded, so
  * the next try reuses them.
  */
-export declare function keepOriginalsAtUpload(deps: IceRunDeps, request: IceRunRequest, ctx: ActorContext, scope: string): Promise<UploadKeepResult>;
+export declare function keepOriginalsAtUpload(siteDeps: IceRunDeps, request: IceRunRequest, ctx: ActorContext, scope: string): Promise<UploadKeepResult>;
 /**
  * Run one import. Fills and returns `report`, which the caller may be
  * showing while it runs. Never throws for one file's failure; that file's
  * status says why.
  */
-export declare function runImport(deps: IceRunDeps, request: IceRunRequest, ctx: ActorContext, report: IceRunReport): Promise<IceRunReport>;
+export declare function runImport(siteDeps: IceRunDeps, request: IceRunRequest, ctx: ActorContext, report: IceRunReport): Promise<IceRunReport>;

package/lib/src/ice/shims/csv.d.ts

@@ -54,6 +54,30 @@ export declare function parseCsv(text: string, delimiter?: string, skipLines?: n
  * invisible one.
  */
 export declare function preambleSuspicion(columns: readonly string[]): string | null;
+/**
+ * Clean CSV text before it is kept as a file (#2149): HTML is taken out of
+ * every cell, and a cell a spreadsheet would run as a formula gets a leading
+ * `'`, so it shows as text (the usual CSV-injection defence). Only the cells
+ * that change are rewritten, quoted; every other byte is kept as it was.
+ * Returns how many cells of each kind were cleaned.
+ */
+export declare function cleanCsvText(text: string, delimiter?: string): {
+    text: string;
+    html: number;
+    formulas: number;
+};
+/**
+ * How a CSV is read and written back for cleaning (#2149), so its bytes stay
+ * its own: UTF-16 with a byte-order mark as UTF-16; valid UTF-8 as UTF-8;
+ * anything else (Latin-1, Windows-1252 and the like) one byte to one
+ * character and back, which round-trips every byte exactly. The characters
+ * cleaning looks for (`, " < > = + - @`, tab, line ends) are ASCII, the same
+ * byte in each of these.
+ */
+export declare function csvEncoding(bytes: Buffer): {
+    text: string;
+    encode: (text: string) => Buffer;
+};
 /** One row as a record: its own id, or one synthesized from its content. */
 export declare function csvRecord(raw: RawRecord, opts: RecordShimOptions): IceRecordData | null;
 export declare const csvShim: IceShim;

package/lib/src/ice/shims/export.d.ts

@@ -0,0 +1,23 @@
+import type { ActorContext } from '../../context/ActorContext.js';
+import { type IceItem, type IceShim } from '../types.js';
+/** The core doors the export shims call. */
+export interface ExportShimDoors {
+    /** A complete HTML document for one NCM item (ExportManager's page document). */
+    renderDocument(item: IceItem): Promise<string>;
+    /** HTML → PDF (ExportManager.htmlToPdf), as the run's user. */
+    htmlToPdf(ctx: ActorContext, html: string): Promise<Buffer>;
+    /** Is a PDF provider chosen? */
+    pdfAvailable(): boolean;
+}
+/** A file name from a title: the title, with what no file system takes replaced. */
+export declare function exportFileName(item: IceItem, extension: string): string;
+/**
+ * The HTML with nothing in it that a renderer would fetch (#2120): only
+ * `data:` URLs are left, in attributes and in CSS. The local renderer
+ * already blocks the network; a remote one (`chrome-service`, Gotenberg)
+ * fetches what the HTML names, from where it runs, so this is done before
+ * the HTML leaves the process. Links (`<a href>`) stay: printing never
+ * follows them.
+ */
+export declare function withoutRemoteUrls(html: string): string;
+export declare function exportShims(doors: ExportShimDoors): IceShim[];

package/lib/src/ice/shims/index.d.ts

@@ -12,5 +12,7 @@
  * receiver that takes records (`receivers: ['*']`).
  */
 import type { IceShim } from '../types.js';
-/** Every record shim, in registration order. */
+/** Every record shim, in registration order. `core.csv` also cleans a CSV kept as a file (#2149). */
 export declare const RECORD_SHIMS: readonly IceShim[];
+/** Shims that only vet a file kept as a file (#2149): they clean and are never picked for a run. */
+export declare const VETTING_SHIMS: readonly IceShim[];

package/lib/src/ice/shims/svg.d.ts

@@ -0,0 +1,27 @@
+/**
+ * svg shim (#2149): cleans an SVG before it is kept as a file. An SVG is a
+ * document, not a picture: it can carry scripts, HTML inside
+ * `<foreignObject>`, `on…` event handlers, script links and animations that
+ * set a link. The file is parsed and rebuilt from an allow-list of SVG
+ * elements and attributes, never patched with patterns: what the parser did
+ * not take as an allowed element or attribute is not written back. The note
+ * says what kind of thing was removed and how many, never the content.
+ *
+ * The parser is the one the site already uses for author HTML
+ * (`src/rendering/htmlPolicy.ts`): sanitize-html on htmlparser2, here in XML
+ * mode so names keep their case. This file only configures it for SVG.
+ *
+ * Defence in depth, not the boundary: an uploaded file is always served
+ * sandboxed (`untrustedFileHeaders`, #1624), so nothing in it runs as the
+ * site. Cleaning keeps a file that is downloaded, embedded elsewhere or
+ * opened outside the site from carrying it.
+ *
+ * A vetting shim only (`clean`, no `read`): never picked for an import run.
+ */
+import type { IceShim, IceWarning } from '../types.js';
+/** The cleaned text and what was removed: the pure step behind the shim. */
+export declare function cleanSvgText(text: string): {
+    text: string;
+    removed: IceWarning[];
+};
+export declare const svgShim: IceShim;

package/lib/src/ice/shims/takeout.d.ts

@@ -0,0 +1,83 @@
+/**
+ * `core.takeout` (#2118, ICE #1979): a download of a private store (#1387)
+ * handed back, into its owner's private store (`core.private-store`). It
+ * replaces the takeout import's own path (#1472).
+ *
+ * The engine unpacks the zip and hands each member here on its own, with the
+ * archive beside it (`IceItem.archive`); this shim reads the takeout's
+ * layout through that. What a takeout is, as #1387 writes it: one `{store}/`
+ * folder holding each page as `{title}.md` with full frontmatter, files under
+ * `attachments/`, and `files-index.json` mapping each file's id to its path
+ * in the archive. The reader is lenient about the one thing people change,
+ * the folder: someone who extracts a takeout and zips it again may add a
+ * level, or zip the contents with no folder at all, so the takeout's root is
+ * found rather than assumed.
+ *
+ * - A page (`.md` directly in the root) is one `takeout` item: its body as
+ *   text, and in `data` its title, uuid and frontmatter, and the files of
+ *   the takeout its body links to (`/attachments/{old id}`), so the
+ *   receiver can store those first and point the links at their new ids.
+ * - A file (directly in `attachments/`) is one `takeout` item: its bytes,
+ *   and in `data` its old id, name, media type and description from the index.
+ * - The file index is read through the archive by the members it names; on
+ *   its own it holds nothing to import (`skip`). So does anything else in
+ *   the archive: versions, the trash, footnotes and comments are not brought
+ *   back, as before.
+ *
+ * Pure: no I/O, no access decision, no write. The receiver's door does those.
+ */
+import type { IceShim } from '../types.js';
+/** The kind this shim produces: one page or one file of a takeout. */
+export declare const TAKEOUT_KIND = "takeout";
+/** The receiver a takeout goes into: its owner's private store. */
+export declare const PRIVATE_STORE_RECEIVER = "core.private-store";
+/** A file of the takeout that a page links to, found through the archive. */
+export interface TakeoutLinkedFile {
+    /** Its id where it came from: what the page's links name. */
+    oldId: string;
+    /** Its path in the archive. */
+    path: string;
+    name: string;
+    encodingFormat?: string;
+    description?: string;
+}
+/** A page of a takeout: the `data` of its item; the body is the item's `text`. */
+export interface TakeoutPageData {
+    entry: 'page';
+    /** From the frontmatter, else the file's name. */
+    title: string;
+    /** From the frontmatter. Absent for a page written by hand. */
+    uuid?: string;
+    /** The frontmatter, as written. */
+    metadata: Record<string, unknown>;
+    /** The takeout's files its body links to. */
+    files: TakeoutLinkedFile[];
+}
+/** A file of a takeout: the `data` of its item; the bytes are the item's `bytes`. */
+export interface TakeoutFileData {
+    entry: 'file';
+    /** Its id where it came from, when the file index names it. */
+    oldId?: string;
+    /** The name it was uploaded with. */
+    name: string;
+    encodingFormat?: string;
+    description?: string;
+}
+export type TakeoutData = TakeoutPageData | TakeoutFileData;
+/**
+ * The folder the takeout lives in: the one holding the file index, else the
+ * shallowest one holding a page. `''` is the archive's own root.
+ */
+export declare function takeoutRoot(paths: readonly string[]): string;
+/** `body` with every `/attachments/{old}` link pointed at its new id. */
+export declare function rewriteAttachmentLinks(body: string, ids: ReadonlyMap<string, string>): string;
+/** Whether `body` links to the file `id`. */
+export declare function linksToAttachment(body: string, id: string): boolean;
+/**
+ * The first free title of `title`, `title (imported)`, `title (imported 2)` …
+ * (operator, 2026-09-25): a DIFFERENT page already holding the title keeps
+ * it, and the import lands beside it.
+ */
+export declare function freeImportTitle(title: string, isTaken: (candidate: string) => Promise<boolean>): Promise<string>;
+/** The takeout shim: every member of a zip, read as a takeout's layout says. */
+export declare const takeoutShim: IceShim;