@mcp-z/mcp-sheets 1.0.0

package/dist/cjs/spreadsheet/data-operations.js

@@ -0,0 +1,1515 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get appendRows () {
+        return appendRows;
+    },
+    get discoverHeader () {
+        return discoverHeader;
+    },
+    get generateRowKey () {
+        return generateRowKey;
+    },
+    get mapRowsToHeader () {
+        return mapRowsToHeader;
+    },
+    get partitionDataForUpsert () {
+        return partitionDataForUpsert;
+    },
+    get performBatchUpdates () {
+        return performBatchUpdates;
+    },
+    get snapshotHeaderAndKeys () {
+        return snapshotHeaderAndKeys;
+    },
+    get snapshotHeaderKeysAndPositions () {
+        return snapshotHeaderKeysAndPositions;
+    },
+    get upsertByKey () {
+        return upsertByKey;
+    },
+    get validateAndMapHeaders () {
+        return validateAndMapHeaders;
+    },
+    get validateRowKeys () {
+        return validateRowKeys;
+    }
+});
+var _columnutilities = require("./column-utilities.js");
+var _sheetoperations = require("./sheet-operations.js");
+function _array_like_to_array(arr, len) {
+    if (len == null || len > arr.length) len = arr.length;
+    for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
+    return arr2;
+}
+function _array_without_holes(arr) {
+    if (Array.isArray(arr)) return _array_like_to_array(arr);
+}
+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 _instanceof(left, right) {
+    if (right != null && typeof Symbol !== "undefined" && right[Symbol.hasInstance]) {
+        return !!right[Symbol.hasInstance](left);
+    } else {
+        return left instanceof right;
+    }
+}
+function _iterable_to_array(iter) {
+    if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
+}
+function _non_iterable_spread() {
+    throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
+function _to_consumable_array(arr) {
+    return _array_without_holes(arr) || _iterable_to_array(arr) || _unsupported_iterable_to_array(arr) || _non_iterable_spread();
+}
+function _unsupported_iterable_to_array(o, minLen) {
+    if (!o) return;
+    if (typeof o === "string") return _array_like_to_array(o, minLen);
+    var n = Object.prototype.toString.call(o).slice(8, -1);
+    if (n === "Object" && o.constructor) n = o.constructor.name;
+    if (n === "Map" || n === "Set") return Array.from(n);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array(o, minLen);
+}
+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 discoverHeader(sheets, spreadsheetId, sheetTitle) {
+    return _async_to_generator(function() {
+        var _response_data, response, unused;
+        return _ts_generator(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    _state.trys.push([
+                        0,
+                        2,
+                        ,
+                        3
+                    ]);
+                    return [
+                        4,
+                        sheets.spreadsheets.values.get({
+                            spreadsheetId: spreadsheetId,
+                            range: "".concat(sheetTitle, "!1:1"),
+                            majorDimension: 'ROWS'
+                        })
+                    ];
+                case 1:
+                    response = _state.sent();
+                    return [
+                        2,
+                        (((_response_data = response.data) === null || _response_data === void 0 ? void 0 : _response_data.values) || [])[0] || []
+                    ];
+                case 2:
+                    unused = _state.sent();
+                    return [
+                        2,
+                        []
+                    ];
+                case 3:
+                    return [
+                        2
+                    ];
+            }
+        });
+    })();
+}
+function validateAndMapHeaders(sheetHeaders, canonicalHeaders) {
+    var requiredColumns = arguments.length > 2 && arguments[2] !== void 0 ? arguments[2] : [];
+    var normalizeColumn = function(col) {
+        return String(col !== null && col !== void 0 ? col : '').toLowerCase().replace(/[^a-z0-9]/g, '');
+    };
+    var sheetNormalized = sheetHeaders.map(normalizeColumn);
+    var canonicalNormalized = canonicalHeaders.map(normalizeColumn);
+    var requiredNormalized = requiredColumns.map(normalizeColumn);
+    var mappings = [];
+    var missingColumns = [];
+    var extraColumns = _to_consumable_array(sheetHeaders);
+    // Create mappings for canonical columns
+    canonicalHeaders.forEach(function(canonical, canonicalIndex) {
+        var canonicalNorm = canonicalNormalized[canonicalIndex];
+        if (!canonicalNorm) return; // Skip if normalization resulted in empty string
+        var sheetIndex = sheetNormalized.indexOf(canonicalNorm);
+        // Special handling for 'id' -> 'messageid' mapping
+        if (sheetIndex === -1 && canonicalNorm === 'id') {
+            sheetIndex = sheetNormalized.indexOf('messageid');
+        }
+        if (sheetIndex !== -1) {
+            var sheetHeader = sheetHeaders[sheetIndex];
+            if (sheetHeader !== undefined) {
+                mappings.push({
+                    canonical: canonical,
+                    sheet: sheetHeader,
+                    index: sheetIndex
+                });
+                // Remove from extra columns
+                var extraIndex = extraColumns.indexOf(sheetHeader);
+                if (extraIndex !== -1) {
+                    extraColumns.splice(extraIndex, 1);
+                }
+            }
+        } else if (requiredNormalized.includes(canonicalNorm)) {
+            missingColumns.push(canonical);
+        }
+    });
+    return {
+        valid: missingColumns.length === 0,
+        missingColumns: missingColumns,
+        extraColumns: extraColumns,
+        mappings: mappings
+    };
+}
+function generateRowKey(row, header, strategy) {
+    var keyColumns = strategy.keyColumns, useProviderIdLogic = strategy.useProviderIdLogic, _strategy_separator = strategy.separator, separator = _strategy_separator === void 0 ? '\\' : _strategy_separator;
+    // Normalize header for consistent lookups
+    var lowerHeader = header.map(function(h) {
+        return String(h !== null && h !== void 0 ? h : '').toLowerCase();
+    });
+    if (useProviderIdLogic) {
+        var providerIndex = lowerHeader.indexOf('provider');
+        var idIndex = lowerHeader.indexOf('messageid');
+        if (idIndex === -1) idIndex = lowerHeader.indexOf('id');
+        if (providerIndex >= 0 && idIndex >= 0) {
+            var _row_providerIndex, _row_idIndex;
+            var providerVal = String((_row_providerIndex = row[providerIndex]) !== null && _row_providerIndex !== void 0 ? _row_providerIndex : '').trim();
+            var idVal = String((_row_idIndex = row[idIndex]) !== null && _row_idIndex !== void 0 ? _row_idIndex : '').trim();
+            if (providerVal || idVal) {
+                // Only return key if at least one component exists
+                return [
+                    providerVal,
+                    idVal
+                ].join(separator);
+            }
+        }
+    }
+    // Standard key generation using specified columns
+    var keyIndices = keyColumns.map(function(name) {
+        var normalizedName = String(name !== null && name !== void 0 ? name : '').toLowerCase();
+        var index = lowerHeader.indexOf(normalizedName);
+        // Consistent fallback: id -> messageid
+        if (index === -1 && normalizedName === 'id') {
+            index = lowerHeader.indexOf('messageid');
+        }
+        return index;
+    }).filter(function(index) {
+        return index >= 0;
+    });
+    if (keyIndices.length === 0) {
+        return ''; // Return empty string for invalid key configurations
+    }
+    var components = keyIndices.map(function(index) {
+        var _row_index;
+        return String((_row_index = row[index]) !== null && _row_index !== void 0 ? _row_index : '').trim();
+    });
+    // Only return key if all components are non-empty
+    if (components.every(function(comp) {
+        return comp.length > 0;
+    })) {
+        return components.join(separator);
+    }
+    return '';
+}
+function validateRowKeys(rows, header, strategy) {
+    var keyMap = new Map();
+    var duplicateKeys = [];
+    rows.forEach(function(row, index) {
+        var _keyMap_get;
+        var key = generateRowKey(row, header, strategy);
+        if (key.replace(/\\+/g, '') === '') return; // Skip empty keys
+        if (!keyMap.has(key)) {
+            keyMap.set(key, []);
+        }
+        (_keyMap_get = keyMap.get(key)) === null || _keyMap_get === void 0 ? void 0 : _keyMap_get.push(index);
+    });
+    // Find duplicates
+    keyMap.forEach(function(indices, key) {
+        if (indices.length > 1) {
+            duplicateKeys.push(key);
+        }
+    });
+    return {
+        valid: duplicateKeys.length === 0,
+        duplicateKeys: duplicateKeys,
+        keyMap: keyMap
+    };
+}
+function appendRows(_0, _1) {
+    return _async_to_generator(function(sheets, param) {
+        var spreadsheetId, sheetTitle, sheetRef, _param_rows, rows, _param_keySet, keySet, _param_keyColumns, keyColumns, _param_header, header, logger, resolvedSheetTitle, sheet, _sheet_properties, respHeader, vr, resolveKeyIndices, keyColsIdx, batchSize, totalUpdated, i, _app_updates, batch, resp, app, updatedRows, toKey, rowsToInsert, insertedKeys, _iteratorNormalCompletion, _didIteratorError, _iteratorError, _iterator, _step, r, key, rowsSkipped, INTERNAL_BATCH_SIZE, totalUpdated1, i1, batch1, _app2_updates, resp1, app2, updatedRows1, error, _iteratorNormalCompletion1, _didIteratorError1, _iteratorError1, _iterator1, _step1, singleRow, _singleApp_updates, singleResp, singleApp, singleUpdatedRows, singleError, // Skip problematic individual rows but continue processing
+        _logger_warn, err, // Single row batch failed, skip it
+        _logger_warn1, rowsSkipped1;
+        return _ts_generator(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    spreadsheetId = param.spreadsheetId, sheetTitle = param.sheetTitle, sheetRef = param.sheetRef, _param_rows = param.rows, rows = _param_rows === void 0 ? [] : _param_rows, _param_keySet = param.keySet, keySet = _param_keySet === void 0 ? null : _param_keySet, _param_keyColumns = param.keyColumns, keyColumns = _param_keyColumns === void 0 ? [
+                        'id'
+                    ] : _param_keyColumns, _param_header = param.header, header = _param_header === void 0 ? [] : _param_header, logger = param.logger;
+                    if (!sheets) throw new Error('appendRows: sheets is required');
+                    if (!spreadsheetId) throw new Error('appendRows: spreadsheetId is required');
+                    if (!sheetTitle && !sheetRef) throw new Error('appendRows: either sheetTitle or sheetRef is required');
+                    // Resolve the actual sheet title from sheetRef if provided
+                    resolvedSheetTitle = sheetTitle;
+                    if (!sheetRef) return [
+                        3,
+                        2
+                    ];
+                    return [
+                        4,
+                        (0, _sheetoperations.findSheetByRef)(sheets, spreadsheetId, sheetRef, logger)
+                    ];
+                case 1:
+                    sheet = _state.sent();
+                    if (sheet) {
+                        ;
+                        resolvedSheetTitle = ((_sheet_properties = sheet.properties) === null || _sheet_properties === void 0 ? void 0 : _sheet_properties.title) || sheetRef;
+                    } else {
+                        // Sheet doesn't exist, use the sheetRef as the title
+                        resolvedSheetTitle = sheetRef;
+                    }
+                    _state.label = 2;
+                case 2:
+                    if (!resolvedSheetTitle) throw new Error('appendRows: could not resolve sheet title');
+                    if (!Array.isArray(rows) || rows.length === 0) return [
+                        2,
+                        {
+                            updatedRows: 0,
+                            inserted: []
+                        }
+                    ];
+                    if (!(!Array.isArray(header) || header.length === 0)) return [
+                        3,
+                        4
+                    ];
+                    return [
+                        4,
+                        sheets.spreadsheets.values.get({
+                            spreadsheetId: spreadsheetId,
+                            range: "".concat(resolvedSheetTitle, "!1:1"),
+                            majorDimension: 'ROWS'
+                        })
+                    ];
+                case 3:
+                    respHeader = _state.sent();
+                    vr = respHeader.data;
+                    header = ((vr === null || vr === void 0 ? void 0 : vr.values) || [])[0] || [];
+                    _state.label = 4;
+                case 4:
+                    resolveKeyIndices = function(kc, hdr) {
+                        if (!Array.isArray(kc) || kc.length === 0) return [];
+                        var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+                        try {
+                            for(var _iterator = kc[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+                                var c = _step.value;
+                                if (typeof c !== 'string' || c.length === 0) throw new Error('appendRows: keyColumns must be an array of non-empty strings');
+                            }
+                        } catch (err) {
+                            _didIteratorError = true;
+                            _iteratorError = err;
+                        } finally{
+                            try {
+                                if (!_iteratorNormalCompletion && _iterator.return != null) {
+                                    _iterator.return();
+                                }
+                            } finally{
+                                if (_didIteratorError) {
+                                    throw _iteratorError;
+                                }
+                            }
+                        }
+                        if (!Array.isArray(hdr) || hdr.length === 0) {
+                            throw new Error('appendRows: header array is required when keyColumns are header names');
+                        }
+                        return kc.map(function(name) {
+                            var idx = hdr.indexOf(name);
+                            if (idx === -1) throw new Error('appendRows: header name "'.concat(name, '" not found in header'));
+                            return idx;
+                        });
+                    };
+                    keyColsIdx = resolveKeyIndices(keyColumns, header);
+                    // Internal batch size to avoid Google Sheets limits
+                    batchSize = 50;
+                    if (!(!keyColsIdx || keyColsIdx.length === 0)) return [
+                        3,
+                        9
+                    ];
+                    totalUpdated = 0;
+                    i = 0;
+                    _state.label = 5;
+                case 5:
+                    if (!(i < rows.length)) return [
+                        3,
+                        8
+                    ];
+                    batch = rows.slice(i, i + batchSize);
+                    return [
+                        4,
+                        sheets.spreadsheets.values.append({
+                            spreadsheetId: spreadsheetId,
+                            range: "".concat(resolvedSheetTitle, "!A1"),
+                            valueInputOption: 'RAW',
+                            insertDataOption: 'INSERT_ROWS',
+                            requestBody: {
+                                values: batch
+                            }
+                        })
+                    ];
+                case 6:
+                    resp = _state.sent();
+                    app = resp.data;
+                    updatedRows = Number((app === null || app === void 0 ? void 0 : (_app_updates = app.updates) === null || _app_updates === void 0 ? void 0 : _app_updates.updatedRows) || batch.length);
+                    totalUpdated += updatedRows;
+                    _state.label = 7;
+                case 7:
+                    i += batchSize;
+                    return [
+                        3,
+                        5
+                    ];
+                case 8:
+                    return [
+                        2,
+                        {
+                            updatedRows: totalUpdated,
+                            inserted: [],
+                            rowsSkipped: 0
+                        }
+                    ];
+                case 9:
+                    toKey = function(r) {
+                        var row = r;
+                        // Use consistent key generation strategy
+                        var strategy = {
+                            keyColumns: keyColumns,
+                            useProviderIdLogic: true,
+                            separator: '\\'
+                        };
+                        return generateRowKey(row, header, strategy);
+                    };
+                    rowsToInsert = [];
+                    insertedKeys = [];
+                    _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+                    try {
+                        for(_iterator = rows[Symbol.iterator](); !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+                            r = _step.value;
+                            key = toKey(r);
+                            if (keySet && keySet.has(key)) continue;
+                            rowsToInsert.push(r);
+                            insertedKeys.push(key);
+                        }
+                    } catch (err) {
+                        _didIteratorError = true;
+                        _iteratorError = err;
+                    } finally{
+                        try {
+                            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                                _iterator.return();
+                            }
+                        } finally{
+                            if (_didIteratorError) {
+                                throw _iteratorError;
+                            }
+                        }
+                    }
+                    if (rowsToInsert.length === 0) {
+                        rowsSkipped = rows.length - rowsToInsert.length; // Should be rows.length when all are skipped
+                        return [
+                            2,
+                            {
+                                updatedRows: 0,
+                                inserted: [],
+                                rowsSkipped: rowsSkipped
+                            }
+                        ];
+                    }
+                    // Use smaller internal batch size to avoid Google Sheets character limit errors
+                    // Especially important when dealing with emails that may have long bodies
+                    INTERNAL_BATCH_SIZE = 50;
+                    totalUpdated1 = 0;
+                    i1 = 0;
+                    _state.label = 10;
+                case 10:
+                    if (!(i1 < rowsToInsert.length)) return [
+                        3,
+                        27
+                    ];
+                    batch1 = rowsToInsert.slice(i1, i1 + INTERNAL_BATCH_SIZE);
+                    _state.label = 11;
+                case 11:
+                    _state.trys.push([
+                        11,
+                        13,
+                        ,
+                        26
+                    ]);
+                    return [
+                        4,
+                        sheets.spreadsheets.values.append({
+                            spreadsheetId: spreadsheetId,
+                            range: "".concat(resolvedSheetTitle, "!A1"),
+                            valueInputOption: 'RAW',
+                            insertDataOption: 'INSERT_ROWS',
+                            requestBody: {
+                                values: batch1
+                            }
+                        })
+                    ];
+                case 12:
+                    resp1 = _state.sent();
+                    app2 = resp1.data;
+                    updatedRows1 = Number((app2 === null || app2 === void 0 ? void 0 : (_app2_updates = app2.updates) === null || _app2_updates === void 0 ? void 0 : _app2_updates.updatedRows) || batch1.length);
+                    totalUpdated1 += updatedRows1;
+                    return [
+                        3,
+                        26
+                    ];
+                case 13:
+                    error = _state.sent();
+                    if (!(batch1.length > 1)) return [
+                        3,
+                        24
+                    ];
+                    _iteratorNormalCompletion1 = true, _didIteratorError1 = false, _iteratorError1 = undefined;
+                    _state.label = 14;
+                case 14:
+                    _state.trys.push([
+                        14,
+                        21,
+                        22,
+                        23
+                    ]);
+                    _iterator1 = batch1[Symbol.iterator]();
+                    _state.label = 15;
+                case 15:
+                    if (!!(_iteratorNormalCompletion1 = (_step1 = _iterator1.next()).done)) return [
+                        3,
+                        20
+                    ];
+                    singleRow = _step1.value;
+                    _state.label = 16;
+                case 16:
+                    _state.trys.push([
+                        16,
+                        18,
+                        ,
+                        19
+                    ]);
+                    return [
+                        4,
+                        sheets.spreadsheets.values.append({
+                            spreadsheetId: spreadsheetId,
+                            range: "".concat(resolvedSheetTitle, "!A1"),
+                            valueInputOption: 'RAW',
+                            insertDataOption: 'INSERT_ROWS',
+                            requestBody: {
+                                values: [
+                                    singleRow
+                                ]
+                            }
+                        })
+                    ];
+                case 17:
+                    singleResp = _state.sent();
+                    singleApp = singleResp.data;
+                    singleUpdatedRows = Number((singleApp === null || singleApp === void 0 ? void 0 : (_singleApp_updates = singleApp.updates) === null || _singleApp_updates === void 0 ? void 0 : _singleApp_updates.updatedRows) || 1);
+                    totalUpdated1 += singleUpdatedRows;
+                    return [
+                        3,
+                        19
+                    ];
+                case 18:
+                    singleError = _state.sent();
+                    (_logger_warn = logger.warn) === null || _logger_warn === void 0 ? void 0 : _logger_warn.call(logger, "Failed to insert single row: ".concat(_instanceof(singleError, Error) ? singleError.message : String(singleError)));
+                    return [
+                        3,
+                        19
+                    ];
+                case 19:
+                    _iteratorNormalCompletion1 = true;
+                    return [
+                        3,
+                        15
+                    ];
+                case 20:
+                    return [
+                        3,
+                        23
+                    ];
+                case 21:
+                    err = _state.sent();
+                    _didIteratorError1 = true;
+                    _iteratorError1 = err;
+                    return [
+                        3,
+                        23
+                    ];
+                case 22:
+                    try {
+                        if (!_iteratorNormalCompletion1 && _iterator1.return != null) {
+                            _iterator1.return();
+                        }
+                    } finally{
+                        if (_didIteratorError1) {
+                            throw _iteratorError1;
+                        }
+                    }
+                    return [
+                        7
+                    ];
+                case 23:
+                    return [
+                        3,
+                        25
+                    ];
+                case 24:
+                    (_logger_warn1 = logger.warn) === null || _logger_warn1 === void 0 ? void 0 : _logger_warn1.call(logger, "Failed to insert batch: ".concat(_instanceof(error, Error) ? error.message : String(error)));
+                    _state.label = 25;
+                case 25:
+                    return [
+                        3,
+                        26
+                    ];
+                case 26:
+                    i1 += INTERNAL_BATCH_SIZE;
+                    return [
+                        3,
+                        10
+                    ];
+                case 27:
+                    rowsSkipped1 = rows.length - rowsToInsert.length;
+                    return [
+                        2,
+                        {
+                            updatedRows: totalUpdated1,
+                            inserted: insertedKeys,
+                            rowsSkipped: rowsSkipped1
+                        }
+                    ];
+            }
+        });
+    }).apply(this, arguments);
+}
+function mapRowsToHeader(param) {
+    var _param_rows = param.rows, rows = _param_rows === void 0 ? [] : _param_rows, _param_header = param.header, header = _param_header === void 0 ? [] : _param_header, _param_canonical = param.canonical, canonical = _param_canonical === void 0 ? [] : _param_canonical;
+    if (!Array.isArray(rows) || rows.length === 0) return [];
+    if (!Array.isArray(header) || header.length === 0) return rows;
+    if (!Array.isArray(canonical) || canonical.length === 0) return rows;
+    var validation = validateAndMapHeaders(header, canonical);
+    var mappingLookup = new Map(validation.mappings.map(function(m) {
+        return [
+            m.canonical,
+            m.index
+        ];
+    }));
+    return rows.map(function(row) {
+        // Fill with null to skip unmapped columns (preserve existing values)
+        // Use '' (empty string) only when explicitly wanting to clear a cell
+        var mappedRow = new Array(header.length).fill(null);
+        canonical.forEach(function(canonicalCol, canonicalIndex) {
+            var sheetIndex = mappingLookup.get(canonicalCol);
+            if (sheetIndex !== undefined && canonicalIndex < row.length) {
+                // Preserve null values - they signal "skip this cell"
+                mappedRow[sheetIndex] = row[canonicalIndex];
+            }
+        });
+        return mappedRow;
+    });
+}
+function snapshotHeaderAndKeys(_0, _1, _2, _3) {
+    return _async_to_generator(function(sheets, spreadsheetId, sheetTitle) {
+        var keyColumns, keyStrategy, _Math, _Math1, _ref, _ref1, header, keySet, strategy, keyIndices, chunkSize, startRow, minIndex, maxIndex, startCol, endCol, endRow, range, _response_data, response, rows, _iteratorNormalCompletion, _didIteratorError, _iteratorError, _loop, _iterator, _step, unused;
+        var _arguments = arguments;
+        return _ts_generator(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    keyColumns = _arguments.length > 3 && _arguments[3] !== void 0 ? _arguments[3] : [
+                        'id'
+                    ], keyStrategy = _arguments.length > 4 ? _arguments[4] : void 0;
+                    return [
+                        4,
+                        discoverHeader(sheets, spreadsheetId, sheetTitle)
+                    ];
+                case 1:
+                    header = _state.sent();
+                    keySet = new Set();
+                    if (header.length === 0) {
+                        return [
+                            2,
+                            {
+                                header: header,
+                                keySet: keySet,
+                                keyIndices: []
+                            }
+                        ];
+                    }
+                    strategy = {
+                        keyColumns: keyColumns,
+                        useProviderIdLogic: (_ref = keyStrategy === null || keyStrategy === void 0 ? void 0 : keyStrategy.useProviderIdLogic) !== null && _ref !== void 0 ? _ref : true,
+                        separator: (_ref1 = keyStrategy === null || keyStrategy === void 0 ? void 0 : keyStrategy.separator) !== null && _ref1 !== void 0 ? _ref1 : '\\'
+                    };
+                    // Find key column indices
+                    keyIndices = keyColumns.map(function(name) {
+                        var normalizedName = String(name !== null && name !== void 0 ? name : '').toLowerCase();
+                        var lowerHeader = header.map(function(h) {
+                            return String(h !== null && h !== void 0 ? h : '').toLowerCase();
+                        });
+                        var index = lowerHeader.indexOf(normalizedName);
+                        if (index === -1 && normalizedName === 'id') {
+                            index = lowerHeader.indexOf('messageid');
+                        }
+                        return index;
+                    }).filter(function(index) {
+                        return index >= 0;
+                    });
+                    if (keyIndices.length === 0) {
+                        return [
+                            2,
+                            {
+                                header: header,
+                                keySet: keySet,
+                                keyIndices: keyIndices
+                            }
+                        ];
+                    }
+                    // Read key columns data in chunks
+                    chunkSize = 1000;
+                    startRow = 2;
+                    minIndex = (_Math = Math).min.apply(_Math, _to_consumable_array(keyIndices));
+                    maxIndex = (_Math1 = Math).max.apply(_Math1, _to_consumable_array(keyIndices));
+                    startCol = (0, _columnutilities.a1Col)(minIndex + 1);
+                    endCol = (0, _columnutilities.a1Col)(maxIndex + 1);
+                    _state.label = 2;
+                case 2:
+                    if (!true) return [
+                        3,
+                        7
+                    ];
+                    endRow = startRow + chunkSize - 1;
+                    range = "".concat(sheetTitle, "!").concat(startCol).concat(startRow, ":").concat(endCol).concat(endRow);
+                    _state.label = 3;
+                case 3:
+                    _state.trys.push([
+                        3,
+                        5,
+                        ,
+                        6
+                    ]);
+                    return [
+                        4,
+                        sheets.spreadsheets.values.get({
+                            spreadsheetId: spreadsheetId,
+                            range: range,
+                            majorDimension: 'ROWS'
+                        })
+                    ];
+                case 4:
+                    response = _state.sent();
+                    rows = ((_response_data = response.data) === null || _response_data === void 0 ? void 0 : _response_data.values) || [];
+                    if (rows.length === 0) return [
+                        3,
+                        7
+                    ];
+                    _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+                    try {
+                        _loop = function() {
+                            var rawRow = _step.value;
+                            // Reconstruct full row for key generation
+                            var fullRow = new Array(header.length).fill('');
+                            keyIndices.forEach(function(globalIndex, _localIndex) {
+                                var localRowIndex = globalIndex - minIndex;
+                                if (localRowIndex >= 0 && localRowIndex < rawRow.length) {
+                                    fullRow[globalIndex] = rawRow[localRowIndex];
+                                }
+                            });
+                            var key = generateRowKey(fullRow, header, strategy);
+                            if (key.replace(/\\+/g, '') !== '') {
+                                keySet.add(key);
+                            }
+                        };
+                        for(_iterator = rows[Symbol.iterator](); !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true)_loop();
+                    } catch (err) {
+                        _didIteratorError = true;
+                        _iteratorError = err;
+                    } finally{
+                        try {
+                            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                                _iterator.return();
+                            }
+                        } finally{
+                            if (_didIteratorError) {
+                                throw _iteratorError;
+                            }
+                        }
+                    }
+                    startRow += rows.length;
+                    if (rows.length < chunkSize) return [
+                        3,
+                        7
+                    ]; // Last chunk
+                    return [
+                        3,
+                        6
+                    ];
+                case 5:
+                    unused = _state.sent();
+                    return [
+                        3,
+                        7
+                    ]; // End of data or error
+                case 6:
+                    return [
+                        3,
+                        2
+                    ];
+                case 7:
+                    return [
+                        2,
+                        {
+                            header: header,
+                            keySet: keySet,
+                            keyIndices: keyIndices
+                        }
+                    ];
+            }
+        });
+    }).apply(this, arguments);
+}
+function snapshotHeaderKeysAndPositions(_0, _1, _2, _3) {
+    return _async_to_generator(function(sheets, spreadsheetId, sheetTitle) {
+        var keyColumns, keyStrategy, _Math, _Math1, _ref, _ref1, header, keySet, keyToRowMap, strategy, keyIndices, chunkSize, startRow, minIndex, maxIndex, startCol, endCol, endRow, range, _loop, _response_data, response, rows, localRowIndex, unused;
+        var _arguments = arguments;
+        return _ts_generator(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    keyColumns = _arguments.length > 3 && _arguments[3] !== void 0 ? _arguments[3] : [
+                        'id'
+                    ], keyStrategy = _arguments.length > 4 ? _arguments[4] : void 0;
+                    return [
+                        4,
+                        discoverHeader(sheets, spreadsheetId, sheetTitle)
+                    ];
+                case 1:
+                    header = _state.sent();
+                    keySet = new Set();
+                    keyToRowMap = new Map();
+                    if (header.length === 0) {
+                        return [
+                            2,
+                            {
+                                header: header,
+                                keySet: keySet,
+                                keyToRowMap: keyToRowMap,
+                                keyIndices: []
+                            }
+                        ];
+                    }
+                    strategy = {
+                        keyColumns: keyColumns,
+                        useProviderIdLogic: (_ref = keyStrategy === null || keyStrategy === void 0 ? void 0 : keyStrategy.useProviderIdLogic) !== null && _ref !== void 0 ? _ref : true,
+                        separator: (_ref1 = keyStrategy === null || keyStrategy === void 0 ? void 0 : keyStrategy.separator) !== null && _ref1 !== void 0 ? _ref1 : '\\'
+                    };
+                    // Find key column indices
+                    keyIndices = keyColumns.map(function(name) {
+                        var normalizedName = String(name !== null && name !== void 0 ? name : '').toLowerCase();
+                        var lowerHeader = header.map(function(h) {
+                            return String(h !== null && h !== void 0 ? h : '').toLowerCase();
+                        });
+                        var index = lowerHeader.indexOf(normalizedName);
+                        if (index === -1 && normalizedName === 'id') {
+                            index = lowerHeader.indexOf('messageid');
+                        }
+                        return index;
+                    }).filter(function(index) {
+                        return index >= 0;
+                    });
+                    if (keyIndices.length === 0) {
+                        return [
+                            2,
+                            {
+                                header: header,
+                                keySet: keySet,
+                                keyToRowMap: keyToRowMap,
+                                keyIndices: keyIndices
+                            }
+                        ];
+                    }
+                    // Read key columns data in chunks and track row positions
+                    chunkSize = 1000;
+                    startRow = 2; // Start from row 2 (after header)
+                    minIndex = (_Math = Math).min.apply(_Math, _to_consumable_array(keyIndices));
+                    maxIndex = (_Math1 = Math).max.apply(_Math1, _to_consumable_array(keyIndices));
+                    startCol = (0, _columnutilities.a1Col)(minIndex + 1);
+                    endCol = (0, _columnutilities.a1Col)(maxIndex + 1);
+                    _state.label = 2;
+                case 2:
+                    if (!true) return [
+                        3,
+                        7
+                    ];
+                    endRow = startRow + chunkSize - 1;
+                    range = "".concat(sheetTitle, "!").concat(startCol).concat(startRow, ":").concat(endCol).concat(endRow);
+                    _state.label = 3;
+                case 3:
+                    _state.trys.push([
+                        3,
+                        5,
+                        ,
+                        6
+                    ]);
+                    _loop = function(localRowIndex) {
+                        var rawRow = rows[localRowIndex];
+                        var globalRowNumber = startRow + localRowIndex;
+                        // Reconstruct full row for key generation
+                        var fullRow = new Array(header.length).fill('');
+                        if (rawRow) {
+                            keyIndices.forEach(function(globalIndex, _localIndex) {
+                                var localRowArrayIndex = globalIndex - minIndex;
+                                if (localRowArrayIndex >= 0 && localRowArrayIndex < rawRow.length) {
+                                    fullRow[globalIndex] = rawRow[localRowArrayIndex];
+                                }
+                            });
+                        }
+                        var key = generateRowKey(fullRow, header, strategy);
+                        if (key.replace(/\\+/g, '') !== '') {
+                            keySet.add(key);
+                            keyToRowMap.set(key, globalRowNumber); // Store 1-indexed row number
+                        }
+                    };
+                    return [
+                        4,
+                        sheets.spreadsheets.values.get({
+                            spreadsheetId: spreadsheetId,
+                            range: range,
+                            majorDimension: 'ROWS'
+                        })
+                    ];
+                case 4:
+                    response = _state.sent();
+                    rows = ((_response_data = response.data) === null || _response_data === void 0 ? void 0 : _response_data.values) || [];
+                    if (rows.length === 0) return [
+                        3,
+                        7
+                    ];
+                    for(localRowIndex = 0; localRowIndex < rows.length; localRowIndex++)_loop(localRowIndex);
+                    startRow += rows.length;
+                    if (rows.length < chunkSize) return [
+                        3,
+                        7
+                    ]; // Last chunk
+                    return [
+                        3,
+                        6
+                    ];
+                case 5:
+                    unused = _state.sent();
+                    return [
+                        3,
+                        7
+                    ]; // End of data or error
+                case 6:
+                    return [
+                        3,
+                        2
+                    ];
+                case 7:
+                    return [
+                        2,
+                        {
+                            header: header,
+                            keySet: keySet,
+                            keyToRowMap: keyToRowMap,
+                            keyIndices: keyIndices
+                        }
+                    ];
+            }
+        });
+    }).apply(this, arguments);
+}
+function partitionDataForUpsert(rows, header, keyStrategy, existingKeys) {
+    var allowUpdates = arguments.length > 4 && arguments[4] !== void 0 ? arguments[4] : false, keyToRowMap = arguments.length > 5 ? arguments[5] : void 0;
+    var toAppend = [];
+    var toUpdate = [];
+    var skippedKeys = [];
+    rows.forEach(function(row) {
+        var key = generateRowKey(row, header, keyStrategy);
+        if (key.replace(/\\+/g, '') === '') {
+            // Skip rows with empty keys
+            return;
+        }
+        if (existingKeys.has(key)) {
+            if (allowUpdates && keyToRowMap) {
+                var existingRowIndex = keyToRowMap.get(key);
+                if (existingRowIndex !== undefined) {
+                    toUpdate.push({
+                        row: row,
+                        existingRowIndex: existingRowIndex
+                    });
+                } else {
+                    skippedKeys.push(key);
+                }
+            } else {
+                skippedKeys.push(key);
+            }
+        } else {
+            toAppend.push(row);
+        }
+    });
+    return {
+        toAppend: toAppend,
+        toUpdate: toUpdate,
+        skippedKeys: skippedKeys
+    };
+}
+function performBatchUpdates(sheets, spreadsheetId, sheetTitle, updates, header, batchSize, valueInputOption) {
+    return _async_to_generator(function() {
+        var errors, totalUpdated, i, batch, requests, _iteratorNormalCompletion, _didIteratorError, _iteratorError, _iterator, _step, _step_value, row, existingRowIndex, error, errorMsg, _iteratorNormalCompletion1, _didIteratorError1, _iteratorError1, _iterator1, _step1, _step_value1, row1, existingRowIndex1, range, singleError, err, result;
+        return _ts_generator(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    errors = [];
+                    totalUpdated = 0;
+                    i = 0;
+                    _state.label = 1;
+                case 1:
+                    if (!(i < updates.length)) return [
+                        3,
+                        17
+                    ];
+                    batch = updates.slice(i, i + batchSize);
+                    _state.label = 2;
+                case 2:
+                    _state.trys.push([
+                        2,
+                        5,
+                        ,
+                        16
+                    ]);
+                    requests = [];
+                    _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+                    try {
+                        for(_iterator = batch[Symbol.iterator](); !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+                            _step_value = _step.value, row = _step_value.row, existingRowIndex = _step_value.existingRowIndex;
+                            requests.push({
+                                updateCells: {
+                                    range: {
+                                        sheetId: 0,
+                                        startRowIndex: existingRowIndex - 1,
+                                        endRowIndex: existingRowIndex,
+                                        startColumnIndex: 0,
+                                        endColumnIndex: header.length
+                                    },
+                                    rows: [
+                                        {
+                                            values: row.map(function(cellValue) {
+                                                return {
+                                                    userEnteredValue: {
+                                                        stringValue: String(cellValue !== null && cellValue !== void 0 ? cellValue : '')
+                                                    }
+                                                };
+                                            })
+                                        }
+                                    ],
+                                    fields: 'userEnteredValue'
+                                }
+                            });
+                        }
+                    } catch (err) {
+                        _didIteratorError = true;
+                        _iteratorError = err;
+                    } finally{
+                        try {
+                            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                                _iterator.return();
+                            }
+                        } finally{
+                            if (_didIteratorError) {
+                                throw _iteratorError;
+                            }
+                        }
+                    }
+                    if (!(requests.length > 0)) return [
+                        3,
+                        4
+                    ];
+                    return [
+                        4,
+                        sheets.spreadsheets.batchUpdate({
+                            spreadsheetId: spreadsheetId,
+                            requestBody: {
+                                requests: requests
+                            }
+                        })
+                    ];
+                case 3:
+                    _state.sent();
+                    totalUpdated += batch.length;
+                    _state.label = 4;
+                case 4:
+                    return [
+                        3,
+                        16
+                    ];
+                case 5:
+                    error = _state.sent();
+                    errorMsg = "Batch update ".concat(Math.floor(i / batchSize) + 1, " failed: ").concat(_instanceof(error, Error) ? error.message : String(error));
+                    errors.push(errorMsg);
+                    _iteratorNormalCompletion1 = true, _didIteratorError1 = false, _iteratorError1 = undefined;
+                    _state.label = 6;
+                case 6:
+                    _state.trys.push([
+                        6,
+                        13,
+                        14,
+                        15
+                    ]);
+                    _iterator1 = batch[Symbol.iterator]();
+                    _state.label = 7;
+                case 7:
+                    if (!!(_iteratorNormalCompletion1 = (_step1 = _iterator1.next()).done)) return [
+                        3,
+                        12
+                    ];
+                    _step_value1 = _step1.value, row1 = _step_value1.row, existingRowIndex1 = _step_value1.existingRowIndex;
+                    _state.label = 8;
+                case 8:
+                    _state.trys.push([
+                        8,
+                        10,
+                        ,
+                        11
+                    ]);
+                    range = "".concat(sheetTitle, "!A").concat(existingRowIndex1, ":").concat((0, _columnutilities.a1Col)(header.length)).concat(existingRowIndex1);
+                    return [
+                        4,
+                        sheets.spreadsheets.values.update({
+                            spreadsheetId: spreadsheetId,
+                            range: range,
+                            valueInputOption: valueInputOption,
+                            requestBody: {
+                                values: [
+                                    row1
+                                ]
+                            }
+                        })
+                    ];
+                case 9:
+                    _state.sent();
+                    totalUpdated += 1;
+                    return [
+                        3,
+                        11
+                    ];
+                case 10:
+                    singleError = _state.sent();
+                    errors.push("Failed to update row ".concat(existingRowIndex1, ": ").concat(_instanceof(singleError, Error) ? singleError.message : String(singleError)));
+                    return [
+                        3,
+                        11
+                    ];
+                case 11:
+                    _iteratorNormalCompletion1 = true;
+                    return [
+                        3,
+                        7
+                    ];
+                case 12:
+                    return [
+                        3,
+                        15
+                    ];
+                case 13:
+                    err = _state.sent();
+                    _didIteratorError1 = true;
+                    _iteratorError1 = err;
+                    return [
+                        3,
+                        15
+                    ];
+                case 14:
+                    try {
+                        if (!_iteratorNormalCompletion1 && _iterator1.return != null) {
+                            _iterator1.return();
+                        }
+                    } finally{
+                        if (_didIteratorError1) {
+                            throw _iteratorError1;
+                        }
+                    }
+                    return [
+                        7
+                    ];
+                case 15:
+                    return [
+                        3,
+                        16
+                    ];
+                case 16:
+                    i += batchSize;
+                    return [
+                        3,
+                        1
+                    ];
+                case 17:
+                    result = {
+                        updatedRows: totalUpdated
+                    };
+                    if (errors.length > 0) {
+                        result.errors = errors;
+                    }
+                    return [
+                        2,
+                        result
+                    ];
+            }
+        });
+    })();
+}
+function upsertByKey(_0, _1) {
+    return _async_to_generator(function(sheets, param) {
+        var spreadsheetId, sheetTitle, sheetRef, rows, canonicalHeaders, options, logger, resolvedSheetTitle, _sheet_properties, sheet, inputValidation, currentHeader, effectiveHeader, headerValidation, _ref, existingKeys, keyToRowMap, processedRows, partition, batchSize, errors, totalUpdated, insertedKeys, i, batch, _response_data_updates, _response_data, response, updatedRows, error, errorMsg, updateResult, _errors, updateError, errorMsg1, result;
+        return _ts_generator(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    spreadsheetId = param.spreadsheetId, sheetTitle = param.sheetTitle, sheetRef = param.sheetRef, rows = param.rows, canonicalHeaders = param.canonicalHeaders, options = param.options, logger = param.logger;
+                    // Validate inputs
+                    if (!sheets) throw new Error('upsertByKey: sheets client is required');
+                    if (!spreadsheetId) throw new Error('upsertByKey: spreadsheetId is required');
+                    if (!sheetTitle && !sheetRef) throw new Error('upsertByKey: either sheetTitle or sheetRef is required');
+                    if (!Array.isArray(rows) || rows.length === 0) {
+                        return [
+                            2,
+                            {
+                                updatedRows: 0,
+                                inserted: [],
+                                rowsSkipped: 0
+                            }
+                        ];
+                    }
+                    // Step 1: Input validation (duplicate key checking)
+                    resolvedSheetTitle = sheetTitle;
+                    if (!sheetRef) return [
+                        3,
+                        2
+                    ];
+                    return [
+                        4,
+                        (0, _sheetoperations.findSheetByRef)(sheets, spreadsheetId, sheetRef, logger)
+                    ];
+                case 1:
+                    sheet = _state.sent();
+                    resolvedSheetTitle = (sheet === null || sheet === void 0 ? void 0 : (_sheet_properties = sheet.properties) === null || _sheet_properties === void 0 ? void 0 : _sheet_properties.title) || sheetRef;
+                    _state.label = 2;
+                case 2:
+                    if (!resolvedSheetTitle) {
+                        throw new Error('upsertByKey: could not resolve sheet title');
+                    }
+                    // Validate for duplicate keys in input data
+                    inputValidation = validateRowKeys(rows, canonicalHeaders || [], options.keyStrategy);
+                    if (!inputValidation.valid) {
+                        throw new Error("upsertByKey: duplicate keys found in input data: ".concat(inputValidation.duplicateKeys.join(', ')));
+                    }
+                    return [
+                        4,
+                        discoverHeader(sheets, spreadsheetId, resolvedSheetTitle)
+                    ];
+                case 3:
+                    currentHeader = _state.sent();
+                    effectiveHeader = currentHeader;
+                    if (!(currentHeader.length === 0 && canonicalHeaders && canonicalHeaders.length > 0)) return [
+                        3,
+                        5
+                    ];
+                    effectiveHeader = canonicalHeaders;
+                    // Write headers to sheet
+                    return [
+                        4,
+                        sheets.spreadsheets.values.append({
+                            spreadsheetId: spreadsheetId,
+                            range: "".concat(resolvedSheetTitle, "!A1"),
+                            valueInputOption: options.valueInputOption || 'USER_ENTERED',
+                            insertDataOption: 'INSERT_ROWS',
+                            requestBody: {
+                                values: [
+                                    effectiveHeader
+                                ]
+                            }
+                        })
+                    ];
+                case 4:
+                    _state.sent();
+                    _state.label = 5;
+                case 5:
+                    // Validate headers if we have requirements
+                    if (canonicalHeaders && canonicalHeaders.length > 0) {
+                        headerValidation = validateAndMapHeaders(effectiveHeader, canonicalHeaders);
+                        if (!headerValidation.valid) {
+                            throw new Error("upsertByKey: missing required columns: ".concat(headerValidation.missingColumns.join(', ')));
+                        }
+                    }
+                    return [
+                        4,
+                        snapshotHeaderKeysAndPositions(sheets, spreadsheetId, resolvedSheetTitle, options.keyStrategy.keyColumns, options.keyStrategy)
+                    ];
+                case 6:
+                    _ref = _state.sent(), existingKeys = _ref.keySet, keyToRowMap = _ref.keyToRowMap;
+                    // Step 4: Partition changes (updates vs appends)
+                    processedRows = rows;
+                    // Map canonical data to sheet structure if needed
+                    if (canonicalHeaders && canonicalHeaders.length > 0 && effectiveHeader.length > 0) {
+                        processedRows = mapRowsToHeader({
+                            rows: rows,
+                            header: effectiveHeader,
+                            canonical: canonicalHeaders
+                        });
+                    }
+                    partition = partitionDataForUpsert(processedRows, effectiveHeader, options.keyStrategy, existingKeys, options.allowUpdates, keyToRowMap);
+                    // Step 5: Efficient batch writing
+                    batchSize = options.batchSize || 50;
+                    errors = [];
+                    totalUpdated = 0;
+                    insertedKeys = [];
+                    if (!(partition.toAppend.length > 0)) return [
+                        3,
+                        12
+                    ];
+                    i = 0;
+                    _state.label = 7;
+                case 7:
+                    if (!(i < partition.toAppend.length)) return [
+                        3,
+                        12
+                    ];
+                    batch = partition.toAppend.slice(i, i + batchSize);
+                    _state.label = 8;
+                case 8:
+                    _state.trys.push([
+                        8,
+                        10,
+                        ,
+                        11
+                    ]);
+                    return [
+                        4,
+                        sheets.spreadsheets.values.append({
+                            spreadsheetId: spreadsheetId,
+                            range: "".concat(resolvedSheetTitle, "!A1"),
+                            valueInputOption: options.valueInputOption || 'USER_ENTERED',
+                            insertDataOption: 'INSERT_ROWS',
+                            requestBody: {
+                                values: batch
+                            }
+                        })
+                    ];
+                case 9:
+                    response = _state.sent();
+                    updatedRows = Number(((_response_data = response.data) === null || _response_data === void 0 ? void 0 : (_response_data_updates = _response_data.updates) === null || _response_data_updates === void 0 ? void 0 : _response_data_updates.updatedRows) || batch.length);
+                    totalUpdated += updatedRows;
+                    // Track inserted keys for successful batch
+                    batch.forEach(function(row) {
+                        var key = generateRowKey(row, effectiveHeader, options.keyStrategy);
+                        if (key.replace(/\\+/g, '') !== '') {
+                            insertedKeys.push(key);
+                        }
+                    });
+                    return [
+                        3,
+                        11
+                    ];
+                case 10:
+                    error = _state.sent();
+                    errorMsg = "Batch ".concat(Math.floor(i / batchSize) + 1, " append failed: ").concat(_instanceof(error, Error) ? error.message : String(error));
+                    errors.push(errorMsg);
+                    return [
+                        3,
+                        11
+                    ];
+                case 11:
+                    i += batchSize;
+                    return [
+                        3,
+                        7
+                    ];
+                case 12:
+                    if (!(partition.toUpdate.length > 0 && options.allowUpdates)) return [
+                        3,
+                        16
+                    ];
+                    _state.label = 13;
+                case 13:
+                    _state.trys.push([
+                        13,
+                        15,
+                        ,
+                        16
+                    ]);
+                    return [
+                        4,
+                        performBatchUpdates(sheets, spreadsheetId, resolvedSheetTitle, partition.toUpdate, effectiveHeader, batchSize, options.valueInputOption || 'USER_ENTERED')
+                    ];
+                case 14:
+                    updateResult = _state.sent();
+                    totalUpdated += updateResult.updatedRows;
+                    if (updateResult.errors) {
+                        ;
+                        (_errors = errors).push.apply(_errors, _to_consumable_array(updateResult.errors));
+                    }
+                    return [
+                        3,
+                        16
+                    ];
+                case 15:
+                    updateError = _state.sent();
+                    errorMsg1 = "Update operations failed: ".concat(_instanceof(updateError, Error) ? updateError.message : String(updateError));
+                    errors.push(errorMsg1);
+                    return [
+                        3,
+                        16
+                    ];
+                case 16:
+                    result = {
+                        updatedRows: totalUpdated,
+                        inserted: insertedKeys,
+                        rowsSkipped: partition.skippedKeys.length
+                    };
+                    if (errors.length > 0) {
+                        result.errors = errors;
+                    }
+                    return [
+                        2,
+                        result
+                    ];
+            }
+        });
+    }).apply(this, arguments);
+}
+/* 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; }