@ariadng/sheets 0.1.1 → 0.2.0

package/README.md

@@ -1,439 +1,566 @@
-# Sheets
+# @ariadng/sheets
 
-A pragmatic TypeScript client for Google Sheets API v4 with stellar performance, that provides essential features without over-engineering. Start simple and add complexity only when needed.
+A command-line tool and library for reading Google Sheets. Works with personal Google accounts and service accounts.
 
-## Features
+## For AI Agents
 
-- **Progressive Enhancement** - Start with core features, add more as needed
-- **Modular Packages** - Core (~3KB), Plus (~5KB), Advanced (~2KB)
-- **Smart Retry Logic** - Exponential backoff with jitter
-- **Optional Caching** - Reduce API calls with configurable TTL
-- **Type Safety** - Full TypeScript support with type utilities
-- **Rate Limiting** - Adaptive or token bucket strategies
-- **Metrics Collection** - Track performance and errors
-- **Batch Operations** - Efficient bulk reads/writes
+If you are an AI agent (Claude, GPT, Copilot, or other AI assistants), use the npx version of this tool. This allows you to run commands without installing the package globally.
 
-## Installation
+**Authentication**: Before reading spreadsheets, the user must be logged in. Check login status first, then prompt the user to login if needed.
 
 ```bash
-# Core package only
-npm install @ariadng/sheets
+# Check if user is logged in
+npx @ariadng/sheets whoami
 
-# With specific packages
-npm install @ariadng/sheets
+# If not logged in, ask user to run this command
+npx @ariadng/sheets login
 ```
 
-## Quick Start
+**Reading data**: Use `--format json` for structured output that is easier to parse.
 
-### Basic Usage
+```bash
+# Get spreadsheet metadata
+npx @ariadng/sheets get SPREADSHEET_ID --format json
 
-```typescript
-import { GoogleSheetsCore, createServiceAccountAuth } from '@ariadng/sheets/core';
+# List all sheets
+npx @ariadng/sheets list SPREADSHEET_ID --format json
 
-// Setup with service account
-const auth = await createServiceAccountAuth('./service-account-key.json');
-const sheets = new GoogleSheetsCore({ auth });
+# Read cell values
+npx @ariadng/sheets read SPREADSHEET_ID "Sheet1!A1:D10" --format json
 
-// Simple read
-const data = await sheets.read('spreadsheetId', 'Sheet1!A1:B10');
-console.log(data); // [[value1, value2], [value3, value4], ...]
+# Read formulas instead of values
+npx @ariadng/sheets read SPREADSHEET_ID "Sheet1!A1:D10" --formula --format json
+```
 
-// Simple write
-await sheets.write('spreadsheetId', 'Sheet1!A1:B2', [
-  ['Name', 'Score'],
-  ['Alice', 100]
-]);
+**Getting the spreadsheet ID**: Extract the ID from the Google Sheets URL. The URL format is `https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit`. The spreadsheet ID is the string between `/d/` and `/edit`.
+
+## What This Tool Does
+
+- Read data from Google Sheets spreadsheets
+- View spreadsheet information and sheet lists
+- Read cell values or formulas
+- Authenticate with your Google account or a service account
+
+## Requirements
+
+- Node.js version 18 or higher
+- A Google account (for personal use) or a Google Cloud service account
+
+## Installation
+
+```bash
+npm install -g @ariadng/sheets
 ```
 
-### With Caching
+After installation, the `sheets` command will be available in your terminal.
 
-```typescript
-import { withCache } from '@ariadng/sheets/plus';
+## Usage Summary
 
-const cachedSheets = withCache(sheets, {
-  ttlSeconds: 300 // 5-minute cache
-});
+| Command | Description |
+|---------|-------------|
+| `sheets login` | Login with Google account |
+| `sheets logout` | Remove saved login |
+| `sheets whoami` | Show current login status |
+| `sheets auth <file>` | Test service account credentials |
+| `sheets get <id>` | Get spreadsheet metadata |
+| `sheets list <id>` | List sheets in spreadsheet |
+| `sheets read <id> <range>` | Read cell values |
+| `sheets read <id> <range> --formula` | Read formulas |
+| `sheets read <id> <range> --format json` | Output as JSON |
 
