@oxygen-agent/cli 1.1014.985 → 1.1014.1087

package/dist/command-families/tables/import-batches.js

@@ -0,0 +1,94 @@
+import { readCount } from "../../command-support.js";
+import { requestOxygen } from "../../http-client.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { MAX_CLI_JSON_BODY_BYTES } from "@oxygen/shared/plan-limits";
+export async function writeImportBatchWithAutoSplit(input) {
+    const body = {
+        table: input.tableRef,
+        rows: input.rows,
+        ...(input.upsertKey ? { key: input.upsertKey } : {}),
+        ...(!input.upsertKey && input.requestId ? { request_id: input.requestId } : {}),
+    };
+    // The server checks content-length against MAX_CLI_JSON_BODY_BYTES and the
+    // client sends exactly JSON.stringify(body), so measuring it here is the same
+    // test — a wide batch (large text cells) splits before it costs an upload and a
+    // 413. Same halving and request_id suffixes as the reactive path below, so a
+    // re-run replays the identical batch ids either way.
+    const bodyBytes = Buffer.byteLength(JSON.stringify(body));
+    if (bodyBytes > MAX_CLI_JSON_BODY_BYTES && input.rows.length > 1) {
+        const midpoint = Math.ceil(input.rows.length / 2);
+        process.stderr.write(`note: import batch of ${input.rows.length} rows serializes to ${bodyBytes} bytes, `
+            + `over the ${MAX_CLI_JSON_BODY_BYTES} byte request limit; `
+            + `sending as ${midpoint} and ${input.rows.length - midpoint} row batches.\n`);
+        const [first, second] = await writeImportBatchHalves(input, midpoint);
+        return combineImportBatchWriteSummaries(first, second, { byteSplits: 1 });
+    }
+    try {
+        const result = await requestOxygen(input.upsertKey ? "/api/cli/tables/rows/upsert" : "/api/cli/tables/rows", {
+            method: "POST",
+            timeoutMs: 300_000,
+            body,
+        });
+        return summarizeImportBatchWrite(result, input.rows.length);
+    }
+    catch (error) {
+        if (!isRequestTooLargeError(error) || input.rows.length <= 1)
+            throw error;
+        // Fallback for a server whose ceiling is tighter than the shared constant.
+        const midpoint = Math.ceil(input.rows.length / 2);
+        process.stderr.write(`note: import batch of ${input.rows.length} rows exceeded the request limit; `
+            + `retrying as ${midpoint} and ${input.rows.length - midpoint} row batches.\n`);
+        const [first, second] = await writeImportBatchHalves(input, midpoint);
+        return combineImportBatchWriteSummaries(first, second, { requestTooLargeRetries: 1 });
+    }
+}
+export async function writeImportBatchHalves(input, midpoint) {
+    const first = await writeImportBatchWithAutoSplit({
+        ...input,
+        rows: input.rows.slice(0, midpoint),
+        ...(input.requestId ? { requestId: `${input.requestId}:0` } : {}),
+    });
+    const second = await writeImportBatchWithAutoSplit({
+        ...input,
+        rows: input.rows.slice(midpoint),
+        ...(input.requestId ? { requestId: `${input.requestId}:1` } : {}),
+    });
+    return [first, second];
+}
+export function summarizeImportBatchWrite(result, batchSize) {
+    const warningCount = readCount(result.warningCount);
+    const batchWarnings = Array.isArray(result.warnings) ? result.warnings : [];
+    return {
+        rowCount: readCount(result.rowCount),
+        insertedCount: readCount(result.insertedCount),
+        updatedCount: readCount(result.updatedCount),
+        warningCount,
+        warnings: batchWarnings.slice(0, 20),
+        warningsTruncated: result.warningsTruncated === true || warningCount > batchWarnings.length,
+        writeRequestCount: 1,
+        requestTooLargeRetries: 0,
+        byteSplits: 0,
+        minimumBatchSizeUsed: batchSize,
+        lastResult: result,
+    };
+}
+export function combineImportBatchWriteSummaries(first, second, extra) {
+    const warnings = [...first.warnings, ...second.warnings].slice(0, 20);
+    const warningCount = first.warningCount + second.warningCount;
+    return {
+        rowCount: first.rowCount + second.rowCount,
+        insertedCount: first.insertedCount + second.insertedCount,
+        updatedCount: first.updatedCount + second.updatedCount,
+        warningCount,
+        warnings,
+        warningsTruncated: first.warningsTruncated || second.warningsTruncated || warningCount > warnings.length,
+        writeRequestCount: first.writeRequestCount + second.writeRequestCount,
+        requestTooLargeRetries: first.requestTooLargeRetries + second.requestTooLargeRetries + (extra.requestTooLargeRetries ?? 0),
+        byteSplits: first.byteSplits + second.byteSplits + (extra.byteSplits ?? 0),
+        minimumBatchSizeUsed: Math.min(first.minimumBatchSizeUsed, second.minimumBatchSizeUsed),
+        lastResult: second.lastResult ?? first.lastResult,
+    };
+}
+export function isRequestTooLargeError(error) {
+    return error instanceof OxygenError && error.code === "request_too_large";
+}

