@mcp-z/mcp-sheets 1.0.0

package/dist/esm/spreadsheet/range-operations.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/servers/mcp-sheets/src/spreadsheet/range-operations.ts"],"sourcesContent":["/**\n * Range Operations Utilities for Google Sheets\n *\n * This module provides comprehensive utilities for working with A1 notation,\n * range parsing, batch operations, and range validation in Google Sheets.\n *\n * Key features:\n * - A1 notation validation and parsing\n * - Range manipulation and calculation utilities\n * - Batch operation builders for Google Sheets API\n * - Cell count and dimension calculations\n * - Range conflict detection for batch operations\n * - Google Sheets limits validation and enforcement\n */\n\nimport { a1Col } from './column-utilities.js';\n\n// Google Sheets constants and limits\nexport const GOOGLE_SHEETS_LIMITS = {\n  MAX_ROWS: 10_000_000,\n  MAX_COLUMNS: 18_278, // ZZZ in base-26\n  MAX_CELLS: 10_000_000, // Approximate limit for total cells\n  MAX_BATCH_REQUESTS: 1000,\n  MAX_DIMENSION_BATCH_REQUESTS: 100,\n} as const;\n\n/**\n * Represents a parsed cell reference (e.g., A1, B5)\n */\nexport interface CellReference {\n  column: string;\n  columnIndex: number; // 1-based\n  row: number; // 1-based\n}\n\n/**\n * Represents a parsed range (e.g., A1:B5, A:B, 1:2)\n */\nexport interface RangeReference {\n  type: 'cell' | 'row' | 'column' | 'range';\n  startCell?: CellReference;\n  endCell?: CellReference;\n  startRow?: number;\n  endRow?: number;\n  startColumn?: string;\n  endColumn?: string;\n  startColumnIndex?: number;\n  endColumnIndex?: number;\n}\n\n/**\n * Represents dimensions of a range\n */\nexport interface RangeDimensions {\n  rows: number;\n  columns: number;\n  cells: number;\n}\n\n/**\n * Represents a range conflict between two ranges\n */\nexport interface RangeConflict {\n  range1: string;\n  range2: string;\n  conflictType: 'overlap' | 'contains' | 'contained' | 'adjacent';\n  description: string;\n}\n\n/**\n * A1 Notation Validation Utilities\n */\n\n/**\n * Validates if a string is a valid A1 notation\n */\nexport function isValidA1Notation(notation: string): boolean {\n  if (!notation || typeof notation !== 'string') {\n    return false;\n  }\n\n  // Use the same regex pattern as in the schema\n  const a1Pattern = /^(?:[A-Z]{1,3}(?:[1-9]\\d{0,6}|10000000)(?::[A-Z]{1,3}(?:[1-9]\\d{0,6}|10000000))?|[A-Z]{1,3}:[A-Z]{1,3}|(?:[1-9]\\d{0,6}|10000000):(?:[1-9]\\d{0,6}|10000000))$/;\n\n  if (!a1Pattern.test(notation)) {\n    return false;\n  }\n\n  // Additional validation for Google Sheets limits\n  const parts = notation.split(':');\n\n  for (const part of parts) {\n    // Check cell reference\n    const cellMatch = part.match(/^([A-Z]{1,3})([1-9]\\d{0,6}|10000000)$/);\n    if (cellMatch && cellMatch[1] && cellMatch[2]) {\n      const [, colStr, rowStr] = cellMatch;\n\n      // Validate column\n      const colNum = columnStringToIndex(colStr);\n      if (colNum > GOOGLE_SHEETS_LIMITS.MAX_COLUMNS) {\n        return false;\n      }\n\n      // Validate row\n      const rowNum = parseInt(rowStr, 10);\n      if (rowNum > GOOGLE_SHEETS_LIMITS.MAX_ROWS) {\n        return false;\n      }\n    }\n\n    // Check column reference\n    const colMatch = part.match(/^([A-Z]{1,3})$/);\n    if (colMatch && colMatch[1]) {\n      const colNum = columnStringToIndex(colMatch[1]);\n      if (colNum > GOOGLE_SHEETS_LIMITS.MAX_COLUMNS) {\n        return false;\n      }\n    }\n\n    // Check row reference\n    const rowMatch = part.match(/^([1-9]\\d{0,6}|10000000)$/);\n    if (rowMatch && rowMatch[1]) {\n      const rowNum = parseInt(rowMatch[1], 10);\n      if (rowNum > GOOGLE_SHEETS_LIMITS.MAX_ROWS) {\n        return false;\n      }\n    }\n  }\n\n  return true;\n}\n\n/**\n * Validates A1 notation and throws detailed error if invalid\n */\nexport function validateA1Notation(notation: string): void {\n  if (!isValidA1Notation(notation)) {\n    throw new Error(`Invalid A1 notation: \"${notation}\". Valid formats: A1, A1:B2, A:B, 1:2`);\n  }\n}\n\n/**\n * Range Parsing and Manipulation Functions\n */\n\n/**\n * Converts column string (A, B, AA, etc.) to 1-based index\n */\nexport function columnStringToIndex(colStr: string): number {\n  let colNum = 0;\n  for (let i = 0; i < colStr.length; i++) {\n    colNum = colNum * 26 + (colStr.charCodeAt(i) - 64);\n  }\n  return colNum;\n}\n\n/**\n * Converts 1-based column index to column string (A, B, AA, etc.)\n */\nexport function columnIndexToString(colIndex: number): string {\n  return a1Col(colIndex);\n}\n\n/**\n * Parses a cell reference (e.g., \"A1\", \"Z999\") into its components\n */\nexport function parseCellReference(cellRef: string): CellReference {\n  const match = cellRef.match(/^([A-Z]{1,3})([1-9]\\d{0,6}|10000000)$/);\n  if (!match || !match[1] || !match[2]) {\n    throw new Error(`Invalid cell reference: ${cellRef}`);\n  }\n\n  const [, column, rowStr] = match;\n  const row = parseInt(rowStr, 10);\n  const columnIndex = columnStringToIndex(column);\n\n  return {\n    column,\n    columnIndex,\n    row,\n  };\n}\n\n/**\n * Parses A1 notation into a structured range reference\n */\nexport function parseA1Notation(notation: string): RangeReference {\n  validateA1Notation(notation);\n\n  const parts = notation.split(':');\n\n  if (parts.length === 1) {\n    const part = parts[0];\n    if (!part) {\n      throw new Error('Invalid A1 notation: empty part after split');\n    }\n\n    // Single cell reference (e.g., A1)\n    const cellMatch = part.match(/^([A-Z]{1,3})([1-9]\\d{0,6}|10000000)$/);\n    if (cellMatch && cellMatch[1] && cellMatch[2]) {\n      const startCell = parseCellReference(part);\n      return {\n        type: 'cell',\n        startCell,\n        endCell: startCell,\n      };\n    }\n\n    // Single column reference (e.g., A)\n    const colMatch = part.match(/^([A-Z]{1,3})$/);\n    if (colMatch && colMatch[1]) {\n      const column = colMatch[1];\n      const columnIndex = columnStringToIndex(column);\n      return {\n        type: 'column',\n        startColumn: column,\n        endColumn: column,\n        startColumnIndex: columnIndex,\n        endColumnIndex: columnIndex,\n      };\n    }\n\n    // Single row reference (e.g., 1)\n    const rowMatch = part.match(/^([1-9]\\d{0,6}|10000000)$/);\n    if (rowMatch && rowMatch[1]) {\n      const row = parseInt(rowMatch[1], 10);\n      return {\n        type: 'row',\n        startRow: row,\n        endRow: row,\n      };\n    }\n  }\n\n  if (parts.length === 2 && parts[0] && parts[1]) {\n    const [start, end] = parts;\n\n    // Cell range (e.g., A1:B5)\n    const startCellMatch = start.match(/^([A-Z]{1,3})([1-9]\\d{0,6}|10000000)$/);\n    const endCellMatch = end.match(/^([A-Z]{1,3})([1-9]\\d{0,6}|10000000)$/);\n\n    if (startCellMatch && endCellMatch && startCellMatch[1] && startCellMatch[2] && endCellMatch[1] && endCellMatch[2]) {\n      const startCell = parseCellReference(start);\n      const endCell = parseCellReference(end);\n      return {\n        type: 'range',\n        startCell,\n        endCell,\n      };\n    }\n\n    // Column range (e.g., A:B)\n    const startColMatch = start.match(/^([A-Z]{1,3})$/);\n    const endColMatch = end.match(/^([A-Z]{1,3})$/);\n\n    if (startColMatch && endColMatch && startColMatch[1] && endColMatch[1]) {\n      const startColumn = startColMatch[1];\n      const endColumn = endColMatch[1];\n      const startColumnIndex = columnStringToIndex(startColumn);\n      const endColumnIndex = columnStringToIndex(endColumn);\n      return {\n        type: 'column',\n        startColumn,\n        endColumn,\n        startColumnIndex,\n        endColumnIndex,\n      };\n    }\n\n    // Row range (e.g., 1:5)\n    const startRowMatch = start.match(/^([1-9]\\d{0,6}|10000000)$/);\n    const endRowMatch = end.match(/^([1-9]\\d{0,6}|10000000)$/);\n\n    if (startRowMatch && endRowMatch && startRowMatch[1] && endRowMatch[1]) {\n      const startRow = parseInt(startRowMatch[1], 10);\n      const endRow = parseInt(endRowMatch[1], 10);\n      return {\n        type: 'row',\n        startRow,\n        endRow,\n      };\n    }\n  }\n\n  throw new Error(`Unable to parse A1 notation: ${notation}`);\n}\n\n/**\n * Converts a range reference back to A1 notation\n */\nexport function rangeToA1Notation(range: RangeReference): string {\n  switch (range.type) {\n    case 'cell':\n      if (!range.startCell) throw new Error('Invalid cell range: missing startCell');\n      return `${range.startCell.column}${range.startCell.row}`;\n\n    case 'range':\n      if (!range.startCell || !range.endCell) throw new Error('Invalid range: missing start or end cell');\n      return `${range.startCell.column}${range.startCell.row}:${range.endCell.column}${range.endCell.row}`;\n\n    case 'column':\n      if (!range.startColumn || !range.endColumn) throw new Error('Invalid column range: missing start or end column');\n      if (range.startColumn === range.endColumn) {\n        return range.startColumn;\n      }\n      return `${range.startColumn}:${range.endColumn}`;\n\n    case 'row':\n      if (range.startRow === undefined || range.endRow === undefined) throw new Error('Invalid row range: missing start or end row');\n      if (range.startRow === range.endRow) {\n        return range.startRow.toString();\n      }\n      return `${range.startRow}:${range.endRow}`;\n\n    default:\n      throw new Error(`Unknown range type: ${(range as { type: unknown }).type}`);\n  }\n}\n\n/**\n * Cell Count and Dimension Calculation Utilities\n */\n\n/**\n * Calculates the dimensions of a range\n */\nexport function calculateRangeDimensions(notation: string): RangeDimensions {\n  const range = parseA1Notation(notation);\n\n  switch (range.type) {\n    case 'cell':\n      return { rows: 1, columns: 1, cells: 1 };\n\n    case 'range': {\n      if (!range.startCell || !range.endCell) throw new Error('Invalid range: missing cells');\n      const rows = range.endCell.row - range.startCell.row + 1;\n      const columns = range.endCell.columnIndex - range.startCell.columnIndex + 1;\n      return { rows, columns, cells: rows * columns };\n    }\n\n    case 'column': {\n      if (range.startColumnIndex === undefined || range.endColumnIndex === undefined) {\n        throw new Error('Invalid column range: missing column indices');\n      }\n      const columnCount = range.endColumnIndex - range.startColumnIndex + 1;\n      return {\n        rows: GOOGLE_SHEETS_LIMITS.MAX_ROWS,\n        columns: columnCount,\n        cells: GOOGLE_SHEETS_LIMITS.MAX_ROWS * columnCount,\n      };\n    }\n\n    case 'row': {\n      if (range.startRow === undefined || range.endRow === undefined) {\n        throw new Error('Invalid row range: missing row numbers');\n      }\n      const rowCount = range.endRow - range.startRow + 1;\n      return {\n        rows: rowCount,\n        columns: GOOGLE_SHEETS_LIMITS.MAX_COLUMNS,\n        cells: rowCount * GOOGLE_SHEETS_LIMITS.MAX_COLUMNS,\n      };\n    }\n\n    default:\n      throw new Error(`Unknown range type: ${(range as { type: string }).type}`);\n  }\n}\n\n/**\n * Calculates total cells affected by multiple ranges\n */\nexport function calculateTotalCells(ranges: string[]): number {\n  return ranges.reduce((total, range) => {\n    const dimensions = calculateRangeDimensions(range);\n    return total + dimensions.cells;\n  }, 0);\n}\n\n/**\n * Batch Operation Builders for Google API\n */\n\n/**\n * Builds a values batch update request for Google Sheets API\n */\nexport function buildValuesBatchUpdateRequest(\n  requests: Array<{\n    range: string;\n    values: (string | number | boolean | null | undefined)[][];\n    majorDimension?: 'ROWS' | 'COLUMNS';\n  }>,\n  sheetTitle: string,\n  options: {\n    valueInputOption?: 'RAW' | 'USER_ENTERED';\n    includeValuesInResponse?: boolean;\n    responseDateTimeRenderOption?: 'FORMATTED_STRING' | 'SERIAL_NUMBER';\n    responseValueRenderOption?: 'FORMATTED_VALUE' | 'UNFORMATTED_VALUE' | 'FORMULA';\n  } = {}\n) {\n  // Validate all ranges first\n  requests.forEach((req, index) => {\n    try {\n      validateA1Notation(req.range);\n    } catch (error) {\n      throw new Error(`Invalid range in request ${index}: ${error}`);\n    }\n  });\n\n  // Calculate total cells for validation\n  const totalCells = calculateTotalCells(requests.map((r) => r.range));\n  if (totalCells > GOOGLE_SHEETS_LIMITS.MAX_CELLS) {\n    throw new Error(`Batch update exceeds maximum cells limit: ${totalCells} > ${GOOGLE_SHEETS_LIMITS.MAX_CELLS}`);\n  }\n\n  // Build the request\n  const data = requests.map((req) => ({\n    range: `${sheetTitle}!${req.range}`,\n    values: req.values,\n    majorDimension: req.majorDimension || 'ROWS',\n  }));\n\n  return {\n    valueInputOption: options.valueInputOption || 'USER_ENTERED',\n    data,\n    includeValuesInResponse: options.includeValuesInResponse || false,\n    responseDateTimeRenderOption: options.responseDateTimeRenderOption || 'FORMATTED_STRING',\n    responseValueRenderOption: options.responseValueRenderOption || 'FORMATTED_VALUE',\n  };\n}\n\n/**\n * Range Conflict Detection\n */\n\n/**\n * Checks if two ranges overlap\n */\nexport function rangesOverlap(range1: string, range2: string): boolean {\n  try {\n    const parsed1 = parseA1Notation(range1);\n    const parsed2 = parseA1Notation(range2);\n\n    // Different types might still overlap, so we need to normalize to cell ranges\n    const normalized1 = normalizeRangeToBounds(parsed1);\n    const normalized2 = normalizeRangeToBounds(parsed2);\n\n    // Check for overlap\n    return !(normalized1.endRow < normalized2.startRow || normalized2.endRow < normalized1.startRow || normalized1.endCol < normalized2.startCol || normalized2.endCol < normalized1.startCol);\n  } catch {\n    // If we can't parse the ranges, assume no overlap\n    return false;\n  }\n}\n\n/**\n * Normalizes a range to bounds for overlap checking\n */\nfunction normalizeRangeToBounds(range: RangeReference): {\n  startRow: number;\n  endRow: number;\n  startCol: number;\n  endCol: number;\n} {\n  switch (range.type) {\n    case 'cell':\n      if (!range.startCell) throw new Error('Invalid cell range');\n      return {\n        startRow: range.startCell.row,\n        endRow: range.startCell.row,\n        startCol: range.startCell.columnIndex,\n        endCol: range.startCell.columnIndex,\n      };\n\n    case 'range':\n      if (!range.startCell || !range.endCell) throw new Error('Invalid range');\n      return {\n        startRow: range.startCell.row,\n        endRow: range.endCell.row,\n        startCol: range.startCell.columnIndex,\n        endCol: range.endCell.columnIndex,\n      };\n\n    case 'column':\n      if (range.startColumnIndex === undefined || range.endColumnIndex === undefined) {\n        throw new Error('Invalid column range');\n      }\n      return {\n        startRow: 1,\n        endRow: GOOGLE_SHEETS_LIMITS.MAX_ROWS,\n        startCol: range.startColumnIndex,\n        endCol: range.endColumnIndex,\n      };\n\n    case 'row':\n      if (range.startRow === undefined || range.endRow === undefined) {\n        throw new Error('Invalid row range');\n      }\n      return {\n        startRow: range.startRow,\n        endRow: range.endRow,\n        startCol: 1,\n        endCol: GOOGLE_SHEETS_LIMITS.MAX_COLUMNS,\n      };\n\n    default:\n      throw new Error(`Unknown range type: ${(range as { type: unknown }).type}`);\n  }\n}\n\n/**\n * Detects conflicts between multiple ranges\n */\nexport function detectRangeConflicts(ranges: string[]): RangeConflict[] {\n  const conflicts: RangeConflict[] = [];\n\n  for (let i = 0; i < ranges.length; i++) {\n    for (let j = i + 1; j < ranges.length; j++) {\n      const range1 = ranges[i];\n      const range2 = ranges[j];\n\n      if (!range1 || !range2) continue;\n\n      if (rangesOverlap(range1, range2)) {\n        conflicts.push({\n          range1,\n          range2,\n          conflictType: 'overlap',\n          description: `Ranges ${range1} and ${range2} overlap`,\n        });\n      }\n    }\n  }\n\n  return conflicts;\n}\n\n/**\n * Validates that a batch of ranges doesn't exceed Google Sheets limits\n */\nexport function validateBatchRanges(ranges: string[]): {\n  valid: boolean;\n  errors: string[];\n  warnings: string[];\n  totalCells: number;\n} {\n  const errors: string[] = [];\n  const warnings: string[] = [];\n  let totalCells = 0;\n\n  // Validate each range\n  ranges.forEach((range, index) => {\n    try {\n      validateA1Notation(range);\n      const dimensions = calculateRangeDimensions(range);\n      totalCells += dimensions.cells;\n\n      // Check for very large ranges that might cause performance issues\n      if (dimensions.cells > 1_000_000) {\n        warnings.push(`Range ${index + 1} (${range}) affects ${dimensions.cells.toLocaleString()} cells, which may impact performance`);\n      }\n    } catch (error) {\n      errors.push(`Range ${index + 1} (${range}): ${error}`);\n    }\n  });\n\n  // Check batch size limits\n  if (ranges.length > GOOGLE_SHEETS_LIMITS.MAX_BATCH_REQUESTS) {\n    errors.push(`Too many ranges: ${ranges.length} > ${GOOGLE_SHEETS_LIMITS.MAX_BATCH_REQUESTS}`);\n  }\n\n  // Check total cells limit\n  if (totalCells > GOOGLE_SHEETS_LIMITS.MAX_CELLS) {\n    errors.push(`Total cells exceed limit: ${totalCells.toLocaleString()} > ${GOOGLE_SHEETS_LIMITS.MAX_CELLS.toLocaleString()}`);\n  }\n\n  // Check for conflicts\n  const conflicts = detectRangeConflicts(ranges);\n  conflicts.forEach((conflict) => {\n    warnings.push(conflict.description);\n  });\n\n  return {\n    valid: errors.length === 0,\n    errors,\n    warnings,\n    totalCells,\n  };\n}\n\n/**\n * Utility Functions for Common Range Operations\n */\n\n/**\n * Expands a range by a specified number of rows and columns\n */\nexport function expandRange(notation: string, expandRows: number, expandCols: number): string {\n  const range = parseA1Notation(notation);\n\n  if (range.type === 'cell' && range.startCell) {\n    const newEndRow = Math.min(range.startCell.row + expandRows, GOOGLE_SHEETS_LIMITS.MAX_ROWS);\n    const newEndCol = Math.min(range.startCell.columnIndex + expandCols, GOOGLE_SHEETS_LIMITS.MAX_COLUMNS);\n    const newEndColStr = columnIndexToString(newEndCol);\n\n    if (expandRows === 0 && expandCols === 0) {\n      return notation;\n    }\n\n    return `${range.startCell.column}${range.startCell.row}:${newEndColStr}${newEndRow}`;\n  }\n\n  if (range.type === 'range' && range.startCell && range.endCell) {\n    const newEndRow = Math.min(range.endCell.row + expandRows, GOOGLE_SHEETS_LIMITS.MAX_ROWS);\n    const newEndCol = Math.min(range.endCell.columnIndex + expandCols, GOOGLE_SHEETS_LIMITS.MAX_COLUMNS);\n    const newEndColStr = columnIndexToString(newEndCol);\n\n    return `${range.startCell.column}${range.startCell.row}:${newEndColStr}${newEndRow}`;\n  }\n\n  // For row and column ranges, expansion doesn't make sense in the same way\n  return notation;\n}\n\n/**\n * Gets the intersection of two ranges\n */\nexport function getRangeIntersection(range1: string, range2: string): string | null {\n  try {\n    const parsed1 = parseA1Notation(range1);\n    const parsed2 = parseA1Notation(range2);\n\n    const bounds1 = normalizeRangeToBounds(parsed1);\n    const bounds2 = normalizeRangeToBounds(parsed2);\n\n    // Check if they overlap\n    if (!rangesOverlap(range1, range2)) {\n      return null;\n    }\n\n    // Calculate intersection bounds\n    const startRow = Math.max(bounds1.startRow, bounds2.startRow);\n    const endRow = Math.min(bounds1.endRow, bounds2.endRow);\n    const startCol = Math.max(bounds1.startCol, bounds2.startCol);\n    const endCol = Math.min(bounds1.endCol, bounds2.endCol);\n\n    const startColStr = columnIndexToString(startCol);\n    const endColStr = columnIndexToString(endCol);\n\n    if (startRow === endRow && startCol === endCol) {\n      return `${startColStr}${startRow}`;\n    }\n\n    return `${startColStr}${startRow}:${endColStr}${endRow}`;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Splits a large range into smaller chunks for batch processing\n */\nexport function splitRangeIntoChunks(notation: string, maxCellsPerChunk = 100_000): string[] {\n  const range = parseA1Notation(notation);\n  const dimensions = calculateRangeDimensions(notation);\n\n  if (dimensions.cells <= maxCellsPerChunk) {\n    return [notation];\n  }\n\n  const chunks: string[] = [];\n\n  if (range.type === 'range' && range.startCell && range.endCell) {\n    const totalRows = range.endCell.row - range.startCell.row + 1;\n    const totalCols = range.endCell.columnIndex - range.startCell.columnIndex + 1;\n\n    // Calculate chunk size based on max cells\n    const cellsPerRow = totalCols;\n    const maxRowsPerChunk = Math.floor(maxCellsPerChunk / cellsPerRow);\n\n    if (maxRowsPerChunk >= 1) {\n      // Split by rows\n      for (let currentRow = range.startCell.row; currentRow <= range.endCell.row; currentRow += maxRowsPerChunk) {\n        const chunkEndRow = Math.min(currentRow + maxRowsPerChunk - 1, range.endCell.row);\n        const chunkRange = `${range.startCell.column}${currentRow}:${range.endCell.column}${chunkEndRow}`;\n        chunks.push(chunkRange);\n      }\n    } else {\n      // If even one row is too big, split by columns\n      const maxColsPerChunk = Math.floor(maxCellsPerChunk / totalRows);\n\n      for (let currentCol = range.startCell.columnIndex; currentCol <= range.endCell.columnIndex; currentCol += maxColsPerChunk) {\n        const chunkEndCol = Math.min(currentCol + maxColsPerChunk - 1, range.endCell.columnIndex);\n        const startColStr = columnIndexToString(currentCol);\n        const endColStr = columnIndexToString(chunkEndCol);\n        const chunkRange = `${startColStr}${range.startCell.row}:${endColStr}${range.endCell.row}`;\n        chunks.push(chunkRange);\n      }\n    }\n  } else {\n    // For other range types, just return the original range\n    // (column and row ranges are already at their limits)\n    chunks.push(notation);\n  }\n\n  return chunks;\n}\n\n/**\n * Converts a RangeReference to Google Sheets API GridRange format\n *\n * This handles the different range types correctly:\n * - 'cell' and 'range' types: Extract indices from startCell/endCell\n * - 'row' types: Use startRow/endRow, omit column indices for full row\n * - 'column' types: Use startColumnIndex/endColumnIndex, omit row indices for full column\n *\n * Important: Google Sheets API uses 0-based indices, while A1 notation uses 1-based indices.\n * This function handles the conversion properly for each range type.\n */\nexport function rangeReferenceToGridRange(\n  rangeRef: RangeReference,\n  sheetId: number\n): {\n  sheetId: number;\n  startRowIndex?: number;\n  endRowIndex?: number;\n  startColumnIndex?: number;\n  endColumnIndex?: number;\n} {\n  if (rangeRef.type === 'cell' || rangeRef.type === 'range') {\n    // For cell and range types, extract from startCell/endCell\n    if (!rangeRef.startCell || !rangeRef.endCell) {\n      throw new Error(`Invalid ${rangeRef.type} range: missing start or end cell`);\n    }\n\n    return {\n      sheetId,\n      // Convert 1-based row to 0-based startRowIndex\n      startRowIndex: rangeRef.startCell.row - 1,\n      // endRowIndex is exclusive (so row 5 becomes endRowIndex 5)\n      endRowIndex: rangeRef.endCell.row,\n      // Convert 1-based column index to 0-based startColumnIndex\n      startColumnIndex: rangeRef.startCell.columnIndex - 1,\n      // endColumnIndex is exclusive\n      endColumnIndex: rangeRef.endCell.columnIndex,\n    };\n  }\n  if (rangeRef.type === 'row') {\n    // For row types, use startRow/endRow and omit column indices for full row width\n    if (rangeRef.startRow === undefined || rangeRef.endRow === undefined) {\n      throw new Error('Invalid row range: missing start or end row');\n    }\n\n    return {\n      sheetId,\n      // Convert 1-based row to 0-based startRowIndex\n      startRowIndex: rangeRef.startRow - 1,\n      // endRowIndex is exclusive\n      endRowIndex: rangeRef.endRow,\n      // Omit startColumnIndex and endColumnIndex to apply to all columns\n    };\n  }\n  if (rangeRef.type === 'column') {\n    // For column types, use startColumnIndex/endColumnIndex and omit row indices for full column height\n    if (rangeRef.startColumnIndex === undefined || rangeRef.endColumnIndex === undefined) {\n      throw new Error('Invalid column range: missing start or end column index');\n    }\n\n    return {\n      sheetId,\n      // Omit startRowIndex and endRowIndex to apply to all rows\n      // Convert 1-based column index to 0-based startColumnIndex\n      startColumnIndex: rangeRef.startColumnIndex - 1,\n      // endColumnIndex is exclusive\n      endColumnIndex: rangeRef.endColumnIndex,\n    };\n  }\n\n  throw new Error(`Unknown range type: ${(rangeRef as { type: unknown }).type}`);\n}\n"],"names":["a1Col","GOOGLE_SHEETS_LIMITS","MAX_ROWS","MAX_COLUMNS","MAX_CELLS","MAX_BATCH_REQUESTS","MAX_DIMENSION_BATCH_REQUESTS","isValidA1Notation","notation","a1Pattern","test","parts","split","part","cellMatch","match","colStr","rowStr","colNum","columnStringToIndex","rowNum","parseInt","colMatch","rowMatch","validateA1Notation","Error","i","length","charCodeAt","columnIndexToString","colIndex","parseCellReference","cellRef","column","row","columnIndex","parseA1Notation","startCell","type","endCell","startColumn","endColumn","startColumnIndex","endColumnIndex","startRow","endRow","start","end","startCellMatch","endCellMatch","startColMatch","endColMatch","startRowMatch","endRowMatch","rangeToA1Notation","range","undefined","toString","calculateRangeDimensions","rows","columns","cells","columnCount","rowCount","calculateTotalCells","ranges","reduce","total","dimensions","buildValuesBatchUpdateRequest","requests","sheetTitle","options","forEach","req","index","error","totalCells","map","r","data","values","majorDimension","valueInputOption","includeValuesInResponse","responseDateTimeRenderOption","responseValueRenderOption","rangesOverlap","range1","range2","parsed1","parsed2","normalized1","normalizeRangeToBounds","normalized2","endCol","startCol","detectRangeConflicts","conflicts","j","push","conflictType","description","validateBatchRanges","errors","warnings","toLocaleString","conflict","valid","expandRange","expandRows","expandCols","newEndRow","Math","min","newEndCol","newEndColStr","getRangeIntersection","bounds1","bounds2","max","startColStr","endColStr","splitRangeIntoChunks","maxCellsPerChunk","chunks","totalRows","totalCols","cellsPerRow","maxRowsPerChunk","floor","currentRow","chunkEndRow","chunkRange","maxColsPerChunk","currentCol","chunkEndCol","rangeReferenceToGridRange","rangeRef","sheetId","startRowIndex","endRowIndex"],"mappings":"AAAA;;;;;;;;;;;;;CAaC,GAED,SAASA,KAAK,QAAQ,wBAAwB;AAE9C,qCAAqC;AACrC,OAAO,MAAMC,uBAAuB;IAClCC,UAAU;IACVC,aAAa;IACbC,WAAW;IACXC,oBAAoB;IACpBC,8BAA8B;AAChC,EAAW;AA6CX;;CAEC,GAED;;CAEC,GACD,OAAO,SAASC,kBAAkBC,QAAgB;IAChD,IAAI,CAACA,YAAY,OAAOA,aAAa,UAAU;QAC7C,OAAO;IACT;IAEA,8CAA8C;IAC9C,MAAMC,YAAY;IAElB,IAAI,CAACA,UAAUC,IAAI,CAACF,WAAW;QAC7B,OAAO;IACT;IAEA,iDAAiD;IACjD,MAAMG,QAAQH,SAASI,KAAK,CAAC;IAE7B,KAAK,MAAMC,QAAQF,MAAO;QACxB,uBAAuB;QACvB,MAAMG,YAAYD,KAAKE,KAAK,CAAC;QAC7B,IAAID,aAAaA,SAAS,CAAC,EAAE,IAAIA,SAAS,CAAC,EAAE,EAAE;YAC7C,MAAM,GAAGE,QAAQC,OAAO,GAAGH;YAE3B,kBAAkB;YAClB,MAAMI,SAASC,oBAAoBH;YACnC,IAAIE,SAASjB,qBAAqBE,WAAW,EAAE;gBAC7C,OAAO;YACT;YAEA,eAAe;YACf,MAAMiB,SAASC,SAASJ,QAAQ;YAChC,IAAIG,SAASnB,qBAAqBC,QAAQ,EAAE;gBAC1C,OAAO;YACT;QACF;QAEA,yBAAyB;QACzB,MAAMoB,WAAWT,KAAKE,KAAK,CAAC;QAC5B,IAAIO,YAAYA,QAAQ,CAAC,EAAE,EAAE;YAC3B,MAAMJ,SAASC,oBAAoBG,QAAQ,CAAC,EAAE;YAC9C,IAAIJ,SAASjB,qBAAqBE,WAAW,EAAE;gBAC7C,OAAO;YACT;QACF;QAEA,sBAAsB;QACtB,MAAMoB,WAAWV,KAAKE,KAAK,CAAC;QAC5B,IAAIQ,YAAYA,QAAQ,CAAC,EAAE,EAAE;YAC3B,MAAMH,SAASC,SAASE,QAAQ,CAAC,EAAE,EAAE;YACrC,IAAIH,SAASnB,qBAAqBC,QAAQ,EAAE;gBAC1C,OAAO;YACT;QACF;IACF;IAEA,OAAO;AACT;AAEA;;CAEC,GACD,OAAO,SAASsB,mBAAmBhB,QAAgB;IACjD,IAAI,CAACD,kBAAkBC,WAAW;QAChC,MAAM,IAAIiB,MAAM,CAAC,sBAAsB,EAAEjB,SAAS,qCAAqC,CAAC;IAC1F;AACF;AAEA;;CAEC,GAED;;CAEC,GACD,OAAO,SAASW,oBAAoBH,MAAc;IAChD,IAAIE,SAAS;IACb,IAAK,IAAIQ,IAAI,GAAGA,IAAIV,OAAOW,MAAM,EAAED,IAAK;QACtCR,SAASA,SAAS,KAAMF,CAAAA,OAAOY,UAAU,CAACF,KAAK,EAAC;IAClD;IACA,OAAOR;AACT;AAEA;;CAEC,GACD,OAAO,SAASW,oBAAoBC,QAAgB;IAClD,OAAO9B,MAAM8B;AACf;AAEA;;CAEC,GACD,OAAO,SAASC,mBAAmBC,OAAe;IAChD,MAAMjB,QAAQiB,QAAQjB,KAAK,CAAC;IAC5B,IAAI,CAACA,SAAS,CAACA,KAAK,CAAC,EAAE,IAAI,CAACA,KAAK,CAAC,EAAE,EAAE;QACpC,MAAM,IAAIU,MAAM,CAAC,wBAAwB,EAAEO,SAAS;IACtD;IAEA,MAAM,GAAGC,QAAQhB,OAAO,GAAGF;IAC3B,MAAMmB,MAAMb,SAASJ,QAAQ;IAC7B,MAAMkB,cAAchB,oBAAoBc;IAExC,OAAO;QACLA;QACAE;QACAD;IACF;AACF;AAEA;;CAEC,GACD,OAAO,SAASE,gBAAgB5B,QAAgB;IAC9CgB,mBAAmBhB;IAEnB,MAAMG,QAAQH,SAASI,KAAK,CAAC;IAE7B,IAAID,MAAMgB,MAAM,KAAK,GAAG;QACtB,MAAMd,OAAOF,KAAK,CAAC,EAAE;QACrB,IAAI,CAACE,MAAM;YACT,MAAM,IAAIY,MAAM;QAClB;QAEA,mCAAmC;QACnC,MAAMX,YAAYD,KAAKE,KAAK,CAAC;QAC7B,IAAID,aAAaA,SAAS,CAAC,EAAE,IAAIA,SAAS,CAAC,EAAE,EAAE;YAC7C,MAAMuB,YAAYN,mBAAmBlB;YACrC,OAAO;gBACLyB,MAAM;gBACND;gBACAE,SAASF;YACX;QACF;QAEA,oCAAoC;QACpC,MAAMf,WAAWT,KAAKE,KAAK,CAAC;QAC5B,IAAIO,YAAYA,QAAQ,CAAC,EAAE,EAAE;YAC3B,MAAMW,SAASX,QAAQ,CAAC,EAAE;YAC1B,MAAMa,cAAchB,oBAAoBc;YACxC,OAAO;gBACLK,MAAM;gBACNE,aAAaP;gBACbQ,WAAWR;gBACXS,kBAAkBP;gBAClBQ,gBAAgBR;YAClB;QACF;QAEA,iCAAiC;QACjC,MAAMZ,WAAWV,KAAKE,KAAK,CAAC;QAC5B,IAAIQ,YAAYA,QAAQ,CAAC,EAAE,EAAE;YAC3B,MAAMW,MAAMb,SAASE,QAAQ,CAAC,EAAE,EAAE;YAClC,OAAO;gBACLe,MAAM;gBACNM,UAAUV;gBACVW,QAAQX;YACV;QACF;IACF;IAEA,IAAIvB,MAAMgB,MAAM,KAAK,KAAKhB,KAAK,CAAC,EAAE,IAAIA,KAAK,CAAC,EAAE,EAAE;QAC9C,MAAM,CAACmC,OAAOC,IAAI,GAAGpC;QAErB,2BAA2B;QAC3B,MAAMqC,iBAAiBF,MAAM/B,KAAK,CAAC;QACnC,MAAMkC,eAAeF,IAAIhC,KAAK,CAAC;QAE/B,IAAIiC,kBAAkBC,gBAAgBD,cAAc,CAAC,EAAE,IAAIA,cAAc,CAAC,EAAE,IAAIC,YAAY,CAAC,EAAE,IAAIA,YAAY,CAAC,EAAE,EAAE;YAClH,MAAMZ,YAAYN,mBAAmBe;YACrC,MAAMP,UAAUR,mBAAmBgB;YACnC,OAAO;gBACLT,MAAM;gBACND;gBACAE;YACF;QACF;QAEA,2BAA2B;QAC3B,MAAMW,gBAAgBJ,MAAM/B,KAAK,CAAC;QAClC,MAAMoC,cAAcJ,IAAIhC,KAAK,CAAC;QAE9B,IAAImC,iBAAiBC,eAAeD,aAAa,CAAC,EAAE,IAAIC,WAAW,CAAC,EAAE,EAAE;YACtE,MAAMX,cAAcU,aAAa,CAAC,EAAE;YACpC,MAAMT,YAAYU,WAAW,CAAC,EAAE;YAChC,MAAMT,mBAAmBvB,oBAAoBqB;YAC7C,MAAMG,iBAAiBxB,oBAAoBsB;YAC3C,OAAO;gBACLH,MAAM;gBACNE;gBACAC;gBACAC;gBACAC;YACF;QACF;QAEA,wBAAwB;QACxB,MAAMS,gBAAgBN,MAAM/B,KAAK,CAAC;QAClC,MAAMsC,cAAcN,IAAIhC,KAAK,CAAC;QAE9B,IAAIqC,iBAAiBC,eAAeD,aAAa,CAAC,EAAE,IAAIC,WAAW,CAAC,EAAE,EAAE;YACtE,MAAMT,WAAWvB,SAAS+B,aAAa,CAAC,EAAE,EAAE;YAC5C,MAAMP,SAASxB,SAASgC,WAAW,CAAC,EAAE,EAAE;YACxC,OAAO;gBACLf,MAAM;gBACNM;gBACAC;YACF;QACF;IACF;IAEA,MAAM,IAAIpB,MAAM,CAAC,6BAA6B,EAAEjB,UAAU;AAC5D;AAEA;;CAEC,GACD,OAAO,SAAS8C,kBAAkBC,KAAqB;IACrD,OAAQA,MAAMjB,IAAI;QAChB,KAAK;YACH,IAAI,CAACiB,MAAMlB,SAAS,EAAE,MAAM,IAAIZ,MAAM;YACtC,OAAO,GAAG8B,MAAMlB,SAAS,CAACJ,MAAM,GAAGsB,MAAMlB,SAAS,CAACH,GAAG,EAAE;QAE1D,KAAK;YACH,IAAI,CAACqB,MAAMlB,SAAS,IAAI,CAACkB,MAAMhB,OAAO,EAAE,MAAM,IAAId,MAAM;YACxD,OAAO,GAAG8B,MAAMlB,SAAS,CAACJ,MAAM,GAAGsB,MAAMlB,SAAS,CAACH,GAAG,CAAC,CAAC,EAAEqB,MAAMhB,OAAO,CAACN,MAAM,GAAGsB,MAAMhB,OAAO,CAACL,GAAG,EAAE;QAEtG,KAAK;YACH,IAAI,CAACqB,MAAMf,WAAW,IAAI,CAACe,MAAMd,SAAS,EAAE,MAAM,IAAIhB,MAAM;YAC5D,IAAI8B,MAAMf,WAAW,KAAKe,MAAMd,SAAS,EAAE;gBACzC,OAAOc,MAAMf,WAAW;YAC1B;YACA,OAAO,GAAGe,MAAMf,WAAW,CAAC,CAAC,EAAEe,MAAMd,SAAS,EAAE;QAElD,KAAK;YACH,IAAIc,MAAMX,QAAQ,KAAKY,aAAaD,MAAMV,MAAM,KAAKW,WAAW,MAAM,IAAI/B,MAAM;YAChF,IAAI8B,MAAMX,QAAQ,KAAKW,MAAMV,MAAM,EAAE;gBACnC,OAAOU,MAAMX,QAAQ,CAACa,QAAQ;YAChC;YACA,OAAO,GAAGF,MAAMX,QAAQ,CAAC,CAAC,EAAEW,MAAMV,MAAM,EAAE;QAE5C;YACE,MAAM,IAAIpB,MAAM,CAAC,oBAAoB,EAAE,AAAC8B,MAA4BjB,IAAI,EAAE;IAC9E;AACF;AAEA;;CAEC,GAED;;CAEC,GACD,OAAO,SAASoB,yBAAyBlD,QAAgB;IACvD,MAAM+C,QAAQnB,gBAAgB5B;IAE9B,OAAQ+C,MAAMjB,IAAI;QAChB,KAAK;YACH,OAAO;gBAAEqB,MAAM;gBAAGC,SAAS;gBAAGC,OAAO;YAAE;QAEzC,KAAK;YAAS;gBACZ,IAAI,CAACN,MAAMlB,SAAS,IAAI,CAACkB,MAAMhB,OAAO,EAAE,MAAM,IAAId,MAAM;gBACxD,MAAMkC,OAAOJ,MAAMhB,OAAO,CAACL,GAAG,GAAGqB,MAAMlB,SAAS,CAACH,GAAG,GAAG;gBACvD,MAAM0B,UAAUL,MAAMhB,OAAO,CAACJ,WAAW,GAAGoB,MAAMlB,SAAS,CAACF,WAAW,GAAG;gBAC1E,OAAO;oBAAEwB;oBAAMC;oBAASC,OAAOF,OAAOC;gBAAQ;YAChD;QAEA,KAAK;YAAU;gBACb,IAAIL,MAAMb,gBAAgB,KAAKc,aAAaD,MAAMZ,cAAc,KAAKa,WAAW;oBAC9E,MAAM,IAAI/B,MAAM;gBAClB;gBACA,MAAMqC,cAAcP,MAAMZ,cAAc,GAAGY,MAAMb,gBAAgB,GAAG;gBACpE,OAAO;oBACLiB,MAAM1D,qBAAqBC,QAAQ;oBACnC0D,SAASE;oBACTD,OAAO5D,qBAAqBC,QAAQ,GAAG4D;gBACzC;YACF;QAEA,KAAK;YAAO;gBACV,IAAIP,MAAMX,QAAQ,KAAKY,aAAaD,MAAMV,MAAM,KAAKW,WAAW;oBAC9D,MAAM,IAAI/B,MAAM;gBAClB;gBACA,MAAMsC,WAAWR,MAAMV,MAAM,GAAGU,MAAMX,QAAQ,GAAG;gBACjD,OAAO;oBACLe,MAAMI;oBACNH,SAAS3D,qBAAqBE,WAAW;oBACzC0D,OAAOE,WAAW9D,qBAAqBE,WAAW;gBACpD;YACF;QAEA;YACE,MAAM,IAAIsB,MAAM,CAAC,oBAAoB,EAAE,AAAC8B,MAA2BjB,IAAI,EAAE;IAC7E;AACF;AAEA;;CAEC,GACD,OAAO,SAAS0B,oBAAoBC,MAAgB;IAClD,OAAOA,OAAOC,MAAM,CAAC,CAACC,OAAOZ;QAC3B,MAAMa,aAAaV,yBAAyBH;QAC5C,OAAOY,QAAQC,WAAWP,KAAK;IACjC,GAAG;AACL;AAEA;;CAEC,GAED;;CAEC,GACD,OAAO,SAASQ,8BACdC,QAIE,EACFC,UAAkB,EAClBC,UAKI,CAAC,CAAC;IAEN,4BAA4B;IAC5BF,SAASG,OAAO,CAAC,CAACC,KAAKC;QACrB,IAAI;YACFnD,mBAAmBkD,IAAInB,KAAK;QAC9B,EAAE,OAAOqB,OAAO;YACd,MAAM,IAAInD,MAAM,CAAC,yBAAyB,EAAEkD,MAAM,EAAE,EAAEC,OAAO;QAC/D;IACF;IAEA,uCAAuC;IACvC,MAAMC,aAAab,oBAAoBM,SAASQ,GAAG,CAAC,CAACC,IAAMA,EAAExB,KAAK;IAClE,IAAIsB,aAAa5E,qBAAqBG,SAAS,EAAE;QAC/C,MAAM,IAAIqB,MAAM,CAAC,0CAA0C,EAAEoD,WAAW,GAAG,EAAE5E,qBAAqBG,SAAS,EAAE;IAC/G;IAEA,oBAAoB;IACpB,MAAM4E,OAAOV,SAASQ,GAAG,CAAC,CAACJ,MAAS,CAAA;YAClCnB,OAAO,GAAGgB,WAAW,CAAC,EAAEG,IAAInB,KAAK,EAAE;YACnC0B,QAAQP,IAAIO,MAAM;YAClBC,gBAAgBR,IAAIQ,cAAc,IAAI;QACxC,CAAA;IAEA,OAAO;QACLC,kBAAkBX,QAAQW,gBAAgB,IAAI;QAC9CH;QACAI,yBAAyBZ,QAAQY,uBAAuB,IAAI;QAC5DC,8BAA8Bb,QAAQa,4BAA4B,IAAI;QACtEC,2BAA2Bd,QAAQc,yBAAyB,IAAI;IAClE;AACF;AAEA;;CAEC,GAED;;CAEC,GACD,OAAO,SAASC,cAAcC,MAAc,EAAEC,MAAc;IAC1D,IAAI;QACF,MAAMC,UAAUtD,gBAAgBoD;QAChC,MAAMG,UAAUvD,gBAAgBqD;QAEhC,8EAA8E;QAC9E,MAAMG,cAAcC,uBAAuBH;QAC3C,MAAMI,cAAcD,uBAAuBF;QAE3C,oBAAoB;QACpB,OAAO,CAAEC,CAAAA,YAAY/C,MAAM,GAAGiD,YAAYlD,QAAQ,IAAIkD,YAAYjD,MAAM,GAAG+C,YAAYhD,QAAQ,IAAIgD,YAAYG,MAAM,GAAGD,YAAYE,QAAQ,IAAIF,YAAYC,MAAM,GAAGH,YAAYI,QAAQ,AAAD;IAC1L,EAAE,OAAM;QACN,kDAAkD;QAClD,OAAO;IACT;AACF;AAEA;;CAEC,GACD,SAASH,uBAAuBtC,KAAqB;IAMnD,OAAQA,MAAMjB,IAAI;QAChB,KAAK;YACH,IAAI,CAACiB,MAAMlB,SAAS,EAAE,MAAM,IAAIZ,MAAM;YACtC,OAAO;gBACLmB,UAAUW,MAAMlB,SAAS,CAACH,GAAG;gBAC7BW,QAAQU,MAAMlB,SAAS,CAACH,GAAG;gBAC3B8D,UAAUzC,MAAMlB,SAAS,CAACF,WAAW;gBACrC4D,QAAQxC,MAAMlB,SAAS,CAACF,WAAW;YACrC;QAEF,KAAK;YACH,IAAI,CAACoB,MAAMlB,SAAS,IAAI,CAACkB,MAAMhB,OAAO,EAAE,MAAM,IAAId,MAAM;YACxD,OAAO;gBACLmB,UAAUW,MAAMlB,SAAS,CAACH,GAAG;gBAC7BW,QAAQU,MAAMhB,OAAO,CAACL,GAAG;gBACzB8D,UAAUzC,MAAMlB,SAAS,CAACF,WAAW;gBACrC4D,QAAQxC,MAAMhB,OAAO,CAACJ,WAAW;YACnC;QAEF,KAAK;YACH,IAAIoB,MAAMb,gBAAgB,KAAKc,aAAaD,MAAMZ,cAAc,KAAKa,WAAW;gBAC9E,MAAM,IAAI/B,MAAM;YAClB;YACA,OAAO;gBACLmB,UAAU;gBACVC,QAAQ5C,qBAAqBC,QAAQ;gBACrC8F,UAAUzC,MAAMb,gBAAgB;gBAChCqD,QAAQxC,MAAMZ,cAAc;YAC9B;QAEF,KAAK;YACH,IAAIY,MAAMX,QAAQ,KAAKY,aAAaD,MAAMV,MAAM,KAAKW,WAAW;gBAC9D,MAAM,IAAI/B,MAAM;YAClB;YACA,OAAO;gBACLmB,UAAUW,MAAMX,QAAQ;gBACxBC,QAAQU,MAAMV,MAAM;gBACpBmD,UAAU;gBACVD,QAAQ9F,qBAAqBE,WAAW;YAC1C;QAEF;YACE,MAAM,IAAIsB,MAAM,CAAC,oBAAoB,EAAE,AAAC8B,MAA4BjB,IAAI,EAAE;IAC9E;AACF;AAEA;;CAEC,GACD,OAAO,SAAS2D,qBAAqBhC,MAAgB;IACnD,MAAMiC,YAA6B,EAAE;IAErC,IAAK,IAAIxE,IAAI,GAAGA,IAAIuC,OAAOtC,MAAM,EAAED,IAAK;QACtC,IAAK,IAAIyE,IAAIzE,IAAI,GAAGyE,IAAIlC,OAAOtC,MAAM,EAAEwE,IAAK;YAC1C,MAAMX,SAASvB,MAAM,CAACvC,EAAE;YACxB,MAAM+D,SAASxB,MAAM,CAACkC,EAAE;YAExB,IAAI,CAACX,UAAU,CAACC,QAAQ;YAExB,IAAIF,cAAcC,QAAQC,SAAS;gBACjCS,UAAUE,IAAI,CAAC;oBACbZ;oBACAC;oBACAY,cAAc;oBACdC,aAAa,CAAC,OAAO,EAAEd,OAAO,KAAK,EAAEC,OAAO,QAAQ,CAAC;gBACvD;YACF;QACF;IACF;IAEA,OAAOS;AACT;AAEA;;CAEC,GACD,OAAO,SAASK,oBAAoBtC,MAAgB;IAMlD,MAAMuC,SAAmB,EAAE;IAC3B,MAAMC,WAAqB,EAAE;IAC7B,IAAI5B,aAAa;IAEjB,sBAAsB;IACtBZ,OAAOQ,OAAO,CAAC,CAAClB,OAAOoB;QACrB,IAAI;YACFnD,mBAAmB+B;YACnB,MAAMa,aAAaV,yBAAyBH;YAC5CsB,cAAcT,WAAWP,KAAK;YAE9B,kEAAkE;YAClE,IAAIO,WAAWP,KAAK,GAAG,SAAW;gBAChC4C,SAASL,IAAI,CAAC,CAAC,MAAM,EAAEzB,QAAQ,EAAE,EAAE,EAAEpB,MAAM,UAAU,EAAEa,WAAWP,KAAK,CAAC6C,cAAc,GAAG,oCAAoC,CAAC;YAChI;QACF,EAAE,OAAO9B,OAAO;YACd4B,OAAOJ,IAAI,CAAC,CAAC,MAAM,EAAEzB,QAAQ,EAAE,EAAE,EAAEpB,MAAM,GAAG,EAAEqB,OAAO;QACvD;IACF;IAEA,0BAA0B;IAC1B,IAAIX,OAAOtC,MAAM,GAAG1B,qBAAqBI,kBAAkB,EAAE;QAC3DmG,OAAOJ,IAAI,CAAC,CAAC,iBAAiB,EAAEnC,OAAOtC,MAAM,CAAC,GAAG,EAAE1B,qBAAqBI,kBAAkB,EAAE;IAC9F;IAEA,0BAA0B;IAC1B,IAAIwE,aAAa5E,qBAAqBG,SAAS,EAAE;QAC/CoG,OAAOJ,IAAI,CAAC,CAAC,0BAA0B,EAAEvB,WAAW6B,cAAc,GAAG,GAAG,EAAEzG,qBAAqBG,SAAS,CAACsG,cAAc,IAAI;IAC7H;IAEA,sBAAsB;IACtB,MAAMR,YAAYD,qBAAqBhC;IACvCiC,UAAUzB,OAAO,CAAC,CAACkC;QACjBF,SAASL,IAAI,CAACO,SAASL,WAAW;IACpC;IAEA,OAAO;QACLM,OAAOJ,OAAO7E,MAAM,KAAK;QACzB6E;QACAC;QACA5B;IACF;AACF;AAEA;;CAEC,GAED;;CAEC,GACD,OAAO,SAASgC,YAAYrG,QAAgB,EAAEsG,UAAkB,EAAEC,UAAkB;IAClF,MAAMxD,QAAQnB,gBAAgB5B;IAE9B,IAAI+C,MAAMjB,IAAI,KAAK,UAAUiB,MAAMlB,SAAS,EAAE;QAC5C,MAAM2E,YAAYC,KAAKC,GAAG,CAAC3D,MAAMlB,SAAS,CAACH,GAAG,GAAG4E,YAAY7G,qBAAqBC,QAAQ;QAC1F,MAAMiH,YAAYF,KAAKC,GAAG,CAAC3D,MAAMlB,SAAS,CAACF,WAAW,GAAG4E,YAAY9G,qBAAqBE,WAAW;QACrG,MAAMiH,eAAevF,oBAAoBsF;QAEzC,IAAIL,eAAe,KAAKC,eAAe,GAAG;YACxC,OAAOvG;QACT;QAEA,OAAO,GAAG+C,MAAMlB,SAAS,CAACJ,MAAM,GAAGsB,MAAMlB,SAAS,CAACH,GAAG,CAAC,CAAC,EAAEkF,eAAeJ,WAAW;IACtF;IAEA,IAAIzD,MAAMjB,IAAI,KAAK,WAAWiB,MAAMlB,SAAS,IAAIkB,MAAMhB,OAAO,EAAE;QAC9D,MAAMyE,YAAYC,KAAKC,GAAG,CAAC3D,MAAMhB,OAAO,CAACL,GAAG,GAAG4E,YAAY7G,qBAAqBC,QAAQ;QACxF,MAAMiH,YAAYF,KAAKC,GAAG,CAAC3D,MAAMhB,OAAO,CAACJ,WAAW,GAAG4E,YAAY9G,qBAAqBE,WAAW;QACnG,MAAMiH,eAAevF,oBAAoBsF;QAEzC,OAAO,GAAG5D,MAAMlB,SAAS,CAACJ,MAAM,GAAGsB,MAAMlB,SAAS,CAACH,GAAG,CAAC,CAAC,EAAEkF,eAAeJ,WAAW;IACtF;IAEA,0EAA0E;IAC1E,OAAOxG;AACT;AAEA;;CAEC,GACD,OAAO,SAAS6G,qBAAqB7B,MAAc,EAAEC,MAAc;IACjE,IAAI;QACF,MAAMC,UAAUtD,gBAAgBoD;QAChC,MAAMG,UAAUvD,gBAAgBqD;QAEhC,MAAM6B,UAAUzB,uBAAuBH;QACvC,MAAM6B,UAAU1B,uBAAuBF;QAEvC,wBAAwB;QACxB,IAAI,CAACJ,cAAcC,QAAQC,SAAS;YAClC,OAAO;QACT;QAEA,gCAAgC;QAChC,MAAM7C,WAAWqE,KAAKO,GAAG,CAACF,QAAQ1E,QAAQ,EAAE2E,QAAQ3E,QAAQ;QAC5D,MAAMC,SAASoE,KAAKC,GAAG,CAACI,QAAQzE,MAAM,EAAE0E,QAAQ1E,MAAM;QACtD,MAAMmD,WAAWiB,KAAKO,GAAG,CAACF,QAAQtB,QAAQ,EAAEuB,QAAQvB,QAAQ;QAC5D,MAAMD,SAASkB,KAAKC,GAAG,CAACI,QAAQvB,MAAM,EAAEwB,QAAQxB,MAAM;QAEtD,MAAM0B,cAAc5F,oBAAoBmE;QACxC,MAAM0B,YAAY7F,oBAAoBkE;QAEtC,IAAInD,aAAaC,UAAUmD,aAAaD,QAAQ;YAC9C,OAAO,GAAG0B,cAAc7E,UAAU;QACpC;QAEA,OAAO,GAAG6E,cAAc7E,SAAS,CAAC,EAAE8E,YAAY7E,QAAQ;IAC1D,EAAE,OAAM;QACN,OAAO;IACT;AACF;AAEA;;CAEC,GACD,OAAO,SAAS8E,qBAAqBnH,QAAgB,EAAEoH,mBAAmB,MAAO;IAC/E,MAAMrE,QAAQnB,gBAAgB5B;IAC9B,MAAM4D,aAAaV,yBAAyBlD;IAE5C,IAAI4D,WAAWP,KAAK,IAAI+D,kBAAkB;QACxC,OAAO;YAACpH;SAAS;IACnB;IAEA,MAAMqH,SAAmB,EAAE;IAE3B,IAAItE,MAAMjB,IAAI,KAAK,WAAWiB,MAAMlB,SAAS,IAAIkB,MAAMhB,OAAO,EAAE;QAC9D,MAAMuF,YAAYvE,MAAMhB,OAAO,CAACL,GAAG,GAAGqB,MAAMlB,SAAS,CAACH,GAAG,GAAG;QAC5D,MAAM6F,YAAYxE,MAAMhB,OAAO,CAACJ,WAAW,GAAGoB,MAAMlB,SAAS,CAACF,WAAW,GAAG;QAE5E,0CAA0C;QAC1C,MAAM6F,cAAcD;QACpB,MAAME,kBAAkBhB,KAAKiB,KAAK,CAACN,mBAAmBI;QAEtD,IAAIC,mBAAmB,GAAG;YACxB,gBAAgB;YAChB,IAAK,IAAIE,aAAa5E,MAAMlB,SAAS,CAACH,GAAG,EAAEiG,cAAc5E,MAAMhB,OAAO,CAACL,GAAG,EAAEiG,cAAcF,gBAAiB;gBACzG,MAAMG,cAAcnB,KAAKC,GAAG,CAACiB,aAAaF,kBAAkB,GAAG1E,MAAMhB,OAAO,CAACL,GAAG;gBAChF,MAAMmG,aAAa,GAAG9E,MAAMlB,SAAS,CAACJ,MAAM,GAAGkG,WAAW,CAAC,EAAE5E,MAAMhB,OAAO,CAACN,MAAM,GAAGmG,aAAa;gBACjGP,OAAOzB,IAAI,CAACiC;YACd;QACF,OAAO;YACL,+CAA+C;YAC/C,MAAMC,kBAAkBrB,KAAKiB,KAAK,CAACN,mBAAmBE;YAEtD,IAAK,IAAIS,aAAahF,MAAMlB,SAAS,CAACF,WAAW,EAAEoG,cAAchF,MAAMhB,OAAO,CAACJ,WAAW,EAAEoG,cAAcD,gBAAiB;gBACzH,MAAME,cAAcvB,KAAKC,GAAG,CAACqB,aAAaD,kBAAkB,GAAG/E,MAAMhB,OAAO,CAACJ,WAAW;gBACxF,MAAMsF,cAAc5F,oBAAoB0G;gBACxC,MAAMb,YAAY7F,oBAAoB2G;gBACtC,MAAMH,aAAa,GAAGZ,cAAclE,MAAMlB,SAAS,CAACH,GAAG,CAAC,CAAC,EAAEwF,YAAYnE,MAAMhB,OAAO,CAACL,GAAG,EAAE;gBAC1F2F,OAAOzB,IAAI,CAACiC;YACd;QACF;IACF,OAAO;QACL,wDAAwD;QACxD,sDAAsD;QACtDR,OAAOzB,IAAI,CAAC5F;IACd;IAEA,OAAOqH;AACT;AAEA;;;;;;;;;;CAUC,GACD,OAAO,SAASY,0BACdC,QAAwB,EACxBC,OAAe;IAQf,IAAID,SAASpG,IAAI,KAAK,UAAUoG,SAASpG,IAAI,KAAK,SAAS;QACzD,2DAA2D;QAC3D,IAAI,CAACoG,SAASrG,SAAS,IAAI,CAACqG,SAASnG,OAAO,EAAE;YAC5C,MAAM,IAAId,MAAM,CAAC,QAAQ,EAAEiH,SAASpG,IAAI,CAAC,iCAAiC,CAAC;QAC7E;QAEA,OAAO;YACLqG;YACA,+CAA+C;YAC/CC,eAAeF,SAASrG,SAAS,CAACH,GAAG,GAAG;YACxC,4DAA4D;YAC5D2G,aAAaH,SAASnG,OAAO,CAACL,GAAG;YACjC,2DAA2D;YAC3DQ,kBAAkBgG,SAASrG,SAAS,CAACF,WAAW,GAAG;YACnD,8BAA8B;YAC9BQ,gBAAgB+F,SAASnG,OAAO,CAACJ,WAAW;QAC9C;IACF;IACA,IAAIuG,SAASpG,IAAI,KAAK,OAAO;QAC3B,gFAAgF;QAChF,IAAIoG,SAAS9F,QAAQ,KAAKY,aAAakF,SAAS7F,MAAM,KAAKW,WAAW;YACpE,MAAM,IAAI/B,MAAM;QAClB;QAEA,OAAO;YACLkH;YACA,+CAA+C;YAC/CC,eAAeF,SAAS9F,QAAQ,GAAG;YACnC,2BAA2B;YAC3BiG,aAAaH,SAAS7F,MAAM;QAE9B;IACF;IACA,IAAI6F,SAASpG,IAAI,KAAK,UAAU;QAC9B,oGAAoG;QACpG,IAAIoG,SAAShG,gBAAgB,KAAKc,aAAakF,SAAS/F,cAAc,KAAKa,WAAW;YACpF,MAAM,IAAI/B,MAAM;QAClB;QAEA,OAAO;YACLkH;YACA,0DAA0D;YAC1D,2DAA2D;YAC3DjG,kBAAkBgG,SAAShG,gBAAgB,GAAG;YAC9C,8BAA8B;YAC9BC,gBAAgB+F,SAAS/F,cAAc;QACzC;IACF;IAEA,MAAM,IAAIlB,MAAM,CAAC,oBAAoB,EAAE,AAACiH,SAA+BpG,IAAI,EAAE;AAC/E"}

