@zackbart/connecta 0.34.1 → 0.36.0

package/dist/providers/quickbooks/api.js

@@ -0,0 +1,299 @@
+import { Effect, Schema } from "effect";
+import { StatusFailure } from "../../http/errors.js";
+import { get, post, Summary, vendor } from "../../http/vendor.js";
+import { vendorIndex } from "../../http/vendor-index.js";
+import { RecordShape, CompanyShape, ReportShape, object } from "./safety.js";
+import { matches, reportProblem, reportQuery } from "./lib/query.js";
+export const ENTITIES = {
+    customers: "Customer",
+    vendors: "Vendor",
+    accounts: "Account",
+    items: "Item",
+    invoices: "Invoice",
+    bills: "Bill",
+    payments: "Payment",
+    bill_payments: "BillPayment",
+};
+export const REPORTS = ["ProfitAndLoss", "BalanceSheet", "CashFlow", "AgedReceivables", "AgedPayables"];
+const version = { minorversion: Schema.optionalKey(Schema.Literal("75")) };
+const id = { id: Schema.String.check(matches("^[1-9]\\d{0,30}$")) };
+export const companyInfo = get("companyInfo", "/companyinfo/:id", {
+    params: id,
+    query: version,
+    success: Schema.Struct({ CompanyInfo: CompanyShape }),
+}).annotate(Summary, "Get the configured company identity");
+export const queryRecords = get("queryRecords", "/query", {
+    query: { ...version, query: Schema.String },
+    success: Schema.Struct({ QueryResponse: Schema.Unknown }),
+}).annotate(Summary, "Structured accounting searches through search_records only; raw SQL refused");
+export const recordReads = Object.fromEntries(Object.entries(ENTITIES).map(([key, entity]) => [
+    key,
+    get(`get${entity}`, `/${entity.toLowerCase()}/:id`, {
+        params: id,
+        query: version,
+        success: Schema.Struct({ [entity]: RecordShape }),
+    }).annotate(Summary, `Read one ${entity} accounting record`),
+]));
+export const reportReads = Object.fromEntries(REPORTS.map((name) => [
+    name,
+    get(`report${name}`, `/reports/${name}`, {
+        query: { ...version, ...reportQuery(name) },
+        success: ReportShape,
+    }).annotate(Summary, `Read the ${name} financial report`),
+]));
+// Closed named-write bodies. POSTs are indexed for safety, but refused by the hatch.
+export const PublicId = Schema.String.check(matches("^[1-9]\\d{0,30}$"));
+export const SyncToken = Schema.String.check(matches("^(?:0|[1-9]\\d{0,30})$"));
+const Name = Schema.String.check(matches("^\\S(?:[^\\r\\n]{0,498}\\S)?$"));
+export const CustomerNames = { DisplayName: Name, CompanyName: Schema.optionalKey(Name) };
+export const customerWrite = post("writeCustomer", "/customer", {
+    query: { minorversion: Schema.Literal("75"), requestid: Schema.String },
+    payload: Schema.Struct({
+        ...CustomerNames,
+        Id: Schema.optionalKey(PublicId),
+        SyncToken: Schema.optionalKey(SyncToken),
+        sparse: Schema.optionalKey(Schema.Literal(true)),
+    }),
+    success: Schema.Struct({ Customer: RecordShape }),
+}).annotate(Summary, "Create a customer or sparsely update naming fields through named tools only");
+export const invoiceWrite = post("createInvoice", "/invoice", {
+    query: { minorversion: Schema.Literal("75"), requestid: Schema.String },
+    payload: Schema.Struct({
+        CustomerRef: Schema.Struct({ value: PublicId }),
+        CurrencyRef: Schema.Struct({ value: Schema.String }),
+        ExchangeRate: Schema.Number,
+        TxnDate: Schema.String,
+        DueDate: Schema.String,
+        DocNumber: Schema.String,
+        Line: Schema.Array(Schema.Struct({
+            Amount: Schema.Number,
+            DetailType: Schema.Literal("SalesItemLineDetail"),
+            SalesItemLineDetail: Schema.Struct({
+                ItemRef: Schema.Struct({ value: PublicId }),
+                Qty: Schema.Literal(1),
+                UnitPrice: Schema.Number,
+            }),
+        })),
+        EmailStatus: Schema.Literal("NotSet"),
+        AllowIPNPayment: Schema.Literal(false),
+        AllowOnlinePayment: Schema.Literal(false),
+        AllowOnlineCreditCardPayment: Schema.Literal(false),
+        AllowOnlineACHPayment: Schema.Literal(false),
+        AllowOnlinePayPalPayment: Schema.Literal(false),
+        AllowOnlineAffirmPayment: Schema.Literal(false),
+    }),
+    success: Schema.Struct({ Invoice: RecordShape }),
+}).annotate(Summary, "Create a real unsent service invoice through create_invoice only");
+export const QuickBooksApi = vendor("QuickBooks Online", companyInfo, queryRecords, customerWrite, invoiceWrite, ...Object.values(recordReads), ...Object.values(reportReads));
+export const QUICKBOOKS_INDEX = vendorIndex(QuickBooksApi, {
+    prefix: "quickbooks",
+    title: "QuickBooks Online",
+    revision: "v3-minor75",
+});
+export const QUICKBOOKS_VERDICTS = {
+    "GET /companyinfo/{id}": "read",
+    "GET /query": "refuse",
+    "POST /customer": "refuse",
+    "POST /invoice": "refuse",
+    ...Object.fromEntries(Object.values(ENTITIES).map((entity) => [`GET /${entity.toLowerCase()}/{id}`, "read"])),
+    ...Object.fromEntries(REPORTS.map((name) => [`GET /reports/${name}`, "read"])),
+};
+export const QUICKBOOKS_NAMED = {
+    "GET /companyinfo/{id}": "get_company_info",
+    "GET /query": "search_records",
+    ...Object.fromEntries(Object.values(ENTITIES).map((entity) => [`GET /${entity.toLowerCase()}/{id}`, "get_record"])),
+    ...Object.fromEntries(REPORTS.map((name) => [`GET /reports/${name}`, "get_report"])),
+};
+export const apiOrigin = (options) => options.environment === "sandbox" ? "https://sandbox-quickbooks.api.intuit.com" : "https://quickbooks.api.intuit.com";
+export function oauth(options) {
+    return {
+        authorizationEndpoint: "https://appcenter.intuit.com/connect/oauth2",
+        tokenEndpoint: "https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer",
+        revocationEndpoint: "https://developer.api.intuit.com/v2/oauth2/tokens/revoke",
+        revocationRequestFormat: "json",
+        clientId: options.clientId,
+        clientSecret: options.clientSecret,
+        scope: "com.intuit.quickbooks.accounting",
+        pkce: false,
+        expectedCallbackParameters: { realmId: options.realmId },
+        apiOrigins: [apiOrigin(options)],
+    };
+}
+export function quickbooksBinding({ connection, options, }) {
+    return {
+        review: "Fixed company/environment, indexed GETs only, minorversion 75; query SQL is reserved for the named structured builder.",
+        cursorScope: { realmId: options.realmId, environment: options.environment },
+        refuse: (call) => {
+            // The indexed refusal owns /query, including its discovery/details reason.
+            if (call.op.path === "/query")
+                return undefined;
+            if (call.op.path === "/companyinfo/{id}" && call.path !== `/companyinfo/${options.realmId}`)
+                return "Company info must name this connector's configured realmId.";
+            if (!/^\/(?:[a-z]+\/[1-9]\d{0,30}|reports\/[A-Za-z]+)$/.test(call.path))
+                return "Use a canonical reviewed QuickBooks path.";
+            if (call.op.path.startsWith("/reports/"))
+                return reportProblem(call.path.split("/").at(-1), call.query);
+            if (Object.keys(call.query).some((key) => key !== "minorversion"))
+                return "This record read accepts no extra query parameters.";
+            return undefined;
+        },
+        send: (call, settings) => connection.sendPath({
+            method: "GET",
+            path: call.path,
+            template: call.op.path,
+            query: Object.entries({ ...call.query, minorversion: "75" }).map(([key, value]) => [
+                key,
+                String(value),
+            ]),
+        }, settings),
+    };
+}
+export const errors = {
+    provider: "QuickBooks Online",
+    meanings: {
+        unknownId: "connector_call_failed",
+        provesAbsence: false,
+        conflicts: ["Intuit fault 5010 for a stale SyncToken", "Intuit fault 6240 for a duplicate DisplayName"],
+    },
+    facts: (body) => {
+        const rows = object(object(body)["Fault"])["Error"];
+        const code = Array.isArray(rows) ? object(rows[0])["code"] : undefined;
+        return { faultCode: typeof code === "string" && ["610", "5010", "6240"].includes(code) ? code : "" };
+    },
+    factVocabulary: { faultCode: ["610", "5010", "6240"] },
+    detail: ({ status }) => `QuickBooks Online returned HTTP ${status}.`,
+    unreadable: "QuickBooks Online returned a successful response that is not JSON.",
+    numericFacts: {
+        retryAfterMs: { header: "retry-after", format: "retry-after", review: "Standard HTTP Retry-After delay." },
+    },
+    statuses: {
+        200: () => ({
+            code: "connector_call_failed",
+            retryable: false,
+            words: (detail) => `${detail} The accounting response was incomplete or invalid.`,
+        }),
+        400: ({ facts }) => ({
+            code: facts["faultCode"] === "610"
+                ? "connector_call_failed"
+                : ["5010", "6240"].includes(String(facts["faultCode"]))
+                    ? "conflict"
+                    : "invalid_args",
+            words: (detail) => facts["faultCode"] === "5010"
+                ? `${detail} The observed SyncToken is stale; reread and review the change.`
+                : facts["faultCode"] === "6240"
+                    ? `${detail} The DisplayName is already in use by a customer, vendor or employee.`
+                    : detail,
+            retryable: false,
+        }),
+        401: () => ({ code: "auth_required" }),
+        403: () => ({ code: "provider_permission_denied", retryable: false }),
+        404: () => ({ code: "connector_call_failed", retryable: false }),
+        429: ({ retryAfterMs }) => ({
+            code: "rate_limited",
+            retryAfterMs: Math.max(60_000, retryAfterMs ?? 0),
+            words: (detail) => `${detail} Intuit documents a wait of at least 60 seconds after throttling.`,
+        }),
+    },
+};
+/** Missing data is a failure, never a fabricated record/report/search or confirmed write. */
+const container = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const cells = (value) => Array.isArray(value) && value.every((cell) => container(cell) && typeof cell["value"] === "string");
+function reportRows(value, depth = 0) {
+    if (!container(value) || depth > 32)
+        return false;
+    if (value["Row"] === undefined)
+        return Object.keys(value).length === 0;
+    return (Array.isArray(value["Row"]) &&
+        value["Row"].every((row) => {
+            if (!container(row))
+                return false;
+            if (!["Header", "Summary", "ColData", "Rows"].some((key) => row[key] !== undefined))
+                return false;
+            for (const key of ["Header", "Summary"]) {
+                if (row[key] !== undefined && (!container(row[key]) || !cells(row[key]["ColData"])))
+                    return false;
+            }
+            return ((row["ColData"] === undefined || cells(row["ColData"])) &&
+                (row["Rows"] === undefined || reportRows(row["Rows"], depth + 1)));
+        }));
+}
+export const result = (body, answer) => {
+    const root = object(body);
+    const path = answer.operation.template;
+    let valid;
+    if (answer.operation.method === "POST") {
+        const key = path === "/customer" ? "Customer" : path === "/invoice" ? "Invoice" : undefined;
+        const record = key === undefined ? {} : object(root[key]);
+        const numericId = (value) => typeof value === "string" && /^[1-9]\d{0,30}$/.test(value);
+        const amount = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0;
+        valid =
+            key !== undefined &&
+                numericId(record["Id"]) &&
+                typeof record["SyncToken"] === "string" &&
+                /^(?:0|[1-9]\d{0,30})$/.test(record["SyncToken"]) &&
+                (key === "Customer"
+                    ? typeof record["DisplayName"] === "string" && record["DisplayName"].trim() !== ""
+                    : (record["EmailStatus"] === undefined || record["EmailStatus"] === "NotSet") &&
+                        [
+                            "AllowIPNPayment",
+                            "AllowOnlinePayment",
+                            "AllowOnlineCreditCardPayment",
+                            "AllowOnlineACHPayment",
+                            "AllowOnlinePayPalPayment",
+                            "AllowOnlineAffirmPayment",
+                        ].every((key) => record[key] === undefined || record[key] === false) &&
+                        amount(record["TotalAmt"]) &&
+                        ["Balance", "HomeTotalAmt", "HomeBalance"].every((key) => record[key] === undefined || amount(record[key])) &&
+                        (record["ExchangeRate"] === undefined ||
+                            (typeof record["ExchangeRate"] === "number" &&
+                                Number.isFinite(record["ExchangeRate"]) &&
+                                record["ExchangeRate"] > 0)) &&
+                        typeof record["DocNumber"] === "string" &&
+                        record["DocNumber"].trim() !== "" &&
+                        numericId(object(record["CustomerRef"])["value"]) &&
+                        typeof object(record["CurrencyRef"])["value"] === "string" &&
+                        /^[A-Z]{3}$/.test(String(object(record["CurrencyRef"])["value"])) &&
+                        Array.isArray(record["Line"]) &&
+                        record["Line"].length > 0 &&
+                        record["Line"].every((line) => container(line) && amount(line["Amount"])) &&
+                        record["Line"].some((line) => object(line)["DetailType"] === "SalesItemLineDetail" &&
+                            numericId(object(object(object(line)["SalesItemLineDetail"])["ItemRef"])["value"])));
+    }
+    else if (path === "/query") {
+        const rows = root["QueryResponse"];
+        valid =
+            container(rows) &&
+                Object.entries(rows).every(([key, value]) => (["startPosition", "maxResults", "totalCount"].includes(key) &&
+                    typeof value === "number" &&
+                    Number.isSafeInteger(value) &&
+                    value >= (key === "startPosition" ? 1 : 0)) ||
+                    (answer.operation.flags?.[key] === true &&
+                        Array.isArray(value) &&
+                        (rows["totalCount"] === undefined ||
+                            (typeof rows["totalCount"] === "number" && rows["totalCount"] >= value.length)) &&
+                        (value.length > 0 ||
+                            ((rows["totalCount"] === undefined || rows["totalCount"] === 0) &&
+                                (rows["maxResults"] === undefined || rows["maxResults"] === 0))) &&
+                        value.every((row) => typeof object(row)["Id"] === "string" && object(row)["Id"] !== ""))) &&
+                (Object.keys(rows).some((key) => answer.operation.flags?.[key] === true) ||
+                    ((rows["totalCount"] === undefined || rows["totalCount"] === 0) &&
+                        (rows["maxResults"] === undefined || rows["maxResults"] === 0)));
+    }
+    else if (path.startsWith("/reports/")) {
+        const columns = object(root["Columns"])["Column"];
+        valid =
+            typeof object(root["Header"])["ReportName"] === "string" &&
+                Array.isArray(columns) &&
+                columns.every((column) => container(column)) &&
+                reportRows(root["Rows"]);
+    }
+    else {
+        const key = path.startsWith("/companyinfo/")
+            ? "CompanyInfo"
+            : Object.values(ENTITIES).find((entity) => path.startsWith(`/${entity.toLowerCase()}/`));
+        valid = key !== undefined && typeof object(root[key])["Id"] === "string";
+    }
+    return valid && root["Fault"] === undefined
+        ? Effect.succeed(body)
+        : Effect.fail(new StatusFailure({ status: answer.status, headers: answer.headers, body, operation: answer.operation }));
+};