package/dist/command-families/tables/import-columns.d.ts

@@ -0,0 +1,24 @@
+import { QueryColumnDescriptor } from "../../command-support.js";
+import { TablesImportOptions } from "./options.js";
+export type ImportTarget = {
+    tableRef: string;
+    rows: Record<string, unknown>[];
+    createdTable: unknown | null;
+    tableWebUrl: string | null;
+    upsertKey: string | undefined;
+    sourceKeyMap: Record<string, string> | null;
+};
+export declare function prepareImportTarget(table: string | undefined, options: TablesImportOptions, parsedRows: Record<string, unknown>[]): Promise<ImportTarget>;
+export declare function resolveExistingTableImportKeyMapping(table: string, rows: Record<string, unknown>[], upsertKey: string | undefined): Promise<{
+    sourceKeyMap: Record<string, string> | null;
+    upsertKey: string | undefined;
+}>;
+export type ExistingTableColumnResolver = {
+    exact: Map<string, string>;
+    aliases: Map<string, string | null>;
+};
+export declare function buildExistingTableColumnResolver(columns: QueryColumnDescriptor[]): ExistingTableColumnResolver;
+export declare function addImportColumnAlias(aliases: Map<string, string | null>, alias: string | undefined | null, key: string): void;
+export declare function resolveImportSourceKey(sourceKey: string, resolver: ExistingTableColumnResolver): string | null;
+export declare function readImportColumnAlias(aliases: Map<string, string | null>, alias: string): string | null;
+export declare function remapImportRows(rows: Record<string, unknown>[], sourceKeyMap: Record<string, string> | null): Record<string, unknown>[];

package/dist/command-families/tables/import-columns.js

