@goodsamsoftware/freshbooks-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chadwick Posey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,357 @@
+# FreshBooks MCP Server
+
+A Model Context Protocol (MCP) server providing complete FreshBooks integration for Claude and other MCP-compatible AI assistants.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
+[![Tests](https://img.shields.io/badge/Tests-1571%20passing-brightgreen.svg)](#testing)
+
+## Features
+
+- **Complete SDK Parity** - 87 tools covering all major FreshBooks functionality
+- **22 Entity Categories** - Full coverage of accounting, invoicing, time tracking, and more
+- **Time Tracking** - Log time, manage timers, track billable hours
+- **Invoicing & Billing** - Create invoices, manage bills, handle payments
+- **Expense Management** - Track expenses, categorize spending, manage vendors
+- **Client & Project Management** - Full CRM and project capabilities
+- **Financial Reports** - Profit/loss, tax summaries, and more
+- **OAuth2 Authentication** - Secure token-based authentication with auto-refresh
+
+## Installation
+
+```bash
+npm install freshbooks-mcp
+```
+
+## Quick Start
+
+The fastest way to get started is with our **hosted service** — no OAuth setup required.
+
+### 1. Sign Up
+
+Go to [freshbooks.goodsamsoftware.com](https://freshbooks.goodsamsoftware.com) and create an account (**14-day free trial**). Once you're in, connect your FreshBooks account from the dashboard.
+
+### 2. Copy Your Configuration
+
+From your dashboard, copy the configuration snippet provided. It works with both **Claude Desktop** and **Claude Code**.
+
+**Claude Desktop** (`claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "freshbooks": {
+      "command": "npx",
+      "args": ["mcp-remote", "https://freshbooks.goodsamsoftware.com/api/mcp", "--header", "Authorization:Bearer YOUR_TOKEN"]
+    }
+  }
+}
+```
+
+**Claude Code** (`.mcp.json` in your project):
+```json
+{
+  "mcpServers": {
+    "freshbooks": {
+      "command": "npx",
+      "args": ["mcp-remote", "https://freshbooks.goodsamsoftware.com/api/mcp", "--header", "Authorization:Bearer YOUR_TOKEN"]
+    }
+  }
+}
+```
+
+### 3. Start Using
+
+Example prompts:
+- "Log 2 hours on the Website Redesign project"
+- "Show me my time entries for this week"
+- "Start a timer for client meeting"
+- "Create an invoice for Acme Corp for $1,500"
+- "What's my profit/loss this month?"
+
+---
+
+## Self-Hosted Setup
+
+You can also run the MCP server locally with your own FreshBooks API application.
+
+> **Note:** FreshBooks requires HTTPS for all OAuth callback URLs, including localhost. See [Local HTTPS Setup](#advanced-local-https-setup) below for instructions.
+
+### 1. Get FreshBooks Credentials
+
+1. Go to [FreshBooks Developer Portal](https://my.freshbooks.com/#/developer)
+2. Create a new application
+3. Set redirect URI to: `https://freshbooks.goodsamsoftware.com/callback`
+4. Note your Client ID and Client Secret
+
+### 2. Configure Claude Desktop
+
+Add to your Claude Desktop configuration (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "freshbooks": {
+      "command": "npx",
+      "args": ["freshbooks-mcp"],
+      "env": {
+        "FRESHBOOKS_CLIENT_ID": "your-client-id",
+        "FRESHBOOKS_CLIENT_SECRET": "your-client-secret",
+        "FRESHBOOKS_REDIRECT_URI": "https://freshbooks.goodsamsoftware.com/callback"
+      }
+    }
+  }
+}
+```
+
+### 3. Authenticate
+
+Ask Claude:
+> "Connect me to FreshBooks"
+
+Claude will guide you through OAuth authentication. After authorizing in FreshBooks, you'll see the authorization code on our [hosted callback page](https://freshbooks.goodsamsoftware.com) - just copy it and paste it back to Claude.
+
+### 4. Start Using
+
+Example prompts:
+- "Log 2 hours on the Website Redesign project"
+- "Show me my time entries for this week"
+- "Start a timer for client meeting"
+- "Create an invoice for Acme Corp for $1,500"
+- "What's my profit/loss this month?"
+
+## Available Tools (87 total)
+
+### Authentication (5 tools)
+| Tool | Description |
+|------|-------------|
+| `auth_status` | Check authentication status |
+| `auth_get_url` | Get OAuth authorization URL |
+| `auth_exchange_code` | Exchange auth code for tokens |
+| `auth_refresh` | Refresh access token |
+| `auth_revoke` | Revoke authentication |
+
+### Time Tracking (5 tools)
+| Tool | Description |
+|------|-------------|
+| `timeentry_list` | List time entries with filters |
+| `timeentry_single` | Get time entry by ID |
+| `timeentry_create` | Create time entry |
+| `timeentry_update` | Update time entry |
+| `timeentry_delete` | Delete time entry |
+
+### Timer Management (4 tools)
+| Tool | Description |
+|------|-------------|
+| `timer_start` | Start a timer |
+| `timer_stop` | Stop timer and log time |
+| `timer_current` | Get running timer(s) |
+| `timer_discard` | Delete timer without logging |
+
+### Invoicing (5 tools)
+| Tool | Description |
+|------|-------------|
+| `invoice_list` | List invoices |
+| `invoice_single` | Get invoice by ID |
+| `invoice_create` | Create invoice |
+| `invoice_update` | Update invoice |
+| `invoice_delete` | Delete invoice |
+
+### Clients (5 tools)
+| Tool | Description |
+|------|-------------|
+| `client_list` | List clients |
+| `client_single` | Get client by ID |
+| `client_create` | Create client |
+| `client_update` | Update client |
+| `client_delete` | Delete client |
+
+### Projects (5 tools)
+| Tool | Description |
+|------|-------------|
+| `project_list` | List projects |
+| `project_single` | Get project by ID |
+| `project_create` | Create project |
+| `project_update` | Update project |
+| `project_delete` | Delete project |
+
+### Expenses (5 tools)
+| Tool | Description |
+|------|-------------|
+| `expense_list` | List expenses |
+| `expense_single` | Get expense by ID |
+| `expense_create` | Create expense |
+| `expense_update` | Update expense |
+| `expense_delete` | Delete expense |
+
+### Bills & Payments (15 tools)
+| Tool | Description |
+|------|-------------|
+| `bill_list` | List bills |
+| `bill_single` | Get bill by ID |
+| `bill_create` | Create bill |
+| `bill_update` | Update bill |
+| `bill_delete` | Delete bill |
+| `billpayment_list` | List bill payments |
+| `billpayment_single` | Get bill payment |
+| `billpayment_create` | Create bill payment |
+| `billpayment_update` | Update bill payment |
+| `billpayment_delete` | Delete bill payment |
+| `billvendor_list` | List vendors |
+| `billvendor_single` | Get vendor by ID |
+| `billvendor_create` | Create vendor |
+| `billvendor_update` | Update vendor |
+| `billvendor_delete` | Delete vendor |
+
+### Additional Tools
+
+| Category | Tools | Description |
+|----------|-------|-------------|
+| **Credit Notes** | 5 | Create, manage credit notes |
+| **Expense Categories** | 3 | Manage expense categories |
+| **Items** | 5 | Product/service catalog |
+| **Journal Entries** | 5 | Manual accounting entries |
+| **Journal Entry Accounts** | 3 | Chart of accounts |
+| **Other Income** | 5 | Non-invoice income tracking |
+| **Payments** | 5 | Invoice payment tracking |
+| **Payment Options** | 2 | Payment gateway settings |
+| **Reports** | 3 | Financial reports |
+| **Services** | 5 | Billable service types |
+| **Tasks** | 5 | Project task management |
+| **User** | 1 | Current user info |
+| **Callbacks** | 5 | Webhook management |
+
+*See complete tool documentation in [docs/api/](docs/api/)*
+
+## Configuration (Self-Hosted)
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `FRESHBOOKS_CLIENT_ID` | Yes | OAuth client ID |
+| `FRESHBOOKS_CLIENT_SECRET` | Yes | OAuth client secret |
+| `FRESHBOOKS_REDIRECT_URI` | Yes | OAuth redirect URI |
+| `FRESHBOOKS_TOKEN_PATH` | No | Path for token storage |
+| `LOG_LEVEL` | No | Logging level (debug, info, warn, error) |
+
+### Advanced: Local HTTPS Setup
+
+If you prefer to use a local callback instead of our hosted callback page, you can set up local HTTPS certificates with [mkcert](https://github.com/FiloSottile/mkcert):
+
+**Windows (winget):**
+```bash
+winget install FiloSottile.mkcert
+mkcert -install
+mkdir certs
+mkcert -key-file certs/localhost-key.pem -cert-file certs/localhost.pem localhost 127.0.0.1 ::1
+```
+
+**macOS (Homebrew):**
+```bash
+brew install mkcert
+mkcert -install
+mkdir certs
+mkcert -key-file certs/localhost-key.pem -cert-file certs/localhost.pem localhost 127.0.0.1 ::1
+```
+
+**Linux:**
+```bash
+# Install mkcert (see https://github.com/FiloSottile/mkcert#installation)
+mkcert -install
+mkdir certs
+mkcert -key-file certs/localhost-key.pem -cert-file certs/localhost.pem localhost 127.0.0.1 ::1
+```
+
+Then set your redirect URI to `https://localhost:3000/callback` in FreshBooks.
+
+The certificates will be valid for 3 years and trusted by your system.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run in development mode
+npm run dev
+
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Type check
+npm run typecheck
+
+# Build for production
+npm run build
+```
+
+## Testing
+
+The project has comprehensive test coverage:
+
+- **1,571 tests** across 93 test files
+- **100% code coverage** requirement
+- Mock factories for all FreshBooks entities
+- Error scenario coverage
+
+```bash
+npm test                 # Run all tests
+npm run test:coverage    # Run with coverage report
+```
+
+## Architecture
+
+```
+src/
+├── server.ts             # MCP server entry point
+├── auth/                 # OAuth2 authentication
+├── client/               # FreshBooks SDK wrapper
+├── errors/               # Error normalization
+├── tools/                # MCP tool implementations (22 categories)
+│   ├── auth/             # Authentication tools
+│   ├── time-entry/       # Time tracking
+│   ├── timer/            # Timer management
+│   ├── invoice/          # Invoicing
+│   ├── client/           # Client management
+│   ├── project/          # Projects
+│   ├── expense/          # Expenses
+│   ├── bill/             # Bills
+│   └── ...               # 14 more categories
+└── config/               # Configuration
+```
+
+## Documentation
+
+- [API Reference](docs/api/) - Complete tool documentation
+- [Authentication Setup](docs/AUTH_SETUP.md) - OAuth configuration
+- [Claude Guide](docs/claude/) - Claude-optimized usage examples
+- [Examples](docs/examples/) - Workflow examples
+
+## Error Handling
+
+All errors are normalized to MCP format with helpful context:
+
+```json
+{
+  "code": -32005,
+  "message": "User-friendly message",
+  "data": {
+    "freshbooksError": { "code": "...", "message": "..." },
+    "recoverable": true,
+    "suggestion": "What to do next"
+  }
+}
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Credits
+
+- [FreshBooks Node.js SDK](https://github.com/freshbooks/freshbooks-nodejs-sdk)
+- [Model Context Protocol](https://modelcontextprotocol.io)
+- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)

package/dist/auth/config.d.ts

@@ -0,0 +1,57 @@
+/**
+ * FreshBooks OAuth Configuration Helper
+ *
+ * Loads OAuth configuration from environment variables with validation.
+ */
+import { OAuthConfig, TokenStore } from './types.js';
+/**
+ * Load OAuth configuration from environment variables
+ *
+ * Required environment variables:
+ * - FRESHBOOKS_CLIENT_ID
+ * - FRESHBOOKS_CLIENT_SECRET
+ * - FRESHBOOKS_REDIRECT_URI
+ *
+ * Optional:
+ * - FRESHBOOKS_SCOPES (comma-separated)
+ *
+ * @throws Error if required environment variables are missing
+ */
+export declare function loadOAuthConfig(): OAuthConfig;
+/**
+ * Create appropriate token store based on environment
+ *
+ * Strategy:
+ * 1. If FRESHBOOKS_ACCESS_TOKEN is set, use EnvTokenStore (CI/testing)
+ * 2. Otherwise, use EncryptedFileTokenStore (production/development)
+ *
+ * Token file location:
+ * - Uses FRESHBOOKS_TOKEN_FILE env var if set
+ * - Otherwise defaults to './freshbooks-tokens.enc'
+ *
+ * Encryption password:
+ * - Uses FRESHBOOKS_TOKEN_PASSWORD env var if set
+ * - Otherwise uses machine-specific default
+ */
+export declare function createTokenStore(): TokenStore;
+/**
+ * Validate OAuth configuration
+ *
+ * Checks that configuration values are properly formatted.
+ *
+ * @param config OAuth configuration to validate
+ * @throws Error if configuration is invalid
+ */
+export declare function validateOAuthConfig(config: OAuthConfig): void;
+/**
+ * Initialize OAuth configuration with validation
+ *
+ * Convenience function that:
+ * 1. Loads configuration from environment
+ * 2. Validates configuration
+ * 3. Returns validated config
+ *
+ * @returns Validated OAuth configuration
+ */
+export declare function initializeOAuthConfig(): OAuthConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/auth/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/auth/config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGrD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,IAAI,WAAW,CAyC7C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,IAAI,UAAU,CAS7C;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAyB7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,IAAI,WAAW,CAInD"}

package/dist/auth/config.js

@@ -0,0 +1,118 @@
+/**
+ * FreshBooks OAuth Configuration Helper
+ *
+ * Loads OAuth configuration from environment variables with validation.
+ */
+import { EncryptedFileTokenStore, EnvTokenStore } from './token-store.js';
+/**
+ * Load OAuth configuration from environment variables
+ *
+ * Required environment variables:
+ * - FRESHBOOKS_CLIENT_ID
+ * - FRESHBOOKS_CLIENT_SECRET
+ * - FRESHBOOKS_REDIRECT_URI
+ *
+ * Optional:
+ * - FRESHBOOKS_SCOPES (comma-separated)
+ *
+ * @throws Error if required environment variables are missing
+ */
+export function loadOAuthConfig() {
+    const clientId = process.env.FRESHBOOKS_CLIENT_ID;
+    const clientSecret = process.env.FRESHBOOKS_CLIENT_SECRET;
+    const redirectUri = process.env.FRESHBOOKS_REDIRECT_URI;
+    if (!clientId) {
+        throw new Error('FRESHBOOKS_CLIENT_ID environment variable is required. ' +
+            'Get your client ID from FreshBooks Developer Portal.');
+    }
+    if (!clientSecret) {
+        throw new Error('FRESHBOOKS_CLIENT_SECRET environment variable is required. ' +
+            'Get your client secret from FreshBooks Developer Portal.');
+    }
+    if (!redirectUri) {
+        throw new Error('FRESHBOOKS_REDIRECT_URI environment variable is required. ' +
+            'Set to your OAuth redirect URI (e.g., http://localhost:3000/callback)');
+    }
+    const scopesEnv = process.env.FRESHBOOKS_SCOPES;
+    const scopes = scopesEnv ? scopesEnv.split(',').map(s => s.trim()) : undefined;
+    const config = {
+        clientId,
+        clientSecret,
+        redirectUri,
+    };
+    // Only add scopes if defined
+    if (scopes) {
+        config.scopes = scopes;
+    }
+    return config;
+}
+/**
+ * Create appropriate token store based on environment
+ *
+ * Strategy:
+ * 1. If FRESHBOOKS_ACCESS_TOKEN is set, use EnvTokenStore (CI/testing)
+ * 2. Otherwise, use EncryptedFileTokenStore (production/development)
+ *
+ * Token file location:
+ * - Uses FRESHBOOKS_TOKEN_FILE env var if set
+ * - Otherwise defaults to './freshbooks-tokens.enc'
+ *
+ * Encryption password:
+ * - Uses FRESHBOOKS_TOKEN_PASSWORD env var if set
+ * - Otherwise uses machine-specific default
+ */
+export function createTokenStore() {
+    // If access token is in environment, use EnvTokenStore
+    if (process.env.FRESHBOOKS_ACCESS_TOKEN) {
+        return new EnvTokenStore();
+    }
+    // Use encrypted file store
+    const tokenFile = process.env.FRESHBOOKS_TOKEN_FILE || './freshbooks-tokens.enc';
+    return new EncryptedFileTokenStore(tokenFile);
+}
+/**
+ * Validate OAuth configuration
+ *
+ * Checks that configuration values are properly formatted.
+ *
+ * @param config OAuth configuration to validate
+ * @throws Error if configuration is invalid
+ */
+export function validateOAuthConfig(config) {
+    // Validate client ID format (basic check)
+    if (config.clientId.length < 10) {
+        throw new Error('Client ID appears to be invalid (too short)');
+    }
+    // Validate client secret format (basic check)
+    if (config.clientSecret.length < 10) {
+        throw new Error('Client secret appears to be invalid (too short)');
+    }
+    // Validate redirect URI format
+    try {
+        const url = new URL(config.redirectUri);
+        // Warn about insecure redirect URIs in production
+        if (process.env.NODE_ENV === 'production' && url.protocol === 'http:') {
+            console.warn('Warning: Using insecure HTTP redirect URI in production. ' +
+                'Consider using HTTPS for enhanced security.');
+        }
+    }
+    catch {
+        throw new Error('Redirect URI must be a valid URL');
+    }
+}
+/**
+ * Initialize OAuth configuration with validation
+ *
+ * Convenience function that:
+ * 1. Loads configuration from environment
+ * 2. Validates configuration
+ * 3. Returns validated config
+ *
+ * @returns Validated OAuth configuration
+ */
+export function initializeOAuthConfig() {
+    const config = loadOAuthConfig();
+    validateOAuthConfig(config);
+    return config;
+}
+//# sourceMappingURL=config.js.map

package/dist/auth/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/auth/config.ts"],"names":[],"mappings":"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"}

package/dist/auth/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * FreshBooks OAuth2 Authentication
+ *
+ * Complete OAuth2 authentication system for FreshBooks API.
+ *
+ * @example Basic Usage
+ * ```typescript
+ * import { FreshBooksOAuth, EncryptedFileTokenStore } from './auth';
+ *
+ * const tokenStore = new EncryptedFileTokenStore('./tokens.enc');
+ * const oauth = new FreshBooksOAuth({
+ *   clientId: 'your-client-id',
+ *   clientSecret: 'your-client-secret',
+ *   redirectUri: 'http://localhost:3000/callback',
+ * }, tokenStore);
+ *
+ * // 1. Generate authorization URL
+ * const url = oauth.generateAuthorizationUrl();
+ * console.log('Visit:', url);
+ *
+ * // 2. After user authorizes, exchange code
+ * await oauth.exchangeCode(authCode);
+ *
+ * // 3. Use valid token for API requests
+ * const token = await oauth.getValidToken();
+ * ```
+ *
+ * @example Environment-based Auth (CI/Testing)
+ * ```typescript
+ * import { FreshBooksOAuth, EnvTokenStore } from './auth';
+ *
+ * // Set environment variables:
+ * // FRESHBOOKS_ACCESS_TOKEN=...
+ * // FRESHBOOKS_REFRESH_TOKEN=...
+ *
+ * const tokenStore = new EnvTokenStore();
+ * const oauth = new FreshBooksOAuth(config, tokenStore);
+ *
+ * const token = await oauth.getValidToken();
+ * ```
+ */
+export { FreshBooksOAuth } from './oauth.js';
+export { EncryptedFileTokenStore, EnvTokenStore, InMemoryTokenStore, } from './token-store.js';
+export type { OAuthConfig, TokenData, AuthStatus, TokenStore, OAuthErrorCode, } from './types.js';
+export { OAuthError } from './types.js';
+export { loadOAuthConfig, createTokenStore, validateOAuthConfig, initializeOAuthConfig, } from './config.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EACL,uBAAuB,EACvB,aAAa,EACb,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,WAAW,EACX,SAAS,EACT,UAAU,EACV,UAAU,EACV,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,aAAa,CAAC"}

package/dist/auth/index.js

@@ -0,0 +1,46 @@
+/**
+ * FreshBooks OAuth2 Authentication
+ *
+ * Complete OAuth2 authentication system for FreshBooks API.
+ *
+ * @example Basic Usage
+ * ```typescript
+ * import { FreshBooksOAuth, EncryptedFileTokenStore } from './auth';
+ *
+ * const tokenStore = new EncryptedFileTokenStore('./tokens.enc');
+ * const oauth = new FreshBooksOAuth({
+ *   clientId: 'your-client-id',
+ *   clientSecret: 'your-client-secret',
+ *   redirectUri: 'http://localhost:3000/callback',
+ * }, tokenStore);
+ *
+ * // 1. Generate authorization URL
+ * const url = oauth.generateAuthorizationUrl();
+ * console.log('Visit:', url);
+ *
+ * // 2. After user authorizes, exchange code
+ * await oauth.exchangeCode(authCode);
+ *
+ * // 3. Use valid token for API requests
+ * const token = await oauth.getValidToken();
+ * ```
+ *
+ * @example Environment-based Auth (CI/Testing)
+ * ```typescript
+ * import { FreshBooksOAuth, EnvTokenStore } from './auth';
+ *
+ * // Set environment variables:
+ * // FRESHBOOKS_ACCESS_TOKEN=...
+ * // FRESHBOOKS_REFRESH_TOKEN=...
+ *
+ * const tokenStore = new EnvTokenStore();
+ * const oauth = new FreshBooksOAuth(config, tokenStore);
+ *
+ * const token = await oauth.getValidToken();
+ * ```
+ */
+export { FreshBooksOAuth } from './oauth.js';
+export { EncryptedFileTokenStore, EnvTokenStore, InMemoryTokenStore, } from './token-store.js';
+export { OAuthError } from './types.js';
+export { loadOAuthConfig, createTokenStore, validateOAuthConfig, initializeOAuthConfig, } from './config.js';
+//# sourceMappingURL=index.js.map

package/dist/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EACL,uBAAuB,EACvB,aAAa,EACb,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAQ1B,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,aAAa,CAAC"}