@happyvertical/accounting 0.103.6 → 0.104.0

package/README.md

@@ -70,27 +70,58 @@ const invoice = {
 
 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).
+`TxnTaxDetail`. It supports `TaxExcluded`, zero-tax `NotApplicable`, and frozen
+`TaxInclusive` snapshots. For an inclusive line, pass the stored net amount as
+`amount`, its stored tax as `taxAmount`, the stored gross amount as
+`taxInclusiveAmount`, and stored per-component amounts as `taxComponents`.
+An explicit zero-tax inclusive snapshot may supply an empty component list when
+its net and gross facts are equal, including when an off-grid reduced unit price
+requires the generated negative discount line.
+The adapter sends net `Amount` and gross
+`SalesItemLineDetail.TaxInclusiveAmt`; Intuit defines that nested field as the
+total including tax in its [SDK reference](https://static.developer.intuit.com/sdkdocs/qbv3doc/ippphpdevkitv3/entities/files/IPPSalesOrderItemLineDetail.html).
+It emits the stored component tax exactly as `TxnTaxDetail.TaxLine[].Amount`.
+When any component detail is present, every taxed line must carry it and the
+minor-unit aggregate must equal the frozen header tax. Each component therefore
+needs a realm `quickbooksTaxRateRef`; its frozen
+`rate` is a fraction from `0` through `1` and becomes QBO's percent-form
+`TaxPercent` (for example `0.13` becomes `13`). Intuit's invoice example shows
+the writable `TaxLineDetail` fields, and its TaxLineDetail reference requires
+an international `TaxRateRef` to belong to a tax code used on a transaction
+line: [invoice API](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/invoice),
+[TaxLineDetail reference](https://static.developer.intuit.com/sdkdocs/qbv3doc/ippdotnetdevkitv3/html/393902ec-f79c-bb8f-82fd-0f3bd296dd27.htm).
+It validates every component sum, rate-to-frozen-amount allocation (each stored
+component is the exact floor or ceiling allowed by line/document rounding), and
+header reconciliation before any network request. Every mapped line must supply both realm-specific references;
+the caller must validate that those IDs belong to the configured company.
 
 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`, either
-as the existing exact-product calculation or as its decimal **half-up** result at
-the explicitly supplied currency's ISO 4217 minor precision. For example, CAD
-quantity `1.0005` × unit price `10` accepts the retained line amount `10.01`.
-The adapter preserves all three supplied values; it does not replace the amount,
-round an omitted amount, or change subtotal/tax reconciliation. The rounded path
-requires an amount exactly on the currency's minor-unit grid, not an arbitrary
-monetary tolerance. Negative quantities, prices and amounts remain unsupported.
+silently discarded: nonzero numeric `taxRate`, generic `taxCode`, `automaticTax`,
+inconsistent totals, partial mappings, or invalid references. `unitPrice` and
+`discount` are in the document's amount mode: net for exclusive inputs and gross
+for inclusive ones; `amount` is always the already-discounted net snapshot. A
+discount uses a reduced QBO unit price only when that price fits the currency's
+ISO 4217 minor-unit grid. Otherwise, for an inclusive line, the adapter derives
+the negative net amount from the frozen gross discount and frozen component
+rates, and then adds a negative `Discount on line N` sales line with the same item and tax-code
+references. It never sends QBO's unsupported line-discount field or subtracts a
+discount twice. Negative generated discount lines are internal; caller invoice
+lines remain non-negative. An explicit exclusive line `amount` must agree with
+`quantity × unitPrice` after discount, either exactly or as its decimal
+**half-up** result at the explicitly supplied currency's ISO 4217 minor
+precision. For example, CAD quantity `1.0005` × unit price `10` accepts the
+retained line amount `10.01`. The adapter preserves approved snapshots and never
+changes subtotal/tax reconciliation.
+
+A frozen monetary snapshot means a `TaxInclusive` document, or a line carrying
+`taxAmount`, `taxComponents`, `taxInclusiveAmount`, or a nonzero `discount`.
+Those snapshots (document subtotal/tax/total and relevant line net/gross,
+component tax, and discount) must fit the explicitly supplied ISO 4217 grid.
+The source `unitPrice` may remain fractional when its retained line amount is
+on that grid. Legacy exclusive exact-product inputs that carry only an `amount`
+or QuickBooks mapping retain the base validation and do not require a known
+currency. Unknown or missing currency never authorizes frozen snapshot rounding.
 
 Precision comes from [ISO 4217 List One published 2026-09-17](https://www.six-group.com/dam/download/financial-information/data-center/iso-currrency/lists/list-one.xml),
 not runtime display formatting (which differs for IQD, MGA and RSD). Zero-, two-,
@@ -179,6 +210,44 @@ environment, request ID, timestamps, and returned IDs without credentials.
 No replay retention period or exactly-once guarantee is asserted here; reconcile
 old or uncertain requests against QuickBooks before any new creation identity.
 
+## QuickBooks credit memos
+
+`creditMemos` is an optional provider capability. QuickBooks supports positive
+frozen customer credit notes through `CreditMemo`; providers that omit the
+capability must be refused by the caller. A `CreditMemoInput` uses the same
+net/gross/tax snapshot rules as an invoice, has a
+`creditedInvoiceExternalId` for durable reconciliation, and is created with a
+separate descriptor:
+
+```ts
+import {
+  prepareQuickBooksCreditMemoRequest,
+  requireCreditMemoOperations,
+} from '@happyvertical/accounting';
+
+const request = prepareQuickBooksCreditMemoRequest(creditMemo, {
+  requestId: outbox.requestId,
+  realmId: outbox.realmId,
+  environment: 'sandbox',
+});
+await requireCreditMemoOperations(qbo).push({
+  ...creditMemo,
+  quickbooksCreditMemoRequest: request,
+});
+```
+
+The descriptor carries its realm, environment, and caller-owned request ID, and
+hashes the mapped frozen credit payload together with
+`creditedInvoiceExternalId`. It does not include mutable payment, allocation,
+or status fields, so a retry of the same frozen revision keeps the same request
+identity. Creating a QBO
+`CreditMemo` does not itself apply that credit to the named invoice through this
+API contract; an application must record any later QBO payment/application step
+explicitly. This package does not assume an account's automatic-credit setting.
+It has the same retry and unknown-outcome rules as a keyed invoice create. No
+live Intuit sandbox assertion is made by this package's contract tests; they
+verify serialized payloads, request IDs, retries, and refusal paths.
+
 ## Stripe invoices
 
 Accounting amounts use currency major units: `12.34` means USD 12.34 and
@@ -435,3 +504,48 @@ After `webhooks.verify` succeeds, the parsed Stripe webhook exposes its provider
 Persist that identifier in a durable inbox before applying side effects; the
 in-process parser alone cannot deduplicate deliveries across restarts or
 replicas.
+
+### Ordered compound tax snapshots
+
+A frozen component may set `compound: true` and `taxableAmount` (currency major
+units). It then taxes the line's net amount plus **all preceding components in
+that line's ordered snapshot**. Its explicit basis must equal that sum of stored
+facts; neither a replacement rate nor a jurisdiction rule is inferred. Different
+applicable line subsets use their corresponding realm tax codes.
+
+Compound lines also require verified configuration evidence:
+
+```ts
+quickbooksMapping: {
+  itemRef: '123',
+  taxCodeRef: 'configured-compound-code',
+  taxComponents: [
+    { taxRateRef: 'gst-rate', compound: false },
+    { taxRateRef: 'provincial-rate', compound: true },
+  ],
+}
+```
+
+The host must verify this sequence against the target company's existing TaxCode,
+including its applicability and ordering, and persist the verification provenance
+with tenant configuration. The SDK requires an exact match with frozen component
+references and flags; it cannot verify a remote realm from an ID alone and does
+not create or modify tax codes. Missing, duplicate, unknown or mismatched order
+metadata fails before a request can be sent. Tax-only dependencies other than
+all previous applicable components are outside this contract.
+
+Exclusive validation uses preceding stored rounded/allocated taxes. Inclusive
+validation extracts exact ordered rational factors and checks the same permitted
+floor/ceiling allocation as additive snapshots. Inclusive discount projection
+uses those factors too. Stored component amounts and original rates are preserved
+in `TxnTaxDetail.TaxLine`; an explicit basis is aggregated by rate into
+`TaxLineDetail.NetAmountTaxable`. Additive snapshots without these new fields
+retain their prior payload bytes and retry descriptor hashes. Credit memos use
+the same representation. This preserves source facts; sandbox acceptance and
+provider readback still require the host's authorized integration verification.
+
+Intuit's [TaxRateDetail schema](https://static.developer.intuit.com/sdkdocs/qbv3doc/ipp-v3-java-devkit-javadoc/com/intuit/ipp/data/TaxRateDetail.html)
+defines applicability/order, including
+[TaxOnAmountPlusTax](https://static.developer.intuit.com/sdkdocs/qbv3doc/ipp-v3-java-devkit-javadoc/com/intuit/ipp/data/TaxTypeApplicablityEnum.html).
+Its [TaxLineDetail reference](https://static.developer.intuit.com/sdkdocs/qbv3doc/ippdotnetdevkitv3/html/393902ec-f79c-bb8f-82fd-0f3bd296dd27.htm)
+documents the applicable-rate taxable base and realm rate-reference constraint.

package/dist/chunks/invoice-request-D5fbd6Id.js

@@ -0,0 +1,479 @@
+import { createHash } from "node:crypto";
+//#region src/providers/quickbooks/line-amount.ts
+var currencyPrecision = new Map([
+	[0, "BIF CLP DJF GNF ISK JPY KMF KRW PYG RWF UGX UYI VND VUV XAF XOF XPF"],
+	[2, "AED AFN ALL AMD AOA ARS AUD AWG AZN BAM BBD BDT BMD BND BOB BOV BRL BSD BTN BWP BYN BZD CAD CDF CHE CHF CHW CNY COP COU CRC CUP CVE CZK DKK DOP DZD EGP ERN ETB EUR FJD FKP GBP GEL GHS GIP GMD GTQ GYD HKD HNL HTG HUF IDR ILS INR IRR JMD KES KGS KHR KPW KYD KZT LAK LBP LKR LRD LSL MAD MDL MGA MKD MMK MNT MOP MRU MUR MVR MWK MXN MXV MYR MZN NAD NGN NIO NOK NPR NZD PAB PEN PGK PHP PKR PLN QAR RON RSD RUB SAR SBD SCR SDG SEK SGD SHP SLE SOS SRD SSP STN SVC SYP SZL THB TJS TMT TOP TRY TTD TWD TZS UAH USD USN UYU UZS VED VES WST XAD XCD XCG YER ZAR ZMW ZWG"],
+	[3, "BHD IQD JOD KWD LYD OMR TND"],
+	[4, "CLF UYW"]
+].flatMap(([precision, codes]) => codes.split(" ").map((code) => [code, precision])));
+/** ISO minor-unit factor, or undefined when the code is unknown or omitted. */
+function currencyMinorUnitFactor(currency) {
+	if (typeof currency !== "string") return void 0;
+	const precision = currencyPrecision.get(currency.toUpperCase());
+	return precision === void 0 ? void 0 : 10 ** precision;
+}
+/** True only for a finite amount exactly representable on the ISO minor-unit grid. */
+function isCurrencyMinorUnit(amount, currency) {
+	if (!Number.isFinite(amount) || typeof currency !== "string") return false;
+	const precision = currencyPrecision.get(currency.toUpperCase());
+	if (precision === void 0) return false;
+	const value = decimalRatio(Math.abs(amount));
+	return value.numerator * 10n ** BigInt(precision) % value.denominator === 0n;
+}
+/** Round a finite major-unit amount half-up to a known ISO currency grid. */
+function roundCurrencyAmount(amount, currency) {
+	if (!Number.isFinite(amount) || typeof currency !== "string") return void 0;
+	const precision = currencyPrecision.get(currency.toUpperCase());
+	if (precision === void 0) return void 0;
+	const sign = amount < 0 ? -1n : 1n;
+	const value = decimalRatio(Math.abs(amount));
+	const scale = 10n ** BigInt(precision);
+	const numerator = value.numerator * scale;
+	const rounded = numerator / value.denominator + (numerator % value.denominator * 2n >= value.denominator ? 1n : 0n);
+	return Number(sign * rounded) / Number(scale);
+}
+/** Exact decimal interpretation of the finite nonnegative public number value. */
+function decimalRatio(value) {
+	const [significand, exponent = "0"] = value.toString().split("e");
+	const [whole, fraction = ""] = significand.split(".");
+	const coefficient = BigInt(whole + fraction);
+	const scale = fraction.length - Number(exponent);
+	return scale >= 0 ? {
+		numerator: coefficient,
+		denominator: 10n ** BigInt(scale)
+	} : {
+		numerator: coefficient * 10n ** BigInt(-scale),
+		denominator: 1n
+	};
+}
+/** Admit only the exact half-up minor-unit result; never rewrite caller money. */
+function matchesCurrencyRoundedLineAmount(quantity, unitPrice, amount, currency) {
+	if (typeof currency !== "string") return false;
+	const precision = currencyPrecision.get(currency.toUpperCase());
+	if (precision === void 0) return false;
+	const minorScale = 10n ** BigInt(precision);
+	const retained = decimalRatio(amount);
+	const retainedMinor = retained.numerator * minorScale;
+	if (retainedMinor % retained.denominator !== 0n) return false;
+	const qty = decimalRatio(quantity);
+	const price = decimalRatio(unitPrice);
+	const numerator = qty.numerator * price.numerator * minorScale;
+	const denominator = qty.denominator * price.denominator;
+	const rounded = numerator / denominator + (numerator % denominator * 2n >= denominator ? 1n : 0n);
+	return retainedMinor / retained.denominator === rounded;
+}
+//#endregion
+//#region src/providers/quickbooks/invoice-request.ts
+/** Prepare once, persist before sending, and reuse unchanged. Performs no I/O. */
+function prepareQuickBooksInvoiceRequest(invoice, identity) {
+	if (invoice.externalId) throw new Error("QuickBooks request identity is only for invoice creation");
+	return prepareRequest(mapInvoiceToQBO(invoice), identity, "invoice");
+}
+/** Prepare once, persist before sending, and reuse unchanged. Performs no I/O. */
+function prepareQuickBooksCreditMemoRequest(creditMemo, identity) {
+	if (creditMemo.externalId) throw new Error("QuickBooks request identity is only for credit memo creation");
+	return prepareRequest(mapCreditMemoToQBO(creditMemo), {
+		...identity,
+		creditedInvoiceExternalId: creditMemo.creditedInvoiceExternalId
+	}, "credit memo");
+}
+function prepareRequest(mapped, identity, kind) {
+	const payload = JSON.stringify(mapped);
+	const request = {
+		...identity,
+		payloadHash: hashDescriptorPayload(payload, identity, kind)
+	};
+	validateRequest(request, identity.realmId, identity.environment, payload, kind);
+	return Object.freeze(request);
+}
+function hash(payload) {
+	return createHash("sha256").update(payload).digest("hex");
+}
+/** Bind a credit memo's immutable source invoice without sending it to QBO. */
+function hashDescriptorPayload(payload, request, kind) {
+	if (kind === "invoice") return hash(payload);
+	return hash(JSON.stringify({
+		payload,
+		linkage: { creditedInvoiceExternalId: request.creditedInvoiceExternalId }
+	}));
+}
+function validateQuickBooksInvoiceRequest(request, realmId, environment, payload) {
+	validateRequest(request, realmId, environment, payload, "invoice");
+}
+function validateQuickBooksCreditMemoRequest(request, realmId, environment, payload) {
+	validateRequest(request, realmId, environment, payload, "credit memo");
+}
+function validateRequest(request, realmId, environment, payload, kind) {
+	if (!request || typeof request.requestId !== "string" || !/^[A-Za-z0-9._-]{1,50}$/.test(request.requestId)) throw new Error("QuickBooks requestId must contain 1–50 URL-safe letters, digits, dots, underscores or hyphens");
+	if (!request.realmId || request.realmId !== realmId || !["sandbox", "production"].includes(request.environment) || request.environment !== environment) throw new Error(`QuickBooks ${kind} request realm/environment mismatch`);
+	if (!payload || request.payloadHash !== hashDescriptorPayload(payload, request, kind)) throw new Error(`QuickBooks ${kind} request payload mismatch; reconcile the original request`);
+	if (kind === "credit memo" && (!("creditedInvoiceExternalId" in request) || !request.creditedInvoiceExternalId || request.creditedInvoiceExternalId.trim() !== request.creditedInvoiceExternalId)) throw new Error("QuickBooks credit memo request requires a credited invoice external ID");
+	const parsed = JSON.parse(payload);
+	if (parsed.Id !== void 0 || parsed.SyncToken !== void 0) throw new Error(`QuickBooks request identity is only for ${kind} creation`);
+}
+function formatLocalDate(date) {
+	return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`;
+}
+function close(a, b) {
+	return Number.isFinite(a) && Number.isFinite(b) && Math.abs(a - b) <= Number.EPSILON * Math.max(1, Math.abs(a), Math.abs(b)) * 8;
+}
+function finite(value, label, allowNegative = false) {
+	if (!Number.isFinite(value) || !allowNegative && value < 0) throw new Error(`QuickBooks ${label} must be a finite ${allowNegative ? "" : "non-negative "}amount`);
+	return value;
+}
+function reference(value, label) {
+	if (!value || value.trim() !== value || value.length > 255) throw new Error(`QuickBooks ${label} must be a non-empty realm reference`);
+	return { value };
+}
+function canonicalRateNumber(value) {
+	for (let places = 0; places <= 12; places++) {
+		const candidate = Number(value.toFixed(places));
+		if (close(value, candidate)) return candidate.toString();
+	}
+	return value.toString();
+}
+function decimalRate(value, label) {
+	const text = typeof value === "string" && /^\d+(?:\.\d+)?$/.test(value) ? value : typeof value === "number" && Number.isFinite(value) && value >= 0 ? canonicalRateNumber(value) : void 0;
+	if (!text || !/^\d+(?:\.\d+)?$/.test(text)) throw new Error(`QuickBooks ${label} needs a frozen component rate from 0 through 1`);
+	const [whole, fraction = ""] = text.split(".");
+	const denominator = 10n ** BigInt(fraction.length);
+	const numerator = BigInt(`${whole}${fraction}`);
+	if (numerator > denominator) throw new Error(`QuickBooks ${label} needs a frozen component rate from 0 through 1`);
+	return {
+		numerator,
+		denominator,
+		value: Number(text)
+	};
+}
+function ratesEqual(left, right) {
+	return left.numerator * right.denominator === right.numerator * left.denominator;
+}
+function addRates(left, right) {
+	const numerator = left.numerator * right.denominator + right.numerator * left.denominator;
+	const denominator = left.denominator * right.denominator;
+	return {
+		numerator,
+		denominator,
+		value: Number(numerator) / Number(denominator)
+	};
+}
+function taxPercent(rate) {
+	return Number(rate.numerator * 100n) / Number(rate.denominator);
+}
+function currencyMinor(amount, currency, label) {
+	const factor = currencyMinorUnitFactor(currency);
+	const rounded = roundCurrencyAmount(amount, currency);
+	if (factor === void 0 || rounded === void 0 || !isCurrencyMinorUnit(amount, currency) && !close(amount, rounded)) throw new Error(`QuickBooks ${label} must fit the explicitly supplied currency's ISO 4217 minor-unit grid`);
+	return BigInt(Math.round((isCurrencyMinorUnit(amount, currency) ? amount : rounded) * factor));
+}
+function currencyMajor(minor, currency) {
+	const factor = currencyMinorUnitFactor(currency);
+	if (factor === void 0) throw new Error("QuickBooks needs a known currency");
+	return Number(minor) / factor;
+}
+function taxMinorMatchesAllocation(taxMinor, numerator, denominator) {
+	const floor = numerator / denominator;
+	const remainder = numerator % denominator;
+	return taxMinor === floor || remainder !== 0n && taxMinor === floor + 1n;
+}
+/** Exact per-component factors relative to net; component order is significant. */
+function orderedFactors(components) {
+	let total = {
+		numerator: 0n,
+		denominator: 1n,
+		value: 0
+	};
+	return {
+		factors: components.map((component) => {
+			const basis = component.compound ? addRates({
+				numerator: 1n,
+				denominator: 1n,
+				value: 1
+			}, total) : {
+				numerator: 1n,
+				denominator: 1n,
+				value: 1
+			};
+			const numerator = component.rate.numerator * basis.numerator;
+			const denominator = component.rate.denominator * basis.denominator;
+			const factor = {
+				numerator,
+				denominator,
+				value: Number(numerator) / Number(denominator)
+			};
+			total = addRates(total, factor);
+			return factor;
+		}),
+		total
+	};
+}
+function validateFrozenComponentRates(components, taxableAmount, currency, inclusive, label) {
+	const taxableMinor = currencyMinor(taxableAmount, currency, `${label} taxable amount`);
+	const { factors, total } = orderedFactors(components);
+	for (const [index, component] of components.entries()) {
+		const factor = factors[index];
+		const numerator = inclusive ? taxableMinor * factor.numerator * total.denominator : component.basisMinor * component.rate.numerator;
+		const denominator = inclusive ? factor.denominator * (total.denominator + total.numerator) : component.rate.denominator;
+		if (!taxMinorMatchesAllocation(component.taxMinor, numerator, denominator)) throw new Error(`QuickBooks ${label} tax component rate is inconsistent with its frozen tax amount`);
+	}
+}
+function frozenCurrencyAmount(value, label, currency, allowNegative = false) {
+	finite(value, label, allowNegative);
+	const rounded = roundCurrencyAmount(value, currency);
+	if (!isCurrencyMinorUnit(value, currency) && (rounded === void 0 || !close(value, rounded))) throw new Error(`QuickBooks ${label} must fit the explicitly supplied currency's ISO 4217 minor-unit grid`);
+	return value;
+}
+function hasFrozenSnapshots(input) {
+	return input.quickbooksMapping?.globalTaxCalculation === "TaxInclusive" || input.lineItems.some((item) => item.taxAmount !== void 0 || item.taxComponents !== void 0 || item.taxInclusiveAmount !== void 0 || item.discount !== void 0 && item.discount !== 0);
+}
+/** Limit accumulated binary error when a valid document has many decimal lines. */
+function compensatedSum(values) {
+	let sum = 0;
+	let compensation = 0;
+	for (const value of values) {
+		const adjusted = value - compensation;
+		const next = sum + adjusted;
+		compensation = next - sum - adjusted;
+		sum = next;
+	}
+	return sum;
+}
+function mapDocumentLines(input) {
+	const mode = input.quickbooksMapping?.globalTaxCalculation;
+	if (mode && ![
+		"TaxExcluded",
+		"TaxInclusive",
+		"NotApplicable"
+	].includes(mode)) throw new Error("QuickBooks globalTaxCalculation must be TaxExcluded, TaxInclusive or NotApplicable");
+	const frozen = hasFrozenSnapshots(input);
+	const validateAmount = (value, label) => frozen ? frozenCurrencyAmount(value, label, input.currency) : finite(value, label);
+	validateAmount(input.subtotal, "subtotal");
+	validateAmount(input.taxAmount, "tax amount");
+	validateAmount(input.totalAmount, "total amount");
+	if (input.lineItems.length === 0) throw new Error("QuickBooks invoices require at least one sales line");
+	const hasLineMapping = input.lineItems.some((item) => item.quickbooksMapping);
+	if ((input.taxAmount > 0 || hasLineMapping) && !input.quickbooksMapping) throw new Error("QuickBooks mapped or nonzero-tax invoices require explicit globalTaxCalculation");
+	if (input.quickbooksMapping && input.lineItems.some((item) => !item.quickbooksMapping)) throw new Error("QuickBooks mapped invoices require itemRef and taxCodeRef on every line");
+	if (input.taxAmount > 0 && mode === "NotApplicable") throw new Error("QuickBooks nonzero tax cannot use NotApplicable global tax calculation");
+	const mapped = [];
+	const taxLines = /* @__PURE__ */ new Map();
+	const snapshotLineTaxes = [];
+	let hasAnyLineTax = false;
+	let hasCompleteLineTax = true;
+	const lineTaxSnapshots = [];
+	for (const [index, item] of input.lineItems.entries()) {
+		const line = mapLine(item, index, input.currency, mode, frozen);
+		mapped.push(...line.lines);
+		lineTaxSnapshots.push({
+			taxAmount: line.taxAmount,
+			taxComponents: line.taxComponents
+		});
+		if (line.taxAmount === void 0) hasCompleteLineTax = false;
+		else {
+			hasAnyLineTax = true;
+			snapshotLineTaxes.push(line.taxAmount);
+		}
+		for (const component of line.taxComponents) {
+			const existing = taxLines.get(component.taxRateRef);
+			if (existing) {
+				if (!ratesEqual(existing.rate, component.rate)) throw new Error(`QuickBooks tax rate ${component.taxRateRef} has inconsistent frozen rates`);
+				existing.amountMinor += component.taxMinor;
+				existing.basisMinor += component.basisMinor;
+				existing.explicitBasis ||= component.explicitBasis;
+				if (existing.explicitBasis && !Number.isSafeInteger(Number(existing.basisMinor))) throw new Error("QuickBooks aggregate taxable basis exceeds safe minor units");
+			} else taxLines.set(component.taxRateRef, {
+				rate: component.rate,
+				amountMinor: component.taxMinor,
+				basisMinor: component.basisMinor,
+				explicitBasis: component.explicitBasis
+			});
+		}
+	}
+	if (!close(compensatedSum(mapped.map((line) => line.Amount)), input.subtotal)) throw new Error("QuickBooks line amounts must equal the invoice subtotal");
+	if (!close(input.subtotal + input.taxAmount, input.totalAmount)) throw new Error("QuickBooks subtotal plus tax must equal the invoice total");
+	if (taxLines.size > 0) {
+		if (lineTaxSnapshots.some((line) => line.taxAmount === void 0 || line.taxAmount > 0 && line.taxComponents.length === 0)) throw new Error("QuickBooks component tax detail requires components on every taxed line");
+		const totalTaxMinor = currencyMinor(input.taxAmount, input.currency, "tax amount");
+		if ([...taxLines.values()].reduce((sum, line) => sum + line.amountMinor, 0n) !== totalTaxMinor) throw new Error("QuickBooks component tax detail must equal the invoice tax amount");
+	}
+	if (hasAnyLineTax && !hasCompleteLineTax) throw new Error("QuickBooks stored line tax must be supplied on every line when any line supplies it");
+	if (hasAnyLineTax && !close(compensatedSum(snapshotLineTaxes), input.taxAmount)) throw new Error("QuickBooks stored line tax must equal the invoice tax amount");
+	return {
+		lines: mapped,
+		taxLines: [...taxLines.entries()].map(([taxRateRef, detail]) => ({
+			Amount: currencyMajor(detail.amountMinor, input.currency),
+			DetailType: "TaxLineDetail",
+			TaxLineDetail: {
+				TaxRateRef: { value: taxRateRef },
+				TaxPercent: taxPercent(detail.rate),
+				PercentBased: true,
+				...detail.explicitBasis ? { NetAmountTaxable: currencyMajor(detail.basisMinor, input.currency) } : {}
+			}
+		}))
+	};
+}
+function mapLine(item, index, currency, mode, enforceCurrencyGrid) {
+	const label = `line ${index + 1}`;
+	if (item.taxRate !== void 0 && item.taxRate !== 0) throw new Error("QuickBooks numeric taxRate is not supported; use a realm taxCodeRef");
+	if (item.taxCode !== void 0) throw new Error("QuickBooks generic taxCode is not a realm tax reference; use quickbooksMapping.taxCodeRef");
+	finite(item.quantity, `${label} quantity`);
+	if (item.quantity <= 0) throw new Error(`QuickBooks ${label} quantity must be greater than zero`);
+	finite(item.unitPrice, `${label} unit price`);
+	const baseDocumentAmount = item.quantity * item.unitPrice;
+	finite(baseDocumentAmount, `${label} pre-discount amount`);
+	const validateAmount = (value, amountLabel, allowNegative = false) => enforceCurrencyGrid ? frozenCurrencyAmount(value, amountLabel, currency, allowNegative) : finite(value, amountLabel, allowNegative);
+	const discount = validateAmount(item.discount ?? 0, `${label} discount`);
+	if (discount > baseDocumentAmount && !close(discount, baseDocumentAmount)) throw new Error(`QuickBooks ${label} discount cannot exceed quantity times unit price`);
+	const netAmount = validateAmount(item.amount ?? baseDocumentAmount - discount, `${label} amount`);
+	const taxAmount = item.taxAmount === void 0 ? void 0 : validateAmount(item.taxAmount, `${label} tax amount`);
+	const taxComponents = [];
+	const componentIds = /* @__PURE__ */ new Set();
+	const componentRateRefs = /* @__PURE__ */ new Set();
+	if (item.taxComponents !== void 0) {
+		if (taxAmount === void 0) throw new Error(`QuickBooks ${label} tax components require a line tax amount`);
+		if (!close(item.taxComponents.reduce((sum, component, componentIndex) => {
+			if (!component || typeof component !== "object" || Object.keys(component).some((key) => ![
+				"taxCode",
+				"rate",
+				"quickbooksTaxRateRef",
+				"taxAmount",
+				"compound",
+				"taxableAmount"
+			].includes(key))) throw new Error(`QuickBooks ${label} tax component has unsupported fields`);
+			if (component.compound !== void 0 && typeof component.compound !== "boolean") throw new Error(`QuickBooks ${label} compound must be boolean`);
+			if (component.compound && component.taxableAmount === void 0) throw new Error(`QuickBooks ${label} compound tax requires its frozen taxableAmount`);
+			if (!component.taxCode || component.taxCode.trim() !== component.taxCode) throw new Error(`QuickBooks ${label} tax component ${componentIndex + 1} needs a tax code`);
+			const rate = decimalRate(component.rate, `${label} tax component ${componentIndex + 1}`);
+			const taxRateRef = reference(component.quickbooksTaxRateRef, `${label} tax component ${componentIndex + 1} quickbooksTaxRateRef`).value;
+			const componentAmount = validateAmount(component.taxAmount, `${label} tax component ${componentIndex + 1}`);
+			if (componentIds.has(component.taxCode) || componentRateRefs.has(taxRateRef)) throw new Error(`QuickBooks ${label} repeats a tax component or rate reference`);
+			componentIds.add(component.taxCode);
+			componentRateRefs.add(taxRateRef);
+			const expectedBasis = currencyMinor(netAmount, currency, `${label} net amount`) + (component.compound ? taxComponents.reduce((sum, prior) => sum + prior.taxMinor, 0n) : 0n);
+			const basisMinor = component.taxableAmount === void 0 ? expectedBasis : currencyMinor(validateAmount(component.taxableAmount, `${label} taxable basis`), currency, `${label} taxable basis`);
+			if (!Number.isSafeInteger(Number(basisMinor))) throw new Error(`QuickBooks ${label} taxable basis exceeds safe minor units`);
+			if (basisMinor !== expectedBasis) throw new Error(`QuickBooks ${label} frozen taxable basis does not match its ordered components`);
+			taxComponents.push({
+				taxRateRef,
+				rate,
+				compound: component.compound ?? false,
+				basisMinor,
+				explicitBasis: component.taxableAmount !== void 0,
+				taxMinor: currencyMinor(componentAmount, currency, `${label} tax component ${componentIndex + 1}`)
+			});
+			return sum + componentAmount;
+		}, 0), taxAmount)) throw new Error(`QuickBooks ${label} tax components must equal the line tax amount`);
+	}
+	const inclusive = mode === "TaxInclusive";
+	const grossAmount = item.taxInclusiveAmount;
+	if (!inclusive && grossAmount !== void 0) throw new Error(`QuickBooks ${label} tax-inclusive amount requires TaxInclusive global tax calculation`);
+	if (inclusive) {
+		if (grossAmount === void 0 || taxAmount === void 0 || taxAmount > 0 && !item.taxComponents?.length) throw new Error(`QuickBooks ${label} TaxInclusive snapshots require gross amount, line tax and tax components for nonzero tax`);
+		validateAmount(grossAmount, `${label} tax-inclusive amount`);
+		if (!close(netAmount + taxAmount, grossAmount)) throw new Error(`QuickBooks ${label} net amount plus tax must equal gross amount`);
+		if (!close(baseDocumentAmount - discount, grossAmount)) throw new Error(`QuickBooks ${label} gross amount must equal quantity times gross unit price less gross discount`);
+	} else if (!close(netAmount, baseDocumentAmount - discount) && !matchesCurrencyRoundedLineAmount(item.quantity, item.unitPrice, netAmount + discount, currency)) throw new Error(`QuickBooks ${label} amount must equal quantity times unit price less discount`);
+	const mappedComponents = item.quickbooksMapping?.taxComponents;
+	if (taxComponents.some((component) => component.compound) && mappedComponents === void 0) throw new Error(`QuickBooks ${label} compound tax requires caller-verified ordered tax-code mapping`);
+	if (mappedComponents !== void 0) {
+		if (!Array.isArray(mappedComponents) || mappedComponents.length !== taxComponents.length) throw new Error(`QuickBooks ${label} ordered tax-code mapping must match every frozen component`);
+		const refs = /* @__PURE__ */ new Set();
+		for (const [position, mapped] of mappedComponents.entries()) {
+			if (!mapped || typeof mapped !== "object" || Object.keys(mapped).some((key) => !["taxRateRef", "compound"].includes(key)) || typeof mapped.compound !== "boolean") throw new Error(`QuickBooks ${label} ordered tax-code mapping has unknown order metadata`);
+			const ref = reference(mapped.taxRateRef, `${label} mapped tax rate`).value;
+			const component = taxComponents[position];
+			if (refs.has(ref) || ref !== component.taxRateRef || mapped.compound !== component.compound) throw new Error(`QuickBooks ${label} ordered tax-code mapping does not match frozen components`);
+			refs.add(ref);
+		}
+	}
+	if (taxComponents.length > 0) validateFrozenComponentRates(taxComponents, inclusive ? grossAmount : netAmount, currency, inclusive, label);
+	const itemRef = item.quickbooksMapping ? reference(item.quickbooksMapping.itemRef, `${label} itemRef`) : void 0;
+	const taxCodeRef = item.quickbooksMapping ? reference(item.quickbooksMapping.taxCodeRef, `${label} taxCodeRef`) : void 0;
+	const line = (amount, quantity, unitPrice, description, taxInclusiveAmount) => ({
+		LineNum: index + 1,
+		Description: description,
+		Amount: amount,
+		DetailType: "SalesItemLineDetail",
+		SalesItemLineDetail: {
+			Qty: quantity,
+			UnitPrice: unitPrice,
+			ItemRef: itemRef,
+			TaxCodeRef: taxCodeRef,
+			...taxInclusiveAmount === void 0 ? {} : { TaxInclusiveAmt: taxInclusiveAmount }
+		}
+	});
+	if (discount === 0 && !inclusive) return {
+		lines: [line(netAmount, item.quantity, item.unitPrice, item.description)],
+		taxAmount,
+		taxComponents
+	};
+	if (discount === 0 || isCurrencyMinorUnit(netAmount / item.quantity, currency)) return {
+		lines: [line(netAmount, item.quantity, netAmount / item.quantity, item.description, inclusive ? grossAmount : void 0)],
+		taxAmount,
+		taxComponents
+	};
+	let preDiscountAmount = netAmount + discount;
+	let negativeAmount = -discount;
+	const preDiscountGross = inclusive ? baseDocumentAmount : void 0;
+	if (inclusive) {
+		const components = item.taxComponents;
+		const exemptSnapshot = taxAmount === 0 && !components?.length;
+		if (!components?.length && !exemptSnapshot) throw new Error(`QuickBooks ${label} needs frozen component rates for an inclusive negative discount line`);
+		let discountNet = roundCurrencyAmount(discount / (1 + (exemptSnapshot ? 0 : (components ?? []).reduce((sum, component, componentIndex) => sum + decimalRate(component.rate, `${label} tax component ${componentIndex + 1}`).value, 0))), currency);
+		if (taxComponents.some((component) => component.compound)) {
+			const { total } = orderedFactors(taxComponents);
+			const numerator = currencyMinor(discount, currency, `${label} discount`) * total.denominator;
+			const denominator = total.denominator + total.numerator;
+			discountNet = currencyMajor((2n * numerator + denominator) / (2n * denominator), currency);
+		}
+		if (discountNet === void 0) throw new Error(`QuickBooks ${label} needs a recognized currency to map an inclusive fractional-unit discount`);
+		preDiscountAmount = netAmount + discountNet;
+		negativeAmount = -discountNet;
+	}
+	if (enforceCurrencyGrid) {
+		frozenCurrencyAmount(preDiscountAmount, `${label} generated pre-discount amount`, currency);
+		frozenCurrencyAmount(negativeAmount, `${label} generated discount amount`, currency, true);
+	}
+	let negativeGross;
+	if (inclusive) {
+		if (grossAmount === void 0 || preDiscountGross === void 0) throw new Error(`QuickBooks ${label} needs frozen gross amounts for an inclusive negative discount line`);
+		const unroundedNegativeGross = grossAmount - preDiscountGross;
+		negativeGross = roundCurrencyAmount(unroundedNegativeGross, currency) ?? unroundedNegativeGross;
+	}
+	if (enforceCurrencyGrid && negativeGross !== void 0) frozenCurrencyAmount(negativeGross, `${label} generated gross discount amount`, currency, true);
+	return {
+		lines: [line(preDiscountAmount, item.quantity, preDiscountAmount / item.quantity, item.description, preDiscountGross), line(negativeAmount, 1, negativeAmount, `Discount on line ${index + 1}`, negativeGross)],
+		taxAmount,
+		taxComponents
+	};
+}
+function basePayload(input, number, dueDate) {
+	const { lines, taxLines } = mapDocumentLines(input);
+	return {
+		CustomerRef: { value: input.customerExternalId || input.customerId },
+		DocNumber: number,
+		TxnDate: formatLocalDate(input.issueDate),
+		...dueDate ? { DueDate: formatLocalDate(dueDate) } : {},
+		Line: lines,
+		GlobalTaxCalculation: input.quickbooksMapping?.globalTaxCalculation,
+		TxnTaxDetail: input.quickbooksMapping ? {
+			TotalTax: input.taxAmount,
+			...taxLines.length > 0 ? { TaxLine: taxLines } : {}
+		} : void 0,
+		CurrencyRef: input.currency ? { value: input.currency } : void 0,
+		CustomerMemo: input.memo ? { value: input.memo } : void 0
+	};
+}
+function mapInvoiceToQBO(invoice) {
+	if (invoice.collectionMethod === "charge_automatically") throw new Error("QuickBooks does not support charge_automatically invoice collection");
+	if (invoice.automaticTax) throw new Error("QuickBooks does not support automaticTax invoice calculation");
+	return basePayload(invoice, invoice.invoiceNumber, invoice.dueDate);
+}
+function mapCreditMemoToQBO(creditMemo) {
+	if (!creditMemo.creditedInvoiceExternalId || creditMemo.creditedInvoiceExternalId.trim() !== creditMemo.creditedInvoiceExternalId) throw new Error("QuickBooks credit memos require a credited invoice external ID");
+	return basePayload(creditMemo, creditMemo.creditMemoNumber);
+}
+//#endregion
+export { validateQuickBooksCreditMemoRequest as a, prepareQuickBooksInvoiceRequest as i, mapInvoiceToQBO as n, validateQuickBooksInvoiceRequest as o, prepareQuickBooksCreditMemoRequest as r, mapCreditMemoToQBO as t };
+
+//# sourceMappingURL=invoice-request-D5fbd6Id.js.map