@panoptic-it-solutions/quickbooks-client 0.1.3 → 0.2.0

package/dist/index.d.mts

@@ -20,6 +20,8 @@ interface QuickBooksConfig {
 /** Options for initializing the client */
 interface QuickBooksClientOptions extends QuickBooksConfig {
     tokenStore: TokenStore;
+    /** QBO API minor version (e.g. 75). Appended to all API URLs. */
+    minorVersion?: number;
     /** Optional logging hook */
     onLog?: (level: "debug" | "info" | "warn" | "error", message: string, data?: unknown) => void;
 }
@@ -60,6 +62,11 @@ interface QueryResponse<T> {
     };
     time?: string;
 }
+/** Ref type used throughout QBO entities */
+interface Ref {
+    value: string;
+    name?: string;
+}
 /** Base entity with common fields */
 interface BaseEntity {
     Id?: string;
@@ -69,42 +76,44 @@ interface BaseEntity {
         LastUpdatedTime?: string;
     };
 }
-/** Invoice entity */
+/** Address */
+interface Address {
+    Id?: string;
+    Line1?: string;
+    Line2?: string;
+    City?: string;
+    CountrySubDivisionCode?: string;
+    PostalCode?: string;
+    Country?: string;
+}
 interface Invoice extends BaseEntity {
     DocNumber?: string;
     TxnDate?: string;
     DueDate?: string;
     TotalAmt?: number;
     Balance?: number;
-    CustomerRef?: {
-        value: string;
-        name?: string;
-    };
+    CustomerRef?: Ref;
     Line?: InvoiceLine[];
     BillEmail?: {
         Address?: string;
     };
-    CurrencyRef?: {
-        value: string;
-        name?: string;
-    };
+    CurrencyRef?: Ref;
+    TxnTaxDetail?: TxnTaxDetail;
+    PrivateNote?: string;
 }
 interface InvoiceLine {
     Id?: string;
     LineNum?: number;
     Description?: string;
     Amount?: number;
-    DetailType?: string;
+    DetailType?: "SalesItemLineDetail" | "SubTotalLineDetail" | "DiscountLineDetail" | "GroupLineDetail" | string;
     SalesItemLineDetail?: {
-        ItemRef?: {
-            value: string;
-            name?: string;
-        };
+        ItemRef?: Ref;
+        TaxCodeRef?: Ref;
         Qty?: number;
         UnitPrice?: number;
     };
 }
-/** Customer entity */
 interface Customer extends BaseEntity {
     DisplayName?: string;
     CompanyName?: string;
@@ -121,31 +130,12 @@ interface Customer extends BaseEntity {
     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;
-    };
+    CustomerRef?: Ref;
+    DepositToAccountRef?: Ref;
+    PaymentMethodRef?: Ref;
     Line?: PaymentLine[];
 }
 interface PaymentLine {
@@ -155,7 +145,6 @@ interface PaymentLine {
         TxnType: string;
     }>;
 }
