@mcp-z/mcp-sheets 1.0.0

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

@@ -0,0 +1,712 @@
+import { a1Col } from './column-utilities.js';
+import { findSheetByRef } from './sheet-operations.js';
+export async function discoverHeader(sheets, spreadsheetId, sheetTitle) {
+    try {
+        var _response_data;
+        const response = await sheets.spreadsheets.values.get({
+            spreadsheetId,
+            range: `${sheetTitle}!1:1`,
+            majorDimension: 'ROWS'
+        });
+        return (((_response_data = response.data) === null || _response_data === void 0 ? void 0 : _response_data.values) || [])[0] || [];
+    } catch  {
+        return [];
+    }
+}
+export function validateAndMapHeaders(sheetHeaders, canonicalHeaders, requiredColumns = []) {
+    const normalizeColumn = (col)=>String(col !== null && col !== void 0 ? col : '').toLowerCase().replace(/[^a-z0-9]/g, '');
+    const sheetNormalized = sheetHeaders.map(normalizeColumn);
+    const canonicalNormalized = canonicalHeaders.map(normalizeColumn);
+    const requiredNormalized = requiredColumns.map(normalizeColumn);
+    const mappings = [];
+    const missingColumns = [];
+    const extraColumns = [
+        ...sheetHeaders
+    ];
+    // Create mappings for canonical columns
+    canonicalHeaders.forEach((canonical, canonicalIndex)=>{
+        const canonicalNorm = canonicalNormalized[canonicalIndex];
+        if (!canonicalNorm) return; // Skip if normalization resulted in empty string
+        let sheetIndex = sheetNormalized.indexOf(canonicalNorm);
+        // Special handling for 'id' -> 'messageid' mapping
+        if (sheetIndex === -1 && canonicalNorm === 'id') {
+            sheetIndex = sheetNormalized.indexOf('messageid');
+        }
+        if (sheetIndex !== -1) {
+            const sheetHeader = sheetHeaders[sheetIndex];
+            if (sheetHeader !== undefined) {
+                mappings.push({
+                    canonical,
+                    sheet: sheetHeader,
+                    index: sheetIndex
+                });
+                // Remove from extra columns
+                const 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,
+        extraColumns,
+        mappings
+    };
+}
+/** Ensures consistent key generation across all functions */ export function generateRowKey(row, header, strategy) {
+    const { keyColumns, useProviderIdLogic, separator = '\\' } = strategy;
+    // Normalize header for consistent lookups
+    const lowerHeader = header.map((h)=>String(h !== null && h !== void 0 ? h : '').toLowerCase());
+    if (useProviderIdLogic) {
+        const providerIndex = lowerHeader.indexOf('provider');
+        let idIndex = lowerHeader.indexOf('messageid');
+        if (idIndex === -1) idIndex = lowerHeader.indexOf('id');
+        if (providerIndex >= 0 && idIndex >= 0) {
+            var _row_providerIndex, _row_idIndex;
+            const providerVal = String((_row_providerIndex = row[providerIndex]) !== null && _row_providerIndex !== void 0 ? _row_providerIndex : '').trim();
+            const 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
+    const keyIndices = keyColumns.map((name)=>{
+        const normalizedName = String(name !== null && name !== void 0 ? name : '').toLowerCase();
+        let index = lowerHeader.indexOf(normalizedName);
+        // Consistent fallback: id -> messageid
+        if (index === -1 && normalizedName === 'id') {
+            index = lowerHeader.indexOf('messageid');
+        }
+        return index;
+    }).filter((index)=>index >= 0);
+    if (keyIndices.length === 0) {
+        return ''; // Return empty string for invalid key configurations
+    }
+    const components = keyIndices.map((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((comp)=>comp.length > 0)) {
+        return components.join(separator);
+    }
+    return '';
+}
+export function validateRowKeys(rows, header, strategy) {
+    const keyMap = new Map();
+    const duplicateKeys = [];
+    rows.forEach((row, index)=>{
+        var _keyMap_get;
+        const 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((indices, key)=>{
+        if (indices.length > 1) {
+            duplicateKeys.push(key);
+        }
+    });
+    return {
+        valid: duplicateKeys.length === 0,
+        duplicateKeys,
+        keyMap
+    };
+}
+export async function appendRows(sheets, { spreadsheetId, sheetTitle, sheetRef, rows = [], keySet = null, keyColumns = [
+    'id'
+], header = [], 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
+    let resolvedSheetTitle = sheetTitle;
+    if (sheetRef) {
+        const sheet = await findSheetByRef(sheets, spreadsheetId, sheetRef, logger);
+        if (sheet) {
+            var _sheet_properties;
+            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;
+        }
+    }
+    if (!resolvedSheetTitle) throw new Error('appendRows: could not resolve sheet title');
+    if (!Array.isArray(rows) || rows.length === 0) return {
+        updatedRows: 0,
+        inserted: []
+    };
+    if (!Array.isArray(header) || header.length === 0) {
+        const respHeader = await sheets.spreadsheets.values.get({
+            spreadsheetId,
+            range: `${resolvedSheetTitle}!1:1`,
+            majorDimension: 'ROWS'
+        });
+        const vr = respHeader.data;
+        header = ((vr === null || vr === void 0 ? void 0 : vr.values) || [])[0] || [];
+    }
+    const resolveKeyIndices = (kc, hdr)=>{
+        if (!Array.isArray(kc) || kc.length === 0) return [];
+        for (const c of kc){
+            if (typeof c !== 'string' || c.length === 0) throw new Error('appendRows: keyColumns must be an array of non-empty strings');
+        }
+        if (!Array.isArray(hdr) || hdr.length === 0) {
+            throw new Error('appendRows: header array is required when keyColumns are header names');
+        }
+        return kc.map((name)=>{
+            const idx = hdr.indexOf(name);
+            if (idx === -1) throw new Error(`appendRows: header name "${name}" not found in header`);
+            return idx;
+        });
+    };
+    const keyColsIdx = resolveKeyIndices(keyColumns, header);
+    // Internal batch size to avoid Google Sheets limits
+    const batchSize = 50;
+    if (!keyColsIdx || keyColsIdx.length === 0) {
+        let totalUpdated = 0;
+        for(let i = 0; i < rows.length; i += batchSize){
+            var _app_updates;
+            const batch = rows.slice(i, i + batchSize);
+            const resp = await sheets.spreadsheets.values.append({
+                spreadsheetId,
+                range: `${resolvedSheetTitle}!A1`,
+                valueInputOption: 'RAW',
+                insertDataOption: 'INSERT_ROWS',
+                requestBody: {
+                    values: batch
+                }
+            });
+            const app = resp.data;
+            const 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;
+        }
+        return {
+            updatedRows: totalUpdated,
+            inserted: [],
+            rowsSkipped: 0
+        };
+    }
+    const toKey = (r)=>{
+        const row = r;
+        // Use consistent key generation strategy
+        const strategy = {
+            keyColumns,
+            useProviderIdLogic: true,
+            separator: '\\'
+        };
+        return generateRowKey(row, header, strategy);
+    };
+    const rowsToInsert = [];
+    const insertedKeys = [];
+    for (const r of rows){
+        const key = toKey(r);
+        if (keySet && keySet.has(key)) continue;
+        rowsToInsert.push(r);
+        insertedKeys.push(key);
+    }
+    if (rowsToInsert.length === 0) {
+        const rowsSkipped = rows.length - rowsToInsert.length; // Should be rows.length when all are skipped
+        return {
+            updatedRows: 0,
+            inserted: [],
+            rowsSkipped
+        };
+    }
+    // Use smaller internal batch size to avoid Google Sheets character limit errors
+    // Especially important when dealing with emails that may have long bodies
+    const INTERNAL_BATCH_SIZE = 50;
+    let totalUpdated = 0;
+    for(let i = 0; i < rowsToInsert.length; i += INTERNAL_BATCH_SIZE){
+        const batch = rowsToInsert.slice(i, i + INTERNAL_BATCH_SIZE);
+        try {
+            var _app2_updates;
+            const resp = await sheets.spreadsheets.values.append({
+                spreadsheetId,
+                range: `${resolvedSheetTitle}!A1`,
+                valueInputOption: 'RAW',
+                insertDataOption: 'INSERT_ROWS',
+                requestBody: {
+                    values: batch
+                }
+            });
+            const app2 = resp.data;
+            const updatedRows = Number((app2 === null || app2 === void 0 ? void 0 : (_app2_updates = app2.updates) === null || _app2_updates === void 0 ? void 0 : _app2_updates.updatedRows) || batch.length);
+            totalUpdated += updatedRows;
+        } catch (error) {
+            // If a batch fails, try with smaller batches to handle partial success
+            if (batch.length > 1) {
+                for (const singleRow of batch){
+                    try {
+                        var _singleApp_updates;
+                        const singleResp = await sheets.spreadsheets.values.append({
+                            spreadsheetId,
+                            range: `${resolvedSheetTitle}!A1`,
+                            valueInputOption: 'RAW',
+                            insertDataOption: 'INSERT_ROWS',
+                            requestBody: {
+                                values: [
+                                    singleRow
+                                ]
+                            }
+                        });
+                        const singleApp = singleResp.data;
+                        const singleUpdatedRows = Number((singleApp === null || singleApp === void 0 ? void 0 : (_singleApp_updates = singleApp.updates) === null || _singleApp_updates === void 0 ? void 0 : _singleApp_updates.updatedRows) || 1);
+                        totalUpdated += singleUpdatedRows;
+                    } catch (singleError) {
+                        var // Skip problematic individual rows but continue processing
+                        _logger_warn;
+                        (_logger_warn = logger.warn) === null || _logger_warn === void 0 ? void 0 : _logger_warn.call(logger, `Failed to insert single row: ${singleError instanceof Error ? singleError.message : String(singleError)}`);
+                    }
+                }
+            } else {
+                var // Single row batch failed, skip it
+                _logger_warn1;
+                (_logger_warn1 = logger.warn) === null || _logger_warn1 === void 0 ? void 0 : _logger_warn1.call(logger, `Failed to insert batch: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+    const rowsSkipped = rows.length - rowsToInsert.length;
+    return {
+        updatedRows: totalUpdated,
+        inserted: insertedKeys,
+        rowsSkipped
+    };
+}
+export function mapRowsToHeader({ rows = [], header = [], 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;
+    const validation = validateAndMapHeaders(header, canonical);
+    const mappingLookup = new Map(validation.mappings.map((m)=>[
+            m.canonical,
+            m.index
+        ]));
+    return rows.map((row)=>{
+        // Fill with null to skip unmapped columns (preserve existing values)
+        // Use '' (empty string) only when explicitly wanting to clear a cell
+        const mappedRow = new Array(header.length).fill(null);
+        canonical.forEach((canonicalCol, canonicalIndex)=>{
+            const sheetIndex = mappingLookup.get(canonicalCol);
+            if (sheetIndex !== undefined && canonicalIndex < row.length) {
+                // Preserve null values - they signal "skip this cell"
+                mappedRow[sheetIndex] = row[canonicalIndex];
+            }
+        });
+        return mappedRow;
+    });
+}
+export async function snapshotHeaderAndKeys(sheets, spreadsheetId, sheetTitle, keyColumns = [
+    'id'
+], keyStrategy) {
+    var _ref, _ref1;
+    const header = await discoverHeader(sheets, spreadsheetId, sheetTitle);
+    const keySet = new Set();
+    if (header.length === 0) {
+        return {
+            header,
+            keySet,
+            keyIndices: []
+        };
+    }
+    const strategy = {
+        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
+    const keyIndices = keyColumns.map((name)=>{
+        const normalizedName = String(name !== null && name !== void 0 ? name : '').toLowerCase();
+        const lowerHeader = header.map((h)=>String(h !== null && h !== void 0 ? h : '').toLowerCase());
+        let index = lowerHeader.indexOf(normalizedName);
+        if (index === -1 && normalizedName === 'id') {
+            index = lowerHeader.indexOf('messageid');
+        }
+        return index;
+    }).filter((index)=>index >= 0);
+    if (keyIndices.length === 0) {
+        return {
+            header,
+            keySet,
+            keyIndices
+        };
+    }
+    // Read key columns data in chunks
+    const chunkSize = 1000;
+    let startRow = 2;
+    const minIndex = Math.min(...keyIndices);
+    const maxIndex = Math.max(...keyIndices);
+    const startCol = a1Col(minIndex + 1);
+    const endCol = a1Col(maxIndex + 1);
+    while(true){
+        const endRow = startRow + chunkSize - 1;
+        const range = `${sheetTitle}!${startCol}${startRow}:${endCol}${endRow}`;
+        try {
+            var _response_data;
+            const response = await sheets.spreadsheets.values.get({
+                spreadsheetId,
+                range,
+                majorDimension: 'ROWS'
+            });
+            const rows = ((_response_data = response.data) === null || _response_data === void 0 ? void 0 : _response_data.values) || [];
+            if (rows.length === 0) break;
+            for (const rawRow of rows){
+                // Reconstruct full row for key generation
+                const fullRow = new Array(header.length).fill('');
+                keyIndices.forEach((globalIndex, _localIndex)=>{
+                    const localRowIndex = globalIndex - minIndex;
+                    if (localRowIndex >= 0 && localRowIndex < rawRow.length) {
+                        fullRow[globalIndex] = rawRow[localRowIndex];
+                    }
+                });
+                const key = generateRowKey(fullRow, header, strategy);
+                if (key.replace(/\\+/g, '') !== '') {
+                    keySet.add(key);
+                }
+            }
+            startRow += rows.length;
+            if (rows.length < chunkSize) break; // Last chunk
+        } catch  {
+            break; // End of data or error
+        }
+    }
+    return {
+        header,
+        keySet,
+        keyIndices
+    };
+}
+/** Tracks row positions for updates in addition to keys */ export async function snapshotHeaderKeysAndPositions(sheets, spreadsheetId, sheetTitle, keyColumns = [
+    'id'
+], keyStrategy) {
+    var _ref, _ref1;
+    const header = await discoverHeader(sheets, spreadsheetId, sheetTitle);
+    const keySet = new Set();
+    const keyToRowMap = new Map();
+    if (header.length === 0) {
+        return {
+            header,
+            keySet,
+            keyToRowMap,
+            keyIndices: []
+        };
+    }
+    const strategy = {
+        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
+    const keyIndices = keyColumns.map((name)=>{
+        const normalizedName = String(name !== null && name !== void 0 ? name : '').toLowerCase();
+        const lowerHeader = header.map((h)=>String(h !== null && h !== void 0 ? h : '').toLowerCase());
+        let index = lowerHeader.indexOf(normalizedName);
+        if (index === -1 && normalizedName === 'id') {
+            index = lowerHeader.indexOf('messageid');
+        }
+        return index;
+    }).filter((index)=>index >= 0);
+    if (keyIndices.length === 0) {
+        return {
+            header,
+            keySet,
+            keyToRowMap,
+            keyIndices
+        };
+    }
+    // Read key columns data in chunks and track row positions
+    const chunkSize = 1000;
+    let startRow = 2; // Start from row 2 (after header)
+    const minIndex = Math.min(...keyIndices);
+    const maxIndex = Math.max(...keyIndices);
+    const startCol = a1Col(minIndex + 1);
+    const endCol = a1Col(maxIndex + 1);
+    while(true){
+        const endRow = startRow + chunkSize - 1;
+        const range = `${sheetTitle}!${startCol}${startRow}:${endCol}${endRow}`;
+        try {
+            var _response_data;
+            const response = await sheets.spreadsheets.values.get({
+                spreadsheetId,
+                range,
+                majorDimension: 'ROWS'
+            });
+            const rows = ((_response_data = response.data) === null || _response_data === void 0 ? void 0 : _response_data.values) || [];
+            if (rows.length === 0) break;
+            for(let localRowIndex = 0; localRowIndex < rows.length; localRowIndex++){
+                const rawRow = rows[localRowIndex];
+                const globalRowNumber = startRow + localRowIndex;
+                // Reconstruct full row for key generation
+                const fullRow = new Array(header.length).fill('');
+                if (rawRow) {
+                    keyIndices.forEach((globalIndex, _localIndex)=>{
+                        const localRowArrayIndex = globalIndex - minIndex;
+                        if (localRowArrayIndex >= 0 && localRowArrayIndex < rawRow.length) {
+                            fullRow[globalIndex] = rawRow[localRowArrayIndex];
+                        }
+                    });
+                }
+                const key = generateRowKey(fullRow, header, strategy);
+                if (key.replace(/\\+/g, '') !== '') {
+                    keySet.add(key);
+                    keyToRowMap.set(key, globalRowNumber); // Store 1-indexed row number
+                }
+            }
+            startRow += rows.length;
+            if (rows.length < chunkSize) break; // Last chunk
+        } catch  {
+            break; // End of data or error
+        }
+    }
+    return {
+        header,
+        keySet,
+        keyToRowMap,
+        keyIndices
+    };
+}
+/**
+ * Partitions data into updates vs appends based on existing keys with row position tracking
+ */ export function partitionDataForUpsert(rows, header, keyStrategy, existingKeys, allowUpdates = false, keyToRowMap) {
+    const toAppend = [];
+    const toUpdate = [];
+    const skippedKeys = [];
+    rows.forEach((row)=>{
+        const key = generateRowKey(row, header, keyStrategy);
+        if (key.replace(/\\+/g, '') === '') {
+            // Skip rows with empty keys
+            return;
+        }
+        if (existingKeys.has(key)) {
+            if (allowUpdates && keyToRowMap) {
+                const existingRowIndex = keyToRowMap.get(key);
+                if (existingRowIndex !== undefined) {
+                    toUpdate.push({
+                        row,
+                        existingRowIndex
+                    });
+                } else {
+                    skippedKeys.push(key);
+                }
+            } else {
+                skippedKeys.push(key);
+            }
+        } else {
+            toAppend.push(row);
+        }
+    });
+    return {
+        toAppend,
+        toUpdate,
+        skippedKeys
+    };
+}
+/**
+ * Performs batch updates on existing rows using batchUpdate API
+ */ export async function performBatchUpdates(sheets, spreadsheetId, sheetTitle, updates, header, batchSize, valueInputOption) {
+    const errors = [];
+    let totalUpdated = 0;
+    // Process updates in batches
+    for(let i = 0; i < updates.length; i += batchSize){
+        const batch = updates.slice(i, i + batchSize);
+        try {
+            const requests = [];
+            for (const { row, existingRowIndex } of batch){
+                requests.push({
+                    updateCells: {
+                        range: {
+                            sheetId: 0,
+                            startRowIndex: existingRowIndex - 1,
+                            endRowIndex: existingRowIndex,
+                            startColumnIndex: 0,
+                            endColumnIndex: header.length
+                        },
+                        rows: [
+                            {
+                                values: row.map((cellValue)=>({
+                                        userEnteredValue: {
+                                            stringValue: String(cellValue !== null && cellValue !== void 0 ? cellValue : '')
+                                        }
+                                    }))
+                            }
+                        ],
+                        fields: 'userEnteredValue'
+                    }
+                });
+            }
+            if (requests.length > 0) {
+                await sheets.spreadsheets.batchUpdate({
+                    spreadsheetId,
+                    requestBody: {
+                        requests
+                    }
+                });
+                totalUpdated += batch.length;
+            }
+        } catch (error) {
+            const errorMsg = `Batch update ${Math.floor(i / batchSize) + 1} failed: ${error instanceof Error ? error.message : String(error)}`;
+            errors.push(errorMsg);
+            // Try individual updates for failed batches
+            for (const { row, existingRowIndex } of batch){
+                try {
+                    const range = `${sheetTitle}!A${existingRowIndex}:${a1Col(header.length)}${existingRowIndex}`;
+                    await sheets.spreadsheets.values.update({
+                        spreadsheetId,
+                        range,
+                        valueInputOption,
+                        requestBody: {
+                            values: [
+                                row
+                            ]
+                        }
+                    });
+                    totalUpdated += 1;
+                } catch (singleError) {
+                    errors.push(`Failed to update row ${existingRowIndex}: ${singleError instanceof Error ? singleError.message : String(singleError)}`);
+                }
+            }
+        }
+    }
+    const result = {
+        updatedRows: totalUpdated
+    };
+    if (errors.length > 0) {
+        result.errors = errors;
+    }
+    return result;
+}
+export async function upsertByKey(sheets, { spreadsheetId, sheetTitle, sheetRef, rows, canonicalHeaders, options, 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 {
+            updatedRows: 0,
+            inserted: [],
+            rowsSkipped: 0
+        };
+    }
+    // Step 1: Input validation (duplicate key checking)
+    let resolvedSheetTitle = sheetTitle;
+    if (sheetRef) {
+        var _sheet_properties;
+        const sheet = await findSheetByRef(sheets, spreadsheetId, sheetRef, logger);
+        resolvedSheetTitle = (sheet === null || sheet === void 0 ? void 0 : (_sheet_properties = sheet.properties) === null || _sheet_properties === void 0 ? void 0 : _sheet_properties.title) || sheetRef;
+    }
+    if (!resolvedSheetTitle) {
+        throw new Error('upsertByKey: could not resolve sheet title');
+    }
+    // Validate for duplicate keys in input data
+    const inputValidation = validateRowKeys(rows, canonicalHeaders || [], options.keyStrategy);
+    if (!inputValidation.valid) {
+        throw new Error(`upsertByKey: duplicate keys found in input data: ${inputValidation.duplicateKeys.join(', ')}`);
+    }
+    // Step 2: Header discovery and column mapping
+    const currentHeader = await discoverHeader(sheets, spreadsheetId, resolvedSheetTitle);
+    let effectiveHeader = currentHeader;
+    // If sheet is empty and we have canonical headers, use them
+    if (currentHeader.length === 0 && canonicalHeaders && canonicalHeaders.length > 0) {
+        effectiveHeader = canonicalHeaders;
+        // Write headers to sheet
+        await sheets.spreadsheets.values.append({
+            spreadsheetId,
+            range: `${resolvedSheetTitle}!A1`,
+            valueInputOption: options.valueInputOption || 'USER_ENTERED',
+            insertDataOption: 'INSERT_ROWS',
+            requestBody: {
+                values: [
+                    effectiveHeader
+                ]
+            }
+        });
+    }
+    // Validate headers if we have requirements
+    if (canonicalHeaders && canonicalHeaders.length > 0) {
+        const headerValidation = validateAndMapHeaders(effectiveHeader, canonicalHeaders);
+        if (!headerValidation.valid) {
+            throw new Error(`upsertByKey: missing required columns: ${headerValidation.missingColumns.join(', ')}`);
+        }
+    }
+    // Step 3: Key column reading for existing row lookup with position tracking
+    const { keySet: existingKeys, keyToRowMap } = await snapshotHeaderKeysAndPositions(sheets, spreadsheetId, resolvedSheetTitle, options.keyStrategy.keyColumns, options.keyStrategy);
+    // Step 4: Partition changes (updates vs appends)
+    let processedRows = rows;
+    // Map canonical data to sheet structure if needed
+    if (canonicalHeaders && canonicalHeaders.length > 0 && effectiveHeader.length > 0) {
+        processedRows = mapRowsToHeader({
+            rows,
+            header: effectiveHeader,
+            canonical: canonicalHeaders
+        });
+    }
+    const partition = partitionDataForUpsert(processedRows, effectiveHeader, options.keyStrategy, existingKeys, options.allowUpdates, keyToRowMap);
+    // Step 5: Efficient batch writing
+    const batchSize = options.batchSize || 50;
+    const errors = [];
+    let totalUpdated = 0;
+    const insertedKeys = [];
+    // Handle appends with proper error handling and partial success tracking
+    if (partition.toAppend.length > 0) {
+        for(let i = 0; i < partition.toAppend.length; i += batchSize){
+            const batch = partition.toAppend.slice(i, i + batchSize);
+            try {
+                var _response_data_updates, _response_data;
+                const response = await sheets.spreadsheets.values.append({
+                    spreadsheetId,
+                    range: `${resolvedSheetTitle}!A1`,
+                    valueInputOption: options.valueInputOption || 'USER_ENTERED',
+                    insertDataOption: 'INSERT_ROWS',
+                    requestBody: {
+                        values: batch
+                    }
+                });
+                const 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((row)=>{
+                    const key = generateRowKey(row, effectiveHeader, options.keyStrategy);
+                    if (key.replace(/\\+/g, '') !== '') {
+                        insertedKeys.push(key);
+                    }
+                });
+            } catch (error) {
+                const errorMsg = `Batch ${Math.floor(i / batchSize) + 1} append failed: ${error instanceof Error ? error.message : String(error)}`;
+                errors.push(errorMsg);
+            }
+        }
+    }
+    // Handle updates with proper row position tracking
+    if (partition.toUpdate.length > 0 && options.allowUpdates) {
+        try {
+            const updateResult = await performBatchUpdates(sheets, spreadsheetId, resolvedSheetTitle, partition.toUpdate, effectiveHeader, batchSize, options.valueInputOption || 'USER_ENTERED');
+            totalUpdated += updateResult.updatedRows;
+            if (updateResult.errors) {
+                errors.push(...updateResult.errors);
+            }
+        } catch (updateError) {
+            const errorMsg = `Update operations failed: ${updateError instanceof Error ? updateError.message : String(updateError)}`;
+            errors.push(errorMsg);
+        }
+    }
+    const result = {
+        updatedRows: totalUpdated,
+        inserted: insertedKeys,
+        rowsSkipped: partition.skippedKeys.length
+    };
+    if (errors.length > 0) {
+        result.errors = errors;
+    }
+    return result;
+}