@voyantjs/finance 0.46.0 → 0.47.0

package/README.md

@@ -59,6 +59,20 @@ The event does not include rendered document bodies or signed download URLs.
 Subscriber failures do not roll back the rendition write; use a durable job or
 workflow when a downstream reaction needs retries.
 
+## Customer-Safe Document Lookup
+
+Public finance routes include booking-scoped document lookup for customer
+portal and checkout surfaces:
+
+- `GET /v1/public/finance/bookings/:bookingId/documents`
+- `GET /v1/public/finance/bookings/:bookingId/documents/by-reference?reference=...`
+- `GET /v1/public/finance/documents/by-reference?reference=...`
+
+Booking-scoped routes require a checkout capability for the requested booking.
+The by-reference variant resolves invoice numbers and payment reference numbers
+only inside that booking, so a valid capability for one booking cannot retrieve
+documents from another booking.
+
 ## Exports
 
 | Entry | Description |

package/dist/routes-public.d.ts

@@ -194,6 +194,52 @@ export declare function createPublicFinanceRoutes(options?: PublicFinanceRouteOp
             status: import("hono/utils/http-status").ContentfulStatusCode;
         };
     };
+} & {
+    "/bookings/:bookingId/documents/by-reference": {
+        $get: {
+            input: {
+                param: {
+                    bookingId: string;
+                };
+            };
+            output: {
+                error: string;
+            };
+            outputFormat: "json";
+            status: 404;
+        } | {
+            input: {
+                param: {
+                    bookingId: string;
+                };
+            };
+            output: {
+                data: {
+                    invoiceId: string;
+                    invoiceNumber: string;
+                    invoiceType: "invoice" | "proforma" | "credit_note";
+                    invoiceStatus: "void" | "draft" | "sent" | "partially_paid" | "paid" | "overdue";
+                    currency: string;
+                    totalCents: number;
+                    paidCents: number;
+                    balanceDueCents: number;
+                    issueDate: string;
+                    dueDate: string;
+                    renditionId: string | null;
+                    documentStatus: "pending" | "failed" | "ready" | "stale" | "missing";
+                    format: "json" | "pdf" | "html" | "xml" | null;
+                    language: string | null;
+                    generatedAt: string | null;
+                    fileSize: number | null;
+                    checksum: string | null;
+                    downloadUrl: string | null;
+                    bookingId: string;
+                };
+            };
+            outputFormat: "json";
+            status: import("hono/utils/http-status").ContentfulStatusCode;
+        };
+    };
 } & {
     "/bookings/:bookingId/payments": {
         $get: {
@@ -750,6 +796,52 @@ export declare const publicFinanceRoutes: import("hono/hono-base").HonoBase<Env,
             status: import("hono/utils/http-status").ContentfulStatusCode;
         };
     };
+} & {
+    "/bookings/:bookingId/documents/by-reference": {
+        $get: {
+            input: {
+                param: {
+                    bookingId: string;
+                };
+            };
+            output: {
+                error: string;
+            };
+            outputFormat: "json";
+            status: 404;
+        } | {
+            input: {
+                param: {
+                    bookingId: string;
+                };
+            };
+            output: {
+                data: {
+                    invoiceId: string;
+                    invoiceNumber: string;
+                    invoiceType: "invoice" | "proforma" | "credit_note";
+                    invoiceStatus: "void" | "draft" | "sent" | "partially_paid" | "paid" | "overdue";
+                    currency: string;
+                    totalCents: number;
+                    paidCents: number;
+                    balanceDueCents: number;
+                    issueDate: string;
+                    dueDate: string;
+                    renditionId: string | null;
+                    documentStatus: "pending" | "failed" | "ready" | "stale" | "missing";
+                    format: "json" | "pdf" | "html" | "xml" | null;
+                    language: string | null;
+                    generatedAt: string | null;
+                    fileSize: number | null;
+                    checksum: string | null;
+                    downloadUrl: string | null;
+                    bookingId: string;
+                };
+            };
+            outputFormat: "json";
+            status: import("hono/utils/http-status").ContentfulStatusCode;
+        };
+    };
 } & {
     "/bookings/:bookingId/payments": {
         $get: {

package/dist/routes-public.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routes-public.d.ts","sourceRoot":"","sources":["../src/routes-public.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,KAAK,GAAG,EAA2B,MAAM,oBAAoB,CAAA;AAStE,MAAM,WAAW,yBAAyB;IACxC,0BAA0B,CAAC,EAAE,CAC3B,QAAQ,EAAE,OAAO,EACjB,UAAU,EAAE,MAAM,KACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,MAAM,GAAG,IAAI,CAAA;CAC5C;AA+CD,wBAAgB,yBAAyB,CAAC,OAAO,GAAE,yBAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gDA0IhF;AAED,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+CAA8B,CAAA;AAE9D,MAAM,MAAM,mBAAmB,GAAG,OAAO,mBAAmB,CAAA"}
+{"version":3,"file":"routes-public.d.ts","sourceRoot":"","sources":["../src/routes-public.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,KAAK,GAAG,EAA2B,MAAM,oBAAoB,CAAA;AAStE,MAAM,WAAW,yBAAyB;IACxC,0BAA0B,CAAC,EAAE,CAC3B,QAAQ,EAAE,OAAO,EACjB,UAAU,EAAE,MAAM,KACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,MAAM,GAAG,IAAI,CAAA;CAC5C;AA+CD,wBAAgB,yBAAyB,CAAC,OAAO,GAAE,yBAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gDAwJhF;AAED,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+CAA8B,CAAA;AAE9D,MAAM,MAAM,mBAAmB,GAAG,OAAO,mBAAmB,CAAA"}

package/dist/routes-public.js

@@ -63,6 +63,13 @@ export function createPublicFinanceRoutes(options = {}) {
             resolveDocumentDownloadUrl: (storageKey) => resolveDocumentDownloadUrl(c.env, storageKey),
         });
         return documents ? c.json({ data: documents }) : notFound(c, "Booking documents not found");
+    })
+        .get("/bookings/:bookingId/documents/by-reference", async (c) => {
+        await requireBookingCheckoutCapability(c, c.req.param("bookingId"), "payment:read");
+        const document = await publicFinanceService.getBookingDocumentByReference(c.get("db"), c.req.param("bookingId"), parseQuery(c, publicFinanceDocumentLookupQuerySchema).reference, {
+            resolveDocumentDownloadUrl: (storageKey) => resolveDocumentDownloadUrl(c.env, storageKey),
+        });
+        return document ? c.json({ data: document }) : notFound(c, "Finance document not found");
     })
         .get("/bookings/:bookingId/payments", async (c) => {
         await requireBookingCheckoutCapability(c, c.req.param("bookingId"), "payment:read");

package/dist/service-public.d.ts

@@ -6,6 +6,7 @@ export interface PublicFinanceRuntimeOptions {
 export declare const publicFinanceService: {
     getBookingDocuments(db: PostgresJsDatabase, bookingId: string, runtime?: PublicFinanceRuntimeOptions): Promise<PublicBookingFinanceDocuments | null>;
     getDocumentByReference(db: PostgresJsDatabase, reference: string, runtime?: PublicFinanceRuntimeOptions): Promise<PublicFinanceDocumentLookup | null>;
+    getBookingDocumentByReference(db: PostgresJsDatabase, bookingId: string, reference: string, runtime?: PublicFinanceRuntimeOptions): Promise<PublicFinanceDocumentLookup | null>;
     getBookingPaymentOptions(db: PostgresJsDatabase, bookingId: string, query: PublicPaymentOptionsQuery): Promise<{
         bookingId: string;
         accounts: {

package/dist/service-public.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service-public.d.ts","sourceRoot":"","sources":["../src/service-public.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAYjE,OAAO,KAAK,EACV,6BAA6B,EAC7B,4BAA4B,EAE5B,2BAA2B,EAC3B,yBAAyB,EACzB,8BAA8B,EAC9B,0BAA0B,EAC3B,MAAM,wBAAwB,CAAA;AAE/B,MAAM,WAAW,2BAA2B;IAC1C,0BAA0B,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,MAAM,GAAG,IAAI,CAAA;CAC5F;AA+HD,eAAO,MAAM,oBAAoB;4BAEzB,kBAAkB,aACX,MAAM,YACR,2BAA2B,GACnC,OAAO,CAAC,6BAA6B,GAAG,IAAI,CAAC;+BA6C1C,kBAAkB,aACX,MAAM,YACR,2BAA2B,GACnC,OAAO,CAAC,2BAA2B,GAAG,IAAI,CAAC;iCA0CxC,kBAAkB,aACX,MAAM,SACV,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAoH5B,kBAAkB,aACX,MAAM,GAChB,OAAO,CAAC,4BAA4B,GAAG,IAAI,CAAC;0BA2DnB,kBAAkB,aAAa,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAKnC,kBAAkB,aAAa,MAAM;2CAW7D,kBAAkB,aACX,MAAM,cACL,MAAM,SACX,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;4CA4BjC,kBAAkB,aACX,MAAM,eACJ,MAAM,SACZ,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;mCAuBjC,kBAAkB,aACX,MAAM,SACV,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAMb,kBAAkB,SAAS,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsEhF,CAAA"}
+{"version":3,"file":"service-public.d.ts","sourceRoot":"","sources":["../src/service-public.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAYjE,OAAO,KAAK,EACV,6BAA6B,EAC7B,4BAA4B,EAE5B,2BAA2B,EAC3B,yBAAyB,EACzB,8BAA8B,EAC9B,0BAA0B,EAC3B,MAAM,wBAAwB,CAAA;AAE/B,MAAM,WAAW,2BAA2B;IAC1C,0BAA0B,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,MAAM,GAAG,IAAI,CAAA;CAC5F;AA+HD,eAAO,MAAM,oBAAoB;4BAEzB,kBAAkB,aACX,MAAM,YACR,2BAA2B,GACnC,OAAO,CAAC,6BAA6B,GAAG,IAAI,CAAC;+BA6C1C,kBAAkB,aACX,MAAM,YACR,2BAA2B,GACnC,OAAO,CAAC,2BAA2B,GAAG,IAAI,CAAC;sCA0CxC,kBAAkB,aACX,MAAM,aACN,MAAM,YACR,2BAA2B,GACnC,OAAO,CAAC,2BAA2B,GAAG,IAAI,CAAC;iCA+CxC,kBAAkB,aACX,MAAM,SACV,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAoH5B,kBAAkB,aACX,MAAM,GAChB,OAAO,CAAC,4BAA4B,GAAG,IAAI,CAAC;0BA2DnB,kBAAkB,aAAa,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAKnC,kBAAkB,aAAa,MAAM;2CAW7D,kBAAkB,aACX,MAAM,cACL,MAAM,SACX,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;4CA4BjC,kBAAkB,aACX,MAAM,eACJ,MAAM,SACZ,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;mCAuBjC,kBAAkB,aACX,MAAM,SACV,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAMb,kBAAkB,SAAS,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsEhF,CAAA"}

package/dist/service-public.js

@@ -172,6 +172,46 @@ export const publicFinanceService = {
             ...(await mapInvoiceDocument(invoice, renditions, runtime)),
         };
     },
+    async getBookingDocumentByReference(db, bookingId, reference, runtime = {}) {
+        const [invoiceMatch, paymentMatch] = await Promise.all([
+            db
+                .select()
+                .from(invoices)
+                .where(and(eq(invoices.bookingId, bookingId), eq(invoices.invoiceNumber, reference)))
+                .orderBy(desc(invoices.createdAt))
+                .limit(1),
+            db
+                .select({
+                invoiceId: payments.invoiceId,
+            })
+                .from(payments)
+                .innerJoin(invoices, eq(payments.invoiceId, invoices.id))
+                .where(and(eq(invoices.bookingId, bookingId), eq(payments.referenceNumber, reference)))
+                .orderBy(desc(payments.createdAt))
+                .limit(1),
+        ]);
+        const invoiceId = invoiceMatch[0]?.id ?? paymentMatch[0]?.invoiceId ?? null;
+        if (!invoiceId) {
+            return null;
+        }
+        const [invoice] = await db
+            .select()
+            .from(invoices)
+            .where(and(eq(invoices.id, invoiceId), eq(invoices.bookingId, bookingId)))
+            .limit(1);
+        if (!invoice?.bookingId) {
+            return null;
+        }
+        const renditions = await db
+            .select()
+            .from(invoiceRenditions)
+            .where(eq(invoiceRenditions.invoiceId, invoice.id))
+            .orderBy(desc(invoiceRenditions.createdAt));
+        return {
+            bookingId: invoice.bookingId,
+            ...(await mapInvoiceDocument(invoice, renditions, runtime)),
+        };
+    },
     async getBookingPaymentOptions(db, bookingId, query) {
         const [booking] = await db
             .select({ id: bookings.id })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyantjs/finance",
-  "version": "0.46.0",
+  "version": "0.47.0",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
@@ -39,12 +39,12 @@
     "drizzle-orm": "^0.45.2",
     "hono": "^4.12.10",
     "zod": "^4.3.6",
-    "@voyantjs/bookings": "0.46.0",
-    "@voyantjs/core": "0.46.0",
-    "@voyantjs/db": "0.46.0",
-    "@voyantjs/hono": "0.46.0",
-    "@voyantjs/utils": "0.46.0",
-    "@voyantjs/storage": "0.46.0"
+    "@voyantjs/bookings": "0.47.0",
+    "@voyantjs/core": "0.47.0",
+    "@voyantjs/db": "0.47.0",
+    "@voyantjs/hono": "0.47.0",
+    "@voyantjs/utils": "0.47.0",
+    "@voyantjs/storage": "0.47.0"
   },
   "devDependencies": {
     "typescript": "^6.0.2",