@oomol-lab/open-connector 1.8.0 → 1.9.0

package/src/providers/quickbooks/resources.js

@@ -0,0 +1,256 @@
+const operationLetters = {
+    l: "list",
+    g: "get",
+    c: "create",
+    u: "update",
+    d: "delete",
+};
+function resource(input) {
+    return {
+        key: input.key,
+        plural: input.plural,
+        label: input.label ?? input.key.replaceAll("_", " "),
+        entity: { name: input.entity, path: input.entity.toLowerCase() },
+        operations: [...input.operations].map((letter) => operationLetters[letter]),
+        remove: input.remove ?? "delete",
+        nameColumn: input.nameColumn,
+        hasActive: input.hasActive ?? false,
+        hasTxnDate: input.hasTxnDate ?? false,
+        defaultOrder: input.defaultOrder ?? input.nameColumn,
+        createHint: input.createHint,
+    };
+}
+function transaction(input) {
+    return resource({ hasTxnDate: true, defaultOrder: "TxnDate", ...input });
+}
+/** Every entity with generated CRUD actions, keyed by `key`. Operations: l=list g=get c=create u=update d=delete. */
+export const quickbooksResources = Object.fromEntries([
+    transaction({
+        key: "bill",
+        plural: "bills",
+        entity: "Bill",
+        operations: "lgcud",
+        createHint: "VendorRef and Line (AccountBasedExpenseLineDetail or ItemBasedExpenseLineDetail lines)",
+    }),
+    transaction({
+        key: "bill_payment",
+        plural: "bill_payments",
+        entity: "BillPayment",
+        operations: "lgcud",
+        createHint: "VendorRef, PayType (Check or CreditCard), TotalAmt, Line with LinkedTxn bills, and CheckPayment or CreditCardPayment",
+    }),
+    resource({ key: "budget", plural: "budgets", entity: "Budget", operations: "l" }),
+    resource({
+        key: "class",
+        plural: "classes",
+        entity: "Class",
+        operations: "l",
+        nameColumn: "Name",
+        hasActive: true,
+    }),
+    transaction({
+        key: "credit_memo",
+        plural: "credit_memos",
+        entity: "CreditMemo",
+        operations: "lgcud",
+        createHint: "CustomerRef and Line (SalesItemLineDetail lines)",
+    }),
+    resource({
+        key: "credit_term",
+        plural: "credit_terms",
+        entity: "Term",
+        operations: "lgcud",
+        remove: "deactivate",
+        nameColumn: "Name",
+        hasActive: true,
+        createHint: "Name and either DueDays or DayOfMonthDue",
+    }),
+    resource({
+        key: "currency",
+        plural: "currencies",
+        entity: "CompanyCurrency",
+        operations: "l",
+        hasActive: true,
+    }),
+    resource({
+        key: "customer",
+        plural: "customers",
+        entity: "Customer",
+        operations: "lgcud",
+        remove: "deactivate",
+        nameColumn: "DisplayName",
+        hasActive: true,
+    }),
+    resource({
+        key: "department",
+        plural: "departments",
+        entity: "Department",
+        operations: "lgcud",
+        remove: "deactivate",
+        nameColumn: "Name",
+        hasActive: true,
+        createHint: "Name",
+    }),
+    transaction({
+        key: "deposit",
+        plural: "deposits",
+        entity: "Deposit",
+        operations: "lgcud",
+        createHint: "DepositToAccountRef and Line (DepositLineDetail lines)",
+    }),
+    resource({
+        key: "employee",
+        plural: "employees",
+        entity: "Employee",
+        operations: "lgcud",
+        remove: "deactivate",
+        nameColumn: "DisplayName",
+        hasActive: true,
+        createHint: "GivenName and FamilyName",
+    }),
+    transaction({
+        key: "estimate",
+        plural: "estimates",
+        entity: "Estimate",
+        operations: "lgcud",
+        createHint: "CustomerRef and Line (SalesItemLineDetail lines)",
+    }),
+    resource({
+        key: "invoice",
+        plural: "invoices",
+        entity: "Invoice",
+        operations: "lgcud",
+        hasTxnDate: true,
+        defaultOrder: "TxnDate",
+    }),
+    resource({
+        key: "journal_code",
+        plural: "journal_codes",
+        entity: "JournalCode",
+        operations: "lgcu",
+        nameColumn: "Name",
+        createHint: "Name and Type",
+    }),
+    transaction({
+        key: "journal_entry",
+        plural: "journal_entries",
+        entity: "JournalEntry",
+        operations: "lgcud",
+        createHint: "Line with balanced debit and credit JournalEntryLineDetail lines",
+    }),
+    resource({
+        key: "account",
+        plural: "accounts",
+        entity: "Account",
+        operations: "lgcd",
+        remove: "deactivate",
+        nameColumn: "Name",
+        hasActive: true,
+        createHint: "Name and AccountType, or Name and AccountSubType",
+    }),
+    resource({
+        key: "payment_method",
+        plural: "payment_methods",
+        entity: "PaymentMethod",
+        operations: "lgcd",
+        remove: "deactivate",
+        nameColumn: "Name",
+        hasActive: true,
+        createHint: "Name",
+    }),
+    transaction({ key: "payment", plural: "payments", entity: "Payment", operations: "lgcud" }),
+    resource({
+        key: "product",
+        plural: "products",
+        entity: "Item",
+        operations: "lgcud",
+        remove: "deactivate",
+        label: "product or service",
+        nameColumn: "Name",
+        hasActive: true,
+        createHint: "Name and Type (Service, Inventory or NonInventory), plus IncomeAccountRef for sellable items",
+    }),
+    transaction({
+        key: "purchase_order",
+        plural: "purchase_orders",
+        entity: "PurchaseOrder",
+        operations: "lgcud",
+        createHint: "VendorRef, APAccountRef and Line (ItemBasedExpenseLineDetail or AccountBasedExpenseLineDetail lines)",
+    }),
+    transaction({
+        key: "purchase",
+        plural: "purchases",
+        entity: "Purchase",
+        operations: "lgcud",
+        label: "purchase (expense, check or credit card charge)",
+        createHint: "AccountRef, PaymentType (Cash, Check or CreditCard) and Line",
+    }),
+    transaction({
+        key: "refund_receipt",
+        plural: "refund_receipts",
+        entity: "RefundReceipt",
+        operations: "lgcud",
+        createHint: "Line (SalesItemLineDetail lines), DepositToAccountRef and optionally CustomerRef",
+    }),
+    transaction({
+        key: "sales_receipt",
+        plural: "sales_receipts",
+        entity: "SalesReceipt",
+        operations: "lgcud",
+        createHint: "Line (SalesItemLineDetail lines) and optionally CustomerRef and DepositToAccountRef",
+    }),
+    resource({
+        key: "tax_agency",
+        plural: "tax_agencies",
+        entity: "TaxAgency",
+        operations: "lgc",
+        createHint: "DisplayName",
+    }),
+    resource({ key: "tax_code", plural: "tax_codes", entity: "TaxCode", operations: "lg", nameColumn: "Name" }),
+    resource({ key: "tax_rate", plural: "tax_rates", entity: "TaxRate", operations: "lg", nameColumn: "Name" }),
+    transaction({
+        key: "time_activity",
+        plural: "time_activities",
+        entity: "TimeActivity",
+        operations: "lgcud",
+        createHint: "NameOf (Employee or Vendor), the matching EmployeeRef or VendorRef, and Hours/Minutes or StartTime/EndTime",
+    }),
+    transaction({
+        key: "transfer",
+        plural: "transfers",
+        entity: "Transfer",
+        operations: "lgcud",
+        createHint: "FromAccountRef, ToAccountRef and Amount",
+    }),
+    transaction({
+        key: "vendor_credit",
+        plural: "vendor_credits",
+        entity: "VendorCredit",
+        operations: "lgcud",
+        createHint: "VendorRef and Line (AccountBasedExpenseLineDetail or ItemBasedExpenseLineDetail lines)",
+    }),
+    resource({
+        key: "vendor",
+        plural: "vendors",
+        entity: "Vendor",
+        operations: "lgcud",
+        remove: "deactivate",
+        nameColumn: "DisplayName",
+        hasActive: true,
+        createHint: "DisplayName, or at least one of GivenName, FamilyName and CompanyName",
+    }),
+].map((entry) => [entry.key, entry]));
+/** Action name of a generated operation, such as `list_bills` or `update_bill`. */
+export function resourceActionName(resource, operation) {
+    return operation === "list" ? `list_${resource.plural}` : `${operation}_${resource.key}`;
+}
+/** The entity of a table entry, for hand-written handlers that need the same path and name. */
+export function quickbooksEntity(key) {
+    const resource = quickbooksResources[key];
+    if (!resource) {
+        throw new Error(`Unknown QuickBooks resource ${key}`);
+    }
+    return resource.entity;
+}
+/** Entity of the `Attachable` record that holds attachment metadata. */
+export const quickbooksAttachable = { name: "Attachable", path: "attachable" };

