@ianmaleney/sheets-api-helper 1.0.0

package/AUTH_IMPLEMENTATION.md

@@ -0,0 +1,109 @@
+# Google Sheets API Authentication Flow - Implementation Summary
+
+## ✅ What's Been Created
+
+### 1. **Production-Ready Authentication System** ([index.js](index.js))
+
+#### Core Functions:
+
+**`initializeAuth()`**
+- Initializes the Google Sheets API client using service account credentials
+- Loads credentials from `service_key.json`
+- Implements caching to avoid re-authentication
+- Error handling with clear error messages
+
+**`getSheetData(spreadsheetId, range)`**
+- Fetches data from a single spreadsheet range
+- Automatically initializes auth if needed
+- Returns rows as an array
+- Returns empty array if no data found
+- Includes error handling
+
+**`getMultipleRanges(spreadsheetId, ranges)`**
+- Efficiently fetches multiple ranges in one API call
+- Returns object with ranges as keys
+- Better performance for bulk reads
+
+### 2. **Setup Guide** ([SETUP.md](SETUP.md))
+Comprehensive documentation including:
+- Prerequisites
+- Step-by-step setup instructions
+- How to create a service account
+- How to share spreadsheets with the service account
+- Usage examples
+- Troubleshooting guide
+
+### 3. **Verification Script** ([setup-check.js](setup-check.js))
+Automated setup checker that verifies:
+- ✓ service_key.json exists and is valid
+- ✓ Environment variables are set
+- ✓ Dependencies are installed
+- ✓ .gitignore is properly configured
+
+### 4. **Tests** ([index.test.js](index.test.js))
+- Runs authentication before tests
+- Integration test that verifies API connectivity
+- Uses Bun's test framework
+
+### 5. **Security** ([.gitignore](.gitignore))
+- Added `service_key.json` to .gitignore
+- Added credential files to ignore list
+- Prevents accidentally committing sensitive data
+
+## 🚀 How to Use
+
+### Initial Setup
+```bash
+# 1. Add your service account key
+cp your-service-account-key.json service_key.json
+
+# 2. Update environment variables
+echo "TEST_SHEET_ID=your_spreadsheet_id" >> .env
+
+# 3. Share the spreadsheet with the service account email
+# (Email is in service_key.json under "client_email")
+
+# 4. Verify setup
+node setup-check.js
+
+# 5. Run tests
+bun test
+```
+
+### In Your Code
+```javascript
+import { initializeAuth, getSheetData } from './index.js';
+
+// Initialize once at app startup
+await initializeAuth();
+
+// Then fetch data anytime
+const rows = await getSheetData('spreadsheet-id', 'Sheet1!A1:D10');
+```
+
+## 🔑 Key Features
+
+- **Service Account Authentication**: Uses service accounts for secure, non-interactive access
+- **Automatic Initialization**: Auth is automatically initialized on first data fetch
+- **Caching**: Client is cached to avoid re-authentication
+- **Error Handling**: Clear error messages for debugging
+- **Batch Fetching**: Support for multiple ranges in one call
+- **Type Safety**: JSDoc comments for all functions
+
+## ⚠️ Common Issues & Solutions
+
+**"The caller does not have permission"**
+- Share the spreadsheet with the service account email (found in service_key.json)
+
+**"Service key not found"**
+- Ensure service_key.json is in the project root
+
+**Slow Initial Load**
+- First authentication takes a few seconds - this is normal
+
+## 📝 Next Steps
+
+1. Follow the [SETUP.md](SETUP.md) guide to complete configuration
+2. Run `node setup-check.js` to verify everything is set up correctly
+3. Run `bun test` to test the connection
+4. Start using `getSheetData()` in your application

package/README.md

