@molecule/api-resource-invoice 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/browser-guard.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser-guard.d.ts.map

package/dist/browser-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}

package/dist/browser-guard.js

@@ -0,0 +1,18 @@
+/**
+ * Browser guard — `@molecule/api-resource-invoice` is SERVER-ONLY.
+ *
+ * Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
+ * Evaluating a server package in a browser bundle is always an import-graph mistake
+ * (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
+ * ("Buffer is not defined") far from the culprit. Throwing here names the package and
+ * the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
+ * unaffected: the throw requires browser globals AND the absence of a node runtime.
+ */
+const g = globalThis;
+if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
+    throw new Error('@molecule/api-resource-invoice is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
+        'from server code (a server route/function or your API), or dynamic-import it inside ' +
+        'the server handler — never from components or shared client modules, and never ' +
+        'polyfill Buffer/process to silence this.');
+}
+export {};

package/dist/index.d.ts

@@ -0,0 +1,75 @@
+/**
+ * `@molecule/api-resource-invoice` — line-item-based invoice CRUD with
+ * auto-computed totals (subtotal + tax), draft/sent/partial/paid/overdue/void
+ * status, and a `recordPayment(invoiceId, userId, amount)` helper that
+ * advances status automatically.
+ *
+ * Extracted from the invoice-billing flagship.
+ *
+ * @example
+ * ```ts
+ * import { createInvoiceRouter } from '@molecule/api-resource-invoice'
+ * app.use('/invoices', createInvoiceRouter())
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { createInvoiceForUser, recordPayment } from '@molecule/api-resource-invoice'
+ *
+ * const inv = await createInvoiceForUser(userId, {
+ *   client_id: 'acme-co',
+ *   items: [{ description: 'Consulting', quantity: 10, unit_price: 250 }],
+ *   tax_rate: 8.5,
+ * })
+ * await recordPayment(inv.id, userId, 2710.00) // marks paid
+ * ```
+ *
+ * @remarks
+ * Table: `src/__setup__/invoices.sql` creates the single `invoices` table. An
+ * mlcl-scaffolded API replays `__setup__/*.sql` automatically on migrate;
+ * anywhere else run it once. The bundled `computeTotals(items, taxRate)`
+ * helper is exported for client-side total previews.
+ *
+ * Everything is owner-scoped: service functions take the authenticated
+ * `userId` and return `null`/`false` for rows the caller doesn't own, and the
+ * router reads the caller from `res.locals.session` (mount behind your global
+ * auth middleware; 401 otherwise). `recordPayment` is bookkeeping — "record a
+ * payment I received" against my own invoice — it never talks to a payment
+ * provider; wire actual charging separately (see `@molecule/api-payments`).
+ *
+ * @e2e
+ * Integration checklist — drive the real UI (live preview, no mocks), adapt
+ * each item to this app's actual screens/flows, and check every box off one
+ * by one. A box you can't check is an integration bug to fix — not a skip:
+ * - [ ] Creating an invoice with line items auto-computes the money: add a
+ *   line (quantity × unit_price) and the subtotal updates, the tax_rate is
+ *   applied (tax_amount = subtotal × rate / 100), and total = subtotal +
+ *   tax_amount — matching `computeTotals` down to the rounded cents shown in
+ *   the UI. Change a quantity or add another line and every figure re-computes.
+ * - [ ] The status lifecycle advances correctly through INVOICE_STATUSES: a
+ *   freshly created invoice reads `draft`; sending it moves it to `sent`; a
+ *   `recordPayment` for LESS than the balance flips it to `partial`; paying the
+ *   remaining balance flips it to `paid` and stamps a paid date. The
+ *   balance-due shown to the user (total - amount_paid) is correct after each
+ *   step.
+ * - [ ] Terminal/edge states read right: an unpaid invoice past its due_date
+ *   shows `overdue`, a cancelled one shows `void`, and once an invoice is `paid`
+ *   or `void` the UI blocks further line-item/total edits as designed.
+ * - [ ] Overpayment and dead-invoice payments are rejected, not silently
+ *   over-applied: recording an amount greater than the outstanding balance, or
+ *   any payment against an already-`paid` or `void` invoice, fails with a
+ *   visible error and leaves amount_paid + status unchanged.
+ * - [ ] AUTHORIZATION: a signed-in user sees and mutates only THEIR OWN
+ *   invoices — every path is `*ForUser`-scoped (listInvoicesForUser /
+ *   getInvoiceForUser / updateInvoiceForUser / recordPayment). Guessing or
+ *   tampering another user's invoice id on GET/PUT/DELETE/:id/payment returns
+ *   403/404 — never that invoice's data and never a cross-user payment.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './routes.js';
+export * from './service.js';
+export * from './types.js';
+export * from './validation.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA"}

package/dist/index.js

@@ -0,0 +1,74 @@
+/**
+ * `@molecule/api-resource-invoice` — line-item-based invoice CRUD with
+ * auto-computed totals (subtotal + tax), draft/sent/partial/paid/overdue/void
+ * status, and a `recordPayment(invoiceId, userId, amount)` helper that
+ * advances status automatically.
+ *
+ * Extracted from the invoice-billing flagship.
+ *
+ * @example
+ * ```ts
+ * import { createInvoiceRouter } from '@molecule/api-resource-invoice'
+ * app.use('/invoices', createInvoiceRouter())
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { createInvoiceForUser, recordPayment } from '@molecule/api-resource-invoice'
+ *
+ * const inv = await createInvoiceForUser(userId, {
+ *   client_id: 'acme-co',
+ *   items: [{ description: 'Consulting', quantity: 10, unit_price: 250 }],
+ *   tax_rate: 8.5,
+ * })
+ * await recordPayment(inv.id, userId, 2710.00) // marks paid
+ * ```
+ *
+ * @remarks
+ * Table: `src/__setup__/invoices.sql` creates the single `invoices` table. An
+ * mlcl-scaffolded API replays `__setup__/*.sql` automatically on migrate;
+ * anywhere else run it once. The bundled `computeTotals(items, taxRate)`
+ * helper is exported for client-side total previews.
+ *
+ * Everything is owner-scoped: service functions take the authenticated
+ * `userId` and return `null`/`false` for rows the caller doesn't own, and the
+ * router reads the caller from `res.locals.session` (mount behind your global
+ * auth middleware; 401 otherwise). `recordPayment` is bookkeeping — "record a
+ * payment I received" against my own invoice — it never talks to a payment
+ * provider; wire actual charging separately (see `@molecule/api-payments`).
+ *
+ * @e2e
+ * Integration checklist — drive the real UI (live preview, no mocks), adapt
+ * each item to this app's actual screens/flows, and check every box off one
+ * by one. A box you can't check is an integration bug to fix — not a skip:
+ * - [ ] Creating an invoice with line items auto-computes the money: add a
+ *   line (quantity × unit_price) and the subtotal updates, the tax_rate is
+ *   applied (tax_amount = subtotal × rate / 100), and total = subtotal +
+ *   tax_amount — matching `computeTotals` down to the rounded cents shown in
+ *   the UI. Change a quantity or add another line and every figure re-computes.
+ * - [ ] The status lifecycle advances correctly through INVOICE_STATUSES: a
+ *   freshly created invoice reads `draft`; sending it moves it to `sent`; a
+ *   `recordPayment` for LESS than the balance flips it to `partial`; paying the
+ *   remaining balance flips it to `paid` and stamps a paid date. The
+ *   balance-due shown to the user (total - amount_paid) is correct after each
+ *   step.
+ * - [ ] Terminal/edge states read right: an unpaid invoice past its due_date
+ *   shows `overdue`, a cancelled one shows `void`, and once an invoice is `paid`
+ *   or `void` the UI blocks further line-item/total edits as designed.
+ * - [ ] Overpayment and dead-invoice payments are rejected, not silently
+ *   over-applied: recording an amount greater than the outstanding balance, or
+ *   any payment against an already-`paid` or `void` invoice, fails with a
+ *   visible error and leaves amount_paid + status unchanged.
+ * - [ ] AUTHORIZATION: a signed-in user sees and mutates only THEIR OWN
+ *   invoices — every path is `*ForUser`-scoped (listInvoicesForUser /
+ *   getInvoiceForUser / updateInvoiceForUser / recordPayment). Guessing or
+ *   tampering another user's invoice id on GET/PUT/DELETE/:id/payment returns
+ *   403/404 — never that invoice's data and never a cross-user payment.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './routes.js';
+export * from './service.js';
+export * from './types.js';
+export * from './validation.js';

package/dist/routes.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Express router for invoices.
+ *
+ * Routes (mounted at e.g. `/invoices`):
+ * - `GET    /`            — list
+ * - `GET    /:id`         — single
+ * - `POST   /`            — create
+ * - `PUT    /:id`         — update (incl. status changes)
+ * - `DELETE /:id`         — delete
+ * - `POST   /:id/payment` — record a payment (auto-promotes status)
+ *
+ * @module
+ */
+import { Router } from 'express';
+/**
+ * Creates and returns an Express router with all CRUD + payment routes for invoices.
+ */
+export declare function createInvoiceRouter(): Router;
+//# sourceMappingURL=routes.d.ts.map