-// First read hits API
-const data1 = await cachedSheets.read(id, 'A1:B10');
+## Using with npx
 
-// Second read uses cache (within 5 minutes)
-const data2 = await cachedSheets.read(id, 'A1:B10'); // Much faster!
+You can also run this tool without installing it:
+
+```bash
+npx @ariadng/sheets login
+npx @ariadng/sheets read SPREADSHEET_ID "Sheet1!A1:D10"
 ```
 
-### With Rate Limiting
+## Getting Started
 
-```typescript
-import { withAdaptiveRateLimit } from '@ariadng/sheets/advanced';
+### Step 1: Login to Your Google Account
 
-const rateLimitedSheets = withAdaptiveRateLimit(sheets);
+Run this command to connect your Google account:
 
-// Automatically handles rate limits
-for (let i = 0; i < 1000; i++) {
-  await rateLimitedSheets.read(id, `A${i}`);
-  // Automatically slows down if hitting limits
-}
+```bash
+sheets login
+```
+
+This will:
+1. Open your web browser
+2. Ask you to sign in to your Google account
+3. Ask you to allow the app to read your spreadsheets
+4. Save your login for future use
+
+After login, you will see your email address displayed.
+
+### Step 2: Read a Spreadsheet
+
+Find the spreadsheet ID from your Google Sheets URL. The URL looks like this:
+
+```
+https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit
+```
+
+The spreadsheet ID is the long string of letters and numbers between `/d/` and `/edit`.
+
+Now you can read data:
+
+```bash
+# Get spreadsheet information
+sheets get SPREADSHEET_ID
+
+# List all sheets in the spreadsheet
+sheets list SPREADSHEET_ID
+
+# Read cells from a range
+sheets read SPREADSHEET_ID "Sheet1!A1:D10"
 ```
 
 ## Authentication
 
-### Service Account
+This tool supports three ways to authenticate:
 
-```typescript
-import { createServiceAccountAuth } from '@ariadng/sheets/core';
+### 1. Personal Google Account (Recommended for Most Users)
 
-// From file
-const auth = await createServiceAccountAuth('./service-account.json');
+Use the `login` command to authenticate with your personal Google account:
 
-// From object
-const auth = await createServiceAccountAuth({
-  client_email: 'your-service-account@project.iam.gserviceaccount.com',
-  private_key: '-----BEGIN PRIVATE KEY-----...',
-  // ... other fields
-});
+```bash
+sheets login
 ```
 
-### OAuth2
+Your login will be saved and used automatically for future commands. To check your login status:
 
-```typescript
-import { createOAuth2Client, generateAuthUrl, getTokenFromCode } from '@ariadng/sheets/core';
+```bash
+sheets whoami
+```
 
-const client = await createOAuth2Client({
-  client_id: 'your-client-id',
-  client_secret: 'your-client-secret',
-  redirect_uris: ['http://localhost:3000/callback']
-});
+To remove your saved login:
+
+```bash
+sheets logout
+```
+
+### 2. Service Account (For Automated Systems)
+
+Service accounts are special Google accounts for applications and scripts. To use a service account:
 
-// Generate auth URL
-const authUrl = generateAuthUrl(client);
-console.log('Visit:', authUrl);
+1. Create a service account in Google Cloud Console
+2. Download the JSON credentials file
+3. Share your spreadsheet with the service account email address
+4. Use the `--credentials` option with commands:
 
-// After user authorizes, exchange code for token
-const tokens = await getTokenFromCode(client, authorizationCode);
+```bash
+sheets get SPREADSHEET_ID --credentials path/to/credentials.json
 ```
 
-## Core Features
+To test if your service account credentials are valid:
 
-### CRUD Operations
+```bash
+sheets auth path/to/credentials.json
+```
 
-```typescript
-// Read
-const values = await sheets.read(spreadsheetId, 'Sheet1!A1:C10');
+### 3. Access Token (For Advanced Use)
 
