Skip to content

feat: query-type coercion, attachables search ergonomics, response sh… - #108

Open
ehkay-bit wants to merge 1 commit into
intuit:mainfrom
ehkay-bit:fix/query-layer-ergonomics-upstream
Open

feat: query-type coercion, attachables search ergonomics, response sh…#108
ehkay-bit wants to merge 1 commit into
intuit:mainfrom
ehkay-bit:fix/query-layer-ergonomics-upstream

Conversation

@ehkay-bit

@ehkay-bit ehkay-bit commented Jul 21, 2026

Copy link
Copy Markdown
Contributor

…aping, transaction deep links, tool aliases

Grounded in heavy production use (hundreds of search/create/update calls):

Query layer:

  • Search criteria values are accepted natively as string/number/boolean/ array. Previously numeric values were rejected by the Zod schema ("Expected string, received number"), boolean-as-string "true" was forwarded raw into QBO SQL (QueryProcessingError: String cannot be cast to Boolean), and IN was unusable (JSON arrays rejected; a pre-built SQL-tuple string double-quoted into QueryParserError). Booleans-as- strings are coerced on known boolean fields; IN accepts a JSON array (node-quickbooks builds the tuple) and legacy tuple strings are parsed.
  • search_attachables: pagination (limit/offset), orderby with a newest-first default (QBO's oldest-first default made "does txn X have a recent attachment" impossible on large files), and created-date range filters. New get_entity_attachments(entity_type, entity_id) pages newest-first and filters by AttachableRef server-side (AttachableRef is not queryable in QBO SQL), reporting scan completeness.
  • Optional fields (dot-path projection) and summary (one compact line per entity) on criteria-based search tools; get_general_ledger gains a flatten mode (Columns/Rows -> [{column: value}]) — raw GL responses ran to megabytes. A test pins that account/source_account reach the Reports API.

Transaction deep links (safe remediation for mis-created transactions):

  • New get_transaction_link tool: (entity_type, id) -> the QBO web deep link, e.g. https://qbo.intuit.com/app/bill?txnId=, covering bill, expense/cheque, transfer, journal, billpayment, deposit, recvpayment, invoice, creditmemo, vendorcredit.
  • Every create_/update_ transaction response now includes a qbo_link field. CAVEAT handled: txnId resolves against whichever company is active in the browser session, so every link is prefixed with the server's company name (cached from CompanyInfo) for the user to verify before acting.

Ergonomics:

  • Underscore aliases for hyphenated tool names (create_bill, update_bill, get_bill, create_vendor, update_vendor, get_vendor); hyphen names kept.
  • get_journal_entry accepts id aliases (journal_entry_id/entry_id).
  • create-vendor: CurrencyRef (immutable after the vendor's first transaction — must be settable at create), TermRef, TaxIdentifier, Vendor1099; schema opened with passthrough.
  • create_attachable: TempDownloadUri (multi-KB pre-signed URL) stripped from responses unless return_download_uri: true.

Tests: query-layer-ergonomics suite (17 cases).

Complementary to #107 (zero file overlap — the two merge independently in either order).

…aping, transaction deep links, tool aliases

Grounded in heavy production use (hundreds of search/create/update calls):

Query layer:
- Search criteria values are accepted natively as string/number/boolean/
  array. Previously numeric values were rejected by the Zod schema
  ("Expected string, received number"), boolean-as-string "true" was
  forwarded raw into QBO SQL (QueryProcessingError: String cannot be cast
  to Boolean), and IN was unusable (JSON arrays rejected; a pre-built
  SQL-tuple string double-quoted into QueryParserError). Booleans-as-
  strings are coerced on known boolean fields; IN accepts a JSON array
  (node-quickbooks builds the tuple) and legacy tuple strings are parsed.
- search_attachables: pagination (limit/offset), orderby with a
  newest-first default (QBO's oldest-first default made "does txn X have
  a recent attachment" impossible on large files), and created-date range
  filters. New get_entity_attachments(entity_type, entity_id) pages
  newest-first and filters by AttachableRef server-side (AttachableRef is
  not queryable in QBO SQL), reporting scan completeness.
- Optional fields (dot-path projection) and summary (one compact line per
  entity) on criteria-based search tools; get_general_ledger gains a
  flatten mode (Columns/Rows -> [{column: value}]) — raw GL responses ran
  to megabytes. A test pins that account/source_account reach the
  Reports API.

Transaction deep links (safe remediation for mis-created transactions):
- New get_transaction_link tool: (entity_type, id) -> the QBO web deep
  link, e.g. https://qbo.intuit.com/app/bill?txnId=<id>, covering bill,
  expense/cheque, transfer, journal, billpayment, deposit, recvpayment,
  invoice, creditmemo, vendorcredit.
- Every create_/update_ transaction response now includes a qbo_link
  field. CAVEAT handled: txnId resolves against whichever company is
  active in the browser session, so every link is prefixed with the
  server's company name (cached from CompanyInfo) for the user to verify
  before acting.

Ergonomics:
- Underscore aliases for hyphenated tool names (create_bill, update_bill,
  get_bill, create_vendor, update_vendor, get_vendor); hyphen names kept.
- get_journal_entry accepts id aliases (journal_entry_id/entry_id).
- create-vendor: CurrencyRef (immutable after the vendor's first
  transaction — must be settable at create), TermRef, TaxIdentifier,
  Vendor1099; schema opened with passthrough.
- create_attachable: TempDownloadUri (multi-KB pre-signed URL) stripped
  from responses unless return_download_uri: true.

Tests: query-layer-ergonomics suite (17 cases).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
a-horde-o-bees added a commit to a-horde-o-bees/quickbooks-online-mcp-server that referenced this pull request Aug 7, 2026
create/update-vendor return to upstream's typed schemas, extended with
BillAddr.Line2/Line3 and .passthrough() at every object level so valid
QBO Vendor fields outside the schema (Active, PrintOnCheckName, AcctNum,
Notes, TermRef, Vendor1099) are no longer silently stripped. Same shape
as upstream's create-journal-entry fix (bef85c4); converges with the
create-vendor changes proposed in upstream PR intuit#108.

tsc clean; npm test 26/26 suites, 494 tests.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant