@beechcms/core 0.7.0 → 0.8.1

package/dist/storage.d.ts

@@ -0,0 +1,46 @@
+export interface PutBucketOptions {
+    contentType?: string;
+    metadata?: Record<string, string>;
+}
+export interface GetBucketResult {
+    body: ReadableStream | ArrayBuffer;
+    contentType?: string;
+    size: number;
+    metadata?: Record<string, string>;
+}
+export interface PresignOptions {
+    /** Duration of the signed URL in seconds. */
+    expiresIn: number;
+    /** Content-Type bound in the signature (PUT). */
+    contentType?: string;
+    /** Expected Content-Length in bytes (PUT). */
+    contentLength?: number;
+}
+export interface BeechBucket {
+    put(key: string, body: ArrayBuffer | Uint8Array | ReadableStream, options?: PutBucketOptions): Promise<void>;
+    get(key: string): Promise<GetBucketResult | null>;
+    delete(key: string): Promise<void>;
+    head(key: string): Promise<{
+        size: number;
+        contentType?: string;
+        metadata?: Record<string, string>;
+    } | null>;
+    getUrl(key: string): string;
+    getTotalSize(): Promise<number>;
+    list(options?: {
+        prefix?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        objects: Array<{
+            key: string;
+            size: number;
+        }>;
+        cursor?: string;
+    }>;
+    /** Generates a signed URL for direct upload (PUT). */
+    presignPut(key: string, options: PresignOptions): Promise<string>;
+    /** Generates a signed URL for direct read (GET). */
+    presignGet(key: string, options: PresignOptions): Promise<string>;
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,cAAc,GAAG,WAAW,CAAC;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC7B,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,cAAc,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7G,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;IAClD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IAC7G,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,KAAK,CAAC;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAElJ,sDAAsD;IACtD,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAElE,oDAAoD;IACpD,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACnE"}

package/dist/storage.js

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+export {};

package/dist/transfer/csv.d.ts

@@ -0,0 +1,34 @@
+/** Encodes one cell. `null`/`undefined` become an empty, unquoted field. */
+export declare function encodeCsvValue(value: string | null | undefined): string;
+/** Encodes one row, CRLF terminator included (RFC 4180 §2.1). */
+export declare function encodeCsvRow(cells: Array<string | null | undefined>): string;
+/**
+ * Splits an arbitrarily-chunked CSV text stream into rows of cells.
+ *
+ * Stateful and quote-aware: a newline inside a quoted field is DATA, not a row break, so
+ * a naive `split('\n')` corrupts any export containing a multi-line text branch — which
+ * the export side of this same module is perfectly capable of producing. The parser
+ * therefore carries its in-quotes state across chunk boundaries as well as across lines.
+ */
+export declare class CsvRowReader {
+    private cells;
+    private field;
+    private inQuotes;
+    private quoteJustClosed;
+    private pendingCarriageReturn;
+    private rowHasContent;
+    private sawFirstChunk;
+    /** Feeds a chunk and returns every row completed by it. */
+    push(chunk: string): string[][];
+    /**
+     * Flushes the final row of a file with no trailing newline.
+     * @throws never — an unterminated quote is reported by `hasUnterminatedQuote()` so the
+     *   caller can record it as a failed row rather than losing the whole chunk.
+     */
+    end(): string[][];
+    /** True when `end()` was reached inside an open quoted field — the file is truncated. */
+    hasUnterminatedQuote(): boolean;
+    private pushField;
+    private completeRow;
+}
+//# sourceMappingURL=csv.d.ts.map

package/dist/transfer/csv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csv.d.ts","sourceRoot":"","sources":["../../src/transfer/csv.ts"],"names":[],"mappings":"AAcA,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAIvE;AAED,iEAAiE;AACjE,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,MAAM,CAE5E;AAID;;;;;;;GAOG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,eAAe,CAAQ;IAC/B,OAAO,CAAC,qBAAqB,CAAQ;IACrC,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,aAAa,CAAQ;IAE7B,2DAA2D;IAC3D,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE;IA6D/B;;;;OAIG;IACH,GAAG,IAAI,MAAM,EAAE,EAAE;IAMjB,yFAAyF;IACzF,oBAAoB,IAAI,OAAO;IAI/B,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,WAAW;CAWpB"}

package/dist/transfer/csv.js

@@ -0,0 +1,135 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * RFC 4180 CSV codec. Hand-written rather than pulled from npm: `packages/core` ships to a
+ * Worker bundle and the two rules that matter here (quote-wrap on delimiter/quote/newline,
+ * double the inner quote) are four lines. A dependency would cost more than it saves.
+ */
+const DELIMITER = ',';
+const ROW_TERMINATOR = '\r\n';
+const QUOTE = '"';
+const MUST_QUOTE = /[",\r\n]/;
+/** Encodes one cell. `null`/`undefined` become an empty, unquoted field. */
+export function encodeCsvValue(value) {
+    if (value === null || value === undefined)
+        return '';
+    if (!MUST_QUOTE.test(value))
+        return value;
+    return `${QUOTE}${value.replaceAll(QUOTE, `${QUOTE}${QUOTE}`)}${QUOTE}`;
+}
+/** Encodes one row, CRLF terminator included (RFC 4180 §2.1). */
+export function encodeCsvRow(cells) {
+    return cells.map(encodeCsvValue).join(DELIMITER) + ROW_TERMINATOR;
+}
+const BYTE_ORDER_MARK = '\uFEFF';
+/**
+ * Splits an arbitrarily-chunked CSV text stream into rows of cells.
+ *
+ * Stateful and quote-aware: a newline inside a quoted field is DATA, not a row break, so
+ * a naive `split('\n')` corrupts any export containing a multi-line text branch — which
+ * the export side of this same module is perfectly capable of producing. The parser
+ * therefore carries its in-quotes state across chunk boundaries as well as across lines.
+ */
+export class CsvRowReader {
+    cells = [];
+    field = '';
+    inQuotes = false;
+    quoteJustClosed = false;
+    pendingCarriageReturn = false;
+    rowHasContent = false;
+    sawFirstChunk = false;
+    /** Feeds a chunk and returns every row completed by it. */
+    push(chunk) {
+        let text = chunk;
+        if (!this.sawFirstChunk) {
+            this.sawFirstChunk = true;
+            if (text.startsWith(BYTE_ORDER_MARK))
+                text = text.slice(BYTE_ORDER_MARK.length);
+        }
+        const rows = [];
+        for (const char of text) {
+            if (this.pendingCarriageReturn) {
+                this.pendingCarriageReturn = false;
+                // A lone CR terminates the row too; a CRLF consumes the LF here.
+                const row = this.completeRow();
+                if (row)
+                    rows.push(row);
+                if (char === '\n')
+                    continue;
+            }
+            if (this.inQuotes) {
+                if (this.quoteJustClosed) {
+                    this.quoteJustClosed = false;
+                    if (char === QUOTE) {
+                        this.field += QUOTE; // an escaped quote inside a quoted field
+                        continue;
+                    }
+                    this.inQuotes = false;
+                    // fall through: this char is a normal unquoted char
+                }
+                else if (char === QUOTE) {
+                    this.quoteJustClosed = true;
+                    continue;
+                }
+                else {
+                    this.field += char;
+                    continue;
+                }
+            }
+            if (char === QUOTE) {
+                this.inQuotes = true;
+                this.rowHasContent = true;
+                continue;
+            }
+            if (char === DELIMITER) {
+                this.pushField();
+                continue;
+            }
+            if (char === '\r') {
+                this.pendingCarriageReturn = true;
+                continue;
+            }
+            if (char === '\n') {
+                const row = this.completeRow();
+                if (row)
+                    rows.push(row);
+                continue;
+            }
+            this.field += char;
+            this.rowHasContent = true;
+        }
+        return rows;
+    }
+    /**
+     * Flushes the final row of a file with no trailing newline.
+     * @throws never — an unterminated quote is reported by `hasUnterminatedQuote()` so the
+     *   caller can record it as a failed row rather than losing the whole chunk.
+     */
+    end() {
+        if (this.pendingCarriageReturn)
+            this.pendingCarriageReturn = false;
+        const row = this.completeRow();
+        return row ? [row] : [];
+    }
+    /** True when `end()` was reached inside an open quoted field — the file is truncated. */
+    hasUnterminatedQuote() {
+        return this.inQuotes && !this.quoteJustClosed;
+    }
+    pushField() {
+        this.cells.push(this.field);
+        this.field = '';
+        this.rowHasContent = true;
+    }
+    completeRow() {
+        if (!this.rowHasContent && this.cells.length === 0 && this.field === '')
+            return null;
+        this.cells.push(this.field);
+        const row = this.cells;
+        this.cells = [];
+        this.field = '';
+        this.inQuotes = false;
+        this.quoteJustClosed = false;
+        this.rowHasContent = false;
+        return row;
+    }
+}

package/dist/transfer/flat-seed.d.ts

@@ -0,0 +1,13 @@
+import type { Branch, Seed } from '../engine/types.js';
+import type { FormatCompatibility, TransferFormat } from './transfer.types.js';
+/** Every branch of `seed` that makes it non-flat, in declaration order. Empty when flat. */
+export declare function nonFlatBranches(seed: Seed): Branch[];
+/** A seed is flat when every branch maps to exactly one scalar column. */
+export declare function isFlatSeed(seed: Seed): boolean;
+/**
+ * The single authority on "may this seed be transferred in this format?", shared by the
+ * export endpoint and the import endpoint so the two can never disagree.
+ * NDJSON is universal; CSV requires a flat seed.
+ */
+export declare function checkFormatCompatibility(seed: Seed, format: TransferFormat): FormatCompatibility;
+//# sourceMappingURL=flat-seed.d.ts.map

package/dist/transfer/flat-seed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flat-seed.d.ts","sourceRoot":"","sources":["../../src/transfer/flat-seed.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAc,IAAI,EAAE,MAAM,oBAAoB,CAAA;AAClE,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAqB9E,4FAA4F;AAC5F,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,CAEpD;AAED,0EAA0E;AAC1E,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAE9C;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,cAAc,GACrB,mBAAmB,CAWrB"}

package/dist/transfer/flat-seed.js

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * Branch types whose value is a collection or a nested document, never a scalar cell.
+ * A CSV cell cannot carry them without inventing a flattening convention that the
+ * importer would then have to guess at — which the brief rules out (§5).
+ */
+const NON_FLAT_BRANCH_TYPES = new Set([
+    'relation',
+    'repeater',
+    'tags',
+    'json',
+]);
+/** True for a branch that cannot be represented as a single scalar CSV cell. */
+function isNonFlat(branch) {
+    // A `file` branch is a single URL string — flat — unless it is an asset list.
+    if (branch.type === 'file')
+        return branch.multiple === true;
+    return NON_FLAT_BRANCH_TYPES.has(branch.type);
+}
+/** Every branch of `seed` that makes it non-flat, in declaration order. Empty when flat. */
+export function nonFlatBranches(seed) {
+    return seed.branches.filter(isNonFlat);
+}
+/** A seed is flat when every branch maps to exactly one scalar column. */
+export function isFlatSeed(seed) {
+    return nonFlatBranches(seed).length === 0;
+}
+/**
+ * The single authority on "may this seed be transferred in this format?", shared by the
+ * export endpoint and the import endpoint so the two can never disagree.
+ * NDJSON is universal; CSV requires a flat seed.
+ */
+export function checkFormatCompatibility(seed, format) {
+    if (format === 'ndjson')
+        return { compatible: true };
+    const offenders = nonFlatBranches(seed);
+    if (offenders.length === 0)
+        return { compatible: true };
+    return {
+        compatible: false,
+        code: 'csv_requires_flat_seed',
+        offendingBranches: offenders.map((branch) => ({ alias: branch.alias, type: branch.type })),
+    };
+}

package/dist/transfer/index.d.ts

@@ -0,0 +1,7 @@
+export * from './transfer.types.js';
+export * from './transfer.constants.js';
+export * from './flat-seed.js';
+export * from './ndjson.js';
+export * from './csv.js';
+export * from './row-mapping.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/transfer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/transfer/index.ts"],"names":[],"mappings":"AAGA,cAAc,qBAAqB,CAAA;AACnC,cAAc,yBAAyB,CAAA;AACvC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,UAAU,CAAA;AACxB,cAAc,kBAAkB,CAAA"}

package/dist/transfer/index.js

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+export * from './transfer.types.js';
+export * from './transfer.constants.js';
+export * from './flat-seed.js';
+export * from './ndjson.js';
+export * from './csv.js';
+export * from './row-mapping.js';

package/dist/transfer/ndjson.d.ts

@@ -0,0 +1,25 @@
+import type { LineParseResult, TransferRecord } from './transfer.types.js';
+/** Serialises one record as an NDJSON line, terminator included. */
+export declare function encodeNdjsonLine(record: TransferRecord): string;
+/**
+ * Decodes one NDJSON line. Never throws: a malformed line is a failed row in the job
+ * report, not an aborted import (brief §2 — best-effort, not atomic).
+ */
+export declare function parseNdjsonLine(line: string): LineParseResult;
+/**
+ * Splits an arbitrarily-chunked text stream into complete lines, holding the trailing
+ * partial line until the next chunk completes it. Stateful by necessity: a single
+ * R2 read boundary may fall in the middle of a record, and an import that lost that
+ * record would report a phantom failed row.
+ *
+ * Blank lines are dropped — a trailing newline at end of file is not a record.
+ */
+export declare class LineReader {
+    private buffer;
+    private sawFirstChunk;
+    /** Feeds a chunk and returns every line completed by it. */
+    push(chunk: string): string[];
+    /** Flushes the trailing line of a file that does not end in a newline. */
+    end(): string[];
+}
+//# sourceMappingURL=ndjson.d.ts.map

package/dist/transfer/ndjson.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ndjson.d.ts","sourceRoot":"","sources":["../../src/transfer/ndjson.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAE1E,oEAAoE;AACpE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAE/D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAiB7D;AAID;;;;;;;GAOG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,aAAa,CAAQ;IAE7B,4DAA4D;IAC5D,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE;IAa7B,0EAA0E;IAC1E,GAAG,IAAI,MAAM,EAAE;CAKhB"}

package/dist/transfer/ndjson.js

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/** Serialises one record as an NDJSON line, terminator included. */
+export function encodeNdjsonLine(record) {
+    return `${JSON.stringify(record)}\n`;
+}
+/**
+ * Decodes one NDJSON line. Never throws: a malformed line is a failed row in the job
+ * report, not an aborted import (brief §2 — best-effort, not atomic).
+ */
+export function parseNdjsonLine(line) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            code: 'invalid_json',
+            message: error instanceof Error ? error.message : 'Malformed JSON',
+        };
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { ok: false, code: 'not_an_object', message: 'Line is not a JSON object' };
+    }
+    return { ok: true, record: parsed };
+}
+const BYTE_ORDER_MARK = '\uFEFF';
+/**
+ * Splits an arbitrarily-chunked text stream into complete lines, holding the trailing
+ * partial line until the next chunk completes it. Stateful by necessity: a single
+ * R2 read boundary may fall in the middle of a record, and an import that lost that
+ * record would report a phantom failed row.
+ *
+ * Blank lines are dropped — a trailing newline at end of file is not a record.
+ */
+export class LineReader {
+    buffer = '';
+    sawFirstChunk = false;
+    /** Feeds a chunk and returns every line completed by it. */
+    push(chunk) {
+        let text = chunk;
+        if (!this.sawFirstChunk) {
+            this.sawFirstChunk = true;
+            if (text.startsWith(BYTE_ORDER_MARK))
+                text = text.slice(BYTE_ORDER_MARK.length);
+        }
+        this.buffer += text;
+        const parts = this.buffer.split('\n');
+        this.buffer = parts.pop() ?? '';
+        return parts.map(stripCarriageReturn).filter((line) => line.length > 0);
+    }
+    /** Flushes the trailing line of a file that does not end in a newline. */
+    end() {
+        const remainder = stripCarriageReturn(this.buffer);
+        this.buffer = '';
+        return remainder.length > 0 ? [remainder] : [];
+    }
+}
+function stripCarriageReturn(line) {
+    return line.endsWith('\r') ? line.slice(0, -1) : line;
+}

package/dist/transfer/row-mapping.d.ts

@@ -0,0 +1,36 @@
+import type { Seed } from '../engine/types.js';
+import type { ImportPayload, LineParseResult, TransferRecord } from './transfer.types.js';
+/**
+ * System columns exported for every seed, in this order, ahead of the branch columns.
+ * `deleted_at` is deliberately absent: a trashed row is not exportable content, and the
+ * repository's default `trashed: 'active'` mode never hands one to the producer anyway.
+ */
+export declare const EXPORT_SYSTEM_COLUMNS: readonly ["id", "slug", "status", "created_at", "updated_at"];
+/**
+ * The ordered column projection for exporting `seed`: system columns, then one column per
+ * scalar branch in declaration order. Non-flat branches are omitted — this projection is
+ * only ever used for CSV, and `checkFormatCompatibility` has already refused a seed that
+ * has any. NDJSON export emits the record whole and does not call this.
+ */
+export declare function exportColumns(seed: Seed): string[];
+/**
+ * Projects an API-shaped record onto `columns` as CSV cells.
+ * `null`/`undefined` become an empty field; booleans become `true`/`false`; everything else
+ * is stringified. The record is expected to have already passed through `dbToApi`, so a
+ * `date` branch arrives as a number and is written as its unix-seconds integer.
+ */
+export declare function toCsvCells(record: TransferRecord, columns: string[]): Array<string | null>;
+/**
+ * Rebuilds a record from a CSV row. An empty cell is treated as ABSENT, not as null:
+ * CSV cannot distinguish the two, and omitting the key lets the engine's own
+ * required-field validation produce the error instead of this module guessing.
+ */
+export declare function fromCsvCells(columns: string[], cells: string[]): LineParseResult;
+/**
+ * Splits a decoded record into the shape `ContentRepository.create` consumes, dropping the
+ * engine-owned columns. Returns `data` WITHOUT `slug`/`status`, mirroring
+ * `apps/api/src/features/content/handlers/create.ts:68-70`, so the import consumer can feed
+ * `data` straight to `validateAndSanitizeSeedPayload` without re-filtering.
+ */
+export declare function toImportPayload(record: TransferRecord): ImportPayload;
+//# sourceMappingURL=row-mapping.d.ts.map