-/** Account entity */
 interface Account extends BaseEntity {
     Name?: string;
     AccountType?: string;
@@ -164,8 +153,8 @@ interface Account extends BaseEntity {
     Active?: boolean;
     Classification?: string;
     FullyQualifiedName?: string;
+    CurrencyRef?: Ref;
 }
-/** Vendor entity */
 interface Vendor extends BaseEntity {
     DisplayName?: string;
     CompanyName?: string;
@@ -180,34 +169,227 @@ interface Vendor extends BaseEntity {
     BillAddr?: Address;
     Balance?: number;
     Active?: boolean;
+    TaxIdentifier?: string;
+    CurrencyRef?: Ref;
 }
-/** Bill entity */
 interface Bill extends BaseEntity {
     DocNumber?: string;
     TxnDate?: string;
     DueDate?: string;
     TotalAmt?: number;
     Balance?: number;
-    VendorRef?: {
-        value: string;
-        name?: string;
-    };
+    VendorRef?: Ref;
+    APAccountRef?: Ref;
     Line?: BillLine[];
+    TxnTaxDetail?: TxnTaxDetail;
+    PrivateNote?: string;
+    CurrencyRef?: Ref;
+    DepartmentRef?: Ref;
 }
 interface BillLine {
     Id?: string;
     LineNum?: number;
     Description?: string;
     Amount?: number;
-    DetailType?: string;
+    DetailType?: "AccountBasedExpenseLineDetail" | "ItemBasedExpenseLineDetail" | string;
+    AccountBasedExpenseLineDetail?: {
+        AccountRef?: Ref;
+        TaxCodeRef?: Ref;
+        BillableStatus?: "Billable" | "NotBillable" | "HasBeenBilled";
+        CustomerRef?: Ref;
+        TaxAmount?: number;
+    };
+    ItemBasedExpenseLineDetail?: {
+        ItemRef?: Ref;
+        TaxCodeRef?: Ref;
+        BillableStatus?: "Billable" | "NotBillable" | "HasBeenBilled";
+        CustomerRef?: Ref;
+        Qty?: number;
+        UnitPrice?: number;
+    };
+}
+interface BillPayment extends BaseEntity {
+    VendorRef?: Ref;
+    TotalAmt?: number;
+    PayType?: "Check" | "CreditCard";
+    DocNumber?: string;
+    TxnDate?: string;
+    APAccountRef?: Ref;
+    DepartmentRef?: Ref;
+    CurrencyRef?: Ref;
+    PrivateNote?: string;
+    Line?: BillPaymentLine[];
+    CheckPayment?: {
+        BankAccountRef?: Ref;
+        PrintStatus?: "NeedToPrint" | "NotSet";
+    };
+    CreditCardPayment?: {
+        CCAccountRef?: Ref;
+    };
+}
+interface BillPaymentLine {
+    Amount?: number;
+    LinkedTxn?: Array<{
+        TxnId: string;
+        TxnType: "Bill" | string;
+    }>;
+}
+interface CreditMemo extends BaseEntity {
+    DocNumber?: string;
+    TxnDate?: string;
+    TotalAmt?: number;
+    Balance?: number;
+    RemainingCredit?: number;
+    CustomerRef?: Ref;
+    Line?: CreditMemoLine[];
+    BillEmail?: {
+        Address?: string;
+    };
+    CurrencyRef?: Ref;
+    TxnTaxDetail?: TxnTaxDetail;
+    PrivateNote?: string;
+    DepartmentRef?: Ref;
+}
+interface CreditMemoLine {
+    Id?: string;
+    LineNum?: number;
+    Description?: string;
+    Amount?: number;
+    DetailType?: "SalesItemLineDetail" | "SubTotalLineDetail" | string;
+    SalesItemLineDetail?: {
+        ItemRef?: Ref;
+        TaxCodeRef?: Ref;
+        Qty?: number;
+        UnitPrice?: number;
+    };
+}
+interface VendorCredit extends BaseEntity {
+    DocNumber?: string;
+    TxnDate?: string;
+    TotalAmt?: number;
+    Balance?: number;
+    VendorRef?: Ref;
+    APAccountRef?: Ref;
+    Line?: VendorCreditLine[];
+    CurrencyRef?: Ref;
+    PrivateNote?: string;
+    DepartmentRef?: Ref;
+}
+interface VendorCreditLine {
+    Id?: string;
+    LineNum?: number;
+    Description?: string;
+    Amount?: number;
+    DetailType?: "AccountBasedExpenseLineDetail" | "ItemBasedExpenseLineDetail" | string;
     AccountBasedExpenseLineDetail?: {
-        AccountRef?: {
-            value: string;
-            name?: string;
-        };
+        AccountRef?: Ref;
+        TaxCodeRef?: Ref;
+        BillableStatus?: "Billable" | "NotBillable" | "HasBeenBilled";
+        CustomerRef?: Ref;
+    };
+    ItemBasedExpenseLineDetail?: {
+        ItemRef?: Ref;
+        TaxCodeRef?: Ref;
+        BillableStatus?: "Billable" | "NotBillable" | "HasBeenBilled";
+        CustomerRef?: Ref;
+        Qty?: number;
+        UnitPrice?: number;
+    };
+}
+interface TaxCode extends BaseEntity {
+    Name?: string;
+    Description?: string;
+    Active?: boolean;
+    Taxable?: boolean;
+    TaxGroup?: boolean;
+    SalesTaxRateList?: {
+        TaxRateDetail?: TaxRateDetail[];
+    };
+    PurchaseTaxRateList?: {
+        TaxRateDetail?: TaxRateDetail[];
+    };
+}
+interface TaxRateDetail {
+    TaxRateRef?: Ref;
+    TaxTypeApplicable?: "TaxOnAmount" | "TaxOnAmountPlusTax" | "TaxOnTax";
+    TaxOrder?: number;
+}
+interface TaxRate extends BaseEntity {
+    Name?: string;
+    Description?: string;
+    RateValue?: number;
+    Active?: boolean;
+    AgencyRef?: Ref;
+    TaxReturnLineRef?: Ref;
+    SpecialTaxType?: string;
+    DisplayType?: string;
+}
+/** Tax detail block used on transactions (Invoice, Bill, CreditMemo, etc.) */
+interface TxnTaxDetail {
+    TxnTaxCodeRef?: Ref;
+    TotalTax?: number;
+    TaxLine?: TaxLine[];
+}
+interface TaxLine {
+    Amount?: number;
+    DetailType?: "TaxLineDetail";
+    TaxLineDetail?: {
+        TaxRateRef?: Ref;
+        PercentBased?: boolean;
+        TaxPercent?: number;
+        NetAmountTaxable?: number;
+        TaxInclusiveAmount?: number;
+        OverrideDeltaAmount?: number;
     };
 }
-/** Item entity */
+interface Attachable extends BaseEntity {
+    FileName?: string;
+    FileAccessUri?: string;
+    TempDownloadUri?: string;
+    Size?: number;
+    ContentType?: string;
+    Category?: string;
+    Lat?: string;
+    Long?: string;
+    PlaceName?: string;
+    Note?: string;
+    Tag?: string;
+    ThumbnailFileAccessUri?: string;
+    ThumbnailTempDownloadUri?: string;
+    AttachableRef?: AttachableRef[];
+}
+interface AttachableRef {
+    EntityRef?: Ref;
+    IncludeOnSend?: boolean;
+    LineInfo?: string;
+    NoRefOnly?: boolean;
+    /** e.g. "Bill", "Invoice", "VendorCredit" */
+    Inactive?: boolean;
+}
+interface CompanyInfo extends BaseEntity {
+    CompanyName?: string;
+    LegalName?: string;
+    CompanyAddr?: Address;
+    CustomerCommunicationAddr?: Address;
+    LegalAddr?: Address;
+    PrimaryPhone?: {
+        FreeFormNumber?: string;
+    };
+    CompanyStartDate?: string;
+    FiscalYearStartMonth?: string;
+    Country?: string;
+    Email?: {
+        Address?: string;
+    };
+    WebAddr?: {
+        URI?: string;
+    };
+    SupportedLanguages?: string;
+    NameValue?: Array<{
+        Name: string;
+        Value: string;
+    }>;
+}
 interface Item extends BaseEntity {
     Name?: string;
     Description?: string;
@@ -217,15 +399,41 @@ interface Item extends BaseEntity {
     UnitPrice?: number;
     PurchaseCost?: number;
     QtyOnHand?: number;
-    IncomeAccountRef?: {
-        value: string;
-        name?: string;
-    };
-    ExpenseAccountRef?: {
-        value: string;
-        name?: string;
+    IncomeAccountRef?: Ref;
+    ExpenseAccountRef?: Ref;
+    AssetAccountRef?: Ref;
+    Taxable?: boolean;
+    SalesTaxIncluded?: boolean;
+    PurchaseTaxIncluded?: boolean;
+    SalesTaxCodeRef?: Ref;
+    PurchaseTaxCodeRef?: Ref;
+}
+interface BatchItemRequest {
+    /** Unique ID for this batch item (you choose) */
+    bId: string;
+    /** Operation to perform */
+    operation: "create" | "update" | "delete" | "query";
+    /** Only for non-query operations: entity name e.g. "Bill", "Invoice" */
+    optionsData?: string;
+    /** The entity payload (for create/update/delete) */
+    [entityName: string]: unknown;
+}
+interface BatchItemResponse {
+    bId: string;
+    [key: string]: unknown;
+    Fault?: {
+        Error?: Array<{
+            Message?: string;
+            Detail?: string;
+            code?: string;
+        }>;
+        type?: string;
     };
 }
+interface BatchResponse {
+    BatchItemResponse: BatchItemResponse[];
+    time?: string;
+}
 
 /**
  * QuickBooks Online API Client
@@ -238,9 +446,14 @@ declare class QuickBooksClient {
     private tokenStore;
     private requestTimestamps;
     private onLog;
+    private minorVersion;
     constructor(options: QuickBooksClientOptions);
     private validateConfig;
     private log;
+    /**
+     * Append minorversion query param to a URL if configured
+     */
+    private appendMinorVersion;
     /**
      * Rate limiting - ensures we don't exceed 500 requests/minute
      */
@@ -285,14 +498,59 @@ declare class QuickBooksClient {
     getBills(where?: string): Promise<Bill[]>;
     createBill(bill: Partial<Bill>): Promise<Bill>;
     updateBill(bill: Bill): Promise<Bill>;
+    deleteBill(id: string, syncToken: string): Promise<void>;
+    getBillPayment(id: string): Promise<BillPayment>;
+    getBillPayments(where?: string): Promise<BillPayment[]>;
+    createBillPayment(billPayment: Partial<BillPayment>): Promise<BillPayment>;
+    updateBillPayment(billPayment: BillPayment): Promise<BillPayment>;
+    deleteBillPayment(id: string, syncToken: string): Promise<void>;
+    getCreditMemo(id: string): Promise<CreditMemo>;
+    getCreditMemos(where?: string): Promise<CreditMemo[]>;
+    createCreditMemo(creditMemo: Partial<CreditMemo>): Promise<CreditMemo>;
+    updateCreditMemo(creditMemo: CreditMemo): Promise<CreditMemo>;
+    deleteCreditMemo(id: string, syncToken: string): Promise<void>;
+    getVendorCredit(id: string): Promise<VendorCredit>;
+    getVendorCredits(where?: string): Promise<VendorCredit[]>;
+    createVendorCredit(vendorCredit: Partial<VendorCredit>): Promise<VendorCredit>;
+    updateVendorCredit(vendorCredit: VendorCredit): Promise<VendorCredit>;
+    deleteVendorCredit(id: string, syncToken: string): Promise<void>;
+    getTaxCode(id: string): Promise<TaxCode>;
+    getTaxCodes(where?: string): Promise<TaxCode[]>;
+    getTaxRate(id: string): Promise<TaxRate>;
+    getTaxRates(where?: string): Promise<TaxRate[]>;
     getItem(id: string): Promise<Item>;
     getItems(where?: string): Promise<Item[]>;
     createItem(item: Partial<Item>): Promise<Item>;
     updateItem(item: Item): Promise<Item>;
+    getAttachable(id: string): Promise<Attachable>;
+    getAttachables(where?: string): Promise<Attachable[]>;
+    /**
+     * Upload a file and attach it to an entity.
+     * Uses multipart/form-data — the QBO upload endpoint differs from standard CRUD.
+     */
+    uploadAttachable(file: Blob | Buffer, fileName: string, contentType: string, attachTo?: {
+        entityType: string;
+        entityId: string;
+    }): Promise<Attachable>;
+    updateAttachable(attachable: Attachable): Promise<Attachable>;
+    deleteAttachable(id: string, syncToken: string): Promise<void>;
+    /**
+     * Execute a batch of up to 30 operations in a single API call.
+     * Each item needs a unique bId and the entity payload.
+     *
+     * @example
+     * ```ts
+     * const results = await client.batch([
+     *   { bId: "1", operation: "create", Bill: { VendorRef: { value: "1" }, Line: [...] } },
+     *   { bId: "2", operation: "query", optionsData: "SELECT * FROM Vendor WHERE Id = '1'" },
+     * ]);
+     * ```
+     */
+    batch(items: BatchItemRequest[]): Promise<BatchResponse>;
     /**
      * Get company info
      */
-    getCompanyInfo(): Promise<unknown>;
+    getCompanyInfo(): Promise<CompanyInfo>;
     /**
      * Check if connected to QuickBooks
      */
@@ -308,6 +566,32 @@ declare class QuickBooksClient {
     }>;
 }
 
+/**
+ * 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;
+
 /**
  * OAuth 2.0 implementation for QuickBooks Online
  *
@@ -343,30 +627,4 @@ declare function isTokenExpired(expiresAt: number, bufferSeconds?: number): bool
  */
 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 };
+export { type Account, type Address, type Attachable, type AttachableRef, type BaseEntity, type BatchItemRequest, type BatchItemResponse, type BatchResponse, type Bill, type BillLine, type BillPayment, type BillPaymentLine, type CompanyInfo, type CreditMemo, type CreditMemoLine, 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 Ref, type TaxCode, type TaxLine, type TaxRate, type TaxRateDetail, type TokenStore, type TxnTaxDetail, type Vendor, type VendorCredit, type VendorCreditLine, calculateTokenExpiry, exchangeCodeForTokens, generateAuthUrl, generateState, handleQuickBooksError, isTokenExpired, refreshTokens, revokeTokens };