@@ -0,0 +1,131 @@
+import { readRecordString } from "../../cli-values.js";
+import { readRecord } from "../../command-support.js";
+import { requestOxygen } from "../../http-client.js";
+import { readOption } from "../../util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { normalizeRowsForNewTable, inferImportColumnLabels, normalizeImportColumnKey } from "@oxygen/shared/file-import";
+import { tableWebUrl } from "./import-values.js";
+import { normalizeCreatedTableUpsertKey } from "./bundle-format.js";
+export async function prepareImportTarget(table, options, parsedRows) {
+    if (options.create && table) {
+        throw new OxygenError("invalid_import_target", "Pass either a table argument or --create, not both.", {
+            exitCode: 1,
+        });
+    }
+    if (!options.create && !table) {
+        throw new OxygenError("invalid_import_target", "Pass a table argument or --create <name>.", {
+            exitCode: 1,
+        });
+    }
+    if (!options.create) {
+        const keyMapping = await resolveExistingTableImportKeyMapping(table, parsedRows, readOption(options.upsertKey) ?? undefined);
+        return {
+            tableRef: table,
+            rows: remapImportRows(parsedRows, keyMapping.sourceKeyMap),
+            createdTable: null,
+            tableWebUrl: null,
+            upsertKey: keyMapping.upsertKey,
+            sourceKeyMap: keyMapping.sourceKeyMap,
+        };
+    }
+    const normalized = normalizeRowsForNewTable(parsedRows);
+    const created = await requestOxygen("/api/cli/tables", {
+        method: "POST",
+        body: {
+            name: options.create,
+            columns: normalized.columns,
+            ...(readOption(options.project) ? { project: readOption(options.project) } : {}),
+        },
+    });
+    const tableRecord = readRecord(created, "table");
+    const createdSlug = readRecordString(tableRecord, "slug") ?? readRecordString(tableRecord, "id");
+    if (!createdSlug) {
+        throw new OxygenError("invalid_response", "Oxygen API response is missing the created table slug.", {
+            exitCode: 1,
+        });
+    }
+    const createdWebUrl = readRecordString(created, "web_url")
+        ?? readRecordString(created, "deepLink");
+    return {
+        tableRef: createdSlug,
+        rows: normalized.rows,
+        createdTable: created,
+        tableWebUrl: createdWebUrl ?? tableWebUrl(createdSlug),
+        upsertKey: normalizeCreatedTableUpsertKey(options.upsertKey, normalized.keyBySource),
+        sourceKeyMap: normalized.keyBySource,
+    };
+}
+export async function resolveExistingTableImportKeyMapping(table, rows, upsertKey) {
+    const describe = await requestOxygen("/api/cli/tables/describe", { method: "POST", body: { table } });
+    const resolver = buildExistingTableColumnResolver(describe.columns ?? []);
+    const resolvedByHeader = new Map();
+    const targetCounts = new Map();
+    for (const sourceKey of inferImportColumnLabels(rows)) {
+        const resolved = resolveImportSourceKey(sourceKey, resolver);
+        if (!resolved)
+            continue;
+        resolvedByHeader.set(sourceKey, resolved);
+        targetCounts.set(resolved, (targetCounts.get(resolved) ?? 0) + 1);
+    }
+    const sourceKeyMap = {};
+    for (const [sourceKey, resolved] of resolvedByHeader) {
+        if ((targetCounts.get(resolved) ?? 0) > 1)
+            continue;
+        if (resolved !== sourceKey)
+            sourceKeyMap[sourceKey] = resolved;
+    }
+    return {
+        sourceKeyMap: Object.keys(sourceKeyMap).length > 0 ? sourceKeyMap : null,
+        upsertKey: upsertKey
+            ? resolveImportSourceKey(upsertKey, resolver) ?? upsertKey
+            : undefined,
+    };
+}
+export function buildExistingTableColumnResolver(columns) {
+    const exact = new Map();
+    const aliases = new Map();
+    for (const column of columns) {
+        if (!column.key)
+            continue;
+        exact.set(column.key, column.key);
+        addImportColumnAlias(aliases, column.label, column.key);
+        addImportColumnAlias(aliases, normalizeImportColumnKey(column.key), column.key);
+        if (column.label)
+            addImportColumnAlias(aliases, normalizeImportColumnKey(column.label), column.key);
+    }
+    return { exact, aliases };
+}
+export function addImportColumnAlias(aliases, alias, key) {
+    const normalizedAlias = alias?.trim();
+    if (!normalizedAlias)
+        return;
+    const existing = aliases.get(normalizedAlias);
+    if (existing === undefined) {
+        aliases.set(normalizedAlias, key);
+        return;
+    }
+    if (existing !== key)
+        aliases.set(normalizedAlias, null);
+}
+export function resolveImportSourceKey(sourceKey, resolver) {
+    const trimmed = sourceKey.trim();
+    return resolver.exact.get(sourceKey)
+        ?? resolver.exact.get(trimmed)
+        ?? readImportColumnAlias(resolver.aliases, sourceKey)
+        ?? readImportColumnAlias(resolver.aliases, trimmed)
+        ?? readImportColumnAlias(resolver.aliases, normalizeImportColumnKey(sourceKey));
+}
+export function readImportColumnAlias(aliases, alias) {
+    return aliases.get(alias) ?? null;
+}
+export function remapImportRows(rows, sourceKeyMap) {
+    if (!sourceKeyMap)
+        return rows;
+    return rows.map((row) => {
+        const remapped = {};
+        for (const [key, value] of Object.entries(row)) {
+            remapped[sourceKeyMap[key] ?? key] = value;
+        }
+        return remapped;
+    });
+}