package/src/providers/quickbooks/runtime.d.ts

@@ -0,0 +1,93 @@
+import type { ProviderFetch } from "../provider-runtime.ts";
+import type { QuickbooksEntity, QuickbooksEnvironment } from "./constants.ts";
+/** What a handler needs to call one company's QuickBooks API. */
+export interface QuickbooksContext {
+    accessToken: string;
+    tokenType: string;
+    realmId: string;
+    baseUrl: string;
+    fetcher: ProviderFetch;
+    signal?: AbortSignal;
+}
+export interface QuickbooksRequest {
+    /** Path below `/v3/company/{realmId}/`. */
+    path: string;
+    method?: "GET" | "POST";
+    query?: Record<string, string | undefined>;
+    /** Objects are sent as JSON; a string is sent as is (used by `send_invoice`'s empty body). */
+    body?: unknown;
+    contentType?: string;
+    /** Multipart upload body; the runtime lets `fetch` set the multipart content type. */
+    formData?: FormData;
+    /** Return the response as `{ text }` instead of parsing JSON, for endpoints that answer with plain text. */
+    responseText?: boolean;
+}
+/** One page of a query: the rows plus `totalCount` when the statement was a count. */
+export interface QuickbooksQueryPage {
+    rows: unknown[];
+    totalCount: number | null;
+}
+/**
+ * Call the QuickBooks Accounting API for one company and return the parsed
+ * JSON body. A `Fault` body, or any non-2xx status, becomes a
+ * `ProviderRequestError` carrying the upstream message and `intuit_tid`.
+ */
+export declare function quickbooksRequest(context: QuickbooksContext, request: QuickbooksRequest): Promise<Record<string, unknown>>;
+/** GET the connected company's CompanyInfo record. */
+export declare function getCompanyInfo(context: QuickbooksContext): Promise<Record<string, unknown>>;
+/** Run a query statement and return its rows. */
+export declare function runQuery(context: QuickbooksContext, statement: string): Promise<QuickbooksQueryPage>;
+/** The paging envelope shared by every list-shaped output. */
+export declare function pageResult(rows: unknown[], paging: QuickbooksPaging): Record<string, unknown>;
+/** List an entity with the given filters and ordering. */
+export declare function listEntities(context: QuickbooksContext, select: QuickbooksSelect): Promise<Record<string, unknown>>;
+/** GET one entity and return its record. */
+export declare function readEntity(context: QuickbooksContext, entity: QuickbooksEntity, id: string): Promise<Record<string, unknown>>;
+/** POST a new entity and return the created record. */
+export declare function createEntity(context: QuickbooksContext, entity: QuickbooksEntity, body: Record<string, unknown>): Promise<Record<string, unknown>>;
+/** Update an entity; `fields` are the QuickBooks body fields to change. */
+export declare function updateEntity(context: QuickbooksContext, entity: QuickbooksEntity, input: Record<string, unknown>, fields: Record<string, unknown>): Promise<Record<string, unknown>>;
+/** Void or delete an entity with `POST /{entity}?operation=...`. */
+export declare function operateOnEntity(context: QuickbooksContext, entity: QuickbooksEntity, operation: "void" | "delete", input: Record<string, unknown>): Promise<Record<string, unknown>>;
+/** Read a report such as `ProfitAndLoss` with the shared date-range options. */
+export declare function readReport(context: QuickbooksContext, reportName: string, input: Record<string, unknown>): Promise<Record<string, unknown>>;
+/**
+ * Read the `environment` credential or client-config value. A blank value means
+ * production; anything other than `production` or `sandbox` is rejected so a
+ * typo can never silently send live credentials to the wrong host.
+ */
+export declare function resolveQuickbooksEnvironment(value: unknown, createError?: (message: string) => Error): QuickbooksEnvironment;
+export interface QuickbooksPaging {
+    startPosition: number;
+    maxResults: number;
+}
+export interface QuickbooksSelect extends QuickbooksPaging {
+    entity: string;
+    conditions: string[];
+    orderBy?: string;
+    descending?: boolean;
+}
+/**
+ * Quote a value as a QuickBooks query string literal. QuickBooks escapes a
+ * single quote with a backslash, so a backslash has to be escaped as well or a
+ * trailing one would swallow the closing quote.
+ */
+export declare function quoteQuickbooksString(value: string): string;
+/** `column = 'value'`; `column` is always a provider constant, never caller input. */
+export declare function equalsCondition(column: string, value: string): string;
+/** `column LIKE '%value%'`. */
+export declare function containsCondition(column: string, value: string): string;
+/** `column <op> 'value'` for ordered comparisons such as `TxnDate >= '2026-01-01'`. */
+export declare function compareCondition(column: string, operator: ">=" | "<=" | ">", value: string): string;
+/** Condition for the `status` list filter; QuickBooks hides inactive rows unless asked for them. */
+export declare function statusCondition(status: string | undefined): string;
+/** Read and bound `start_position` and `max_results`. */
+export declare function readPaging(input: Record<string, unknown>): QuickbooksPaging;
+/** Build a `select *` statement with filters, ordering and paging. */
+export declare function buildSelectStatement(select: QuickbooksSelect): string;
+/** `TxnDate` range conditions for the `txn_date_from` and `txn_date_to` list filters. */
+export declare function txnDateConditions(input: Record<string, unknown>): string[];
+/** Reject anything but a read-only `select` statement. */
+export declare function assertReadOnlySelect(statement: string): void;
+/** Reject anything but a `select` statement without its own paging clauses. */
+export declare function assertSelectStatement(statement: string): void;