@@ -0,0 +1,185 @@
+# Google Sheets API - Complete Authentication Flow
+
+A production-ready authentication system for accessing Google Sheets data using service account credentials.
+
+## 🎯 What This Provides
+
+✅ **Service Account Authentication** - Secure, non-interactive API access  
+✅ **Automatic Initialization** - Auth is set up automatically on first use  
+✅ **Cached Client** - Avoids re-authentication for every request  
+✅ **Error Handling** - Clear error messages for debugging  
+✅ **Batch Operations** - Fetch multiple ranges efficiently  
+✅ **Integration Tests** - Verify API connectivity  
+✅ **Setup Verification** - Script to check your configuration  
+
+## 📁 Project Structure
+
+```
+.
+├── index.js                    # Main API implementation
+├── index.test.js              # Integration tests
+├── example.js                 # Usage examples
+├── setup-check.js             # Configuration verification script
+├── SETUP.md                   # Detailed setup guide
+├── AUTH_IMPLEMENTATION.md     # Implementation details
+├── README.md                  # This file
+├── .env                       # Environment variables (contains TEST_SHEET_ID)
+├── .gitignore                 # Git ignore (keeps credentials safe)
+├── service_key.json           # Service account key (DO NOT COMMIT)
+└── package.json               # Project dependencies
+```
+
+## 🚀 Quick Start
+
+### 1. Verify Setup
+```bash
+node setup-check.js
+```
+
+This will check:
+- ✓ service_key.json exists and is valid
+- ✓ TEST_SHEET_ID is set in .env
+- ✓ Dependencies are installed
+- ✓ Credentials are not committed to git
+
+### 2. Share Your Spreadsheet
+
+1. Get the service account email from the output above
+2. Open your Google Sheet
+3. Click **Share**
+4. Paste the service account email
+5. Give it **Viewer** access (or **Editor** if needed)
+
+### 3. Run Example
+```bash
+bun run example.js
+```
+
+### 4. Run Tests
+```bash
+bun test
+```
+
+## 📖 API Reference
+
+### `initializeAuth()`
+Initialize the Google Sheets API client. Call this once at app startup.
+
+```javascript
+import { initializeAuth } from './index.js';
+
+await initializeAuth();
+```
+
+### `getSheetData(spreadsheetId, range)`
+Fetch data from a single spreadsheet range.
+
+```javascript
+const rows = await getSheetData(
+  '1ZEs6v0-izIyVNFdBb7B4PXOGXsdsjuTq0tAXJBg_kDU',
+  'Sheet1!A1:D10'
+);
+
+console.log(rows); // Array of rows
+```
+
+### `getMultipleRanges(spreadsheetId, ranges)`
+Fetch multiple ranges efficiently in one API call.
+
+```javascript
+const data = await getMultipleRanges(
+  '1ZEs6v0-izIyVNFdBb7B4PXOGXsdsjuTq0tAXJBg_kDU',
+  ['Sheet1!A1:D10', 'Sheet2!A1:B5']
+);
+
+console.log(data['Sheet1!A1:D10']); // Array of rows
+console.log(data['Sheet2!A1:B5']);  // Array of rows
+```
+
+## 🔧 Configuration
+
+### Environment Variables (.env)
+```env
+TEST_SHEET_ID=your_spreadsheet_id
+```
+
+Get your spreadsheet ID from the URL:
+```
+https://docs.google.com/spreadsheets/d/{SPREADSHEET_ID}/edit
+```
+
+### Service Key (service_key.json)
+Your Google Cloud service account JSON key. Already in `.gitignore` to prevent accidental commits.
+
+## 🐛 Troubleshooting
+
+### "The caller does not have permission"
+**Cause:** Spreadsheet not shared with service account
+
+**Solution:**
+1. Get service account email from `service_key.json` → `client_email`
+2. Share the spreadsheet with this email
+3. Grant at least **Viewer** access
+
+### "Service key not found"
+**Cause:** `service_key.json` not in project root
+
+**Solution:**
+1. Download your service account key from Google Cloud Console
+2. Save it as `service_key.json` in the project root
+3. Never commit it (already in `.gitignore`)
+
+### Authentication Timeout
+**Cause:** Normal for first request
+
+**Solution:** This is expected. Subsequent requests are faster due to caching.
+
+### No data returned
+**Cause:** Empty sheet or invalid range
+
+**Solution:**
+- Check that the range contains data
+- Verify spreadsheet ID is correct
+- Try a different range like `Sheet1!A1:Z100`
+
+## 📚 More Information
+
+- **Setup Instructions**: See [SETUP.md](SETUP.md)
+- **Implementation Details**: See [AUTH_IMPLEMENTATION.md](AUTH_IMPLEMENTATION.md)
+- **Code Examples**: See [example.js](example.js)
+- **Google Sheets API Docs**: [https://developers.google.com/sheets/api](https://developers.google.com/sheets/api)
+
+## 🔐 Security
+
+- ✓ `service_key.json` is in `.gitignore`
+- ✓ Credentials never logged in production
+- ✓ Uses Google Cloud's official libraries
+- ✓ Service account is recommended over user authentication
+- ✓ Use environment variables for sensitive data
+
+## 🔄 Workflow Summary
+
+```javascript
+// 1. Import once in your app
+import { initializeAuth, getSheetData } from './index.js';
+
+// 2. Initialize once at startup
+await initializeAuth();
+
+// 3. Use anytime, anywhere
+const rows = await getSheetData('spreadsheet-id', 'Sheet1!A1:D10');
+```
+
+## 💡 Tips
+
+- **Batch Reads**: Use `getMultipleRanges()` instead of multiple `getSheetData()` calls
+- **Range Format**: Use A1 notation like `Sheet1!A1:D10` or `'Sheet1'!A1:D10`
+- **Large Datasets**: For very large sheets, consider using pagination
+- **Caching**: The auth client is cached automatically - no need to reinitialize
+
+## 🤝 Need Help?
+
+1. Run `node setup-check.js` to verify configuration
+2. Check [SETUP.md](SETUP.md) for detailed instructions
+3. See [example.js](example.js) for working code
+4. Review error messages - they indicate the exact issue

package/SETUP.md

@@ -0,0 +1,114 @@
+# Google Sheets API Setup Guide
+
+## Overview
+This project provides a working authentication flow for the Google Sheets API using service account credentials.
+
+## Prerequisites
+- A Google Cloud Project with the Sheets API enabled
+- Service account key (JSON file)
+
+## Setup Steps
+
+### 1. Create a Service Account (if you haven't already)
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com)
+2. Create a new project or select an existing one
+3. Navigate to **Service Accounts** (Search for "Service Accounts")
+4. Click **Create Service Account**
+5. Fill in the service account details
+6. Click **Create and Continue**
+7. Grant the service account "Editor" role (or minimal "Sheets Editor" role)
+8. Click **Create Key** and select **JSON** format
+9. Save the JSON file as `service_key.json` in the root of this project
+
+### 2. Share Your Spreadsheet with the Service Account
+
+1. Open the spreadsheet you want to access
+2. Get your spreadsheet ID from the URL: `https://docs.google.com/spreadsheets/d/{SPREADSHEET_ID}/edit`
+3. Click **Share** on the spreadsheet
+4. In the service account JSON file, find the `client_email` field
+5. Share the spreadsheet with this email address
+6. Grant it **Viewer** access (or **Editor** if you need write permissions)
+
+### 3. Set Environment Variables
+
+Create or update `.env` file:
+
+```
+TEST_SHEET_ID=your_spreadsheet_id_here
+```
+
+## Usage
+
+### Basic Usage
+
+```javascript
+import { initializeAuth, getSheetData } from './index.js';
+
+// Initialize authentication (call once at app startup)
+await initializeAuth();
+
+// Fetch data from a specific range
+const data = await getSheetData('your-spreadsheet-id', 'Sheet1!A1:D10');
+console.log(data);
+```
+
+### Get Multiple Ranges
+
+```javascript
+import { initializeAuth, getMultipleRanges } from './index.js';
+
+await initializeAuth();
+
+const data = await getMultipleRanges('your-spreadsheet-id', [
+  'Sheet1!A1:D10',
+  'Sheet2!A1:B5'
+]);
+
+console.log(data['Sheet1!A1:D10']);
+console.log(data['Sheet2!A1:B5']);
+```
+
+## Running Tests
+
+```bash
+bun test
+```
+
+## Troubleshooting
+
+### "The caller does not have permission" Error
+- Ensure the spreadsheet is shared with the service account email
+- Check that the service account has at least **Viewer** access
+
+### "Service key not found" Error
+- Verify `service_key.json` exists in the project root
+- Check file permissions
+
+### Authentication Timeout
+- The first authentication may take a few seconds
+- Ensure your internet connection is stable
+
+## Architecture
+
+### `initializeAuth()`
+- Initializes the Google Sheets API client once
+- Uses service account credentials from `service_key.json`
+- Caches the client for subsequent calls
+
+### `getSheetData(spreadsheetId, range)`
+- Fetches data from a single range
+- Returns an array of rows
+- Returns empty array if no data found
+
+### `getMultipleRanges(spreadsheetId, ranges)`
+- Fetches data from multiple ranges in one call
+- Returns an object with ranges as keys and data as values
+- More efficient for bulk reads
+
+## Security Notes
+
+- **Never commit** `service_key.json` to version control
+- Add `service_key.json` to `.gitignore` (already done)
+- Rotate service account keys regularly
+- Use environment variables for sensitive data

