@happyvertical/accounting 0.100.3 → 0.101.0

package/README.md

@@ -4,6 +4,50 @@ Provider-neutral accounting synchronization with Stripe billing support.
 
 ## QuickBooks invoice creation and retries
 
+QuickBooks sales lines can carry explicit references to existing entities in the
+target company:
+
+```ts
+const invoice = {
+  // ...provider-neutral invoice fields...
+  currency: 'CAD',
+  subtotal: 100,
+  taxAmount: 5,
+  totalAmount: 105,
+  quickbooksMapping: { globalTaxCalculation: 'TaxExcluded' },
+  lineItems: [
+    {
+      description: 'Reviewed work',
+      quantity: 1,
+      unitPrice: 100,
+      quickbooksMapping: {
+        itemRef: '123', // Item.Id in this QuickBooks company
+        taxCodeRef: 'GST', // TaxCode.Id in this QuickBooks company
+      },
+    },
+  ],
+};
+```
+
+The QuickBooks adapter maps these values to `SalesItemLineDetail.ItemRef`,
+`SalesItemLineDetail.TaxCodeRef`, `GlobalTaxCalculation`, and
+`TxnTaxDetail.TotalTax`. It supports `TaxExcluded` and zero-tax
+`NotApplicable`; tax-inclusive inputs are rejected because the provider-neutral
+line model does not allocate included tax. Every mapped line must supply both
+realm-specific references. The caller must validate that those IDs belong to
+the configured company. See Intuit's [invoice API](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/invoice)
+and [item API](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/item).
+
+Legacy untaxed invoices without `quickbooksMapping` remain supported. The
+adapter fails before authentication or HTTP when an input would otherwise be
+silently discarded: nonzero line `discount`, nonzero numeric `taxRate`, generic
+`taxCode`, `automaticTax`, inconsistent totals, partial mappings, or invalid
+references. Explicit zero `discount` and `taxRate` are accepted. This mapping
+API has no discount representation and does not silently net discounts into
+prices. An explicit line `amount` must agree with `quantity × unitPrice`; the
+adapter compares ordinary decimal calculations without assuming a fixed number
+of decimal places for every currency.
+
 Prepare a caller-owned request descriptor **once**, persist it with the approved
 invoice in your durable outbox, then pass it on every create attempt:
 
@@ -76,8 +120,7 @@ The [static documentation](https://static.developer.intuit.com/output_html/qbo/d
 confirms the 50-character limit and per-realm uniqueness requirement.
 Our regression tests mock remote acceptance and response loss; they prove SDK
 identity/byte preservation and retry policy, **not live Intuit deduplication**.
-No sandbox credentials were available for this change. Before relying on remote
-idempotency, verify in an authorized sandbox: send a uniquely identified invoice,
+Before relying on remote idempotency, verify in an authorized sandbox: send a uniquely identified invoice,
 repeat the identical request with the same ID, confirm the same Invoice.Id and
 one invoice, and simulate a lost response before replaying it. Record realm,
 environment, request ID, timestamps, and returned IDs without credentials.

package/dist/chunks/{OAuthClient-CF65pAW_.js → OAuthClient-BbD5jYu3.js}

@@ -1,4 +1,4 @@
-import { a as __toCommonJS, i as __require, n as __esmMin, r as __exportAll, t as __commonJSMin } from "./quickbooks-DLkypnT9.js";
+import { a as __toCommonJS, i as __require, n as __esmMin, r as __exportAll, t as __commonJSMin } from "./quickbooks-BJlHXQSw.js";
 //#region ../../node_modules/.pnpm/atob@2.1.2/node_modules/atob/browser-atob.js
 var require_browser_atob = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	(function(w) {
@@ -18261,4 +18261,4 @@ var require_OAuthClient = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 //#endregion
 export default require_OAuthClient();
 
-//# sourceMappingURL=OAuthClient-CF65pAW_.js.map
+//# sourceMappingURL=OAuthClient-BbD5jYu3.js.map