@aglyn/tenant-data-admin 1.0.0-beta.221 → 1.0.0-beta.222

package/src/lib/server/transfer-export.js

@@ -0,0 +1,221 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { _ as _object_without_properties_loose } from "@swc/helpers/_/_object_without_properties_loose";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /*==========================================
+ * THE FIELD-SELECTABLE EXPORT (AGL-3525) — any resource, the fields the
+ * person chose, in their order, streamed.
+ *
+ * The resource's plugin reads its own records (`readPage`, page by page,
+ * holding only the chosen fields) and this module writes them as CSV, JSON
+ * or NDJSON (`export-file.ts` in the core), so every resource's file reads
+ * the same way and maps straight back in on import.
+ *
+ * ## The file says how many rows it promised
+ *
+ * A stream that dies halfway is a well-formed shorter file. So the rows are
+ * counted BEFORE the first byte — by the resource's `count` hook, or by
+ * reading ahead up to `TRANSFER_EXPORT_PREFETCH_ROWS` — and the route sends
+ * the count as `X-Aglyn-Export-Rows`, which the console's client checks the
+ * download against (`exportShortfall`'s convention). A resource that cannot
+ * count and holds more than the read-ahead sends no count rather than a
+ * wrong one.
+ *
+ * ## Scope is the plugin's to honor
+ *
+ * The export reads through the Admin SDK, past the rules, so a collaborator
+ * scoped to some sites is handed to `readPage` as `scopeTokens`, the tokens
+ * a row's `visibleTo` must hold one of — what the rules would have asked.
+ *
+ * ## Remembered choices
+ *
+ * `users/{uid}/transferPrefs/{resourceKey}` holds a person's last export
+ * choice and saved presets; the owner reads and writes it (rules), and the
+ * `fields` route reads it here to open the dialog where they left it.
+ *=========================================*/ import { TRANSFER_EXPORT_PAGE_ROWS, TRANSFER_EXPORT_PREFETCH_ROWS, TRANSFER_EXPORT_SELECTION_MAX, TRANSFER_PREFS_COLLECTION, normalizeTransferPrefs, resolveTransferFieldSelection, transferContentType, transferExportCsvHeader, transferExportCsvLine, transferExportFileName, transferExportHeaders, transferExportRecord } from "@aglyn/aglyn/data-transfer";
+import { transferRecordsHooks, transferResourceCatalog } from "@aglyn/aglyn/plugin-manager/plugin-transfer-resources";
+import { TransferEngineError, resolveTransferRecordsResource, transferHostIdFor } from "./transfer-jobs.js";
+const FORMATS = [
+    'csv',
+    'json',
+    'ndjson'
+];
+/** The read options an export's scope makes, or the refusal. */ function readOptionsFor(input) {
+    const options = {
+        pageSize: TRANSFER_EXPORT_PAGE_ROWS
+    };
+    const scope = input.scope;
+    if ((scope == null ? void 0 : scope.kind) === 'selection') {
+        const ids = [
+            ...new Set((Array.isArray(scope.ids) ? scope.ids : []).filter((id)=>typeof id === 'string' && id))
+        ];
+        if (!ids.length) throw new TransferEngineError('invalid', 400, 'Select the records to export.');
+        if (ids.length > TRANSFER_EXPORT_SELECTION_MAX) {
+            throw new TransferEngineError('tooLarge', 413, `Select at most ${TRANSFER_EXPORT_SELECTION_MAX.toLocaleString('en-US')} records, or export the filter or everything.`);
+        }
+        options.ids = ids;
+    } else if ((scope == null ? void 0 : scope.kind) === 'filter') {
+        if (!scope.filter || typeof scope.filter !== 'object' || Array.isArray(scope.filter)) {
+            throw new TransferEngineError('invalid', 400, 'The filter could not be read.');
+        }
+        options.filter = scope.filter;
+    } else if ((scope == null ? void 0 : scope.kind) !== 'all') {
+        throw new TransferEngineError('invalid', 400, 'Say which records to export.');
+    }
+    if (input.scopeTokens) options.scopeTokens = [
+        ...input.scopeTokens
+    ];
+    return options;
+}
+/**
+ * The export, ready to stream (see the block header): the resource
+ * resolved, the fields checked against its catalog in the person's order,
+ * the rows counted when they can be, and a stream that reads the rest page
+ * by page. A field the catalog no longer has, a format the resource does not
+ * write, or an empty selection is refused before a byte is sent.
+ */ export async function streamTransferExport(deps, input) {
+    var _input_resource, _deps_now;
+    const resource = await resolveTransferRecordsResource(deps, String((_input_resource = input.resource) != null ? _input_resource : '').trim());
+    const options = readOptionsFor(input);
+    // The catalog the chosen fields are checked against is the one the dialog
+    // showed for the filter, for a resource whose columns follow the records read.
+    const ctx = _extends({
+        resource: resource.key,
+        orgId: input.orgId,
+        hostId: transferHostIdFor(resource, input.hostId),
+        actorUid: input.actorUid
+    }, options.filter ? {
+        filter: options.filter
+    } : {});
+    const format = input.format;
+    if (!FORMATS.includes(format) || !resource.formats.includes(format)) {
+        throw new TransferEngineError('unsupportedFormat', 415, `${resource.label} can be exported as ${resource.formats.join(', ').toUpperCase()}.`);
+    }
+    const catalog = await transferResourceCatalog(resource, ctx);
+    const selection = resolveTransferFieldSelection(catalog, (Array.isArray(input.fieldIds) ? input.fieldIds : []).filter((id)=>typeof id === 'string'));
+    if (selection.unknown.length) {
+        throw new TransferEngineError('invalid', 400, 'Some chosen fields no longer exist. Choose the fields again.', {
+            unknown: selection.unknown
+        });
+    }
+    const fieldIds = selection.fieldIds;
+    if (!fieldIds.length) throw new TransferEngineError('invalid', 400, 'Choose at least one field to export.');
+    const hooks = transferRecordsHooks(resource);
+    // Counted before the first byte: by the resource, or by reading ahead.
+    const buffered = [];
+    let cursor = null;
+    let exhausted = false;
+    let rows = null;
+    if (hooks.count) {
+        const { pageSize: _pageSize } = options, countOptions = _object_without_properties_loose(options, [
+            "pageSize"
+        ]);
+        rows = Math.max(0, Math.floor(Number(await hooks.count(ctx, countOptions)) || 0));
+    } else {
+        while(buffered.length < TRANSFER_EXPORT_PREFETCH_ROWS){
+            const page = await hooks.readPage(ctx, cursor, fieldIds, options);
+            buffered.push(...page.rows);
+            cursor = page.next;
+            if (!cursor) {
+                exhausted = true;
+                break;
+            }
+        }
+        if (exhausted) rows = buffered.length;
+    }
+    const encoder = new TextEncoder();
+    // A preset's column names (another product's layout) stand in for labels.
+    const headers = transferExportHeaders(fieldIds, input.headers);
+    const label = (fieldId)=>{
+        var _ref, _headers_fieldId;
+        var _catalog_byId_get;
+        return (_ref = (_headers_fieldId = headers[fieldId]) != null ? _headers_fieldId : (_catalog_byId_get = catalog.byId.get(fieldId)) == null ? void 0 : _catalog_byId_get.label) != null ? _ref : fieldId;
+    };
+    const typeOf = (fieldId)=>{
+        var _catalog_byId_get;
+        return (_catalog_byId_get = catalog.byId.get(fieldId)) == null ? void 0 : _catalog_byId_get.type;
+    };
+    let written = 0;
+    const write = (batch)=>{
+        let text = '';
+        for (const row of batch){
+            if (format === 'csv') text += `\r\n${transferExportCsvLine(row, fieldIds, typeOf)}`;
+            else {
+                const json = JSON.stringify(transferExportRecord(row, fieldIds));
+                text += format === 'ndjson' ? `${json}\n` : `${written ? ',' : ''}\n${json}`;
+            }
+            written += 1;
+        }
+        return text;
+    };
+    let phase = 'head';
+    const stream = new ReadableStream({
+        async pull (controller) {
+            try {
+                if (phase === 'head') {
+                    phase = 'buffered';
+                    const head = format === 'csv' ? `${input.bom ? '' : ''}${transferExportCsvHeader(fieldIds, label)}` : format === 'json' ? '[' : '';
+                    if (head) {
+                        controller.enqueue(encoder.encode(head));
+                        return;
+                    }
+                }
+                if (phase === 'buffered') {
+                    phase = exhausted ? 'tail' : 'pages';
+                    if (buffered.length) {
+                        controller.enqueue(encoder.encode(write(buffered)));
+                        buffered.length = 0;
+                        return;
+                    }
+                }
+                if (phase === 'pages') {
+                    const page = await hooks.readPage(ctx, cursor, fieldIds, options);
+                    cursor = page.next;
+                    if (!cursor) phase = 'tail';
+                    if (page.rows.length) {
+                        controller.enqueue(encoder.encode(write(page.rows)));
+                        return;
+                    }
+                    if (phase === 'pages') return;
+                }
+                controller.enqueue(encoder.encode(format === 'csv' ? '\r\n' : format === 'json' ? '\n]\n' : ''));
+                controller.close();
+            } catch (error) {
+                // Erroring the stream fails the download rather than completing it
+                // short: a half-written file the browser reports as failed.
+                controller.error(error);
+            }
+        }
+    });
+    return {
+        stream,
+        rows,
+        fileName: transferExportFileName(resource.key, format, new Date(((_deps_now = deps.now) != null ? _deps_now : Date.now)())),
+        contentType: transferContentType(format),
+        fieldIds,
+        label: resource.label
+    };
+}
+/** A person's remembered choices for one resource, as far as they can be trusted. */ export async function readTransferPrefs(firestore, uid, resource) {
+    const key = String(resource != null ? resource : '').trim();
+    if (!uid || !key || key.includes('/')) return {
+        presets: []
+    };
+    const snapshot = await firestore.collection('users').doc(uid).collection(TRANSFER_PREFS_COLLECTION).doc(key).get();
+    return normalizeTransferPrefs(snapshot.exists ? snapshot.data() : null);
+}
+
+//# sourceMappingURL=transfer-export.js.map

