@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/csp-report.js

@@ -0,0 +1,177 @@
+/**
+ * @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.
+ */ /**
+ * Reading CSP violation reports (AGL-523).
+ *
+ * The report-only policy has shipped since AGL-518 with **no reporting
+ * directive at all**, so every violation it detected went to the console of
+ * whoever happened to have devtools open and nowhere else. The evidence the
+ * issue wanted before flipping to enforcing — "confirm no legitimate script is
+ * being reported" — has therefore never existed, and the choice between
+ * `strict-dynamic` and `'self' https: blob:` is currently a guess.
+ *
+ * Pure, and separate from the route, because the interesting part is not the
+ * HTTP: it is deciding which reports are worth keeping.
+ *
+ * Lives in a lib rather than `apps/console/utils` since AGL-1703, which gave
+ * the tenant its own collector. The two ROUTES are different — the tenant's is
+ * driven by anonymous visitors to every published customer site, so it carries
+ * limiters the console's does not need — but normalizing two wire formats and
+ * throwing away extension noise is the same job on both, and a second copy of
+ * a parser that reads hostile input is a second thing to get wrong.
+ *
+ * ## Why filtering is the whole job
+ *
+ * A CSP endpoint that logs everything is worse than none. Browser extensions
+ * inject inline scripts into every page they touch, and each injection is a
+ * violation — so an unfiltered collector on a logged-in app produces a
+ * firehose of reports about code we do not ship and cannot fix. The signal
+ * (one of OUR scripts is unnonced) drowns, the flip decision stays unmade,
+ * and the log bill is real. Filtering at the edge, before anything is
+ * emitted, is what makes the data usable.
+ */ // A violation from a scheme no deployment of ours serves is never ours to fix.
+// The error beacon reads the same list off a stack's frames, so it lives in
+// one place — see `FOREIGN_SCRIPT_SCHEMES`.
+import { isForeignScriptUrl as isForeign } from "./foreign-script.js";
+/** Trim a value that a hostile client controls, and that we log. */ const clamp = (value, max)=>typeof value === 'string' ? value.slice(0, max) : '';
+/**
+ * The document URL reduced to its path.
+ *
+ * Query and fragment are dropped deliberately, for two reasons that point the
+ * same way: they can carry user data we have no business logging, and keeping
+ * them would split one recurring violation into a different line per visitor.
+ * The path is what identifies the surface, which is what a fix needs.
+ */ export function documentPath(rawUrl) {
+    const value = clamp(rawUrl, 2048);
+    if (!value) return '';
+    try {
+        return new URL(value).pathname;
+    } catch (unused) {
+        // Not a URL. Keep something rather than dropping the report, but never
+        // echo an unbounded attacker-supplied string into the log.
+        return value.slice(0, 200);
+    }
+}
+/**
+ * Normalize every wire format into `CspViolation[]`.
+ *
+ * There are THREE, not two, and all three are live (AGL-1788, measured in real
+ * browsers against a real response rather than read from a spec):
+ *
+ * 1. **Legacy** — `{"csp-report": {...}}`, kebab-case keys,
+ *    `application/csp-report`. What `report-uri` posts when the policy carries
+ *    no `report-to`.
+ * 2. **Reporting API** — an ARRAY of `{type, body}` with camelCase keys,
+ *    `application/reports+json`. What Chrome posts for `report-to`, batched.
+ * 3. **Safari's hybrid** — a SINGLE `{type, url, body}` with the camelCase
+ *    body of (2) but the `application/csp-report` content type of (1). Safari
+ *    switches to the modern body shape as soon as `report-to` is present in
+ *    the policy, without adopting the array envelope.
+ *
+ * Shape (3) is why this comment exists. It parsed as neither of the other two
+ * — not an array, and no `csp-report` key — so it fell through to `[]`, and
+ * the console and tenant collectors silently discarded every report Safari
+ * sent for as long as the policy has carried both directives. A dropped report
+ * and a clean page are indistinguishable downstream, which is the same
+ * false all-clear AGL-518 shipped.
+ */ export function parseCspReports(payload) {
+    if (!payload || typeof payload !== 'object') return [];
+    // Reporting API: an array of envelopes, possibly mixed with other report
+    // types (deprecation, intervention) that share the endpoint.
+    if (Array.isArray(payload)) {
+        return payload.filter(isViolationEnvelope).map((entry)=>fromModern(entry.body)).filter((violation)=>violation !== null);
+    }
+    const legacy = payload['csp-report'];
+    if (legacy && typeof legacy === 'object') {
+        const violation = fromLegacy(legacy);
+        return violation ? [
+            violation
+        ] : [];
+    }
+    // Safari's single envelope. Checked AFTER `csp-report` so a legacy body that
+    // happens to carry a `body` key cannot be read with the wrong key set, and
+    // gated on `type` so this cannot swallow an unrelated object shape.
+    if (isViolationEnvelope(payload)) {
+        const violation = fromModern(payload.body);
+        return violation ? [
+            violation
+        ] : [];
+    }
+    return [];
+}
+/** A Reporting API envelope that is specifically a CSP violation. */ const isViolationEnvelope = (entry)=>!!entry && typeof entry === 'object' && entry.type === 'csp-violation';
+function fromModern(body) {
+    if (!body || typeof body !== 'object') return null;
+    const b = body;
+    return {
+        documentPath: documentPath(b['documentURL']),
+        effectiveDirective: clamp(b['effectiveDirective'], 64),
+        blockedUri: clamp(b['blockedURL'], 512),
+        sourceFile: clamp(b['sourceFile'], 512),
+        sample: clamp(b['sample'], 80),
+        lineNumber: typeof b['lineNumber'] === 'number' ? b['lineNumber'] : null,
+        disposition: clamp(b['disposition'], 16) || 'report'
+    };
+}
+function fromLegacy(body) {
+    if (!body || typeof body !== 'object') return null;
+    const b = body;
+    return {
+        documentPath: documentPath(b['document-uri']),
+        // `effective-directive` is the precise one but older browsers only send
+        // `violated-directive`, which carries the whole source list. Take the
+        // directive name off the front so both shapes group together.
+        effectiveDirective: clamp(b['effective-directive'], 64) || clamp(b['violated-directive'], 256).split(/\s+/)[0] || '',
+        blockedUri: clamp(b['blocked-uri'], 512),
+        sourceFile: clamp(b['source-file'], 512),
+        sample: clamp(b['script-sample'], 80),
+        lineNumber: typeof b['line-number'] === 'number' ? b['line-number'] : null,
+        disposition: clamp(b['disposition'], 16) || 'report'
+    };
+}
+/**
+ * Is this violation about code we ship?
+ *
+ * The test is the SOURCE of the offending script, not what was blocked. An
+ * extension injecting an inline script reports `blocked-uri: inline` — exactly
+ * what one of our own unnonced scripts reports — and the only thing that
+ * separates them is `source-file` naming the extension. Filtering on
+ * `blocked-uri` alone would therefore throw away the signal and keep the noise,
+ * which is the failure mode worth being careful about.
+ */ export function isActionableViolation(violation) {
+    if (!violation.effectiveDirective) return false;
+    if (isForeign(violation.sourceFile)) return false;
+    if (isForeign(violation.blockedUri)) return false;
+    // Safari reports some extension violations with the page as `source-file`
+    // and nothing blocked at all. Nothing to act on either way.
+    if (!violation.blockedUri && !violation.sample) return false;
+    return true;
+}
+/**
+ * A stable grouping key, so a recurring violation reads as one problem.
+ *
+ * Line numbers and samples are deliberately absent: a bundle rebuild moves
+ * every line, and the point of the key is that the same defect keeps the same
+ * identity across deploys.
+ */ export function violationKey(violation) {
+    return [
+        violation.effectiveDirective,
+        violation.blockedUri,
+        violation.documentPath
+    ].join('|');
+}
+
+//# sourceMappingURL=csp-report.js.map

