@happyvertical/accounting 0.100.3 → 0.101.1

package/README.md

@@ -2,8 +2,88 @@
 
 Provider-neutral accounting synchronization with Stripe billing support.
 
+## QuickBooks connection OAuth
+
+Use the public connection helper to generate an accounting authorization URL,
+exchange Intuit's callback, and revoke a refresh token:
+
+```ts
+import { createQuickBooksOAuthClient } from '@happyvertical/accounting';
+
+const oauth = await createQuickBooksOAuthClient({
+  clientId: process.env.QBO_CLIENT_ID!,
+  clientSecret: process.env.QBO_CLIENT_SECRET!,
+  environment: 'sandbox',
+  redirectUri: 'https://app.example.com/api/accounting/quickbooks/callback',
+});
+
+const url = oauth.authorizationUrl({ state: oneUseOpaqueState });
+const connection = await oauth.exchangeCallback({
+  callbackUrl: request.url,
+  expectedState: oneUseOpaqueState,
+});
+await oauth.revoke({ refreshToken: connection.tokens.refreshToken });
+```
+
+The helper requests only Intuit's QuickBooks accounting scope. Before the
+official client receives a callback, it requires the configured origin and
+path, exactly one nonempty state, code, and realm ID, and a constant-time state
+match. Returned failures have stable `QuickBooksOAuthError.code` values and do
+not retain provider errors that may contain callback URLs or credentials.
+
+The application owns one-use state bound to its authenticated principal,
+tenant, and environment; authorization to connect the returned realm;
+encrypted token storage; and atomic connection persistence. The helper does
+not make those application decisions. The redirect URI must also be registered
+in Intuit's developer portal. See Intuit's [OAuth client authorization-code flow](https://github.com/intuit/oauth-jsclient#authorization-code-flow)
+and [revocation helper](https://github.com/intuit/oauth-jsclient#revoke-access_token).
+
 ## 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 +156,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-x9rUYj0b.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 "./rolldown-runtime-D1cXj70v.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-x9rUYj0b.js.map