-// Write (replaces existing data)
-await sheets.write(spreadsheetId, 'Sheet1!A1:C3', [
-  ['Header1', 'Header2', 'Header3'],
-  ['Value1', 'Value2', 'Value3']
-]);
+If you have an OAuth access token, you can use it directly:
 
-// Append (adds to end)
-await sheets.append(spreadsheetId, 'Sheet1!A:C', [
-  ['New1', 'New2', 'New3']
-]);
+```bash
+sheets get SPREADSHEET_ID --token YOUR_ACCESS_TOKEN
+```
+
+## CLI Commands Reference
+
+### Authentication Commands
 
-// Clear
-await sheets.clear(spreadsheetId, 'Sheet1!A1:C10');
+#### sheets login
+
+Connect your Google account.
+
+```bash
+sheets login
 ```
 
-### Batch Operations
+Options:
+- `--client <file>`: Use custom OAuth client credentials (optional)
 
-```typescript
-// Batch read multiple ranges
-const results = await sheets.batchRead(spreadsheetId, [
-  'Sheet1!A1:B10',
-  'Sheet2!C1:D5'
-]);
+What happens:
+1. Opens your browser to Google sign-in page
+2. Starts a local server on port 8085 to receive the response
+3. Saves your tokens to `~/.sheets/tokens.json`
 
-// Batch write multiple ranges
-await sheets.batchWrite(spreadsheetId, [
-  { range: 'Sheet1!A1:B2', values: [['A', 'B'], ['C', 'D']] },
-  { range: 'Sheet2!A1:B2', values: [['E', 'F'], ['G', 'H']] }
-]);
+#### sheets logout
+
+Remove your saved login.
+
+```bash
+sheets logout
 ```
 
-## Plus Package Features
+This deletes the stored tokens from your computer.
 
-### Type Utilities
+#### sheets whoami
 
-```typescript
-import { A1, TypedSheets, Parsers, Serializers } from '@ariadng/sheets/plus';
-
-// A1 notation utilities
-const col = A1.columnToIndex('C'); // 2
-const letter = A1.indexToColumn(2); // 'C'
-const range = A1.build('Sheet1', 'A', 1, 'C', 10); // 'Sheet1!A1:C10'
-
-// Type-safe operations
-interface User {
-  name: string;
-  email: string;
-  age: number;
-}
+Show your current login status.
+
+```bash
+sheets whoami
+```
+
+Output includes:
+- Your email address
+- Token expiration time
+- Whether the token is still valid
 
-const typed = new TypedSheets<User[]>(sheets);
-const users = await typed.read(
-  spreadsheetId,
-  'Users!A1:C100',
-  Parsers.rowsToObjects<User>
-);
+Exit code: 0 if logged in, 1 if not logged in.
 
-// Data transformation
-const objects = [
-  { name: 'Alice', age: 30 },
-  { name: 'Bob', age: 25 }
-];
-const rows = Serializers.objectsToRows(objects);
-// [['name', 'age'], ['Alice', 30], ['Bob', 25]]
+#### sheets auth
+
+Test service account credentials.
+
+```bash
+sheets auth path/to/credentials.json
 ```
 
-### Batch Operations Manager
+This validates the credentials file format and shows:
+- Project ID
+- Service account email
 
-```typescript
-import { BatchOperations } from '@ariadng/sheets/plus';
+### Spreadsheet Commands
 
-const batchOps = new BatchOperations(sheets);
+#### sheets get
 
-// Automatically chunks large batches
-const operations = Array.from({ length: 500 }, (_, i) => ({
-  range: `Sheet1!A${i}:B${i}`,
-  values: [[`Row${i}`, `Value${i}`]]
-}));
+Get spreadsheet information.
 
-await batchOps.batchWrite(spreadsheetId, operations); // Handles chunking
+```bash
+sheets get SPREADSHEET_ID
 ```
 
-### Simple Cache
+Options:
+- `--credentials <file>`: Use service account credentials
+- `--token <token>`: Use OAuth access token
+- `--format <format>`: Output format, either `table` (default) or `json`
 
-```typescript
-import { SimpleCache } from '@ariadng/sheets/plus';
+Output includes:
+- Spreadsheet title
+- Spreadsheet ID
+- Locale and timezone
+- Number of sheets
+- Spreadsheet URL
 