package/dist/transfer/row-mapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"row-mapping.d.ts","sourceRoot":"","sources":["../../src/transfer/row-mapping.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAA;AAE9C,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAEzF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,+DAAgE,CAAA;AAclG;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,CAMlD;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,CAO1F;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,eAAe,CAgBhF;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,aAAa,CAYrE"}

package/dist/transfer/row-mapping.js

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { nonFlatBranches } from './flat-seed.js';
+/**
+ * System columns exported for every seed, in this order, ahead of the branch columns.
+ * `deleted_at` is deliberately absent: a trashed row is not exportable content, and the
+ * repository's default `trashed: 'active'` mode never hands one to the producer anyway.
+ */
+export const EXPORT_SYSTEM_COLUMNS = ['id', 'slug', 'status', 'created_at', 'updated_at'];
+/**
+ * Columns the importer must never accept from a file: the engine owns them.
+ * `id` is minted by `idGenerator.uuid()`, the timestamps by SQLite defaults. Accepting an
+ * `id` from a file would also turn insert-only import (brief §2) into a covert upsert.
+ */
+const IMPORT_REJECTED_COLUMNS = new Set([
+    'id',
+    'created_at',
+    'updated_at',
+    'deleted_at',
+]);
+/**
+ * The ordered column projection for exporting `seed`: system columns, then one column per
+ * scalar branch in declaration order. Non-flat branches are omitted — this projection is
+ * only ever used for CSV, and `checkFormatCompatibility` has already refused a seed that
+ * has any. NDJSON export emits the record whole and does not call this.
+ */
+export function exportColumns(seed) {
+    const excluded = new Set(nonFlatBranches(seed).map((branch) => branch.alias));
+    return [
+        ...EXPORT_SYSTEM_COLUMNS,
+        ...seed.branches.map((branch) => branch.alias).filter((alias) => !excluded.has(alias)),
+    ];
+}
+/**
+ * Projects an API-shaped record onto `columns` as CSV cells.
+ * `null`/`undefined` become an empty field; booleans become `true`/`false`; everything else
+ * is stringified. The record is expected to have already passed through `dbToApi`, so a
+ * `date` branch arrives as a number and is written as its unix-seconds integer.
+ */
+export function toCsvCells(record, columns) {
+    return columns.map((column) => {
+        const value = record[column];
+        if (value === null || value === undefined)
+            return null;
+        if (typeof value === 'boolean')
+            return value ? 'true' : 'false';
+        return String(value);
+    });
+}
+/**
+ * Rebuilds a record from a CSV row. An empty cell is treated as ABSENT, not as null:
+ * CSV cannot distinguish the two, and omitting the key lets the engine's own
+ * required-field validation produce the error instead of this module guessing.
+ */
+export function fromCsvCells(columns, cells) {
+    if (cells.length !== columns.length) {
+        return {
+            ok: false,
+            code: 'column_count_mismatch',
+            message: `Expected ${columns.length} columns, received ${cells.length}`,
+        };
+    }
+    const record = {};
+    for (const [index, column] of columns.entries()) {
+        const cell = cells[index] ?? '';
+        if (cell === '')
+            continue;
+        record[column] = cell;
+    }
+    return { ok: true, record };
+}
+/**
+ * Splits a decoded record into the shape `ContentRepository.create` consumes, dropping the
+ * engine-owned columns. Returns `data` WITHOUT `slug`/`status`, mirroring
+ * `apps/api/src/features/content/handlers/create.ts:68-70`, so the import consumer can feed
+ * `data` straight to `validateAndSanitizeSeedPayload` without re-filtering.
+ */
+export function toImportPayload(record) {
+    const data = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (IMPORT_REJECTED_COLUMNS.has(key))
+            continue;
+        if (key === 'slug' || key === 'status')
+            continue;
+        data[key] = value;
+    }
+    const slug = typeof record['slug'] === 'string' && record['slug'] !== '' ? record['slug'] : undefined;
+    const status = typeof record['status'] === 'string' && record['status'] !== '' ? record['status'] : undefined;
+    return { ...(slug ? { slug } : {}), ...(status ? { status } : {}), data };
+}

