@voyantjs/plugin-smartbill 0.40.0 → 0.41.0

package/README.md

@@ -79,6 +79,46 @@ 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.
 
+## Workflow Factories
+
+The package also ships scheduler-agnostic workflow factories for recurring
+SmartBill maintenance. They return async functions that can be called from
+`@voyantjs/workflows`, a Cloudflare cron handler, Trigger.dev, Hatchet, or any
+other job runner.
+
+```typescript
+import {
+  createSmartbillDriftReconciler,
+  createSmartbillProformaConversionPoller,
+} from "@voyantjs/plugin-smartbill"
+
+const pollProformas = createSmartbillProformaConversionPoller({
+  db,
+  client: smartbillClient,
+  onConverted: async (proformaRef, conversion) => {
+    // Record a Voyant payment or emit a domain event in the host app.
+    // The plugin reports the SmartBill invoice series/number and source
+    // proforma ref, but leaves payment semantics to the consumer.
+  },
+})
+
+const reconcileSmartbill = createSmartbillDriftReconciler({
+  db,
+  client: smartbillClient,
+  listRemoteDocuments: async () => remoteSmartbillInventory,
+  onFinding: async (finding) => {
+    // Log, alert, or open an operator ticket.
+  },
+})
+```
+
+`createSmartbillProformaConversionPoller` scans SmartBill proforma external refs
+and calls `client.listEstimateInvoices(...)` to detect SmartBill-created final
+invoices. `createSmartbillDriftReconciler` verifies known SmartBill refs by
+default and can compare a caller-provided remote inventory for `missing_local`
+findings. The reconciler only reports drift; it does not delete, void, or create
+finance records.
+
 ## Exports
 
 | Entry | Description |
@@ -87,6 +127,7 @@ without issuing a new document.
 | `./plugin` | `smartbillPlugin(options)` — packaged adapter/subscriber bundle |
 | `./client` | `createSmartbillClient` — `createInvoice`, `cancelInvoice`, `viewPdf`, `getPaymentStatus`, etc. |
 | `./mock` | `createSmartbillMockServer` — stateful local SmartBill-compatible mock for tests |
+| `./workflows` | Proforma conversion polling and drift reconciliation factories |
 | `./types` | SmartBill adapter and bundle types |
 
 ## Local SmartBill Mock

package/dist/index.d.ts

@@ -13,4 +13,6 @@ export { createSmartbillSyncRuntime } from "./runtime.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";
+export type { SmartbillDriftFinding, SmartbillDriftFindingType, SmartbillDriftReconciler, SmartbillDriftReconcilerOptions, SmartbillDriftReconcilerResult, SmartbillProformaConversion, SmartbillProformaConversionPoller, SmartbillProformaConversionPollerOptions, SmartbillProformaConversionPollerResult, SmartbillReferenceParts, SmartbillRemoteDocument, SmartbillRemoteDocumentStatus, SmartbillWorkflowDocumentType, SmartbillWorkflowError, SmartbillWorkflowExternalRef, SmartbillWorkflowInvoice, SmartbillWorkflowLogger, } from "./workflows.js";
+export { createSmartbillDriftReconciler, createSmartbillProformaConversionPoller, } from "./workflows.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,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"}
+{"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"}

package/dist/index.js

@@ -5,3 +5,4 @@ export { createSmartbillMockServer } from "./mock.js";
 export { smartbillPlugin } from "./plugin.js";
 export { createSmartbillSyncRuntime } from "./runtime.js";
 export { createSmartbillInvoiceSettlementPoller } from "./settlement.js";
+export { createSmartbillDriftReconciler, createSmartbillProformaConversionPoller, } from "./workflows.js";

package/dist/workflows.d.ts

