@panoptic-it-solutions/quickbooks-client 0.1.0

package/README.md

@@ -0,0 +1,194 @@
+# @panoptic-it-solutions/quickbooks-client
+
+QuickBooks Online API client with OAuth 2.0, rate limiting, and typed entities.
+
+## Installation
+
+```bash
+npm install @panoptic-it-solutions/quickbooks-client
+```
+
+## Quick Start
+
+```typescript
+import { QuickBooksClient, generateAuthUrl, exchangeCodeForTokens, generateState } from '@panoptic-it-solutions/quickbooks-client';
+import type { TokenStore, QuickBooksTokens } from '@panoptic-it-solutions/quickbooks-client';
+
+// 1. Implement TokenStore for your storage backend
+const tokenStore: TokenStore = {
+  async getTokens() {
+    // Return stored tokens or null
+    return db.getQuickBooksTokens();
+  },
+  async storeTokens(tokens) {
+    // Store tokens
+    await db.saveQuickBooksTokens(tokens);
+  },
+  async clearTokens() {
+    // Clear tokens
+    await db.deleteQuickBooksTokens();
+  }
+};
+
+// 2. Create the client
+const client = new QuickBooksClient({
+  clientId: process.env.QB_CLIENT_ID,
+  clientSecret: process.env.QB_CLIENT_SECRET,
+  redirectUri: process.env.QB_REDIRECT_URI,
+  environment: 'production', // or 'sandbox'
+  tokenStore,
+});
+
+// 3. Use the client
+const invoices = await client.getInvoices();
+const customers = await client.getCustomers('Active = true');
+```
+
+## OAuth Flow
+
+### Generate Authorization URL
+
+```typescript
+import { generateAuthUrl, generateState } from '@panoptic/quickbooks-client';
+
+const state = generateState(); // Store this for CSRF validation
+const authUrl = generateAuthUrl({
+  clientId: process.env.QB_CLIENT_ID,
+  clientSecret: process.env.QB_CLIENT_SECRET,
+  redirectUri: process.env.QB_REDIRECT_URI,
+}, state);
+
+// Redirect user to authUrl
+```
+
+### Handle OAuth Callback
+
+```typescript
+import { exchangeCodeForTokens } from '@panoptic/quickbooks-client';
+
+// In your callback handler:
+const tokens = await exchangeCodeForTokens(
+  {
+    clientId: process.env.QB_CLIENT_ID,
+    clientSecret: process.env.QB_CLIENT_SECRET,
+    redirectUri: process.env.QB_REDIRECT_URI,
+  },
+  code,    // from URL params
+  realmId  // from URL params
+);
+
+// Store tokens using your TokenStore
+await tokenStore.storeTokens(tokens);
+```
+
+## API Methods
+
+### Invoices
+
+```typescript
+const invoices = await client.getInvoices();
+const invoice = await client.getInvoice('123');
+const newInvoice = await client.createInvoice({
+  CustomerRef: { value: '1' },
+  Line: [{ Amount: 100, DetailType: 'SalesItemLineDetail' }]
+});
+```
+
+### Customers
+
+```typescript
+const customers = await client.getCustomers();
+const customer = await client.getCustomer('123');
+const newCustomer = await client.createCustomer({
+  DisplayName: 'Acme Corp'
+});
+```
+
+### Payments
+
+```typescript
+const payments = await client.getPayments();
+const payment = await client.createPayment({
+  CustomerRef: { value: '1' },
+  TotalAmt: 100
+});
+```
+
+### Bills & Vendors
+
+```typescript
+const bills = await client.getBills();
+const vendors = await client.getVendors();
+```
+
+### Raw Query
+
+```typescript
+const results = await client.query<Invoice>(
+  "SELECT * FROM Invoice WHERE Balance > '0'"
+);
+```
+
+## Features
+
+- **No external OAuth dependencies** - Pure fetch-based OAuth 2.0 implementation
+- **Automatic token refresh** - Tokens are refreshed automatically when expired
+- **Rate limiting** - Built-in 500 req/min rate limiter with exponential backoff
+- **Typed entities** - Full TypeScript support for Invoice, Customer, Payment, etc.
+- **Pluggable token storage** - Implement `TokenStore` interface for any backend
+
+## TokenStore Interface
+
+```typescript
+interface TokenStore {
+  getTokens(): Promise<QuickBooksTokens | null>;
+  storeTokens(tokens: QuickBooksTokens): Promise<void>;
+  clearTokens(): Promise<void>;
+}
+
+interface QuickBooksTokens {
+  access_token: string;
+  refresh_token: string;
+  realm_id: string;
+  expires_at: number;
+}
+```
+
+## Error Handling
+
+```typescript
+import { QuickBooksError, QB_ERROR_CODES } from '@panoptic-it-solutions/quickbooks-client';
+
+try {
+  await client.getInvoices();
+} catch (error) {
+  if (error instanceof QuickBooksError) {
+    switch (error.code) {
+      case QB_ERROR_CODES.TOKEN_EXPIRED:
+        // Handle expired token
+        break;
+      case QB_ERROR_CODES.RATE_LIMIT:
+        // Handle rate limiting
+        break;
+      case QB_ERROR_CODES.UNAUTHORIZED:
+        // Handle auth error
+        break;
+    }
+  }
+}
+```
+
+## Configuration
+
+| Option | Required | Default | Description |
+|--------|----------|---------|-------------|
+| `clientId` | Yes | - | OAuth client ID from Intuit |
+| `clientSecret` | Yes | - | OAuth client secret |
+| `redirectUri` | Yes | - | OAuth callback URL |
+| `environment` | No | `production` | `sandbox` or `production` |
+| `tokenStore` | Yes | - | Token storage implementation |
+| `onLog` | No | - | Logging callback |
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,366 @@
+/**
+ * QuickBooks Client Types
+ */
+/** OAuth token data */
+interface QuickBooksTokens {
+    access_token: string;
+    refresh_token: string;
+    realm_id: string;
+    expires_at: number;
+    token_type?: string;
+}
+/** Configuration for the QuickBooks client */
+interface QuickBooksConfig {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    environment?: "sandbox" | "production";
+    scopes?: string[];
+}
+/** Options for initializing the client */
+interface QuickBooksClientOptions extends QuickBooksConfig {
+    tokenStore: TokenStore;
+    /** Optional logging hook */
+    onLog?: (level: "debug" | "info" | "warn" | "error", message: string, data?: unknown) => void;
+}
+/** Token storage interface - implement this for your storage backend */
+interface TokenStore {
+    /** Get stored tokens */
+    getTokens(): Promise<QuickBooksTokens | null>;
+    /** Store tokens */
+    storeTokens(tokens: QuickBooksTokens): Promise<void>;
+    /** Clear stored tokens */
+    clearTokens(): Promise<void>;
+}
+/** OAuth token response from Intuit */
+interface OAuthTokenResponse {
+    access_token: string;
+    refresh_token: string;
+    token_type: string;
+    expires_in: number;
+    x_refresh_token_expires_in: number;
+}
+/** QuickBooks API error response */
+interface QuickBooksApiError {
+    Fault?: {
+        Error?: Array<{
+            Message?: string;
+            Detail?: string;
+            code?: string;
+        }>;
+        type?: string;
+    };
+}
+/** Query response wrapper */
+interface QueryResponse<T> {
+    QueryResponse: Record<string, T[] | number | undefined> & {
+        startPosition?: number;
+        maxResults?: number;
+        totalCount?: number;
+    };
+    time?: string;
+}
+/** Base entity with common fields */
+interface BaseEntity {
+    Id?: string;
+    SyncToken?: string;
+    MetaData?: {
+        CreateTime?: string;
+        LastUpdatedTime?: string;
+    };
+}
+/** Invoice entity */
+interface Invoice extends BaseEntity {
+    DocNumber?: string;
+    TxnDate?: string;
+    DueDate?: string;
+    TotalAmt?: number;
+    Balance?: number;
+    CustomerRef?: {
+        value: string;
+        name?: string;
+    };
+    Line?: InvoiceLine[];
+    BillEmail?: {
+        Address?: string;
+    };
+    CurrencyRef?: {
+        value: string;
+        name?: string;
+    };
+}
+interface InvoiceLine {
+    Id?: string;
+    LineNum?: number;
+    Description?: string;
+    Amount?: number;
+    DetailType?: string;
+    SalesItemLineDetail?: {
+        ItemRef?: {
+            value: string;
+            name?: string;
+        };
+        Qty?: number;
+        UnitPrice?: number;
+    };
+}
+/** Customer entity */
+interface Customer extends BaseEntity {
+    DisplayName?: string;
+    CompanyName?: string;
+    GivenName?: string;
+    FamilyName?: string;
+    PrimaryEmailAddr?: {
+        Address?: string;
+    };
+    PrimaryPhone?: {
+        FreeFormNumber?: string;
+    };
+    BillAddr?: Address;
+    ShipAddr?: Address;
+    Balance?: number;
+    Active?: boolean;
+}
+interface Address {
+    Id?: string;
+    Line1?: string;
+    Line2?: string;
+    City?: string;
+    CountrySubDivisionCode?: string;
+    PostalCode?: string;
+    Country?: string;
+}
+/** Payment entity */
+interface Payment extends BaseEntity {
+    TxnDate?: string;
+    TotalAmt?: number;
+    CustomerRef?: {
+        value: string;
+        name?: string;
+    };
+    DepositToAccountRef?: {
+        value: string;
+        name?: string;
+    };
+    PaymentMethodRef?: {
+        value: string;
+        name?: string;
+    };
+    Line?: PaymentLine[];
+}
+interface PaymentLine {
+    Amount?: number;
+    LinkedTxn?: Array<{
+        TxnId: string;
+        TxnType: string;
+    }>;
+}
+/** Account entity */
+interface Account extends BaseEntity {
+    Name?: string;
+    AccountType?: string;
+    AccountSubType?: string;
+    CurrentBalance?: number;
+    Active?: boolean;
+    Classification?: string;
+    FullyQualifiedName?: string;
+}
+/** Vendor entity */
+interface Vendor extends BaseEntity {
+    DisplayName?: string;
+    CompanyName?: string;
+    GivenName?: string;
+    FamilyName?: string;
+    PrimaryEmailAddr?: {
+        Address?: string;
+    };
+    PrimaryPhone?: {
+        FreeFormNumber?: string;
+    };
+    BillAddr?: Address;
+    Balance?: number;
+    Active?: boolean;
+}
+/** Bill entity */
+interface Bill extends BaseEntity {
+    DocNumber?: string;
+    TxnDate?: string;
+    DueDate?: string;
+    TotalAmt?: number;
+    Balance?: number;
+    VendorRef?: {
+        value: string;
+        name?: string;
+    };
+    Line?: BillLine[];
+}
+interface BillLine {
+    Id?: string;
+    LineNum?: number;
+    Description?: string;
+    Amount?: number;
+    DetailType?: string;
+    AccountBasedExpenseLineDetail?: {
+        AccountRef?: {
+            value: string;
+            name?: string;
+        };
+    };
+}
+/** Item entity */
+interface Item extends BaseEntity {
+    Name?: string;
+    Description?: string;
+    Active?: boolean;
+    FullyQualifiedName?: string;
+    Type?: "Inventory" | "Service" | "NonInventory";
+    UnitPrice?: number;
+    PurchaseCost?: number;
+    QtyOnHand?: number;
+    IncomeAccountRef?: {
+        value: string;
+        name?: string;
+    };
+    ExpenseAccountRef?: {
+        value: string;
+        name?: string;
+    };
+}
+
+/**
+ * QuickBooks Online API Client
+ *
+ * Main client class with rate limiting, auto token refresh, and typed API methods
+ */
+
+declare class QuickBooksClient {
+    private config;
+    private tokenStore;
+    private requestTimestamps;
+    private onLog;
+    constructor(options: QuickBooksClientOptions);
+    private validateConfig;
+    private log;
+    /**
+     * Rate limiting - ensures we don't exceed 500 requests/minute
+     */
+    private checkRateLimit;
+    /**
+     * Get current tokens, refreshing if necessary
+     */
+    private getValidTokens;
+    /**
+     * Make an authenticated API request with retry logic
+     */
+    private request;
+    /**
+     * Execute a query using QuickBooks Query Language
+     */
+    query<T>(sql: string): Promise<T[]>;
+    getInvoice(id: string): Promise<Invoice>;
+    getInvoices(where?: string): Promise<Invoice[]>;
+    createInvoice(invoice: Partial<Invoice>): Promise<Invoice>;
+    updateInvoice(invoice: Invoice): Promise<Invoice>;
+    deleteInvoice(id: string, syncToken: string): Promise<void>;
+    getCustomer(id: string): Promise<Customer>;
+    getCustomers(where?: string): Promise<Customer[]>;
+    createCustomer(customer: Partial<Customer>): Promise<Customer>;
+    updateCustomer(customer: Customer): Promise<Customer>;
+    getPayment(id: string): Promise<Payment>;
+    getPayments(where?: string): Promise<Payment[]>;
+    createPayment(payment: Partial<Payment>): Promise<Payment>;
+    getAccount(id: string): Promise<Account>;
+    getAccounts(where?: string): Promise<Account[]>;
+    getVendor(id: string): Promise<Vendor>;
+    getVendors(where?: string): Promise<Vendor[]>;
+    createVendor(vendor: Partial<Vendor>): Promise<Vendor>;
+    updateVendor(vendor: Vendor): Promise<Vendor>;
+    getBill(id: string): Promise<Bill>;
+    getBills(where?: string): Promise<Bill[]>;
+    createBill(bill: Partial<Bill>): Promise<Bill>;
+    updateBill(bill: Bill): Promise<Bill>;
+    getItem(id: string): Promise<Item>;
+    getItems(where?: string): Promise<Item[]>;
+    createItem(item: Partial<Item>): Promise<Item>;
+    updateItem(item: Item): Promise<Item>;
+    /**
+     * Get company info
+     */
+    getCompanyInfo(): Promise<unknown>;
+    /**
+     * Check if connected to QuickBooks
+     */
+    isConnected(): Promise<boolean>;
+    /**
+     * Check connection status with details
+     */
+    getConnectionStatus(): Promise<{
+        isConnected: boolean;
+        needsRefresh: boolean;
+        realmId?: string;
+        expiresAt?: number;
+    }>;
+}
+
+/**
+ * OAuth 2.0 implementation for QuickBooks Online
+ *
+ * Replaces intuit-oauth with native fetch implementation
+ */
+
+/**
+ * Generate the authorization URL for OAuth flow
+ */
+declare function generateAuthUrl(config: QuickBooksConfig, state: string): string;
+/**
+ * Exchange authorization code for tokens
+ */
+declare function exchangeCodeForTokens(config: QuickBooksConfig, code: string, realmId: string): Promise<QuickBooksTokens>;
+/**
+ * Refresh access token using refresh token
+ */
+declare function refreshTokens(config: QuickBooksConfig, refreshToken: string, realmId: string): Promise<QuickBooksTokens>;
+/**
+ * Revoke tokens (disconnect from QuickBooks)
+ */
+declare function revokeTokens(config: QuickBooksConfig, token: string): Promise<void>;
+/**
+ * Calculate token expiry timestamp from expires_in value
+ */
+declare function calculateTokenExpiry(expiresIn: number): number;
+/**
+ * Check if token is expired or will expire soon (within 5 minutes)
+ */
+declare function isTokenExpired(expiresAt: number, bufferSeconds?: number): boolean;
+/**
+ * Generate a random state parameter for CSRF protection
+ */
+declare function generateState(): string;
+
+/**
+ * QuickBooks Error Handling
+ */
+/** Error codes for QuickBooks API errors */
+declare const QB_ERROR_CODES: {
+    readonly TOKEN_EXPIRED: "QB_TOKEN_EXPIRED";
+    readonly REFRESH_FAILED: "QB_REFRESH_FAILED";
+    readonly UNAUTHORIZED: "QB_UNAUTHORIZED";
+    readonly INVALID_REALM: "QB_INVALID_REALM";
+    readonly API_ERROR: "QB_API_ERROR";
+    readonly RATE_LIMIT: "QB_RATE_LIMIT";
+    readonly NETWORK_ERROR: "QB_NETWORK_ERROR";
+    readonly INVALID_CONFIG: "QB_INVALID_CONFIG";
+    readonly TOKEN_STORE_ERROR: "QB_TOKEN_STORE_ERROR";
+};
+type QuickBooksErrorCode = (typeof QB_ERROR_CODES)[keyof typeof QB_ERROR_CODES];
+/** Custom error class for QuickBooks-related errors */
+declare class QuickBooksError extends Error {
+    code: QuickBooksErrorCode;
+    status?: number | undefined;
+    details?: unknown | undefined;
+    constructor(message: string, code: QuickBooksErrorCode, status?: number | undefined, details?: unknown | undefined);
+}
+/** Handle and normalize errors from QuickBooks API */
+declare function handleQuickBooksError(error: unknown): QuickBooksError;
+
+export { type Account, type Address, type BaseEntity, type Bill, type BillLine, type Customer, type Invoice, type InvoiceLine, type Item, type OAuthTokenResponse, type Payment, type PaymentLine, QB_ERROR_CODES, type QueryResponse, type QuickBooksApiError, QuickBooksClient, type QuickBooksClientOptions, type QuickBooksConfig, QuickBooksError, type QuickBooksErrorCode, type QuickBooksTokens, type TokenStore, type Vendor, calculateTokenExpiry, exchangeCodeForTokens, generateAuthUrl, generateState, handleQuickBooksError, isTokenExpired, refreshTokens, revokeTokens };