package/example.js

@@ -0,0 +1,59 @@
+/**
+ * Example: Using the Google Sheets API
+ * 
+ * Before running this file:
+ * 1. Ensure service_key.json is in the project root
+ * 2. Share your spreadsheet with the service account email
+ * 3. Set your spreadsheet ID in .env
+ */
+
+import 'dotenv/config';
+import { initializeAuth, getSheetData, getMultipleRanges } from './index.js';
+
+async function main() {
+  try {
+    // Initialize authentication
+    console.log('Initializing authentication...\n');
+    await initializeAuth();
+
+    // Example 1: Get data from a single range
+    console.log('📊 Fetching data from Sheet1!A1:D10...');
+    const data = await getSheetData(
+      process.env.TEST_SHEET_ID,
+      'Sheet1!A1:D10'
+    );
+    
+    if (data.length > 0) {
+      console.log(`✓ Retrieved ${data.length} rows`);
+      console.log('First row:', data[0]);
+    } else {
+      console.log('No data found in range');
+    }
+
+    // Example 2: Get multiple ranges (if you have multiple sheets)
+    // Uncomment to test:
+    /*
+    console.log('\n📊 Fetching multiple ranges...');
+    const multiData = await getMultipleRanges(
+      process.env.TEST_SHEET_ID,
+      ['Sheet1!A1:D10', 'Sheet2!A1:B5']
+    );
+    
+    console.log('Sheet1 data:', multiData['Sheet1!A1:D10']);
+    console.log('Sheet2 data:', multiData['Sheet2!A1:B5']);
+    */
+
+  } catch (error) {
+    console.error('❌ Error:', error.message);
+    
+    if (error.message.includes('The caller does not have permission')) {
+      console.log('\n💡 Solution: Share your spreadsheet with this email:');
+      console.log('   sheets@eco-emissary-484012-i1.iam.gserviceaccount.com');
+      console.log('   (Email from service_key.json client_email field)');
+    }
+    
+    process.exit(1);
+  }
+}
+
+main();