@@ -0,0 +1,119 @@
+import { type Invoice } from "@voyantjs/finance";
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import type { SmartbillClientApi } from "./client.js";
+import type { SmartbillEstimateInvoicesResponse, SmartbillInvoiceResponse } from "./types.js";
+export type SmartbillWorkflowDocumentType = "invoice" | "proforma";
+export interface SmartbillWorkflowLogger {
+    info?: (message: string, meta?: unknown) => void;
+    error?: (message: string, meta?: unknown) => void;
+}
+export interface SmartbillWorkflowInvoice {
+    id: string;
+    invoiceNumber: string;
+    invoiceType: Invoice["invoiceType"];
+    status: Invoice["status"];
+    currency: string;
+    totalCents: number;
+    paidCents: number;
+    balanceDueCents: number;
+}
+export interface SmartbillWorkflowExternalRef {
+    id: string;
+    invoiceId: string;
+    provider: string;
+    externalId: string | null;
+    externalNumber: string | null;
+    externalUrl: string | null;
+    status: string | null;
+    metadata: unknown;
+    syncError: string | null;
+    createdAt?: Date | null;
+    updatedAt?: Date | null;
+    invoice?: SmartbillWorkflowInvoice | null;
+}
+export interface SmartbillReferenceParts {
+    companyVatCode: string;
+    seriesName: string;
+    number: string;
+    documentType: SmartbillWorkflowDocumentType;
+}
+export interface SmartbillProformaConversion {
+    proformaRef: SmartbillWorkflowExternalRef;
+    invoice: SmartbillWorkflowInvoice | null;
+    companyVatCode: string;
+    proformaSeriesName: string;
+    proformaNumber: string;
+    invoiceSeriesName: string;
+    invoiceNumber: string;
+    invoiceUrl: string | null;
+    response: SmartbillEstimateInvoicesResponse;
+    smartbillInvoice: SmartbillInvoiceResponse;
+}
+export interface SmartbillProformaConversionPollerOptions {
+    db?: PostgresJsDatabase;
+    client: SmartbillClientApi;
+    limit?: number;
+    companyVatCode?: string;
+    logger?: SmartbillWorkflowLogger;
+    listExternalRefs?: () => Promise<SmartbillWorkflowExternalRef[]>;
+    onConverted: (proformaRef: SmartbillWorkflowExternalRef, conversion: SmartbillProformaConversion) => void | Promise<void>;
+    onError?: (error: SmartbillWorkflowError) => void | Promise<void>;
+}
+export interface SmartbillWorkflowError {
+    ref?: SmartbillWorkflowExternalRef;
+    error: unknown;
+}
+export interface SmartbillProformaConversionPollerResult {
+    checked: number;
+    converted: SmartbillProformaConversion[];
+    skipped: Array<{
+        ref: SmartbillWorkflowExternalRef;
+        reason: string;
+    }>;
+    errors: SmartbillWorkflowError[];
+}
+export type SmartbillRemoteDocumentStatus = "present" | "issued" | "paid" | "unpaid" | "partially_paid" | "voided" | "cancelled" | "reversed" | "deleted" | "missing";
+export interface SmartbillRemoteDocument extends SmartbillReferenceParts {
+    status?: SmartbillRemoteDocumentStatus;
+    metadata?: Record<string, unknown>;
+}
+export type SmartbillDriftFindingType = "missing_local" | "missing_remote" | "voided_remote";
+export interface SmartbillDriftFinding {
+    type: SmartbillDriftFindingType;
+    document: SmartbillReferenceParts;
+    ref?: SmartbillWorkflowExternalRef;
+    invoice?: SmartbillWorkflowInvoice | null;
+    remote?: SmartbillRemoteDocument | null;
+    error?: unknown;
+}
+export interface SmartbillDriftReconcilerOptions {
+    db?: PostgresJsDatabase;
+    client: SmartbillClientApi;
+    limit?: number;
+    companyVatCode?: string;
+    logger?: SmartbillWorkflowLogger;
+    listExternalRefs?: () => Promise<SmartbillWorkflowExternalRef[]>;
+    listRemoteDocuments?: (context: {
+        refs: SmartbillWorkflowExternalRef[];
+    }) => Promise<SmartbillRemoteDocument[]>;
+    verifyRemoteDocument?: (context: {
+        ref: SmartbillWorkflowExternalRef;
+        document: SmartbillReferenceParts;
+    }) => Promise<SmartbillRemoteDocumentStatus | SmartbillRemoteDocument>;
+    onFinding?: (finding: SmartbillDriftFinding) => void | Promise<void>;
+    onError?: (error: SmartbillWorkflowError) => void | Promise<void>;
+}
+export interface SmartbillDriftReconcilerResult {
+    checked: number;
+    findings: SmartbillDriftFinding[];
+    skipped: Array<{
+        ref: SmartbillWorkflowExternalRef;
+        reason: string;
+    }>;
+    errors: SmartbillWorkflowError[];
+}
+export type SmartbillProformaConversionPoller = () => Promise<SmartbillProformaConversionPollerResult>;
+export type SmartbillDriftReconciler = () => Promise<SmartbillDriftReconcilerResult>;
+export declare function createSmartbillProformaConversionPoller(options: SmartbillProformaConversionPollerOptions): SmartbillProformaConversionPoller;
+export declare function createSmartbillDriftReconciler(options: SmartbillDriftReconcilerOptions): SmartbillDriftReconciler;
+//# sourceMappingURL=workflows.d.ts.map

package/dist/workflows.d.ts.map

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

package/dist/workflows.js