package/src/lib/app-utils/csp-report.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/csp-report.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 * Reading CSP violation reports (AGL-523).\n *\n * The report-only policy has shipped since AGL-518 with **no reporting\n * directive at all**, so every violation it detected went to the console of\n * whoever happened to have devtools open and nowhere else. The evidence the\n * issue wanted before flipping to enforcing — \"confirm no legitimate script is\n * being reported\" — has therefore never existed, and the choice between\n * `strict-dynamic` and `'self' https: blob:` is currently a guess.\n *\n * Pure, and separate from the route, because the interesting part is not the\n * HTTP: it is deciding which reports are worth keeping.\n *\n * Lives in a lib rather than `apps/console/utils` since AGL-1703, which gave\n * the tenant its own collector. The two ROUTES are different — the tenant's is\n * driven by anonymous visitors to every published customer site, so it carries\n * limiters the console's does not need — but normalizing two wire formats and\n * throwing away extension noise is the same job on both, and a second copy of\n * a parser that reads hostile input is a second thing to get wrong.\n *\n * ## Why filtering is the whole job\n *\n * A CSP endpoint that logs everything is worse than none. Browser extensions\n * inject inline scripts into every page they touch, and each injection is a\n * violation — so an unfiltered collector on a logged-in app produces a\n * firehose of reports about code we do not ship and cannot fix. The signal\n * (one of OUR scripts is unnonced) drowns, the flip decision stays unmade,\n * and the log bill is real. Filtering at the edge, before anything is\n * emitted, is what makes the data usable.\n */\n\n// A violation from a scheme no deployment of ours serves is never ours to fix.\n// The error beacon reads the same list off a stack's frames, so it lives in\n// one place — see `FOREIGN_SCRIPT_SCHEMES`.\nimport { isForeignScriptUrl as isForeign } from './foreign-script'\n\n/** One violation, normalized across the two wire formats. */\nexport interface CspViolation {\n  /** The page, PATH ONLY — see `documentPath`. */\n  documentPath: string\n  /** e.g. `script-src-elem`. */\n  effectiveDirective: string\n  /** What was blocked: a URL, or `inline` / `eval`. */\n  blockedUri: string\n  /** The script that triggered it, when the browser names one. */\n  sourceFile: string\n  /** Browser-capped excerpt of the offending inline script. */\n  sample: string\n  lineNumber: number | null\n  /** `enforce` or `report`. */\n  disposition: string\n}\n\n/** Trim a value that a hostile client controls, and that we log. */\nconst clamp = (value: unknown, max: number): string =>\n  typeof value === 'string' ? value.slice(0, max) : ''\n\n/**\n * The document URL reduced to its path.\n *\n * Query and fragment are dropped deliberately, for two reasons that point the\n * same way: they can carry user data we have no business logging, and keeping\n * them would split one recurring violation into a different line per visitor.\n * The path is what identifies the surface, which is what a fix needs.\n */\nexport function documentPath(rawUrl: unknown): string {\n  const value = clamp(rawUrl, 2048)\n  if (!value) return ''\n  try {\n    return new URL(value).pathname\n  } catch {\n    // Not a URL. Keep something rather than dropping the report, but never\n    // echo an unbounded attacker-supplied string into the log.\n    return value.slice(0, 200)\n  }\n}\n\n/**\n * Normalize every wire format into `CspViolation[]`.\n *\n * There are THREE, not two, and all three are live (AGL-1788, measured in real\n * browsers against a real response rather than read from a spec):\n *\n * 1. **Legacy** — `{\"csp-report\": {...}}`, kebab-case keys,\n *    `application/csp-report`. What `report-uri` posts when the policy carries\n *    no `report-to`.\n * 2. **Reporting API** — an ARRAY of `{type, body}` with camelCase keys,\n *    `application/reports+json`. What Chrome posts for `report-to`, batched.\n * 3. **Safari's hybrid** — a SINGLE `{type, url, body}` with the camelCase\n *    body of (2) but the `application/csp-report` content type of (1). Safari\n *    switches to the modern body shape as soon as `report-to` is present in\n *    the policy, without adopting the array envelope.\n *\n * Shape (3) is why this comment exists. It parsed as neither of the other two\n * — not an array, and no `csp-report` key — so it fell through to `[]`, and\n * the console and tenant collectors silently discarded every report Safari\n * sent for as long as the policy has carried both directives. A dropped report\n * and a clean page are indistinguishable downstream, which is the same\n * false all-clear AGL-518 shipped.\n */\nexport function parseCspReports(payload: unknown): CspViolation[] {\n  if (!payload || typeof payload !== 'object') return []\n\n  // Reporting API: an array of envelopes, possibly mixed with other report\n  // types (deprecation, intervention) that share the endpoint.\n  if (Array.isArray(payload)) {\n    return payload\n      .filter(isViolationEnvelope)\n      .map((entry) => fromModern((entry as { body?: unknown }).body))\n      .filter((violation): violation is CspViolation => violation !== null)\n  }\n\n  const legacy = (payload as { 'csp-report'?: unknown })['csp-report']\n  if (legacy && typeof legacy === 'object') {\n    const violation = fromLegacy(legacy)\n    return violation ? [violation] : []\n  }\n\n  // Safari's single envelope. Checked AFTER `csp-report` so a legacy body that\n  // happens to carry a `body` key cannot be read with the wrong key set, and\n  // gated on `type` so this cannot swallow an unrelated object shape.\n  if (isViolationEnvelope(payload)) {\n    const violation = fromModern((payload as { body?: unknown }).body)\n    return violation ? [violation] : []\n  }\n  return []\n}\n\n/** A Reporting API envelope that is specifically a CSP violation. */\nconst isViolationEnvelope = (entry: unknown): boolean =>\n  !!entry &&\n  typeof entry === 'object' &&\n  (entry as { type?: unknown }).type === 'csp-violation'\n\nfunction fromModern(body: unknown): CspViolation | null {\n  if (!body || typeof body !== 'object') return null\n  const b = body as Record<string, unknown>\n  return {\n    documentPath: documentPath(b['documentURL']),\n    effectiveDirective: clamp(b['effectiveDirective'], 64),\n    blockedUri: clamp(b['blockedURL'], 512),\n    sourceFile: clamp(b['sourceFile'], 512),\n    sample: clamp(b['sample'], 80),\n    lineNumber: typeof b['lineNumber'] === 'number' ? b['lineNumber'] : null,\n    disposition: clamp(b['disposition'], 16) || 'report',\n  }\n}\n\nfunction fromLegacy(body: unknown): CspViolation | null {\n  if (!body || typeof body !== 'object') return null\n  const b = body as Record<string, unknown>\n  return {\n    documentPath: documentPath(b['document-uri']),\n    // `effective-directive` is the precise one but older browsers only send\n    // `violated-directive`, which carries the whole source list. Take the\n    // directive name off the front so both shapes group together.\n    effectiveDirective:\n      clamp(b['effective-directive'], 64) ||\n      clamp(b['violated-directive'], 256).split(/\\s+/)[0] ||\n      '',\n    blockedUri: clamp(b['blocked-uri'], 512),\n    sourceFile: clamp(b['source-file'], 512),\n    sample: clamp(b['script-sample'], 80),\n    lineNumber: typeof b['line-number'] === 'number' ? b['line-number'] : null,\n    disposition: clamp(b['disposition'], 16) || 'report',\n  }\n}\n\n/**\n * Is this violation about code we ship?\n *\n * The test is the SOURCE of the offending script, not what was blocked. An\n * extension injecting an inline script reports `blocked-uri: inline` — exactly\n * what one of our own unnonced scripts reports — and the only thing that\n * separates them is `source-file` naming the extension. Filtering on\n * `blocked-uri` alone would therefore throw away the signal and keep the noise,\n * which is the failure mode worth being careful about.\n */\nexport function isActionableViolation(violation: CspViolation): boolean {\n  if (!violation.effectiveDirective) return false\n  if (isForeign(violation.sourceFile)) return false\n  if (isForeign(violation.blockedUri)) return false\n  // Safari reports some extension violations with the page as `source-file`\n  // and nothing blocked at all. Nothing to act on either way.\n  if (!violation.blockedUri && !violation.sample) return false\n  return true\n}\n\n/**\n * A stable grouping key, so a recurring violation reads as one problem.\n *\n * Line numbers and samples are deliberately absent: a bundle rebuild moves\n * every line, and the point of the key is that the same defect keeps the same\n * identity across deploys.\n */\nexport function violationKey(violation: CspViolation): string {\n  return [\n    violation.effectiveDirective,\n    violation.blockedUri,\n    violation.documentPath,\n  ].join('|')\n}\n"],"names":["isForeignScriptUrl","isForeign","clamp","value","max","slice","documentPath","rawUrl","URL","pathname","parseCspReports","payload","Array","isArray","filter","isViolationEnvelope","map","entry","fromModern","body","violation","legacy","fromLegacy","type","b","effectiveDirective","blockedUri","sourceFile","sample","lineNumber","disposition","split","isActionableViolation","violationKey","join"],"mappings":"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"}