package/index.js

@@ -0,0 +1,105 @@
+import { google } from 'googleapis';
+import path from 'node:path';
+import process from 'node:process';
+import fs from 'node:fs';
+
+const SCOPES = ['https://www.googleapis.com/auth/spreadsheets.readonly'];
+let sheetsClient = null;
+
+/**
+ * Initialize the Google Sheets API client using service account credentials
+ * @returns {Promise<void>}
+ */
+export const initializeAuth = async () => {
+  if (sheetsClient) {
+    return; // Already initialized
+  }
+
+  try {
+    const keyPath = path.join(process.cwd(), 'service_key.json');
+    
+    if (!fs.existsSync(keyPath)) {
+      throw new Error(`Service key not found at ${keyPath}`);
+    }
+
+    const keyData = JSON.parse(fs.readFileSync(keyPath, 'utf-8'));
+
+    const auth = new google.auth.GoogleAuth({
+      credentials: keyData,
+      scopes: SCOPES,
+    });
+
+    sheetsClient = google.sheets({
+      version: 'v4',
+      auth: auth,
+    });
+
+    console.log('✓ Google Sheets API authentication initialized successfully');
+  } catch (error) {
+    console.error('✗ Failed to initialize authentication:', error.message);
+    throw error;
+  }
+};
+
+/**
+ * Get data from a Google Sheet
+ * @param {string} spreadsheet_id - The spreadsheet ID
+ * @param {string} range - The range to read (e.g., 'Sheet1!A1:D10')
+ * @returns {Promise<Array>} Array of rows
+ */
+export const getSheetData = async (spreadsheet_id, range) => {
+  // Ensure authentication is initialized
+  if (!sheetsClient) {
+    await initializeAuth();
+  }
+
+  try {
+    // Get the values from the spreadsheet.
+    const result = await sheetsClient.spreadsheets.values.get({
+      spreadsheetId: spreadsheet_id,
+      range: range,
+    });
+
+    const rows = result.data.values;
+
+    if (!rows || rows.length === 0) {
+      console.log('No data found.');
+      return [];
+    }
+
+    return rows;
+  } catch (error) {
+    console.error(`Failed to fetch sheet data: ${error.message}`);
+    throw error;
+  }
+};
+
+/**
+ * Get multiple ranges from a Google Sheet
+ * @param {string} spreadsheet_id - The spreadsheet ID
+ * @param {Array<string>} ranges - Array of ranges to read
+ * @returns {Promise<Object>} Object with ranges as keys and data as values
+ */
+export const getMultipleRanges = async (spreadsheet_id, ranges) => {
+  if (!sheetsClient) {
+    await initializeAuth();
+  }
+
+  try {
+    const result = await sheetsClient.spreadsheets.values.batchGet({
+      spreadsheetId: spreadsheet_id,
+      ranges: ranges,
+    });
+
+    const data = {};
+    result.data.valueRanges.forEach((range, index) => {
+      data[ranges[index]] = range.values || [];
+    });
+
+    return data;
+  } catch (error) {
+    console.error(`Failed to fetch multiple ranges: ${error.message}`);
+    throw error;
+  }
+};
+