-const cache = new SimpleCache({
-  ttlSeconds: 60,
-  maxEntries: 100
-});
+#### sheets list
 
-cache.set('key', data);
-const cached = cache.get('key');
-cache.invalidate('pattern*'); // Wildcard invalidation
-cache.clear(); // Clear all
+List all sheets in a spreadsheet.
+
+```bash
+sheets list SPREADSHEET_ID
 ```
 
-## Advanced Package Features
+Options:
+- `--credentials <file>`: Use service account credentials
+- `--token <token>`: Use OAuth access token
+- `--format <format>`: Output format, either `table` (default) or `json`
 
-### Adaptive Rate Limiting
+Output includes:
+- Sheet index
+- Sheet title
+- Grid size (rows and columns)
+- Hidden status
 
-```typescript
-import { AdaptiveRateLimiter } from '@ariadng/sheets/advanced';
+#### sheets read
 
-const limiter = new AdaptiveRateLimiter();
+Read cell values from a spreadsheet range.
 
-// Automatically adjusts delay based on success/failure
-await limiter.execute(async () => {
-  return sheets.read(id, range);
-});
+```bash
+sheets read SPREADSHEET_ID "Sheet1!A1:D10"
+```
+
+Options:
+- `--credentials <file>`: Use service account credentials
+- `--token <token>`: Use OAuth access token
+- `--format <format>`: Output format, either `table` (default) or `json`
+- `--formula`: Show formulas instead of calculated values
 
-// Get current stats
-const stats = limiter.getStats();
-console.log(stats); // { requestsInWindow: 45, successRate: 0.98, baseDelay: 0 }
+Examples:
+
+```bash
+# Read a range of cells
+sheets read SPREADSHEET_ID "Sheet1!A1:D10"
+
+# Read an entire column
+sheets read SPREADSHEET_ID "Sheet1!A:A"
+
+# Read with formulas visible
+sheets read SPREADSHEET_ID "Sheet1!A1:D10" --formula
+
+# Output as JSON
+sheets read SPREADSHEET_ID "Sheet1!A1:D10" --format json
 ```
 
-### Metrics Collection
+Range format:
+- `Sheet1!A1:D10`: Cells A1 through D10 on Sheet1
+- `Sheet1!A:A`: Entire column A on Sheet1
+- `Sheet1!1:1`: Entire row 1 on Sheet1
+- `A1:D10`: Cells A1 through D10 on the first sheet
 
-```typescript
-import { withMetrics } from '@ariadng/sheets/advanced';
+### Global Options
+
+These options work with all spreadsheet commands:
+
+| Option | Description |
+|--------|-------------|
+| `--credentials <file>` | Path to service account JSON file |
+| `--token <token>` | OAuth access token string |
+| `--format <format>` | Output format: `table` or `json` |
+| `--version` | Show version number |
+| `--help` | Show help message |
 
-const metricsSheets = withMetrics(sheets);
+## Library Usage
 
-// Use normally
-await metricsSheets.read(id, range);
-await metricsSheets.write(id, range, values);
+You can also use this package as a library in your Node.js applications.
 
-// Get metrics
-const metrics = metricsSheets.metrics.getMetrics();
-console.log(metrics);
-// {
-//   totalRequests: 150,
-//   successfulRequests: 148,
-//   failedRequests: 2,
-//   averageLatency: 123.5,
-//   rateLimitHits: 1,
-//   errorsByCode: Map { 429 => 1, 500 => 1 }
-// }
+### Installation
 
-const summary = metricsSheets.metrics.getSummary();
-console.log(summary);
-// {
-//   successRate: 0.987,
-//   requestsPerSecond: 2.5,
-//   uptimeSeconds: 60
-// }
+```bash
+npm install @ariadng/sheets
 ```
 