package/dist/transfer/transfer.constants.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Hard cap on rows a single synchronous export may stream (brief §2). Past this the
+ * endpoint answers 413 rather than opening a stream that the edge may truncate mid-file.
+ * Overridable per deployment by the API layer (S2) — this is the default, not the law.
+ */
+export declare const DEFAULT_EXPORT_MAX_ROWS = 50000;
+/** Page size for the export producer's findMany loop. Never materialise the full set. */
+export declare const DEFAULT_EXPORT_PAGE_SIZE = 500;
+/**
+ * Rows an import consumer processes per queue invocation before persisting its offset
+ * and re-enqueuing (brief §2). Sized well under the Workers CPU budget so a chunk that
+ * retries repeats at most this many already-inserted rows.
+ */
+export declare const DEFAULT_IMPORT_CHUNK_ROWS = 500;
+/**
+ * Upper bound on per-row errors retained in a job report (brief §4). Beyond this only
+ * the aggregate failure count grows, so one pathological file cannot unbound the row.
+ */
+export declare const MAX_JOB_ERROR_SAMPLES = 100;
+//# sourceMappingURL=transfer.constants.d.ts.map

package/dist/transfer/transfer.constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transfer.constants.d.ts","sourceRoot":"","sources":["../../src/transfer/transfer.constants.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,QAAS,CAAA;AAE7C,yFAAyF;AACzF,eAAO,MAAM,wBAAwB,MAAM,CAAA;AAE3C;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,MAAM,CAAA;AAE5C;;;GAGG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAA"}