package/dist/command-families/tables/import-upload.d.ts

@@ -0,0 +1,30 @@
+import type { RowsFileFormat } from "@oxygen/shared/file-import";
+import { TablesFileImportOptions } from "./options.js";
+import { ImportTarget } from "./import-columns.js";
+/**
+ * The file a staged import uploads. `read` supplies the rows its target is
+ * prepared from, the exact row count and the digest; it runs AFTER the presign,
+ * so a file over the plan's limit is refused before a large file is scanned.
+ */
+export type StagedImportFile = {
+    byteLength: number;
+    read: () => Promise<{
+        targetRows: Record<string, unknown>[];
+        rowCount: number;
+        sha256: string;
+    }>;
+    put: (uploadUrl: string, contentType: string) => Promise<Response>;
+};
+export declare function tryEnqueueStagedFileImport(// skipcq: JS-R1005
+table: string | undefined, options: TablesFileImportOptions, format: RowsFileFormat, file: StagedImportFile, context: {
+    autoBackground: boolean;
+    batchSize: number;
+}, preparedTarget?: ImportTarget | null): Promise<Record<string, unknown> | null>;
+export declare function formatMebibytes(bytes: number): string;
+export declare function putImportFile(uploadUrl: string, fileBuffer: Buffer, contentType: string): Promise<Response>;
+export declare function importFileContentType(format: RowsFileFormat): string;
+export declare function enqueueImportFile(table: string | undefined, options: TablesFileImportOptions, format: RowsFileFormat, batchSize: number, context: {
+    autoBackground: boolean;
+    sourceHash: string;
+}, preparedTarget?: ImportTarget | null): Promise<Record<string, unknown>>;
+export declare function emitQueueWaitStderrNote(queueWait: Record<string, unknown> | null): void;

package/dist/command-families/tables/import-upload.js

