@jwilleke/ngdpbase-types 5.37.0 → 5.39.0

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

@@ -15,6 +15,7 @@
  * only, so the published entry carries no JavaScript.
  */
 export type { AddonModule, AddonManifest, AddonListing } from '../../src/managers/AddonsManager.js';
+export type { AddonDashboardCard, AddonCardSurface, AddonCardSummary, AddonCardFigure } from '../../src/managers/AddonsManager.js';
 export type { AddonHost, AddonIceDeclaration, PersonSwitchSetter } from '../../src/utils/addonHost.js';
 export type { WikiEngine } from '../../src/types/WikiEngine.js';
 export type { ApiContext } from '../../src/context/ApiContext.js';
@@ -39,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, IceRunRequest, IceRunReport, IceFileReport, IceFileStatus } 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, 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/ledger.d.ts

@@ -25,6 +25,8 @@ declare abstract class ScopedLedger implements IceLedger {
     recordFile(scope: string, entry: LedgerFileEntry): Promise<void>;
     hasItem(scope: string, itemKey: string): Promise<boolean>;
     recordItem(scope: string, itemKey: string): Promise<void>;
+    seenItems(scope: string, itemKeys: string[]): Promise<Set<string>>;
+    recordItems(scope: string, itemKeys: string[]): Promise<void>;
     files(scope: string): Promise<LedgerFileEntry[]>;
 }
 /** The ledger in memory: for tests, and for a site that keeps no import history. */

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