package/src/lib/server/transfer-export.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/transfer-export.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/*==========================================\n * THE FIELD-SELECTABLE EXPORT (AGL-3525) — any resource, the fields the\n * person chose, in their order, streamed.\n *\n * The resource's plugin reads its own records (`readPage`, page by page,\n * holding only the chosen fields) and this module writes them as CSV, JSON\n * or NDJSON (`export-file.ts` in the core), so every resource's file reads\n * the same way and maps straight back in on import.\n *\n * ## The file says how many rows it promised\n *\n * A stream that dies halfway is a well-formed shorter file. So the rows are\n * counted BEFORE the first byte — by the resource's `count` hook, or by\n * reading ahead up to `TRANSFER_EXPORT_PREFETCH_ROWS` — and the route sends\n * the count as `X-Aglyn-Export-Rows`, which the console's client checks the\n * download against (`exportShortfall`'s convention). A resource that cannot\n * count and holds more than the read-ahead sends no count rather than a\n * wrong one.\n *\n * ## Scope is the plugin's to honor\n *\n * The export reads through the Admin SDK, past the rules, so a collaborator\n * scoped to some sites is handed to `readPage` as `scopeTokens`, the tokens\n * a row's `visibleTo` must hold one of — what the rules would have asked.\n *\n * ## Remembered choices\n *\n * `users/{uid}/transferPrefs/{resourceKey}` holds a person's last export\n * choice and saved presets; the owner reads and writes it (rules), and the\n * `fields` route reads it here to open the dialog where they left it.\n *=========================================*/\n\nimport {\n  TRANSFER_EXPORT_PAGE_ROWS,\n  TRANSFER_EXPORT_PREFETCH_ROWS,\n  TRANSFER_EXPORT_SELECTION_MAX,\n  TRANSFER_PREFS_COLLECTION,\n  normalizeTransferPrefs,\n  resolveTransferFieldSelection,\n  transferContentType,\n  transferExportCsvHeader,\n  transferExportCsvLine,\n  transferExportFileName,\n  transferExportHeaders,\n  transferExportRecord,\n  type TransferExportChoice,\n  type TransferFormat,\n  type TransferPrefs,\n} from '@aglyn/aglyn/data-transfer'\nimport {\n  transferRecordsHooks,\n  transferResourceCatalog,\n  type TransferReadOptions,\n  type TransferResourceContext,\n} from '@aglyn/aglyn/plugin-manager/plugin-transfer-resources'\nimport {\n  TransferEngineError,\n  resolveTransferRecordsResource,\n  transferHostIdFor,\n  type TransferEngineDeps,\n} from './transfer-jobs'\n\nconst FORMATS: readonly TransferFormat[] = ['csv', 'json', 'ndjson']\n\nexport interface TransferExportInput extends TransferExportChoice {\n  orgId: string\n  actorUid: string\n  hostId?: string | null\n  /** A scoped collaborator's tokens; absent for a reader who sees the whole workspace. */\n  scopeTokens?: readonly string[]\n}\n\nexport interface TransferExportFile {\n  stream: ReadableStream<Uint8Array>\n  /** The rows the file holds, when they could be counted before the first byte. */\n  rows: number | null\n  fileName: string\n  contentType: string\n  /** The fields written, in order. */\n  fieldIds: string[]\n  /** The resource's name, for the audit and the file. */\n  label: string\n}\n\n/** The read options an export's scope makes, or the refusal. */\nfunction readOptionsFor(input: TransferExportInput): TransferReadOptions {\n  const options: TransferReadOptions = { pageSize: TRANSFER_EXPORT_PAGE_ROWS }\n  const scope = input.scope as TransferExportChoice['scope'] | undefined\n  if (scope?.kind === 'selection') {\n    const ids = [...new Set((Array.isArray(scope.ids) ? scope.ids : []).filter((id) => typeof id === 'string' && id))]\n    if (!ids.length) throw new TransferEngineError('invalid', 400, 'Select the records to export.')\n    if (ids.length > TRANSFER_EXPORT_SELECTION_MAX) {\n      throw new TransferEngineError(\n        'tooLarge',\n        413,\n        `Select at most ${TRANSFER_EXPORT_SELECTION_MAX.toLocaleString('en-US')} records, or export the filter or everything.`,\n      )\n    }\n    options.ids = ids\n  } else if (scope?.kind === 'filter') {\n    if (!scope.filter || typeof scope.filter !== 'object' || Array.isArray(scope.filter)) {\n      throw new TransferEngineError('invalid', 400, 'The filter could not be read.')\n    }\n    options.filter = scope.filter as Readonly<Record<string, unknown>>\n  } else if (scope?.kind !== 'all') {\n    throw new TransferEngineError('invalid', 400, 'Say which records to export.')\n  }\n  if (input.scopeTokens) options.scopeTokens = [...input.scopeTokens]\n  return options\n}\n\n/**\n * The export, ready to stream (see the block header): the resource\n * resolved, the fields checked against its catalog in the person's order,\n * the rows counted when they can be, and a stream that reads the rest page\n * by page. A field the catalog no longer has, a format the resource does not\n * write, or an empty selection is refused before a byte is sent.\n */\nexport async function streamTransferExport(\n  deps: Pick<TransferEngineDeps, 'resolveResource' | 'now'>,\n  input: TransferExportInput,\n): Promise<TransferExportFile> {\n  const resource = await resolveTransferRecordsResource(deps, String(input.resource ?? '').trim())\n  const options = readOptionsFor(input)\n  // The catalog the chosen fields are checked against is the one the dialog\n  // showed for the filter, for a resource whose columns follow the records read.\n  const ctx: TransferResourceContext = {\n    resource: resource.key,\n    orgId: input.orgId,\n    hostId: transferHostIdFor(resource, input.hostId),\n    actorUid: input.actorUid,\n    ...(options.filter ? { filter: options.filter } : {}),\n  }\n  const format = input.format\n  if (!FORMATS.includes(format) || !resource.formats.includes(format)) {\n    throw new TransferEngineError(\n      'unsupportedFormat',\n      415,\n      `${resource.label} can be exported as ${resource.formats.join(', ').toUpperCase()}.`,\n    )\n  }\n  const catalog = await transferResourceCatalog(resource, ctx)\n  const selection = resolveTransferFieldSelection(\n    catalog,\n    (Array.isArray(input.fieldIds) ? input.fieldIds : []).filter((id): id is string => typeof id === 'string'),\n  )\n  if (selection.unknown.length) {\n    throw new TransferEngineError('invalid', 400, 'Some chosen fields no longer exist. Choose the fields again.', {\n      unknown: selection.unknown,\n    })\n  }\n  const fieldIds = selection.fieldIds\n  if (!fieldIds.length) throw new TransferEngineError('invalid', 400, 'Choose at least one field to export.')\n  const hooks = transferRecordsHooks(resource)\n\n  // Counted before the first byte: by the resource, or by reading ahead.\n  const buffered: Array<Record<string, unknown>> = []\n  let cursor: string | null = null\n  let exhausted = false\n  let rows: number | null = null\n  if (hooks.count) {\n    const { pageSize: _pageSize, ...countOptions } = options\n    rows = Math.max(0, Math.floor(Number(await hooks.count(ctx, countOptions)) || 0))\n  } else {\n    while (buffered.length < TRANSFER_EXPORT_PREFETCH_ROWS) {\n      const page = await hooks.readPage(ctx, cursor, fieldIds, options)\n      buffered.push(...page.rows)\n      cursor = page.next\n      if (!cursor) {\n        exhausted = true\n        break\n      }\n    }\n    if (exhausted) rows = buffered.length\n  }\n\n  const encoder = new TextEncoder()\n  // A preset's column names (another product's layout) stand in for labels.\n  const headers = transferExportHeaders(fieldIds, input.headers)\n  const label = (fieldId: string) => headers[fieldId] ?? catalog.byId.get(fieldId)?.label ?? fieldId\n  const typeOf = (fieldId: string) => catalog.byId.get(fieldId)?.type\n  let written = 0\n  const write = (batch: ReadonlyArray<Readonly<Record<string, unknown>>>): string => {\n    let text = ''\n    for (const row of batch) {\n      if (format === 'csv') text += `\\r\\n${transferExportCsvLine(row, fieldIds, typeOf)}`\n      else {\n        const json = JSON.stringify(transferExportRecord(row, fieldIds))\n        text += format === 'ndjson' ? `${json}\\n` : `${written ? ',' : ''}\\n${json}`\n      }\n      written += 1\n    }\n    return text\n  }\n  let phase: 'head' | 'buffered' | 'pages' | 'tail' = 'head'\n  const stream = new ReadableStream<Uint8Array>({\n    async pull(controller) {\n      try {\n        if (phase === 'head') {\n          phase = 'buffered'\n          const head =\n            format === 'csv'\n              ? `${input.bom ? '' : ''}${transferExportCsvHeader(fieldIds, label)}`\n              : format === 'json'\n                ? '['\n                : ''\n          if (head) {\n            controller.enqueue(encoder.encode(head))\n            return\n          }\n        }\n        if (phase === 'buffered') {\n          phase = exhausted ? 'tail' : 'pages'\n          if (buffered.length) {\n            controller.enqueue(encoder.encode(write(buffered)))\n            buffered.length = 0\n            return\n          }\n        }\n        if (phase === 'pages') {\n          const page = await hooks.readPage(ctx, cursor, fieldIds, options)\n          cursor = page.next\n          if (!cursor) phase = 'tail'\n          if (page.rows.length) {\n            controller.enqueue(encoder.encode(write(page.rows)))\n            return\n          }\n          if (phase === 'pages') return\n        }\n        controller.enqueue(encoder.encode(format === 'csv' ? '\\r\\n' : format === 'json' ? '\\n]\\n' : ''))\n        controller.close()\n      } catch (error) {\n        // Erroring the stream fails the download rather than completing it\n        // short: a half-written file the browser reports as failed.\n        controller.error(error)\n      }\n    },\n  })\n\n  return {\n    stream,\n    rows,\n    fileName: transferExportFileName(resource.key, format, new Date((deps.now ?? Date.now)())),\n    contentType: transferContentType(format),\n    fieldIds,\n    label: resource.label,\n  }\n}\n\n/** A person's remembered choices for one resource, as far as they can be trusted. */\nexport async function readTransferPrefs(\n  firestore: FirebaseFirestore.Firestore,\n  uid: string,\n  resource: string,\n): Promise<TransferPrefs> {\n  const key = String(resource ?? '').trim()\n  if (!uid || !key || key.includes('/')) return { presets: [] }\n  const snapshot = await firestore.collection('users').doc(uid).collection(TRANSFER_PREFS_COLLECTION).doc(key).get()\n  return normalizeTransferPrefs(snapshot.exists ? snapshot.data() : null)\n}\n"],"names":["TRANSFER_EXPORT_PAGE_ROWS","TRANSFER_EXPORT_PREFETCH_ROWS","TRANSFER_EXPORT_SELECTION_MAX","TRANSFER_PREFS_COLLECTION","normalizeTransferPrefs","resolveTransferFieldSelection","transferContentType","transferExportCsvHeader","transferExportCsvLine","transferExportFileName","transferExportHeaders","transferExportRecord","transferRecordsHooks","transferResourceCatalog","TransferEngineError","resolveTransferRecordsResource","transferHostIdFor","FORMATS","readOptionsFor","input","options","pageSize","scope","kind","ids","Set","Array","isArray","filter","id","length","toLocaleString","scopeTokens","streamTransferExport","deps","resource","String","trim","ctx","key","orgId","hostId","actorUid","format","includes","formats","label","join","toUpperCase","catalog","selection","fieldIds","unknown","hooks","buffered","cursor","exhausted","rows","count","_pageSize","countOptions","Math","max","floor","Number","page","readPage","push","next","encoder","TextEncoder","headers","fieldId","byId","get","typeOf","type","written","write","batch","text","row","json","JSON","stringify","phase","stream","ReadableStream","pull","controller","head","bom","enqueue","encode","close","error","fileName","Date","now","contentType","readTransferPrefs","firestore","uid","presets","snapshot","collection","doc","exists","data"],"mappings":"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"}

package/src/lib/server/transfer-jobs.d.ts

@@ -0,0 +1,385 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type TransferJobSummary, type TransferUnfinishedImportSummary, type TransferAnalyzeResponse, type TransferCsvDelimiter, type TransferDateOrder, type TransferErrorCode, type TransferFormat, type TransferJobRecord, type TransferJobRetention, type TransferPlanChoices, type TransferPlanResponse, type TransferPlanRowsPage, type TransferProgress, type TransferResourceInfo, type TransferResultSummary, type TransferRowResult, type TransferRowVerdict, type TransferUndoCounts, type TransferUndoDecision, type TransferUndoEntry, type TransferUndoPlanResponse, type TransferUndoState, type TransferWarningClass } from '@aglyn/aglyn/data-transfer';
+import { type ResolvedTransferResource, type TransferPlanRefusal, type TransferResourceContext } from '@aglyn/aglyn/plugin-manager/plugin-transfer-resources';
+/** The one Storage object operation set the engine uses. */
+export interface TransferBucketFile {
+    save(data: Buffer, options?: {
+        contentType?: string;
+        resumable?: boolean;
+    }): Promise<unknown>;
+    download(): Promise<[Buffer]>;
+    delete(options?: {
+        ignoreNotFound?: boolean;
+    }): Promise<unknown>;
+}
+/** The bucket the files are stored in (the Admin SDK's default bucket in production). */
+export interface TransferBucket {
+    file(path: string): TransferBucketFile;
+}
+/** What the engine runs against; a spec hands it doubles. */
+export interface TransferEngineDeps {
+    firestore: FirebaseFirestore.Firestore;
+    bucket: TransferBucket;
+    /** Defaults to `resolveTransferResource`. */
+    resolveResource?: (key: string) => Promise<ResolvedTransferResource>;
+    /** Defaults to `Date.now`. */
+    now?: () => number;
+    /** Defaults to `createResourceUid()`, the id every console resource carries. */
+    newJobId?: () => string;
+}
+/** A refusal a route answers as `{ error, code, details }` with `status`. */
+export declare class TransferEngineError extends Error {
+    readonly code: TransferErrorCode;
+    readonly status: number;
+    readonly details?: unknown;
+    constructor(code: TransferErrorCode, status: number, message: string, details?: unknown);
+}
+/**
+ * A refusal for the workspace's plan (AGL-3555): a route answers its
+ * `refusal` as it stands — the owning plugin's flat 403 body, with
+ * `reason: 'plan_required'` and the plan feature as `code` — rather than
+ * as `{ error, code, details }`. Its own `code` is `planRequired`, what a
+ * client reads that body as.
+ */
+export declare class TransferPlanRefusedError extends TransferEngineError {
+    readonly refusal: TransferPlanRefusal;
+    constructor(refusal: TransferPlanRefusal);
+}
+/** The collection an organization's jobs live in. */
+export declare const TRANSFER_JOBS_COLLECTION = "transferJobs";
+/** How long a driver's lease outlives its budget, so a crashed request's job is resumed soon after. */
+export declare const TRANSFER_LEASE_GRACE_MS = 30000;
+/** How long an `applying` job sits untouched before the sweep resumes it. */
+export declare const TRANSFER_STALE_MS: number;
+/** Below this much budget, a request stops rather than starting another chunk. */
+export declare const TRANSFER_MIN_CHUNK_BUDGET_MS = 2000;
+/** Where an organization's jobs are. */
+export declare function transferJobsCollection(firestore: FirebaseFirestore.Firestore, orgId: string): FirebaseFirestore.CollectionReference;
+/** Where a job's file is stored. */
+export declare function transferSourcePath(orgId: string, jobId: string): string;
+/** Where one part of a file sent in parts waits until the rest arrives. */
+export declare function transferPartPath(orgId: string, jobId: string, part: number): string;
+export declare const clock: (deps: Pick<TransferEngineDeps, "now">) => number;
+/** A value as Firestore can store it: no `undefined`, no class instances. */
+export declare function stored<T>(value: T): T;
+export declare function emptyResults(): TransferResultSummary;
+export declare function emptyUndoCounts(): TransferUndoCounts;
+/** `fn` over `items`, at most `limit` at once. */
+export declare function eachLimited<T>(items: readonly T[], limit: number, fn: (item: T) => Promise<void>): Promise<void>;
+export declare function isAlreadyExists(error: unknown): boolean;
+/**
+ * Writes `value` as JSON on `ref` beside `fields`. JSON, because a plan row
+ * holds whatever the file held — a nested list from a JSON file is a value
+ * Firestore refuses — and past {@link JSON_PIECE_CHARS} the text goes into
+ * `pieces/{k}` documents, so a chunk of long notes is never refused for size.
+ */
+export declare function writeJsonDoc(ref: FirebaseFirestore.DocumentReference, fields: Record<string, unknown>, value: unknown): Promise<void>;
+/** The value {@link writeJsonDoc} wrote, or `null` when the document is absent. */
+export declare function readJsonDoc<T>(ref: FirebaseFirestore.DocumentReference): Promise<T | null>;
+/** Deletes every document of a collection (and a JSON document's pieces), eight at a time. */
+export declare function clearCollection(collection: FirebaseFirestore.CollectionReference): Promise<void>;
+export declare function readJob(deps: TransferEngineDeps, orgId: string, jobId: string): Promise<TransferJobRecord>;
+/**
+ * When the sweep may clean a job up, and how (see the sweep below): never
+ * while it runs or undoes, nor once trimmed; a job that never wrote expires
+ * {@link TRANSFER_DRAFT_RETENTION_MS} after it was last touched; one that
+ * wrote is trimmed once its undo window has closed.
+ */
+export declare function transferJobRetention(job: TransferJobRecord): {
+    retention: TransferJobRetention;
+    retainUntil: number;
+} | null;
+export declare function saveJob(deps: TransferEngineDeps, job: TransferJobRecord): Promise<void>;
+/** The job as a route returns it. */
+export declare function readTransferJob(deps: TransferEngineDeps, input: {
+    orgId: string;
+    jobId: string;
+}): Promise<TransferJobRecord>;
+/** A `records` resource, joined to its server half, or the refusal a route answers. */
+export declare function resolveTransferRecordsResource(deps: Pick<TransferEngineDeps, 'resolveResource'>, key: string): Promise<ResolvedTransferResource>;
+/**
+ * The site a transfer concerns: required for a `host` resource; for an
+ * `org` resource the site the person named, or `null` — a workspace's
+ * records can be read through one site's view of them and imported as
+ * that site's captures (the CRM's, AGL-3541), and the gate has already
+ * checked `data.manage` on that site.
+ */
+export declare function transferHostIdFor(resource: ResolvedTransferResource, hostId: string | null | undefined): string | null;
+export declare function contextFor(job: TransferJobRecord, actorUid: string | null): TransferResourceContext;
+export declare function moveJob(job: TransferJobRecord, to: TransferJobRecord['status'], now: number, patch?: Partial<TransferJobRecord>): TransferJobRecord;
+/** Where a job stands, for a progress bar. */
+export declare function transferJobProgress(job: TransferJobRecord): TransferProgress;
+/**
+ * What a resource offers the wizard and the export dialog: its descriptor,
+ * every field and group, its match keys (and the ones a person starts with,
+ * which the Re-importable preset leads with), the presets' hints and its own
+ * presets, its locked rules and aliases. `prefs` is the person's own
+ * and is filled by the caller; a custom field cannot be created from here.
+ */
+export declare function readTransferResourceInfo(deps: TransferEngineDeps, input: {
+    orgId: string;
+    actorUid: string;
+    resource: string;
+    hostId?: string | null;
+    filter?: unknown;
+}): Promise<Omit<TransferResourceInfo, 'prefs'>>;
+export interface TransferUploadInput {
+    orgId: string;
+    actorUid: string;
+    resource: string;
+    hostId?: string | null;
+    fileName: string;
+    format?: TransferFormat;
+    content: string;
+    part?: number;
+    parts?: number;
+    jobId?: string;
+    delimiter?: TransferCsvDelimiter;
+    headerRow?: boolean;
+}
+/**
+ * Stores a file, or one part of it, and makes the job on the first part.
+ * Each part is inspected before it is stored; the whole file is inspected
+ * again, read, counted against the resource's limits and stored as the
+ * source once the last part lands. A part sent twice is accepted once.
+ */
+export declare function uploadTransferSource(deps: TransferEngineDeps, input: TransferUploadInput): Promise<{
+    job: TransferJobRecord;
+    complete: boolean;
+}>;
+export interface AnalyzeTransferInput {
+    orgId: string;
+    jobId: string;
+    actorUid: string;
+    mapping?: Record<number, string | null>;
+    /** Match key field ids, in priority order; the resource's defaults when absent. */
+    matchKeys?: string[];
+    dateOrders?: Record<string, TransferDateOrder>;
+}
+/**
+ * Reads the file and proposes a mapping: every column against the
+ * resource's catalog and aliases, with the first rows as samples, and each
+ * mapped picklist column's values against the organization's list. With
+ * `mapping`, the values are read under that mapping instead of the proposal,
+ * and the answer adds what reading every mapped field did over the whole
+ * file and how the rows match existing records under `matchKeys`.
+ */
+export declare function analyzeTransferJob(deps: TransferEngineDeps, input: AnalyzeTransferInput): Promise<Omit<TransferAnalyzeResponse, 'ok'>>;
+/**
+ * The dry run: every row read, its picklist values resolved, matched to the
+ * records that exist and planned under the policy — without writing a
+ * record. The planned rows are stored chunk by chunk for Apply; the summary,
+ * the warnings and the first page answer the wizard.
+ */
+export declare function planTransferJob(deps: TransferEngineDeps, input: {
+    orgId: string;
+    jobId: string;
+    actorUid: string;
+    choices: TransferPlanChoices;
+}): Promise<Omit<TransferPlanResponse, 'ok'>>;
+/** One page of the stored dry run, optionally only rows with some verdicts. */
+export declare function readTransferPlanRows(deps: TransferEngineDeps, input: {
+    orgId: string;
+    jobId: string;
+    offset?: number;
+    limit?: number;
+    verdicts?: readonly TransferRowVerdict[];
+}): Promise<TransferPlanRowsPage>;
+export interface ApplyTransferInput {
+    orgId: string;
+    jobId: string;
+    /** Whose import it is, for the plugin's own checks and activity lines. */
+    actorUid: string;
+    acknowledged?: readonly TransferWarningClass[];
+    /** When this request must stop starting chunks (epoch ms). */
+    deadlineMs: number;
+    /** Who is driving: a request id, or the sweep. */
+    driver: string;
+}
+export interface ApplyTransferOutcome {
+    job: TransferJobRecord;
+    progress: TransferProgress;
+    done: boolean;
+    /** This call moved the job into `applying` (the first call, or a resume after a failure). */
+    started: boolean;
+    /** That move was a resume after a failure. */
+    resumed: boolean;
+    /** The results of the chunks this call wrote. */
+    results: TransferRowResult[];
+}
+export declare function addResults(total: TransferResultSummary, more: TransferResultSummary): TransferResultSummary;
+export interface LedgerEntry {
+    result: TransferRowResult;
+    undo: TransferUndoEntry | null;
+}
+/** Takes the job for `driver`, or refuses: another driver holds it, or another import of the resource is running. */
+export declare function takeLease(deps: TransferEngineDeps, job: TransferJobRecord, driver: string, expiresAt: number, enter: (current: TransferJobRecord, now: number) => TransferJobRecord): Promise<TransferJobRecord>;
+/**
+ * Writes chunks until the budget runs out (see the block header). The first
+ * call needs every required acknowledgement; later calls — the browser's
+ * next, or the sweep's — resume at the cursor. A plugin `apply` that throws
+ * fails the job with the chunk named, and calling again resumes it.
+ */
+export declare function applyTransferJob(deps: TransferEngineDeps, input: ApplyTransferInput): Promise<ApplyTransferOutcome>;
+/** The job, its progress, and whether undo is open. */
+export declare function readTransferJobStatus(deps: TransferEngineDeps, input: {
+    orgId: string;
+    jobId: string;
+    include?: 'results';
+}): Promise<{
+    job: TransferJobRecord;
+    progress: TransferProgress;
+    undo: {
+        available: boolean;
+        expiresAt: number | null;
+        state: TransferUndoState | null;
+    };
+    rows?: TransferRowResult[];
+}>;
+/**
+ * The result file: every row of the file as it was sent, then what happened
+ * to it, why, and the record it wrote. A row not written yet says `pending`.
+ */
+export declare function transferResultFile(deps: TransferEngineDeps, input: {
+    orgId: string;
+    jobId: string;
+}): Promise<{
+    csv: string;
+    rows: number;
+    fileName: string;
+}>;
+/**
+ * The workspace's imports, newest first, a page at a time, as the hub's
+ * history lists them. Clients cannot read the jobs' subcollections, and
+ * the hub needs more than the job document says — whether undo is still
+ * open, whether the result file can still be made — so the route answers
+ * this. `labels` names each resource; `emailsOf` says who each member is.
+ */
+export declare function listTransferJobs(deps: TransferEngineDeps, input: {
+    orgId: string;
+    limit?: number;
+    after?: number | null;
+    labels?: Readonly<Record<string, string>>;
+    emailsOf?: (uids: readonly string[]) => Promise<ReadonlyMap<string, string>>;
+}): Promise<{
+    jobs: TransferJobSummary[];
+    next: number | null;
+}>;
+/**
+ * The caller's unfinished imports of records, newest first — a Firestore
+ * query on `(createdBy, retention, updatedAt ↓)`, never a page of the
+ * history filtered.
+ */
+export declare function listUnfinishedTransferJobs(deps: TransferEngineDeps, input: {
+    orgId: string;
+    actorUid: string;
+    labels?: Readonly<Record<string, string>>;
+}): Promise<TransferUnfinishedImportSummary[]>;
+/**
+ * Throws one of the caller's unfinished imports away now: its job, its
+ * pieces and its file, as the cleanup would a week on. Refused for someone
+ * else's import, and for one that has written anything — that is undone.
+ */
+export declare function discardTransferJob(deps: TransferEngineDeps, input: {
+    orgId: string;
+    jobId: string;
+    actorUid: string;
+}): Promise<void>;
+/**
+ * What undo would do, writing nothing: every record the import touched,
+ * read as it is now, and planned with the core's `planTransferUndo`. A
+ * record edited since comes back as a conflict, with what it holds now and
+ * what undo would put back, for the person to decide.
+ */
+export declare function planTransferJobUndo(deps: TransferEngineDeps, input: {
+    orgId: string;
+    jobId: string;
+    actorUid: string;
+    offset?: number;
+    limit?: number;
+}): Promise<Omit<TransferUndoPlanResponse, 'ok'>>;
+export interface ApplyTransferUndoInput {
+    orgId: string;
+    jobId: string;
+    actorUid: string;
+    decisions?: Readonly<Record<string, TransferUndoDecision>>;
+    otherwise: TransferUndoDecision;
+    deadlineMs: number;
+    driver: string;
+}
+/**
+ * Carries undo out, chunk by chunk, through the plugin's `revert`, each
+ * record with the person's decision (`otherwise` for one the decisions do
+ * not name). Called again until `done`; the last chunk moves the job to
+ * `undone`. Reverting a chunk twice is harmless: a field already restored
+ * plans as nothing.
+ */
+export declare function applyTransferJobUndo(deps: TransferEngineDeps, input: ApplyTransferUndoInput): Promise<{
+    job: TransferJobRecord;
+    undo: TransferUndoState;
+    done: boolean;
+    started: boolean;
+}>;
+export interface TransferSweepOutcome {
+    /** Jobs found applying and untouched past the stale window. */
+    found: number;
+    resumed: Array<{
+        orgId: string;
+        jobId: string;
+        status: TransferJobRecord['status'];
+        done: boolean;
+    }>;
+    /** Jobs that could not be resumed this time (held by a driver, or failed). */
+    skipped: Array<{
+        orgId: string;
+        jobId: string;
+        reason: string;
+    }>;
+    /** Undos found running and untouched, and what resuming each did. */
+    undone: Array<{
+        orgId: string;
+        jobId: string;
+        done: boolean;
+    }>;
+    /** Jobs that never wrote, deleted with their file. */
+    expired: Array<{
+        orgId: string;
+        jobId: string;
+    }>;
+    /** Jobs past their undo window, cleared to the job and its results. */
+    trimmed: Array<{
+        orgId: string;
+        jobId: string;
+    }>;
+}
+/** A job that never wrote, gone: its subcollections, its file, then the job. */
+export declare function expireTransferJob(deps: TransferEngineDeps, job: TransferJobRecord): Promise<void>;
+/** A job past its undo window, kept as the job and its results: the dry run, undo snapshots, ledger and file cleared. */
+export declare function trimTransferJob(deps: TransferEngineDeps, job: TransferJobRecord): Promise<TransferJobRecord>;
+/**
+ * The sweep (see the block header). Each resume runs under the sweep's
+ * lease until the budget is spent; the ledger makes overlapping with a
+ * returning browser harmless. `dryRun` lists what it would do and does
+ * nothing.
+ */
+export declare function sweepAbandonedTransferJobs(deps: TransferEngineDeps, input: {
+    deadlineMs: number;
+    dryRun?: boolean;
+    limit?: number;
+    staleMs?: number;
+}): Promise<TransferSweepOutcome>;