clipy-kit 0.1.0

package/dist/lib/ops.js

@@ -0,0 +1,475 @@
+import { CliError } from '../output.js';
+import { parseA1, qualifyRange, toGridRange } from '../ranges.js';
+import { formatToRepeatCell, freezeRequest } from './format.js';
+import { findHeader, objectToRow, unknownKeys, valuesToTable } from './table.js';
+export function createOps(client) {
+    return {
+        getSpreadsheet: (id, fields) => getSpreadsheet(client, id, fields),
+        findSpreadsheets: (name, limit) => findSpreadsheets(client, name, limit),
+        info: (id) => info(client, id),
+        listTabs: (id) => listTabs(client, id),
+        readTable: (id, opts) => readTable(client, id, opts),
+        readRange: (id, range) => readRange(client, id, range),
+        append: (id, opts) => appendRows(client, id, opts),
+        update: (id, opts) => updateByKey(client, id, opts),
+        upsert: (id, opts) => upsertRows(client, id, opts),
+        setRange: (id, opts) => setRange(client, id, opts),
+        clear: (id, range, dryRun) => clearRange(client, id, range, dryRun),
+        batch: (id, ops, dryRun) => batchOps(client, id, ops, dryRun),
+        create: (opts) => createSpreadsheet(client, opts),
+        tabAdd: (id, opts) => tabAdd(client, id, opts),
+        tabRename: (id, opts) => tabRename(client, id, opts),
+        tabDelete: (id, opts) => tabDelete(client, id, opts),
+        tabDuplicate: (id, opts) => tabDuplicate(client, id, opts),
+        format: (id, opts) => formatRange(client, id, opts),
+        formatHeader: (id, opts) => formatHeader(client, id, opts),
+        freeze: (id, opts) => freeze(client, id, opts),
+        numberFormat: (id, opts) => numberFormat(client, id, opts),
+        formula: (id, opts) => writeFormula(client, id, opts),
+        fillDown: (id, opts) => fillDown(client, id, opts),
+        share: (id, opts) => share(client, id, opts),
+        unshare: (id, email, dryRun) => unshare(client, id, email, dryRun),
+        permissions: (id) => listPermissions(client, id),
+        api: (method, id, json) => apiEscape(client, method, id, json),
+    };
+}
+const VALUE_INPUT = { valueInputOption: 'USER_ENTERED' };
+async function getSpreadsheet(client, id, fields) {
+    return client.sheets('GET', `/spreadsheets/${encodeURIComponent(id)}`, {
+        query: { fields: fields || 'spreadsheetId,spreadsheetUrl,properties,sheets.properties' },
+    });
+}
+async function findSpreadsheets(client, name, limit = 10) {
+    const q = `mimeType='application/vnd.google-apps.spreadsheet' and name contains '${name.replace(/'/g, "\\'")}' and trashed=false`;
+    const data = await client.drive('GET', '/files', {
+        query: {
+            q,
+            pageSize: String(limit),
+            fields: 'files(id,name,webViewLink)',
+        },
+    });
+    return {
+        query: name,
+        files: (data.files ?? []).map((f) => ({
+            id: f.id,
+            name: f.name,
+            url: f.webViewLink || `https://docs.google.com/spreadsheets/d/${f.id}/edit`,
+        })),
+    };
+}
+async function info(client, id) {
+    const ss = await getSpreadsheet(client, id);
+    return {
+        spreadsheetId: ss.spreadsheetId,
+        title: ss.properties?.title,
+        url: ss.spreadsheetUrl,
+        tabs: (ss.sheets ?? []).map((s) => ({
+            sheetId: s.properties?.sheetId,
+            title: s.properties?.title,
+            index: s.properties?.index,
+            rows: s.properties?.gridProperties?.rowCount,
+            columns: s.properties?.gridProperties?.columnCount,
+        })),
+    };
+}
+async function listTabs(client, id) {
+    const data = await info(client, id);
+    return { title: data.title, tabs: data.tabs };
+}
+function sheetByName(ss, name) {
+    const found = ss.sheets?.find((s) => s.properties?.title === name);
+    if (!found?.properties) {
+        const titles = (ss.sheets ?? []).map((s) => s.properties?.title).filter(Boolean);
+        throw new CliError('NOT_FOUND', `Tab not found: ${name}`, { tabs: titles });
+    }
+    return found.properties;
+}
+async function readValues(client, id, range) {
+    const data = await client.sheets('GET', `/spreadsheets/${encodeURIComponent(id)}/values/${encodeURIComponent(range)}`, { query: { valueRenderOption: 'UNFORMATTED_VALUE', dateTimeRenderOption: 'FORMATTED_STRING' } });
+    return data.values ?? [];
+}
+async function readTable(client, id, opts) {
+    const tab = opts.tab || (opts.range ? parseA1(opts.range).sheet : undefined);
+    if (!tab && !opts.range)
+        throw new CliError('VALIDATION_ERROR', 'Pass --tab or --range');
+    const range = opts.range ? qualifyRange(opts.range, opts.tab) : `'${(tab ?? '').replace(/'/g, "''")}'`;
+    const values = await readValues(client, id, range);
+    if (opts.raw)
+        return { range, values };
+    return { range, ...valuesToTable(values, { headerRow: opts.headerRow, limit: opts.limit }) };
+}
+async function readRange(client, id, range) {
+    const values = await readValues(client, id, range);
+    return { range, values };
+}
+async function writeValues(client, id, range, values, valueInput = 'USER_ENTERED') {
+    return client.sheets('PUT', `/spreadsheets/${encodeURIComponent(id)}/values/${encodeURIComponent(range)}`, {
+        query: { valueInputOption: valueInput },
+        body: { range, values },
+    });
+}
+async function appendValues(client, id, range, values, valueInput = 'USER_ENTERED') {
+    return client.sheets('POST', `/spreadsheets/${encodeURIComponent(id)}/values/${encodeURIComponent(range)}:append`, {
+        query: { valueInputOption: valueInput, insertDataOption: 'INSERT_ROWS' },
+        body: { range, values },
+    });
+}
+async function appendRows(client, id, opts) {
+    const range = `'${opts.tab.replace(/'/g, "''")}'`;
+    const existing = await readValues(client, id, range);
+    const table = valuesToTable(existing);
+    let headers = table.headers;
+    if (!headers.length) {
+        headers = Object.keys(opts.rows[0] ?? {}).filter((k) => k !== '_row');
+        if (!headers.length)
+            throw new CliError('VALIDATION_ERROR', 'No columns to append');
+        const toWrite = [headers, ...opts.rows.map((row) => objectToRow(row, headers))];
+        if (opts.dryRun)
+            return { dryRun: true, tab: opts.tab, headers, rows: opts.rows.length, bootstrap: true };
+        const written = await writeValues(client, id, `${range}!A1`, toWrite, opts.valueInput);
+        return { tab: opts.tab, headers, rows: opts.rows.length, bootstrap: true, result: written };
+    }
+    const dataRows = opts.rows.map((row) => objectToRow(row, headers));
+    if (opts.dryRun)
+        return { dryRun: true, tab: opts.tab, headers, rows: dataRows.length };
+    const appended = await appendValues(client, id, range, dataRows, opts.valueInput);
+    return { tab: opts.tab, headers, rows: dataRows.length, result: appended };
+}
+async function updateByKey(client, id, opts) {
+    const range = `'${opts.tab.replace(/'/g, "''")}'`;
+    const values = await readValues(client, id, range);
+    const table = valuesToTable(values);
+    const keyHeader = findHeader(table.headers, opts.keyCol);
+    if (!keyHeader)
+        throw new CliError('NOT_FOUND', `Key column not found: ${opts.keyCol}`, { headers: table.headers });
+    const matches = table.rows.filter((r) => String(r[keyHeader] ?? '') === opts.key);
+    if (!matches.length)
+        throw new CliError('NOT_FOUND', `No row with ${keyHeader}=${opts.key}`);
+    if (matches.length > 1 && !opts.allowMulti) {
+        throw new CliError('VALIDATION_ERROR', `Multiple rows match ${keyHeader}=${opts.key}. Pass --allow-multi.`);
+    }
+    const unknown = unknownKeys(opts.set, table.headers);
+    if (unknown.length)
+        throw new CliError('VALIDATION_ERROR', `Unknown columns: ${unknown.join(', ')}`, { headers: table.headers });
+    if (opts.dryRun) {
+        return { dryRun: true, matchedRows: matches.map((r) => r._row), set: opts.set };
+    }
+    const data = matches.map((row) => {
+        const merged = { ...row, ...opts.set };
+        return {
+            range: `'${opts.tab.replace(/'/g, "''")}'!A${row._row}`,
+            values: [objectToRow(merged, table.headers)],
+        };
+    });
+    const result = await client.sheets('POST', `/spreadsheets/${encodeURIComponent(id)}/values:batchUpdate`, {
+        body: { valueInputOption: opts.valueInput || 'USER_ENTERED', data },
+    });
+    return { matchedRows: matches.map((r) => r._row), updated: matches.length, result };
+}
+async function updateRow(client, id, tab, row, set, dryRun, valueInput) {
+    const range = `'${tab.replace(/'/g, "''")}'`;
+    const values = await readValues(client, id, range);
+    const table = valuesToTable(values);
+    const unknown = unknownKeys(set, table.headers);
+    if (unknown.length)
+        throw new CliError('VALIDATION_ERROR', `Unknown columns: ${unknown.join(', ')}`, { headers: table.headers });
+    const existing = table.rows.find((r) => r._row === row) ?? {};
+    const merged = { ...existing, ...set };
+    if (dryRun)
+        return { dryRun: true, row, set };
+    const a1 = `${range}!A${row}`;
+    const result = await writeValues(client, id, a1, [objectToRow(merged, table.headers)], valueInput);
+    return { row, result };
+}
+async function upsertRows(client, id, opts) {
+    const updated = [];
+    const inserted = [];
+    for (const row of opts.rows) {
+        const keyVal = row[opts.keyCol] ?? row[Object.keys(row).find((k) => k.toLowerCase() === opts.keyCol.toLowerCase()) ?? ''];
+        if (keyVal === undefined || keyVal === '') {
+            throw new CliError('VALIDATION_ERROR', `Upsert row missing key column ${opts.keyCol}`);
+        }
+        try {
+            const result = await updateByKey(client, id, {
+                tab: opts.tab,
+                keyCol: opts.keyCol,
+                key: String(keyVal),
+                set: row,
+                dryRun: opts.dryRun,
+                valueInput: opts.valueInput,
+            });
+            updated.push({ key: keyVal, result });
+        }
+        catch (err) {
+            if (err instanceof CliError && err.code === 'NOT_FOUND')
+                inserted.push(row);
+            else
+                throw err;
+        }
+    }
+    let appendResult;
+    if (inserted.length) {
+        appendResult = await appendRows(client, id, { tab: opts.tab, rows: inserted, dryRun: opts.dryRun, valueInput: opts.valueInput });
+    }
+    return { updated: updated.length, inserted: inserted.length, updatedRows: updated, appendResult };
+}
+async function setRange(client, id, opts) {
+    if (opts.dryRun)
+        return { dryRun: true, range: opts.range, values: opts.values };
+    const result = await writeValues(client, id, opts.range, opts.values, opts.valueInput);
+    return { range: opts.range, result };
+}
+async function clearRange(client, id, range, dryRun) {
+    if (dryRun)
+        return { dryRun: true, range };
+    const result = await client.sheets('POST', `/spreadsheets/${encodeURIComponent(id)}/values/${encodeURIComponent(range)}:clear`, {
+        body: {},
+    });
+    return { range, result };
+}
+async function batchOps(client, id, ops, dryRun) {
+    const results = [];
+    for (const op of ops) {
+        if (op.op === 'append') {
+            const rows = Array.isArray(op.values) ? op.values : [op.values];
+            results.push({ op: op.op, result: await appendRows(client, id, { tab: op.sheet, rows, dryRun }) });
+        }
+        else if (op.op === 'updateKey') {
+            results.push({
+                op: op.op,
+                result: await updateByKey(client, id, {
+                    tab: op.sheet,
+                    keyCol: op.keyCol,
+                    key: op.key,
+                    set: op.set,
+                    allowMulti: op.allowMulti,
+                    dryRun,
+                }),
+            });
+        }
+        else if (op.op === 'updateRow') {
+            results.push({ op: op.op, result: await updateRow(client, id, op.sheet, op.row, op.set, dryRun) });
+        }
+        else if (op.op === 'setRange') {
+            results.push({ op: op.op, result: await setRange(client, id, { range: op.range, values: op.values, dryRun }) });
+        }
+        else if (op.op === 'clear') {
+            results.push({ op: op.op, result: await clearRange(client, id, op.range, dryRun) });
+        }
+        else {
+            throw new CliError('VALIDATION_ERROR', `Unknown batch op: ${op.op}`);
+        }
+    }
+    return { count: results.length, results };
+}
+async function createSpreadsheet(client, opts) {
+    const tabs = opts.tabs?.length ? opts.tabs : ['Sheet1'];
+    const body = {
+        properties: { title: opts.title },
+        sheets: tabs.map((title, index) => ({ properties: { title, index } })),
+    };
+    if (opts.dryRun)
+        return { dryRun: true, ...body };
+    const created = await client.sheets('POST', '/spreadsheets', { body });
+    return {
+        spreadsheetId: created.spreadsheetId,
+        url: created.spreadsheetUrl || `https://docs.google.com/spreadsheets/d/${created.spreadsheetId}/edit`,
+        title: created.properties?.title,
+        tabs,
+    };
+}
+async function batchUpdate(client, id, requests, dryRun) {
+    if (dryRun)
+        return { dryRun: true, requests };
+    return client.sheets('POST', `/spreadsheets/${encodeURIComponent(id)}:batchUpdate`, { body: { requests } });
+}
+async function tabAdd(client, id, opts) {
+    const requests = [{ addSheet: { properties: { title: opts.title, index: opts.index } } }];
+    const result = await batchUpdate(client, id, requests, opts.dryRun);
+    return { title: opts.title, result };
+}
+async function tabRename(client, id, opts) {
+    const ss = await getSpreadsheet(client, id);
+    const sheet = sheetByName(ss, opts.tab);
+    const requests = [{ updateSheetProperties: { properties: { sheetId: sheet.sheetId, title: opts.title }, fields: 'title' } }];
+    const result = await batchUpdate(client, id, requests, opts.dryRun);
+    return { from: opts.tab, title: opts.title, result };
+}
+async function tabDelete(client, id, opts) {
+    const ss = await getSpreadsheet(client, id);
+    const sheet = sheetByName(ss, opts.tab);
+    const result = await batchUpdate(client, id, [{ deleteSheet: { sheetId: sheet.sheetId } }], opts.dryRun);
+    return { tab: opts.tab, sheetId: sheet.sheetId, result };
+}
+async function tabDuplicate(client, id, opts) {
+    const ss = await getSpreadsheet(client, id);
+    const sheet = sheetByName(ss, opts.tab);
+    const result = await batchUpdate(client, id, [{ duplicateSheet: { sourceSheetId: sheet.sheetId, newSheetName: opts.title } }], opts.dryRun);
+    return { tab: opts.tab, title: opts.title, result };
+}
+async function formatRange(client, id, opts) {
+    const range = qualifyRange(opts.range, opts.tab);
+    const parsed = parseA1(range);
+    const ss = await getSpreadsheet(client, id);
+    const tabName = parsed.sheet || opts.tab;
+    if (!tabName)
+        throw new CliError('VALIDATION_ERROR', 'Range must include a sheet name or pass --tab');
+    const sheet = sheetByName(ss, tabName);
+    const request = formatToRepeatCell(toGridRange(parsed, sheet.sheetId), opts);
+    if (opts.dryRun)
+        return { dryRun: true, range, requests: [request] };
+    const result = await batchUpdate(client, id, [request], false);
+    return { range, result };
+}
+async function formatHeader(client, id, opts) {
+    const ss = await getSpreadsheet(client, id);
+    const sheet = sheetByName(ss, opts.tab);
+    const flags = {
+        bold: opts.bold ?? true,
+        bg: opts.bg ?? '#1a365d',
+        fg: opts.fg ?? 'white',
+        align: opts.align ?? 'center',
+        italic: opts.italic,
+    };
+    const requests = [
+        formatToRepeatCell({ sheetId: sheet.sheetId, startRowIndex: 0, endRowIndex: 1 }, flags),
+    ];
+    if (opts.freeze !== false)
+        requests.push(freezeRequest(sheet.sheetId, 1));
+    const result = await batchUpdate(client, id, requests, opts.dryRun);
+    return { tab: opts.tab, freeze: opts.freeze !== false, result };
+}
+async function freeze(client, id, opts) {
+    const ss = await getSpreadsheet(client, id);
+    const sheet = sheetByName(ss, opts.tab);
+    const result = await batchUpdate(client, id, [freezeRequest(sheet.sheetId, opts.rows ?? 1, opts.columns)], opts.dryRun);
+    return { tab: opts.tab, rows: opts.rows ?? 1, columns: opts.columns, result };
+}
+async function numberFormat(client, id, opts) {
+    return formatRange(client, id, { range: opts.range, tab: opts.tab, pattern: opts.pattern, dryRun: opts.dryRun });
+}
+async function writeFormula(client, id, opts) {
+    const expr = opts.expr.startsWith('=') ? opts.expr : `=${opts.expr}`;
+    if (opts.dryRun)
+        return { dryRun: true, cell: opts.cell, expr };
+    const result = await writeValues(client, id, opts.cell, [[expr]]);
+    return { cell: opts.cell, expr, result };
+}
+async function fillDown(client, id, opts) {
+    const expr = opts.expr.startsWith('=') ? opts.expr : `=${opts.expr}`;
+    const parsed = parseA1(opts.range);
+    const startRow = parsed.startRow;
+    const endRow = parsed.endRow ?? startRow + 1;
+    const col = parsed.startCol;
+    const sheet = parsed.sheet;
+    if (!sheet)
+        throw new CliError('VALIDATION_ERROR', 'Range must include a sheet name');
+    const values = [];
+    for (let r = startRow; r < endRow; r++) {
+        values.push([expr]);
+    }
+    const a1 = qualifyRange(opts.range, sheet);
+    if (opts.dryRun)
+        return { dryRun: true, range: a1, expr, rows: values.length };
+    void col;
+    const result = await writeValues(client, id, a1, values);
+    return { range: a1, expr, rows: values.length, result };
+}
+async function share(client, id, opts) {
+    const role = opts.role === 'reader' || opts.role === 'writer' ? opts.role : null;
+    if (!role)
+        throw new CliError('VALIDATION_ERROR', 'Role must be reader or writer');
+    if (opts.dryRun)
+        return { dryRun: true, email: opts.email, role };
+    const result = await client.drive('POST', `/files/${encodeURIComponent(id)}/permissions`, {
+        query: { sendNotificationEmail: 'false' },
+        body: { type: 'user', role, emailAddress: opts.email },
+    });
+    return { email: opts.email, role, result };
+}
+async function unshare(client, id, email, dryRun) {
+    const list = await listPermissions(client, id);
+    const perm = list.permissions.find((p) => p.email?.toLowerCase() === email.toLowerCase());
+    if (!perm)
+        throw new CliError('NOT_FOUND', `No permission for ${email}`);
+    if (dryRun)
+        return { dryRun: true, email, permissionId: perm.id };
+    await client.drive('DELETE', `/files/${encodeURIComponent(id)}/permissions/${encodeURIComponent(perm.id)}`);
+    return { email, removed: perm.id };
+}
+async function listPermissions(client, id) {
+    const data = await client.drive('GET', `/files/${encodeURIComponent(id)}/permissions`, {
+        query: { fields: 'permissions(id,role,type,emailAddress,displayName)', supportsAllDrives: 'true' },
+    });
+    return {
+        permissions: (data.permissions ?? []).map((p) => ({
+            id: p.id,
+            role: p.role,
+            type: p.type,
+            email: p.emailAddress,
+            name: p.displayName,
+        })),
+    };
+}
+const API_METHODS = {
+    batchUpdate: (c, id, json) => {
+        if (!id)
+            throw new CliError('VALIDATION_ERROR', 'batchUpdate requires a spreadsheet id');
+        return c.sheets('POST', `/spreadsheets/${encodeURIComponent(id)}:batchUpdate`, { body: json });
+    },
+    'spreadsheets.get': (c, id) => {
+        if (!id)
+            throw new CliError('VALIDATION_ERROR', 'spreadsheets.get requires a spreadsheet id');
+        return getSpreadsheet(c, id);
+    },
+    'spreadsheets.create': (c, _id, json) => c.sheets('POST', '/spreadsheets', { body: json }),
+    'values.get': (c, id, json) => {
+        if (!id)
+            throw new CliError('VALIDATION_ERROR', 'values.get requires a spreadsheet id');
+        const range = json?.range;
+        if (!range)
+            throw new CliError('VALIDATION_ERROR', 'values.get JSON must include range');
+        return c.sheets('GET', `/spreadsheets/${encodeURIComponent(id)}/values/${encodeURIComponent(range)}`);
+    },
+    'values.update': (c, id, json) => {
+        if (!id)
+            throw new CliError('VALIDATION_ERROR', 'values.update requires a spreadsheet id');
+        const body = json;
+        return c.sheets('PUT', `/spreadsheets/${encodeURIComponent(id)}/values/${encodeURIComponent(body.range)}`, {
+            query: { valueInputOption: body.valueInputOption || 'USER_ENTERED' },
+            body,
+        });
+    },
+    'values.append': (c, id, json) => {
+        if (!id)
+            throw new CliError('VALIDATION_ERROR', 'values.append requires a spreadsheet id');
+        const body = json;
+        return c.sheets('POST', `/spreadsheets/${encodeURIComponent(id)}/values/${encodeURIComponent(body.range)}:append`, {
+            query: { ...VALUE_INPUT, insertDataOption: 'INSERT_ROWS' },
+            body,
+        });
+    },
+    'values.clear': (c, id, json) => {
+        if (!id)
+            throw new CliError('VALIDATION_ERROR', 'values.clear requires a spreadsheet id');
+        const range = json?.range;
+        if (!range)
+            throw new CliError('VALIDATION_ERROR', 'values.clear JSON must include range');
+        return c.sheets('POST', `/spreadsheets/${encodeURIComponent(id)}/values/${encodeURIComponent(range)}:clear`, { body: {} });
+    },
+    'drive.files.list': (c, _id, json) => c.drive('GET', '/files', { query: json ?? {} }),
+    'drive.permissions.create': (c, id, json) => {
+        if (!id)
+            throw new CliError('VALIDATION_ERROR', 'drive.permissions.create requires a spreadsheet id');
+        return c.drive('POST', `/files/${encodeURIComponent(id)}/permissions`, { body: json });
+    },
+};
+async function apiEscape(client, method, id, json) {
+    const fn = API_METHODS[method];
+    if (!fn) {
+        throw new CliError('VALIDATION_ERROR', `Unknown api method: ${method}`, { methods: Object.keys(API_METHODS) });
+    }
+    const result = await fn(client, id, json ?? {});
+    return { method, result };
+}
+export { VALUE_INPUT };