package/dist/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAoD,MAAM,EAAE,MAAM,SAAS,CAAA;AAkBlF;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CA+F5C"}

package/dist/routes.js

@@ -0,0 +1,101 @@
+/**
+ * Express router for invoices.
+ *
+ * Routes (mounted at e.g. `/invoices`):
+ * - `GET    /`            — list
+ * - `GET    /:id`         — single
+ * - `POST   /`            — create
+ * - `PUT    /:id`         — update (incl. status changes)
+ * - `DELETE /:id`         — delete
+ * - `POST   /:id/payment` — record a payment (auto-promotes status)
+ *
+ * @module
+ */
+import { Router } from 'express';
+import { getParamId, requireUser } from '@molecule/api-bonds-default-express';
+import { t } from '@molecule/api-i18n';
+import { validateBody as validateBodyRaw } from '@molecule/api-middleware-validation';
+import { createInvoiceForUser, deleteInvoiceForUser, getInvoiceForUser, listInvoicesForUser, recordPayment, updateInvoiceForUser, } from './service.js';
+import { invoiceCreateSchema, invoiceUpdateSchema, recordPaymentSchema } from './validation.js';
+const validateBody = validateBodyRaw;
+/**
+ * Creates and returns an Express router with all CRUD + payment routes for invoices.
+ */
+export function createInvoiceRouter() {
+    const router = Router();
+    router.get('/', async (req, res) => {
+        const userId = requireUser(res);
+        if (!userId)
+            return;
+        const q = req.query;
+        res.json(await listInvoicesForUser(userId, {
+            client_id: typeof q.client_id === 'string' ? q.client_id : undefined,
+            status: typeof q.status === 'string'
+                ? q.status
+                : undefined,
+            page: typeof q.page === 'string' ? Number(q.page) : undefined,
+            limit: typeof q.limit === 'string' ? Number(q.limit) : undefined,
+        }));
+    });
+    router.get('/:id', async (req, res) => {
+        const userId = requireUser(res);
+        if (!userId)
+            return;
+        const inv = await getInvoiceForUser(getParamId(req), userId);
+        if (!inv) {
+            res
+                .status(404)
+                .json({ error: t('invoice.notFound', undefined, { defaultValue: 'Invoice not found' }) });
+            return;
+        }
+        res.json(inv);
+    });
+    router.post('/', validateBody(invoiceCreateSchema), async (req, res) => {
+        const userId = requireUser(res);
+        if (!userId)
+            return;
+        res
+            .status(201)
+            .json(await createInvoiceForUser(userId, req.body));
+    });
+    router.put('/:id', validateBody(invoiceUpdateSchema), async (req, res) => {
+        const userId = requireUser(res);
+        if (!userId)
+            return;
+        const inv = await updateInvoiceForUser(getParamId(req), userId, req.body);
+        if (!inv) {
+            res
+                .status(404)
+                .json({ error: t('invoice.notFound', undefined, { defaultValue: 'Invoice not found' }) });
+            return;
+        }
+        res.json(inv);
+    });
+    router.delete('/:id', async (req, res) => {
+        const userId = requireUser(res);
+        if (!userId)
+            return;
+        const ok = await deleteInvoiceForUser(getParamId(req), userId);
+        if (!ok) {
+            res
+                .status(404)
+                .json({ error: t('invoice.notFound', undefined, { defaultValue: 'Invoice not found' }) });
+            return;
+        }
+        res.status(204).end();
+    });
+    router.post('/:id/payment', validateBody(recordPaymentSchema), async (req, res) => {
+        const userId = requireUser(res);
+        if (!userId)
+            return;
+        const inv = await recordPayment(getParamId(req), userId, req.body.amount);
+        if (!inv) {
+            res
+                .status(404)
+                .json({ error: t('invoice.notFound', undefined, { defaultValue: 'Invoice not found' }) });
+            return;
+        }
+        res.json(inv);
+    });
+    return router;
+}

