@zackbart/connecta 0.35.0 → 0.36.1

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;
+}
+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}`;
+}

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

@@ -0,0 +1,168 @@
+import { Effect, Schema } from "effect";
+import { ConnectorCallError } from "../../../errors.js";
+import { Refusal, StatusFailure } from "../../../http/errors.js";
+import { Budget } from "../../../http/services.js";
+import { write } from "../../../http/tools.js";
+import { companyInfo, CustomerNames, customerWrite, invoiceWrite, PublicId, recordReads, SyncToken } from "../api.js";
+import { namedRecord, NamedRecordShape, object } from "../safety.js";
+import { matches, reportProblem } from "./query.js";
+const RequestId = Schema.String.check(matches("^[A-Za-z0-9][A-Za-z0-9_-]{0,49}$")).annotate({
+    description: "Stable identifier for this exact intent, unique across all requests in this company; at most 50 ASCII letters, digits, underscores or hyphens. Never reuse for changed content.",
+});
+const DateOnly = Schema.String.check(matches("^\\d{4}-\\d{2}-\\d{2}$"));
+// Decimal strings avoid binary arithmetic and caller-side cents conversion. Conversion only encodes a JSON number.
+const Amount = Schema.String.check(matches("^(?:0|[1-9]\\d{0,8})\\.\\d{2}$")).annotate({
+    description: "Positive decimal currency units with exactly two fractional digits, at most 999999999.99; never integer cents. One service unit per line.",
+});
+const InvoiceInput = Schema.Struct({
+    requestId: RequestId,
+    customerId: PublicId.annotate({ description: "Caller-observed active Customer Id in this company." }),
+    currency: Schema.Literal("USD").annotate({
+        description: "Caller-observed customer currency, restricted to USD for this initial two-decimal write surface. Vendor computes taxes and totals.",
+    }),
+    exchangeRate: Schema.String.check(matches("^(?:0|[1-9]\\d{0,5})(?:\\.\\d{1,6})?$")).annotate({
+        description: "Explicit positive home-currency units per transaction-currency unit, at most six decimal places. Use 1 for home currency; no rate is fetched or defaulted.",
+    }),
+    txnDate: DateOnly.annotate({ description: "Explicit accounting date, YYYY-MM-DD." }),
+    dueDate: DateOnly.annotate({ description: "Explicit due date, YYYY-MM-DD, on or after txnDate." }),
+    docNumber: Schema.String.check(matches("^[A-Za-z0-9][A-Za-z0-9_-]{0,20}$")).annotate({
+        description: "Explicit reconciliation label, at most 21 characters; not AUTO_GENERATE. Labels may repeat, so reconcile customer, currency and amounts too.",
+    }),
+    lines: Schema.Array(Schema.Struct({
+        itemId: PublicId.annotate({
+            description: "Caller-observed active Service item Id; inventory and other item types are refused.",
+        }),
+        amount: Amount,
+    })).check(Schema.isMinLength(1), Schema.isMaxLength(20)),
+});
+const refuse = (message) => Effect.fail(new Refusal({ error: new ConnectorCallError("invalid_args", message) }));
+const version = { minorversion: "75" };
+const charge = Effect.flatMap(Budget, (budget) => budget.charge).pipe(Effect.catch((error) => error instanceof ConnectorCallError ? Effect.fail(new Refusal({ error })) : Effect.die(error)));
+/** Totals and tax are vendor-computed; the authored references, dates and service prices must agree. */
+function matchesInvoice(record, args) {
+    const lines = Array.isArray(record["Line"]) ? record["Line"] : [];
+    const services = lines.filter((line) => object(line)["DetailType"] === "SalesItemLineDetail");
+    const expected = args.lines
+        .map((line) => JSON.stringify([line.itemId, Number(line.amount), 1, Number(line.amount)]))
+        .sort();
+    const actual = services
+        .map((line) => {
+        const row = object(line), detail = object(row["SalesItemLineDetail"]);
+        return JSON.stringify([object(detail["ItemRef"])["value"], row["Amount"], detail["Qty"], detail["UnitPrice"]]);
+    })
+        .sort();
+    return (object(record["CustomerRef"])["value"] === args.customerId &&
+        object(record["CurrencyRef"])["value"] === args.currency &&
+        record["DocNumber"] === args.docNumber &&
+        record["TxnDate"] === args.txnDate &&
+        record["DueDate"] === args.dueDate &&
+        (record["ExchangeRate"] === Number(args.exchangeRate) ||
+            (record["ExchangeRate"] === undefined && Number(args.exchangeRate) === 1)) &&
+        lines.every((line) => ["SalesItemLineDetail", "SubTotalLineDetail"].includes(String(object(line)["DetailType"]))) &&
+        JSON.stringify(actual) === JSON.stringify(expected));
+}
+export function quickbooksWrites(connection, realmId) {
+    return [
+        write(connection, {
+            name: "create_customer",
+            description: "Create a customer once with a DisplayName and optional CompanyName. No contact, tax, bank or payment fields. Reconcile an unknown outcome by exact DisplayName before another intent.",
+            destructive: true,
+            idempotent: false,
+            input: Schema.Struct({ requestId: RequestId, ...CustomerNames }),
+            output: NamedRecordShape,
+            run: ({ requestId, ...body }) => connection
+                .send(customerWrite, { query: { ...version, requestid: requestId }, payload: body })
+                .pipe(Effect.map(({ data }) => namedRecord(object(data)["Customer"]))),
+        }),
+        write(connection, {
+            name: "update_customer",
+            description: "Sparsely update only DisplayName and optional CompanyName using caller-observed Id and SyncToken. A stale version fails; no version fetch or overwrite follows. Omitted CompanyName is unchanged.",
+            destructive: true,
+            idempotent: false,
+            input: Schema.Struct({ requestId: RequestId, Id: PublicId, SyncToken, ...CustomerNames }),
+            output: NamedRecordShape,
+            run: ({ requestId, ...body }) => connection
+                .send(customerWrite, { query: { ...version, requestid: requestId }, payload: { ...body, sparse: true } })
+                .pipe(Effect.map(({ data }) => namedRecord(object(data)["Customer"]))),
+        }),
+        write(connection, {
+            name: "create_invoice",
+            destructive: true,
+            idempotent: false,
+            description: "Create a real US-company USD accounting invoice, never a draft, once after checking company, active customer/currency and Service items. Dates, DocNumber, exchange rate and one-unit line prices are explicit. EmailStatus is fixed NotSet and online payment flags are false; no email/send operation. Vendor computes taxes/totals. Reconcile unknown outcomes through reads; never blindly create again.",
+            input: InvoiceInput,
+            output: NamedRecordShape,
+            writeSteps: {
+                company: "once",
+                customer: "once",
+                items: {
+                    maxItems: 20,
+                    items: (args) => [...new Set(args.lines.map((line) => line.itemId))],
+                    request: (item) => ({ method: "GET", path: `/item/${item}`, template: "/item/:id", query: version }),
+                },
+                write: "once",
+            },
+            run: (args) => Effect.gen(function* () {
+                const problem = reportProblem("ProfitAndLoss", { start_date: args.txnDate, end_date: args.dueDate });
+                if (problem)
+                    return yield* refuse("Invoice dates must be real YYYY-MM-DD dates, with dueDate on or after txnDate.");
+                if (args.docNumber === "AUTO_GENERATE" ||
+                    Number(args.exchangeRate) <= 0 ||
+                    args.lines.some((line) => Number(line.amount) <= 0))
+                    return yield* refuse("Use an explicit DocNumber and positive exchange rate and line amounts.");
+                const company = object(object((yield* connection.send(companyInfo, { params: { id: realmId }, query: version }, { step: "company", effect: "read" })).data)["CompanyInfo"]);
+                if (company["Id"] !== realmId || company["Country"] !== "US")
+                    return yield* refuse("Invoice creation is restricted to US companies, where the reviewed invoice-autosend contract applies.");
+                yield* charge;
+                const customer = object(object((yield* connection.send(recordReads["customers"], { params: { id: args.customerId }, query: version }, { step: "customer", effect: "read" })).data)["Customer"]);
+                if (customer["Id"] !== args.customerId ||
+                    customer["Active"] !== true ||
+                    object(customer["CurrencyRef"])["value"] !== args.currency)
+                    return yield* refuse("The customer must be active and have the supplied currency; reread before creating an invoice.");
+                for (const itemId of new Set(args.lines.map((line) => line.itemId))) {
+                    yield* charge;
+                    const item = object(object((yield* connection.send(recordReads["items"], { params: { id: itemId }, query: version }, { step: "items", item: itemId, effect: "read" })).data)["Item"]);
+                    if (item["Id"] !== itemId || item["Active"] !== true || item["Type"] !== "Service")
+                        return yield* refuse("Every invoice item must be an active Service item; reread before creating an invoice.");
+                }
+                yield* charge;
+                const { data, status } = yield* connection.send(invoiceWrite, {
+                    query: { ...version, requestid: args.requestId },
+                    payload: {
+                        CustomerRef: { value: args.customerId },
+                        CurrencyRef: { value: args.currency },
+                        ExchangeRate: Number(args.exchangeRate),
+                        TxnDate: args.txnDate,
+                        DueDate: args.dueDate,
+                        DocNumber: args.docNumber,
+                        Line: args.lines.map((line) => ({
+                            Amount: Number(line.amount),
+                            DetailType: "SalesItemLineDetail",
+                            SalesItemLineDetail: {
+                                ItemRef: { value: line.itemId },
+                                Qty: 1,
+                                UnitPrice: Number(line.amount),
+                            },
+                        })),
+                        EmailStatus: "NotSet",
+                        AllowIPNPayment: false,
+                        AllowOnlinePayment: false,
+                        AllowOnlineCreditCardPayment: false,
+                        AllowOnlineACHPayment: false,
+                        AllowOnlinePayPalPayment: false,
+                        AllowOnlineAffirmPayment: false,
+                    },
+                });
+                const invoice = object(object(data)["Invoice"]);
+                if (!matchesInvoice(invoice, args))
+                    return yield* Effect.fail(new StatusFailure({
+                        status,
+                        headers: new Headers(),
+                        body: undefined,
+                        operation: { method: "POST", template: "/invoice" },
+                    }));
+                return namedRecord(invoice);
+            }),
+        }),
+    ];
+}

package/dist/providers/quickbooks/safety.js

@@ -0,0 +1,222 @@
+import { Schema } from "effect";
+import { ConnectorCallError } from "../../errors.js";
+import { withholdEmbeddedUrls } from "../_shared/rest/value-safety.js";
+import { QUICKBOOKS_INDEX } from "./api.js";
+const scalars = [
+    "Id",
+    "SyncToken",
+    "DisplayName",
+    "Name",
+    "CompanyName",
+    "Active",
+    "FullyQualifiedName",
+    "AccountType",
+    "AccountSubType",
+    "Classification",
+    "CurrentBalance",
+    "CurrentBalanceWithSubAccounts",
+    "Type",
+    "UnitPrice",
+    "PurchaseCost",
+    "QtyOnHand",
+    "TrackQtyOnHand",
+    "TxnDate",
+    "DueDate",
+    "DocNumber",
+    "TotalAmt",
+    "Balance",
+    "UnappliedAmt",
+    "ExchangeRate",
+    "HomeTotalAmt",
+    "HomeBalance",
+    "Amount",
+    "LineNum",
+    "DetailType",
+    "Qty",
+    "UnitBasedOn",
+    "PercentBased",
+    "DiscountPercent",
+    "DiscountAmt",
+    "TotalTax",
+    "TaxInclusiveAmt",
+    "PayType",
+];
+const references = [
+    "CurrencyRef",
+    "CustomerRef",
+    "VendorRef",
+    "ParentRef",
+    "AccountRef",
+    "IncomeAccountRef",
+    "ExpenseAccountRef",
+    "AssetAccountRef",
+    "APAccountRef",
+    "ARAccountRef",
+    "DepositToAccountRef",
+    "ItemRef",
+    "ClassRef",
+    "DepartmentRef",
+    "SalesTermRef",
+];
+const details = [
+    "SalesItemLineDetail",
+    "AccountBasedExpenseLineDetail",
+    "ItemBasedExpenseLineDetail",
+    "DiscountLineDetail",
+    "SubTotalLineDetail",
+    "GroupLineDetail",
+    "TxnTaxDetail",
+];
+const optional = (names) => Object.fromEntries(names.map((key) => [key, Schema.optionalKey(Schema.Unknown)]));
+export const RecordShape = Schema.Struct({
+    ...optional(scalars),
+    ...optional(references),
+    ...optional(details),
+    MetaData: Schema.optionalKey(Schema.Unknown),
+    Line: Schema.optionalKey(Schema.Unknown),
+    LinkedTxn: Schema.optionalKey(Schema.Unknown),
+});
+export const CompanyShape = Schema.Struct(optional(["Id", "SyncToken", "CompanyName", "LegalName", "Country", "FiscalYearStartMonth", "SupportedLanguages"]));
+const namedKeys = [
+    "Id",
+    "SyncToken",
+    "DisplayName",
+    "Name",
+    "CompanyName",
+    "Active",
+    "AccountType",
+    "CurrentBalance",
+    "UnitPrice",
+    "QtyOnHand",
+    "PayType",
+    "Type",
+    "TxnDate",
+    "DueDate",
+    "DocNumber",
+    "TotalAmt",
+    "Balance",
+    "UnappliedAmt",
+    "CurrencyRef",
+    "ExchangeRate",
+    "CustomerRef",
+    "VendorRef",
+    "MetaData",
+    "Line",
+    "LinkedTxn",
+];
+export const NamedRecordShape = Schema.Struct(optional(namedKeys));
+export const namedRecord = (value) => Object.fromEntries(Object.entries(object(value)).filter(([key]) => namedKeys.includes(key)));
+export const ReportShape = Schema.Struct({
+    Header: Schema.optionalKey(Schema.Unknown),
+    Columns: Schema.optionalKey(Schema.Unknown),
+    Rows: Schema.optionalKey(Schema.Unknown),
+});
+export const object = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
+const cleanText = (text) => withholdEmbeddedUrls(text).replace(/https?:\/\/[^\s<>"']+/gi, "[redacted]");
+const scalar = (value) => typeof value === "string"
+    ? cleanText(value)
+    : (typeof value === "number" && Number.isFinite(value)) || typeof value === "boolean"
+        ? value
+        : undefined;
+function pick(value, keys) {
+    const source = object(value);
+    return Object.fromEntries(keys.flatMap((key) => source[key] === undefined || scalar(source[key]) === undefined ? [] : [[key, scalar(source[key])]]));
+}
+/** Closed accounting projection: unknown fields never become a way around privacy. SyncToken is a version, not a credential. */
+function safeRecord(value) {
+    const source = object(value), out = pick(source, scalars);
+    for (const key of references)
+        if (source[key])
+            out[key] = pick(source[key], ["value", "name", "type"]);
+    if (source["MetaData"])
+        out["MetaData"] = pick(source["MetaData"], ["CreateTime", "LastUpdatedTime"]);
+    for (const key of details)
+        if (source[key])
+            out[key] = safeRecord(source[key]);
+    if (Array.isArray(source["Line"]))
+        out["Line"] = source["Line"].map(safeRecord);
+    if (Array.isArray(source["LinkedTxn"]))
+        out["LinkedTxn"] = source["LinkedTxn"].map((row) => pick(row, ["TxnId", "TxnType", "TxnLineId"]));
+    return out;
+}
+// Report trees retain vendor hierarchy, column metadata and empty strings. No index has a fixed metric meaning.
+function reportTree(value) {
+    if (Array.isArray(value))
+        return value.map(reportTree);
+    if (typeof value !== "object" || value === null)
+        return scalar(value);
+    const keys = new Set([
+        "Header",
+        "Columns",
+        "Column",
+        "Rows",
+        "Row",
+        "Summary",
+        "ColData",
+        "ColTitle",
+        "ColType",
+        "MetaData",
+        "Name",
+        "Value",
+        "Option",
+        "Time",
+        "ReportName",
+        "DateMacro",
+        "ReportBasis",
+        "StartPeriod",
+        "EndPeriod",
+        "SummarizeColumnsBy",
+        "Currency",
+        "value",
+        "id",
+        "type",
+        "group",
+    ]);
+    return Object.fromEntries(Object.entries(value)
+        .filter(([key]) => keys.has(key))
+        .map(([key, entry]) => [key, reportTree(entry)]));
+}
+export function quickbooksSafety(options) {
+    return {
+        reviewed: {
+            resolve: (method, path) => {
+                if (/[%;\\?#]/.test(path) || path.split("/").some((part) => part === "." || part === ".."))
+                    throw new ConnectorCallError("invalid_args", "Use a canonical reviewed QuickBooks path.");
+                const { op } = QUICKBOOKS_INDEX.resolve(method, path);
+                if (op.path === "/companyinfo/{id}" && path !== `/companyinfo/${options.realmId}`)
+                    throw new ConnectorCallError("invalid_args", "The company must match the configured realmId.");
+                return { method: op.method, template: op.path };
+            },
+            withholdsErrors: () => true,
+            redact: (body, operation) => {
+                const root = object(body);
+                if (operation.template.startsWith("/reports/"))
+                    return reportTree(root);
+                if (operation.template.startsWith("/companyinfo/"))
+                    return {
+                        CompanyInfo: pick(root["CompanyInfo"], [
+                            "Id",
+                            "SyncToken",
+                            "CompanyName",
+                            "LegalName",
+                            "Country",
+                            "FiscalYearStartMonth",
+                            "SupportedLanguages",
+                        ]),
+                    };
+                if (operation.template === "/query") {
+                    const query = object(root["QueryResponse"]);
+                    return {
+                        QueryResponse: Object.fromEntries(Object.entries(query)
+                            .filter(([key]) => ["Customer", "Vendor", "Account", "Item", "Invoice", "Bill", "Payment", "BillPayment"].includes(key) && Array.isArray(query[key]))
+                            .map(([key, rows]) => [key, rows.map(safeRecord)])),
+                    };
+                }
+                return Object.fromEntries(Object.entries(root)
+                    .filter(([key]) => ["Customer", "Vendor", "Account", "Item", "Invoice", "Bill", "Payment", "BillPayment"].includes(key))
+                    .map(([key, record]) => [key, safeRecord(record)]));
+            },
+        },
+        sensitiveFields: { names: [], choice: "drop" },
+    };
+}

package/dist/providers/quickbooks/skill.generated.js

@@ -0,0 +1,5 @@
+// Generated by scripts/generate-providers.mjs; do not edit.
+export const skill = {
+    "content": "## Accounting identity and joins\n\nAn Id identifies a record inside this company and record family. DocNumber is\na human label, may repeat, and is not an Id. SyncToken is the public record\nversion used for concurrency control, not an OAuth credential. References carry\nthe target Id in value; invoice CustomerRef joins Customer, bill VendorRef\njoins Vendor, and payment Line.LinkedTxn joins invoices or bills.\n\nAccounting Payment and BillPayment records describe received and paid money;\nreading them does not execute a payment. Desktop, Payments, Payroll, attachments,\nand unreviewed accounting entities are outside this connection.\n\n## Money, time and reports\n\nAmounts use decimal currency units, never integer cents. Preserve CurrencyRef\nand ExchangeRate when combining transactions; never sum unlike currencies.\nTxnDate is the company's accounting date, not a UTC instant. MetaData timestamps\ncarry their own offset. Customer and vendor searches omit inactive records\nunless the Active filter explicitly selects them.\n\nReports are trees with Header, Columns, nested Rows and section summaries.\nRead column types and metadata together with row values; column order and\nsection labels can change. Empty amount strings mean no value, not zero.\nDo not flatten away section identity or add totals to their component rows.\nCheck the returned period, basis, currency and NoReportData option before\ncomparing reports. Aging is an as-of snapshot, rather than a transaction range.\n\nReturn aggregates and the few identifying records the task needs; avoid\ncopying full customer or vendor directories into the conversation.\n\n\n## Named writes and reconciliation\n\nThe connector defaults to read-only. Deployment code must set `readOnly: false`\nto expose named writes; endpoint and pool read-only policies still apply. The\nAPI hatch remains read-only. `create_customer` accepts DisplayName and optional\nCompanyName. `update_customer` requires caller-observed Id and SyncToken and\nchanges only those naming fields with sparse:true. Omitted CompanyName stays\nunchanged. A stale-version conflict never fetches a newer version or overwrites\nit. Read and review the current record before proposing a new update.\nDisplayName must be unique across customers, vendors and employees.\n\n`create_invoice` creates a real accounting transaction, never a draft, for a\nverified US company and a customer using USD. This bounds the no-email claim\nto the reviewed US autosend contract and money to two-decimal USD units. First\nobserve an active customer with its CurrencyRef and active Service item Ids.\nSupply currency USD, a positive explicit exchange rate, accounting and\ndue dates, a reconciliation DocNumber and 1–20 lines. Each line is one service\nunit with an explicit positive amount in decimal currency units, supplied as a\nstring with exactly two fractional digits. No prices, dates or exchange rates\nare defaulted or fetched. Preflight reads verify the fixed company Country is US\nand recheck customer currency and item activity/type; they are not an atomic snapshot. Vendor validation can still\nreject changed references. Taxes and totals are computed by QuickBooks: inspect\nthe returned currency, exchange rate and totals; line sums are not a promise of\nan untaxed total. Locale/company tax requirements may reject this narrow body.\nNo customer/item creation happens implicitly.\nEach additional request charges the call-admission budget before dispatch.\nContradictory returned references, dates, rate or service prices produce an\nunknown outcome; reconcile through reads rather than repeating the write.\n\nInvoice email status is fixed to NotSet; online, IPN, credit-card, ACH, PayPal\nand Affirm payment flags are fixed false. No email field or send operation is\nexposed. Company invoice-autosend opt-in does not supply the documented\nNeedToSend request state. This prevents this creation request from asking Intuit\nto email the invoice, including when the customer has an email on file.\nInvoice updates are unavailable: preserving an existing send-ready state has\nnot been established safe, while resetting it would change payment settings.\nDeletes, voids, email delivery, charges, refunds, other accounting writes and\narbitrary mutations are unavailable.\n\nEvery write requires a caller-generated `requestId`: 1–50 ASCII letters,\ndigits, underscores or hyphens, starting with a letter or digit. Keep it stable\nfor the exact intent and unique across requests/tools for this company. It is\nsent in Intuit's requestid query parameter with minorversion 75, rather than an\nidempotency header. Intuit documents recognizing the same content and ID and\nreturning the original response; no retention duration is established. This\nnever permits automatic replay. A dispatched write is sent once even after\n401, timeout, server failure or an invalid success response.\n\nAfter an unknown customer-create outcome, search exact DisplayName, including\ninactive records when needed, and inspect the match. For an invoice, search\nDocNumber plus CustomerRef and inspect currency, dates, lines and computed\namounts. DocNumber can repeat, so it alone proves nothing. Reconcile and report\nambiguity before considering another create; never generate a fresh requestId\nand blindly repeat a potentially committed intent. Unknown update outcomes\nneed a read of the known Id and version. A requestId is not a lookup endpoint or\na permanent duplicate-prevention guarantee.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `quickbooks_api_details`, `quickbooks_api_search`, `search_records`, pass it as the top-level `cursor`; omit raw paging anchors on continuations. Keep the original method, path, filters, page size, fields and headers. Paged `list_*` and `search_*` reads take `limit` (default 25, at most 100). The last page has no `nextCursor`. If `page.hasMore` is true without a cursor, the data is incomplete and continuation was withheld. When approaching execute_code's per-program call limit, return page.nextCursor before the call that would exceed it and continue in the next program; don't restart.\n- **Results:** `fields` narrows a read's result to the dot paths you name. `truncated` lists the dot paths a result cut for size; the ids that fetch what was cut stay in the result.\n- **Hatch:** `quickbooks_api_search` finds this API's operations and reads no account data, `quickbooks_api_details` shows one operation's contract, and `quickbooks_api_read` calls a reviewed read. An operation without a reviewed verdict is refused. 3 operations are refused by design; use `quickbooks_api_details` with the method and path to inspect the original operation summary and its separate refusal. Use details for refused methods outside the read/write call schemas; those methods remain unavailable.\n- **Writes:** a write is sent once and never retried. When its outcome is unknown, read the target before repeating it. Writes take no idempotency key.\n- **Errors:** codes come from the vendor's statuses and error facts, never its prose. An unknown id, or one these credentials cannot reach, fails as `connector_call_failed`; this API does not tell the two apart. `conflict` means: Intuit fault 5010 for a stale SyncToken; Intuit fault 6240 for a duplicate DisplayName.\n- **Withheld values:** a value withheld for safety reads `\"[redacted]\"`. Writes refuse whole marker values and withheld links; longer prose may mention the marker. Paths and queries refuse any containment.",
+    "instructionsHeading": "Company instructions"
+};