sheets.readAsRecords — read Sheet as array of keyed objects #50
Description
Summary
Implement sheets.readAsRecords operation that reads a Google Sheet range and returns data as an array of keyed objects using the first row as column headers. Foundational for mail-merge style outreach workflows.
Context
- Repository: ~/Projects/local-mcps/gdrive
- GitHub: AojdevStudio/gdrive
- Plan Doc:
docs/plans/2026-03-10-email-outreach-features.md(Task 1) - Relevant Files: src/modules/sheets/read.ts, src/modules/sheets/index.ts, src/sdk/spec.ts, src/sdk/runtime.ts
- Related Issues: None
Current Behavior
sheets.readSheet returns raw 2D array of cell values. Users must manually map header row to data rows.
Expected Behavior
sheets.readAsRecords reads a sheet range, uses row 1 as keys, and returns rows 2+ as Record<string, string>[]. Supports optional headerRow parameter to specify a different header row.
Acceptance Criteria (max 3)
- AC-1: Returns an array of objects where keys are column headers from the first row and values are corresponding cell data
- AC-2: Handles edge cases: empty sheet returns [], mismatched column counts fill missing values with empty string
- AC-3: SDK spec and runtime registration follow existing sheets operation pattern
Scope
In scope: readAsRecords function, type definitions, SDK spec + runtime, unit tests
Out of scope: Write-back capability, data type coercion (all values returned as strings), pagination for large sheets