package/dist/service.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Invoice service — line-item-based invoicing with totals/tax computation.
+ *
+ * @module
+ */
+import type { Invoice, InvoiceRow, InvoiceStatus, LineItem } from './types.js';
+/** Compute subtotal/tax/total from line items + tax rate (percent 0-100). */
+export declare function computeTotals(items: LineItem[], taxRate: number): {
+    subtotal: number;
+    tax_amount: number;
+    total: number;
+};
+/** Map a raw database InvoiceRow to a normalized Invoice with ISO date strings. */
+export declare function toInvoice(row: InvoiceRow): Invoice;
+/** List all invoices for a user, with optional client/status filters and pagination. */
+export declare function listInvoicesForUser(userId: string, opts?: {
+    client_id?: string;
+    status?: InvoiceStatus;
+    page?: number;
+    limit?: number;
+}): Promise<{
+    data: Invoice[];
+    total: number;
+    page: number;
+    limit: number;
+}>;
+/** Fetch a single invoice by ID, returning null if not found or not owned by the user. */
+export declare function getInvoiceForUser(invoiceId: string, userId: string): Promise<Invoice | null>;
+/** Create a new draft invoice for a user, computing totals from line items and tax rate. */
+export declare function createInvoiceForUser(userId: string, data: {
+    client_id: string;
+    items: LineItem[];
+    due_date?: string;
+    notes?: string;
+    tax_rate?: number;
+    currency?: string;
+}): Promise<Invoice>;
+/** Apply a partial update to a user-owned invoice, recomputing totals and marking paid_at when status becomes paid. */
+export declare function updateInvoiceForUser(invoiceId: string, userId: string, patch: Partial<{
+    items: LineItem[];
+    due_date: string;
+    notes: string;
+    tax_rate: number;
+    currency: string;
+    status: InvoiceStatus;
+}>): Promise<Invoice | null>;
+/** Delete a user-owned invoice by ID, returning false if not found or not owned by the user. */
+export declare function deleteInvoiceForUser(invoiceId: string, userId: string): Promise<boolean>;
+/** Record a payment amount against an invoice, updating amount_paid and transitioning status to partial or paid. */
+export declare function recordPayment(invoiceId: string, userId: string, amount: number): Promise<Invoice | null>;
+//# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAaH,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAS9E,6EAA6E;AAC7E,wBAAgB,aAAa,CAC3B,KAAK,EAAE,QAAQ,EAAE,EACjB,OAAO,EAAE,MAAM,GACd;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAKzD;AAgBD,mFAAmF;AACnF,wBAAgB,SAAS,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAiBlD;AASD,wFAAwF;AACxF,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE;IACJ,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,MAAM,CAAC,EAAE,aAAa,CAAA;IACtB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;CACV,GACL,OAAO,CAAC;IAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAgB1E;AAED,0FAA0F;AAC1F,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAIzB;AAED,4FAA4F;AAC5F,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE;IACJ,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,QAAQ,EAAE,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,GACA,OAAO,CAAC,OAAO,CAAC,CAuBlB;AAED,uHAAuH;AACvH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,QAAQ,EAAE,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,aAAa,CAAA;CACtB,CAAC,GACD,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAuBzB;AAED,gGAAgG;AAChG,wBAAsB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAK9F;AAED,oHAAoH;AACpH,wBAAsB,aAAa,CACjC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAgBzB"}

