@zackbart/connecta 0.35.0 → 0.36.0

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. */
+export 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"
+};

package/dist/providers/quickbooks/tools.js

@@ -0,0 +1,117 @@
+import { quickbooksWrites } from "./lib/writes.js";
+import { Effect, Schema } from "effect";
+import { ConnectorCallError } from "../../errors.js";
+import { Refusal } from "../../http/errors.js";
+import { get as getTool, list } from "../../http/tools.js";
+import { companyInfo, ENTITIES, queryRecords, REPORTS, recordReads, reportReads } from "./api.js";
+import { CompanyShape, namedRecord, NamedRecordShape, object, ReportShape } from "./safety.js";
+import { buildSearch, Filters, matches, reportParameters, reportProblem, REPORT_QUERY } from "./lib/query.js";
+const Entity = Schema.Literals([
+    "customers",
+    "vendors",
+    "accounts",
+    "items",
+    "invoices",
+    "bills",
+    "payments",
+    "bill_payments",
+]);
+const Id = Schema.String.check(matches("^[1-9]\\d{0,30}$"));
+const query = { minorversion: "75" };
+const checked = (run) => Effect.try({
+    try: run,
+    catch: (error) => new Refusal({
+        error: error instanceof ConnectorCallError
+            ? error
+            : new ConnectorCallError("invalid_args", "Invalid QuickBooks arguments."),
+    }),
+});
+export function quickbooksTools({ connection, pageSize, options, }) {
+    return [
+        ...quickbooksWrites(connection, options.realmId),
+        getTool(connection, {
+            name: "get_company_info",
+            description: "Read the configured company's accounting identity without contact or tax identifiers.",
+            input: Schema.Struct({}),
+            output: CompanyShape,
+            fields: true,
+            run: () => connection
+                .send(companyInfo, { params: { id: options.realmId }, query })
+                .pipe(Effect.map(({ data }) => object(object(data)["CompanyInfo"]))),
+        }),
+        list(connection, {
+            name: "search_records",
+            description: "Search reviewed accounting records using bounded structured filters. Customer/vendor names are exact DisplayName matches; record ids and references join invoices, bills and accounting payments. No raw SQL. Inactive master records need an explicit Active filter.",
+            filters: {
+                entity: Entity.annotate({
+                    description: "Accounting record family; payments are accounting records, not the Payments API.",
+                }),
+                filters: Schema.optionalKey(Filters.annotate({
+                    description: "At most 8 AND filters. Master records: Id, Active, LastUpdatedTime and DisplayName (customers/vendors) or Name (accounts/items). Transactions: Id, LastUpdatedTime, TxnDate and CustomerRef or VendorRef. Invoices/bills/bill payments also DocNumber; invoices/bills also DueDate and Balance.",
+                })),
+            },
+            row: NamedRecordShape,
+            limit: {
+                default: pageSize,
+                max: 100,
+                description: "Rows per page, default 25, at most 100. A bounded extra row detects continuation.",
+            },
+            cursor: "bound",
+            cursorScope: { realmId: options.realmId, environment: options.environment },
+            page: (args, cursor) => Effect.gen(function* () {
+                const entity = ENTITIES[args.entity];
+                const start = cursor === undefined ? 1 : Number(cursor);
+                const sql = yield* checked(() => buildSearch(entity, args.filters ?? [], start, args.limit + 1));
+                const { data } = yield* connection.send(queryRecords, { query: { ...query, query: sql } }, { flags: { [entity]: true } });
+                const rows = object(object(data)["QueryResponse"])[entity];
+                const all = Array.isArray(rows) ? rows : [];
+                const more = all.length > args.limit;
+                return {
+                    rows: all.slice(0, args.limit).map(namedRecord),
+                    page: { hasMore: more, nextCursor: more ? String(start + args.limit) : null },
+                };
+            }),
+        }),
+        getTool(connection, {
+            name: "get_record",
+            description: "Read one reviewed accounting record by Id. SyncToken is its public version identifier; DocNumber is a separate human label. Contact details and payment credentials are withheld.",
+            input: Schema.Struct({
+                entity: Entity,
+                id: Id.annotate({ description: "Record Id from search_records, never DocNumber." }),
+            }),
+            output: NamedRecordShape,
+            fields: true,
+            run: (args) => connection
+                .sendPath({
+                method: "GET",
+                path: `/${ENTITIES[args.entity].toLowerCase()}/${args.id}`,
+                template: recordReads[args.entity].path,
+                query: [["minorversion", "75"]],
+            })
+                .pipe(Effect.map(({ data }) => namedRecord(object(data)[ENTITIES[args.entity]]))),
+        }),
+        getTool(connection, {
+            name: "get_report",
+            description: "Read Profit & Loss, Balance Sheet, Cash Flow or AR/AP aging summary. Preserve Header, Columns and nested Rows; empty amount strings mean no value, never zero. P&L/CashFlow support start_date; P&L/BalanceSheet support accounting_method. All accept end_date (aging as-of date). Reports retain vendor currency; no currency conversion.",
+            input: Schema.Struct({ report: Schema.Literals(REPORTS), ...REPORT_QUERY }),
+            output: ReportShape,
+            fields: true,
+            run: (args) => Effect.gen(function* () {
+                const { report, ...raw } = args;
+                const parameters = reportParameters(report, Object.fromEntries(Object.entries(raw).filter(([, value]) => value !== undefined)));
+                yield* checked(() => {
+                    const problem = reportProblem(report, parameters);
+                    if (problem)
+                        throw new ConnectorCallError("invalid_args", problem);
+                });
+                const { data } = yield* connection.sendPath({
+                    method: "GET",
+                    path: `/reports/${report}`,
+                    template: reportReads[report].path,
+                    query: Object.entries({ ...parameters, minorversion: "75" }),
+                });
+                return object(data);
+            }),
+        }),
+    ];
+}