@@ -9,6 +9,8 @@ export interface IceEngineSettings {
     maxFileBytes: number;
     maxChainDepth: number;
     defaultOriginal: OriginalChoice;
+    /** The largest response a URL source may return (#2109). */
+    fetchMaxBytes: number;
 }
 export interface IceRunDeps {
     /** Enabled shims, in registration order. */
@@ -17,6 +19,8 @@ export interface IceRunDeps {
     ledger: IceLedger;
     settings: IceEngineSettings;
     tools(shim: RegisteredShim): ShimTools;
+    /** The engine's guarded fetch, for a URL source (#2109): the same one `tools` hands shims. */
+    fetch?: ShimTools['fetch'];
     now?: () => Date;
 }
 /** The id of the receiver that keeps an original when the chosen receiver does not keep its own (D11). */
@@ -39,6 +43,8 @@ export declare const SCOPE_FORM = "ice2";
  * `sub` (phr's source id) narrows it within that user's scope, never outside.
  */
 export declare function boundScope(receiverId: string, owner: string, sub?: string): 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 {
     item: IceItem;
     chain: string[];

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

@@ -0,0 +1,59 @@
+/**
+ * csv shim (#685 slice 4+, #911; a core shim since #2109) — zero dependency (a
+ * small RFC 4180 parser). Needed for sources that only publish CSV, e.g. NASA
+ * FIRMS thermal hotspots (geohazardwatch#4), whose `/api/area/csv/...`
+ * endpoint has no JSON/GeoJSON/XML variant.
+ *
+ * Nothing in it is about feeds, so any receiver of records can use it (a
+ * bank statement as well as a feed). The first row is the header; each
+ * subsequent row becomes one `record` item keyed by the header column names
+ * (all values are strings — `map`/dot-path and the downstream schema
+ * mappers cast as needed, exactly as for the other shims).
+ *
+ * Rows rarely carry an `id` column, so when neither the `recordIdField`
+ * option nor an `id` field resolves, a stable content hash of the row is
+ * synthesized as the id — order-independent (keys sorted) so a column
+ * reorder upstream doesn't churn ids, and content-addressed so
+ * change-detection still works.
+ *
+ * Delimiter defaults to `,`; override with the `delimiter` option (e.g. `\t`).
+ *
+ * The `skipLines` option skips N leading lines before the header (#1102).
+ * Some sources — government data exports especially — emit a human-readable
+ * caption above the real header. Without skipping it, the caption becomes
+ * the sole column name, the real header is consumed as the first record,
+ * and every column but the first is discarded. That failure is entirely
+ * silent: HTTP 200, a successful parse, records stored, and a table of empty
+ * values. Hence {@link preambleSuspicion}, which makes it visible (a warning
+ * on the read) without blocking it.
+ */
+import { type IceRecordData, type IceShim } from '../types.js';
+import { type RecordShimOptions, type RawRecord } from './record.js';
+/**
+ * Parse CSV text into header-keyed row objects. RFC 4180 subset: quoted fields,
+ * escaped quotes (`""`), embedded commas/newlines inside quotes, CRLF/CR/LF line
+ * endings, and a leading UTF-8 BOM. Values are returned verbatim (strings);
+ * header cells are trimmed. Fully-empty lines are skipped.
+ *
+ * `skipLines` drops that many leading lines before the header is taken, for
+ * feeds with a caption preamble (#1102). Default 0 — byte-identical to the
+ * previous behaviour.
+ */
+export declare function parseCsv(text: string, delimiter?: string, skipLines?: number): Record<string, string>[];
+/**
+ * Return the suspect header when a parse looks like it consumed an unskipped
+ * preamble, or `null` when it looks fine (#1102).
+ *
+ * The signature of the failure is a single column whose name reads like a
+ * sentence: a caption line has no delimiter in it, so the whole line becomes one
+ * field. A legitimate single-column CSV has a short, word-like header, so the
+ * two are distinguishable in practice.
+ *
+ * Deliberately advisory. A one-column CSV is legal, just unusual, and a caller
+ * that guessed and re-parsed would only trade a visible wrong answer for an
+ * invisible one.
+ */
+export declare function preambleSuspicion(columns: readonly string[]): string | null;
+/** 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/dotpath.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Trivial dot-path lookup (#685) — the only "mapping engine" the framework has.
+ * NO JSONPath dependency (design §7): `getByPath(obj, 'properties.mag')`,
+ * `getByPath(obj, 'geometry.coordinates.2')` (numeric segment = array index).
+ * Returns undefined for any missing segment.
+ */
+export declare function getByPath(obj: unknown, path: string): unknown;

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

@@ -0,0 +1,19 @@
+/**
+ * GeoJSON shim (#685 slice 4; a core shim since #2109) — zero dependency (JSON.parse).
+ *
+ * Handles a GeoJSON FeatureCollection (`{ features: [...] }`), a bare array of
+ * features, or a single Feature. Per feature, the id comes from the
+ * `recordIdField` option (dot-path) or the feature's own `id`; properties come
+ * from the `map` option (dot-path per field) or, with no map, the feature's
+ * `properties` object.
+ *
+ * Reference feed: the USGS earthquakes GeoJSON
+ * (https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/4.5_week.geojson).
+ */
+import { type IceRecordData, type IceShim } from '../types.js';
+import { type RecordShimOptions, type RawRecord } from './record.js';
+/** The features of a GeoJSON document. */
+export declare function geojsonFeatures(data: unknown): RawRecord[];
+/** One feature as a record. With no map, the feature's own `properties` object is lifted. */
+export declare function geojsonRecord(raw: RawRecord, opts: RecordShimOptions): IceRecordData | null;
+export declare const geojsonShim: IceShim;

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

@@ -0,0 +1,16 @@
+/**
+ * Core's record shims (#2109; moved into core by the operator's decision of
+ * 2026-10-29, "generic work goes to core"): one per structured format,
+ * registered by ImportManager as `core.<name>`, so any receiver that takes
+ * records can use them, with no add-on enabled. The feeds add-on was their
+ * first user and names one per source as its `adapter`; accounting's bank
+ * statements (#2121) are the next.
+ *
+ * Shipped: geojson + rest-json (zero-dep), xml (fast-xml-parser), csv
+ * (zero-dep, #911), rss-atom (#913, xml-based) and xml-index (#912, two-phase).
+ * Each produces `record` items with per-item duplicates and hands to any
+ * receiver that takes records (`receivers: ['*']`).
+ */
+import type { IceShim } from '../types.js';
+/** Every record shim, in registration order. */
+export declare const RECORD_SHIMS: readonly IceShim[];

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

@@ -0,0 +1,68 @@
+/**
+ * What core's record shims share (#685 slice 8; core shims since #2109): the
+ * options a run hands its shim, turning one raw item into a `record` item,
+ * and the item's key.
+ *
+ * Nothing here is about any one receiver. A record shim reads one format
+ * into `record` items (`data` is `{ id, properties }`, `IceRecordData`); which
+ * receiver takes them, and what it does with them, is the receiver's
+ * business. So the same CSV shim serves a feed (the feeds add-on's
+ * `feeds.items`) and a bank-statement import alike, with neither add-on's
+ * code (operator, 2026-10-29: generic work goes to core).
+ *
+ * id ← the `recordIdField` option (dot-path) or the item's own `id`.
+ * properties ← the `map` option (dot-path per field), or — with no map — the
+ * supplied `defaultProps` object (geojson lifts `feature.properties`;
+ * rest-json lifts the item itself). No id resolves → no record (skipped).
+ */
+import type { IceItem, IceRecordData, IceWarning } from '../types.js';
+/** One raw item straight off the wire (a GeoJSON feature, an RSS item, a CSV row, …). */
+export type RawRecord = Record<string, unknown>;
+/** The kind every record shim produces: core's generic record (#2109). */
+export declare const RECORD_KIND = "record";
+/**
+ * A record shim's options (#2109): the site's `ngdpbase.import.shims.<id>.options`,
+ * with the run's own over them (a feed source's settings, an import's).
+ * Each is optional and generic: where the items are, which field is the id,
+ * a field map, and the few format settings (CSV's delimiter and preamble, an
+ * index's links).
+ */
+export interface RecordShimOptions {
+    /** Dot-path to each item's id. */
+    recordIdField?: string;
+    /** Dot-path map: property → source path. */
+    map?: Record<string, string>;
+    /** Dot-path to the items array (rest-json, xml, rss-atom, xml-index). */
+    itemsPath?: string;
+    /** csv: the field delimiter. Default ','. */
+    delimiter?: string;
+    /** csv: lines skipped before the header (#1102). Default 0. */
+    skipLines?: number;
+    /** xml-index: a regex matched against the index's hrefs. */
+    linkPattern?: string;
+    /** xml-index: the most item documents fetched in one run. */
+    maxItems?: number;
+}
+/**
+ * The options as a shim reads them: each of the right type, or absent. The
+ * caller (a feed's configuration) validated its own; this only refuses a
+ * value of the wrong type from anywhere.
+ */
+export declare function recordOptions(raw: Record<string, unknown>): RecordShimOptions;
+export declare function buildRecord(raw: RawRecord, opts: RecordShimOptions, defaultProps: Record<string, unknown> | undefined): IceRecordData | null;
+/**
+ * The key the engine knows a record by (per-item duplicates, #2109): its own
+ * id with a hash of its content. The id alone would skip a record that
+ * changed upstream under the same id (a revised advisory), so the hash is
+ * the version. A receiver's own duplicate check is still its own (the feeds
+ * add-on compares the hash its record store keeps).
+ */
+export declare function recordItemKey(rec: IceRecordData): string;
+/** The `record` items of one read, from its records in order; null records (no id) are dropped. */
+export declare function recordItems(input: IceItem, records: Array<IceRecordData | null>, warnings?: IceWarning[]): IceItem[];
+/**
+ * Locate the items array in a JSON response when no explicit `itemsPath` is
+ * configured: the body itself if it's an array, else the first array found
+ * under common envelope keys, else any array-valued property, else [].
+ */
+export declare function pickItemsArray(data: unknown): unknown[];

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

@@ -0,0 +1,14 @@
+/**
+ * rest-json shim (#685 slice 8; a core shim since #2109) — zero dependency (JSON.parse).
+ *
+ * Generic REST GET → JSON. Locates the items array via the `itemsPath` option
+ * (dot-path, e.g. 'results' or 'data.events'); with none, falls back to the
+ * body itself if it's an array, or the first array under a common envelope
+ * key (results/data/items/records). Each item IS the record (its own fields
+ * are lifted as properties when no `map` is set).
+ */
+import { type IceShim } from '../types.js';
+import { type RawRecord } from './record.js';
+/** The items of a JSON document: at `itemsPath`, or the first likely array. */
+export declare function jsonItems(data: unknown, itemsPath: string | undefined): RawRecord[];
+export declare const restJsonShim: IceShim;

package/lib/src/ice/shims/rss-atom.d.ts

@@ -0,0 +1,22 @@
+/**
+ * rss-atom shim (#913; a core shim since #2109) — dependency: fast-xml-parser
+ * (shared with the xml shim). RSS 2.0 and Atom 1.0 are both XML, so this is a
+ * thin, sensible-default wrapper over the shared XML machinery rather than a
+ * separate parser.
+ *
+ * Item location (when the `itemsPath` option is not set):
+ *   - RSS 2.0 → `rss.channel.item`
+ *   - Atom 1.0 → `feed.entry`
+ *   - else the generic envelope detection (pickItemsArray)
+ *
+ * Id resolution (when `recordIdField` is not set): RSS `<guid>` → `<link>`;
+ * Atom `<id>` → `<link href>`. guid/link may parse as objects (guid with
+ * `@isPermaLink`, Atom link as an attribute-only element) — both are unwrapped.
+ */
+import { type IceRecordData, type IceShim } from '../types.js';
+import { type RecordShimOptions, type RawRecord } from './record.js';
+/** The items of an RSS or Atom document. */
+export declare function rssAtomItems(text: string, itemsPath: string | undefined): RawRecord[];
+/** One RSS item or Atom entry as a record. */
+export declare function rssAtomRecord(raw: RawRecord, opts: RecordShimOptions): IceRecordData | null;
+export declare const rssAtomShim: IceShim;

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

@@ -0,0 +1,32 @@
+/**
+ * xml-index shim (#912; a core shim since #2109) — dependency: fast-xml-parser
+ * (shared with the xml shim). For "index page + N item documents, no
+ * combined feed" sources common to bulletin-style publishers (e.g. Washington
+ * VAAC ash advisories, geohazardwatch#5): an HTML/text index links to many
+ * separately-fetchable per-record XML files, with no single URL returning
+ * them all.
+ *
+ * Two phases:
+ *   1. The index is the file the engine hands it (a URL source, fetched by the
+ *      engine). Item URLs are the hrefs matching the `linkPattern` option (a
+ *      regex string), resolved against the index's URL (`metadata.sourceUrl`,
+ *      else the file's name). Deduped, capped at the `maxItems` option
+ *      (default 100; a site sets its own with
+ *      `ngdpbase.import.shims.core.xml-index.options.maxItems`).
+ *   2. Each item document is fetched by asking the engine (`tools.fetch`), so
+ *      every request takes the one guarded path with the source's headers
+ *      and timeout (design rule), then XML-parsed. Each yields one record (its
+ *      unwrapped root), or — with `itemsPath` — the items located in it. The
+ *      item's URL is kept as `__itemUrl` so it serves as the id when the
+ *      document has none.
+ *
+ * A single failed item fetch or parse is skipped, never failing the whole
+ * read: the read is then `partial`, saying which.
+ */
+import { type IceShim } from '../types.js';
+import { buildRecord, type RecordShimOptions, type RawRecord } from './record.js';
+/** Extract, resolve, dedupe and cap item URLs from index HTML/text. */
+export declare function extractItemUrls(html: string, baseUrl: string, linkPattern: string, maxItems: number): string[];
+/** One item document's record: `__itemUrl` is plumbing, kept out of the properties but usable as the id. */
+export declare function xmlIndexRecord(raw: RawRecord, opts: RecordShimOptions): ReturnType<typeof buildRecord>;
+export declare const xmlIndexShim: IceShim;

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

@@ -0,0 +1,30 @@
+/**
+ * xml shim (#685 slice 8; a core shim since #2109) — dependency: fast-xml-parser
+ * (itself zero-dep).
+ *
+ * Generic XML → records, for sources with no JSON surface (e.g. VAAC ash
+ * advisories, geohazardwatch#5). The document is parsed to plain objects so
+ * the existing dot-path machinery applies unchanged: locate the items array
+ * via the `itemsPath` option (e.g. 'rss.channel.item' or
+ * 'advisories.advisory'), map fields via `map` / `recordIdField`.
+ *
+ * XML-specific shape rules:
+ * - Attributes are kept, prefixed '@' — dot-path them as e.g. 'link.@href'.
+ * - Element text alongside attributes lands under '#text'.
+ * - A single repeated element parses as an object, not a 1-element array —
+ *   the shim coerces the located items to an array, so `itemsPath` behaves
+ *   identically for 1 and N items.
+ */
+import { XMLParser } from 'fast-xml-parser';
+import { type IceShim } from '../types.js';
+import { type RawRecord } from './record.js';
+/**
+ * Shared fast-xml-parser instance — reused by the rss-atom (#913) and xml-index
+ * (#912) shims so XML shape rules stay identical across all XML-based sources.
+ */
+export declare const xmlParser: XMLParser;
+/** XML parses a lone repeated element as an object — normalize to an array. */
+export declare function coerceItems(located: unknown): RawRecord[];
+/** The items of an XML document: at `itemsPath`, else under its (single) root by envelope detection. */
+export declare function xmlItems(text: string, itemsPath: string | undefined): RawRecord[];
+export declare const xmlShim: IceShim;

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

@@ -20,12 +20,16 @@
  */
 import type { ActorContext } from '../context/ActorContext.js';
 import type { GuardedFetchOptions, GuardedResponse } from '../http/guardedFetch.js';
+/** In a shim's `receivers`: any receiver that takes the kind the shim produces (#2109). */
+export declare const ANY_RECEIVER = "*";
 /** 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`.
+ * input bytes; `html` and `ncm` are core's; `record` is one structured entry
+ * of a table or feed (`data` is `{ id, properties }`, {@link IceRecordData}),
+ * so a format shim such as CSV serves any receiver that takes records (#2109);
+ * 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. */
@@ -57,6 +61,15 @@ export interface IceItem {
      */
     itemKey?: string;
 }
+/**
+ * The `data` of a `record` item (#2109): one row of a table or one entry of a
+ * feed. `id` is the entry's own id (a configured id field, the format's own
+ * id, or a hash of the row when it has none); `properties` its fields.
+ */
+export interface IceRecordData {
+    id: string;
+    properties: Record<string, unknown>;
+}
 /** 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']`. */
@@ -78,7 +91,11 @@ export interface ShimTools {
      * 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`. */
+    /**
+     * This shim's options from site configuration (D6):
+     * `ngdpbase.import.shims.<id>.options`, with the run's own `options` over
+     * them (a feed source's parse settings, #2109).
+     */
     options: Record<string, unknown>;
 }
 /** What a shim's read returns. */
@@ -104,7 +121,10 @@ export interface IceShim {
     produces: IceKind;
     /**
      * Receivers it may hand to directly (ids, `core.pages` or `<slug>.<name>`).
-     * Empty for a shim whose output only feeds another shim.
+     * Empty for a shim whose output only feeds another shim. {@link ANY_RECEIVER}
+     * (`'*'`): any receiver that takes the kind it produces — a generic format
+     * shim such as core's CSV, whose `record` items any add-on's receiver may
+     * take (#2109). Each receiver still decides with its own permission (D5).
      */
     receivers: string[];
     /** Two duplicate kinds (design rule): a whole file by fingerprint, or each item by `itemKey`. Default `file`. */
@@ -185,6 +205,13 @@ export interface ReceiveInfo {
     citation?: IceCitation;
     original?: KeptOriginal;
 }
+/** What a receiver's `fileDone` is told (#2109). */
+export interface FileDoneInfo extends ReceiveInfo {
+    /** What the source said about the file: a URL source's `metadata`. */
+    metadata: Record<string, unknown>;
+    /** Every item the file held, in order: those handed to `receive`, and those skipped as already seen. */
+    items: IceItem[];
+}
 /** A receiver's answer for one item. `refused` is its existing permission saying no (D5). */
 export interface ReceiveOutcome {
     status: 'stored' | 'duplicate' | 'refused';
@@ -211,6 +238,29 @@ export interface IceReceiver {
     mayUse(ctx: ActorContext): Promise<boolean>;
     /** Hand one item to the receiver's own door. */
     receive(item: IceItem, ctx: ActorContext, info: ReceiveInfo): Promise<ReceiveOutcome>;
+    /**
+     * Called once per file whose shims read it through (#2109), after each of
+     * its items was handed to `receive` or skipped as already seen, with every
+     * item the file held, in order. A receiver that holds a snapshot of a
+     * source (a feed's records) stores it here and drops what the source no
+     * longer holds: an item skipped as already seen is still in the source.
+     * Not called for a file that failed before its items were known. Returns a
+     * note for the file's status; a throw fails the file.
+     */
+    fileDone?(ctx: ActorContext, info: FileDoneInfo): Promise<string | void>;
+    /**
+     * `false`: this receiver is fed only by its owner's own sources (a feed's
+     * schedule, #2109). The import screen never offers it and an upload into
+     * it is refused. Default: it takes uploads.
+     */
+    uploads?: boolean;
+    /**
+     * Where this context can open what one of its references names (#2110),
+     * for "your recent imports" on the import screen: a URL, or null when
+     * the thing is gone or this context may not open it. The receiver decides
+     * with its own existing read rule (D5). Without it, nothing is linked.
+     */
+    linkFor?(ref: string, ctx: ActorContext): Promise<string | null>;
     /**
      * Keep the original file itself (D11: phr keeps originals in its own
      * store). Without this, `keep` hands the original to the files receiver.
@@ -241,13 +291,36 @@ export interface IceUpload {
     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.
+ * A URL the engine fetches as the run's one file (D1, D10, #2109): through
+ * the one guarded path (`guardedFetch`, #1139) with the site's egress policy
+ * and default User-Agent, and the source's own headers and timeout (#1959),
+ * which also apply to every follow-up fetch a shim asks of the engine during
+ * the run. A feed's schedule is its owner's job; the engine fetches when run.
+ */
+export interface IceUrlSource {
+    type: 'url';
+    url: string;
+    /** The name the fetched file gets in reports and the ledger. Default: the URL. */
+    name?: string;
+    /** Request headers for every fetch of the run (a `User-Agent` replaces the site default). */
+    headers?: Record<string, string>;
+    /** Each fetch's time limit, ms. Default `ngdpbase.fetch-timeout-ms`. */
+    timeoutMs?: number;
+    /**
+     * Facts the source states about the file, carried on it and on every item
+     * read from it (a feed source's id). The engine adds `sourceUrl`, the URL
+     * fetched, so a shim can resolve the file's relative links.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A source (D1): uploaded files, or a URL fetched when the run starts
+ * (#2109). A server folder joins this union later.
  */
 export type IceSource = {
     type: 'upload';
     files: IceUpload[];
-};
+} | IceUrlSource;
 /** One import, as a caller asks for it. */
 export interface IceRunRequest {
     source: IceSource;
@@ -267,6 +340,12 @@ export interface IceRunRequest {
      * value a client sent.
      */
     scope?: string;
+    /**
+     * Options for this run's shims, over the site's (`ShimTools.options`): a
+     * feed source's parse settings (#2109). Server-built; never a value a
+     * client sent.
+     */
+    options?: Record<string, unknown>;
 }
 /** Per-file status (first slice). */
 export type IceFileStatus = 'imported' | 'partial' | 'unchanged' | 'duplicate' | 'noise' | 'unreadable' | 'refused' | 'failed';
@@ -318,6 +397,25 @@ export interface LedgerFileEntry {
     /** The original kept for this fingerprint, whatever became of the conversion (D11). */
     original?: LedgerOriginal;
 }
+/**
+ * One file in a user's recent imports (#2110), read from the ledger: what
+ * the import screen lists, so the list survives a restart. Only the user's
+ * own entries, from the receivers they may use.
+ */
+export interface RecentImport {
+    name: string;
+    status: IceFileStatus;
+    message?: string;
+    /** When the ledger last recorded this file, ISO. */
+    at: string;
+    /** The receiver it went into. */
+    receiver: string;
+    receiverLabel?: string;
+    /** How many references the receiver gave (pages, records). */
+    refs: number;
+    /** Where the user can open the first of them (`linkFor`), when they may. */
+    link?: 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
@@ -328,5 +426,9 @@ export interface IceLedger {
     recordFile(scope: string, entry: LedgerFileEntry): Promise<void>;
     hasItem(scope: string, itemKey: string): Promise<boolean>;
     recordItem(scope: string, itemKey: string): Promise<void>;
+    /** Which of these item keys the scope has seen: one read for a whole file's items (#2109). */
+    seenItems(scope: string, itemKeys: string[]): Promise<Set<string>>;
+    /** Record several item keys in one write (#2109). */
+    recordItems(scope: string, itemKeys: string[]): Promise<void>;
     files(scope: string): Promise<LedgerFileEntry[]>;
 }

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

@@ -289,9 +289,27 @@ export interface AddonStatusDetails {
     message?: string;
     [key: string]: unknown;
 }
+/** The pages an add-on's card can be shown on: `/admin` (the default) and the Executive Hub, `/executive` (#2093). */
+export type AddonCardSurface = 'admin' | 'executive';
+/** One labelled figure on an Executive Hub card (`Funds`, `$12,400.00`). The add-on formats the value. */
+export interface AddonCardFigure {
+    label: string;
+    value: string | number;
+}
+/** What an Executive Hub card shows a viewer: its figures, and an optional line under them. */
+export interface AddonCardSummary {
+    figures?: AddonCardFigure[];
+    message?: string;
+}
 /**
- * Card registered by an add-on for display on the admin dashboard.
- * The card's live stats are sourced from the add-on's existing status() method.
+ * Card registered by an add-on for display on the admin dashboard, or, with
+ * `surface: 'executive'`, on the Executive Hub (#2093). An add-on registers
+ * at most one card per surface.
+ *
+ * An admin card's live stats come from the add-on's existing status() method.
+ * An executive card names the `permission` a viewer must hold to see it, and
+ * its figures come from `summary(ctx)`, called with the viewer's context, so
+ * the add-on's own doors decide what it reads.
  */
 export interface AddonDashboardCard {
     /** Must match the add-on's registered name */
@@ -300,8 +318,25 @@ export interface AddonDashboardCard {
     title: string;
     /** Font Awesome class, e.g. 'fas fa-wpforms' */
     icon: string;
-    /** URL of the add-on's admin page */
+    /** The page the card links to: the add-on's admin page, or for an executive card the page with the detail */
     adminUrl: string;
+    /** Where the card is shown; omitted means `/admin` */
+    surface?: AddonCardSurface;
+    /** Executive cards: the permission a viewer must hold to see the card (the add-on's own read permission). Required there */
+    permission?: string;
+    /** Executive cards: the card's figures for this viewer, read with their context. Throw to say they could not be read */
+    summary?: (ctx: ActorContext) => Promise<AddonCardSummary>;
+}
+/** An executive card as the hub shows it to one viewer: the figures read for them, or that they could not be. */
+export interface ExecutiveCardView {
+    addonName: string;
+    title: string;
+    icon: string;
+    adminUrl: string;
+    figures: AddonCardFigure[];
+    message: string;
+    /** True when the add-on's summary threw; the card says its figures could not be read. */
+    failed: boolean;
 }
 /** #2100: the PDP refused an administrator's add-on Update or Check. */
 export declare class AddonUpdateForbiddenError extends Error {
@@ -823,10 +858,19 @@ declare class AddonsManager extends BaseManager {
      */
     registerDashboardCard(card: AddonDashboardCard): void;
     /**
-     * Return all registered dashboard cards in registration order.
-     * Called by the admin dashboard route to populate the addon cards row.
+     * Return the registered cards for one surface, in registration order.
+     * The admin dashboard route calls it with no argument for the `/admin` cards.
+     */
+    getDashboardCards(surface?: AddonCardSurface): AddonDashboardCard[];
+    /**
+     * The Executive Hub's cards for one viewer (#2093): each card whose
+     * permission the PDP permits `ctx`, asked with that context, with the
+     * figures its add-on's `summary(ctx)` reads for them. A card the viewer may
+     * not see is left out; a summary that throws shows the card with its
+     * figures marked as not read, and is logged by add-on name only. No
+     * context, or no PDP, shows no cards.
      */
-    getDashboardCards(): AddonDashboardCard[];
+    executiveCardsFor(ctx: ActorContext): Promise<ExecutiveCardView[]>;
     /**
      * Get list of all discovered add-on names
      */