package/dist/service.js

@@ -0,0 +1,164 @@
+/**
+ * Invoice service — line-item-based invoicing with totals/tax computation.
+ *
+ * @module
+ */
+import { count, create, deleteById, findById, findMany, updateById, } from '@molecule/api-database';
+const TABLE = 'invoices';
+/** Round a number to two decimal places for currency precision. */
+function round2(n) {
+    return Math.round(n * 100) / 100;
+}
+/** Compute subtotal/tax/total from line items + tax rate (percent 0-100). */
+export function computeTotals(items, taxRate) {
+    const subtotal = round2(items.reduce((sum, i) => sum + i.quantity * i.unit_price, 0));
+    const taxAmount = round2(subtotal * (taxRate / 100));
+    const total = round2(subtotal + taxAmount);
+    return { subtotal, tax_amount: taxAmount, total };
+}
+/** Convert a string, Date, or null to an ISO 8601 string, or null if absent. */
+function toIso(value) {
+    if (!value)
+        return null;
+    if (value instanceof Date)
+        return value.toISOString();
+    return String(value);
+}
+/** Convert a string, Date, or null to a YYYY-MM-DD date string, or null if absent. */
+function toDateString(value) {
+    const iso = toIso(value);
+    if (!iso)
+        return null;
+    return iso.length >= 10 ? iso.slice(0, 10) : iso;
+}
+/** Map a raw database InvoiceRow to a normalized Invoice with ISO date strings. */
+export function toInvoice(row) {
+    return {
+        ...row,
+        // pg returns `numeric` columns as strings (precision guard); the Invoice
+        // contract and every downstream math site expect numbers. Coerce here so
+        // comparisons ("paid >= total") and JSON responses are numeric.
+        subtotal: Number(row.subtotal),
+        tax_rate: Number(row.tax_rate),
+        tax_amount: Number(row.tax_amount),
+        total: Number(row.total),
+        amount_paid: Number(row.amount_paid),
+        issue_date: toDateString(row.issue_date) ?? '',
+        due_date: toDateString(row.due_date),
+        paid_at: toIso(row.paid_at),
+        created_at: toIso(row.created_at) ?? '',
+        updated_at: toIso(row.updated_at) ?? '',
+    };
+}
+/** Generate an invoice number like INV-2026-0001 for a user's next invoice. */
+async function nextInvoiceNumber(userId) {
+    const year = new Date().getFullYear();
+    const existing = await count(TABLE, [{ field: 'user_id', operator: '=', value: userId }]);
+    return `INV-${year}-${String(existing + 1).padStart(4, '0')}`;
+}
+/** List all invoices for a user, with optional client/status filters and pagination. */
+export async function listInvoicesForUser(userId, opts = {}) {
+    const page = opts.page ?? 1;
+    const limit = opts.limit ?? 50;
+    const where = [{ field: 'user_id', operator: '=', value: userId }];
+    if (opts.client_id)
+        where.push({ field: 'client_id', operator: '=', value: opts.client_id });
+    if (opts.status)
+        where.push({ field: 'status', operator: '=', value: opts.status });
+    const orderBy = [
+        { field: 'issue_date', direction: 'desc' },
+        { field: 'created_at', direction: 'desc' },
+    ];
+    const offset = (page - 1) * limit;
+    const [rows, total] = await Promise.all([
+        findMany(TABLE, { where, orderBy, limit, offset }),
+        count(TABLE, where),
+    ]);
+    return { data: rows.map(toInvoice), total, page, limit };
+}
+/** Fetch a single invoice by ID, returning null if not found or not owned by the user. */
+export async function getInvoiceForUser(invoiceId, userId) {
+    const row = await findById(TABLE, invoiceId);
+    if (!row || row.user_id !== userId)
+        return null;
+    return toInvoice(row);
+}
+/** Create a new draft invoice for a user, computing totals from line items and tax rate. */
+export async function createInvoiceForUser(userId, data) {
+    const taxRate = data.tax_rate ?? 0;
+    const totals = computeTotals(data.items, taxRate);
+    const number = await nextInvoiceNumber(userId);
+    const today = new Date().toISOString().slice(0, 10);
+    const result = await create(TABLE, {
+        user_id: userId,
+        client_id: data.client_id,
+        number,
+        status: 'draft',
+        items: data.items,
+        subtotal: totals.subtotal,
+        tax_rate: taxRate,
+        tax_amount: totals.tax_amount,
+        total: totals.total,
+        amount_paid: 0,
+        currency: data.currency ?? 'USD',
+        issue_date: today,
+        due_date: data.due_date ?? null,
+        paid_at: null,
+        notes: data.notes ?? null,
+    });
+    return toInvoice(result.data);
+}
+/** Apply a partial update to a user-owned invoice, recomputing totals and marking paid_at when status becomes paid. */
+export async function updateInvoiceForUser(invoiceId, userId, patch) {
+    const existing = await findById(TABLE, invoiceId);
+    if (!existing || existing.user_id !== userId)
+        return null;
+    const updates = { ...patch };
+    if (patch.items || patch.tax_rate !== undefined) {
+        const items = patch.items ?? existing.items;
+        // pg numerics arrive as strings — the ?? fallback must be numeric before
+        // it reaches computeTotals' multiplication.
+        const taxRate = patch.tax_rate ?? Number(existing.tax_rate);
+        const totals = computeTotals(items, taxRate);
+        updates.subtotal = totals.subtotal;
+        updates.tax_amount = totals.tax_amount;
+        updates.total = totals.total;
+    }
+    if (patch.status === 'paid' && existing.status !== 'paid') {
+        updates.paid_at = new Date().toISOString();
+        updates.amount_paid = patch.items
+            ? computeTotals(patch.items, patch.tax_rate ?? existing.tax_rate).total
+            : existing.total;
+    }
+    await updateById(TABLE, invoiceId, updates);
+    const next = await findById(TABLE, invoiceId);
+    return next ? toInvoice(next) : null;
+}
+/** Delete a user-owned invoice by ID, returning false if not found or not owned by the user. */
+export async function deleteInvoiceForUser(invoiceId, userId) {
+    const row = await findById(TABLE, invoiceId);
+    if (!row || row.user_id !== userId)
+        return false;
+    await deleteById(TABLE, invoiceId);
+    return true;
+}
+/** Record a payment amount against an invoice, updating amount_paid and transitioning status to partial or paid. */
+export async function recordPayment(invoiceId, userId, amount) {
+    const existing = await findById(TABLE, invoiceId);
+    if (!existing || existing.user_id !== userId)
+        return null;
+    // pg numerics arrive as strings — coerce before arithmetic or the addition
+    // string-concats ("0.00" + 42000 → "0.0042000") and the paid check compares
+    // strings lexicographically.
+    const newPaid = round2(Number(existing.amount_paid) + amount);
+    const isFullyPaid = newPaid >= Number(existing.total);
+    const updates = {
+        amount_paid: newPaid,
+        status: isFullyPaid ? 'paid' : 'partial',
+    };
+    if (isFullyPaid)
+        updates.paid_at = new Date().toISOString();
+    await updateById(TABLE, invoiceId, updates);
+    const next = await findById(TABLE, invoiceId);
+    return next ? toInvoice(next) : null;
+}