-## Error Handling
+### Basic Example
 
 ```typescript
-import { GoogleSheetsError } from '@ariadng/sheets/core';
+import { createClient } from '@ariadng/sheets';
 
-try {
-  await sheets.read(spreadsheetId, range);
-} catch (error) {
-  if (error instanceof GoogleSheetsError) {
-    console.error(`API Error ${error.code}: ${error.message}`);
+// Create a client with user authentication (after running "sheets login")
+const client = createClient({
+    auth: { type: 'user' }
+});
 
-    if (error.isRetryable) {
-      console.log('This error is retryable');
-    }
+// Get spreadsheet information
+const spreadsheet = await client.getSpreadsheet('SPREADSHEET_ID');
+console.log(spreadsheet.properties.title);
+
+// Read cell values
+const values = await client.getValues('SPREADSHEET_ID', 'Sheet1!A1:D10');
+console.log(values.values);
+```
+
+### Service Account Example
 
-    if (error.isPermissionError()) {
-      console.log('Share the sheet with service account');
+```typescript
+import { createClient } from '@ariadng/sheets';
+
+const client = createClient({
+    auth: {
+        type: 'service-account',
+        credentialsPath: './credentials.json'
     }
+});
+
+const values = await client.getValues('SPREADSHEET_ID', 'Sheet1!A1:D10');
+```
 
-    if (error.isRateLimitError()) {
-      console.log('Hit rate limit, slow down');
+### OAuth Token Example
+
+```typescript
+import { createClient } from '@ariadng/sheets';
+
+const client = createClient({
+    auth: {
+        type: 'oauth',
+        accessToken: 'YOUR_ACCESS_TOKEN'
     }
+});
 
-    // User-friendly message
-    console.log(error.getUserMessage());
-  }
-}
+const values = await client.getValues('SPREADSHEET_ID', 'Sheet1!A1:D10');
 ```
 
-## Common Patterns
+### Available Methods
 
-### Progressive Enhancement
+#### getSpreadsheet(spreadsheetId)
+
+Get spreadsheet metadata.
 
 ```typescript
-import { GoogleSheetsCore } from '@ariadng/sheets/core';
-import { withCache } from '@ariadng/sheets/plus';
-import { withAdaptiveRateLimit, withMetrics } from '@ariadng/sheets/advanced';
+const spreadsheet = await client.getSpreadsheet('SPREADSHEET_ID');
+// Returns: { spreadsheetId, properties, sheets, spreadsheetUrl }
+```
 
-// Start simple
-let sheets = new GoogleSheetsCore({ auth });
+#### getSheets(spreadsheetId)
 
-// Add features as needed
-sheets = withCache(sheets, { ttlSeconds: 300 });
-sheets = withAdaptiveRateLimit(sheets);
-sheets = withMetrics(sheets);
+Get list of sheets in a spreadsheet.
 
-// Now have all features!
+```typescript
+const sheets = await client.getSheets('SPREADSHEET_ID');
+// Returns: [{ sheetId, title, index, gridProperties, hidden }]
 ```
 
-### Data Processing Pipeline
+#### getValues(spreadsheetId, range, options?)
+
+Read cell values from a range.
 
 ```typescript
-import { Parsers, Serializers } from '@ariadng/sheets/plus';
+const values = await client.getValues('SPREADSHEET_ID', 'Sheet1!A1:D10');
+// Returns: { range, majorDimension, values }
 
-// Read raw data
-const raw = await sheets.read(id, 'Data!A1:Z1000');
+// With options
+const values = await client.getValues('SPREADSHEET_ID', 'Sheet1!A1:D10', {
+    valueRenderOption: 'UNFORMATTED_VALUE',
+    dateTimeRenderOption: 'SERIAL_NUMBER'
+});
+```
+
+Options:
+- `valueRenderOption`: How values should be rendered
+  - `FORMATTED_VALUE` (default): Values as displayed in the UI
+  - `UNFORMATTED_VALUE`: Raw values without formatting
+  - `FORMULA`: Formulas instead of calculated values
+- `dateTimeRenderOption`: How dates should be rendered
+  - `FORMATTED_STRING` (default): Date as formatted string
+  - `SERIAL_NUMBER`: Date as serial number
+- `majorDimension`: How data is organized
+  - `ROWS` (default): Data organized by rows
+  - `COLUMNS`: Data organized by columns
+
+#### getFormulas(spreadsheetId, range)
+
+Read formulas from a range. This is a shortcut for `getValues` with `valueRenderOption: 'FORMULA'`.
 
-// Parse to objects
-const records = Parsers.rowsToObjects(raw);
+```typescript
+const formulas = await client.getFormulas('SPREADSHEET_ID', 'Sheet1!A1:D10');
+```
 
-// Process data
-const processed = records
-  .filter(r => r.status === 'active')
-  .map(r => ({ ...r, processed: true }));
+#### batchGetValues(spreadsheetId, ranges, options?)
 
-// Convert back to rows
-const rows = Serializers.objectsToRows(processed);
+Read multiple ranges in a single request.
 
-// Write back
-await sheets.write(id, 'Processed!A1', rows);
+```typescript
+const result = await client.batchGetValues('SPREADSHEET_ID', [
+    'Sheet1!A1:D10',
+    'Sheet2!A1:B5'
+]);
+// Returns: { spreadsheetId, valueRanges: [...] }
 ```
 
-### Efficient Batch Processing
+### Authentication Functions
 
 ```typescript
-import { BatchOperations } from '@ariadng/sheets/plus';
+import { login, loadStoredTokens, deleteTokens } from '@ariadng/sheets';
 
-const batch = new BatchOperations(sheets);
+// Perform OAuth login flow
+const tokens = await login();
+console.log(tokens.email);
 
-// Mixed operations
-const results = await batch.executeBatch(spreadsheetId, {
-  reads: ['Summary!A1:Z1', 'Config!A1:B10'],
-  writes: [
-    { range: 'Output!A1:B100', values: outputData }
-  ],
-  clears: ['Temp!A:Z']
-});
+// Load stored tokens
+const stored = await loadStoredTokens();
+if (stored) {
+    console.log('Logged in as:', stored.email);
+}
 
-// All executed efficiently in parallel when possible
+// Delete stored tokens
+await deleteTokens();
 ```
 
-## API Reference
+## Troubleshooting
 
-### Core Package
+### "Not logged in" Error
 
-#### GoogleSheetsCore
+Run `sheets login` to authenticate with your Google account.
 
-- `constructor(config: GoogleSheetsConfig)`
-- `read(spreadsheetId: string, range: string): Promise<any[][]>`
-- `write(spreadsheetId: string, range: string, values: any[][]): Promise<UpdateValuesResponse>`
-- `append(spreadsheetId: string, range: string, values: any[][]): Promise<AppendValuesResponse>`
-- `clear(spreadsheetId: string, range: string): Promise<ClearValuesResponse>`
-- `batchRead(spreadsheetId: string, ranges: string[]): Promise<ValueRange[]>`
-- `batchWrite(spreadsheetId: string, data: BatchWriteData[]): Promise<BatchUpdateValuesResponse>`
-- `getSpreadsheet(spreadsheetId: string): Promise<Spreadsheet>`
-- `getApi(): sheets_v4.Sheets`
+### "Access denied" or "Permission denied" Error
 
-### Plus Package
+Make sure you have access to the spreadsheet:
+- For personal accounts: The spreadsheet must be shared with your Google account
+- For service accounts: Share the spreadsheet with the service account email address
 
-#### A1 Utilities
+### "Invalid credentials" Error
 
-- `A1.columnToIndex(column: string): number`
-- `A1.indexToColumn(index: number): string`
-- `A1.parse(notation: string): A1Components`
-- `A1.build(sheet?, startCol, startRow, endCol?, endRow?): string`
-- `A1.getDimensions(notation: string): { rows: number, columns: number }`
-- `A1.offset(notation: string, rowOffset: number, colOffset: number): string`
+For service accounts:
+- Check that the JSON file is valid
+- Make sure the file contains `type: "service_account"`
+- Verify the private key is correct
 
-#### Parsers
+### Browser Does Not Open During Login
 
-- `Parsers.rowsToObjects<T>(data: any[][]): T[]`
-- `Parsers.asNumbers(data: any[][]): number[][]`
-- `Parsers.asStrings(data: any[][]): string[][]`
-- `Parsers.asMap<V>(data: any[][]): Map<string, V>`
-- `Parsers.column<T>(data: any[][], columnIndex: number): T[]`
+Try these solutions:
+- Open the URL manually (it will be displayed in the terminal)
+- Make sure port 8085 is not in use by another application
 
-#### Serializers
+### Token Expired
 
-- `Serializers.objectsToRows<T>(objects: T[], headers?: string[]): any[][]`
-- `Serializers.mapToRows<K,V>(map: Map<K,V>): any[][]`
-- `Serializers.arrayToColumn<T>(array: T[]): any[][]`
-- `Serializers.transpose(data: any[][]): any[][]`
+Tokens are automatically refreshed when they expire. If you see token errors, try logging out and logging in again:
 
-## Performance
+```bash
+sheets logout
+sheets login
+```
 
-| Operation | Base Latency | With Cache | With Rate Limit |
-|-----------|-------------|------------|-----------------|
-| Single Read | 100-200ms | 0-1ms (hit) | +0-50ms |
-| Batch Read (10) | 150-250ms | 0-1ms (hit) | +0-50ms |
-| Single Write | 150-300ms | N/A | +0-50ms |
-| Batch Write (100) | 300-500ms | N/A | +0-100ms |
+## Token Storage
 
-## Best Practices
+When you run `sheets login`, your authentication tokens are saved to:
 
-1. **Use batch operations** when reading/writing multiple ranges
-2. **Enable caching** for frequently read, rarely changed data
-3. **Add rate limiting** for bulk operations or scripts
-4. **Use type utilities** for better type safety and code clarity
-5. **Handle errors gracefully** with proper retry logic
-6. **Monitor with metrics** in production environments
+```
+~/.sheets/tokens.json
+```
 
-## Requirements
+This file contains:
+- Access token (used to make API requests)
+- Refresh token (used to get new access tokens)
+- Token expiration time
+- Your email address
 
-- Node.js 14+
-- Google Sheets API enabled in Google Cloud Console
-- Service account or OAuth2 credentials
+Keep this file secure. Do not share it with others.
 
-## License
+## How It Works
 
-MIT
+This tool uses the Google Sheets API v4 to read spreadsheet data. It does not use the official Google SDK. Instead, it makes direct HTTP requests to the API.
 
-## Contributing
+Authentication methods:
+- Personal accounts: OAuth 2.0 with PKCE (Proof Key for Code Exchange)
+- Service accounts: JWT (JSON Web Token) signed with RS256
 
-Contributions are welcome! Please read our contributing guidelines before submitting PRs.
+The tool only requests read-only access to your spreadsheets. It cannot modify your data.
 
-## Support
+## Project Structure
 
-For issues and feature requests, please use the [GitHub issues page](https://github.com/ariadng/sheets/issues).
+```
+src/
+  index.ts              Public API exports
+  cli.ts                CLI entry point
+  api/index.ts          SheetsClient class
+  auth/
+    index.ts            Auth provider factory
+    constants.ts        OAuth configuration
+    oauth.ts            OAuth token wrapper
+    user-auth.ts        User OAuth with PKCE
+    service-account.ts  Service account JWT auth
+  http/index.ts         HTTP client with retry
+  types/index.ts        TypeScript definitions
+```
+
+## Development
+
+### Build
+
+```bash
+npm run build
+```
+
+This compiles TypeScript to JavaScript in the `dist` folder.
+
+### Development Mode
+
+```bash
+npm run dev
+```
+
+This runs the CLI with automatic reloading when files change.
+
+### Run Without Building
+
+```bash
+npx tsx src/cli.ts <command>
+```
+
+## License
+
+MIT