@mcp-z/mcp-sheets 1.0.0

package/dist/cjs/spreadsheet/csv-streaming.d.cts

@@ -0,0 +1,19 @@
+/** Streaming CSV parsing utilities for memory-efficient large file processing */
+import { Readable } from 'stream';
+/**
+ * Get readable stream from CSV URI
+ *
+ * Memory efficiency:
+ * - file:// URIs stream directly from disk
+ * - http:// URIs stream directly from response (no temp files!)
+ *
+ * @example
+ * ```ts
+ * const readStream = await getCsvReadStream(csvUri);
+ * const parser = readStream.pipe(parse({ columns: true }));
+ * for await (const record of parser) {
+ *   // Process record
+ * }
+ * ```
+ */
+export declare function getCsvReadStream(csvUri: string): Promise<Readable>;

package/dist/cjs/spreadsheet/csv-streaming.d.ts

@@ -0,0 +1,19 @@
+/** Streaming CSV parsing utilities for memory-efficient large file processing */
+import { Readable } from 'stream';
+/**
+ * Get readable stream from CSV URI
+ *
+ * Memory efficiency:
+ * - file:// URIs stream directly from disk
+ * - http:// URIs stream directly from response (no temp files!)
+ *
+ * @example
+ * ```ts
+ * const readStream = await getCsvReadStream(csvUri);
+ * const parser = readStream.pipe(parse({ columns: true }));
+ * for await (const record of parser) {
+ *   // Process record
+ * }
+ * ```
+ */
+export declare function getCsvReadStream(csvUri: string): Promise<Readable>;

package/dist/cjs/spreadsheet/csv-streaming.js

@@ -0,0 +1,188 @@
+/** Streaming CSV parsing utilities for memory-efficient large file processing */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "getCsvReadStream", {
+    enumerable: true,
+    get: function() {
+        return getCsvReadStream;
+    }
+});
+var _fs = require("fs");
+var _path = require("path");
+var _stream = require("stream");
+function asyncGeneratorStep(gen, resolve, reject, _next, _throw, key, arg) {
+    try {
+        var info = gen[key](arg);
+        var value = info.value;
+    } catch (error) {
+        reject(error);
+        return;
+    }
+    if (info.done) {
+        resolve(value);
+    } else {
+        Promise.resolve(value).then(_next, _throw);
+    }
+}
+function _async_to_generator(fn) {
+    return function() {
+        var self = this, args = arguments;
+        return new Promise(function(resolve, reject) {
+            var gen = fn.apply(self, args);
+            function _next(value) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "next", value);
+            }
+            function _throw(err) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "throw", err);
+            }
+            _next(undefined);
+        });
+    };
+}
+function _ts_generator(thisArg, body) {
+    var f, y, t, _ = {
+        label: 0,
+        sent: function() {
+            if (t[0] & 1) throw t[1];
+            return t[1];
+        },
+        trys: [],
+        ops: []
+    }, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype), d = Object.defineProperty;
+    return d(g, "next", {
+        value: verb(0)
+    }), d(g, "throw", {
+        value: verb(1)
+    }), d(g, "return", {
+        value: verb(2)
+    }), typeof Symbol === "function" && d(g, Symbol.iterator, {
+        value: function() {
+            return this;
+        }
+    }), g;
+    function verb(n) {
+        return function(v) {
+            return step([
+                n,
+                v
+            ]);
+        };
+    }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while(g && (g = 0, op[0] && (_ = 0)), _)try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [
+                op[0] & 2,
+                t.value
+            ];
+            switch(op[0]){
+                case 0:
+                case 1:
+                    t = op;
+                    break;
+                case 4:
+                    _.label++;
+                    return {
+                        value: op[1],
+                        done: false
+                    };
+                case 5:
+                    _.label++;
+                    y = op[1];
+                    op = [
+                        0
+                    ];
+                    continue;
+                case 7:
+                    op = _.ops.pop();
+                    _.trys.pop();
+                    continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) {
+                        _ = 0;
+                        continue;
+                    }
+                    if (op[0] === 3 && (!t || op[1] > t[0] && op[1] < t[3])) {
+                        _.label = op[1];
+                        break;
+                    }
+                    if (op[0] === 6 && _.label < t[1]) {
+                        _.label = t[1];
+                        t = op;
+                        break;
+                    }
+                    if (t && _.label < t[2]) {
+                        _.label = t[2];
+                        _.ops.push(op);
+                        break;
+                    }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop();
+                    continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) {
+            op = [
+                6,
+                e
+            ];
+            y = 0;
+        } finally{
+            f = t = 0;
+        }
+        if (op[0] & 5) throw op[1];
+        return {
+            value: op[0] ? op[1] : void 0,
+            done: true
+        };
+    }
+}
+function getCsvReadStream(csvUri) {
+    return _async_to_generator(function() {
+        var filePath, resolvedPath, response;
+        return _ts_generator(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    if (csvUri.startsWith('file://')) {
+                        // Local file - stream directly from disk
+                        filePath = csvUri.replace('file://', '');
+                        resolvedPath = (0, _path.resolve)(filePath);
+                        return [
+                            2,
+                            (0, _fs.createReadStream)(resolvedPath, {
+                                encoding: 'utf-8'
+                            })
+                        ];
+                    }
+                    if (!(csvUri.startsWith('http://') || csvUri.startsWith('https://'))) return [
+                        3,
+                        2
+                    ];
+                    return [
+                        4,
+                        fetch(csvUri)
+                    ];
+                case 1:
+                    response = _state.sent();
+                    if (!response.ok) {
+                        throw new Error("Failed to fetch CSV from ".concat(csvUri, ": ").concat(response.statusText));
+                    }
+                    if (!response.body) {
+                        throw new Error("No response body from ".concat(csvUri));
+                    }
+                    // Convert web stream to Node.js stream
+                    // response.body is ReadableStream<Uint8Array> from fetch API
+                    // Cast to Node.js ReadableStream type for compatibility with Readable.fromWeb
+                    return [
+                        2,
+                        _stream.Readable.fromWeb(response.body)
+                    ];
+                case 2:
+                    throw new Error("Invalid CSV URI: ".concat(csvUri, ". Must start with file://, http://, or https://"));
+            }
+        });
+    })();
+}
+/* CJS INTEROP */ if (exports.__esModule && exports.default) { try { Object.defineProperty(exports.default, '__esModule', { value: true }); for (var key in exports) { exports.default[key] = exports[key]; } } catch (_) {}; module.exports = exports.default; }