package/dist/types.d.ts

@@ -0,0 +1,38 @@
+/** Lifecycle states an invoice can be in, from initial draft through payment or cancellation. */
+export type InvoiceStatus = 'draft' | 'sent' | 'partial' | 'paid' | 'overdue' | 'void';
+/** A single billable line on an invoice, with description, quantity, and unit price. */
+export interface LineItem {
+    description: string;
+    quantity: number;
+    unit_price: number;
+}
+/** Raw database row shape for an invoice, with date fields typed as string or Date. */
+export interface InvoiceRow {
+    id: string;
+    user_id: string;
+    client_id: string;
+    number: string;
+    status: InvoiceStatus;
+    items: LineItem[];
+    subtotal: number;
+    tax_rate: number;
+    tax_amount: number;
+    total: number;
+    amount_paid: number;
+    currency: string;
+    issue_date: string | Date;
+    due_date: string | Date | null;
+    paid_at: string | Date | null;
+    notes: string | null;
+    created_at: string | Date;
+    updated_at: string | Date;
+}
+/** Normalized invoice with all date fields serialized to ISO strings for API responses. */
+export interface Invoice extends Omit<InvoiceRow, 'issue_date' | 'due_date' | 'paid_at' | 'created_at' | 'updated_at'> {
+    issue_date: string;
+    due_date: string | null;
+    paid_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAA;AAEtF,wFAAwF;AACxF,MAAM,WAAW,QAAQ;IACvB,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,uFAAuF;AACvF,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAA;IACV,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,aAAa,CAAA;IACrB,KAAK,EAAE,QAAQ,EAAE,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;IAC9B,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;IAC7B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B;AAED,2FAA2F;AAC3F,MAAM,WAAW,OAAQ,SAAQ,IAAI,CACnC,UAAU,EACV,YAAY,GAAG,UAAU,GAAG,SAAS,GAAG,YAAY,GAAG,YAAY,CACpE;IACC,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;CACnB"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/validation.d.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+/** All valid lifecycle statuses an invoice can hold. */
+export declare const INVOICE_STATUSES: readonly ["draft", "sent", "partial", "paid", "overdue", "void"];
+/** Zod schema for a single invoice line item (description, quantity, unit price). */
+export declare const lineItemSchema: z.ZodObject<{
+    description: z.ZodString;
+    quantity: z.ZodNumber;
+    unit_price: z.ZodNumber;
+}, z.core.$strip>;
+/** Zod schema for creating a new invoice (client, items, optional due date / notes / tax / currency). */
+export declare const invoiceCreateSchema: z.ZodObject<{
+    client_id: z.ZodString;
+    items: z.ZodArray<z.ZodObject<{
+        description: z.ZodString;
+        quantity: z.ZodNumber;
+        unit_price: z.ZodNumber;
+    }, z.core.$strip>>;
+    due_date: z.ZodOptional<z.ZodString>;
+    notes: z.ZodOptional<z.ZodString>;
+    tax_rate: z.ZodOptional<z.ZodNumber>;
+    currency: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Zod schema for partially updating an existing invoice (all fields optional). */
+export declare const invoiceUpdateSchema: z.ZodObject<{
+    items: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        description: z.ZodString;
+        quantity: z.ZodNumber;
+        unit_price: z.ZodNumber;
+    }, z.core.$strip>>>;
+    due_date: z.ZodOptional<z.ZodString>;
+    notes: z.ZodOptional<z.ZodString>;
+    tax_rate: z.ZodOptional<z.ZodNumber>;
+    currency: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        draft: "draft";
+        sent: "sent";
+        partial: "partial";
+        paid: "paid";
+        overdue: "overdue";
+        void: "void";
+    }>>;
+}, z.core.$strip>;
+/** Zod schema for recording a payment against an invoice (positive amount required). */
+export declare const recordPaymentSchema: z.ZodObject<{
+    amount: z.ZodNumber;
+}, z.core.$strip>;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,wDAAwD;AACxD,eAAO,MAAM,gBAAgB,kEAAmE,CAAA;AAEhG,qFAAqF;AACrF,eAAO,MAAM,cAAc;;;;iBAIzB,CAAA;AAEF,yGAAyG;AACzG,eAAO,MAAM,mBAAmB;;;;;;;;;;;iBAO9B,CAAA;AAEF,mFAAmF;AACnF,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;iBAO9B,CAAA;AAEF,wFAAwF;AACxF,eAAO,MAAM,mBAAmB;;iBAE9B,CAAA"}