package/dist/lib/table.d.ts

@@ -0,0 +1,14 @@
+export declare function normalizeHeader(value: string): string;
+export declare function detectHeaderRow(values: unknown[][]): number;
+export type Table = {
+    headers: string[];
+    rows: Record<string, unknown>[];
+    headerRow: number;
+};
+export declare function valuesToTable(values: unknown[][], opts?: {
+    headerRow?: number;
+    limit?: number;
+}): Table;
+export declare function findHeader(headers: string[], key: string): string | undefined;
+export declare function objectToRow(obj: Record<string, unknown>, headers: string[]): unknown[];
+export declare function unknownKeys(obj: Record<string, unknown>, headers: string[]): string[];

package/dist/lib/table.js

@@ -0,0 +1,67 @@
+import { colLetter } from '../ranges.js';
+export function normalizeHeader(value) {
+    return value.trim().replace(/\s+/g, ' ').toLowerCase();
+}
+export function detectHeaderRow(values) {
+    for (let i = 0; i < values.length; i++) {
+        if ((values[i] ?? []).some((c) => String(c ?? '').trim() !== ''))
+            return i;
+    }
+    return 0;
+}
+function uniqueHeaders(raw) {
+    const seen = new Map();
+    return raw.map((cell, i) => {
+        const base = String(cell ?? '').trim() || colLetter(i);
+        const n = (seen.get(normalizeHeader(base)) ?? 0) + 1;
+        seen.set(normalizeHeader(base), n);
+        return n === 1 ? base : `${base}_${n}`;
+    });
+}
+export function valuesToTable(values, opts = {}) {
+    if (!values.length) {
+        return { headers: [], rows: [], headerRow: 1 };
+    }
+    const headerIdx = opts.headerRow ? opts.headerRow - 1 : detectHeaderRow(values);
+    const headers = uniqueHeaders(values[headerIdx] ?? []);
+    const rows = [];
+    const start = headerIdx + 1;
+    const end = opts.limit != null ? Math.min(values.length, start + opts.limit) : values.length;
+    for (let i = start; i < end; i++) {
+        const line = values[i] ?? [];
+        if (!line.some((c) => String(c ?? '').trim() !== ''))
+            continue;
+        const row = { _row: i + 1 };
+        headers.forEach((h, col) => {
+            row[h] = line[col] ?? '';
+        });
+        rows.push(row);
+    }
+    return { headers, rows, headerRow: headerIdx + 1 };
+}
+export function findHeader(headers, key) {
+    const needle = normalizeHeader(key);
+    const match = headers.find((h) => normalizeHeader(h) === needle);
+    if (match)
+        return match;
+    if (/^[A-Za-z]+$/.test(key.trim())) {
+        const letter = key.trim().toUpperCase();
+        return headers.find((h) => h.toUpperCase() === letter);
+    }
+    return undefined;
+}
+export function objectToRow(obj, headers) {
+    const mapped = new Array(headers.length).fill('');
+    for (const [key, value] of Object.entries(obj)) {
+        if (key === '_row')
+            continue;
+        const header = findHeader(headers, key);
+        if (!header)
+            continue;
+        mapped[headers.indexOf(header)] = value ?? '';
+    }
+    return mapped;
+}
+export function unknownKeys(obj, headers) {
+    return Object.keys(obj).filter((k) => k !== '_row' && !findHeader(headers, k));
+}