package/dist/cjs/spreadsheet/csv-streaming.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/servers/mcp-sheets/src/spreadsheet/csv-streaming.ts"],"sourcesContent":["/** Streaming CSV parsing utilities for memory-efficient large file processing */\n\nimport { createReadStream } from 'fs';\nimport { resolve } from 'path';\nimport { Readable } from 'stream';\nimport type { ReadableStream as NodeReadableStream } from 'stream/web';\n\n/**\n * Get readable stream from CSV URI\n *\n * Memory efficiency:\n * - file:// URIs stream directly from disk\n * - http:// URIs stream directly from response (no temp files!)\n *\n * @example\n * ```ts\n * const readStream = await getCsvReadStream(csvUri);\n * const parser = readStream.pipe(parse({ columns: true }));\n * for await (const record of parser) {\n *   // Process record\n * }\n * ```\n */\nexport async function getCsvReadStream(csvUri: string): Promise<Readable> {\n  if (csvUri.startsWith('file://')) {\n    // Local file - stream directly from disk\n    const filePath = csvUri.replace('file://', '');\n    const resolvedPath = resolve(filePath);\n    return createReadStream(resolvedPath, { encoding: 'utf-8' });\n  }\n\n  if (csvUri.startsWith('http://') || csvUri.startsWith('https://')) {\n    // Remote file - stream directly from fetch response\n    const response = await fetch(csvUri);\n    if (!response.ok) {\n      throw new Error(`Failed to fetch CSV from ${csvUri}: ${response.statusText}`);\n    }\n\n    if (!response.body) {\n      throw new Error(`No response body from ${csvUri}`);\n    }\n\n    // Convert web stream to Node.js stream\n    // response.body is ReadableStream<Uint8Array> from fetch API\n    // Cast to Node.js ReadableStream type for compatibility with Readable.fromWeb\n    return Readable.fromWeb(response.body as unknown as NodeReadableStream<Uint8Array>);\n  }\n\n  throw new Error(`Invalid CSV URI: ${csvUri}. Must start with file://, http://, or https://`);\n}\n"],"names":["getCsvReadStream","csvUri","filePath","resolvedPath","response","startsWith","replace","resolve","createReadStream","encoding","fetch","ok","Error","statusText","body","Readable","fromWeb"],"mappings":"AAAA,+EAA+E;;;;+BAuBzDA;;;eAAAA;;;kBArBW;oBACT;sBACC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmBlB,SAAeA,iBAAiBC,MAAc;;YAG3CC,UACAC,cAMAC;;;;oBATR,IAAIH,OAAOI,UAAU,CAAC,YAAY;wBAChC,yCAAyC;wBACnCH,WAAWD,OAAOK,OAAO,CAAC,WAAW;wBACrCH,eAAeI,IAAAA,aAAO,EAACL;wBAC7B;;4BAAOM,IAAAA,oBAAgB,EAACL,cAAc;gCAAEM,UAAU;4BAAQ;;oBAC5D;yBAEIR,CAAAA,OAAOI,UAAU,CAAC,cAAcJ,OAAOI,UAAU,CAAC,WAAU,GAA5DJ;;;;oBAEe;;wBAAMS,MAAMT;;;oBAAvBG,WAAW;oBACjB,IAAI,CAACA,SAASO,EAAE,EAAE;wBAChB,MAAM,IAAIC,MAAM,AAAC,4BAAsCR,OAAXH,QAAO,MAAwB,OAApBG,SAASS,UAAU;oBAC5E;oBAEA,IAAI,CAACT,SAASU,IAAI,EAAE;wBAClB,MAAM,IAAIF,MAAM,AAAC,yBAA+B,OAAPX;oBAC3C;oBAEA,uCAAuC;oBACvC,6DAA6D;oBAC7D,8EAA8E;oBAC9E;;wBAAOc,gBAAQ,CAACC,OAAO,CAACZ,SAASU,IAAI;;;oBAGvC,MAAM,IAAIF,MAAM,AAAC,oBAA0B,OAAPX,QAAO;;;IAC7C"}

package/dist/cjs/spreadsheet/data-operations.d.cts

@@ -0,0 +1,115 @@
+import type { sheets_v4 } from 'googleapis';
+import type { Logger } from '../types.js';
+export type Cell = string | number | boolean | null | undefined;
+export type Row = Cell[];
+export interface ColumnMapping {
+    canonical: string;
+    sheet: string;
+    index: number;
+}
+export interface HeaderValidationResult {
+    valid: boolean;
+    missingColumns: string[];
+    extraColumns: string[];
+    mappings: ColumnMapping[];
+}
+export interface KeyGenerationStrategy {
+    keyColumns: string[];
+    useProviderIdLogic: boolean;
+    separator?: string;
+}
+export interface DataPartition {
+    toAppend: Row[];
+    toUpdate: Array<{
+        row: Row;
+        existingRowIndex: number;
+    }>;
+    skippedKeys: string[];
+}
+export interface BatchOperationResult {
+    updatedRows: number;
+    inserted: string[];
+    rowsSkipped: number;
+    errors?: string[];
+}
+export interface UpsertOptions {
+    keyStrategy: KeyGenerationStrategy;
+    allowUpdates: boolean;
+    batchSize?: number;
+    valueInputOption?: 'RAW' | 'USER_ENTERED';
+}
+export declare function discoverHeader(sheets: sheets_v4.Sheets, spreadsheetId: string, sheetTitle: string): Promise<string[]>;
+export declare function validateAndMapHeaders(sheetHeaders: string[], canonicalHeaders: string[], requiredColumns?: string[]): HeaderValidationResult;
+/** Ensures consistent key generation across all functions */
+export declare function generateRowKey(row: Row, header: string[], strategy: KeyGenerationStrategy): string;
+export declare function validateRowKeys(rows: Row[], header: string[], strategy: KeyGenerationStrategy): {
+    valid: boolean;
+    duplicateKeys: string[];
+    keyMap: Map<string, number[]>;
+};
+export declare function appendRows(sheets: sheets_v4.Sheets, params: {
+    spreadsheetId: string;
+    sheetTitle: string;
+    rows?: unknown[];
+    keySet?: Set<string> | null;
+    keyColumns?: string[];
+    header?: string[];
+    logger: Logger;
+}): Promise<{
+    updatedRows: number;
+    inserted: string[];
+    rowsSkipped?: number;
+}>;
+export declare function appendRows(sheets: sheets_v4.Sheets, params: {
+    spreadsheetId: string;
+    sheetRef: string;
+    rows?: unknown[];
+    keySet?: Set<string> | null;
+    keyColumns?: string[];
+    header?: string[];
+    logger: Logger;
+}): Promise<{
+    updatedRows: number;
+    inserted: string[];
+    rowsSkipped?: number;
+}>;
+export declare function mapRowsToHeader({ rows, header, canonical }: {
+    rows?: Row[];
+    header?: string[];
+    canonical?: string[];
+}): Row[];
+export declare function snapshotHeaderAndKeys(sheets: sheets_v4.Sheets, spreadsheetId: string, sheetTitle: string, keyColumns?: string[], keyStrategy?: Partial<KeyGenerationStrategy>): Promise<{
+    header: string[];
+    keySet: Set<string>;
+    keyIndices: number[];
+}>;
+/** Tracks row positions for updates in addition to keys */
+export declare function snapshotHeaderKeysAndPositions(sheets: sheets_v4.Sheets, spreadsheetId: string, sheetTitle: string, keyColumns?: string[], keyStrategy?: Partial<KeyGenerationStrategy>): Promise<{
+    header: string[];
+    keySet: Set<string>;
+    keyToRowMap: Map<string, number>;
+    keyIndices: number[];
+}>;
+/**
+ * Partitions data into updates vs appends based on existing keys with row position tracking
+ */
+export declare function partitionDataForUpsert(rows: Row[], header: string[], keyStrategy: KeyGenerationStrategy, existingKeys: Set<string>, allowUpdates?: boolean, keyToRowMap?: Map<string, number>): DataPartition;
+/**
+ * Performs batch updates on existing rows using batchUpdate API
+ */
+export declare function performBatchUpdates(sheets: sheets_v4.Sheets, spreadsheetId: string, sheetTitle: string, updates: Array<{
+    row: Row;
+    existingRowIndex: number;
+}>, header: string[], batchSize: number, valueInputOption: 'RAW' | 'USER_ENTERED'): Promise<{
+    updatedRows: number;
+    errors?: string[];
+}>;
+export declare function upsertByKey(sheets: sheets_v4.Sheets, { spreadsheetId, sheetTitle, sheetRef, rows, canonicalHeaders, options, logger, }: {
+    spreadsheetId: string;
+    sheetTitle?: string;
+    sheetRef?: string;
+    rows: Row[];
+    canonicalHeaders?: string[];
+    options: UpsertOptions;
+    logger: Logger;
+}): Promise<BatchOperationResult>;

package/dist/cjs/spreadsheet/data-operations.d.ts

@@ -0,0 +1,115 @@
+import type { sheets_v4 } from 'googleapis';
+import type { Logger } from '../types.js';
+export type Cell = string | number | boolean | null | undefined;
+export type Row = Cell[];
+export interface ColumnMapping {
+    canonical: string;
+    sheet: string;
+    index: number;
+}
+export interface HeaderValidationResult {
+    valid: boolean;
+    missingColumns: string[];
+    extraColumns: string[];
+    mappings: ColumnMapping[];
+}
+export interface KeyGenerationStrategy {
+    keyColumns: string[];
+    useProviderIdLogic: boolean;
+    separator?: string;
+}
+export interface DataPartition {
+    toAppend: Row[];
+    toUpdate: Array<{
+        row: Row;
+        existingRowIndex: number;
+    }>;
+    skippedKeys: string[];
+}
+export interface BatchOperationResult {
+    updatedRows: number;
+    inserted: string[];
+    rowsSkipped: number;
+    errors?: string[];
+}
+export interface UpsertOptions {
+    keyStrategy: KeyGenerationStrategy;
+    allowUpdates: boolean;
+    batchSize?: number;
+    valueInputOption?: 'RAW' | 'USER_ENTERED';
+}
+export declare function discoverHeader(sheets: sheets_v4.Sheets, spreadsheetId: string, sheetTitle: string): Promise<string[]>;
+export declare function validateAndMapHeaders(sheetHeaders: string[], canonicalHeaders: string[], requiredColumns?: string[]): HeaderValidationResult;
+/** Ensures consistent key generation across all functions */
+export declare function generateRowKey(row: Row, header: string[], strategy: KeyGenerationStrategy): string;
+export declare function validateRowKeys(rows: Row[], header: string[], strategy: KeyGenerationStrategy): {
+    valid: boolean;
+    duplicateKeys: string[];
+    keyMap: Map<string, number[]>;
+};
+export declare function appendRows(sheets: sheets_v4.Sheets, params: {
+    spreadsheetId: string;
+    sheetTitle: string;
+    rows?: unknown[];
+    keySet?: Set<string> | null;
+    keyColumns?: string[];
+    header?: string[];
+    logger: Logger;
+}): Promise<{
+    updatedRows: number;
+    inserted: string[];
+    rowsSkipped?: number;
+}>;
+export declare function appendRows(sheets: sheets_v4.Sheets, params: {
+    spreadsheetId: string;
+    sheetRef: string;
+    rows?: unknown[];
+    keySet?: Set<string> | null;
+    keyColumns?: string[];
+    header?: string[];
+    logger: Logger;
+}): Promise<{
+    updatedRows: number;
+    inserted: string[];
+    rowsSkipped?: number;
+}>;
+export declare function mapRowsToHeader({ rows, header, canonical }: {
+    rows?: Row[];
+    header?: string[];
+    canonical?: string[];
+}): Row[];
+export declare function snapshotHeaderAndKeys(sheets: sheets_v4.Sheets, spreadsheetId: string, sheetTitle: string, keyColumns?: string[], keyStrategy?: Partial<KeyGenerationStrategy>): Promise<{
+    header: string[];
+    keySet: Set<string>;
+    keyIndices: number[];
+}>;
+/** Tracks row positions for updates in addition to keys */
+export declare function snapshotHeaderKeysAndPositions(sheets: sheets_v4.Sheets, spreadsheetId: string, sheetTitle: string, keyColumns?: string[], keyStrategy?: Partial<KeyGenerationStrategy>): Promise<{
+    header: string[];
+    keySet: Set<string>;
+    keyToRowMap: Map<string, number>;
+    keyIndices: number[];
+}>;
+/**
+ * Partitions data into updates vs appends based on existing keys with row position tracking
+ */
+export declare function partitionDataForUpsert(rows: Row[], header: string[], keyStrategy: KeyGenerationStrategy, existingKeys: Set<string>, allowUpdates?: boolean, keyToRowMap?: Map<string, number>): DataPartition;
+/**
+ * Performs batch updates on existing rows using batchUpdate API
+ */
+export declare function performBatchUpdates(sheets: sheets_v4.Sheets, spreadsheetId: string, sheetTitle: string, updates: Array<{
+    row: Row;
+    existingRowIndex: number;
+}>, header: string[], batchSize: number, valueInputOption: 'RAW' | 'USER_ENTERED'): Promise<{
+    updatedRows: number;
+    errors?: string[];
+}>;
+export declare function upsertByKey(sheets: sheets_v4.Sheets, { spreadsheetId, sheetTitle, sheetRef, rows, canonicalHeaders, options, logger, }: {
+    spreadsheetId: string;
+    sheetTitle?: string;
+    sheetRef?: string;
+    rows: Row[];
+    canonicalHeaders?: string[];
+    options: UpsertOptions;
+    logger: Logger;
+}): Promise<BatchOperationResult>;