@@ -0,0 +1,247 @@
+import { invoiceExternalRefs, invoices, } from "@voyantjs/finance";
+import { desc, eq } from "drizzle-orm";
+export function createSmartbillProformaConversionPoller(options) {
+    return async () => {
+        const result = {
+            checked: 0,
+            converted: [],
+            skipped: [],
+            errors: [],
+        };
+        const refs = await loadSmartbillExternalRefs(options);
+        for (const ref of refs) {
+            const document = resolveReferenceParts(ref, options.companyVatCode);
+            if (document?.documentType !== "proforma")
+                continue;
+            result.checked += 1;
+            try {
+                const response = await options.client.listEstimateInvoices(document.companyVatCode, document.seriesName, document.number);
+                const convertedInvoices = convertedInvoicesFromResponse(response);
+                if (convertedInvoices.length === 0) {
+                    result.skipped.push({ ref, reason: "not_converted" });
+                    continue;
+                }
+                for (const smartbillInvoice of convertedInvoices) {
+                    if (!smartbillInvoice.series || !smartbillInvoice.number) {
+                        result.skipped.push({ ref, reason: "missing_converted_invoice_number" });
+                        continue;
+                    }
+                    const conversion = {
+                        proformaRef: ref,
+                        invoice: ref.invoice ?? null,
+                        companyVatCode: document.companyVatCode,
+                        proformaSeriesName: document.seriesName,
+                        proformaNumber: document.number,
+                        invoiceSeriesName: smartbillInvoice.series,
+                        invoiceNumber: smartbillInvoice.number,
+                        invoiceUrl: smartbillInvoice.url ?? null,
+                        response,
+                        smartbillInvoice,
+                    };
+                    await options.onConverted(ref, conversion);
+                    options.logger?.info?.("[smartbill] proforma conversion detected", conversion);
+                    result.converted.push(conversion);
+                }
+            }
+            catch (error) {
+                await recordWorkflowError(options, result.errors, { ref, error });
+            }
+        }
+        return result;
+    };
+}
+export function createSmartbillDriftReconciler(options) {
+    return async () => {
+        const result = {
+            checked: 0,
+            findings: [],
+            skipped: [],
+            errors: [],
+        };
+        const refs = await loadSmartbillExternalRefs(options);
+        const remoteDocuments = await options.listRemoteDocuments?.({ refs });
+        const remoteDocumentMap = new Map((remoteDocuments ?? []).map((remote) => [documentKey(remote), remote]));
+        const hasRemoteInventory = remoteDocuments !== undefined;
+        const localDocuments = new Map();
+        for (const ref of refs) {
+            const document = resolveReferenceParts(ref, options.companyVatCode);
+            if (!document) {
+                result.skipped.push({ ref, reason: "missing_smartbill_reference" });
+                continue;
+            }
+            const key = documentKey(document);
+            localDocuments.set(key, document);
+            result.checked += 1;
+            try {
+                const remote = hasRemoteInventory
+                    ? (remoteDocumentMap.get(key) ?? { ...document, status: "missing" })
+                    : await verifyRemoteDocument(options, ref, document);
+                if (remote.status === "missing" || remote.status === "deleted") {
+                    await recordFinding(options, result.findings, {
+                        type: "missing_remote",
+                        document,
+                        ref,
+                        invoice: ref.invoice ?? null,
+                        remote,
+                    });
+                }
+                else if (isVoidedRemote(remote.status) && ref.invoice?.status !== "void") {
+                    await recordFinding(options, result.findings, {
+                        type: "voided_remote",
+                        document,
+                        ref,
+                        invoice: ref.invoice ?? null,
+                        remote,
+                    });
+                }
+            }
+            catch (error) {
+                await recordWorkflowError(options, result.errors, { ref, error });
+                await recordFinding(options, result.findings, {
+                    type: "missing_remote",
+                    document,
+                    ref,
+                    invoice: ref.invoice ?? null,
+                    remote: null,
+                    error,
+                });
+            }
+        }
+        for (const remote of remoteDocuments ?? []) {
+            if (!localDocuments.has(documentKey(remote))) {
+                await recordFinding(options, result.findings, {
+                    type: "missing_local",
+                    document: remote,
+                    remote,
+                });
+            }
+        }
+        return result;
+    };
+}
+async function loadSmartbillExternalRefs(options) {
+    if (options.listExternalRefs)
+        return options.listExternalRefs();
+    if (!options.db)
+        throw new Error("SmartBill workflow requires db or listExternalRefs");
+    const rows = await options.db
+        .select({
+        ref: invoiceExternalRefs,
+        invoice: {
+            id: invoices.id,
+            invoiceNumber: invoices.invoiceNumber,
+            invoiceType: invoices.invoiceType,
+            status: invoices.status,
+            currency: invoices.currency,
+            totalCents: invoices.totalCents,
+            paidCents: invoices.paidCents,
+            balanceDueCents: invoices.balanceDueCents,
+        },
+    })
+        .from(invoiceExternalRefs)
+        .leftJoin(invoices, eq(invoiceExternalRefs.invoiceId, invoices.id))
+        .where(eq(invoiceExternalRefs.provider, "smartbill"))
+        .orderBy(desc(invoiceExternalRefs.createdAt))
+        .limit(options.limit ?? 500);
+    return rows.map((row) => toWorkflowExternalRef(row.ref, row.invoice));
+}
+function toWorkflowExternalRef(ref, invoice) {
+    return {
+        id: ref.id,
+        invoiceId: ref.invoiceId,
+        provider: ref.provider,
+        externalId: ref.externalId,
+        externalNumber: ref.externalNumber,
+        externalUrl: ref.externalUrl,
+        status: ref.status,
+        metadata: ref.metadata,
+        syncError: ref.syncError,
+        createdAt: ref.createdAt,
+        updatedAt: ref.updatedAt,
+        invoice,
+    };
+}
+function convertedInvoicesFromResponse(response) {
+    if (Array.isArray(response.invoices) && response.invoices.length > 0) {
+        return response.invoices.filter((invoice) => invoice.series && invoice.number);
+    }
+    if (response.areInvoicesCreated && response.series && response.number) {
+        return [{ series: response.series, number: response.number }];
+    }
+    return [];
+}
+async function verifyRemoteDocument(options, ref, document) {
+    const verified = await (options.verifyRemoteDocument
+        ? options.verifyRemoteDocument({ ref, document })
+        : defaultVerifyRemoteDocument(options.client, document));
+    return typeof verified === "string" ? { ...document, status: verified } : verified;
+}
+async function defaultVerifyRemoteDocument(client, document) {
+    if (document.documentType === "proforma") {
+        await client.listEstimateInvoices(document.companyVatCode, document.seriesName, document.number);
+        return "present";
+    }
+    const status = await client.getPaymentStatus(document.companyVatCode, document.seriesName, document.number);
+    return paymentStatusToRemoteStatus(status);
+}
+function paymentStatusToRemoteStatus(status) {
+    const providerStatus = `${status.message ?? ""} ${status.errorText ?? ""}`.toLowerCase();
+    if (providerStatus.includes("cancel"))
+        return "cancelled";
+    if (providerStatus.includes("reverse"))
+        return "reversed";
+    if (providerStatus.includes("void"))
+        return "voided";
+    if (providerStatus.includes("delete"))
+        return "deleted";
+    if (status.paid)
+        return "paid";
+    if ((status.paidAmount ?? 0) > 0)
+        return "partially_paid";
+    return "unpaid";
+}
+function resolveReferenceParts(ref, fallbackCompanyVatCode) {
+    const metadata = coerceMetadata(ref.metadata);
+    const documentType = coerceDocumentType(metadata?.documentType);
+    const companyVatCode = metadataString(metadata, "companyVatCode") ??
+        metadataString(metadata, "vatCode") ??
+        fallbackCompanyVatCode;
+    const seriesName = metadataString(metadata, "series") ?? metadataString(metadata, "seriesName");
+    const number = metadataString(metadata, "number") ?? ref.externalNumber ?? ref.externalId;
+    if (!documentType || !companyVatCode || !seriesName || !number)
+        return null;
+    return { companyVatCode, seriesName, number, documentType };
+}
+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;
+}
+function coerceDocumentType(value) {
+    return value === "invoice" || value === "proforma" ? value : null;
+}
+function documentKey(document) {
+    return [
+        document.documentType,
+        document.companyVatCode,
+        document.seriesName,
+        document.number,
+    ].join(":");
+}
+function isVoidedRemote(status) {
+    return status === "voided" || status === "cancelled" || status === "reversed";
+}
+async function recordFinding(options, findings, finding) {
+    findings.push(finding);
+    options.logger?.info?.("[smartbill] drift finding", finding);
+    await options.onFinding?.(finding);
+}
+async function recordWorkflowError(options, errors, error) {
+    errors.push(error);
+    options.logger?.error?.("[smartbill] workflow error", error);
+    await options.onError?.(error);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyantjs/plugin-smartbill",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
@@ -29,6 +29,11 @@
       "import": "./dist/settlement.js",
       "default": "./dist/settlement.js"
     },
+    "./workflows": {
+      "types": "./dist/workflows.d.ts",
+      "import": "./dist/workflows.js",
+      "default": "./dist/workflows.js"
+    },
     "./types": {
       "types": "./dist/types.d.ts",
       "import": "./dist/types.js",
@@ -38,9 +43,9 @@
   "dependencies": {
     "drizzle-orm": "^0.45.2",
     "zod": "^4.3.6",
-    "@voyantjs/core": "0.40.0",
-    "@voyantjs/finance": "0.40.0",
-    "@voyantjs/storage": "0.40.0"
+    "@voyantjs/core": "0.41.0",
+    "@voyantjs/finance": "0.41.0",
+    "@voyantjs/storage": "0.41.0"
   },
   "devDependencies": {
     "typescript": "^6.0.2",