package/dist/esm/spreadsheet/sheet-operations.d.ts

@@ -0,0 +1,30 @@
+import type { sheets_v4 } from 'googleapis';
+import type { Logger } from '../types.js';
+export declare function ensureSheetIfNeeded(sheets: sheets_v4.Sheets, id: string, sheetTitle: string, ensureSheet: boolean, headers: string[] | undefined, logger: Logger): Promise<{
+    sheetCreated: boolean;
+    sheetGUID?: string;
+    headersEnsured?: boolean;
+}>;
+export declare function findSheetByRef(client: sheets_v4.Sheets, spreadsheetId: string, sheetRef: string, logger: Logger): Promise<sheets_v4.Schema$Sheet>;
+export declare function ensureTabAndHeaders(sheets: sheets_v4.Sheets, params: {
+    spreadsheetId: string;
+    sheetTitle: string;
+    requiredHeader?: string[] | null;
+    keyColumns?: string[];
+    logger: Logger;
+}): Promise<{
+    header: string[];
+    keySet: Set<string>;
+    keyColumnsIdx?: number[];
+}>;
+export declare function ensureTabAndHeaders(sheets: sheets_v4.Sheets, params: {
+    spreadsheetId: string;
+    sheetRef: string;
+    requiredHeader?: string[] | null;
+    keyColumns?: string[];
+    logger: Logger;
+}): Promise<{
+    header: string[];
+    keySet: Set<string>;
+    keyColumnsIdx?: number[];
+}>;

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