package/src/lib/app-utils/csv-import.d.ts

@@ -0,0 +1,192 @@
+/**
+ * @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.
+ */
+/**
+ * READING A SPREADSHEET INTO A CRM COLLECTION — the part that does not care
+ * which collection (AGL-2621).
+ *
+ * The contact import (AGL-2602) settled how a file becomes records: a
+ * header row is matched against an alias table to PROPOSE a column → field
+ * mapping, the operator corrects it, one line is mapped to a raw row of
+ * verbatim strings, and the server judges each row and tallies what it did.
+ * A companies file goes through the same three stages with a different
+ * field list, so the stages live here, parametric over the field union, and
+ * the CRM plugin's contact and company importers each supply their vocabulary
+ * — the fields, their aliases, their labels — and nothing else.
+ *
+ * ## A custom target is `custom:<key>`
+ *
+ * A column may also map to a custom field the merchant defined, which has
+ * no standard name. The target is one string rather than a discriminated
+ * object because it is the VALUE of a select control and travels through a
+ * form; the prefix is what tells the two apart on the way back.
+ *
+ * ## The ceilings are shared numbers
+ *
+ * One file, one request and one preview are bounded the same way for every
+ * collection, because the bounds are about the browser's memory and a
+ * console request's budget, not about what the rows hold.
+ */
+/**
+ * The most rows one uploaded file may carry.
+ *
+ * A bound on the work one import represents and on the memory the browser
+ * holds while mapping it — five thousand rows of a wide export is already
+ * several megabytes of cells in a tab. A larger list is split and imported
+ * in pieces; the drawer says so on the file, before a single row is sent.
+ */
+export declare const CSV_IMPORT_MAX_ROWS = 5000;
+/**
+ * Rows per request.
+ *
+ * Each row costs the server a lookup and a write, plus whatever a name it
+ * has not seen in this request costs to resolve; two hundred of those sit
+ * comfortably inside a console request's budget and give the progress bar
+ * twenty-five steps on the largest file the drawer accepts.
+ */
+export declare const CSV_IMPORT_CHUNK_SIZE = 200;
+/**
+ * The most bytes one request may carry, checked before the body is judged.
+ *
+ * Two hundred rows of a wide export with long values is well under a
+ * megabyte; two megabytes is the line past which a request is not a chunk
+ * of a file but something else being pushed through this door.
+ */
+export declare const CSV_IMPORT_MAX_BODY_BYTES = 2000000;
+/** How many mapped rows the drawer shows before the operator commits. */
+export declare const CSV_IMPORT_PREVIEW_ROWS = 10;
+/** The custom-field target id for a definition key. */
+export declare function customImportTarget(key: string): `custom:${string}`;
+/** The definition key a custom target names, or `null` for a standard field. */
+export declare function customImportTargetKey(target: string): string | null;
+/**
+ * Normalizes a header cell for alias matching.
+ *
+ * Underscores, dots and hyphens all become one space, so `e-mail`,
+ * `email_address` and `Email Address` compare as the words they are. The
+ * alias tables are written in the human spelling and pass through the same
+ * function, so a table stays readable and the comparison stays exact.
+ */
+export declare function importHeaderKey(value: unknown): string;
+/** An alias table, normalized once through {@link importHeaderKey}. */
+export declare function importAliasKeys<F extends string>(fields: readonly F[], aliases: Record<F, readonly string[]>): Record<F, ReadonlySet<string>>;
+/**
+ * A proposed mapping from a file's header row.
+ *
+ * Custom fields win over standard aliases when a header matches a
+ * definition's label or key exactly — a merchant who defined a field called
+ * "Status" meant THEIR status, not our lifecycle stage. Each target is
+ * taken at most once, by the first column that claims it, so a file with two
+ * columns named "Email" maps the first and leaves the second for the
+ * operator to decide.
+ */
+export declare function guessImportMapping<F extends string>(columns: readonly string[], fields: readonly F[], aliasKeys: Record<F, ReadonlySet<string>>): Record<number, F>;
+export declare function guessImportMapping<F extends string>(columns: readonly string[], fields: readonly F[], aliasKeys: Record<F, ReadonlySet<string>>, customFields: readonly {
+    key: string;
+    label: string;
+}[]): Record<number, F | `custom:${string}`>;
+/**
+ * One parsed line under a mapping: the cells the mapping selected, under the
+ * field they were mapped to, verbatim, with custom values gathered under
+ * `custom` by definition key. Empty cells are left absent.
+ */
+export declare function mapImportRow<F extends string>(cells: readonly string[], mapping: Record<number, F | `custom:${string}`>): Partial<Record<F, string>> & {
+    custom?: Record<string, string>;
+};
+/**
+ * A tag cell as the tags it names.
+ *
+ * `|` or `,` separated — the CSV export writes `|`, most other products
+ * write `,` — lowercased and trimmed like a record's own tag field, so an
+ * imported `VIP` and a typed `vip` are one tag and not two.
+ */
+export declare function parseImportTags(value: unknown, max: number): string[];
+/**
+ * A yes/no cell as a boolean, or `null` when it is neither.
+ *
+ * The affirmatives are the ones consent and checkbox columns actually
+ * carry; the negatives are listed so that an explicit `no` is a `false`
+ * rather than an unreadable value that gets reported as dropped.
+ */
+export declare function parseImportFlag(value: unknown): boolean | null;
+/** A cell as trimmed text capped at `max`, or `undefined` when blank. */
+export declare function importTextValue(value: unknown, max: number): string | undefined;
+/** A cell the file carried that could not be read as the field it was mapped to. */
+export interface ImportDroppedValue {
+    /** The standard field name, or `custom:<key>`. */
+    field: string;
+    value: string;
+}
+/** A CSV cell, quoted only when it has to be. */
+export declare function csvCell(value: unknown): string;
+/**
+ * A whole CSV — the header, then one line per row — through {@link csvCell}.
+ *
+ * The one serializer for every CSV the console writes: each CRM section's
+ * export, the skipped-rows file an import hands back and each report
+ * table's export.
+ * Quoting is decided in {@link csvCell} and nowhere else — a cell holding a
+ * comma, a quote or a line break is wrapped in quotes with its quotes
+ * doubled, no other cell is touched, and a `null` or `undefined` cell is
+ * empty rather than the word — so that a report's file and a contacts file
+ * open the same way in a spreadsheet.
+ */
+export declare function csvDocument(header: readonly unknown[], rows: readonly (readonly unknown[])[]): string;
+/**
+ * The skipped rows as a file the operator can fix and re-import.
+ *
+ * The original columns verbatim plus a trailing `Skipped because` column,
+ * so the file round-trips: correct the cell, delete the last column or
+ * leave it unmapped, and import it again.
+ */
+export declare function importSkippedCsv<R extends string>(columns: readonly string[], entries: readonly {
+    cells: readonly string[];
+    reason: R;
+}[], labels: Record<R, string>): string;
+/**
+ * One row the server did not store, by its index in the request. Each
+ * collection names the row back to the operator in its own field — an
+ * address, a company name — beside these two.
+ */
+export interface ImportSkippedRow<R extends string> {
+    index: number;
+    reason: R;
+}
+/**
+ * What one request did, in the shape every collection's import reports.
+ * The drawer sums these across a file; a collection with more to say
+ * extends the shape and folds its own field beside {@link mergeImportResults}.
+ */
+export interface ImportChunkResult<S extends ImportSkippedRow<string>> {
+    received: number;
+    created: number;
+    merged: number;
+    skipped: S[];
+    /** Unreadable cells, tallied by field. */
+    dropped: Record<string, number>;
+    /** Owner addresses that matched no member of the organization. */
+    ownersUnresolved: string[];
+}
+/** An empty tally, for the drawer to fold chunk results into. */
+export declare function emptyImportResult<S extends ImportSkippedRow<string>>(): ImportChunkResult<S>;
+/**
+ * Two results as one.
+ *
+ * `offset` is where the chunk started in the file, so a skipped row's index
+ * comes back as its position in the FILE rather than in the request — which
+ * is what the download of skipped rows has to look up.
+ */
+export declare function mergeImportResults<S extends ImportSkippedRow<string>>(total: ImportChunkResult<S>, chunk: Partial<ImportChunkResult<S>>, offset?: number): ImportChunkResult<S>;