package/dist/providers/sheets/tools.js

@@ -5,7 +5,6 @@ import { Refusal } from "../../http/errors.js";
 import { googleClient, googleFailureMessage, googleOutcomeOf } from "../_shared/google/kit.js";
 import { clampText, jsonBytes, RESULT_BUDGET_BYTES } from "../_shared/google/result-size.js";
 import { encodeForAgent, redactBeforeCut } from "../../sent-secrets.js";
-import { SHEETS } from "./api.js";
 import { read, write } from "../../http/tools.js";
 import { boundCursor } from "../../http/paging.js";
 import { fieldsInput, fieldsProblem, selectFields } from "../../http/fields.js";
@@ -336,7 +335,7 @@ const SPREADSHEET_FIELDS = [
 ].join(",");
 // --- Tools ------------------------------------------------------------------------
 export function sheetsTools({ connection }) {
-    const client = googleClient(connection, SHEETS.provider, { standard: true, index: sheetsIndex });
+    const client = googleClient(connection, sheetsIndex);
     const readOnly = { readOnlyHint: true };
     // Additive: nothing that existed is lost. Writes require a writable
     // endpoint: call_destructive_tool or a program. The host controls approval.

package/dist/providers/slides/tools.js

@@ -5,7 +5,7 @@ import { RESULT_BUDGET_BYTES, clampRedactedText, clampText, jsonBytes } from "..
 import { googleClient, googleOutcomeOf, googleFailureMessage } from "../_shared/google/kit.js";
 import { encodeForAgent, redactBeforeCut, redactSentSecrets } from "../../sent-secrets.js";
 import { REQUEST_KINDS, COMMENT_KINDS, COMMENTS_UNSAVED } from "./lib/requests.js";
-import { SLIDES, SLIDES_INDEX } from "./api.js";
+import { SLIDES_INDEX } from "./api.js";
 import * as contracts from "./lib/schemas.js";
 import { read, write } from "../../http/tools.js";
 import { Operation } from "../../runtime/call.js";
@@ -1228,7 +1228,7 @@ function postToThread(connection, client, ctx, tool, args, post) {
     });
 }
 export function slidesTools({ connection }) {
-    const client = googleClient(connection, SLIDES.provider, { standard: true, index: SLIDES_INDEX });
+    const client = googleClient(connection, SLIDES_INDEX);
     const readOnly = { readOnlyHint: true };
     const presentationPath = (id) => `/presentations/${encodeURIComponent(id)}`;
     const nextPage = (cursor) => cursor === null ? { hasMore: false } : { hasMore: true, nextCursor: cursor };

package/dist/providers/vercel/index.js

@@ -1,7 +1,6 @@
 import { keys, optionsOf, variants } from "../../config-schema.js";
 import { defineApiProvider } from "../../http/provider.js";
 import { CALL_ADMISSION } from "../../provider.js";
-import { removedHostedMcp } from "../_shared/rest/dispatch.js";
 import { authenticate, MAX_RESPONSE_BYTES, READ_CAP_MS, probe, result, safety, vercelErrors, VercelApi, usageGuide, transformGuide, VERCEL_VERDICTS, VERCEL_PAGES, vercelBinding, vercelIndex, } from "./api.js";
 import { VERCEL_API_BASE_URL } from "./lib/config.js";
 import { pinOptions, PIN_WRITE_STEPS } from "./lib/pin.js";
@@ -38,7 +37,7 @@ export const vercel = defineApiProvider({
     vendor: VercelApi,
     baseUrl: (options) => {
         if (options.auth.type !== "token")
-            removedHostedMcp();
+            throw new Error("remoteMcp() with ConnectaConfig.classification for hosted MCP connections; use a distinct id beside the API connector.");
         pinOptions(options);
         return options.baseUrl ?? VERCEL_API_BASE_URL;
     },

package/dist/routes/oauth.js

@@ -217,6 +217,9 @@ async function finishOAuthCallback(context) {
         if (["state", "iss", "code", "error"].some((name) => url.searchParams.getAll(name).length > 1))
             return refused();
         try {
+            if (connector.verifyCallbackParameters &&
+                !(await connector.verifyCallbackParameters(url.searchParams, connectorContext)))
+                return refused();
             const issuer = url.searchParams.get("iss");
             if (connector.verifyCallbackIssuer) {
                 if (!(await connector.verifyCallbackIssuer(issuer, connectorContext)))

package/dist/runtime/call.js

@@ -292,9 +292,6 @@ export function deriveView(view, overrides) {
     views.set(derived, entry);
     return derived;
 }
-export function viewCaller(view) {
-    return serviceFor(view, Caller);
-}
 export function viewLease(view) {
     return views.get(view)?.call;
 }
@@ -337,7 +334,6 @@ export function contextView(lease, operation) {
         lease.close();
     return view;
 }
-export const callView = (operation, lease) => contextView(lease, operation);
 export function chargeView(view) {
     const budget = recordedService(view, Budget);
     return budget ? runEdge(budget.charge) : Promise.reject(ended());

package/dist/skills.js

@@ -32,7 +32,6 @@ export function endpointInstructions(description, native) {
 export function nativeInstructions(executeCode) {
     return `Each tool here is one operation; annotations classify reads/writes. Call known tools directly; ${executeCode ? "combine work in execute_code using the program addresses in tool descriptions." : "find tools with your host's search."} Read-only endpoints omit and refuse writes. Never repeat a write for output. Give auth handoffs to the user/operator. Follow nextAction to page with ${executeCode ? "connecta.result in execute_code" : "read_result"}. skills lists guidance.`;
 }
-export { USAGE_SKILL } from "./usage-guide.js";
 /** True when at least one of `connectors` carries a usage guide. */
 export function hasConnectorGuides(connectors) {
     return connectors.some((connector) => connectorGuide(connector) !== undefined);

package/dist/types.d.ts

@@ -432,6 +432,8 @@ export interface Connector {
      * pending URL could complete consent with their own account.
      */
     verifyState?(state: string | null, ctx: ConnectorContext): Promise<boolean>;
+    /** Validate provider callback parameters after state verification and before issuer validation, including errors. */
+    verifyCallbackParameters?(params: URLSearchParams, ctx: ConnectorContext): Promise<boolean>;
     /** Validate a callback issuer against its verified consent, including error responses. */
     verifyCallbackIssuer?(issuer: string | null, ctx: ConnectorContext): Promise<boolean>;
     /**

package/dist/ui.d.ts

@@ -6,7 +6,7 @@ import type { RegistryView } from "./registry.js";
 import type { ConnectaBranding, Connector, ConnectorStatus, ToolDef, UiAuthConfig } from "./types.js";
 export { filterUiConnectors, type CredentialManagementCapability, type UiConnector, type UiData, } from "./operator-ui/model.js";
 export { CONNECTA_FAVICON_SVG, resolveBranding, isSafeHttpUrl, isSafeHttpsUrl, isSafeIconHref } from "./branding.js";
-export type OperatorPage = import("./operator-ui/view.js").OperatorPage;
+export type OperatorPage = import("./operator-ui/contract.js").OperatorPage;
 export declare function operatorPageForPath(path: string): OperatorPage | undefined;
 export declare function operatorPageTitle(page: OperatorPage, configuredTitle: string): string;
 /** Report the verdict the registry stored, independent of whether an endpoint is read-only. */

package/dist/ui.js

@@ -164,7 +164,6 @@ _nonce, page = "endpoints") {
             productName: brand.productName,
             brandMark: brandMark(branding, true),
             productDescription: brand.description,
-            productOperatorLabel: brand.productName + " operator",
         })}</script><script defer src="${OPERATOR_UI_SCRIPT_PATH}"></script>`,
     });
 }