@voyantjs/plugin-smartbill 0.77.6 → 0.77.11

package/dist/artifacts.d.ts

@@ -31,6 +31,14 @@ export interface PersistSmartbillInvoiceArtifactInput {
     body: SmartbillInvoiceBody;
     result: SmartbillInvoiceResponse;
 }
+export interface RecordSmartbillInvoiceArtifactFailureInput {
+    runtime: SmartbillArtifactPersistenceRuntime;
+    event: VoyantInvoiceEvent;
+    documentType: SmartbillDocumentType;
+    body: SmartbillInvoiceBody;
+    result: SmartbillInvoiceResponse;
+    error: unknown;
+}
 export type SmartbillExternalRef = Pick<InvoiceExternalRef, "id" | "invoiceId" | "externalId" | "externalNumber" | "externalUrl" | "metadata">;
 export interface RetrySmartbillInvoiceArtifactInput {
     runtime: SmartbillArtifactPersistenceRuntime;
@@ -40,6 +48,17 @@ export interface RetrySmartbillInvoiceArtifactInput {
 }
 type InvoiceAttachmentRecord = Awaited<ReturnType<typeof financeService.createInvoiceAttachment>>;
 type InvoiceRenditionRecord = Awaited<ReturnType<typeof financeService.createInvoiceRendition>>;
+export type SmartbillPdfPersistStage = "attachment_lookup" | "viewInvoicePdf" | "viewEstimatePdf" | "storage_upload" | "rendition_insert" | "attachment_insert" | "unknown";
+export declare class SmartbillPdfPersistError extends Error {
+    readonly stage: SmartbillPdfPersistStage;
+    readonly originalError: unknown;
+    constructor(stage: SmartbillPdfPersistStage, error: unknown);
+}
+export declare class SmartbillPdfPersistMetadataUpdateError extends Error {
+    readonly originalError: unknown;
+    constructor(error: unknown);
+}
+export declare function isSmartbillPdfPersistMetadataUpdateError(error: unknown): error is SmartbillPdfPersistMetadataUpdateError;
 export type SmartbillArtifactPersistenceResult = {
     status: "skipped";
     reason: "missing_db" | "missing_invoice" | "missing_document_storage" | "missing_smartbill_reference";
@@ -55,6 +74,7 @@ export type SmartbillArtifactPersistenceResult = {
     attachment: InvoiceAttachmentRecord;
 };
 export declare function persistSmartbillInvoiceArtifact({ runtime, client, event, documentType, body, result, }: PersistSmartbillInvoiceArtifactInput): Promise<SmartbillArtifactPersistenceResult>;
+export declare function recordSmartbillInvoiceArtifactFailure({ runtime, event, documentType, body, result, error, }: RecordSmartbillInvoiceArtifactFailureInput): Promise<SmartbillArtifactPersistenceResult>;
 export declare function retrySmartbillInvoiceArtifact({ runtime, client, externalRef, documentType, }: RetrySmartbillInvoiceArtifactInput): Promise<SmartbillArtifactPersistenceResult>;
 export {};
 //# sourceMappingURL=artifacts.d.ts.map

package/dist/artifacts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../src/artifacts.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../src/artifacts.ts"],"names":[],"mappings":"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"}

package/dist/artifacts.js

@@ -1,4 +1,25 @@
 import { financeService } from "@voyantjs/finance";
+export class SmartbillPdfPersistError extends Error {
+    stage;
+    originalError;
+    constructor(stage, error) {
+        super(`SmartBill PDF persist failed at ${stage}: ${errorMessage(error)}`);
+        this.name = "SmartbillPdfPersistError";
+        this.stage = stage;
+        this.originalError = error;
+    }
+}
+export class SmartbillPdfPersistMetadataUpdateError extends Error {
+    originalError;
+    constructor(error) {
+        super(`SmartBill PDF persist metadata update failed: ${errorMessage(error)}`);
+        this.name = "SmartbillPdfPersistMetadataUpdateError";
+        this.originalError = error;
+    }
+}
+export function isSmartbillPdfPersistMetadataUpdateError(error) {
+    return error instanceof SmartbillPdfPersistMetadataUpdateError;
+}
 const SMARTBILL_ATTACHMENT_KIND = "smartbill_pdf";
 function isResolver(value) {
     return typeof value === "function";
@@ -32,16 +53,37 @@ function metadataString(metadata, key) {
     const value = metadata?.[key];
     return typeof value === "string" && value.length > 0 ? value : null;
 }
-export async function persistSmartbillInvoiceArtifact({ runtime, client, event, documentType, body, result, }) {
-    if (!runtime.db)
-        return { status: "skipped", reason: "missing_db" };
-    const context = { event, documentType, body, result };
-    const db = await resolveMaybe(runtime.db, context);
-    if (!db)
-        return { status: "skipped", reason: "missing_db" };
-    const seriesName = result.series ?? body.seriesName;
+function errorMessage(error) {
+    if (error instanceof SmartbillPdfPersistError)
+        return errorMessage(error.originalError);
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+function errorStage(error) {
+    return error instanceof SmartbillPdfPersistError ? error.stage : "unknown";
+}
+async function withPdfPersistStage(stage, operation) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        throw new SmartbillPdfPersistError(stage, error);
+    }
+}
+function buildSmartbillExternalRefMetadata({ body, result, documentType, extra, }) {
+    return {
+        companyVatCode: body.companyVatCode,
+        seriesName: body.seriesName,
+        series: result.series ?? body.seriesName,
+        number: result.number ?? null,
+        documentType,
+        ...extra,
+    };
+}
+async function registerSmartbillExternalRef(db, invoiceId, body, result, documentType, metadataExtra) {
     const number = result.number;
-    const externalRef = await financeService.registerInvoiceExternalRef(db, event.id, {
+    return financeService.registerInvoiceExternalRef(db, invoiceId, {
         provider: "smartbill",
         externalId: number ?? null,
         externalNumber: number ?? null,
@@ -49,14 +91,39 @@ export async function persistSmartbillInvoiceArtifact({ runtime, client, event,
         status: result.errorText ? "error" : "issued",
         syncedAt: new Date().toISOString(),
         syncError: result.errorText ?? null,
-        metadata: {
-            companyVatCode: body.companyVatCode,
-            seriesName: body.seriesName,
-            series: seriesName,
-            number: number ?? null,
+        metadata: buildSmartbillExternalRefMetadata({
+            body,
+            result,
             documentType,
-        },
+            extra: metadataExtra,
+        }),
     });
+}
+async function recordSmartbillInvoiceArtifactReady(db, invoiceId, body, result, documentType, storageKey, existingMetadata) {
+    try {
+        await registerSmartbillExternalRef(db, invoiceId, body, result, documentType, {
+            ...(existingMetadata ?? {}),
+            pdfPersistStatus: "ready",
+            pdfPersistedAt: new Date().toISOString(),
+            pdfStorageKey: storageKey,
+            pdfPersistError: null,
+            pdfPersistStage: null,
+        });
+    }
+    catch (error) {
+        throw new SmartbillPdfPersistMetadataUpdateError(error);
+    }
+}
+export async function persistSmartbillInvoiceArtifact({ runtime, client, event, documentType, body, result, }) {
+    if (!runtime.db)
+        return { status: "skipped", reason: "missing_db" };
+    const context = { event, documentType, body, result };
+    const db = await resolveMaybe(runtime.db, context);
+    if (!db)
+        return { status: "skipped", reason: "missing_db" };
+    const seriesName = result.series ?? body.seriesName;
+    const number = result.number;
+    const externalRef = await registerSmartbillExternalRef(db, event.id, body, result, documentType);
     if (!externalRef)
         return { status: "skipped", reason: "missing_invoice" };
     const storage = await resolveMaybe(runtime.documentStorage, context);
@@ -65,7 +132,7 @@ export async function persistSmartbillInvoiceArtifact({ runtime, client, event,
     if (!number)
         return { status: "registered_ref", reason: "missing_number" };
     const keyPrefix = await resolveMaybe(runtime.documentStorageKeyPrefix, context);
-    return persistSmartbillPdfArtifact({
+    const persisted = await persistSmartbillPdfArtifact({
         db,
         storage,
         client,
@@ -77,6 +144,27 @@ export async function persistSmartbillInvoiceArtifact({ runtime, client, event,
         language: body.language ?? null,
         keyPrefix,
     });
+    if (persisted.status === "persisted" || persisted.status === "already_exists") {
+        await recordSmartbillInvoiceArtifactReady(db, event.id, body, result, documentType, persisted.attachment?.storageKey ?? null);
+    }
+    return persisted;
+}
+export async function recordSmartbillInvoiceArtifactFailure({ runtime, event, documentType, body, result, error, }) {
+    if (!runtime.db)
+        return { status: "skipped", reason: "missing_db" };
+    const context = { event, documentType, body, result };
+    const db = await resolveMaybe(runtime.db, context);
+    if (!db)
+        return { status: "skipped", reason: "missing_db" };
+    const externalRef = await registerSmartbillExternalRef(db, event.id, body, result, documentType, {
+        pdfPersistStatus: "failed",
+        pdfPersistError: errorMessage(error),
+        pdfPersistStage: errorStage(error),
+        pdfPersistedAt: null,
+    });
+    if (!externalRef)
+        return { status: "skipped", reason: "missing_invoice" };
+    return { status: "registered_ref" };
 }
 export async function retrySmartbillInvoiceArtifact({ runtime, client, externalRef, documentType, }) {
     if (!runtime.db)
@@ -115,34 +203,52 @@ export async function retrySmartbillInvoiceArtifact({ runtime, client, externalR
     if (!storage)
         return { status: "skipped", reason: "missing_document_storage" };
     const keyPrefix = await resolveMaybe(runtime.documentStorageKeyPrefix, context);
-    return persistSmartbillPdfArtifact({
-        db,
-        storage,
-        client,
-        invoiceId: externalRef.invoiceId,
-        documentType,
-        companyVatCode,
-        seriesName,
-        number,
-        language: metadataString(metadata, "language"),
-        keyPrefix,
-    });
+    const result = context.result;
+    let persisted;
+    try {
+        persisted = await persistSmartbillPdfArtifact({
+            db,
+            storage,
+            client,
+            invoiceId: externalRef.invoiceId,
+            documentType,
+            companyVatCode,
+            seriesName,
+            number,
+            language: metadataString(metadata, "language"),
+            keyPrefix,
+        });
+    }
+    catch (error) {
+        await registerSmartbillExternalRef(db, externalRef.invoiceId, context.body, result, documentType, {
+            ...(metadata ?? {}),
+            pdfPersistStatus: "failed",
+            pdfPersistError: errorMessage(error),
+            pdfPersistStage: errorStage(error),
+            pdfPersistedAt: null,
+        });
+        throw error;
+    }
+    if (persisted.status === "persisted" || persisted.status === "already_exists") {
+        await recordSmartbillInvoiceArtifactReady(db, externalRef.invoiceId, context.body, result, documentType, persisted.attachment?.storageKey ?? null, metadata);
+    }
+    return persisted;
 }
 async function persistSmartbillPdfArtifact({ db, storage, client, invoiceId, documentType, companyVatCode, seriesName, number, language, keyPrefix, }) {
-    const existingAttachments = await financeService.listInvoiceAttachments(db, invoiceId);
+    const existingAttachments = await withPdfPersistStage("attachment_lookup", () => financeService.listInvoiceAttachments(db, invoiceId));
     const existingSmartbillAttachment = existingAttachments.find((attachment) => attachment.kind === SMARTBILL_ATTACHMENT_KIND);
     if (existingSmartbillAttachment) {
         return { status: "already_exists", attachment: existingSmartbillAttachment };
     }
     const pdf = documentType === "proforma"
-        ? await client.viewEstimatePdf(companyVatCode, seriesName, number)
-        : await client.viewInvoicePdf(companyVatCode, seriesName, number);
+        ? await withPdfPersistStage("viewEstimatePdf", () => client.viewEstimatePdf(companyVatCode, seriesName, number))
+        : await withPdfPersistStage("viewInvoicePdf", () => client.viewInvoicePdf(companyVatCode, seriesName, number));
     const defaultPrefix = `invoices/${invoiceId}/smartbill`;
     const resolvedKeyPrefix = keyPrefix ?? defaultPrefix;
     const key = `${resolvedKeyPrefix.replace(/\/$/, "")}/${documentType}-${sanitizeKeyPart(seriesName)}-${sanitizeKeyPart(number)}.pdf`;
     const contentType = pdf.contentType || "application/pdf";
     const checksum = await sha256(pdf.bytes);
-    const uploaded = await storage.upload(pdf.bytes, {
+    const uploaded = await withPdfPersistStage("storage_upload", () => storage.upload(pdf.bytes, {
         key,
         contentType,
         metadata: {
@@ -152,7 +258,7 @@ async function persistSmartbillPdfArtifact({ db, storage, client, invoiceId, doc
             seriesName,
             number,
         },
-    });
+    }));
     const commonMetadata = {
         provider: "smartbill",
         documentType,
@@ -162,7 +268,7 @@ async function persistSmartbillPdfArtifact({ db, storage, client, invoiceId, doc
         storageProvider: storage.name,
         ...(uploaded.url ? { url: uploaded.url } : {}),
     };
-    const rendition = await financeService.createInvoiceRendition(db, invoiceId, {
+    const rendition = await withPdfPersistStage("rendition_insert", () => financeService.createInvoiceRendition(db, invoiceId, {
         format: "pdf",
         status: "ready",
         storageKey: uploaded.key,
@@ -171,8 +277,8 @@ async function persistSmartbillPdfArtifact({ db, storage, client, invoiceId, doc
         language: language ?? null,
         generatedAt: new Date().toISOString(),
         metadata: commonMetadata,
-    });
-    const attachment = await financeService.createInvoiceAttachment(db, invoiceId, {
+    }));
+    const attachment = await withPdfPersistStage("attachment_insert", () => financeService.createInvoiceAttachment(db, invoiceId, {
         kind: SMARTBILL_ATTACHMENT_KIND,
         name: smartbillAttachmentName(documentType, seriesName, number),
         mimeType: contentType,
@@ -183,6 +289,6 @@ async function persistSmartbillPdfArtifact({ db, storage, client, invoiceId, doc
             ...commonMetadata,
             renditionId: rendition?.id ?? null,
         },
-    });
+    }));
     return { status: "persisted", rendition, attachment };
 }

package/dist/client.js

@@ -46,7 +46,7 @@ export function createSmartbillClient(options) {
         }
         const response = await fetchImpl(`${apiUrl}${path}`, {
             method: "GET",
-            headers: { ...headers(), Accept: "application/pdf" },
+            headers: { ...headers(), Accept: "application/octet-stream" },
         });
         if (!response.ok) {
             const text = await response.text().catch(() => "");

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export type { SmartbillEventValue, SmartbillMappingOptions, SmartbillMaybePromis
 export { mapClient, mapLineItems, mapVoyantInvoiceToSmartbill, mapVoyantInvoiceToSmartbillAsync, } from "./mapping.js";
 export type { SmartbillMockDocument, SmartbillMockDocumentKind, SmartbillMockDocumentStatus, SmartbillMockListenOptions, SmartbillMockRequest, SmartbillMockResponse, SmartbillMockSeries, SmartbillMockServer, SmartbillMockServerHandle, SmartbillMockServerOptions, SmartbillMockTax, } from "./mock.js";
 export { createSmartbillMockServer } from "./mock.js";
-export type { SmartbillErrorHandler, SmartbillIdempotencyOptions, SmartbillLogger, SmartbillMapFn, SmartbillPluginOptions, SmartbillSyncEventNames, } from "./plugin.js";
+export type { SmartbillErrorHandler, SmartbillIdempotencyOptions, SmartbillInvoiceNumberWriteBackFormatter, SmartbillLogger, SmartbillMapFn, SmartbillPluginOptions, SmartbillSyncEventNames, } from "./plugin.js";
 export { smartbillPlugin } from "./plugin.js";
 export type { ResolvedSmartbillSyncEventNames, SmartbillSyncRuntime } from "./runtime.js";
 export { createSmartbillSyncRuntime } from "./runtime.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,kCAAkC,EAClC,mCAAmC,EACnC,kCAAkC,EAClC,mCAAmC,EACnC,+BAA+B,EAC/B,mBAAmB,EACnB,gCAAgC,EAChC,qBAAqB,EACrB,oBAAoB,EACpB,iCAAiC,GAClC,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,6BAA6B,EAAE,MAAM,gBAAgB,CAAA;AAC9D,YAAY,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAC7E,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AACnD,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,SAAS,EACT,YAAY,EACZ,2BAA2B,EAC3B,gCAAgC,GACjC,MAAM,cAAc,CAAA;AACrB,YAAY,EACV,qBAAqB,EACrB,yBAAyB,EACzB,2BAA2B,EAC3B,0BAA0B,EAC1B,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,EACnB,yBAAyB,EACzB,0BAA0B,EAC1B,gBAAgB,GACjB,MAAM,WAAW,CAAA;AAClB,OAAO,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAA;AACrD,YAAY,EACV,qBAAqB,EACrB,2BAA2B,EAC3B,eAAe,EACf,cAAc,EACd,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7C,YAAY,EAAE,+BAA+B,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AACzF,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAA;AACzD,YAAY,EACV,gCAAgC,EAChC,uCAAuC,EACvC,8BAA8B,EAC9B,0BAA0B,EAC1B,gCAAgC,EAChC,+BAA+B,EAC/B,gCAAgC,GACjC,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,sCAAsC,EAAE,MAAM,iBAAiB,CAAA;AACxE,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,iCAAiC,EACjC,cAAc,EACd,oBAAoB,EACpB,wBAAwB,EACxB,qBAAqB,EACrB,oBAAoB,EACpB,gBAAgB,EAChB,uBAAuB,EACvB,uBAAuB,EACvB,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,YAAY,CAAA;AACnB,YAAY,EACV,qBAAqB,EACrB,yBAAyB,EACzB,wBAAwB,EACxB,+BAA+B,EAC/B,8BAA8B,EAC9B,2BAA2B,EAC3B,iCAAiC,EACjC,wCAAwC,EACxC,uCAAuC,EACvC,uBAAuB,EACvB,uBAAuB,EACvB,6BAA6B,EAC7B,6BAA6B,EAC7B,sBAAsB,EACtB,4BAA4B,EAC5B,wBAAwB,EACxB,uBAAuB,GACxB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACL,8BAA8B,EAC9B,uCAAuC,GACxC,MAAM,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,kCAAkC,EAClC,mCAAmC,EACnC,kCAAkC,EAClC,mCAAmC,EACnC,+BAA+B,EAC/B,mBAAmB,EACnB,gCAAgC,EAChC,qBAAqB,EACrB,oBAAoB,EACpB,iCAAiC,GAClC,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,6BAA6B,EAAE,MAAM,gBAAgB,CAAA;AAC9D,YAAY,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAC7E,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AACnD,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,SAAS,EACT,YAAY,EACZ,2BAA2B,EAC3B,gCAAgC,GACjC,MAAM,cAAc,CAAA;AACrB,YAAY,EACV,qBAAqB,EACrB,yBAAyB,EACzB,2BAA2B,EAC3B,0BAA0B,EAC1B,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,EACnB,yBAAyB,EACzB,0BAA0B,EAC1B,gBAAgB,GACjB,MAAM,WAAW,CAAA;AAClB,OAAO,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAA;AACrD,YAAY,EACV,qBAAqB,EACrB,2BAA2B,EAC3B,wCAAwC,EACxC,eAAe,EACf,cAAc,EACd,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7C,YAAY,EAAE,+BAA+B,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AACzF,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAA;AACzD,YAAY,EACV,gCAAgC,EAChC,uCAAuC,EACvC,8BAA8B,EAC9B,0BAA0B,EAC1B,gCAAgC,EAChC,+BAA+B,EAC/B,gCAAgC,GACjC,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,sCAAsC,EAAE,MAAM,iBAAiB,CAAA;AACxE,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,iCAAiC,EACjC,cAAc,EACd,oBAAoB,EACpB,wBAAwB,EACxB,qBAAqB,EACrB,oBAAoB,EACpB,gBAAgB,EAChB,uBAAuB,EACvB,uBAAuB,EACvB,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,YAAY,CAAA;AACnB,YAAY,EACV,qBAAqB,EACrB,yBAAyB,EACzB,wBAAwB,EACxB,+BAA+B,EAC/B,8BAA8B,EAC9B,2BAA2B,EAC3B,iCAAiC,EACjC,wCAAwC,EACxC,uCAAuC,EACvC,uBAAuB,EACvB,uBAAuB,EACvB,6BAA6B,EAC7B,6BAA6B,EAC7B,sBAAsB,EACtB,4BAA4B,EAC5B,wBAAwB,EACxB,uBAAuB,GACxB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACL,8BAA8B,EAC9B,uCAAuC,GACxC,MAAM,gBAAgB,CAAA"}

package/dist/plugin.d.ts

@@ -2,7 +2,7 @@ import type { Plugin } from "@voyantjs/core";
 import { type SmartbillArtifactPersistenceOptions } from "./artifacts.js";
 import type { SmartbillClientOptions } from "./client.js";
 import type { SmartbillMappingOptions } from "./mapping.js";
-import type { SmartbillInvoiceBody, VoyantInvoiceEvent } from "./types.js";
+import type { SmartbillInvoiceBody, SmartbillInvoiceResponse, VoyantInvoiceEvent } from "./types.js";
 export interface SmartbillSyncEventNames {
     issued?: string;
     proformaIssued?: string;
@@ -23,12 +23,19 @@ export interface SmartbillIdempotencyOptions {
     skipExistingExternalRef?: boolean;
 }
 export type SmartbillErrorHandler = (event: VoyantInvoiceEvent, error: unknown) => void | Promise<void>;
+export type SmartbillInvoiceNumberWriteBackFormatter = (event: VoyantInvoiceEvent, result: SmartbillInvoiceResponse) => string | Promise<string>;
 export interface SmartbillPluginOptions extends SmartbillClientOptions, SmartbillMappingOptions {
     events?: SmartbillSyncEventNames;
     mapEvent?: SmartbillMapFn;
     logger?: SmartbillLogger;
     idempotency?: SmartbillIdempotencyOptions;
     onError?: SmartbillErrorHandler;
+    /**
+     * When enabled, mirrors SmartBill's issued series-number back onto
+     * `invoices.invoice_number` after a successful create. `true` uses
+     * `${series}-${number}`; a formatter can return a custom value.
+     */
+    writeBackInvoiceNumber?: boolean | SmartbillInvoiceNumberWriteBackFormatter;
     /**
      * Optional finance artifact persistence. When `db` is supplied, the plugin
      * registers the SmartBill external ref after creation. When

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAc,MAAM,gBAAgB,CAAA;AAIxD,OAAO,EAGL,KAAK,mCAAmC,EAIzC,MAAM,gBAAgB,CAAA;AACvB,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AACzD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AAE3D,OAAO,KAAK,EAAE,oBAAoB,EAA4B,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAGpG,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;IAChD,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;CACjD;AAED,MAAM,MAAM,cAAc,GAAG,CAC3B,KAAK,EAAE,kBAAkB,KACtB,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAA;AAEzD,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAA;CAClC;AAED,MAAM,MAAM,qBAAqB,GAAG,CAClC,KAAK,EAAE,kBAAkB,EACzB,KAAK,EAAE,OAAO,KACX,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AAEzB,MAAM,WAAW,sBAAuB,SAAQ,sBAAsB,EAAE,uBAAuB;IAC7F,MAAM,CAAC,EAAE,uBAAuB,CAAA;IAChC,QAAQ,CAAC,EAAE,cAAc,CAAA;IACzB,MAAM,CAAC,EAAE,eAAe,CAAA;IACxB,WAAW,CAAC,EAAE,2BAA2B,CAAA;IACzC,OAAO,CAAC,EAAE,qBAAqB,CAAA;IAC/B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,mCAAmC,CAAA;IAC/C,sCAAsC;IACtC,EAAE,CAAC,EAAE,mCAAmC,CAAC,IAAI,CAAC,CAAA;IAC9C,mDAAmD;IACnD,eAAe,CAAC,EAAE,mCAAmC,CAAC,iBAAiB,CAAC,CAAA;IACxE,4DAA4D;IAC5D,wBAAwB,CAAC,EAAE,mCAAmC,CAAC,0BAA0B,CAAC,CAAA;CAC3F;AAYD,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,MAAM,CAgUvE"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAc,MAAM,gBAAgB,CAAA;AAIxD,OAAO,EAKL,KAAK,mCAAmC,EAIzC,MAAM,gBAAgB,CAAA;AACvB,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AACzD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AAE3D,OAAO,KAAK,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAGpG,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;IAChD,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;CACjD;AAED,MAAM,MAAM,cAAc,GAAG,CAC3B,KAAK,EAAE,kBAAkB,KACtB,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAA;AAEzD,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAA;CAClC;AAED,MAAM,MAAM,qBAAqB,GAAG,CAClC,KAAK,EAAE,kBAAkB,EACzB,KAAK,EAAE,OAAO,KACX,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AAEzB,MAAM,MAAM,wCAAwC,GAAG,CACrD,KAAK,EAAE,kBAAkB,EACzB,MAAM,EAAE,wBAAwB,KAC7B,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;AAE7B,MAAM,WAAW,sBAAuB,SAAQ,sBAAsB,EAAE,uBAAuB;IAC7F,MAAM,CAAC,EAAE,uBAAuB,CAAA;IAChC,QAAQ,CAAC,EAAE,cAAc,CAAA;IACzB,MAAM,CAAC,EAAE,eAAe,CAAA;IACxB,WAAW,CAAC,EAAE,2BAA2B,CAAA;IACzC,OAAO,CAAC,EAAE,qBAAqB,CAAA;IAC/B;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,OAAO,GAAG,wCAAwC,CAAA;IAC3E;;;;;OAKG;IACH,SAAS,CAAC,EAAE,mCAAmC,CAAA;IAC/C,sCAAsC;IACtC,EAAE,CAAC,EAAE,mCAAmC,CAAC,IAAI,CAAC,CAAA;IAC9C,mDAAmD;IACnD,eAAe,CAAC,EAAE,mCAAmC,CAAC,iBAAiB,CAAC,CAAA;IACxE,4DAA4D;IAC5D,wBAAwB,CAAC,EAAE,mCAAmC,CAAC,0BAA0B,CAAC,CAAA;CAC3F;AAYD,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,MAAM,CAiavE"}

package/dist/plugin.js

@@ -1,6 +1,6 @@
 import { financeService } from "@voyantjs/finance";
 import { ZodError } from "zod";
-import { persistSmartbillInvoiceArtifact, retrySmartbillInvoiceArtifact, } from "./artifacts.js";
+import { isSmartbillPdfPersistMetadataUpdateError, persistSmartbillInvoiceArtifact, recordSmartbillInvoiceArtifactFailure, retrySmartbillInvoiceArtifact, } from "./artifacts.js";
 import { createSmartbillSyncRuntime } from "./runtime.js";
 import { smartbillPluginOptionsSchema } from "./validation.js";
 function coerceEvent(data) {
@@ -16,7 +16,7 @@ function coerceEvent(data) {
 }
 export function smartbillPlugin(options) {
     const validatedOptions = parseSmartbillPluginOptions(options);
-    const { client, logger, mapEvent, eventNames, artifacts, idempotency, onError } = createSmartbillSyncRuntime(validatedOptions);
+    const { client, logger, mapEvent, eventNames, artifacts, idempotency, onError, writeBackInvoiceNumber, } = createSmartbillSyncRuntime(validatedOptions);
     async function resolveMaybe(value, context) {
         return typeof value === "function"
             ? await value(context)
@@ -46,11 +46,12 @@ export function smartbillPlugin(options) {
         if (!db)
             return null;
         const refs = await financeService.listInvoiceExternalRefs(db, event.id);
-        return refs.find((ref) => isUsableSmartbillRef(ref)) ?? null;
+        return refs.find((ref) => isMatchingSmartbillRef(ref, documentType)) ?? null;
     }
     async function handleExistingSmartbillRef(event, documentType, body, externalRef) {
         logger.info?.(`[smartbill] ${documentType} already has SmartBill ref for ${event.id}; skipping create`, externalRef);
         await applyExternalAllocationFromRefIfRequired(event, documentType, body, externalRef);
+        await writeBackInvoiceNumberFromRefIfRequired(event, documentType, body, externalRef);
         try {
             const persisted = await retrySmartbillInvoiceArtifact({
                 runtime: artifacts,
@@ -63,7 +64,10 @@ export function smartbillPlugin(options) {
             }
         }
         catch (err) {
-            logger.error(`[smartbill] artifact re-attach failed for ${event.id}`, err);
+            const message = isSmartbillPdfPersistMetadataUpdateError(err)
+                ? `[smartbill] artifact re-attach metadata update failed for ${event.id}`
+                : `[smartbill] artifact re-attach failed for ${event.id}`;
+            logger.error(message, err);
         }
     }
     async function persistArtifact(event, documentType, body, result) {
@@ -81,7 +85,24 @@ export function smartbillPlugin(options) {
             }
         }
         catch (err) {
+            if (isSmartbillPdfPersistMetadataUpdateError(err)) {
+                logger.error(`[smartbill] artifact persistence metadata update failed for ${event.id}`, err);
+                return;
+            }
             logger.error(`[smartbill] artifact persistence failed for ${event.id}`, err);
+            try {
+                await recordSmartbillInvoiceArtifactFailure({
+                    runtime: artifacts,
+                    event,
+                    documentType,
+                    body,
+                    result,
+                    error: err,
+                });
+            }
+            catch (recordError) {
+                logger.error(`[smartbill] artifact failure external-ref update failed for ${event.id}`, recordError);
+            }
         }
     }
     async function applyExternalAllocationIfRequired(event, documentType, body, result) {
@@ -117,6 +138,52 @@ export function smartbillPlugin(options) {
             url: externalRef.externalUrl ?? undefined,
         });
     }
+    async function resolveWriteBackInvoiceNumber(event, body, result) {
+        if (!writeBackInvoiceNumber)
+            return null;
+        if (typeof writeBackInvoiceNumber === "function") {
+            const invoiceNumber = await writeBackInvoiceNumber(event, result);
+            if (typeof invoiceNumber !== "string" || invoiceNumber.trim().length === 0) {
+                throw new Error("SmartBill invoice number write-back formatter returned an empty value");
+            }
+            return invoiceNumber;
+        }
+        if (!result.number)
+            return null;
+        return formatExternalInvoiceNumber(result.series ?? body.seriesName, result.number);
+    }
+    async function writeBackInvoiceNumberIfRequired(event, documentType, body, result) {
+        const invoiceNumber = await resolveWriteBackInvoiceNumber(event, body, result);
+        if (!invoiceNumber)
+            return;
+        const db = await resolveArtifactDb(event, documentType, body, result);
+        if (!db) {
+            throw new Error("SmartBill invoice number write-back requires artifact database access");
+        }
+        const invoice = await financeService.updateInvoice(db, event.id, { invoiceNumber });
+        if (!invoice) {
+            throw new Error(`SmartBill invoice number write-back failed for missing invoice ${event.id}`);
+        }
+        logger.info?.(`[smartbill] invoice number write-back applied for ${event.id}`, invoice);
+    }
+    async function writeBackInvoiceNumberFromRefIfRequired(event, documentType, body, externalRef) {
+        if (!writeBackInvoiceNumber)
+            return;
+        const metadata = coerceMetadata(externalRef.metadata);
+        const number = metadataString(metadata, "number") ??
+            externalRef.externalNumber ??
+            externalRef.externalId ??
+            null;
+        if (!number)
+            return;
+        await writeBackInvoiceNumberIfRequired(event, documentType, body, {
+            number,
+            series: metadataString(metadata, "series") ??
+                metadataString(metadata, "seriesName") ??
+                body.seriesName,
+            url: externalRef.externalUrl ?? undefined,
+        });
+    }
     async function recordSyncError(event, documentType, err) {
         try {
             await onError?.(event, err);
@@ -129,7 +196,7 @@ export function smartbillPlugin(options) {
             if (!db)
                 return;
             const refs = await financeService.listInvoiceExternalRefs(db, event.id);
-            if (refs.some((ref) => isUsableSmartbillRef(ref)))
+            if (refs.some((ref) => isMatchingSmartbillRef(ref, documentType)))
                 return;
             await financeService.registerInvoiceExternalRef(db, event.id, {
                 provider: "smartbill",
@@ -172,6 +239,7 @@ export function smartbillPlugin(options) {
                     const result = await client.createInvoice(body);
                     logger.info?.(`[smartbill] invoice created: ${result.series}-${result.number} for ${event.id}`, result);
                     await persistArtifact(event, "invoice", body, result);
+                    await writeBackInvoiceNumberIfRequired(event, "invoice", body, result);
                     await applyExternalAllocationIfRequired(event, "invoice", body, result);
                 }
                 catch (err) {
@@ -198,6 +266,7 @@ export function smartbillPlugin(options) {
                     const result = await client.createProforma(body);
                     logger.info?.(`[smartbill] proforma created: ${result.series}-${result.number} for ${event.id}`, result);
                     await persistArtifact(event, "proforma", body, result);
+                    await writeBackInvoiceNumberIfRequired(event, "proforma", body, result);
                     await applyExternalAllocationIfRequired(event, "proforma", body, result);
                 }
                 catch (err) {
@@ -293,6 +362,11 @@ function isUsableSmartbillRef(ref) {
         !ref.syncError &&
         Boolean(ref.externalNumber || ref.externalId));
 }
+function isMatchingSmartbillRef(ref, documentType) {
+    if (!isUsableSmartbillRef(ref))
+        return false;
+    return metadataString(coerceMetadata(ref.metadata), "documentType") === documentType;
+}
 function parseSmartbillPluginOptions(options) {
     try {
         return smartbillPluginOptionsSchema.parse(options);

package/dist/runtime.d.ts

@@ -15,6 +15,7 @@ export interface SmartbillSyncRuntime {
     artifacts: SmartbillArtifactPersistenceOptions;
     idempotency: NonNullable<SmartbillPluginOptions["idempotency"]>;
     onError: SmartbillPluginOptions["onError"];
+    writeBackInvoiceNumber: SmartbillPluginOptions["writeBackInvoiceNumber"];
 }
 export declare function createSmartbillSyncRuntime(options: SmartbillPluginOptions): SmartbillSyncRuntime;
 //# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mCAAmC,EAAE,MAAM,gBAAgB,CAAA;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAEnD,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAG1F,MAAM,WAAW,+BAA+B;IAC9C,MAAM,EAAE,MAAM,CAAA;IACd,cAAc,EAAE,MAAM,CAAA;IACtB,MAAM,EAAE,MAAM,CAAA;IACd,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAA;IAChD,MAAM,EAAE,eAAe,CAAA;IACvB,QAAQ,EAAE,cAAc,CAAA;IACxB,UAAU,EAAE,+BAA+B,CAAA;IAC3C,SAAS,EAAE,mCAAmC,CAAA;IAC9C,WAAW,EAAE,WAAW,CAAC,sBAAsB,CAAC,aAAa,CAAC,CAAC,CAAA;IAC/D,OAAO,EAAE,sBAAsB,CAAC,SAAS,CAAC,CAAA;CAC3C;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,sBAAsB,GAAG,oBAAoB,CAwChG"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mCAAmC,EAAE,MAAM,gBAAgB,CAAA;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAEnD,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAG1F,MAAM,WAAW,+BAA+B;IAC9C,MAAM,EAAE,MAAM,CAAA;IACd,cAAc,EAAE,MAAM,CAAA;IACtB,MAAM,EAAE,MAAM,CAAA;IACd,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAA;IAChD,MAAM,EAAE,eAAe,CAAA;IACvB,QAAQ,EAAE,cAAc,CAAA;IACxB,UAAU,EAAE,+BAA+B,CAAA;IAC3C,SAAS,EAAE,mCAAmC,CAAA;IAC9C,WAAW,EAAE,WAAW,CAAC,sBAAsB,CAAC,aAAa,CAAC,CAAC,CAAA;IAC/D,OAAO,EAAE,sBAAsB,CAAC,SAAS,CAAC,CAAA;IAC1C,sBAAsB,EAAE,sBAAsB,CAAC,wBAAwB,CAAC,CAAA;CACzE;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,sBAAsB,GAAG,oBAAoB,CAyChG"}

package/dist/runtime.js

@@ -36,5 +36,6 @@ export function createSmartbillSyncRuntime(options) {
             skipExistingExternalRef: options.idempotency?.skipExistingExternalRef ?? true,
         },
         onError: options.onError,
+        writeBackInvoiceNumber: options.writeBackInvoiceNumber,
     };
 }

package/dist/validation.d.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import type { SmartbillArtifactPersistenceOptions, SmartbillDbResolver, SmartbillDocumentStorageResolver, SmartbillStorageKeyPrefixResolver } from "./artifacts.js";
-import type { SmartbillErrorHandler, SmartbillIdempotencyOptions, SmartbillLogger, SmartbillMapFn, SmartbillSyncEventNames } from "./plugin.js";
+import type { SmartbillErrorHandler, SmartbillIdempotencyOptions, SmartbillInvoiceNumberWriteBackFormatter, SmartbillLogger, SmartbillMapFn, SmartbillSyncEventNames } from "./plugin.js";
 import type { SmartbillFetch } from "./types.js";
 export declare const smartbillPluginOptionsSchema: z.ZodObject<{
     username: z.ZodString;
@@ -21,6 +21,7 @@ export declare const smartbillPluginOptionsSchema: z.ZodObject<{
     logger: z.ZodOptional<z.ZodCustom<SmartbillLogger | undefined, SmartbillLogger | undefined>>;
     idempotency: z.ZodOptional<z.ZodCustom<SmartbillIdempotencyOptions | undefined, SmartbillIdempotencyOptions | undefined>>;
     onError: z.ZodOptional<z.ZodCustom<SmartbillErrorHandler | undefined, SmartbillErrorHandler | undefined>>;
+    writeBackInvoiceNumber: z.ZodOptional<z.ZodCustom<boolean | SmartbillInvoiceNumberWriteBackFormatter | undefined, boolean | SmartbillInvoiceNumberWriteBackFormatter | undefined>>;
     artifacts: z.ZodOptional<z.ZodCustom<SmartbillArtifactPersistenceOptions | undefined, SmartbillArtifactPersistenceOptions | undefined>>;
     db: z.ZodOptional<z.ZodCustom<SmartbillDbResolver | undefined, SmartbillDbResolver | undefined>>;
     documentStorage: z.ZodOptional<z.ZodCustom<SmartbillDocumentStorageResolver | undefined, SmartbillDocumentStorageResolver | undefined>>;

package/dist/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EACV,mCAAmC,EACnC,mBAAmB,EACnB,gCAAgC,EAChC,iCAAiC,EAClC,MAAM,gBAAgB,CAAA;AAEvB,OAAO,KAAK,EACV,qBAAqB,EACrB,2BAA2B,EAC3B,eAAe,EACf,cAAc,EAEd,uBAAuB,EACxB,MAAM,aAAa,CAAA;AACpB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAyGhD,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;iBAuBK,CAAA"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EACV,mCAAmC,EACnC,mBAAmB,EACnB,gCAAgC,EAChC,iCAAiC,EAClC,MAAM,gBAAgB,CAAA;AAEvB,OAAO,KAAK,EACV,qBAAqB,EACrB,2BAA2B,EAC3B,wCAAwC,EACxC,eAAe,EACf,cAAc,EAEd,uBAAuB,EACxB,MAAM,aAAa,CAAA;AACpB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAgHhD,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;iBAwBK,CAAA"}

package/dist/validation.js

@@ -14,6 +14,7 @@ const optionalLogger = z.custom((value) => value === undefined ||
             typeof value.info === "function")), "Expected a logger with an error function");
 const optionalMapEvent = z.custom((value) => value === undefined || typeof value === "function", "Expected a mapEvent function");
 const optionalOnError = z.custom((value) => value === undefined || typeof value === "function", "Expected an onError function");
+const optionalWriteBackInvoiceNumber = z.custom((value) => value === undefined || typeof value === "boolean" || typeof value === "function", "Expected a boolean or invoice number formatter function");
 const optionalDb = z.custom((value) => value === undefined ||
     typeof value === "function" ||
     (typeof value === "object" && value !== null), "Expected a database handle or resolver function");
@@ -76,6 +77,7 @@ export const smartbillPluginOptionsSchema = z.object({
     logger: optionalLogger.optional(),
     idempotency: optionalIdempotency.optional(),
     onError: optionalOnError.optional(),
+    writeBackInvoiceNumber: optionalWriteBackInvoiceNumber.optional(),
     artifacts: optionalArtifacts.optional(),
     db: optionalDb.optional(),
     documentStorage: optionalDocumentStorage.optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyantjs/plugin-smartbill",
-  "version": "0.77.6",
+  "version": "0.77.11",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
@@ -48,17 +48,17 @@
   "dependencies": {
     "drizzle-orm": "^0.45.2",
     "zod": "^4.3.6",
-    "@voyantjs/core": "0.77.6",
-    "@voyantjs/finance": "0.77.6",
-    "@voyantjs/storage": "0.77.6"
+    "@voyantjs/core": "0.77.11",
+    "@voyantjs/finance": "0.77.11",
+    "@voyantjs/storage": "0.77.11"
   },
   "peerDependencies": {
     "@tanstack/react-query": "^5.0.0",
     "lucide-react": "^0.475.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@voyantjs/finance-react": "0.77.6",
-    "@voyantjs/ui": "0.77.6"
+    "@voyantjs/finance-react": "0.77.11",
+    "@voyantjs/ui": "0.77.11"
   },
   "peerDependenciesMeta": {
     "@tanstack/react-query": {
@@ -89,8 +89,8 @@
     "react-dom": "^19.2.4",
     "typescript": "^6.0.2",
     "vitest": "^4.1.2",
-    "@voyantjs/finance-react": "0.77.6",
-    "@voyantjs/ui": "0.77.6",
+    "@voyantjs/finance-react": "0.77.11",
+    "@voyantjs/ui": "0.77.11",
     "@voyantjs/voyant-typescript-config": "0.1.0"
   },
   "files": [