package/dist/lib/types.d.ts

@@ -0,0 +1,26 @@
+export type SheetProperties = {
+    sheetId: number;
+    title: string;
+    index?: number;
+    gridProperties?: {
+        rowCount?: number;
+        columnCount?: number;
+        frozenRowCount?: number;
+        frozenColumnCount?: number;
+    };
+};
+export type Spreadsheet = {
+    spreadsheetId: string;
+    spreadsheetUrl?: string;
+    properties?: {
+        title?: string;
+        locale?: string;
+    };
+    sheets?: {
+        properties?: SheetProperties;
+    }[];
+};
+export type ValueRange = {
+    range?: string;
+    values?: unknown[][];
+};

package/dist/lib/types.js

@@ -0,0 +1 @@
+export {};

package/dist/output.d.ts

@@ -0,0 +1,37 @@
+export declare const EXIT: {
+    readonly OK: 0;
+    readonly VALIDATION: 10;
+    readonly AUTH: 20;
+    readonly PERMISSION: 30;
+    readonly API: 40;
+};
+export type ErrorBody = {
+    code: string;
+    message: string;
+    details?: unknown;
+};
+export type Envelope = {
+    ok: true;
+    cmd: string;
+    spreadsheetId?: string;
+    sheet?: string;
+    result: unknown;
+} | {
+    ok: false;
+    cmd: string;
+    error: ErrorBody;
+};
+export declare class CliError extends Error {
+    readonly code: string;
+    readonly details?: unknown;
+    readonly exitCode: number;
+    constructor(code: string, message: string, details?: unknown, exitCode?: number);
+}
+export declare function compact(value: unknown): unknown;
+export declare function envelopeOk(cmd: string, result: unknown, extra?: {
+    spreadsheetId?: string;
+    sheet?: string;
+}): Envelope;
+export declare function envelopeErr(cmd: string, err: unknown): Envelope;
+export declare function exitCodeFor(err: unknown): number;
+export declare function stringifyEnvelope(body: Envelope, pretty: boolean): string;