package/dist/transfer/transfer.constants.js

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * Hard cap on rows a single synchronous export may stream (brief §2). Past this the
+ * endpoint answers 413 rather than opening a stream that the edge may truncate mid-file.
+ * Overridable per deployment by the API layer (S2) — this is the default, not the law.
+ */
+export const DEFAULT_EXPORT_MAX_ROWS = 50_000;
+/** Page size for the export producer's findMany loop. Never materialise the full set. */
+export const DEFAULT_EXPORT_PAGE_SIZE = 500;
+/**
+ * Rows an import consumer processes per queue invocation before persisting its offset
+ * and re-enqueuing (brief §2). Sized well under the Workers CPU budget so a chunk that
+ * retries repeats at most this many already-inserted rows.
+ */
+export const DEFAULT_IMPORT_CHUNK_ROWS = 500;
+/**
+ * Upper bound on per-row errors retained in a job report (brief §4). Beyond this only
+ * the aggregate failure count grows, so one pathological file cannot unbound the row.
+ */
+export const MAX_JOB_ERROR_SAMPLES = 100;

package/dist/transfer/transfer.types.d.ts

@@ -0,0 +1,46 @@
+import type { Branch } from '../engine/types.js';
+/** Wire formats supported for bulk transfer. NDJSON is universal; CSV is flat-only. */
+export type TransferFormat = 'csv' | 'ndjson';
+export declare const TRANSFER_FORMATS: readonly ["csv", "ndjson"];
+export declare function isTransferFormat(value: unknown): value is TransferFormat;
+/**
+ * Outcome of checking a requested format against a seed's shape.
+ * `offendingBranches` is non-empty only on the incompatible branch, and exists so the
+ * caller can name the exact fields in its 400 response instead of a generic message.
+ */
+export type FormatCompatibility = {
+    compatible: true;
+} | {
+    compatible: false;
+    code: 'csv_requires_flat_seed';
+    offendingBranches: Array<{
+        alias: string;
+        type: Branch['type'];
+    }>;
+};
+/** A decoded wire row, keyed by branch alias / system column name. */
+export type TransferRecord = Record<string, unknown>;
+/**
+ * Per-line decode outcome. Import is best-effort (brief §2), so a bad line is a VALUE,
+ * never a thrown error — the consumer must record it in the job report and keep going.
+ */
+export type LineParseResult = {
+    ok: true;
+    record: TransferRecord;
+} | {
+    ok: false;
+    code: LineParseErrorCode;
+    message: string;
+};
+export type LineParseErrorCode = 'invalid_json' | 'not_an_object' | 'column_count_mismatch' | 'unterminated_quote';
+/**
+ * A decoded row split into the three arguments `ContentRepository.create` takes.
+ * `slug` and `status` are optional: the caller supplies its own defaults
+ * (`create.ts` slugifies the display-name branch and defaults status to 'draft').
+ */
+export interface ImportPayload {
+    slug?: string;
+    status?: string;
+    data: TransferRecord;
+}
+//# sourceMappingURL=transfer.types.d.ts.map