package/index.test.js

@@ -0,0 +1,23 @@
+import { describe, it, expect, beforeAll } from 'bun:test';
+import { getSheetData, initializeAuth } from './index.js';
+import 'dotenv/config';
+
+describe('getSheetData', () => {
+  beforeAll(async () => {
+    // Initialize authentication before running tests
+    await initializeAuth();
+  });
+
+  it('should return rows when data is found', async () => {
+    const result = await getSheetData(
+      process.env.TEST_SHEET_ID,
+      'Film!A1:D10'
+    );
+
+    console.log('Result:', result);
+
+    // Since the actual data in the sheet may vary, we will just check if result is an array.
+    expect(Array.isArray(result)).toBe(true);
+    expect(result.length).toBeGreaterThan(0);
+  });
+});

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@ianmaleney/sheets-api-helper",
+  "version": "1.0.0",
+  "description": "A helper library for interacting with the Google Sheets API using Node.js.",
+  "main": "index.js",
+  "author": "Ian Maleney <ian@fallowmedia.com>",
+  "license": "MIT",
+  "type": "module",
+  "dependencies": {
+    "@google-cloud/local-auth": "^2.1.0",
+    "dotenv": "^17.2.3",
+    "googleapis": "^105.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "bun test"
+  }
+}
+

package/setup-check.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+
+/**
+ * Setup verification script for Google Sheets API
+ * Run with: node setup-check.js
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+console.log('🔍 Google Sheets API Setup Verification\n');
+
+// Check 1: Service Key File
+console.log('1. Checking service_key.json...');
+const serviceKeyPath = path.join(__dirname, 'service_key.json');
+if (fs.existsSync(serviceKeyPath)) {
+  try {
+    const keyData = JSON.parse(fs.readFileSync(serviceKeyPath, 'utf-8'));
+    console.log('   ✓ service_key.json found');
+    console.log(`   ✓ Project ID: ${keyData.project_id}`);
+    console.log(`   ✓ Service Account Email: ${keyData.client_email}`);
+    
+    if (!keyData.private_key) {
+      console.log('   ✗ WARNING: private_key is missing from service_key.json');
+    }
+  } catch (e) {
+    console.log('   ✗ service_key.json is not valid JSON');
+  }
+} else {
+  console.log(`   ✗ service_key.json not found at ${serviceKeyPath}`);
+  console.log('     Run: touch service_key.json and add your credentials');
+}
+
+// Check 2: Environment Variables
+console.log('\n2. Checking environment variables...');
+const envPath = path.join(__dirname, '.env');
+if (fs.existsSync(envPath)) {
+  const envContent = fs.readFileSync(envPath, 'utf-8');
+  if (envContent.includes('TEST_SHEET_ID')) {
+    console.log('   ✓ TEST_SHEET_ID is set in .env');
+  } else {
+    console.log('   ✗ TEST_SHEET_ID is not set in .env');
+  }
+} else {
+  console.log('   ✗ .env file not found');
+}
+
+// Check 3: Dependencies
+console.log('\n3. Checking dependencies...');
+const packageJsonPath = path.join(__dirname, 'package.json');
+const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+const requiredDeps = ['googleapis', '@google-cloud/local-auth'];
+const nodeModulesPath = path.join(__dirname, 'node_modules');
+
+requiredDeps.forEach(dep => {
+  const depPath = path.join(nodeModulesPath, dep);
+  if (fs.existsSync(depPath)) {
+    console.log(`   ✓ ${dep} is installed`);
+  } else {
+    console.log(`   ✗ ${dep} is not installed`);
+    console.log('     Run: npm install or bun install');
+  }
+});
+
+// Check 4: .gitignore
+console.log('\n4. Checking .gitignore...');
+const gitignorePath = path.join(__dirname, '.gitignore');
+if (fs.existsSync(gitignorePath)) {
+  const gitignoreContent = fs.readFileSync(gitignorePath, 'utf-8');
+  if (gitignoreContent.includes('service_key.json')) {
+    console.log('   ✓ service_key.json is in .gitignore');
+  } else {
+    console.log('   ⚠ service_key.json is NOT in .gitignore');
+    console.log('   Add this line to .gitignore: service_key.json');
+  }
+} else {
+  console.log('   ⚠ .gitignore not found');
+}
+
+console.log('\n' + '='.repeat(50));
+console.log('Next Steps:');
+console.log('1. Ensure service_key.json is in the project root');
+console.log('2. Share your spreadsheet with the service account email');
+console.log('3. Set TEST_SHEET_ID in .env');
+console.log('4. Run: bun test');
+console.log('='.repeat(50));