@voyantjs/plugin-smartbill 0.38.1 → 0.40.0

package/README.md

@@ -27,8 +27,11 @@ const smartbillSync = smartbillPlugin({
   username: env.SMARTBILL_USERNAME,
   apiToken: env.SMARTBILL_API_TOKEN,
   companyVatCode: "RO12345678",
-  seriesName: "A",
-  // optional: language, art311SpecialRegime, events, mapEvent, logger
+  seriesName: (event) => (event.channel === "online" ? "WEB" : "A"),
+  mentions: async (event) => `Booking ${event.bookingCode ?? event.id}`,
+  observations: "Generated by Voyant",
+  art311SpecialRegimeText: "Custom Art. 311 disclosure",
+  // optional: language, art311SpecialRegime, events, mapEvent, logger, onError
   artifacts: {
     db: appDb,
     documentStorage,
@@ -58,6 +61,24 @@ upload path defaults to `invoices/<invoiceId>/smartbill/...`; pass
 `smartbill_pdf` attachments are reused so repeat event delivery does not upload
 the same PDF again.
 
+`seriesName`, `mentions`, and `observations` may be static strings or
+event-specific callbacks. The packaged plugin awaits these callbacks in its
+default mapper, so each invoice event can choose a SmartBill series or
+compliance text based on document type, sales channel, or booking metadata.
+
+When `artifacts.db` is configured, duplicate `invoice.issued` and
+`invoice.proforma.issued` deliveries are idempotent by default: the plugin
+checks for an existing non-error SmartBill external reference before creating a
+new SmartBill document. Disable this with
+`idempotency: { skipExistingExternalRef: false }` only when the caller owns
+deduplication elsewhere. Create failures are recorded as SmartBill external refs
+with `status: "error"` and `syncError`; `onError(event, error)` can be supplied
+for application-specific reporting.
+
+Use `retrySmartbillInvoiceArtifact({ runtime, client, externalRef, documentType
+})` to re-download and re-attach a SmartBill PDF from an existing external ref
+without issuing a new document.
+
 ## Exports
 
 | Entry | Description |

package/dist/artifacts.d.ts

@@ -1,3 +1,4 @@
+import { financeService, type InvoiceExternalRef } from "@voyantjs/finance";
 import type { StorageProvider } from "@voyantjs/storage";
 import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
 import type { SmartbillClientApi } from "./client.js";
@@ -30,72 +31,30 @@ export interface PersistSmartbillInvoiceArtifactInput {
     body: SmartbillInvoiceBody;
     result: SmartbillInvoiceResponse;
 }
-export declare function persistSmartbillInvoiceArtifact({ runtime, client, event, documentType, body, result, }: PersistSmartbillInvoiceArtifactInput): Promise<{
-    status: "skipped";
-    reason: "missing_db";
-    attachment?: undefined;
-    rendition?: undefined;
-} | {
+export type SmartbillExternalRef = Pick<InvoiceExternalRef, "id" | "invoiceId" | "externalId" | "externalNumber" | "externalUrl" | "metadata">;
+export interface RetrySmartbillInvoiceArtifactInput {
+    runtime: SmartbillArtifactPersistenceRuntime;
+    client: SmartbillClientApi;
+    externalRef: SmartbillExternalRef;
+    documentType: SmartbillDocumentType;
+}
+type InvoiceAttachmentRecord = Awaited<ReturnType<typeof financeService.createInvoiceAttachment>>;
+type InvoiceRenditionRecord = Awaited<ReturnType<typeof financeService.createInvoiceRendition>>;
+export type SmartbillArtifactPersistenceResult = {
     status: "skipped";
-    reason: "missing_invoice";
-    attachment?: undefined;
-    rendition?: undefined;
-} | {
-    status: "registered_ref";
-    reason?: undefined;
-    attachment?: undefined;
-    rendition?: undefined;
+    reason: "missing_db" | "missing_invoice" | "missing_document_storage" | "missing_smartbill_reference";
 } | {
     status: "registered_ref";
-    reason: "missing_number";
-    attachment?: undefined;
-    rendition?: undefined;
+    reason?: "missing_number";
 } | {
     status: "already_exists";
-    attachment: {
-        id: string;
-        invoiceId: string;
-        kind: string;
-        name: string;
-        mimeType: string | null;
-        fileSize: number | null;
-        storageKey: string | null;
-        checksum: string | null;
-        metadata: unknown;
-        createdAt: Date;
-    };
-    reason?: undefined;
-    rendition?: undefined;
+    attachment: InvoiceAttachmentRecord;
 } | {
     status: "persisted";
-    rendition: {
-        metadata: unknown;
-        id: string;
-        createdAt: Date;
-        updatedAt: Date;
-        status: "pending" | "failed" | "ready" | "stale";
-        format: "json" | "pdf" | "html" | "xml";
-        errorMessage: string | null;
-        templateId: string | null;
-        language: string | null;
-        invoiceId: string;
-        storageKey: string | null;
-        fileSize: number | null;
-        checksum: string | null;
-        generatedAt: Date | null;
-    } | null;
-    attachment: {
-        metadata: unknown;
-        name: string;
-        id: string;
-        createdAt: Date;
-        kind: string;
-        invoiceId: string;
-        storageKey: string | null;
-        fileSize: number | null;
-        checksum: string | null;
-        mimeType: string | null;
-    } | null;
-    reason?: undefined;
-}>;
+    rendition: InvoiceRenditionRecord;
+    attachment: InvoiceAttachmentRecord;
+};
+export declare function persistSmartbillInvoiceArtifact({ runtime, client, event, documentType, body, result, }: PersistSmartbillInvoiceArtifactInput): 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":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAEjE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AACrD,OAAO,KAAK,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAEpG,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,UAAU,CAAA;AAE1D,MAAM,WAAW,+BAA+B;IAC9C,KAAK,EAAE,kBAAkB,CAAA;IACzB,YAAY,EAAE,qBAAqB,CAAA;IACnC,IAAI,EAAE,oBAAoB,CAAA;IAC1B,MAAM,EAAE,wBAAwB,CAAA;CACjC;AAED,MAAM,MAAM,mBAAmB,GAC3B,kBAAkB,GAClB,CAAC,CACC,OAAO,EAAE,+BAA+B,KACrC,kBAAkB,GAAG,IAAI,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC,CAAA;AAExE,MAAM,MAAM,gCAAgC,GACxC,eAAe,GACf,IAAI,GACJ,CAAC,CACC,OAAO,EAAE,+BAA+B,KACrC,eAAe,GAAG,IAAI,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC,CAAA;AAElE,MAAM,MAAM,iCAAiC,GACzC,MAAM,GACN,CAAC,CAAC,OAAO,EAAE,+BAA+B,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAA;AAE5E,MAAM,WAAW,mCAAmC;IAClD,EAAE,CAAC,EAAE,mBAAmB,CAAA;IACxB,eAAe,CAAC,EAAE,gCAAgC,CAAA;IAClD,wBAAwB,CAAC,EAAE,iCAAiC,CAAA;CAC7D;AAED,MAAM,WAAW,mCAAmC;IAClD,EAAE,CAAC,EAAE,mBAAmB,CAAA;IACxB,eAAe,CAAC,EAAE,gCAAgC,CAAA;IAClD,wBAAwB,CAAC,EAAE,iCAAiC,CAAA;CAC7D;AAED,MAAM,WAAW,oCAAoC;IACnD,OAAO,EAAE,mCAAmC,CAAA;IAC5C,MAAM,EAAE,kBAAkB,CAAA;IAC1B,KAAK,EAAE,kBAAkB,CAAA;IACzB,YAAY,EAAE,qBAAqB,CAAA;IACnC,IAAI,EAAE,oBAAoB,CAAA;IAC1B,MAAM,EAAE,wBAAwB,CAAA;CACjC;AAwCD,wBAAsB,+BAA+B,CAAC,EACpD,OAAO,EACP,MAAM,EACN,KAAK,EACL,YAAY,EACZ,IAAI,EACJ,MAAM,GACP,EAAE,oCAAoC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiGtC"}
+{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../src/artifacts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAC3E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAEjE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AACrD,OAAO,KAAK,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAEpG,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,UAAU,CAAA;AAE1D,MAAM,WAAW,+BAA+B;IAC9C,KAAK,EAAE,kBAAkB,CAAA;IACzB,YAAY,EAAE,qBAAqB,CAAA;IACnC,IAAI,EAAE,oBAAoB,CAAA;IAC1B,MAAM,EAAE,wBAAwB,CAAA;CACjC;AAED,MAAM,MAAM,mBAAmB,GAC3B,kBAAkB,GAClB,CAAC,CACC,OAAO,EAAE,+BAA+B,KACrC,kBAAkB,GAAG,IAAI,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC,CAAA;AAExE,MAAM,MAAM,gCAAgC,GACxC,eAAe,GACf,IAAI,GACJ,CAAC,CACC,OAAO,EAAE,+BAA+B,KACrC,eAAe,GAAG,IAAI,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC,CAAA;AAElE,MAAM,MAAM,iCAAiC,GACzC,MAAM,GACN,CAAC,CAAC,OAAO,EAAE,+BAA+B,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAA;AAE5E,MAAM,WAAW,mCAAmC;IAClD,EAAE,CAAC,EAAE,mBAAmB,CAAA;IACxB,eAAe,CAAC,EAAE,gCAAgC,CAAA;IAClD,wBAAwB,CAAC,EAAE,iCAAiC,CAAA;CAC7D;AAED,MAAM,WAAW,mCAAmC;IAClD,EAAE,CAAC,EAAE,mBAAmB,CAAA;IACxB,eAAe,CAAC,EAAE,gCAAgC,CAAA;IAClD,wBAAwB,CAAC,EAAE,iCAAiC,CAAA;CAC7D;AAED,MAAM,WAAW,oCAAoC;IACnD,OAAO,EAAE,mCAAmC,CAAA;IAC5C,MAAM,EAAE,kBAAkB,CAAA;IAC1B,KAAK,EAAE,kBAAkB,CAAA;IACzB,YAAY,EAAE,qBAAqB,CAAA;IACnC,IAAI,EAAE,oBAAoB,CAAA;IAC1B,MAAM,EAAE,wBAAwB,CAAA;CACjC;AAED,MAAM,MAAM,oBAAoB,GAAG,IAAI,CACrC,kBAAkB,EAClB,IAAI,GAAG,WAAW,GAAG,YAAY,GAAG,gBAAgB,GAAG,aAAa,GAAG,UAAU,CAClF,CAAA;AAED,MAAM,WAAW,kCAAkC;IACjD,OAAO,EAAE,mCAAmC,CAAA;IAC5C,MAAM,EAAE,kBAAkB,CAAA;IAC1B,WAAW,EAAE,oBAAoB,CAAA;IACjC,YAAY,EAAE,qBAAqB,CAAA;CACpC;AAED,KAAK,uBAAuB,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,cAAc,CAAC,uBAAuB,CAAC,CAAC,CAAA;AACjG,KAAK,sBAAsB,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,cAAc,CAAC,sBAAsB,CAAC,CAAC,CAAA;AAE/F,MAAM,MAAM,kCAAkC,GAC1C;IACE,MAAM,EAAE,SAAS,CAAA;IACjB,MAAM,EACF,YAAY,GACZ,iBAAiB,GACjB,0BAA0B,GAC1B,6BAA6B,CAAA;CAClC,GACD;IAAE,MAAM,EAAE,gBAAgB,CAAC;IAAC,MAAM,CAAC,EAAE,gBAAgB,CAAA;CAAE,GACvD;IAAE,MAAM,EAAE,gBAAgB,CAAC;IAAC,UAAU,EAAE,uBAAuB,CAAA;CAAE,GACjE;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,SAAS,EAAE,sBAAsB,CAAC;IAAC,UAAU,EAAE,uBAAuB,CAAA;CAAE,CAAA;AAmDnG,wBAAsB,+BAA+B,CAAC,EACpD,OAAO,EACP,MAAM,EACN,KAAK,EACL,YAAY,EACZ,IAAI,EACJ,MAAM,GACP,EAAE,oCAAoC,GAAG,OAAO,CAAC,kCAAkC,CAAC,CA6CpF;AAED,wBAAsB,6BAA6B,CAAC,EAClD,OAAO,EACP,MAAM,EACN,WAAW,EACX,YAAY,GACb,EAAE,kCAAkC,GAAG,OAAO,CAAC,kCAAkC,CAAC,CAqDlF"}

package/dist/artifacts.js

@@ -23,6 +23,15 @@ async function sha256(bytes) {
 function smartbillAttachmentName(documentType, seriesName, number) {
     return `SmartBill ${documentType} ${seriesName}-${number}.pdf`;
 }
+function coerceMetadata(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+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" };
@@ -55,17 +64,82 @@ export async function persistSmartbillInvoiceArtifact({ runtime, client, event,
         return { status: "registered_ref" };
     if (!number)
         return { status: "registered_ref", reason: "missing_number" };
-    const existingAttachments = await financeService.listInvoiceAttachments(db, event.id);
+    const keyPrefix = await resolveMaybe(runtime.documentStorageKeyPrefix, context);
+    return persistSmartbillPdfArtifact({
+        db,
+        storage,
+        client,
+        invoiceId: event.id,
+        documentType,
+        companyVatCode: body.companyVatCode,
+        seriesName,
+        number,
+        language: body.language ?? null,
+        keyPrefix,
+    });
+}
+export async function retrySmartbillInvoiceArtifact({ runtime, client, externalRef, documentType, }) {
+    if (!runtime.db)
+        return { status: "skipped", reason: "missing_db" };
+    const metadata = coerceMetadata(externalRef.metadata);
+    const companyVatCode = metadataString(metadata, "companyVatCode") ?? metadataString(metadata, "vatCode");
+    const seriesName = metadataString(metadata, "series") ?? metadataString(metadata, "seriesName");
+    const number = metadataString(metadata, "number") ??
+        externalRef.externalNumber ??
+        externalRef.externalId ??
+        null;
+    if (!companyVatCode || !seriesName || !number) {
+        return { status: "skipped", reason: "missing_smartbill_reference" };
+    }
+    const context = {
+        event: { id: externalRef.invoiceId },
+        documentType,
+        body: {
+            companyVatCode,
+            client: { name: "Client" },
+            seriesName,
+            currency: "RON",
+            language: metadataString(metadata, "language") ?? undefined,
+            products: [],
+        },
+        result: {
+            number,
+            series: seriesName,
+            url: externalRef.externalUrl ?? undefined,
+        },
+    };
+    const db = await resolveMaybe(runtime.db, context);
+    if (!db)
+        return { status: "skipped", reason: "missing_db" };
+    const storage = await resolveMaybe(runtime.documentStorage, context);
+    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,
+    });
+}
+async function persistSmartbillPdfArtifact({ db, storage, client, invoiceId, documentType, companyVatCode, seriesName, number, language, keyPrefix, }) {
+    const existingAttachments = await 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(body.companyVatCode, seriesName, number)
-        : await client.viewInvoicePdf(body.companyVatCode, seriesName, number);
-    const defaultPrefix = `invoices/${event.id}/smartbill`;
-    const keyPrefix = (await resolveMaybe(runtime.documentStorageKeyPrefix, context)) ?? defaultPrefix;
-    const key = `${keyPrefix.replace(/\/$/, "")}/${documentType}-${sanitizeKeyPart(seriesName)}-${sanitizeKeyPart(number)}.pdf`;
+        ? await client.viewEstimatePdf(companyVatCode, seriesName, number)
+        : await 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, {
@@ -74,7 +148,7 @@ export async function persistSmartbillInvoiceArtifact({ runtime, client, event,
         metadata: {
             provider: "smartbill",
             documentType,
-            invoiceId: event.id,
+            invoiceId,
             seriesName,
             number,
         },
@@ -82,23 +156,23 @@ export async function persistSmartbillInvoiceArtifact({ runtime, client, event,
     const commonMetadata = {
         provider: "smartbill",
         documentType,
-        companyVatCode: body.companyVatCode,
+        companyVatCode,
         seriesName,
         number,
         storageProvider: storage.name,
         ...(uploaded.url ? { url: uploaded.url } : {}),
     };
-    const rendition = await financeService.createInvoiceRendition(db, event.id, {
+    const rendition = await financeService.createInvoiceRendition(db, invoiceId, {
         format: "pdf",
         status: "ready",
         storageKey: uploaded.key,
         fileSize: pdf.bytes.byteLength,
         checksum,
-        language: body.language ?? null,
+        language: language ?? null,
         generatedAt: new Date().toISOString(),
         metadata: commonMetadata,
     });
-    const attachment = await financeService.createInvoiceAttachment(db, event.id, {
+    const attachment = await financeService.createInvoiceAttachment(db, invoiceId, {
         kind: SMARTBILL_ATTACHMENT_KIND,
         name: smartbillAttachmentName(documentType, seriesName, number),
         mimeType: contentType,

package/dist/index.d.ts

@@ -1,15 +1,16 @@
-export type { SmartbillArtifactPersistenceOptions, SmartbillArtifactStorageContext, SmartbillDbResolver, SmartbillDocumentStorageResolver, SmartbillDocumentType, SmartbillStorageKeyPrefixResolver, } from "./artifacts.js";
+export type { RetrySmartbillInvoiceArtifactInput, SmartbillArtifactPersistenceOptions, SmartbillArtifactPersistenceResult, SmartbillArtifactPersistenceRuntime, SmartbillArtifactStorageContext, SmartbillDbResolver, SmartbillDocumentStorageResolver, SmartbillDocumentType, SmartbillExternalRef, SmartbillStorageKeyPrefixResolver, } from "./artifacts.js";
+export { retrySmartbillInvoiceArtifact } from "./artifacts.js";
 export type { SmartbillClientApi, SmartbillClientOptions } from "./client.js";
 export { createSmartbillClient } from "./client.js";
-export type { SmartbillMappingOptions } from "./mapping.js";
-export { mapClient, mapLineItems, mapVoyantInvoiceToSmartbill } from "./mapping.js";
+export type { SmartbillEventValue, SmartbillMappingOptions, SmartbillMaybePromise, } from "./mapping.js";
+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 { SmartbillLogger, SmartbillMapFn, SmartbillPluginOptions, SmartbillSyncEventNames, } from "./plugin.js";
+export type { SmartbillErrorHandler, SmartbillIdempotencyOptions, SmartbillLogger, SmartbillMapFn, SmartbillPluginOptions, SmartbillSyncEventNames, } from "./plugin.js";
 export { smartbillPlugin } from "./plugin.js";
 export type { ResolvedSmartbillSyncEventNames, SmartbillSyncRuntime } from "./runtime.js";
 export { createSmartbillSyncRuntime } from "./runtime.js";
-export type { SmartbillInvoiceSettlementPoller, SmartbillInvoiceSettlementPollerOptions, SmartbillSettlementExternalRef, SmartbillSettlementInvoice, SmartbillSettlementPollerContext, SmartbillSettlementPollerResult, } from "./settlement.js";
+export type { SmartbillInvoiceSettlementPoller, SmartbillInvoiceSettlementPollerOptions, SmartbillSettlementExternalRef, SmartbillSettlementInvoice, SmartbillSettlementPollerContext, SmartbillSettlementPollerResult, SmartbillSettlementSeriesContext, } from "./settlement.js";
 export { createSmartbillInvoiceSettlementPoller } from "./settlement.js";
 export type { SmartbillClient, SmartbillEnvelope, SmartbillEstimateInvoicesResponse, SmartbillFetch, SmartbillInvoiceBody, SmartbillInvoiceResponse, SmartbillPaymentEntry, SmartbillPdfResponse, SmartbillProduct, SmartbillSeriesResponse, SmartbillStatusResponse, SmartbillTaxesResponse, VoyantInvoiceEvent, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,mCAAmC,EACnC,+BAA+B,EAC/B,mBAAmB,EACnB,gCAAgC,EAChC,qBAAqB,EACrB,iCAAiC,GAClC,MAAM,gBAAgB,CAAA;AACvB,YAAY,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAC7E,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AACnD,YAAY,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AAC3D,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAA;AACnF,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,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,GAChC,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"}
+{"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"}

package/dist/index.js

@@ -1,5 +1,6 @@
+export { retrySmartbillInvoiceArtifact } from "./artifacts.js";
 export { createSmartbillClient } from "./client.js";
-export { mapClient, mapLineItems, mapVoyantInvoiceToSmartbill } from "./mapping.js";
+export { mapClient, mapLineItems, mapVoyantInvoiceToSmartbill, mapVoyantInvoiceToSmartbillAsync, } from "./mapping.js";
 export { createSmartbillMockServer } from "./mock.js";
 export { smartbillPlugin } from "./plugin.js";
 export { createSmartbillSyncRuntime } from "./runtime.js";

package/dist/mapping.d.ts

@@ -1,18 +1,26 @@
 import type { SmartbillClient, SmartbillInvoiceBody, SmartbillProduct, VoyantInvoiceEvent } from "./types.js";
+export type SmartbillMaybePromise<T> = T | Promise<T>;
+export type SmartbillEventValue<T> = T | ((event: VoyantInvoiceEvent) => SmartbillMaybePromise<T>);
 /**
  * Options for the default invoice mapper.
  */
 export interface SmartbillMappingOptions {
     /** Romanian company VAT code (e.g. `"RO12345678"`). */
     companyVatCode: string;
-    /** SmartBill invoice series name (e.g. `"A"`). */
-    seriesName: string;
+    /** SmartBill invoice series name (e.g. `"A"`), or an event-specific resolver. */
+    seriesName: SmartbillEventValue<string>;
     /** Invoice language. Defaults to `"RO"`. */
     language?: string;
     /** Whether VAT is included in line item prices. Defaults to `true`. */
     isTaxIncluded?: boolean;
     /** Whether to use Art. 311 special regime (margin scheme for travel). */
     art311SpecialRegime?: boolean;
+    /** Text appended to mentions when Art. 311 special regime is enabled. */
+    art311SpecialRegimeText?: string;
+    /** SmartBill mentions override, or an event-specific resolver. Defaults to event.mentions. */
+    mentions?: SmartbillEventValue<string | null | undefined>;
+    /** SmartBill observations override, or an event-specific resolver. Defaults to event.observations. */
+    observations?: SmartbillEventValue<string | null | undefined>;
 }
 /**
  * Extract the SmartBill client block from a Voyant invoice event.
@@ -24,9 +32,15 @@ export declare function mapClient(event: VoyantInvoiceEvent): SmartbillClient;
  * Expects `event.lineItems` to be an array of objects with at minimum
  * `description`/`name`, `quantity`, `unitPrice`, `currency`.
  */
-export declare function mapLineItems(event: VoyantInvoiceEvent, options: SmartbillMappingOptions): SmartbillProduct[];
+export declare function mapLineItems(event: VoyantInvoiceEvent, options: Pick<SmartbillMappingOptions, "isTaxIncluded">): SmartbillProduct[];
 /**
  * Map a full Voyant invoice event to a SmartBill invoice body.
  */
 export declare function mapVoyantInvoiceToSmartbill(event: VoyantInvoiceEvent, options: SmartbillMappingOptions): SmartbillInvoiceBody;
+/**
+ * Async variant of the default mapper. Use this when mapping options include
+ * promise-returning callbacks such as `seriesName`, `mentions`, or
+ * `observations`.
+ */
+export declare function mapVoyantInvoiceToSmartbillAsync(event: VoyantInvoiceEvent, options: SmartbillMappingOptions): Promise<SmartbillInvoiceBody>;
 //# sourceMappingURL=mapping.d.ts.map

package/dist/mapping.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mapping.d.ts","sourceRoot":"","sources":["../src/mapping.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,YAAY,CAAA;AAEnB;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,uDAAuD;IACvD,cAAc,EAAE,MAAM,CAAA;IACtB,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAA;IAClB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,uEAAuE;IACvE,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,yEAAyE;IACzE,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAC9B;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,kBAAkB,GAAG,eAAe,CAapE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE,uBAAuB,GAC/B,gBAAgB,EAAE,CAiBpB;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE,uBAAuB,GAC/B,oBAAoB,CA2BtB"}
+{"version":3,"file":"mapping.d.ts","sourceRoot":"","sources":["../src/mapping.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,YAAY,CAAA;AAEnB,MAAM,MAAM,qBAAqB,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;AAErD,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,kBAAkB,KAAK,qBAAqB,CAAC,CAAC,CAAC,CAAC,CAAA;AAKlG;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,uDAAuD;IACvD,cAAc,EAAE,MAAM,CAAA;IACtB,iFAAiF;IACjF,UAAU,EAAE,mBAAmB,CAAC,MAAM,CAAC,CAAA;IACvC,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,uEAAuE;IACvE,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,yEAAyE;IACzE,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAC7B,yEAAyE;IACzE,uBAAuB,CAAC,EAAE,MAAM,CAAA;IAChC,8FAA8F;IAC9F,QAAQ,CAAC,EAAE,mBAAmB,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAA;IACzD,sGAAsG;IACtG,YAAY,CAAC,EAAE,mBAAmB,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAA;CAC9D;AAeD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,kBAAkB,GAAG,eAAe,CAapE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE,IAAI,CAAC,uBAAuB,EAAE,eAAe,CAAC,GACtD,gBAAgB,EAAE,CAiBpB;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE,uBAAuB,GAC/B,oBAAoB,CAEtB;AAED;;;;GAIG;AACH,wBAAsB,gCAAgC,CACpD,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,oBAAoB,CAAC,CAE/B"}

package/dist/mapping.js

@@ -1,3 +1,4 @@
+const DEFAULT_ART311_SPECIAL_REGIME_TEXT = "Regimul special de taxare - agentie de turism (Art. 311 Cod Fiscal)";
 /**
  * Extract the SmartBill client block from a Voyant invoice event.
  * Falls back to empty strings for missing fields.
@@ -43,6 +44,17 @@ export function mapLineItems(event, options) {
  * Map a full Voyant invoice event to a SmartBill invoice body.
  */
 export function mapVoyantInvoiceToSmartbill(event, options) {
+    return buildSmartbillInvoiceBody(event, resolveMappingOptionsSync(event, options));
+}
+/**
+ * Async variant of the default mapper. Use this when mapping options include
+ * promise-returning callbacks such as `seriesName`, `mentions`, or
+ * `observations`.
+ */
+export async function mapVoyantInvoiceToSmartbillAsync(event, options) {
+    return buildSmartbillInvoiceBody(event, await resolveMappingOptions(event, options));
+}
+function buildSmartbillInvoiceBody(event, options) {
     const body = {
         companyVatCode: options.companyVatCode,
         client: mapClient(event),
@@ -59,14 +71,20 @@ export function mapVoyantInvoiceToSmartbill(event, options) {
         body.issueDate = event.issueDate;
     if (typeof event.deliveryDate === "string")
         body.deliveryDate = event.deliveryDate;
-    if (typeof event.mentions === "string")
-        body.mentions = event.mentions;
-    if (typeof event.observations === "string")
-        body.observations = event.observations;
+    const mentions = options.hasMentionsOverride
+        ? options.mentions
+        : asStringOrUndefined(event.mentions);
+    if (mentions)
+        body.mentions = mentions;
+    const observations = options.hasObservationsOverride
+        ? options.observations
+        : asStringOrUndefined(event.observations);
+    if (observations)
+        body.observations = observations;
     if (options.art311SpecialRegime) {
         body.mentions = [
             body.mentions,
-            "Regimul special de taxare - agentie de turism (Art. 311 Cod Fiscal)",
+            options.art311SpecialRegimeText ?? DEFAULT_ART311_SPECIAL_REGIME_TEXT,
         ]
             .filter(Boolean)
             .join("\n");
@@ -74,6 +92,70 @@ export function mapVoyantInvoiceToSmartbill(event, options) {
     return body;
 }
 // --- helpers ---
+function resolveMappingOptionsSync(event, options) {
+    return {
+        companyVatCode: options.companyVatCode,
+        seriesName: resolveRequiredEventValueSync(event, options.seriesName, "seriesName"),
+        language: options.language,
+        isTaxIncluded: options.isTaxIncluded,
+        art311SpecialRegime: options.art311SpecialRegime,
+        art311SpecialRegimeText: options.art311SpecialRegimeText,
+        mentions: normalizeOptionalText(resolveEventValueSync(event, options.mentions, "mentions")),
+        observations: normalizeOptionalText(resolveEventValueSync(event, options.observations, "observations")),
+        hasMentionsOverride: options.mentions !== undefined,
+        hasObservationsOverride: options.observations !== undefined,
+    };
+}
+async function resolveMappingOptions(event, options) {
+    return {
+        companyVatCode: options.companyVatCode,
+        seriesName: await resolveRequiredEventValue(event, options.seriesName, "seriesName"),
+        language: options.language,
+        isTaxIncluded: options.isTaxIncluded,
+        art311SpecialRegime: options.art311SpecialRegime,
+        art311SpecialRegimeText: options.art311SpecialRegimeText,
+        mentions: normalizeOptionalText(await resolveEventValue(event, options.mentions)),
+        observations: normalizeOptionalText(await resolveEventValue(event, options.observations)),
+        hasMentionsOverride: options.mentions !== undefined,
+        hasObservationsOverride: options.observations !== undefined,
+    };
+}
+function resolveEventValueSync(event, value, field) {
+    const resolved = typeof value === "function"
+        ? value(event)
+        : value;
+    if (isPromiseLike(resolved)) {
+        throw new Error(`SmartBill mapping option "${field}" returned a Promise; use mapVoyantInvoiceToSmartbillAsync`);
+    }
+    return resolved;
+}
+function resolveRequiredEventValueSync(event, value, field) {
+    const resolved = resolveEventValueSync(event, value, field);
+    if (resolved === undefined || resolved === null) {
+        throw new Error(`SmartBill mapping option "${field}" is required`);
+    }
+    return resolved;
+}
+async function resolveEventValue(event, value) {
+    return typeof value === "function"
+        ? await value(event)
+        : value;
+}
+async function resolveRequiredEventValue(event, value, field) {
+    const resolved = await resolveEventValue(event, value);
+    if (resolved === undefined || resolved === null) {
+        throw new Error(`SmartBill mapping option "${field}" is required`);
+    }
+    return resolved;
+}
+function isPromiseLike(value) {
+    return (value != null &&
+        typeof value === "object" &&
+        typeof value.then === "function");
+}
+function normalizeOptionalText(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
 function asString(value, fallback) {
     if (typeof value === "string" && value.length > 0)
         return value;

package/dist/plugin.d.ts

@@ -1,8 +1,8 @@
 import type { Plugin } from "@voyantjs/core";
 import { type SmartbillArtifactPersistenceOptions } from "./artifacts.js";
 import type { SmartbillClientOptions } from "./client.js";
-import type { mapVoyantInvoiceToSmartbill, SmartbillMappingOptions } from "./mapping.js";
-import type { VoyantInvoiceEvent } from "./types.js";
+import type { SmartbillMappingOptions } from "./mapping.js";
+import type { SmartbillInvoiceBody, VoyantInvoiceEvent } from "./types.js";
 export interface SmartbillSyncEventNames {
     issued?: string;
     proformaIssued?: string;
@@ -13,11 +13,22 @@ export interface SmartbillLogger {
     error: (message: string, meta?: unknown) => void;
     info?: (message: string, meta?: unknown) => void;
 }
-export type SmartbillMapFn = (event: VoyantInvoiceEvent) => ReturnType<typeof mapVoyantInvoiceToSmartbill>;
+export type SmartbillMapFn = (event: VoyantInvoiceEvent) => SmartbillInvoiceBody | Promise<SmartbillInvoiceBody>;
+export interface SmartbillIdempotencyOptions {
+    /**
+     * When artifact DB access is configured, skip SmartBill create calls for
+     * duplicate invoice events that already have a non-error SmartBill ref.
+     * Defaults to true.
+     */
+    skipExistingExternalRef?: boolean;
+}
+export type SmartbillErrorHandler = (event: VoyantInvoiceEvent, error: unknown) => void | Promise<void>;
 export interface SmartbillPluginOptions extends SmartbillClientOptions, SmartbillMappingOptions {
     events?: SmartbillSyncEventNames;
     mapEvent?: SmartbillMapFn;
     logger?: SmartbillLogger;
+    idempotency?: SmartbillIdempotencyOptions;
+    onError?: SmartbillErrorHandler;
     /**
      * 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;AAGxD,OAAO,EAEL,KAAK,mCAAmC,EAEzC,MAAM,gBAAgB,CAAA;AACvB,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AACzD,OAAO,KAAK,EAAE,2BAA2B,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AAExF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAGpD,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,UAAU,CAAC,OAAO,2BAA2B,CAAC,CAAA;AAEnD,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;;;;;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,CAwJvE"}
+{"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,CA6QvE"}

package/dist/plugin.js

@@ -1,5 +1,6 @@
+import { financeService } from "@voyantjs/finance";
 import { ZodError } from "zod";
-import { persistSmartbillInvoiceArtifact, } from "./artifacts.js";
+import { persistSmartbillInvoiceArtifact, retrySmartbillInvoiceArtifact, } from "./artifacts.js";
 import { createSmartbillSyncRuntime } from "./runtime.js";
 import { smartbillPluginOptionsSchema } from "./validation.js";
 function coerceEvent(data) {
@@ -15,7 +16,55 @@ function coerceEvent(data) {
 }
 export function smartbillPlugin(options) {
     const validatedOptions = parseSmartbillPluginOptions(options);
-    const { client, logger, mapEvent, eventNames, artifacts } = createSmartbillSyncRuntime(validatedOptions);
+    const { client, logger, mapEvent, eventNames, artifacts, idempotency, onError } = createSmartbillSyncRuntime(validatedOptions);
+    async function resolveMaybe(value, context) {
+        return typeof value === "function"
+            ? await value(context)
+            : value;
+    }
+    async function resolveArtifactDb(event, documentType, body, result) {
+        if (!artifacts.db)
+            return null;
+        const context = {
+            event,
+            documentType,
+            body: body ?? {
+                companyVatCode: validatedOptions.companyVatCode,
+                client: { name: "Client" },
+                seriesName: "unknown",
+                currency: "RON",
+                products: [],
+            },
+            result: result ?? {},
+        };
+        return (await resolveMaybe(artifacts.db, context)) ?? null;
+    }
+    async function findExistingSmartbillRef(event, documentType, body) {
+        if (idempotency.skipExistingExternalRef === false)
+            return null;
+        const db = await resolveArtifactDb(event, documentType, body);
+        if (!db)
+            return null;
+        const refs = await financeService.listInvoiceExternalRefs(db, event.id);
+        return refs.find((ref) => isUsableSmartbillRef(ref)) ?? null;
+    }
+    async function handleExistingSmartbillRef(event, documentType, externalRef) {
+        logger.info?.(`[smartbill] ${documentType} already has SmartBill ref for ${event.id}; skipping create`, externalRef);
+        try {
+            const persisted = await retrySmartbillInvoiceArtifact({
+                runtime: artifacts,
+                client,
+                externalRef,
+                documentType,
+            });
+            if (persisted.status === "persisted") {
+                logger.info?.(`[smartbill] ${documentType} PDF re-attached for ${event.id}`, persisted);
+            }
+        }
+        catch (err) {
+            logger.error(`[smartbill] artifact re-attach failed for ${event.id}`, err);
+        }
+    }
     async function persistArtifact(event, documentType, body, result) {
         try {
             const persisted = await persistSmartbillInvoiceArtifact({
@@ -34,6 +83,44 @@ export function smartbillPlugin(options) {
             logger.error(`[smartbill] artifact persistence failed for ${event.id}`, err);
         }
     }
+    async function recordSyncError(event, documentType, err) {
+        try {
+            await onError?.(event, err);
+        }
+        catch (handlerError) {
+            logger.error(`[smartbill] onError handler failed for ${event.id}`, handlerError);
+        }
+        try {
+            const db = await resolveArtifactDb(event, documentType);
+            if (!db)
+                return;
+            const refs = await financeService.listInvoiceExternalRefs(db, event.id);
+            if (refs.some((ref) => isUsableSmartbillRef(ref)))
+                return;
+            await financeService.registerInvoiceExternalRef(db, event.id, {
+                provider: "smartbill",
+                externalId: null,
+                externalNumber: null,
+                externalUrl: null,
+                status: "error",
+                syncedAt: new Date().toISOString(),
+                syncError: errorMessage(err),
+                metadata: { documentType },
+            });
+        }
+        catch (recordError) {
+            logger.error(`[smartbill] error external-ref recording failed for ${event.id}`, recordError);
+        }
+    }
+    async function resolveConfiguredSeriesName(event) {
+        const value = validatedOptions.seriesName;
+        return typeof value === "function" ? await value(event) : value;
+    }
+    async function resolveExternalSeriesName(event) {
+        return typeof event.externalSeriesName === "string"
+            ? event.externalSeriesName
+            : await resolveConfiguredSeriesName(event);
+    }
     const subscribers = [
         {
             event: eventNames.issued,
@@ -42,13 +129,19 @@ export function smartbillPlugin(options) {
                 if (!event)
                     return;
                 try {
-                    const body = mapEvent(event);
+                    const body = await mapEvent(event);
+                    const existingRef = await findExistingSmartbillRef(event, "invoice", body);
+                    if (existingRef) {
+                        await handleExistingSmartbillRef(event, "invoice", existingRef);
+                        return;
+                    }
                     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);
                 }
                 catch (err) {
                     logger.error(`[smartbill] createInvoice on "${eventNames.issued}" failed for ${event.id}`, err);
+                    await recordSyncError(event, "invoice", err);
                 }
             },
         },
@@ -61,13 +154,19 @@ export function smartbillPlugin(options) {
                 try {
                     // Same shape as createInvoice — SmartBill's `/proforma`
                     // endpoint accepts the same body as `/invoice`.
-                    const body = mapEvent(event);
+                    const body = await mapEvent(event);
+                    const existingRef = await findExistingSmartbillRef(event, "proforma", body);
+                    if (existingRef) {
+                        await handleExistingSmartbillRef(event, "proforma", existingRef);
+                        return;
+                    }
                     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);
                 }
                 catch (err) {
                     logger.error(`[smartbill] createProforma on "${eventNames.proformaIssued}" failed for ${event.id}`, err);
+                    await recordSyncError(event, "proforma", err);
                 }
             },
         },
@@ -78,9 +177,7 @@ export function smartbillPlugin(options) {
                 if (!event)
                     return;
                 try {
-                    const seriesName = typeof event.externalSeriesName === "string"
-                        ? event.externalSeriesName
-                        : validatedOptions.seriesName;
+                    const seriesName = await resolveExternalSeriesName(event);
                     const number = typeof event.externalNumber === "string"
                         ? event.externalNumber
                         : typeof event.invoiceNumber === "string"
@@ -105,9 +202,7 @@ export function smartbillPlugin(options) {
                 if (!event)
                     return;
                 try {
-                    const seriesName = typeof event.externalSeriesName === "string"
-                        ? event.externalSeriesName
-                        : validatedOptions.seriesName;
+                    const seriesName = await resolveExternalSeriesName(event);
                     const number = typeof event.externalNumber === "string"
                         ? event.externalNumber
                         : typeof event.invoiceNumber === "string"
@@ -137,6 +232,15 @@ export function smartbillPlugin(options) {
         subscribers,
     };
 }
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isUsableSmartbillRef(ref) {
+    return (ref.provider === "smartbill" &&
+        ref.status !== "error" &&
+        !ref.syncError &&
+        Boolean(ref.externalNumber || ref.externalId));
+}
 function parseSmartbillPluginOptions(options) {
     try {
         return smartbillPluginOptionsSchema.parse(options);

package/dist/runtime.d.ts

@@ -13,6 +13,8 @@ export interface SmartbillSyncRuntime {
     mapEvent: SmartbillMapFn;
     eventNames: ResolvedSmartbillSyncEventNames;
     artifacts: SmartbillArtifactPersistenceOptions;
+    idempotency: NonNullable<SmartbillPluginOptions["idempotency"]>;
+    onError: SmartbillPluginOptions["onError"];
 }
 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;CAC/C;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,sBAAsB,GAAG,oBAAoB,CAgChG"}
+{"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,CAuChG"}

package/dist/runtime.js

@@ -1,5 +1,5 @@
 import { createSmartbillClient } from "./client.js";
-import { mapVoyantInvoiceToSmartbill } from "./mapping.js";
+import { mapVoyantInvoiceToSmartbillAsync } from "./mapping.js";
 export function createSmartbillSyncRuntime(options) {
     const client = createSmartbillClient(options);
     const logger = options.logger ?? console;
@@ -9,9 +9,12 @@ export function createSmartbillSyncRuntime(options) {
         language: options.language,
         isTaxIncluded: options.isTaxIncluded,
         art311SpecialRegime: options.art311SpecialRegime,
+        art311SpecialRegimeText: options.art311SpecialRegimeText,
+        mentions: options.mentions,
+        observations: options.observations,
     };
     const mapEvent = options.mapEvent ??
-        ((event) => mapVoyantInvoiceToSmartbill(event, mappingOptions));
+        ((event) => mapVoyantInvoiceToSmartbillAsync(event, mappingOptions));
     const eventNames = {
         issued: options.events?.issued ?? "invoice.issued",
         proformaIssued: options.events?.proformaIssued ?? "invoice.proforma.issued",
@@ -28,5 +31,9 @@ export function createSmartbillSyncRuntime(options) {
             documentStorage: options.artifacts?.documentStorage ?? options.documentStorage,
             documentStorageKeyPrefix: options.artifacts?.documentStorageKeyPrefix ?? options.documentStorageKeyPrefix,
         },
+        idempotency: {
+            skipExistingExternalRef: options.idempotency?.skipExistingExternalRef ?? true,
+        },
+        onError: options.onError,
     };
 }

package/dist/settlement.d.ts

@@ -1,7 +1,7 @@
 import type { SmartbillClientOptions } from "./client.js";
 export interface SmartbillInvoiceSettlementPollerOptions extends SmartbillClientOptions {
     companyVatCode?: string;
-    seriesName?: string;
+    seriesName?: string | ((context: SmartbillSettlementSeriesContext) => string | null | undefined | Promise<string | null | undefined>);
 }
 export interface SmartbillSettlementInvoice {
     invoiceNumber: string;
@@ -15,6 +15,9 @@ export interface SmartbillSettlementPollerContext {
     invoice: SmartbillSettlementInvoice;
     externalRef: SmartbillSettlementExternalRef;
 }
+export interface SmartbillSettlementSeriesContext extends SmartbillSettlementPollerContext {
+    metadata: Record<string, unknown> | null;
+}
 export interface SmartbillSettlementPollerResult {
     externalId?: string | null;
     externalNumber?: string | null;

package/dist/settlement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"settlement.d.ts","sourceRoot":"","sources":["../src/settlement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAGzD,MAAM,WAAW,uCAAwC,SAAQ,sBAAsB;IACrF,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,0BAA0B;IACzC,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,8BAA8B;IAC7C,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,gCAAgC;IAC/C,OAAO,EAAE,0BAA0B,CAAA;IACnC,WAAW,EAAE,8BAA8B,CAAA;CAC5C;AAED,MAAM,WAAW,+BAA+B;IAC9C,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;CAC1C;AAED,MAAM,MAAM,gCAAgC,GAAG,CAC7C,OAAO,EAAE,gCAAgC,KACtC,OAAO,CAAC,+BAA+B,CAAC,CAAA;AAuD7C,wBAAgB,sCAAsC,CACpD,OAAO,EAAE,uCAAuC,GAC/C,gCAAgC,CA2ClC"}
+{"version":3,"file":"settlement.d.ts","sourceRoot":"","sources":["../src/settlement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAGzD,MAAM,WAAW,uCAAwC,SAAQ,sBAAsB;IACrF,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,UAAU,CAAC,EACP,MAAM,GACN,CAAC,CACC,OAAO,EAAE,gCAAgC,KACtC,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC,CAAA;CACzE;AAED,MAAM,WAAW,0BAA0B;IACzC,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,8BAA8B;IAC7C,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,gCAAgC;IAC/C,OAAO,EAAE,0BAA0B,CAAA;IACnC,WAAW,EAAE,8BAA8B,CAAA;CAC5C;AAED,MAAM,WAAW,gCAAiC,SAAQ,gCAAgC;IACxF,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;CACzC;AAED,MAAM,WAAW,+BAA+B;IAC9C,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;CAC1C;AAED,MAAM,MAAM,gCAAgC,GAAG,CAC7C,OAAO,EAAE,gCAAgC,KACtC,OAAO,CAAC,+BAA+B,CAAC,CAAA;AAyD7C,wBAAgB,sCAAsC,CACpD,OAAO,EAAE,uCAAuC,GAC/C,gCAAgC,CA4ClC"}

package/dist/settlement.js

@@ -13,11 +13,11 @@ function resolveCompanyVatCode(metadata, options) {
         options.companyVatCode ??
         null);
 }
-function resolveSeriesName(metadata, options) {
-    return (coerceString(metadata?.seriesName) ??
-        coerceString(metadata?.series) ??
-        options.seriesName ??
-        null);
+async function resolveSeriesName(metadata, options, context) {
+    const optionSeriesName = typeof options.seriesName === "function"
+        ? await options.seriesName({ ...context, metadata })
+        : options.seriesName;
+    return (coerceString(metadata?.seriesName) ?? coerceString(metadata?.series) ?? optionSeriesName ?? null);
 }
 function resolveInvoiceNumber(metadata, externalNumber, externalId, invoiceNumber) {
     return (coerceString(metadata?.number) ??
@@ -32,9 +32,10 @@ function toCents(value) {
 export function createSmartbillInvoiceSettlementPoller(options) {
     const client = createSmartbillClient(options);
     return async ({ invoice, externalRef }) => {
+        const context = { invoice, externalRef };
         const metadata = coerceMetadata(externalRef.metadata);
         const companyVatCode = resolveCompanyVatCode(metadata, options);
-        const seriesName = resolveSeriesName(metadata, options);
+        const seriesName = await resolveSeriesName(metadata, options, context);
         const number = resolveInvoiceNumber(metadata, externalRef.externalNumber, externalRef.externalId, invoice.invoiceNumber);
         if (!companyVatCode) {
             return { syncError: "SmartBill settlement polling requires companyVatCode" };

package/dist/validation.d.ts

@@ -1,20 +1,25 @@
 import { z } from "zod";
 import type { SmartbillArtifactPersistenceOptions, SmartbillDbResolver, SmartbillDocumentStorageResolver, SmartbillStorageKeyPrefixResolver } from "./artifacts.js";
-import type { SmartbillLogger, SmartbillMapFn, SmartbillSyncEventNames } from "./plugin.js";
+import type { SmartbillErrorHandler, SmartbillIdempotencyOptions, SmartbillLogger, SmartbillMapFn, SmartbillSyncEventNames } from "./plugin.js";
 import type { SmartbillFetch } from "./types.js";
 export declare const smartbillPluginOptionsSchema: z.ZodObject<{
     username: z.ZodString;
     apiToken: z.ZodString;
     companyVatCode: z.ZodString;
-    seriesName: z.ZodString;
+    seriesName: z.ZodCustom<import("./mapping.js").SmartbillEventValue<string>, import("./mapping.js").SmartbillEventValue<string>>;
     apiUrl: z.ZodOptional<z.ZodString>;
     fetch: z.ZodOptional<z.ZodCustom<SmartbillFetch | undefined, SmartbillFetch | undefined>>;
     language: z.ZodOptional<z.ZodString>;
     isTaxIncluded: z.ZodOptional<z.ZodBoolean>;
     art311SpecialRegime: z.ZodOptional<z.ZodBoolean>;
+    art311SpecialRegimeText: z.ZodOptional<z.ZodString>;
+    mentions: z.ZodOptional<z.ZodCustom<import("./mapping.js").SmartbillEventValue<string | null | undefined>, import("./mapping.js").SmartbillEventValue<string | null | undefined>>>;
+    observations: z.ZodOptional<z.ZodCustom<import("./mapping.js").SmartbillEventValue<string | null | undefined>, import("./mapping.js").SmartbillEventValue<string | null | undefined>>>;
     events: z.ZodOptional<z.ZodCustom<SmartbillSyncEventNames | undefined, SmartbillSyncEventNames | undefined>>;
     mapEvent: z.ZodOptional<z.ZodCustom<SmartbillMapFn | undefined, SmartbillMapFn | undefined>>;
     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>>;
     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;AACvB,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EAEd,uBAAuB,EACxB,MAAM,aAAa,CAAA;AACpB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AA+EhD,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;iBAiBK,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,eAAe,EACf,cAAc,EAEd,uBAAuB,EACxB,MAAM,aAAa,CAAA;AACpB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAyGhD,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;iBAsBK,CAAA"}

package/dist/validation.js

@@ -1,6 +1,10 @@
 import { z } from "zod";
 const optionalString = z.string().trim().min(1).optional();
 const optionalUrl = z.string().trim().url().optional();
+const requiredEventString = z.custom((value) => (typeof value === "string" && value.trim().length > 0) || typeof value === "function", "Expected a non-empty string or event resolver function");
+const optionalEventText = z.custom((value) => value === undefined ||
+    (typeof value === "string" && value.trim().length > 0) ||
+    typeof value === "function", "Expected a non-empty string or event resolver function");
 const optionalFetch = z.custom((value) => value === undefined || typeof value === "function", "Expected a fetch implementation function");
 const optionalLogger = z.custom((value) => value === undefined ||
     (typeof value === "object" &&
@@ -9,6 +13,7 @@ const optionalLogger = z.custom((value) => value === undefined ||
         ((value.info ?? undefined) === 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 optionalDb = z.custom((value) => value === undefined ||
     typeof value === "function" ||
     (typeof value === "object" && value !== null), "Expected a database handle or resolver function");
@@ -43,19 +48,33 @@ const optionalEvents = z.custom((value) => {
     const events = value;
     return [events.issued, events.proformaIssued, events.voided, events.syncRequested].every((entry) => entry === undefined || (typeof entry === "string" && entry.trim().length > 0));
 }, "Expected event names to be non-empty strings");
+const optionalIdempotency = z.custom((value) => {
+    if (value === undefined)
+        return true;
+    if (typeof value !== "object" || value === null)
+        return false;
+    const options = value;
+    return (options.skipExistingExternalRef === undefined ||
+        typeof options.skipExistingExternalRef === "boolean");
+}, "Expected valid SmartBill idempotency options");
 export const smartbillPluginOptionsSchema = z.object({
     username: z.string().trim().min(1),
     apiToken: z.string().trim().min(1),
     companyVatCode: z.string().trim().min(1),
-    seriesName: z.string().trim().min(1),
+    seriesName: requiredEventString,
     apiUrl: optionalUrl,
     fetch: optionalFetch.optional(),
     language: optionalString,
     isTaxIncluded: z.boolean().optional(),
     art311SpecialRegime: z.boolean().optional(),
+    art311SpecialRegimeText: optionalString,
+    mentions: optionalEventText.optional(),
+    observations: optionalEventText.optional(),
     events: optionalEvents.optional(),
     mapEvent: optionalMapEvent.optional(),
     logger: optionalLogger.optional(),
+    idempotency: optionalIdempotency.optional(),
+    onError: optionalOnError.optional(),
     artifacts: optionalArtifacts.optional(),
     db: optionalDb.optional(),
     documentStorage: optionalDocumentStorage.optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyantjs/plugin-smartbill",
-  "version": "0.38.1",
+  "version": "0.40.0",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
@@ -38,9 +38,9 @@
   "dependencies": {
     "drizzle-orm": "^0.45.2",
     "zod": "^4.3.6",
-    "@voyantjs/core": "0.38.1",
-    "@voyantjs/finance": "0.38.1",
-    "@voyantjs/storage": "0.38.1"
+    "@voyantjs/core": "0.40.0",
+    "@voyantjs/finance": "0.40.0",
+    "@voyantjs/storage": "0.40.0"
   },
   "devDependencies": {
     "typescript": "^6.0.2",