package/dist/validation.js

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+/** All valid lifecycle statuses an invoice can hold. */
+export const INVOICE_STATUSES = ['draft', 'sent', 'partial', 'paid', 'overdue', 'void'];
+/** Zod schema for a single invoice line item (description, quantity, unit price). */
+export const lineItemSchema = z.object({
+    description: z.string().min(1),
+    quantity: z.number().positive(),
+    unit_price: z.number().nonnegative(),
+});
+/** Zod schema for creating a new invoice (client, items, optional due date / notes / tax / currency). */
+export const invoiceCreateSchema = z.object({
+    client_id: z.string().min(1),
+    items: z.array(lineItemSchema).min(1),
+    due_date: z.string().optional(),
+    notes: z.string().optional(),
+    tax_rate: z.number().min(0).max(100).optional(),
+    currency: z.string().min(3).max(8).optional(),
+});
+/** Zod schema for partially updating an existing invoice (all fields optional). */
+export const invoiceUpdateSchema = z.object({
+    items: z.array(lineItemSchema).optional(),
+    due_date: z.string().optional(),
+    notes: z.string().optional(),
+    tax_rate: z.number().min(0).max(100).optional(),
+    currency: z.string().min(3).max(8).optional(),
+    status: z.enum(INVOICE_STATUSES).optional(),
+});
+/** Zod schema for recording a payment against an invoice (positive amount required). */
+export const recordPaymentSchema = z.object({
+    amount: z.number().positive(),
+});

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@molecule/api-resource-invoice",
+  "version": "1.0.0",
+  "description": "Invoice CRUD + line items + draft/sent/paid/overdue status. Extracted from invoice-billing flagship.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "molecule",
+    "invoice",
+    "billing",
+    "resource"
+  ],
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/express": "5.0.6",
+    "@types/node": "26.1.2",
+    "express": "5.2.1",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10",
+    "zod": "4.4.3"
+  },
+  "peerDependencies": {
+    "@molecule/api-bonds-default-express": "^1.0.0",
+    "@molecule/api-database": "^1.0.0",
+    "@molecule/api-i18n": "^1.0.0",
+    "@molecule/api-middleware-validation": "^1.0.0",
+    "express": "^5.0.0",
+    "zod": "^4.0.0"
+  }
+}