@@ -0,0 +1,359 @@
+import { a1Col } from './column-utilities.js';
+export async function ensureSheetIfNeeded(sheets, id, sheetTitle, ensureSheet, headers, logger) {
+    var _res_data_replies__addSheet_properties, _res_data_replies__addSheet, _res_data_replies_, _res_data_replies, _res_data;
+    if (!sheetTitle) return {
+        sheetCreated: false
+    };
+    const ssResp = await sheets.spreadsheets.get({
+        spreadsheetId: id
+    });
+    const ss = ssResp.data;
+    const has = Array.isArray(ss === null || ss === void 0 ? void 0 : ss.sheets) && ss.sheets.some((s)=>{
+        var _s_properties;
+        return (s === null || s === void 0 ? void 0 : (_s_properties = s.properties) === null || _s_properties === void 0 ? void 0 : _s_properties.title) === sheetTitle;
+    });
+    if (has) {
+        var _ss_sheets_find_properties, _ss_sheets_find, _ss_sheets;
+        const sid = (_ss_sheets = ss.sheets) === null || _ss_sheets === void 0 ? void 0 : (_ss_sheets_find = _ss_sheets.find((s)=>{
+            var _s_properties;
+            return (s === null || s === void 0 ? void 0 : (_s_properties = s.properties) === null || _s_properties === void 0 ? void 0 : _s_properties.title) === sheetTitle;
+        })) === null || _ss_sheets_find === void 0 ? void 0 : (_ss_sheets_find_properties = _ss_sheets_find.properties) === null || _ss_sheets_find_properties === void 0 ? void 0 : _ss_sheets_find_properties.sheetId;
+        const result = {
+            sheetCreated: false
+        };
+        if (sid != null) result.sheetGUID = String(sid);
+        if (headers) {
+            try {
+                const { header: merged } = await ensureTabAndHeaders(sheets, {
+                    spreadsheetId: id,
+                    sheetTitle,
+                    requiredHeader: headers,
+                    logger
+                });
+                if (merged) result.headersEnsured = true;
+            } catch (e) {
+                var _logger_warn;
+                (_logger_warn = logger.warn) === null || _logger_warn === void 0 ? void 0 : _logger_warn.call(logger, 'ensureTabAndHeaders after sheet creation failed', e);
+            }
+        }
+        return result;
+    }
+    if (!ensureSheet) return {
+        sheetCreated: false
+    };
+    const res = await sheets.spreadsheets.batchUpdate({
+        spreadsheetId: id,
+        requestBody: {
+            requests: [
+                {
+                    addSheet: {
+                        properties: {
+                            title: sheetTitle
+                        }
+                    }
+                }
+            ]
+        }
+    });
+    const createdId = (_res_data = res.data) === null || _res_data === void 0 ? void 0 : (_res_data_replies = _res_data.replies) === null || _res_data_replies === void 0 ? void 0 : (_res_data_replies_ = _res_data_replies[0]) === null || _res_data_replies_ === void 0 ? void 0 : (_res_data_replies__addSheet = _res_data_replies_.addSheet) === null || _res_data_replies__addSheet === void 0 ? void 0 : (_res_data_replies__addSheet_properties = _res_data_replies__addSheet.properties) === null || _res_data_replies__addSheet_properties === void 0 ? void 0 : _res_data_replies__addSheet_properties.sheetId;
+    const result = {
+        sheetCreated: !!createdId
+    };
+    if (createdId != null) result.sheetGUID = String(createdId);
+    if (createdId && headers) {
+        try {
+            const { header: merged } = await ensureTabAndHeaders(sheets, {
+                spreadsheetId: id,
+                sheetTitle,
+                requiredHeader: headers,
+                logger
+            });
+            if (merged) result.headersEnsured = true;
+        } catch (e) {
+            var _logger_warn1;
+            (_logger_warn1 = logger.warn) === null || _logger_warn1 === void 0 ? void 0 : _logger_warn1.call(logger, 'ensureTabAndHeaders after sheet creation failed', e);
+        }
+    }
+    return result;
+}
+export async function findSheetByRef(client, spreadsheetId, sheetRef, logger) {
+    var _ssResp_data, _logger_debug, _logger_warn;
+    const ssResp = await client.spreadsheets.get({
+        spreadsheetId
+    });
+    const sheets = ((_ssResp_data = ssResp.data) === null || _ssResp_data === void 0 ? void 0 : _ssResp_data.sheets) || [];
+    const trimmedRef = sheetRef === null || sheetRef === void 0 ? void 0 : sheetRef.trim();
+    (_logger_debug = logger.debug) === null || _logger_debug === void 0 ? void 0 : _logger_debug.call(logger, 'findSheetByRef called', {
+        spreadsheetId,
+        sheetRef,
+        trimmedRef,
+        availableSheets: sheets.map((s)=>{
+            var _s_properties, _s_properties1;
+            return {
+                title: s === null || s === void 0 ? void 0 : (_s_properties = s.properties) === null || _s_properties === void 0 ? void 0 : _s_properties.title,
+                id: s === null || s === void 0 ? void 0 : (_s_properties1 = s.properties) === null || _s_properties1 === void 0 ? void 0 : _s_properties1.sheetId
+            };
+        })
+    });
+    if (!trimmedRef) {
+        var _logger_warn1;
+        (_logger_warn1 = logger.warn) === null || _logger_warn1 === void 0 ? void 0 : _logger_warn1.call(logger, 'findSheetByRef empty sheetRef');
+        return null;
+    }
+    // Strategy 1: Try exact title match first (most common case)
+    const exactTitleMatch = sheets.find((s)=>{
+        var _s_properties;
+        return (s === null || s === void 0 ? void 0 : (_s_properties = s.properties) === null || _s_properties === void 0 ? void 0 : _s_properties.title) === trimmedRef;
+    });
+    if (exactTitleMatch) {
+        var _logger_debug1;
+        (_logger_debug1 = logger.debug) === null || _logger_debug1 === void 0 ? void 0 : _logger_debug1.call(logger, 'findSheetByRef exact title match found');
+        return exactTitleMatch;
+    }
+    // Strategy 2: Try exact GUID match (for when user passes actual sheet ID)
+    const exactGuidMatch = sheets.find((s)=>{
+        var _s_properties;
+        return String(s === null || s === void 0 ? void 0 : (_s_properties = s.properties) === null || _s_properties === void 0 ? void 0 : _s_properties.sheetId) === trimmedRef;
+    });
+    if (exactGuidMatch) {
+        var _logger_debug2;
+        (_logger_debug2 = logger.debug) === null || _logger_debug2 === void 0 ? void 0 : _logger_debug2.call(logger, 'findSheetByRef exact GUID match found');
+        return exactGuidMatch;
+    }
+    // Strategy 3: Case-insensitive title match
+    const caseInsensitiveMatch = sheets.find((s)=>{
+        var _s_properties_title, _s_properties;
+        return (s === null || s === void 0 ? void 0 : (_s_properties = s.properties) === null || _s_properties === void 0 ? void 0 : (_s_properties_title = _s_properties.title) === null || _s_properties_title === void 0 ? void 0 : _s_properties_title.toLowerCase()) === trimmedRef.toLowerCase();
+    });
+    if (caseInsensitiveMatch) {
+        var _logger_debug3;
+        (_logger_debug3 = logger.debug) === null || _logger_debug3 === void 0 ? void 0 : _logger_debug3.call(logger, 'findSheetByRef case-insensitive title match found');
+        return caseInsensitiveMatch;
+    }
+    // Strategy 4: Trimmed title match (handles extra whitespace in sheet names)
+    const trimmedTitleMatch = sheets.find((s)=>{
+        var _s_properties_title, _s_properties;
+        return (s === null || s === void 0 ? void 0 : (_s_properties = s.properties) === null || _s_properties === void 0 ? void 0 : (_s_properties_title = _s_properties.title) === null || _s_properties_title === void 0 ? void 0 : _s_properties_title.trim()) === trimmedRef;
+    });
+    if (trimmedTitleMatch) {
+        var _logger_debug4;
+        (_logger_debug4 = logger.debug) === null || _logger_debug4 === void 0 ? void 0 : _logger_debug4.call(logger, 'findSheetByRef trimmed title match found');
+        return trimmedTitleMatch;
+    }
+    // Strategy 5: Case-insensitive + trimmed title match
+    const caseInsensitiveTrimmedMatch = sheets.find((s)=>{
+        var _s_properties_title, _s_properties;
+        return (s === null || s === void 0 ? void 0 : (_s_properties = s.properties) === null || _s_properties === void 0 ? void 0 : (_s_properties_title = _s_properties.title) === null || _s_properties_title === void 0 ? void 0 : _s_properties_title.trim().toLowerCase()) === trimmedRef.toLowerCase();
+    });
+    if (caseInsensitiveTrimmedMatch) {
+        var _logger_debug5;
+        (_logger_debug5 = logger.debug) === null || _logger_debug5 === void 0 ? void 0 : _logger_debug5.call(logger, 'findSheetByRef case-insensitive trimmed title match found');
+        return caseInsensitiveTrimmedMatch;
+    }
+    // Strategy 6: Partial title match (last resort)
+    const partialMatch = sheets.find((s)=>{
+        var _s_properties_title, _s_properties;
+        return s === null || s === void 0 ? void 0 : (_s_properties = s.properties) === null || _s_properties === void 0 ? void 0 : (_s_properties_title = _s_properties.title) === null || _s_properties_title === void 0 ? void 0 : _s_properties_title.toLowerCase().includes(trimmedRef.toLowerCase());
+    });
+    if (partialMatch) {
+        var _logger_debug6;
+        (_logger_debug6 = logger.debug) === null || _logger_debug6 === void 0 ? void 0 : _logger_debug6.call(logger, 'findSheetByRef partial title match found');
+        return partialMatch;
+    }
+    (_logger_warn = logger.warn) === null || _logger_warn === void 0 ? void 0 : _logger_warn.call(logger, 'findSheetByRef no match found', {
+        searchRef: trimmedRef,
+        availableTitles: sheets.map((s)=>{
+            var _s_properties;
+            return s === null || s === void 0 ? void 0 : (_s_properties = s.properties) === null || _s_properties === void 0 ? void 0 : _s_properties.title;
+        }),
+        availableIds: sheets.map((s)=>{
+            var _s_properties;
+            return s === null || s === void 0 ? void 0 : (_s_properties = s.properties) === null || _s_properties === void 0 ? void 0 : _s_properties.sheetId;
+        })
+    });
+    return null;
+}
+export async function ensureTabAndHeaders(sheets, { spreadsheetId, sheetTitle, sheetRef, requiredHeader = null, keyColumns = [
+    'id'
+], logger }) {
+    if (!sheets) throw new Error('ensureTabAndHeaders: sheets is required');
+    if (!spreadsheetId) throw new Error('ensureTabAndHeaders: spreadsheetId is required');
+    if (!sheetTitle && !sheetRef) throw new Error('ensureTabAndHeaders: 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 for creation
+            resolvedSheetTitle = sheetRef;
+        }
+    }
+    if (!resolvedSheetTitle) throw new Error('ensureTabAndHeaders: could not resolve sheet title');
+    const defaultHeader = [
+        'id',
+        'provider',
+        'threadId',
+        'to',
+        'from',
+        'cc',
+        'bcc',
+        'date',
+        'subject',
+        'labels',
+        'snippet',
+        'body'
+    ];
+    const header = Array.isArray(requiredHeader) && requiredHeader.length ? requiredHeader : defaultHeader;
+    let existingHeader = null;
+    try {
+        const resp = await sheets.spreadsheets.values.get({
+            spreadsheetId,
+            range: `${resolvedSheetTitle}!1:1`,
+            majorDimension: 'ROWS'
+        });
+        const vr = resp.data;
+        const values = ((vr === null || vr === void 0 ? void 0 : vr.values) || [])[0] || [];
+        existingHeader = values.length ? values : null;
+    } catch (_err) {
+        try {
+            await sheets.spreadsheets.batchUpdate({
+                spreadsheetId,
+                requestBody: {
+                    requests: [
+                        {
+                            addSheet: {
+                                properties: {
+                                    title: resolvedSheetTitle
+                                }
+                            }
+                        }
+                    ]
+                }
+            });
+        } catch  {}
+        await sheets.spreadsheets.values.append({
+            spreadsheetId,
+            range: `${resolvedSheetTitle}!A1`,
+            valueInputOption: 'RAW',
+            insertDataOption: 'INSERT_ROWS',
+            requestBody: {
+                values: [
+                    header
+                ]
+            }
+        });
+        return {
+            header,
+            keySet: new Set()
+        };
+    }
+    if (!existingHeader) {
+        await sheets.spreadsheets.values.append({
+            spreadsheetId,
+            range: `${resolvedSheetTitle}!A1`,
+            valueInputOption: 'RAW',
+            insertDataOption: 'INSERT_ROWS',
+            requestBody: {
+                values: [
+                    header
+                ]
+            }
+        });
+        return {
+            header,
+            keySet: new Set()
+        };
+    }
+    const mergedHeader = existingHeader.slice();
+    for (const col of header)if (!mergedHeader.includes(col)) mergedHeader.push(col);
+    if (Array.isArray(keyColumns)) {
+        for (const name of keyColumns){
+            if (typeof name !== 'string' || name.length === 0) throw new Error('ensureTabAndHeaders: keyColumns must be an array of non-empty strings');
+            if (!mergedHeader.includes(name)) mergedHeader.push(name);
+        }
+    }
+    if (mergedHeader.length !== existingHeader.length) {
+        await sheets.spreadsheets.values.update({
+            spreadsheetId,
+            range: `${resolvedSheetTitle}!1:1`,
+            valueInputOption: 'RAW',
+            requestBody: {
+                values: [
+                    mergedHeader
+                ]
+            }
+        });
+    }
+    const keySet = new Set();
+    const chunkSize = 1000;
+    let startRow = 2;
+    const normalizeKeyColumnsByName = (kc, hdr)=>{
+        if (!Array.isArray(kc) || kc.length === 0) return [];
+        return kc.map((name)=>{
+            if (typeof name !== 'string' || name.length === 0) return -1;
+            const idx = hdr.indexOf(name);
+            return Number.isInteger(idx) && idx >= 0 ? idx : -1;
+        });
+    };
+    const keyColsIdx = normalizeKeyColumnsByName(keyColumns, mergedHeader);
+    const validKeyIdxs = keyColsIdx.filter((i)=>i >= 0);
+    if (validKeyIdxs.length === 0) return {
+        header: mergedHeader,
+        keySet: new Set(),
+        keyColumnsIdx: keyColsIdx
+    };
+    const minIdx = Math.min(...validKeyIdxs);
+    const maxIdx = Math.max(...validKeyIdxs);
+    const startCol = a1Col(minIdx + 1);
+    const endCol = a1Col(maxIdx + 1);
+    while(true){
+        const endRow = startRow + chunkSize - 1;
+        const range = `${resolvedSheetTitle}!${startCol}${startRow}:${endCol}${endRow}`;
+        const respChunk = await sheets.spreadsheets.values.get({
+            spreadsheetId,
+            range,
+            majorDimension: 'ROWS'
+        });
+        const vrChunk = respChunk.data;
+        const chunkRows = (vrChunk === null || vrChunk === void 0 ? void 0 : vrChunk.values) || [];
+        if (!chunkRows || chunkRows.length === 0) break;
+        for (const r of chunkRows){
+            const row = Array.isArray(r) ? r : [];
+            // Use the same key generation logic as appendRows for consistency
+            const lower = mergedHeader.map((h)=>String(h !== null && h !== void 0 ? h : '').toLowerCase());
+            const provHeaderIdx = lower.indexOf('provider');
+            let idHeaderIdx = lower.indexOf('messageid');
+            if (idHeaderIdx === -1) idHeaderIdx = lower.indexOf('id');
+            let compositeKey;
+            if (provHeaderIdx >= 0 && idHeaderIdx >= 0) {
+                var _row_providerOffset, _row_idOffset;
+                // Special case: if both provider and id columns exist, use them
+                const providerOffset = provHeaderIdx - minIdx;
+                const idOffset = idHeaderIdx - minIdx;
+                const providerVal = providerOffset >= 0 ? String((_row_providerOffset = row[providerOffset]) !== null && _row_providerOffset !== void 0 ? _row_providerOffset : '').trim() : '';
+                const messageVal = idOffset >= 0 ? String((_row_idOffset = row[idOffset]) !== null && _row_idOffset !== void 0 ? _row_idOffset : '').trim() : '';
+                compositeKey = [
+                    providerVal,
+                    messageVal
+                ].join('\\');
+            } else {
+                // General case: use the specified key columns
+                const comps = keyColsIdx.map((i)=>{
+                    var _row_;
+                    return i < 0 ? '' : String((_row_ = row[i - minIdx]) !== null && _row_ !== void 0 ? _row_ : '').trim();
+                });
+                compositeKey = comps.join('\\');
+            }
+            if (compositeKey.replace(/\\+/g, '') !== '') keySet.add(compositeKey);
+        }
+        startRow += chunkRows.length;
+    }
+    return {
+        header: mergedHeader,
+        keySet,
+        keyColumnsIdx: keyColsIdx
+    };
+}