@@ -0,0 +1,203 @@
+import { readRecordString, readPositiveInt } from "../../cli-values.js";
+import { readRecord } from "../../command-support.js";
+import { requestOxygen } from "../../http-client.js";
+import { readOption } from "../../util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { prepareImportTarget } from "./import-columns.js";
+export async function tryEnqueueStagedFileImport(// skipcq: JS-R1005
+table, options, format, file, context, preparedTarget = null) {
+    if (options.create && table) {
+        throw new OxygenError("invalid_import_target", "Pass either a table argument or --create, not both.", {
+            exitCode: 1,
+        });
+    }
+    if (!options.create && !table) {
+        throw new OxygenError("invalid_import_target", "Pass a table argument or --create <name>.", {
+            exitCode: 1,
+        });
+    }
+    const filename = basename(options.file);
+    const contentType = importFileContentType(format);
+    const traceId = randomUUID();
+    // Probe for a presigned upload URL. If object storage isn't configured the
+    // server returns object_storage_not_configured; signal the caller to fall
+    // back to the inline multipart import by returning null.
+    const requestPresign = async () => {
+        try {
+            return await requestOxygen("/api/cli/tables/import-url", {
+                method: "POST",
+                body: {
+                    file_name: filename,
+                    content_type: contentType,
+                    byte_length: file.byteLength,
+                    format,
+                    trace_id: traceId,
+                },
+            });
+        }
+        catch (error) {
+            if (error instanceof OxygenError && error.code === "object_storage_not_configured") {
+                return null;
+            }
+            throw error;
+        }
+    };
+    let presigned = await requestPresign();
+    if (!presigned)
+        return null;
+    const contents = await file.read();
+    // Create the table for --create (or resolve the existing ref) before the
+    // upload so a presign success always pairs with a real target.
+    const target = preparedTarget ?? await prepareImportTarget(table, options, contents.targetRows);
+    const put = (current) => {
+        const uploadUrl = readRecordString(current, "upload_url");
+        return uploadUrl ? file.put(uploadUrl, contentType) : Promise.resolve(new Response(null, { status: 500 }));
+    };
+    let putResponse = await put(presigned);
+    // A direct-upload 403 most commonly means a stale/mismatched signature.
+    // Refresh once under the same client trace so a transient presign never
+    // strands a durable import, while persistent policy failures stay explicit.
+    if (putResponse.status === 403) {
+        const refreshed = await requestPresign();
+        if (refreshed) {
+            presigned = refreshed;
+            putResponse = await put(presigned);
+        }
+    }
+    if (!putResponse.ok) {
+        throw new OxygenError("import_upload_failed", `Uploading the import file to object storage failed (HTTP ${putResponse.status}).`, { details: { status: putResponse.status, trace_id: traceId }, exitCode: 1 });
+    }
+    const storageKey = readRecordString(presigned, "storage_key");
+    const storageBucket = readRecordString(presigned, "storage_bucket");
+    const storageProvider = readRecordString(presigned, "storage_provider") ?? "s3";
+    if (!storageKey)
+        return null;
+    const result = await requestOxygen("/api/cli/tables/import-staged", {
+        method: "POST",
+        timeoutMs: 120_000,
+        body: {
+            table: target.tableRef,
+            storage_provider: storageProvider,
+            storage_bucket: storageBucket,
+            storage_key: storageKey,
+            format,
+            file_name: filename,
+            byte_length: file.byteLength,
+            sha256: contents.sha256,
+            row_count: contents.rowCount,
+            batch_size: context.batchSize,
+            ...(readPositiveInt(options.maxConcurrency)
+                ? { max_concurrency: readPositiveInt(options.maxConcurrency) }
+                : {}),
+            ...(target.upsertKey ? { upsert_key: target.upsertKey } : {}),
+            ...(target.sourceKeyMap ? { source_key_map: target.sourceKeyMap } : {}),
+            ...(options.skipBlankCells ? { skip_blank_cells: true } : {}),
+        },
+    });
+    emitQueueWaitStderrNote(readRecord(result, "queue_wait"));
+    return {
+        ...result,
+        ...(target.createdTable ? { createdTable: target.createdTable } : {}),
+        ...(target.tableWebUrl ? { table_web_url: target.tableWebUrl } : {}),
+        background: true,
+        autoBackground: context.autoBackground,
+        import_engine: "chunked_file_v2",
+        storage_provider: storageProvider,
+    };
+}
+export function formatMebibytes(bytes) {
+    return `${Math.round(bytes / (1024 * 1024)).toLocaleString("en-US")} MiB`;
+}
+export async function putImportFile(uploadUrl, fileBuffer, contentType) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 300_000);
+    try {
+        return await fetch(uploadUrl, {
+            method: "PUT",
+            headers: {
+                "content-type": contentType,
+                "content-length": String(fileBuffer.byteLength),
+            },
+            body: new Uint8Array(fileBuffer),
+            signal: controller.signal,
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export function importFileContentType(format) {
+    if (format === "csv")
+        return "text/csv";
+    if (format === "xlsx")
+        return "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+    if (format === "jsonl")
+        return "application/x-ndjson";
+    return "application/json";
+}
+export async function enqueueImportFile(table, options, format, batchSize, context, preparedTarget = null) {
+    if (options.create && table) {
+        throw new OxygenError("invalid_import_target", "Pass either a table argument or --create, not both.", {
+            exitCode: 1,
+        });
+    }
+    if (!options.create && !table) {
+        throw new OxygenError("invalid_import_target", "Pass a table argument or --create <name>.", {
+            exitCode: 1,
+        });
+    }
+    if (options.skipBlankCells) {
+        // The multipart import cannot leave blank cells out; failing beats clearing them.
+        throw new OxygenError("skip_blank_cells_unavailable", "--skip-blank-cells needs the staged file upload, which this OXYGEN server has not configured. Add --sync to write the rows from this machine instead.", { exitCode: 1 });
+    }
+    const fileBuffer = readFileSync(options.file);
+    const filename = basename(options.file);
+    const form = new FormData();
+    const file = new File([fileBuffer], filename);
+    form.append("file", file, filename);
+    form.append("filename", filename);
+    form.append("format", format);
+    form.append("batch_size", String(batchSize));
+    form.append("auto_background", String(context.autoBackground));
+    form.append("source_hash", context.sourceHash);
+    const targetTable = preparedTarget?.tableRef ?? table;
+    if (targetTable)
+        form.append("table", targetTable);
+    if (!preparedTarget && options.create)
+        form.append("table_name", options.create);
+    const project = readOption(options.project);
+    if (project)
+        form.append("project", project);
+    const upsertKey = preparedTarget?.upsertKey ?? readOption(options.upsertKey);
+    if (upsertKey)
+        form.append("upsert_key", upsertKey);
+    if (preparedTarget?.sourceKeyMap) {
+        form.append("source_key_map", JSON.stringify(preparedTarget.sourceKeyMap));
+    }
+    if (options.sheet)
+        form.append("sheet", options.sheet);
+    const maxConcurrency = readPositiveInt(options.maxConcurrency);
+    if (maxConcurrency)
+        form.append("max_concurrency", String(maxConcurrency));
+    const result = await requestOxygen("/api/cli/tables/import-file", {
+        method: "POST",
+        timeoutMs: 300_000,
+        formData: form,
+    });
+    emitQueueWaitStderrNote(readRecord(result, "queue_wait"));
+    return {
+        ...result,
+        background: true,
+        autoBackground: context.autoBackground,
+    };
+}
+export function emitQueueWaitStderrNote(queueWait) {
+    if (!queueWait)
+        return;
+    const note = readRecordString(queueWait, "note");
+    if (note)
+        process.stderr.write(`note: ${note}\n`);
+}

package/dist/command-families/tables/import-values.d.ts

@@ -0,0 +1,10 @@
+export declare const LARGE_IMPORT_BACKGROUND_ROW_THRESHOLD = 500;
+export declare const SAFE_IMPORT_WRITE_BATCH_SIZE = 500;
+export declare const IMPORT_FILE_LIMIT_HELP: string;
+export declare function tableWebUrl(tableIdOrSlug: string): string;
+export declare function formatImportFileSizeLimit(tier: "free" | "starter" | "pro" | "scale"): string;
+export declare function formatImportByteSize(bytes: number): string;
+export declare function formatJsonBodyLimit(): string;
+export declare function withImportWaitNextStep(envelope: Record<string, unknown>): Record<string, unknown>;
+export declare function normalizeImportBatchSize(value: string | undefined): number;
+export declare function hashImportFile(path: string): string;

package/dist/command-families/tables/import-values.js

@@ -0,0 +1,60 @@
+import { readRecordString, readPositiveInt } from "../../cli-values.js";
+import { readRecord } from "../../command-support.js";
+import { defaultApiUrl } from "../../credentials.js";
+import { oxygenAppUrl } from "../../help.js";
+import { STREAMED_FILE_IMPORT_MIN_BYTES } from "../../streamed-file-import.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { MAX_BUFFERED_IMPORT_PARSE_BYTES } from "@oxygen/shared/file-import";
+import { PLAN_LIMITS, MAX_CLI_JSON_BODY_BYTES } from "@oxygen/shared/plan-limits";
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+export const LARGE_IMPORT_BACKGROUND_ROW_THRESHOLD = 500;
+export const SAFE_IMPORT_WRITE_BATCH_SIZE = 500;
+export const IMPORT_FILE_LIMIT_HELP = `Per-file row limit: your plan's rows-per-Table limit, since one file can fill an empty Table (\`oxygen limits show\` lists it for every plan size). File-size limit: ${formatImportFileSizeLimit("free")} on free, ${formatImportFileSizeLimit("starter")} on $49-$99, ${formatImportFileSizeLimit("pro")} on $199-$499, ${formatImportFileSizeLimit("scale")} on $999 and up. JSON and XLSX are read whole, so they stop at ${formatImportByteSize(MAX_BUFFERED_IMPORT_PARSE_BYTES)}; save a larger file as CSV or JSONL. Files over ${formatImportByteSize(STREAMED_FILE_IMPORT_MIN_BYTES)} upload straight from disk and always load in the background.`;
+// Deep-links must name the host the command actually talked to. This hardcoded
+// https://oxygen-agent.com, so every `oxygen-dev` bundle export/import handed
+// back a PRODUCTION url for a table that only exists on dev (OXY-4360).
+// `defaultApiUrl()` is the same resolver the request layer uses, so the link and
+// the call can no longer disagree.
+export function tableWebUrl(tableIdOrSlug) {
+    return oxygenAppUrl(defaultApiUrl(), `/tables/${encodeURIComponent(tableIdOrSlug)}`);
+}
+export function formatImportFileSizeLimit(tier) {
+    return formatImportByteSize(PLAN_LIMITS[tier].import.maxFileBytes);
+}
+export function formatImportByteSize(bytes) {
+    const mebibytes = bytes / (1024 * 1024);
+    return mebibytes >= 1024 && mebibytes % 1024 === 0 ? `${mebibytes / 1024} GiB` : `${Math.round(mebibytes)} MiB`;
+}
+// Help copy reads the shared ceiling so the number can never drift from the
+// one the server enforces and the import writer splits against.
+export function formatJsonBodyLimit() {
+    return `${Math.round(MAX_CLI_JSON_BODY_BYTES / 1_000_000)} MB`;
+}
+// A backgrounded import returns as soon as the file is staged, with counts.rows
+// still 0 while the worker loads. With no follow-up command in the envelope that
+// reads as a truncated import - which is how a 500-row `--batch-size` default
+// gets mistaken for a 500-row cap. `table-ingestions wait` takes the ingestion
+// run's own id (`ingestionRunId`), not the linked `runId`, which 404s.
+export function withImportWaitNextStep(envelope) {
+    const ingestionRunId = readRecordString(envelope, "ingestionRunId")
+        ?? readRecordString(readRecord(envelope, "ingestionRun"), "id");
+    if (!ingestionRunId)
+        return envelope;
+    const nextStep = `oxygen table-ingestions wait ${ingestionRunId}`;
+    process.stderr.write(`note: rows load in the background - watch with ${nextStep}\n`);
+    return { ...envelope, next_step: nextStep };
+}
+export function normalizeImportBatchSize(value) {
+    const batchSize = readPositiveInt(value) ?? 500;
+    if (batchSize > 5000) {
+        throw new OxygenError("invalid_number", "Import batch size cannot exceed 5000.", {
+            details: { value },
+            exitCode: 1,
+        });
+    }
+    return batchSize;
+}
+export function hashImportFile(path) {
+    return createHash("sha256").update(readFileSync(path)).digest("hex");
+}

package/dist/command-families/tables/imports.d.ts

@@ -0,0 +1,19 @@
+import type { RowsFileFormat } from "@oxygen/shared/file-import";
+import { TablesFileImportOptions, TablesImportOptions } from "./options.js";
+/**
+ * `--url` hands the fetch to the server: the same durable import the file path
+ * enqueues, with the bytes read by OXYGEN behind SSRF, size and content guards,
+ * so the CLI never downloads anything and a 0-credit preview is one flag away.
+ */
+export declare function importRowsFromUrl(table: string | undefined, options: TablesImportOptions & {
+    url: string;
+}): Promise<Record<string, unknown>>;
+export declare function importRows(table: string | undefined, options: TablesImportOptions): Promise<Record<string, unknown>>;
+export declare function importRowsFromFile(table: string | undefined, options: TablesFileImportOptions): Promise<Record<string, unknown>>;
+/**
+ * A CSV or JSONL file over STREAMED_FILE_IMPORT_MIN_BYTES: never read whole.
+ * One streaming pass counts, hashes and collects its columns, the upload streams
+ * from disk, and the import always runs in the background. There is no inline
+ * fallback: a file this large cannot travel in one API request.
+ */
+export declare function importLargeFileStreamed(table: string | undefined, options: TablesFileImportOptions, format: RowsFileFormat, fileBytes: number): Promise<Record<string, unknown>>;