@happyvertical/smrt-commerce 0.56.0 → 0.56.1

package/dist/chunks/InvoiceCollection-CKQflFjc.js

@@ -0,0 +1,1047 @@
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
+import { s as InvoiceStatus } from "./types-LDETvQ1C.js";
+import { o as minorToMajorUnits } from "./units-CNcjH_eE.js";
+import { i as claimAllocationParent, r as assertAllocationParent } from "./allocation-integrity-DI3G16BN.js";
+import { MoneyValidationError, assertIntegerMinorUnits } from "../money.js";
+import { a as DOCUMENT_MONEY_READ_REBIND, o as DOCUMENT_MONEY_WRITE } from "./TaxSettingsCollection-BBTZDH1S.js";
+import { i as withTenantMoneyCollectionRead } from "./tenant-money-barrier-DjRXgMnX.js";
+import { SmrtCollection, SmrtObject, crossPackageRef, field, foreignKey, smrt } from "@happyvertical/smrt-core";
+import { TenantScoped, getTenantId, queryGlobal, queryWithGlobals, tenantId } from "@happyvertical/smrt-tenancy";
+//#region src/models/Invoice.ts
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, {
+	enumerable: true,
+	configurable: true,
+	writable: true,
+	value
+}) : obj[key] = value;
+var __decorateClass = (decorators, target, key, kind) => {
+	var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+	for (var i = decorators.length - 1, decorator; i >= 0; i--) if (decorator = decorators[i]) result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+	if (kind && result) __defProp(target, key, result);
+	return result;
+};
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+var INVOICE_STATUS_TRANSITIONS = {
+	[InvoiceStatus.DRAFT]: [
+		InvoiceStatus.SENT,
+		InvoiceStatus.PARTIAL,
+		InvoiceStatus.PAID,
+		InvoiceStatus.CANCELLED,
+		InvoiceStatus.WRITTEN_OFF
+	],
+	[InvoiceStatus.SENT]: [
+		InvoiceStatus.VIEWED,
+		InvoiceStatus.PARTIAL,
+		InvoiceStatus.PAID,
+		InvoiceStatus.OVERDUE,
+		InvoiceStatus.CANCELLED,
+		InvoiceStatus.WRITTEN_OFF
+	],
+	[InvoiceStatus.VIEWED]: [
+		InvoiceStatus.SENT,
+		InvoiceStatus.PARTIAL,
+		InvoiceStatus.PAID,
+		InvoiceStatus.OVERDUE,
+		InvoiceStatus.CANCELLED,
+		InvoiceStatus.WRITTEN_OFF
+	],
+	[InvoiceStatus.PARTIAL]: [
+		InvoiceStatus.DRAFT,
+		InvoiceStatus.SENT,
+		InvoiceStatus.VIEWED,
+		InvoiceStatus.PAID,
+		InvoiceStatus.OVERDUE,
+		InvoiceStatus.CANCELLED,
+		InvoiceStatus.WRITTEN_OFF
+	],
+	[InvoiceStatus.OVERDUE]: [
+		InvoiceStatus.SENT,
+		InvoiceStatus.VIEWED,
+		InvoiceStatus.PARTIAL,
+		InvoiceStatus.PAID,
+		InvoiceStatus.CANCELLED,
+		InvoiceStatus.WRITTEN_OFF
+	],
+	[InvoiceStatus.PAID]: [
+		InvoiceStatus.DRAFT,
+		InvoiceStatus.PARTIAL,
+		InvoiceStatus.VIEWED,
+		InvoiceStatus.SENT,
+		InvoiceStatus.OVERDUE,
+		InvoiceStatus.CANCELLED,
+		InvoiceStatus.WRITTEN_OFF
+	],
+	[InvoiceStatus.CANCELLED]: [],
+	[InvoiceStatus.WRITTEN_OFF]: []
+};
+var loadedInvoiceStatus = /* @__PURE__ */ new WeakMap();
+var Invoice = class extends SmrtObject {
+	/** @internal Collection read guard returns this snapshot on its root DB. */
+	rebindMoneyRead(capability, db) {
+		if (capability !== DOCUMENT_MONEY_READ_REBIND) throw new MoneyValidationError("FROZEN_DOCUMENT", "Invoice read rebinding requires the owning capability");
+		this._db = db;
+		this.options.db = db;
+		return this;
+	}
+	kind = "invoice";
+	creditedInvoiceId = null;
+	/** Issued credit-note total cached under the source invoice lock. */
+	creditedAmount = 0;
+	tenantId = null;
+	customerId = "";
+	contractId = "";
+	invoiceNumber = "";
+	/**
+	* External reference (e.g., customer PO number)
+	*/
+	reference = "";
+	issueDate = /* @__PURE__ */ new Date();
+	dueDate = /* @__PURE__ */ new Date();
+	paidDate = null;
+	subtotal = 0;
+	taxAmount = 0;
+	providerTaxAmount = 0;
+	totalAmount = 0;
+	amountPaid = 0;
+	currency = "CAD";
+	/** Pricing interpretation fixed for the document before issue. */
+	lineAmountType = "exclusive";
+	/** Component rounding scope fixed for the document before issue. */
+	taxRoundingScope = "line";
+	/** Informational sum of resolved line discounts, in minor units. */
+	discountTotal = 0;
+	/** Immutable seller registration snapshot once the invoice leaves draft. */
+	sellerTaxRegistrationsJson = "[]";
+	get sellerTaxRegistrations() {
+		try {
+			const value = JSON.parse(this.sellerTaxRegistrationsJson);
+			if (!Array.isArray(value)) return [];
+			return value.filter((entry) => !!entry && typeof entry === "object" && typeof entry.taxComponentId === "string" && typeof entry.number === "string" && typeof entry.label === "string");
+		} catch {
+			return [];
+		}
+	}
+	set sellerTaxRegistrations(value) {
+		this.sellerTaxRegistrationsJson = JSON.stringify(value);
+	}
+	/** Immutable customer tax identifier snapshot once issued. */
+	partyTaxId = "";
+	/** Stable issue/freeze identity, independent of lifecycle updated_at. */
+	moneySnapshotId = "";
+	status = InvoiceStatus.DRAFT;
+	arJournalId = "";
+	arReversalJournalId = null;
+	revenueJournalId = "";
+	/**
+	* External ID in accounting provider (e.g., QBO invoice ID)
+	*/
+	externalId = "";
+	/**
+	* Customer's external ID in accounting provider.
+	* Used to link invoice to customer in external system.
+	*/
+	customerExternalId = "";
+	/**
+	* Accounting provider name ('quickbooks' | 'stripe' | etc.)
+	*/
+	externalProvider = "";
+	/**
+	* When invoice was last synced to provider
+	*/
+	syncedAt = null;
+	accountingSyncStateJson = "";
+	/**
+	* How the provider collects this invoice (#3190), decided once by billing
+	* period close before its first push and reused on every retry, so it is
+	* what the provider was asked for. Server-managed. A host must not offer
+	* another payment rail on a `charge_automatically` invoice the provider is
+	* still collecting.
+	*/
+	collectionMethod = "";
+	/**
+	* When invoice was sent to customer
+	*/
+	sentAt = null;
+	/**
+	* When customer viewed the invoice
+	*/
+	viewedAt = null;
+	/**
+	* Number of payment reminders sent
+	*/
+	remindersSent = 0;
+	/**
+	* When last reminder was sent
+	*/
+	lastReminderAt = null;
+	notes = "";
+	customerNotes = "";
+	terms = "";
+	constructor(options = {}) {
+		super(options);
+		if (options.kind !== void 0) this.kind = options.kind;
+		if (options.creditedInvoiceId !== void 0) this.creditedInvoiceId = options.creditedInvoiceId;
+		if (options.creditedAmount !== void 0) this.creditedAmount = options.creditedAmount;
+		if (options.tenantId !== void 0) this.tenantId = options.tenantId;
+		if (options.customerId !== void 0) this.customerId = options.customerId;
+		if (options.contractId !== void 0) this.contractId = options.contractId;
+		if (options.invoiceNumber !== void 0) this.invoiceNumber = options.invoiceNumber;
+		if (options.reference !== void 0) this.reference = options.reference;
+		if (options.issueDate !== void 0) this.issueDate = options.issueDate;
+		if (options.dueDate !== void 0) this.dueDate = options.dueDate;
+		if (options.paidDate !== void 0) this.paidDate = options.paidDate;
+		if (options.subtotal !== void 0) this.subtotal = options.subtotal;
+		if (options.taxAmount !== void 0) this.taxAmount = options.taxAmount;
+		if (options.providerTaxAmount !== void 0) this.providerTaxAmount = options.providerTaxAmount;
+		if (options.totalAmount !== void 0) this.totalAmount = options.totalAmount;
+		if (options.amountPaid !== void 0) this.amountPaid = options.amountPaid;
+		if (options.currency !== void 0) this.currency = options.currency;
+		if (options.lineAmountType !== void 0) this.lineAmountType = options.lineAmountType;
+		if (options.taxRoundingScope !== void 0) this.taxRoundingScope = options.taxRoundingScope;
+		if (options.discountTotal !== void 0) this.discountTotal = options.discountTotal;
+		if (options.sellerTaxRegistrationsJson !== void 0) this.sellerTaxRegistrationsJson = options.sellerTaxRegistrationsJson;
+		if (options.sellerTaxRegistrations !== void 0) this.sellerTaxRegistrations = structuredClone(options.sellerTaxRegistrations);
+		if (options.partyTaxId !== void 0) this.partyTaxId = options.partyTaxId;
+		if (options.moneySnapshotId !== void 0) this.moneySnapshotId = options.moneySnapshotId;
+		if (options.status !== void 0) this.status = options.status;
+		if (options.arJournalId !== void 0) this.arJournalId = options.arJournalId;
+		if (options.arReversalJournalId !== void 0) this.arReversalJournalId = options.arReversalJournalId;
+		if (options.revenueJournalId !== void 0) this.revenueJournalId = options.revenueJournalId;
+		if (options.externalId !== void 0) this.externalId = options.externalId;
+		if (options.customerExternalId !== void 0) this.customerExternalId = options.customerExternalId;
+		if (options.externalProvider !== void 0) this.externalProvider = options.externalProvider;
+		if (options.syncedAt !== void 0) this.syncedAt = options.syncedAt;
+		if (options.accountingSyncStateJson !== void 0) this.accountingSyncStateJson = options.accountingSyncStateJson;
+		if (options.collectionMethod !== void 0) this.collectionMethod = options.collectionMethod;
+		if (options.sentAt !== void 0) this.sentAt = options.sentAt;
+		if (options.viewedAt !== void 0) this.viewedAt = options.viewedAt;
+		if (options.remindersSent !== void 0) this.remindersSent = options.remindersSent;
+		if (options.lastReminderAt !== void 0) this.lastReminderAt = options.lastReminderAt;
+		if (options.notes !== void 0) this.notes = options.notes;
+		if (options.customerNotes !== void 0) this.customerNotes = options.customerNotes;
+		if (options.terms !== void 0) this.terms = options.terms;
+	}
+	/**
+	* Capture the persisted status the row was loaded with, so the save-time
+	* transition guard can reject illegal status flips made via raw field
+	* assignment (mass-assignment on a generated update route, a stale caller,
+	* etc.). Only rows that already exist in the database carry a "prior"
+	* status — freshly-constructed (not-yet-saved) invoices have no prior and
+	* may start in any status.
+	*/
+	async initialize() {
+		await super.initialize();
+		if (await this.isSaved()) loadedInvoiceStatus.set(this, this.status);
+		return this;
+	}
+	/**
+	* Recompute and validate financial fields before every write so forged
+	* totals, negative amounts, and illegal status flips can't be persisted via
+	* raw mass-assignment on the generated CRUD routes.
+	*
+	* Behaviour:
+	*  - **Totals are authoritative from line items.** When the invoice is
+	*    persisted and has line items, `subtotal` / `taxAmount` / `totalAmount`
+	*    are recomputed from those items, overriding whatever the caller sent.
+	*    This blocks "create real line items but claim a tiny total" forgery.
+	*  - **Without line items**, the caller-supplied totals are accepted but the
+	*    `totalAmount === subtotal + taxAmount` arithmetic invariant is enforced.
+	*  - **amountPaid is derived/validated.** When persisted, it is recomputed
+	*    from PaymentAllocations rather than trusted from the caller. It may
+	*    never exceed `totalAmount`.
+	*  - **Whole minor units and non-negativity** are enforced on all four
+	*    amounts. The integer check runs FIRST (#2401), before the
+	*    `totalAmount === subtotal + taxAmount` invariant, so a caller who wrote
+	*    major units gets "money is minor units" rather than a confusing
+	*    arithmetic-mismatch error from float addition.
+	*  - **Status transitions** are validated against the prior persisted status.
+	*/
+	async save() {
+		const { saveInvoice } = await import("./document-money-DNVhDJyC.js").then((n) => n.t);
+		return await saveInvoice(this);
+	}
+	/** @internal Aggregate persistence only. */
+	async saveDerived(capability, options) {
+		if (capability !== DOCUMENT_MONEY_WRITE) throw new Error("Invoice money write capability is required");
+		await claimAllocationParent(this, "invoice");
+		const persisted = await this.isSaved();
+		const prior = await this.resolvePriorStatus(persisted);
+		this.assertAmountsAreMinorUnits();
+		if (options.recomputeLegacy) await this.recomputeAmountsForSave(persisted);
+		else if (persisted && this.id) await this.recomputeAmountPaid();
+		else this.amountPaid = 0;
+		this.assertNonNegativeAmounts();
+		this.assertStatusTransition(prior);
+		this.assertPaymentStatusConsistent();
+		await this.assertDraftDeliveryHistory(persisted);
+		await assertAllocationParent(this, "invoice");
+		const result = await super.save();
+		loadedInvoiceStatus.set(this, this.status);
+		return result;
+	}
+	async delete(options = {}) {
+		const { deleteInvoice } = await import("./document-money-DNVhDJyC.js").then((n) => n.t);
+		await deleteInvoice(this, options);
+	}
+	/** @internal Aggregate persistence only. */
+	async deleteDerived(capability, options = {}) {
+		if (capability !== DOCUMENT_MONEY_WRITE) throw new Error("Invoice money write capability is required");
+		await super.delete(options);
+	}
+	/**
+	* Resolve the AUTHORITATIVE prior status (S5 audit #1390 round 4). The
+	* {@link loadedInvoiceStatus} WeakMap is only populated when {@link initialize}
+	* hydrated the row, so a `create({ id: <existing>, _skipLoad: true })` upsert
+	* yields an instance whose WeakMap entry is missing — trusting it would treat
+	* the write as a brand-new row and skip the transition guard entirely. Read
+	* the persisted row's status directly so a create-onto-existing is correctly
+	* treated as an update. `undefined` means no row exists (genuinely new).
+	*/
+	async resolvePriorStatus(persisted) {
+		if (persisted && this.id) try {
+			const row = await this.db.get(this.tableName, { id: this.id });
+			if (row && row.status != null) return row.status;
+		} catch {}
+		return loadedInvoiceStatus.get(this);
+	}
+	/**
+	* Recompute subtotal/tax/total from line items (when present) and derive
+	* amountPaid from PaymentAllocations. Falls back to the arithmetic invariant
+	* when the invoice has no line items. Tolerant of smrt-ledgers being absent
+	* (the dynamic imports stay inside the package).
+	*/
+	async recomputeAmountsForSave(persisted) {
+		if (persisted && this.id) {
+			const { InvoiceLineItemCollection } = await import("./InvoiceLineItemCollection-CHm9zdqh.js").then((n) => n.n);
+			const lineItems = await (await InvoiceLineItemCollection.create({
+				...this.options,
+				db: this.db
+			})).findByInvoice(this.id);
+			if (lineItems.length > 0) {
+				const subtotal = lineItems.reduce((sum, item) => sum + item.getSubtotal(), 0);
+				const taxAmount = lineItems.reduce((sum, item) => sum + item.getTaxAmount(), 0) + this.providerTaxAmount;
+				const computedTotal = subtotal + taxAmount;
+				this.subtotal = subtotal;
+				this.taxAmount = taxAmount;
+				this.totalAmount = computedTotal;
+			} else this.assertTotalArithmetic();
+			await this.recomputeAmountPaid();
+		} else {
+			this.assertTotalArithmetic();
+			this.amountPaid = 0;
+			if (this.status === InvoiceStatus.PAID || this.status === InvoiceStatus.PARTIAL) throw new Error(`Invoice ${this.invoiceNumber || "<new>"}: a new invoice cannot start in status '${this.status}' \u2014 payment status is derived from PaymentAllocations, not set at creation. Create the invoice unpaid (DRAFT / SENT) and record payments via allocations.`);
+		}
+	}
+	async recomputeAmountPaid() {
+		const { PaymentAllocationCollection } = await import("../index.js").then((n) => n.r);
+		const allocationCollection = await PaymentAllocationCollection.create({
+			...this.options,
+			db: this.db
+		});
+		if (!this.id) throw new Error("Persisted invoice is missing its ID");
+		this.amountPaid = await allocationCollection.getTotalAllocatedToInvoice(this.id);
+	}
+	/**
+	* Whether `amountPaid` covers `totalAmount`. This is the SINGLE source of
+	* truth for the **PAID** decision — both {@link updatePaymentStatus} (which
+	* decides PAID) and {@link assertPaymentStatusConsistent} (which validates
+	* PAID on save) call it, so the PAID-deciding comparison and the
+	* PAID-validating comparison can never drift apart (S5 audit #1390
+	* follow-up).
+	*
+	* With integer minor units this is a plain `>=` (#2401). The float-era
+	* hazard it used to guard against — a total summed from `0.1 × 3` line items
+	* reading as "not covered" by `>=` but "covered" by an epsilon-tolerant
+	* guard, leaving a genuinely-paid invoice unsaveable — cannot arise when both
+	* sides are exact integers. That also removes the documented PAID/PARTIAL
+	* asymmetry: {@link updatePaymentStatus} and {@link isPartiallyPaid} now
+	* agree that any `amountPaid > 0` is a partial payment, because there is no
+	* such thing as sub-cent dust.
+	*/
+	isFullyPaid() {
+		return this.amountPaid + this.creditedAmount >= this.totalAmount;
+	}
+	/**
+	* Whether `amountPaid` is a non-trivial partial payment of `totalAmount`.
+	* Derived from {@link isFullyPaid} so the two stay mutually exclusive.
+	*/
+	isPartiallyPaid() {
+		return this.amountPaid + this.creditedAmount > 0 && !this.isFullyPaid();
+	}
+	/**
+	* After amounts are recomputed and amountPaid is re-derived from allocations,
+	* assert the persisted `status` is consistent with the derived
+	* amountPaid-vs-totalAmount relationship. This blocks the raw
+	* `SENT → PAID with amountPaid=0` flip (and its inverse, claiming PARTIAL/SENT
+	* while fully allocated) that the status-transition map alone permits because
+	* SENT → PAID is a structurally legal edge.
+	*
+	* Only enforced for the payment-derived statuses (PAID / PARTIAL and the
+	* unpaid states DRAFT / SENT / VIEWED). Lifecycle statuses that aren't a
+	* function of amountPaid — OVERDUE, CANCELLED, WRITTEN_OFF — are left
+	* to their own transition rules.
+	*/
+	assertPaymentStatusConsistent() {
+		const label = this.invoiceNumber || this.id || "<new>";
+		const fullyPaid = this.isFullyPaid();
+		const partiallyPaid = this.isPartiallyPaid();
+		if (this.status === InvoiceStatus.DRAFT && this.amountPaid !== 0) throw new Error(`Invoice ${label}: DRAFT requires zero derived payment allocations.`);
+		if (this.status === InvoiceStatus.PAID && !fullyPaid) throw new Error(`Invoice ${label}: status is PAID but derived amountPaid ${this.amountPaid} does not cover totalAmount ${this.totalAmount}. Payment status is derived from PaymentAllocations \u2014 use updatePaymentStatus().`);
+		if (this.status === InvoiceStatus.PARTIAL && !partiallyPaid) throw new Error(`Invoice ${label}: status is PARTIAL but derived amountPaid ${this.amountPaid} is not a partial payment of totalAmount ${this.totalAmount}. Payment status is derived from PaymentAllocations \u2014 use updatePaymentStatus().`);
+		if ((this.status === InvoiceStatus.SENT || this.status === InvoiceStatus.VIEWED) && this.totalAmount > 0 && fullyPaid) throw new Error(`Invoice ${label}: status is '${this.status}' but derived amountPaid ${this.amountPaid} fully covers totalAmount ${this.totalAmount}. Use updatePaymentStatus() so the status reflects the allocations.`);
+	}
+	/** A payment reversal cannot erase an actual delivery event. */
+	async assertDraftDeliveryHistory(persisted) {
+		if (this.status !== InvoiceStatus.DRAFT) return;
+		if (this.sentAt || this.viewedAt) throw new Error("DRAFT requires an undelivered invoice");
+		if (persisted && this.id) {
+			const { InvoiceCollection } = await Promise.resolve().then(() => InvoiceCollection_exports);
+			const prior = await (await InvoiceCollection.create({ db: this.db })).get({ id: this.id }, { cache: false });
+			if (prior?.sentAt || prior?.viewedAt) throw new Error("DRAFT cannot erase persisted invoice delivery history");
+		}
+	}
+	/**
+	* Enforce `totalAmount === subtotal + taxAmount` exactly. Used when the
+	* invoice has no line items to recompute from.
+	*
+	* Exact because every term is integer minor units (#2401). The float era
+	* needed a `0.01` tolerance here and then had to SNAP `totalAmount` to the
+	* recomputed value afterwards, because a total that passed the invoice's
+	* loose tolerance could still fail smrt-ledgers' tighter `BALANCE_EPSILON`
+	* and void the journal `recognizeRevenue` builds from it. Integer arithmetic
+	* removes both halves of that workaround: what the caller supplied either is
+	* the sum or is rejected, and any journal built from it balances exactly.
+	*/
+	assertTotalArithmetic() {
+		const expected = this.subtotal + this.taxAmount;
+		if (this.totalAmount !== expected) throw new Error(`Invoice ${this.invoiceNumber || this.id || "<new>"}: totalAmount ${this.totalAmount} must equal subtotal + taxAmount (${expected}).`);
+	}
+	/**
+	* Reject amounts that are not whole minor units, negative financial values,
+	* and an amountPaid that exceeds the total (overpayment is modelled
+	* elsewhere, not by letting amountPaid float above the invoice total).
+	*/
+	assertAmountsAreMinorUnits() {
+		assertIntegerMinorUnits("Invoice", this.invoiceNumber || this.id || "<new>", [
+			["subtotal", this.subtotal],
+			["taxAmount", this.taxAmount],
+			["providerTaxAmount", this.providerTaxAmount],
+			["totalAmount", this.totalAmount],
+			["amountPaid", this.amountPaid],
+			["creditedAmount", this.creditedAmount]
+		]);
+	}
+	assertNonNegativeAmounts() {
+		const label = this.invoiceNumber || this.id || "<new>";
+		const amounts = [
+			["subtotal", this.subtotal],
+			["taxAmount", this.taxAmount],
+			["providerTaxAmount", this.providerTaxAmount],
+			["totalAmount", this.totalAmount],
+			["amountPaid", this.amountPaid],
+			["creditedAmount", this.creditedAmount]
+		];
+		assertIntegerMinorUnits("Invoice", label, amounts);
+		for (const [field2, value] of amounts) if (value < 0) throw new Error(`Invoice ${label}: ${field2} must be a non-negative number (got ${value}).`);
+		if (this.amountPaid > this.totalAmount) throw new Error(`Invoice ${label}: amountPaid ${this.amountPaid} cannot exceed totalAmount ${this.totalAmount}.`);
+	}
+	/**
+	* Reject an illegal status flip done via raw field assignment. Compares the
+	* about-to-be-written status against the status the row was loaded with.
+	* No-op transitions (status unchanged) and brand-new rows are always allowed.
+	*/
+	assertStatusTransition(prior) {
+		if (prior === void 0) return;
+		if (prior === this.status) return;
+		if (!(INVOICE_STATUS_TRANSITIONS[prior] ?? []).includes(this.status)) throw new Error(`Invoice ${this.invoiceNumber || this.id}: illegal status transition '${prior}' \u2192 '${this.status}'. Use the guarded transition helpers (markSent / markViewed / updatePaymentStatus / cancel / writeOff).`);
+	}
+	/**
+	* Check if invoice is a draft
+	*/
+	isDraft() {
+		return this.status === InvoiceStatus.DRAFT;
+	}
+	/**
+	* Check if invoice has been sent
+	*/
+	isSent() {
+		return this.status === InvoiceStatus.SENT;
+	}
+	/**
+	* Check if invoice is fully paid
+	*/
+	isPaid() {
+		return this.status === InvoiceStatus.PAID;
+	}
+	/**
+	* Check if invoice is partially paid
+	*/
+	isPartial() {
+		return this.status === InvoiceStatus.PARTIAL;
+	}
+	/**
+	* Check if invoice is overdue
+	*/
+	isOverdue() {
+		if (this.status === InvoiceStatus.OVERDUE) return true;
+		if (this.isPaid() || this.status === InvoiceStatus.CANCELLED) return false;
+		return /* @__PURE__ */ new Date() > this.dueDate;
+	}
+	/**
+	* Get remaining amount due
+	*/
+	getAmountDue() {
+		return Math.max(0, this.getBalance());
+	}
+	/** Signed amount still owed after payments and issued credit notes. */
+	getBalance() {
+		return this.totalAmount - this.amountPaid - this.creditedAmount;
+	}
+	/**
+	* Mark invoice as sent
+	*/
+	markSent() {
+		if (this.status === InvoiceStatus.PARTIAL || this.status === InvoiceStatus.PAID) {
+			this.sentAt ??= /* @__PURE__ */ new Date();
+			return;
+		}
+		if (this.status !== InvoiceStatus.DRAFT) throw new Error(`Cannot send invoice with status '${this.status}'. Only draft or payment-progress invoices can be sent.`);
+		this.status = InvoiceStatus.SENT;
+		this.sentAt = /* @__PURE__ */ new Date();
+	}
+	/**
+	* Record that the invoice was viewed by the customer.
+	*
+	* This method is idempotent - calling it multiple times will only
+	* record the first view time. Status only transitions to VIEWED if
+	* the current status is SENT (other statuses like PARTIAL or PAID
+	* are preserved).
+	*/
+	markViewed() {
+		if (this.viewedAt) return;
+		this.viewedAt = /* @__PURE__ */ new Date();
+		if (this.status === InvoiceStatus.SENT) this.status = InvoiceStatus.VIEWED;
+	}
+	/**
+	* Update payment amount and status.
+	*
+	* Called when PaymentAllocations change. Handles both forward transitions
+	* (DRAFT/SENT → PARTIAL → PAID) and reversals (PAID → PARTIAL → original status).
+	*
+	* Terminal statuses (CANCELLED, WRITTEN_OFF) are not modified.
+	*/
+	updatePaymentStatus(amountPaid) {
+		this.amountPaid = amountPaid;
+		if (this.status === InvoiceStatus.CANCELLED || this.status === InvoiceStatus.WRITTEN_OFF) return;
+		if (this.isFullyPaid()) {
+			if (this.status !== InvoiceStatus.PAID || !this.paidDate) this.paidDate = /* @__PURE__ */ new Date();
+			this.status = InvoiceStatus.PAID;
+		} else if (amountPaid + this.creditedAmount > 0) {
+			this.status = InvoiceStatus.PARTIAL;
+			this.paidDate = null;
+		} else {
+			this.paidDate = null;
+			if (this.viewedAt) this.status = InvoiceStatus.VIEWED;
+			else if (this.sentAt) this.status = InvoiceStatus.SENT;
+			else this.status = InvoiceStatus.DRAFT;
+		}
+	}
+	/**
+	* Cancel the invoice
+	*/
+	cancel() {
+		if (this.kind === "invoice" && this.isPaid() || this.kind === "credit_note" && this.amountPaid > 0) throw new Error(`Cannot cancel ${this.kind} with status '${this.status}' and refunded/paid amount ${this.amountPaid}.`);
+		this.status = InvoiceStatus.CANCELLED;
+	}
+	/** Cancel a posted money-v2 invoice with an exact atomic journal reversal. */
+	async cancelWithRevenueReversal(options) {
+		const { cancelInvoiceWithRevenueReversal } = await import("./invoice-posting-BwV8g7z0.js");
+		return cancelInvoiceWithRevenueReversal(this, options);
+	}
+	/**
+	* Write off the invoice (bad debt)
+	*/
+	writeOff() {
+		this.status = InvoiceStatus.WRITTEN_OFF;
+	}
+	/**
+	* Recognize revenue and create AR journal entry.
+	*
+	* Creates a balanced journal entry in smrt-ledgers:
+	* - Debit: Accounts Receivable (assets increase)
+	* - Credit: Revenue (revenue increases)
+	* - Credit: Tax Payable (liability increases, if taxAmount > 0)
+	*
+	* **Note**: This method saves the invoice after setting arJournalId.
+	*
+	* @param options - Account IDs for the journal entry
+	* @returns The created journal
+	*
+	* @example
+	* ```typescript
+	* const journal = await invoice.recognizeRevenue({
+	*   arAccountId: '1120',
+	*   revenueAccountId: '4100',
+	*   taxAccountId: '2130'
+	* });
+	* ```
+	*/
+	async recognizeRevenue(options) {
+		const { recognizeInvoiceRevenueV2 } = await import("./invoice-posting-BwV8g7z0.js");
+		const v2Journal = await recognizeInvoiceRevenueV2(this, options);
+		if (v2Journal) return v2Journal;
+		if (this.arJournalId) throw new Error(`Revenue already recognized for invoice ${this.invoiceNumber} (journal ID: ${this.arJournalId})`);
+		await this.save();
+		if (this.totalAmount <= 0) throw new Error(`Cannot recognize revenue for invoice ${this.invoiceNumber} with non-positive total: ${this.totalAmount}`);
+		if (this.taxAmount > 0 && !options.taxAccountId) throw new Error(`Invoice ${this.invoiceNumber} has taxAmount ${this.taxAmount} but no taxAccountId provided`);
+		const { JournalCollection } = await import("@happyvertical/smrt-ledgers");
+		const journalCollection = await JournalCollection.create(this.options);
+		const entries = [{
+			accountId: options.arAccountId,
+			debit: this.totalAmount,
+			memo: `Invoice ${this.invoiceNumber}`
+		}, {
+			accountId: options.revenueAccountId,
+			credit: this.subtotal,
+			memo: `Invoice ${this.invoiceNumber}`
+		}];
+		if (this.taxAmount > 0 && options.taxAccountId) entries.push({
+			accountId: options.taxAccountId,
+			credit: this.taxAmount,
+			memo: `Tax on Invoice ${this.invoiceNumber}`
+		});
+		const journal = await journalCollection.createWithEntries({
+			description: `Revenue: Invoice ${this.invoiceNumber}`,
+			sourceModule: "smrt-commerce",
+			sourceRef: this.id,
+			entries
+		});
+		await journal.post();
+		if (!journal.id) throw new Error("Invoice.recognizeRevenue: journal was posted but has no id");
+		this.arJournalId = journal.id;
+		try {
+			await this.save();
+		} catch (err) {
+			try {
+				await journal.void(`Reverted: invoice ${this.invoiceNumber} save failed during revenue recognition`);
+			} catch {}
+			this.arJournalId = "";
+			throw err;
+		}
+		return journal;
+	}
+	/**
+	* Get the AR journal entry (if revenue was recognized)
+	*/
+	async getArJournal() {
+		if (!this.arJournalId) return null;
+		try {
+			const { JournalCollection } = await import("@happyvertical/smrt-ledgers");
+			return await (await JournalCollection.create(this.options)).get({ id: this.arJournalId });
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* Convert to InvoiceInput for SDK accounting provider sync.
+	*
+	* Fetches line items and maps all fields to the format expected
+	* by @happyvertical/accounting providers. The SDK takes currency **major**
+	* units (`12.34` USD), so every amount is converted from this package's
+	* integer minor units with the currency's ISO 4217 exponent (#3060).
+	*
+	* @returns InvoiceInput compatible with @happyvertical/accounting
+	*
+	* @example
+	* ```typescript
+	* const provider = await getAccountingProvider({ type: 'quickbooks', ... });
+	* const input = await invoice.toAccountingInput();
+	* const result = await provider.invoices.push(input);
+	* invoice.externalId = result.externalId;
+	* invoice.syncedAt = result.syncedAt;
+	* await invoice.save();
+	* ```
+	*/
+	async toAccountingInput(options) {
+		if (!this.tenantId) return this.toAccountingInputLocked(options, null);
+		const { withTenantMoneyRuntime } = await import("./tenant-money-barrier-DjRXgMnX.js").then((n) => n.r);
+		return withTenantMoneyRuntime(this.db, this.tenantId, "legacy-or-v2", (scope) => this.withDatabase(scope.db, (bound) => bound.toAccountingInputLocked(options, scope.barrier.settings)));
+	}
+	async toAccountingInputLocked(options, settings) {
+		if (settings?.moneyModel === "v2") {
+			if (!options) throw new MoneyValidationError("INVALID_MONEY_INPUT", "Money-v2 accounting conversion requires explicit realm mapping");
+			if (!this.id || !this.tenantId) throw new MoneyValidationError("INVALID_MONEY_INPUT", "Money-v2 accounting conversion requires a persisted tenant invoice");
+			const { toFrozenInvoiceAccountingInput } = await import("../index.js").then((n) => n.n);
+			return toFrozenInvoiceAccountingInput({
+				db: this.db,
+				tenantId: this.tenantId,
+				invoiceId: this.id,
+				mapping: options.mapping
+			});
+		}
+		const { InvoiceLineItemCollection } = await import("./InvoiceLineItemCollection-CHm9zdqh.js").then((n) => n.n);
+		const lineItemCollection = await InvoiceLineItemCollection.create(this.options);
+		if (!this.id) throw new Error("Invoice.toAccountingInput requires a persisted invoice (missing id)");
+		const invoiceId = this.id;
+		const lineItems = await lineItemCollection.findByInvoice(invoiceId);
+		return {
+			id: invoiceId,
+			externalId: this.externalId || void 0,
+			invoiceNumber: this.invoiceNumber,
+			customerId: this.customerId,
+			customerExternalId: this.customerExternalId || void 0,
+			issueDate: this.issueDate,
+			dueDate: this.dueDate,
+			lineItems: lineItems.map((item) => item.toAccountingLineItem(this.currency)),
+			subtotal: minorToMajorUnits(this.subtotal, this.currency),
+			taxAmount: minorToMajorUnits(this.taxAmount, this.currency),
+			totalAmount: minorToMajorUnits(this.totalAmount, this.currency),
+			currency: this.currency,
+			reference: this.reference || void 0,
+			memo: this.customerNotes || void 0
+		};
+	}
+};
+__publicField(Invoice, "__smrtPackage__", "@happyvertical/smrt-commerce");
+__decorateClass([field({ description: "Invoice or customer credit note." })], Invoice.prototype, "kind", 2);
+__decorateClass([foreignKey("Invoice", { nullable: true })], Invoice.prototype, "creditedInvoiceId", 2);
+__decorateClass([tenantId({ nullable: true })], Invoice.prototype, "tenantId", 2);
+__decorateClass([field({ description: "The customer being billed." }), foreignKey("Customer")], Invoice.prototype, "customerId", 2);
+__decorateClass([field({ description: "The order or agreement this invoice bills for, if any." }), foreignKey("SalesContract", { validateSubtype: true })], Invoice.prototype, "contractId", 2);
+__decorateClass([field({ description: "The number printed on the invoice." })], Invoice.prototype, "invoiceNumber", 2);
+__decorateClass([field({ description: "The date the invoice was issued." })], Invoice.prototype, "issueDate", 2);
+__decorateClass([field({ description: "The date payment is expected." })], Invoice.prototype, "dueDate", 2);
+__decorateClass([field({ description: "The date it was paid in full." })], Invoice.prototype, "paidDate", 2);
+__decorateClass([field({
+	description: "The amount before tax.",
+	ui: { format: "money" }
+})], Invoice.prototype, "subtotal", 2);
+__decorateClass([field({
+	description: "The tax charged.",
+	ui: { format: "money" }
+})], Invoice.prototype, "taxAmount", 2);
+__decorateClass([field({ ui: { format: "money" } })], Invoice.prototype, "providerTaxAmount", 2);
+__decorateClass([field({
+	description: "What the customer owes in all, tax included.",
+	ui: { format: "money" }
+})], Invoice.prototype, "totalAmount", 2);
+__decorateClass([field({
+	description: "How much of the total has been paid so far.",
+	ui: { format: "money" }
+})], Invoice.prototype, "amountPaid", 2);
+__decorateClass([field({
+	description: "The currency of the invoice.",
+	ui: { widget: "currency" }
+})], Invoice.prototype, "currency", 2);
+__decorateClass([field({ description: "Where the invoice stands: draft, sent, viewed, paid, overdue or cancelled." })], Invoice.prototype, "status", 2);
+__decorateClass([crossPackageRef("@happyvertical/smrt-ledgers:Journal")], Invoice.prototype, "arJournalId", 2);
+__decorateClass([crossPackageRef("@happyvertical/smrt-ledgers:Journal", { nullable: true })], Invoice.prototype, "arReversalJournalId", 2);
+__decorateClass([crossPackageRef("@happyvertical/smrt-ledgers:Journal")], Invoice.prototype, "revenueJournalId", 2);
+__decorateClass([field({ sensitive: true })], Invoice.prototype, "accountingSyncStateJson", 2);
+__decorateClass([field({
+	description: "Private notes, not shown to the customer.",
+	ui: { widget: "textarea" }
+})], Invoice.prototype, "notes", 2);
+__decorateClass([field({
+	description: "A message shown to the customer on the invoice.",
+	ui: { widget: "textarea" }
+})], Invoice.prototype, "customerNotes", 2);
+__decorateClass([field({
+	description: "The payment conditions, such as Net 30.",
+	ui: { widget: "textarea" }
+})], Invoice.prototype, "terms", 2);
+Invoice = __decorateClass([TenantScoped({ mode: "optional" }), smrt({
+	api: {
+		include: [
+			"list",
+			"get",
+			"create",
+			"update"
+		],
+		writable: [
+			"customerId",
+			"contractId",
+			"invoiceNumber",
+			"reference",
+			"issueDate",
+			"dueDate",
+			"currency",
+			"lineAmountType",
+			"taxRoundingScope",
+			"notes",
+			"customerNotes",
+			"terms",
+			"externalId",
+			"customerExternalId",
+			"externalProvider"
+		]
+	},
+	mcp: {
+		include: ["list", "get"],
+		serializers: { get: {
+			importPath: "@happyvertical/smrt-commerce",
+			exportName: "serializeInvoiceMcpGet"
+		} }
+	},
+	cli: { skipApiCheck: true }
+})], Invoice);
+//#endregion
+//#region src/collections/InvoiceCollection.ts
+var InvoiceCollection_exports = /* @__PURE__ */ __exportAll({
+	InvoiceCollection: () => InvoiceCollection,
+	UNPAID_STATUSES: () => UNPAID_STATUSES
+});
+var UNPAID_STATUSES = [
+	InvoiceStatus.SENT,
+	InvoiceStatus.VIEWED,
+	InvoiceStatus.PARTIAL,
+	InvoiceStatus.OVERDUE
+];
+var InvoiceCollection = class extends SmrtCollection {
+	static _itemClass = Invoice;
+	async withMoneyRead(operation) {
+		const rootDb = this.db;
+		const tenantId = getTenantId();
+		if (!tenantId) return operation();
+		const result = await withTenantMoneyCollectionRead(rootDb, tenantId, (boundDb) => this.withDatabase(boundDb, operation));
+		if (result instanceof Invoice) result.rebindMoneyRead(DOCUMENT_MONEY_READ_REBIND, rootDb);
+		else if (Array.isArray(result)) {
+			for (const item of result) if (item instanceof Invoice) item.rebindMoneyRead(DOCUMENT_MONEY_READ_REBIND, rootDb);
+		}
+		return result;
+	}
+	async get(filter, options = {}) {
+		return this.withMoneyRead(() => super.get(filter, options));
+	}
+	async list(options = {}) {
+		return this.withMoneyRead(() => super.list(options));
+	}
+	/**
+	* Find invoices by customer
+	*
+	* @param customerId - Customer ID
+	* @returns Array of invoices
+	*/
+	async findByCustomer(customerId) {
+		return await this.list({
+			where: { customerId },
+			orderBy: "issueDate DESC"
+		});
+	}
+	/**
+	* Find invoices by contract
+	*
+	* @param contractId - Contract ID
+	* @returns Array of invoices
+	*/
+	async findByContract(contractId) {
+		return await this.list({
+			where: { contractId },
+			orderBy: "issueDate DESC"
+		});
+	}
+	/**
+	* Find invoices by status
+	*
+	* @param status - Invoice status
+	* @returns Array of invoices
+	*/
+	async findByStatus(status) {
+		return await this.list({
+			where: { status },
+			orderBy: "issueDate DESC"
+		});
+	}
+	/**
+	* Find all draft invoices
+	*
+	* @returns Array of draft invoices
+	*/
+	async findDrafts() {
+		return await this.findByStatus(InvoiceStatus.DRAFT);
+	}
+	/**
+	* Find all sent invoices
+	*
+	* @returns Array of sent invoices
+	*/
+	async findSent() {
+		return await this.findByStatus(InvoiceStatus.SENT);
+	}
+	/**
+	* Find all paid invoices
+	*
+	* @returns Array of paid invoices
+	*/
+	async findPaid() {
+		return await this.findByStatus(InvoiceStatus.PAID);
+	}
+	/**
+	* Find all partial invoices
+	*
+	* @returns Array of partially paid invoices
+	*/
+	async findPartial() {
+		return await this.findByStatus(InvoiceStatus.PARTIAL);
+	}
+	/**
+	* Find overdue invoices (past due date, not paid).
+	*
+	* **Note**: This method finds invoices by date, but does not automatically
+	* update their status to OVERDUE. Use a background job or scheduled task
+	* to periodically update invoice statuses based on due dates.
+	*
+	* @returns Array of overdue invoices
+	*/
+	async findOverdue() {
+		const now = (/* @__PURE__ */ new Date()).toISOString();
+		return (await this.list({
+			where: { "dueDate <": now },
+			orderBy: "dueDate ASC"
+		})).filter((inv) => UNPAID_STATUSES.includes(inv.status));
+	}
+	/**
+	* Find invoices in date range (by issue date)
+	*
+	* @param startDate - Start date
+	* @param endDate - End date
+	* @returns Array of invoices
+	*/
+	async findByDateRange(startDate, endDate) {
+		return await this.list({
+			where: {
+				"issueDate >=": startDate.toISOString(),
+				"issueDate <=": endDate.toISOString()
+			},
+			orderBy: "issueDate DESC"
+		});
+	}
+	/**
+	* Find invoice by external ID (from accounting provider)
+	*
+	* @param externalId - External ID
+	* @returns Invoice or null
+	*/
+	async findByExternalId(externalId) {
+		return (await this.list({
+			where: { externalId },
+			limit: 1
+		}))[0] || null;
+	}
+	/**
+	* Find invoices needing sync to external provider
+	* (no externalId or stale syncedAt)
+	*
+	* @returns Array of invoices needing sync
+	*/
+	async findNeedingSync() {
+		return (await this.list({ orderBy: "issueDate DESC" })).filter((inv) => inv.status !== InvoiceStatus.DRAFT && inv.status !== InvoiceStatus.CANCELLED && !inv.externalId);
+	}
+	/**
+	* Find invoice by invoice number
+	*
+	* @param invoiceNumber - Invoice number
+	* @returns Invoice or null
+	*/
+	async findByNumber(invoiceNumber) {
+		return (await this.list({
+			where: { invoiceNumber },
+			limit: 1
+		}))[0] || null;
+	}
+	/**
+	* Count invoices for a given year
+	*
+	* @param year - Year to count
+	* @returns Number of invoices
+	*/
+	async countForYear(year) {
+		const startDate = new Date(year, 0, 1).toISOString();
+		const endDate = new Date(year + 1, 0, 1).toISOString();
+		return (await this.list({ where: {
+			"issueDate >=": startDate,
+			"issueDate <": endDate
+		} })).length;
+	}
+	/**
+	* Generate the next invoice number.
+	*
+	* **Warning**: This method has a potential race condition if multiple
+	* invoices are created concurrently. For high-concurrency environments,
+	* consider using a database sequence or atomic counter instead.
+	*
+	* @param options - Optional configuration for number format
+	* @returns Generated invoice number (e.g., 'INV-2025-0001')
+	*
+	* @example
+	* ```typescript
+	* // Default format: INV-2025-0001
+	* const num = await invoices.generateInvoiceNumber();
+	*
+	* // Custom prefix: BILL-2025-0001
+	* const num = await invoices.generateInvoiceNumber({ prefix: 'BILL' });
+	*
+	* // Simple sequential: INV-000001
+	* const num = await invoices.generateInvoiceNumber({ format: 'prefix-seq' });
+	* ```
+	*/
+	async generateInvoiceNumber(options = {}) {
+		const prefix = options.prefix || "INV";
+		const format = options.format || "prefix-year-seq";
+		const year = (/* @__PURE__ */ new Date()).getFullYear();
+		if (format === "prefix-year-seq") {
+			const count = await this.countForYear(year);
+			return `${prefix}-${year}-${String(count + 1).padStart(4, "0")}`;
+		}
+		const allInvoices = await this.list({});
+		return `${prefix}-${String(allInvoices.length + 1).padStart(6, "0")}`;
+	}
+	/**
+	* Get total outstanding (unpaid) amount for a customer
+	*
+	* @param customerId - Customer ID
+	* @returns Total amount due
+	*/
+	async getTotalOutstandingForCustomer(customerId) {
+		return (await this.list({ where: { customerId } })).filter((inv) => UNPAID_STATUSES.includes(inv.status)).reduce((sum, inv) => sum + inv.getAmountDue(), 0);
+	}
+	/**
+	* Find all invoices belonging to a specific tenant
+	*
+	* @param tenantId - Tenant ID
+	* @returns Array of invoices for the tenant
+	*/
+	async findByTenant(tenantId) {
+		return this.list({ where: { tenantId } });
+	}
+	/**
+	* Find all global invoices (not associated with any tenant).
+	*
+	* Routes through the shared tenant-global helper so it does not throw under
+	* an active tenant context (an explicit `tenant_id IS NULL` filter would be
+	* flagged as an isolation violation). (#1600)
+	*
+	* @returns Array of global invoices
+	*/
+	async findGlobal() {
+		return queryGlobal(this);
+	}
+	/**
+	* Find invoices for a tenant including global invoices.
+	*
+	* Fails closed if an active tenant context requests a different tenant's
+	* rows; the admin/system path keeps the cross-tenant capability. (#1600)
+	*
+	* @param tenantId - Tenant ID
+	* @returns Array of tenant-specific and global invoices
+	*/
+	async findWithGlobals(tenantId) {
+		return queryWithGlobals(this, tenantId, "Invoice.findWithGlobals");
+	}
+};
+//#endregion
+export { Invoice as i, InvoiceCollection_exports as n, UNPAID_STATUSES as r, InvoiceCollection as t };
+
+//# sourceMappingURL=InvoiceCollection-CKQflFjc.js.map