package/dist/esm/spreadsheet/sheet-operations.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/servers/mcp-sheets/src/spreadsheet/sheet-operations.ts"],"sourcesContent":["import type { sheets_v4 } from 'googleapis';\nimport type { Logger } from '../types.js';\nimport { a1Col } from './column-utilities.js';\n\ntype ValueRange = sheets_v4.Schema$ValueRange;\n\nexport async function ensureSheetIfNeeded(sheets: sheets_v4.Sheets, id: string, sheetTitle: string, ensureSheet: boolean, headers: string[] | undefined, logger: Logger) {\n  if (!sheetTitle) return { sheetCreated: false };\n  const ssResp = await sheets.spreadsheets.get({ spreadsheetId: id });\n  const ss = ssResp.data;\n  const has = Array.isArray(ss?.sheets) && ss.sheets.some((s) => s?.properties?.title === sheetTitle);\n  if (has) {\n    const sid = ss.sheets?.find((s) => s?.properties?.title === sheetTitle)?.properties?.sheetId;\n    const result: { sheetCreated: boolean; sheetGUID?: string; headersEnsured?: boolean } = { sheetCreated: false };\n    if (sid != null) result.sheetGUID = String(sid);\n    if (headers) {\n      try {\n        const { header: merged } = await ensureTabAndHeaders(sheets, { spreadsheetId: id, sheetTitle, requiredHeader: headers, logger });\n        if (merged) result.headersEnsured = true;\n      } catch (e) {\n        logger.warn?.('ensureTabAndHeaders after sheet creation failed', e as Record<string, unknown>);\n      }\n    }\n    return result;\n  }\n  if (!ensureSheet) return { sheetCreated: false };\n\n  const res = await sheets.spreadsheets.batchUpdate({ spreadsheetId: id, requestBody: { requests: [{ addSheet: { properties: { title: sheetTitle } } }] } });\n  const createdId = res.data?.replies?.[0]?.addSheet?.properties?.sheetId;\n  const result: { sheetCreated: boolean; sheetGUID?: string; headersEnsured?: boolean } = { sheetCreated: !!createdId };\n  if (createdId != null) result.sheetGUID = String(createdId);\n  if (createdId && headers) {\n    try {\n      const { header: merged } = await ensureTabAndHeaders(sheets, { spreadsheetId: id, sheetTitle, requiredHeader: headers, logger });\n      if (merged) result.headersEnsured = true;\n    } catch (e) {\n      logger.warn?.('ensureTabAndHeaders after sheet creation failed', e as Record<string, unknown>);\n    }\n  }\n  return result;\n}\n\nexport async function findSheetByRef(client: sheets_v4.Sheets, spreadsheetId: string, sheetRef: string, logger: Logger) {\n  const ssResp = await client.spreadsheets.get({ spreadsheetId });\n  const sheets = ssResp.data?.sheets || [];\n  const trimmedRef = sheetRef?.trim();\n\n  logger.debug?.('findSheetByRef called', {\n    spreadsheetId,\n    sheetRef,\n    trimmedRef,\n    availableSheets: sheets.map((s) => ({\n      title: s?.properties?.title,\n      id: s?.properties?.sheetId,\n    })),\n  });\n\n  if (!trimmedRef) {\n    logger.warn?.('findSheetByRef empty sheetRef');\n    return null;\n  }\n\n  // Strategy 1: Try exact title match first (most common case)\n  const exactTitleMatch = sheets.find((s) => s?.properties?.title === trimmedRef);\n  if (exactTitleMatch) {\n    logger.debug?.('findSheetByRef exact title match found');\n    return exactTitleMatch;\n  }\n\n  // Strategy 2: Try exact GUID match (for when user passes actual sheet ID)\n  const exactGuidMatch = sheets.find((s) => String(s?.properties?.sheetId) === trimmedRef);\n  if (exactGuidMatch) {\n    logger.debug?.('findSheetByRef exact GUID match found');\n    return exactGuidMatch;\n  }\n\n  // Strategy 3: Case-insensitive title match\n  const caseInsensitiveMatch = sheets.find((s) => s?.properties?.title?.toLowerCase() === trimmedRef.toLowerCase());\n  if (caseInsensitiveMatch) {\n    logger.debug?.('findSheetByRef case-insensitive title match found');\n    return caseInsensitiveMatch;\n  }\n\n  // Strategy 4: Trimmed title match (handles extra whitespace in sheet names)\n  const trimmedTitleMatch = sheets.find((s) => s?.properties?.title?.trim() === trimmedRef);\n  if (trimmedTitleMatch) {\n    logger.debug?.('findSheetByRef trimmed title match found');\n    return trimmedTitleMatch;\n  }\n\n  // Strategy 5: Case-insensitive + trimmed title match\n  const caseInsensitiveTrimmedMatch = sheets.find((s) => s?.properties?.title?.trim().toLowerCase() === trimmedRef.toLowerCase());\n  if (caseInsensitiveTrimmedMatch) {\n    logger.debug?.('findSheetByRef case-insensitive trimmed title match found');\n    return caseInsensitiveTrimmedMatch;\n  }\n\n  // Strategy 6: Partial title match (last resort)\n  const partialMatch = sheets.find((s) => s?.properties?.title?.toLowerCase().includes(trimmedRef.toLowerCase()));\n  if (partialMatch) {\n    logger.debug?.('findSheetByRef partial title match found');\n    return partialMatch;\n  }\n\n  logger.warn?.('findSheetByRef no match found', {\n    searchRef: trimmedRef,\n    availableTitles: sheets.map((s) => s?.properties?.title),\n    availableIds: sheets.map((s) => s?.properties?.sheetId),\n  });\n  return null;\n}\n\n// Overloaded function signatures\nexport async function ensureTabAndHeaders(sheets: sheets_v4.Sheets, params: { spreadsheetId: string; sheetTitle: string; requiredHeader?: string[] | null; keyColumns?: string[]; logger: Logger }): Promise<{ header: string[]; keySet: Set<string>; keyColumnsIdx?: number[] }>;\n\nexport async function ensureTabAndHeaders(sheets: sheets_v4.Sheets, params: { spreadsheetId: string; sheetRef: string; requiredHeader?: string[] | null; keyColumns?: string[]; logger: Logger }): Promise<{ header: string[]; keySet: Set<string>; keyColumnsIdx?: number[] }>;\n\nexport async function ensureTabAndHeaders(\n  sheets: sheets_v4.Sheets,\n  {\n    spreadsheetId,\n    sheetTitle,\n    sheetRef,\n    requiredHeader = null as string[] | null,\n    keyColumns = ['id'] as string[],\n    logger,\n  }: {\n    spreadsheetId: string;\n    sheetTitle?: string;\n    sheetRef?: string;\n    requiredHeader?: string[] | null;\n    keyColumns?: string[];\n    logger: Logger;\n  }\n) {\n  if (!sheets) throw new Error('ensureTabAndHeaders: sheets is required');\n  if (!spreadsheetId) throw new Error('ensureTabAndHeaders: spreadsheetId is required');\n  if (!sheetTitle && !sheetRef) throw new Error('ensureTabAndHeaders: either sheetTitle or sheetRef is required');\n\n  // Resolve the actual sheet title from sheetRef if provided\n  let resolvedSheetTitle = sheetTitle;\n  if (sheetRef) {\n    const sheet = await findSheetByRef(sheets, spreadsheetId, sheetRef, logger);\n    if (sheet) {\n      resolvedSheetTitle = sheet.properties?.title || sheetRef;\n    } else {\n      // Sheet doesn't exist, use the sheetRef as the title for creation\n      resolvedSheetTitle = sheetRef;\n    }\n  }\n\n  if (!resolvedSheetTitle) throw new Error('ensureTabAndHeaders: could not resolve sheet title');\n\n  const defaultHeader = ['id', 'provider', 'threadId', 'to', 'from', 'cc', 'bcc', 'date', 'subject', 'labels', 'snippet', 'body'];\n  const header = Array.isArray(requiredHeader) && requiredHeader.length ? requiredHeader : defaultHeader;\n\n  let existingHeader: string[] | null = null;\n  try {\n    const resp = await sheets.spreadsheets.values.get({ spreadsheetId, range: `${resolvedSheetTitle}!1:1`, majorDimension: 'ROWS' });\n    const vr = resp.data as ValueRange;\n    const values = ((vr?.values || [])[0] || []) as string[];\n    existingHeader = values.length ? values : null;\n  } catch (_err: unknown) {\n    try {\n      await sheets.spreadsheets.batchUpdate({ spreadsheetId, requestBody: { requests: [{ addSheet: { properties: { title: resolvedSheetTitle } } }] } });\n    } catch {}\n    await sheets.spreadsheets.values.append({ spreadsheetId, range: `${resolvedSheetTitle}!A1`, valueInputOption: 'RAW', insertDataOption: 'INSERT_ROWS', requestBody: { values: [header] } });\n    return { header, keySet: new Set<string>() };\n  }\n\n  if (!existingHeader) {\n    await sheets.spreadsheets.values.append({ spreadsheetId, range: `${resolvedSheetTitle}!A1`, valueInputOption: 'RAW', insertDataOption: 'INSERT_ROWS', requestBody: { values: [header] } });\n    return { header, keySet: new Set<string>() };\n  }\n\n  const mergedHeader = existingHeader.slice();\n  for (const col of header) if (!mergedHeader.includes(col)) mergedHeader.push(col);\n\n  if (Array.isArray(keyColumns)) {\n    for (const name of keyColumns) {\n      if (typeof name !== 'string' || name.length === 0) throw new Error('ensureTabAndHeaders: keyColumns must be an array of non-empty strings');\n      if (!mergedHeader.includes(name)) mergedHeader.push(name);\n    }\n  }\n\n  if (mergedHeader.length !== existingHeader.length) {\n    await sheets.spreadsheets.values.update({ spreadsheetId, range: `${resolvedSheetTitle}!1:1`, valueInputOption: 'RAW', requestBody: { values: [mergedHeader] } });\n  }\n\n  const keySet = new Set<string>();\n  const chunkSize = 1000;\n  let startRow = 2;\n\n  const normalizeKeyColumnsByName = (kc: string[], hdr: string[]) => {\n    if (!Array.isArray(kc) || kc.length === 0) return [] as number[];\n    return kc.map((name) => {\n      if (typeof name !== 'string' || name.length === 0) return -1;\n      const idx = hdr.indexOf(name);\n      return Number.isInteger(idx) && idx >= 0 ? idx : -1;\n    });\n  };\n\n  const keyColsIdx = normalizeKeyColumnsByName(keyColumns, mergedHeader);\n  const validKeyIdxs = keyColsIdx.filter((i) => i >= 0);\n  if (validKeyIdxs.length === 0) return { header: mergedHeader, keySet: new Set<string>(), keyColumnsIdx: keyColsIdx };\n\n  const minIdx = Math.min(...validKeyIdxs);\n  const maxIdx = Math.max(...validKeyIdxs);\n  const startCol = a1Col(minIdx + 1);\n  const endCol = a1Col(maxIdx + 1);\n\n  while (true) {\n    const endRow = startRow + chunkSize - 1;\n    const range = `${resolvedSheetTitle}!${startCol}${startRow}:${endCol}${endRow}`;\n    const respChunk = await sheets.spreadsheets.values.get({ spreadsheetId, range, majorDimension: 'ROWS' });\n    const vrChunk = respChunk.data as ValueRange;\n    const chunkRows = (vrChunk?.values || []) as string[][];\n    if (!chunkRows || chunkRows.length === 0) break;\n    for (const r of chunkRows) {\n      const row = Array.isArray(r) ? r : [];\n\n      // Use the same key generation logic as appendRows for consistency\n      const lower = mergedHeader.map((h) => String(h ?? '').toLowerCase());\n      const provHeaderIdx = lower.indexOf('provider');\n      let idHeaderIdx = lower.indexOf('messageid');\n      if (idHeaderIdx === -1) idHeaderIdx = lower.indexOf('id');\n\n      let compositeKey: string;\n\n      if (provHeaderIdx >= 0 && idHeaderIdx >= 0) {\n        // Special case: if both provider and id columns exist, use them\n        const providerOffset = provHeaderIdx - minIdx;\n        const idOffset = idHeaderIdx - minIdx;\n        const providerVal = providerOffset >= 0 ? String(row[providerOffset] ?? '').trim() : '';\n        const messageVal = idOffset >= 0 ? String(row[idOffset] ?? '').trim() : '';\n        compositeKey = [providerVal, messageVal].join('\\\\');\n      } else {\n        // General case: use the specified key columns\n        const comps = keyColsIdx.map((i) => (i < 0 ? '' : String(row[i - minIdx] ?? '').trim()));\n        compositeKey = comps.join('\\\\');\n      }\n\n      if (compositeKey.replace(/\\\\+/g, '') !== '') keySet.add(compositeKey);\n    }\n    startRow += chunkRows.length;\n  }\n  return { header: mergedHeader, keySet, keyColumnsIdx: keyColsIdx };\n}\n"],"names":["a1Col","ensureSheetIfNeeded","sheets","id","sheetTitle","ensureSheet","headers","logger","res","sheetCreated","ssResp","spreadsheets","get","spreadsheetId","ss","data","has","Array","isArray","some","s","properties","title","sid","find","sheetId","result","sheetGUID","String","header","merged","ensureTabAndHeaders","requiredHeader","headersEnsured","e","warn","batchUpdate","requestBody","requests","addSheet","createdId","replies","findSheetByRef","client","sheetRef","trimmedRef","trim","debug","availableSheets","map","exactTitleMatch","exactGuidMatch","caseInsensitiveMatch","toLowerCase","trimmedTitleMatch","caseInsensitiveTrimmedMatch","partialMatch","includes","searchRef","availableTitles","availableIds","keyColumns","Error","resolvedSheetTitle","sheet","defaultHeader","length","existingHeader","resp","values","range","majorDimension","vr","_err","append","valueInputOption","insertDataOption","keySet","Set","mergedHeader","slice","col","push","name","update","chunkSize","startRow","normalizeKeyColumnsByName","kc","hdr","idx","indexOf","Number","isInteger","keyColsIdx","validKeyIdxs","filter","i","keyColumnsIdx","minIdx","Math","min","maxIdx","max","startCol","endCol","endRow","respChunk","vrChunk","chunkRows","r","row","lower","h","provHeaderIdx","idHeaderIdx","compositeKey","providerOffset","idOffset","providerVal","messageVal","join","comps","replace","add"],"mappings":"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"}

package/dist/esm/spreadsheet/spreadsheet-management.d.ts

@@ -0,0 +1,21 @@
+import type { drive_v3, sheets_v4 } from 'googleapis';
+export declare const SPREADSHEET_URL_RE: RegExp;
+export declare const SPREADSHEET_ID_RE: RegExp;
+export declare function findById(sheets: sheets_v4.Sheets, drive: drive_v3.Drive, id: string): Promise<{
+    id: string;
+    spreadsheetTitle: any;
+    url: any;
+    modifiedTime: any;
+}>;
+export declare function findByName(drive: drive_v3.Drive, name: string): Promise<{
+    id: string;
+    spreadsheetTitle: string;
+    url: string;
+    modifiedTime: string;
+}[]>;
+export declare function findSpreadsheetsByRef(sheets: sheets_v4.Sheets, drive: drive_v3.Drive, ref: string): Promise<{
+    id: string;
+    spreadsheetTitle: any;
+    url: any;
+    modifiedTime: any;
+}[]>;

package/dist/esm/spreadsheet/spreadsheet-management.js

@@ -0,0 +1,73 @@
+export const SPREADSHEET_URL_RE = /https:\/\/docs.google.com\/spreadsheets\/d\/([a-zA-Z0-9-_]{10,})/;
+export const SPREADSHEET_ID_RE = /^[a-zA-Z0-9-_]{30,}$/;
+export async function findById(sheets, drive, id) {
+    var _ref, _ref1;
+    var _ss_properties;
+    const ssResp = await sheets.spreadsheets.get({
+        spreadsheetId: id
+    }).catch((e)=>{
+        var _error_response;
+        const error = e;
+        const status = (error === null || error === void 0 ? void 0 : (_error_response = error.response) === null || _error_response === void 0 ? void 0 : _error_response.status) || (error === null || error === void 0 ? void 0 : error.status) || (error === null || error === void 0 ? void 0 : error.code);
+        if (Number(status) === 404) return null;
+        throw e;
+    });
+    const dmResp = await drive.files.get({
+        fileId: id,
+        fields: 'modifiedTime,webViewLink,name'
+    }).catch((e)=>{
+        var _error_response;
+        const error = e;
+        const status = (error === null || error === void 0 ? void 0 : (_error_response = error.response) === null || _error_response === void 0 ? void 0 : _error_response.status) || (error === null || error === void 0 ? void 0 : error.status) || (error === null || error === void 0 ? void 0 : error.code);
+        if (Number(status) === 404) return null;
+        throw e;
+    });
+    const dm = dmResp === null || dmResp === void 0 ? void 0 : dmResp.data;
+    if (!ssResp) return null;
+    const ss = ssResp.data;
+    return {
+        id: id,
+        spreadsheetTitle: (_ref = ss === null || ss === void 0 ? void 0 : (_ss_properties = ss.properties) === null || _ss_properties === void 0 ? void 0 : _ss_properties.title) !== null && _ref !== void 0 ? _ref : dm === null || dm === void 0 ? void 0 : dm.name,
+        url: (_ref1 = ss === null || ss === void 0 ? void 0 : ss.spreadsheetUrl) !== null && _ref1 !== void 0 ? _ref1 : dm === null || dm === void 0 ? void 0 : dm.webViewLink,
+        modifiedTime: dm === null || dm === void 0 ? void 0 : dm.modifiedTime
+    };
+}
+export async function findByName(drive, name) {
+    var _resp_data;
+    const escaped = String(name).replace(/['"\\]/g, (m)=>`\\${m}`);
+    const q = `mimeType='application/vnd.google-apps.spreadsheet' and name contains '${escaped}' and trashed = false`;
+    const resp = await drive.files.list({
+        q,
+        pageSize: 50,
+        fields: 'files(id,name,webViewLink,modifiedTime)'
+    });
+    const files = ((_resp_data = resp.data) === null || _resp_data === void 0 ? void 0 : _resp_data.files) || [];
+    return files.map((f)=>({
+            id: String(f.id),
+            spreadsheetTitle: String(f.name),
+            url: String(f.webViewLink),
+            modifiedTime: f.modifiedTime
+        }));
+}
+export async function findSpreadsheetsByRef(sheets, drive, ref) {
+    const trimmedRef = ref === null || ref === void 0 ? void 0 : ref.trim();
+    if (!trimmedRef) return [];
+    // Strategy 1: Try URL extraction (most specific)
+    const urlMatch = trimmedRef.match(SPREADSHEET_URL_RE);
+    if (urlMatch && typeof urlMatch[1] === 'string' && urlMatch[1].length > 0) {
+        const id = urlMatch[1];
+        const r = await findById(sheets, drive, id);
+        return r ? [
+            r
+        ] : [];
+    }
+    // Strategy 2: Try direct ID match (if it looks like a spreadsheet ID)
+    if (SPREADSHEET_ID_RE.test(trimmedRef)) {
+        const r = await findById(sheets, drive, trimmedRef);
+        return r ? [
+            r
+        ] : [];
+    }
+    // Strategy 3: Search by name
+    return await findByName(drive, trimmedRef);
+}