@ariadng/sheets 0.3.4 → 0.4.0

package/README.md

@@ -1,601 +0,0 @@
-# @ariadng/sheets
-
-A command-line tool and library for reading Google Sheets. Works with personal Google accounts and service accounts.
-
-## For AI Agents
-
-If you are an AI agent (Claude, GPT, Copilot, or other AI assistants), use the npx version of this tool with the `-y` flag. This allows you to run commands without installing the package globally and without interactive prompts.
-
-**Important**: Always use `npx -y` to skip the installation confirmation prompt that would otherwise block automated execution.
-
-**Authentication**: Before reading spreadsheets, the user must be logged in. Check login status first, then prompt the user to login if needed.
-
-```bash
-# Check if user is logged in
-npx -y @ariadng/sheets whoami
-
-# If not logged in, ask user to run this command
-npx -y @ariadng/sheets login
-```
-
-**Reading data**: Use `--format json` for structured output that is easier to parse.
-
-```bash
-# Get spreadsheet metadata
-npx -y @ariadng/sheets get SPREADSHEET_ID --format json
-
-# List all sheets
-npx -y @ariadng/sheets list SPREADSHEET_ID --format json
-
-# Read cell values
-npx -y @ariadng/sheets read SPREADSHEET_ID "Sheet1!A1:D10" --format json
-
-# Read formulas instead of values
-npx -y @ariadng/sheets read SPREADSHEET_ID "Sheet1!A1:D10" --formula --format json
-```
-
-**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
-```
-
-After installation, the `sheets` command will be available in your terminal.
-
-## Usage Summary
-
-| 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 |
-| `sheets install-claude-skill` | Install Claude Code skill |
-
-## Using with npx
-
-You can also run this tool without installing it:
-
-```bash
-npx @ariadng/sheets login
-npx @ariadng/sheets read SPREADSHEET_ID "Sheet1!A1:D10"
-```
-
-**Note**: The first time you run npx, it will ask for confirmation to install the package. Use the `-y` flag to skip this prompt:
-
-```bash
-npx -y @ariadng/sheets login
-```
-
-## Claude Code Integration
-
-This tool includes a Claude Skill that teaches Claude Code how to use the sheets CLI. To install the skill:
-
-```bash
-sheets install-claude-skill
-```
-
-Or with npx:
-
-```bash
-npx @ariadng/sheets install-claude-skill
-```
-
-After installation, you can use `/sheets` in Claude Code to read Google Sheets data. The skill is installed to `~/.claude/skills/sheets/SKILL.md`.
-
-## Getting Started
-
-### Step 1: Login to Your Google Account
-
-Run this command to connect your Google account:
-
-```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
-
-This tool supports three ways to authenticate:
-
-### 1. Personal Google Account (Recommended for Most Users)
-
-Use the `login` command to authenticate with your personal Google account:
-
-```bash
-sheets login
-```
-
-Your login will be saved and used automatically for future commands. To check your login status:
-
-```bash
-sheets whoami
-```
-
-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:
-
-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:
-
-```bash
-sheets get SPREADSHEET_ID --credentials path/to/credentials.json
-```
-
-To test if your service account credentials are valid:
-
-```bash
-sheets auth path/to/credentials.json
-```
-
-### 3. Access Token (For Advanced Use)
-
-If you have an OAuth access token, you can use it directly:
-
-```bash
-sheets get SPREADSHEET_ID --token YOUR_ACCESS_TOKEN
-```
-
-## CLI Commands Reference
-
-### Authentication Commands
-
-#### sheets login
-
-Connect your Google account.
-
-```bash
-sheets login
-```
-
-Options:
-- `--client <file>`: Use custom OAuth client credentials (optional)
-
-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`
-
-#### sheets logout
-
-Remove your saved login.
-
-```bash
-sheets logout
-```
-
-This deletes the stored tokens from your computer.
-
-#### sheets whoami
-
-Show your current login status.
-
-```bash
-sheets whoami
-```
-
-Output includes:
-- Your email address
-- Token expiration time
-- Whether the token is still valid
-
-Exit code: 0 if logged in, 1 if not logged in.
-
-#### sheets auth
-
-Test service account credentials.
-
-```bash
-sheets auth path/to/credentials.json
-```
-
-This validates the credentials file format and shows:
-- Project ID
-- Service account email
-
-### Spreadsheet Commands
-
-#### sheets get
-
-Get spreadsheet information.
-
-```bash
-sheets get SPREADSHEET_ID
-```
-
-Options:
-- `--credentials <file>`: Use service account credentials
-- `--token <token>`: Use OAuth access token
-- `--format <format>`: Output format, either `table` (default) or `json`
-
-Output includes:
-- Spreadsheet title
-- Spreadsheet ID
-- Locale and timezone
-- Number of sheets
-- Spreadsheet URL
-
-#### sheets list
-
-List all sheets in a spreadsheet.
-
-```bash
-sheets list SPREADSHEET_ID
-```
-
-Options:
-- `--credentials <file>`: Use service account credentials
-- `--token <token>`: Use OAuth access token
-- `--format <format>`: Output format, either `table` (default) or `json`
-
-Output includes:
-- Sheet index
-- Sheet title
-- Grid size (rows and columns)
-- Hidden status
-
-#### sheets read
-
-Read cell values from a spreadsheet 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
-
-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
-```
-
-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
-
-#### sheets install-claude-skill
-
-Install the Claude Code skill for this tool.
-
-```bash
-sheets install-claude-skill
-```
-
-This installs a skill file to `~/.claude/skills/sheets/SKILL.md` that teaches Claude Code how to use the sheets CLI. After installation, you can use `/sheets` in Claude Code.
-
-### 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 |
-
-## Library Usage
-
-You can also use this package as a library in your Node.js applications.
-
-### Installation
-
-```bash
-npm install @ariadng/sheets
-```
-
-### Basic Example
-
-```typescript
-import { createClient } from '@ariadng/sheets';
-
-// Create a client with user authentication (after running "sheets login")
-const client = createClient({
-    auth: { type: 'user' }
-});
-
-// 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
-
-```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');
-```
-
-### OAuth Token Example
-
-```typescript
-import { createClient } from '@ariadng/sheets';
-
-const client = createClient({
-    auth: {
-        type: 'oauth',
-        accessToken: 'YOUR_ACCESS_TOKEN'
-    }
-});
-
-const values = await client.getValues('SPREADSHEET_ID', 'Sheet1!A1:D10');
-```
-
-### Available Methods
-
-#### getSpreadsheet(spreadsheetId)
-
-Get spreadsheet metadata.
-
-```typescript
-const spreadsheet = await client.getSpreadsheet('SPREADSHEET_ID');
-// Returns: { spreadsheetId, properties, sheets, spreadsheetUrl }
-```
-
-#### getSheets(spreadsheetId)
-
-Get list of sheets in a spreadsheet.
-
-```typescript
-const sheets = await client.getSheets('SPREADSHEET_ID');
-// Returns: [{ sheetId, title, index, gridProperties, hidden }]
-```
-
-#### getValues(spreadsheetId, range, options?)
-
-Read cell values from a range.
-
-```typescript
-const values = await client.getValues('SPREADSHEET_ID', 'Sheet1!A1:D10');
-// Returns: { range, majorDimension, values }
-
-// 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'`.
-
-```typescript
-const formulas = await client.getFormulas('SPREADSHEET_ID', 'Sheet1!A1:D10');
-```
-
-#### batchGetValues(spreadsheetId, ranges, options?)
-
-Read multiple ranges in a single request.
-
-```typescript
-const result = await client.batchGetValues('SPREADSHEET_ID', [
-    'Sheet1!A1:D10',
-    'Sheet2!A1:B5'
-]);
-// Returns: { spreadsheetId, valueRanges: [...] }
-```
-
-### Authentication Functions
-
-```typescript
-import { login, loadStoredTokens, deleteTokens } from '@ariadng/sheets';
-
-// Perform OAuth login flow
-const tokens = await login();
-console.log(tokens.email);
-
-// Load stored tokens
-const stored = await loadStoredTokens();
-if (stored) {
-    console.log('Logged in as:', stored.email);
-}
-
-// Delete stored tokens
-await deleteTokens();
-```
-
-## Troubleshooting
-
-### "Not logged in" Error
-
-Run `sheets login` to authenticate with your Google account.
-
-### "Access denied" or "Permission denied" Error
-
-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
-
-### "Invalid credentials" Error
-
-For service accounts:
-- Check that the JSON file is valid
-- Make sure the file contains `type: "service_account"`
-- Verify the private key is correct
-
-### Browser Does Not Open During Login
-
-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
-
-### Token Expired
-
-Tokens are automatically refreshed when they expire. If you see token errors, try logging out and logging in again:
-
-```bash
-sheets logout
-sheets login
-```
-
-## Token Storage
-
-When you run `sheets login`, your authentication tokens are saved to:
-
-```
-~/.sheets/tokens.json
-```
-
-This file contains:
-- Access token (used to make API requests)
-- Refresh token (used to get new access tokens)
-- Token expiration time
-- Your email address
-
-Keep this file secure. Do not share it with others.
-
-## How It Works
-
-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.
-
-Authentication methods:
-- Personal accounts: OAuth 2.0 with PKCE (Proof Key for Code Exchange)
-- Service accounts: JWT (JSON Web Token) signed with RS256
-
-The tool only requests read-only access to your spreadsheets. It cannot modify your data.
-
-## Project Structure
-
-```
-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