package/src/providers/quickbooks/runtime.js

@@ -0,0 +1,278 @@
+import { looseArray, optionalBoolean, optionalInteger, optionalRecord, optionalString } from "../../core/cast.js";
+import { encodePathSegment } from "../../core/request.js";
+import { ProviderRequestError, parseProviderJsonBodyText, providerInputError, providerUserAgent, readProviderTextBody, requiredInputString, requiredResponseRecord, runProviderRequest, setSearchParams, withRetryAfterSeconds, } from "../provider-runtime.js";
+import { quickbooksDefaultMaxResults, quickbooksMaxResults, quickbooksMinorVersion } from "./constants.js";
+const staleObjectCode = "5010";
+const staleObjectPattern = /stale object/i;
+const throttleWaitHint = "QuickBooks allows about 500 requests per minute per company; wait about 60 seconds and retry.";
+/**
+ * Call the QuickBooks Accounting API for one company and return the parsed
+ * JSON body. A `Fault` body, or any non-2xx status, becomes a
+ * `ProviderRequestError` carrying the upstream message and `intuit_tid`.
+ */
+export async function quickbooksRequest(context, request) {
+    const url = new URL(`${context.baseUrl}/v3/company/${encodePathSegment(context.realmId)}/${request.path}`);
+    setSearchParams(url, { ...request.query, minorversion: quickbooksMinorVersion });
+    const headers = {
+        accept: request.responseText ? "*/*" : "application/json",
+        authorization: `${context.tokenType} ${context.accessToken}`,
+        "user-agent": providerUserAgent,
+    };
+    let body = request.formData;
+    if (request.body !== undefined) {
+        body = typeof request.body === "string" ? request.body : JSON.stringify(request.body);
+        headers["content-type"] = request.contentType ?? "application/json";
+    }
+    return runProviderRequest({ signal: context.signal, label: "QuickBooks" }, async (signal) => {
+        const response = await context.fetcher(url, { method: request.method ?? "GET", headers, body, signal });
+        const text = await readProviderTextBody(response, "QuickBooks response");
+        if (request.responseText && response.ok) {
+            return { text: text.trim() };
+        }
+        const payload = optionalRecord(parseProviderJsonBodyText(text, {
+            emptyBody: {},
+            invalidJsonMessage: "QuickBooks returned an invalid JSON response",
+            // An error page is not JSON; the status line still tells the caller what happened.
+            invalidJsonFallback: response.ok ? undefined : () => ({}),
+        }));
+        const intuitTid = response.headers.get("intuit_tid") ?? undefined;
+        const fault = optionalRecord(payload?.Fault);
+        if (!response.ok || fault) {
+            throw quickbooksError(response, fault, intuitTid);
+        }
+        return requiredResponseRecord(payload, "QuickBooks response");
+    });
+}
+function quickbooksError(response, fault, intuitTid) {
+    const errors = looseArray(fault?.Error).map((entry) => optionalRecord(entry) ?? {});
+    const described = errors
+        .map((error) => {
+        const text = [optionalString(error.Message), optionalString(error.Detail)].filter(Boolean).join(": ");
+        const code = optionalString(error.code);
+        return code ? `${text} (code ${code})` : text;
+    })
+        .filter(Boolean)
+        .join("; ");
+    const stale = errors.some((error) => optionalString(error.code) === staleObjectCode ||
+        staleObjectPattern.test(`${optionalString(error.Message) ?? ""} ${optionalString(error.Detail) ?? ""}`));
+    const tid = intuitTid ? ` [intuit_tid ${intuitTid}]` : "";
+    const details = { intuitTid, fault };
+    // A 200 carrying a Fault is still a failure; treat it as the caller's bad request.
+    const status = response.ok ? 400 : response.status;
+    if (stale) {
+        return new ProviderRequestError(400, `The SyncToken is stale because the entity changed after it was read. Re-fetch the entity and retry with its current SyncToken. ${described}${tid}`, details);
+    }
+    if (status === 429) {
+        return new ProviderRequestError(429, `QuickBooks rate limit exceeded. ${throttleWaitHint}${tid}`, withRetryAfterSeconds(response, details));
+    }
+    const message = `${described || `QuickBooks request failed (HTTP ${status})`}${tid}`;
+    if (status >= 500) {
+        return new ProviderRequestError(502, message, details);
+    }
+    return new ProviderRequestError(status, message, details, "provider_error");
+}
+/** GET the connected company's CompanyInfo record. */
+export async function getCompanyInfo(context) {
+    const payload = await quickbooksRequest(context, {
+        path: `companyinfo/${encodePathSegment(context.realmId)}`,
+    });
+    return requiredResponseRecord(payload.CompanyInfo, "QuickBooks CompanyInfo");
+}
+/** Run a query statement and return its rows. */
+export async function runQuery(context, statement) {
+    const payload = await quickbooksRequest(context, { path: "query", query: { query: statement } });
+    const response = optionalRecord(payload.QueryResponse) ?? {};
+    const totalCount = optionalInteger(response.totalCount);
+    // The rows sit under the entity name; the other keys are paging metadata.
+    const rows = Object.values(response).find(Array.isArray);
+    return { rows: rows ?? [], totalCount: totalCount ?? null };
+}
+/** The paging envelope shared by every list-shaped output. */
+export function pageResult(rows, paging) {
+    const hasMore = rows.length >= paging.maxResults;
+    return {
+        items: rows,
+        start_position: paging.startPosition,
+        max_results: paging.maxResults,
+        next_start_position: hasMore ? paging.startPosition + rows.length : null,
+        has_more: hasMore,
+    };
+}
+/** List an entity with the given filters and ordering. */
+export async function listEntities(context, select) {
+    const page = await runQuery(context, buildSelectStatement(select));
+    return pageResult(page.rows, select);
+}
+/** GET one entity and return its record. */
+export async function readEntity(context, entity, id) {
+    const payload = await quickbooksRequest(context, { path: `${entity.path}/${encodePathSegment(id)}` });
+    return requiredResponseRecord(payload[entity.name], `QuickBooks ${entity.name}`);
+}
+/** POST a new entity and return the created record. */
+export async function createEntity(context, entity, body) {
+    const payload = await quickbooksRequest(context, { path: entity.path, method: "POST", body });
+    return requiredResponseRecord(payload[entity.name], `QuickBooks ${entity.name}`);
+}
+/**
+ * The caller's SyncToken, or the entity's current one when the caller gave none.
+ * Fetching it first means an update never silently targets a stale version, but
+ * it also overwrites edits made since the caller last read the entity.
+ */
+async function resolveSyncToken(context, entity, input, id) {
+    const provided = optionalString(input.sync_token);
+    if (provided) {
+        return provided;
+    }
+    const current = await readEntity(context, entity, id);
+    const token = optionalString(current.SyncToken);
+    if (!token) {
+        throw new ProviderRequestError(502, `QuickBooks ${entity.name} response is missing SyncToken`);
+    }
+    return token;
+}
+/** Update an entity; `fields` are the QuickBooks body fields to change. */
+export async function updateEntity(context, entity, input, fields) {
+    const id = requiredInputString(input.id, "id");
+    const syncToken = await resolveSyncToken(context, entity, input, id);
+    const sparse = optionalBoolean(input.sparse) ?? true;
+    return createEntity(context, entity, { ...fields, Id: id, SyncToken: syncToken, sparse });
+}
+/** Void or delete an entity with `POST /{entity}?operation=...`. */
+export async function operateOnEntity(context, entity, operation, input) {
+    const id = requiredInputString(input.id, "id");
+    const syncToken = await resolveSyncToken(context, entity, input, id);
+    // QuickBooks voids a Payment as a sparse update with `include=void`; other entities use `operation=void`.
+    const voidsPayment = operation === "void" && entity.name === "Payment";
+    const payload = await quickbooksRequest(context, {
+        path: entity.path,
+        method: "POST",
+        query: voidsPayment ? { operation: "update", include: "void" } : { operation },
+        body: voidsPayment ? { Id: id, SyncToken: syncToken, sparse: true } : { Id: id, SyncToken: syncToken },
+    });
+    return requiredResponseRecord(payload[entity.name], `QuickBooks ${entity.name}`);
+}
+const reportParameterNamePattern = /^[A-Za-z_]+$/;
+/** Extra report query parameters, passed through by name. Values are sent as strings. */
+function reportParameters(value) {
+    const parameters = {};
+    for (const [name, entry] of Object.entries(optionalRecord(value) ?? {})) {
+        if (!reportParameterNamePattern.test(name)) {
+            throw providerInputError(`parameters.${name} is not a valid report parameter name`);
+        }
+        parameters[name] = entry === undefined ? undefined : String(entry);
+    }
+    return parameters;
+}
+/** Read a report such as `ProfitAndLoss` with the shared date-range options. */
+export async function readReport(context, reportName, input) {
+    const startDate = optionalString(input.start_date);
+    const endDate = optionalString(input.end_date);
+    if (startDate && endDate && startDate > endDate) {
+        throw providerInputError("start_date must not be after end_date");
+    }
+    return quickbooksRequest(context, {
+        path: `reports/${reportName}`,
+        query: {
+            start_date: startDate,
+            end_date: endDate,
+            accounting_method: optionalString(input.accounting_method),
+            summarize_column_by: optionalString(input.summarize_column_by),
+            ...reportParameters(input.parameters),
+        },
+    });
+}
+/**
+ * Read the `environment` credential or client-config value. A blank value means
+ * production; anything other than `production` or `sandbox` is rejected so a
+ * typo can never silently send live credentials to the wrong host.
+ */
+export function resolveQuickbooksEnvironment(value, createError = providerInputError) {
+    const environment = optionalString(value)?.toLowerCase() ?? "production";
+    if (environment === "production" || environment === "sandbox") {
+        return environment;
+    }
+    throw createError("environment must be production or sandbox");
+}
+const columnPattern = /^[A-Za-z][A-Za-z0-9.]*$/;
+const selectPattern = /^\s*select\s/i;
+const pagingClausePattern = /\b(?:startposition|maxresults)\b/i;
+/**
+ * Quote a value as a QuickBooks query string literal. QuickBooks escapes a
+ * single quote with a backslash, so a backslash has to be escaped as well or a
+ * trailing one would swallow the closing quote.
+ */
+export function quoteQuickbooksString(value) {
+    return `'${value.replaceAll("\\", "\\\\").replaceAll("'", "\\'")}'`;
+}
+/** `column = 'value'`; `column` is always a provider constant, never caller input. */
+export function equalsCondition(column, value) {
+    return `${column} = ${quoteQuickbooksString(value)}`;
+}
+/** `column LIKE '%value%'`. */
+export function containsCondition(column, value) {
+    return `${column} LIKE ${quoteQuickbooksString(`%${value}%`)}`;
+}
+/** `column <op> 'value'` for ordered comparisons such as `TxnDate >= '2026-01-01'`. */
+export function compareCondition(column, operator, value) {
+    return `${column} ${operator} ${quoteQuickbooksString(value)}`;
+}
+/** Condition for the `status` list filter; QuickBooks hides inactive rows unless asked for them. */
+export function statusCondition(status) {
+    switch (status) {
+        case "inactive":
+            return "Active = false";
+        case "all":
+            return "Active IN (true, false)";
+        default:
+            return "Active = true";
+    }
+}
+/** Read and bound `start_position` and `max_results`. */
+export function readPaging(input) {
+    const startPosition = optionalInteger(input.start_position) ?? 1;
+    const maxResults = optionalInteger(input.max_results) ?? quickbooksDefaultMaxResults;
+    if (startPosition < 1) {
+        throw providerInputError("start_position must be at least 1");
+    }
+    if (maxResults < 1 || maxResults > quickbooksMaxResults) {
+        throw providerInputError(`max_results must be between 1 and ${quickbooksMaxResults}`);
+    }
+    return { startPosition, maxResults };
+}
+/** Build a `select *` statement with filters, ordering and paging. */
+export function buildSelectStatement(select) {
+    const parts = [`select * from ${select.entity}`];
+    if (select.conditions.length > 0) {
+        parts.push(`where ${select.conditions.join(" and ")}`);
+    }
+    if (select.orderBy) {
+        if (!columnPattern.test(select.orderBy)) {
+            throw providerInputError("order_by is not a valid column name");
+        }
+        parts.push(`order by ${select.orderBy}${select.descending ? " desc" : ""}`);
+    }
+    parts.push(`startposition ${select.startPosition}`, `maxresults ${select.maxResults}`);
+    return parts.join(" ");
+}
+/** `TxnDate` range conditions for the `txn_date_from` and `txn_date_to` list filters. */
+export function txnDateConditions(input) {
+    const from = optionalString(input.txn_date_from);
+    const to = optionalString(input.txn_date_to);
+    return [
+        ...(from ? [compareCondition("TxnDate", ">=", from)] : []),
+        ...(to ? [compareCondition("TxnDate", "<=", to)] : []),
+    ];
+}
+/** Reject anything but a read-only `select` statement. */
+export function assertReadOnlySelect(statement) {
+    if (!selectPattern.test(statement)) {
+        throw providerInputError("statement must be a read-only query that begins with select");
+    }
+}
+/** Reject anything but a `select` statement without its own paging clauses. */
+export function assertSelectStatement(statement) {
+    assertReadOnlySelect(statement);
+    if (pagingClausePattern.test(statement)) {
+        throw providerInputError("statement must not contain STARTPOSITION or MAXRESULTS; use start_position and max_results");
+    }
+}