package/dist/providers/quickbooks/index.d.ts

@@ -0,0 +1,13 @@
+import type { ProviderOptions } from "../../provider.js";
+/** One fixed QuickBooks Online company, using the deployment's own Intuit app. */
+export interface QuickBooksOptions extends ProviderOptions {
+    realmId: string;
+    environment: "sandbox" | "production";
+    clientId: string;
+    clientSecret: string;
+    /** Default rows per search: 25, at most 100. */
+    defaultPageSize?: number;
+    /** Defaults to true. Explicit false enables the bounded named writes. */
+    readOnly?: boolean;
+}
+export declare const quickbooks: import("../../provider.js").ProviderFactory<QuickBooksOptions>;

package/dist/providers/quickbooks/index.js

@@ -0,0 +1,93 @@
+import { keys, optionsOf } from "../../config-schema.js";
+import { PROVIDER_COMMON } from "../../connectors/option-shapes.js";
+import { defineApiProvider } from "../../http/provider.js";
+import { bearer } from "../../http/oauth.js";
+import { apiOrigin, companyInfo, errors, oauth, QuickBooksApi, QUICKBOOKS_INDEX, QUICKBOOKS_NAMED, QUICKBOOKS_VERDICTS, quickbooksBinding, result, } from "./api.js";
+import { quickbooksSafety } from "./safety.js";
+import { quickbooksTools } from "./tools.js";
+import { skill } from "./skill.generated.js";
+const OPTIONS = optionsOf()({
+    ...PROVIDER_COMMON,
+    ...keys("realmId", "environment", "clientId", "clientSecret", "defaultPageSize"),
+});
+function baseUrl(options) {
+    if (typeof options.realmId !== "string" ||
+        options.realmId.trim() !== options.realmId ||
+        !/^[1-9]\d{0,30}$/.test(options.realmId))
+        throw new Error("quickbooks() realmId must be the fixed numeric company id.");
+    if (options.environment !== "sandbox" && options.environment !== "production")
+        throw new Error('quickbooks() requires environment: "sandbox" or "production".');
+    for (const key of ["clientId", "clientSecret"]) {
+        if (typeof options[key] !== "string" || !options[key].trim() || /[\r\n]/.test(options[key]))
+            throw new Error(`quickbooks() requires ${key}.`);
+    }
+    return `${apiOrigin(options)}/v3/company/${options.realmId}`;
+}
+export const quickbooks = defineApiProvider({
+    name: "quickbooks",
+    title: "QuickBooks Online",
+    readme: "QuickBooks Online",
+    bundle: {
+        baselineGzip: 357549,
+        note: "./providers/quickbooks initial read surface measures 357,549 B standalone gzip-9 before recording these bundle facts (Node 26.12.0, neutral workerd/worker/browser/import conditions, esbuild). Shared Effect is paid once per deployment; this provider baseline is reported, not capped (#1079).",
+    },
+    skill,
+    options: OPTIONS,
+    displayTitle: (options) => `QuickBooks Online (${options.environment})`,
+    description: (options) => `QuickBooks Online accounting, company ${options.realmId} (${options.environment}): ${options.purpose}`,
+    vendor: QuickBooksApi,
+    baseUrl,
+    maxResponseBytes: 4 * 1024 * 1024,
+    headers: { Accept: "application/json" },
+    pageSize: { default: 25, max: 100 },
+    idempotencyKey: false,
+    authenticate: bearer,
+    oauth,
+    errors,
+    result,
+    safety: quickbooksSafety,
+    probe: {
+        operation: companyInfo,
+        request: (options) => ({
+            params: { id: options.realmId },
+            query: { minorversion: "75" },
+        }),
+        describe: () => "Connected to the configured QuickBooks Online company.",
+    },
+    guide: (options) => ({
+        context: [
+            `Company ${options.realmId}, ${options.environment}: ${options.purpose}`,
+            options.readOnly === false
+                ? "Bounded named writes are enabled. The API hatch remains read-only."
+                : "This connection is read-only. Set readOnly: false in deployment code to enable bounded named writes.",
+            "Contact details, bank/card/tax identifiers, credentials and private links are withheld on every read.",
+        ],
+        summary: "QuickBooks Online accounting reads and explicitly enabled customer/service-invoice writes.",
+        required: true,
+    }),
+    hatch: {
+        name: "quickbooks",
+        title: "QuickBooks Online",
+        index: QUICKBOOKS_INDEX,
+        verdicts: QUICKBOOKS_VERDICTS,
+        named: QUICKBOOKS_NAMED,
+        pathExample: "/invoice/42",
+        binding: quickbooksBinding,
+        notes: () => ({
+            read: "Only reviewed record, company and report reads. Use search_records for bounded structured queries; raw SQL is refused.",
+        }),
+    },
+    // The existing common option defaults writable elsewhere. This provider requires explicit opt-in.
+    tagConnector: (connector, options) => {
+        Object.defineProperty(connector, "readOnly", {
+            value: options.readOnly !== false,
+            enumerable: true,
+            configurable: true,
+        });
+    },
+    transformGuide: (guide) => ({
+        ...guide,
+        content: guide.content.replace("Writes take no idempotency key.", "Every named write requires requestId, sent as Intuit's requestid query parameter; no idempotencyKey header argument is accepted."),
+    }),
+    tools: quickbooksTools,
+});