package/dist/transfer/transfer.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transfer.types.d.ts","sourceRoot":"","sources":["../../src/transfer/transfer.types.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAEhD,uFAAuF;AACvF,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,QAAQ,CAAA;AAE7C,eAAO,MAAM,gBAAgB,4BAAiE,CAAA;AAE9F,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAExE;AAED;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IAAE,UAAU,EAAE,IAAI,CAAA;CAAE,GACpB;IACE,UAAU,EAAE,KAAK,CAAA;IACjB,IAAI,EAAE,wBAAwB,CAAA;IAC9B,iBAAiB,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAA;KAAE,CAAC,CAAA;CAClE,CAAA;AAEL,sEAAsE;AACtE,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAEpD;;;GAGG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,cAAc,CAAA;CAAE,GACpC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,kBAAkB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AAE5D,MAAM,MAAM,kBAAkB,GAC1B,cAAc,GACd,eAAe,GACf,uBAAuB,GACvB,oBAAoB,CAAA;AAExB;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,cAAc,CAAA;CACrB"}

package/dist/transfer/transfer.types.js

@@ -0,0 +1,6 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+export const TRANSFER_FORMATS = ['csv', 'ndjson'];
+export function isTransferFormat(value) {
+    return typeof value === 'string' && TRANSFER_FORMATS.includes(value);
+}