package/dist/providers/quickbooks/lib/query.js

@@ -0,0 +1,118 @@
+import { Schema } from "effect";
+import { ConnectorCallError } from "../../../errors.js";
+import { isMaxChars } from "../../../http/json-schema.js";
+export const matches = (pattern) => Schema.makeFilter((value) => new RegExp(pattern).test(value), { toJsonSchema: () => ({ pattern }) });
+const DateOnly = Schema.String.check(matches("^\\d{4}-\\d{2}-\\d{2}$"));
+export const REPORT_QUERY = {
+    start_date: Schema.optionalKey(DateOnly.annotate({ description: "First date, YYYY-MM-DD; P&L and Cash Flow only." })),
+    end_date: Schema.optionalKey(DateOnly.annotate({ description: "Last date or statement date, YYYY-MM-DD." })),
+    accounting_method: Schema.optionalKey(Schema.Literals(["Cash", "Accrual"]).annotate({ description: "Accounting basis; P&L and Balance Sheet only." })),
+};
+export function reportQuery(report) {
+    if (report === "AgedReceivables" || report === "AgedPayables")
+        return {
+            report_date: Schema.optionalKey(DateOnly.annotate({ description: "As-of date, YYYY-MM-DD." })),
+            aging_method: Schema.optionalKey(Schema.Literal("Report_Date").annotate({ description: "Age relative to report_date." })),
+        };
+    return {
+        ...(["ProfitAndLoss", "CashFlow"].includes(report) ? { start_date: REPORT_QUERY.start_date } : {}),
+        end_date: REPORT_QUERY.end_date,
+        ...(["ProfitAndLoss", "BalanceSheet"].includes(report)
+            ? { accounting_method: REPORT_QUERY.accounting_method }
+            : {}),
+    };
+}
+/** Named reports use one end_date; aging translates it to the vendor's snapshot date. */
+export function reportParameters(report, query) {
+    if ((report === "AgedReceivables" || report === "AgedPayables") && query["end_date"] !== undefined) {
+        const { end_date, ...rest } = query;
+        return { ...rest, report_date: end_date, aging_method: "Report_Date" };
+    }
+    return query;
+}
+export function reportProblem(report, query) {
+    const allowed = new Set(["minorversion", ...Object.keys(reportQuery(report))]);
+    if (Object.keys(query).some((key) => !allowed.has(key)))
+        return "This report does not support a supplied parameter; inspect get_report or quickbooks_api_details.";
+    for (const key of ["start_date", "end_date", "report_date"]) {
+        const value = query[key];
+        if (value !== undefined &&
+            (typeof value !== "string" ||
+                !/^\d{4}-\d{2}-\d{2}$/.test(value) ||
+                !Number.isFinite(Date.parse(value)) ||
+                new Date(value).toISOString().slice(0, 10) !== value))
+            return `${key} must be a real YYYY-MM-DD date.`;
+    }
+    if (query["start_date"] && query["end_date"] && String(query["start_date"]) > String(query["end_date"]))
+        return "start_date must not follow end_date.";
+    if (query["aging_method"] !== undefined && query["report_date"] === undefined)
+        return "aging_method requires report_date.";
+    return undefined;
+}
+export const FILTER_FIELDS = [
+    "Id",
+    "DisplayName",
+    "Name",
+    "Active",
+    "MetaData.LastUpdatedTime",
+    "TxnDate",
+    "DueDate",
+    "DocNumber",
+    "CustomerRef",
+    "VendorRef",
+    "Balance",
+];
+export const Filters = Schema.Array(Schema.Struct({
+    field: Schema.Literals(FILTER_FIELDS).annotate({
+        description: "Reviewed filter field, subject to the chosen record type.",
+    }),
+    operator: Schema.Literals(["eq", "gt", "gte", "lt", "lte"]).annotate({
+        description: "Equality or an ordered date/amount comparison.",
+    }),
+    value: Schema.Union([Schema.String.check(isMaxChars(200)), Schema.Boolean, Schema.Number.check(Schema.isFinite())]),
+})).check(Schema.isMaxLength(8));
+const operations = { eq: "=", gt: ">", gte: ">=", lt: "<", lte: "<=" };
+/** One SQL builder. No agent text is ever used as a clause, identifier or paging anchor. */
+export function buildSearch(entity, filters, start, size) {
+    const master = ["Customer", "Vendor", "Account", "Item"].includes(entity);
+    const fields = new Set([
+        "Id",
+        "MetaData.LastUpdatedTime",
+        ...(master
+            ? ["Active", entity === "Customer" || entity === "Vendor" ? "DisplayName" : "Name"]
+            : [
+                "TxnDate",
+                ...(entity === "Payment" ? [] : ["DocNumber"]),
+                ...(entity === "Invoice" || entity === "Bill" ? ["DueDate", "Balance"] : []),
+                ...(entity === "Invoice" || entity === "Payment" ? ["CustomerRef"] : ["VendorRef"]),
+            ]),
+    ]);
+    if (!Number.isSafeInteger(start) || start < 1 || !Number.isSafeInteger(size) || size < 1 || size > 101)
+        throw new ConnectorCallError("invalid_args", "Invalid QuickBooks search page.");
+    const clauses = filters.map(({ field, operator, value }) => {
+        if (!fields.has(field))
+            throw new ConnectorCallError("invalid_args", `${field} is not a reviewed filter for ${entity}.`);
+        const range = ["TxnDate", "DueDate", "MetaData.LastUpdatedTime", "Balance"].includes(field);
+        if (!range && operator !== "eq")
+            throw new ConnectorCallError("invalid_args", `${field} supports only eq.`);
+        if (field === "Active"
+            ? typeof value !== "boolean"
+            : field === "Balance"
+                ? typeof value !== "number"
+                : typeof value !== "string" ||
+                    [...value].some((character) => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127))
+            throw new ConnectorCallError("invalid_args", `Invalid value type for ${field}.`);
+        if (["Id", "CustomerRef", "VendorRef"].includes(field) && !/^[1-9]\d{0,30}$/.test(String(value)))
+            throw new ConnectorCallError("invalid_args", `${field} requires a numeric record id.`);
+        if (["TxnDate", "DueDate"].includes(field) && reportProblem("ProfitAndLoss", { end_date: value }))
+            throw new ConnectorCallError("invalid_args", `${field} requires a real YYYY-MM-DD date.`);
+        if (field === "MetaData.LastUpdatedTime" &&
+            (typeof value !== "string" ||
+                !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(value) ||
+                !Number.isFinite(Date.parse(value))))
+            throw new ConnectorCallError("invalid_args", "LastUpdatedTime requires an ISO timestamp with timezone.");
+        const literal = typeof value === "string" ? `'${value.replaceAll("\\", "\\\\").replaceAll("'", "\\'")}'` : String(value);
+        return `${field} ${operations[operator]} ${literal}`;
+    });
+    return `SELECT * FROM ${entity}${clauses.length ? ` WHERE ${clauses.join(" AND ")}` : ""} STARTPOSITION ${start} MAXRESULTS ${size}`;
+}