@openlup/platform 0.21.0 → 0.23.0

package/dist/fulfillment/replacementRefusals.js

@@ -0,0 +1,38 @@
+export const FULFILLMENT_REPLACEMENT_COMMAND_REFUSALS = [
+    "invalid_input",
+    "idempotency_conflict",
+    "order_not_found",
+    "order_not_replaceable",
+    "missing_client",
+    "missing_shipping_address",
+    "shipping_address_not_found",
+    "payment_not_succeeded",
+    "subscription_cycle_not_paid",
+    "no_parcel_to_replace",
+    "undispatched_replacement_exists",
+    "missing_order_items",
+    "missing_catalog_sku",
+    "missing_inventory_reservation",
+    "blocked_by_payment_not_succeeded_hold",
+    "blocked_by_inventory_review_hold",
+    "blocked_by_risk_review_hold",
+    "blocked_by_address_review_hold",
+    "blocked_by_manual_support_hold",
+];
+export const FULFILLMENT_REPLACEMENT_RESERVATION_REFUSALS = [
+    "inventory_external_provider_insufficient_available_stock",
+    "inventory_external_provider_stock_stale",
+    "inventory_external_provider_stock_missing",
+    "inventory_external_provider_sku_not_found",
+    "inventory_external_provider_location_missing",
+    "inventory_reservation_insufficient_available_stock",
+    "inventory_reservation_allocation_incomplete",
+    "inventory_reservation_payment_status_not_reservable",
+    "inventory_reservation_invalid_quantity",
+];
+export const UNSPECIFIED_FULFILLMENT_REPLACEMENT_REFUSAL = "unspecified_refusal";
+export const FULFILLMENT_REPLACEMENT_REFUSALS = [
+    ...FULFILLMENT_REPLACEMENT_COMMAND_REFUSALS,
+    ...FULFILLMENT_REPLACEMENT_RESERVATION_REFUSALS,
+    UNSPECIFIED_FULFILLMENT_REPLACEMENT_REFUSAL,
+];

package/dist/fulfillment/replacementShipmentHandler.d.ts

@@ -0,0 +1,5 @@
+import { type BaseDeps, type FulfillmentHandlerRequest } from './handlerSupport.js';
+import type { FulfillmentReplacementPort } from './contracts/replacement.js';
+export declare function createAdminCommerceOrderRequestReplacementShipmentHandler<Response>({ authorizeAdmin, respond, omsPort, }: BaseDeps<Response> & {
+    omsPort: FulfillmentReplacementPort;
+}): (req: FulfillmentHandlerRequest, res: Response) => Promise<void>;

package/dist/fulfillment/replacementShipmentHandler.js

@@ -0,0 +1,46 @@
+import { adminCommerceOrderRequestReplacementShipmentRequestSchema, adminCommerceOrderRequestReplacementShipmentResponseSchema } from './handlerSchemas.js';
+import { authorize, CommerceFulfillmentConflictError, isNativeUnsupported } from './handlerSupport.js';
+export function createAdminCommerceOrderRequestReplacementShipmentHandler({ authorizeAdmin, respond, omsPort, }) {
+    const { sendMethodNotAllowed } = respond;
+    return async function handler(req, res) {
+        if (req.method !== "POST")
+            return sendMethodNotAllowed(res, ["POST"]);
+        const auth = await authorize(req, res, authorizeAdmin, respond);
+        if (!auth)
+            return;
+        const request = parseOmsRequest(res, respond, adminCommerceOrderRequestReplacementShipmentRequestSchema, req.body ?? {}, "Invalid admin commerce replacement shipment request");
+        if (request === undefined)
+            return;
+        await sendOmsMutationResponse(res, respond, () => omsPort.requestReplacementShipment({ ...request, actorUserId: auth.userId }), adminCommerceOrderRequestReplacementShipmentResponseSchema, "Admin commerce replacement shipment returned invalid response", "Admin commerce replacement shipment failed");
+    };
+}
+function parseOmsRequest(res, respond, schema, input, message) {
+    const request = schema.safeParse(input);
+    if (!request.success) {
+        respond.sendBffError(res, 'BAD_REQUEST', message, { details: request.error.flatten() });
+        return undefined;
+    }
+    return request.data;
+}
+async function sendOmsMutationResponse(res, respond, action, schema, invalidMessage, failureMessage) {
+    try {
+        const result = await action();
+        if (isNativeUnsupported(result)) {
+            respond.sendBffError(res, 'UPSTREAM_UNAVAILABLE', 'Native fulfillment operation unsupported', { details: result });
+            return;
+        }
+        const response = schema.safeParse(result);
+        if (!response.success) {
+            respond.sendBffError(res, 'INVALID_RESPONSE', invalidMessage);
+            return;
+        }
+        respond.sendBffSuccess(res, response.data);
+    }
+    catch (error) {
+        if (error instanceof CommerceFulfillmentConflictError) {
+            respond.sendBffError(res, 'CONFLICT', error.message, { details: error.details });
+            return;
+        }
+        respond.sendBffError(res, 'UPSTREAM_UNAVAILABLE', failureMessage);
+    }
+}

package/dist/fulfillment/schemaCapabilities.d.ts

@@ -0,0 +1,13 @@
+/** Sparse projections require the full canonical graph and a trusted native binding. */
+export declare const FULFILLMENT_NATIVE_CAPABILITIES: {
+    readonly shipment: "supported";
+    readonly commandFence: "supported";
+    readonly deliveryAlignment: "supported";
+    readonly stockEvidence: "supported";
+    readonly observationPersistence: "supported";
+    readonly localInventoryBalances: "host_required";
+    readonly dispatchContactPreparation: "host_required";
+    readonly productPacks: "unsupported";
+    readonly providerAccess: "unsupported";
+    readonly automaticReplacementConfirmation: "unsupported";
+};

package/dist/fulfillment/schemaCapabilities.js

@@ -0,0 +1,7 @@
+/** Sparse projections require the full canonical graph and a trusted native binding. */
+export const FULFILLMENT_NATIVE_CAPABILITIES = {
+    shipment: 'supported', commandFence: 'supported', deliveryAlignment: 'supported',
+    stockEvidence: 'supported', observationPersistence: 'supported',
+    localInventoryBalances: 'host_required', dispatchContactPreparation: 'host_required',
+    productPacks: 'unsupported', providerAccess: 'unsupported', automaticReplacementConfirmation: 'unsupported',
+};

package/dist/fulfillment/shipmentsOverviewHandler.d.ts

@@ -0,0 +1,16 @@
+import { type FulfillmentHandlerRequest, type FulfillmentHandlerResponder } from './handlerSupport.js';
+import type { FulfillmentShipmentsOverviewPort, FulfillmentShipmentsOverviewResponse } from './contracts/read.js';
+export interface FulfillmentShipmentsOverviewHandlerDeps<Response> {
+    respond: FulfillmentHandlerResponder<Response>;
+    overviewPort: FulfillmentShipmentsOverviewPort;
+    responseSchema: {
+        safeParse(input: unknown): {
+            success: true;
+            data: FulfillmentShipmentsOverviewResponse;
+        } | {
+            success: false;
+        };
+    };
+    authorizeAdmin: (req: FulfillmentHandlerRequest) => Promise<boolean>;
+}
+export declare function createFulfillmentShipmentsOverviewHandler<Response>({ respond, overviewPort, responseSchema: adminShipmentsOverviewResponseSchema, authorizeAdmin, }: FulfillmentShipmentsOverviewHandlerDeps<Response>): (req: FulfillmentHandlerRequest, res: Response) => Promise<void>;

package/dist/fulfillment/shipmentsOverviewHandler.js

@@ -0,0 +1,54 @@
+import { isNativeUnsupported } from './handlerSupport.js';
+import { z } from 'zod';
+const adminShipmentsOverviewRequestSchema = z.object({
+    shippedFilter: z.enum(['today', '7d', '30d', 'all']).default('7d'),
+});
+export function createFulfillmentShipmentsOverviewHandler({ respond, overviewPort, responseSchema: adminShipmentsOverviewResponseSchema, authorizeAdmin, }) {
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = respond;
+    return async function handler(req, res) {
+        if (req.method !== "GET") {
+            sendMethodNotAllowed(res, ["GET"]);
+            return;
+        }
+        let authorized = false;
+        try {
+            authorized = await authorizeAdmin(req);
+        }
+        catch {
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin authorization failed");
+            return;
+        }
+        if (!authorized) {
+            sendBffError(res, "UNAUTHORIZED", "Admin session required");
+            return;
+        }
+        const request = adminShipmentsOverviewRequestSchema.safeParse({
+            shippedFilter: scalarQuery(req.query.shippedFilter),
+        });
+        if (!request.success) {
+            sendBffError(res, "BAD_REQUEST", "Invalid shipments overview request", {
+                details: request.error.flatten(),
+            });
+            return;
+        }
+        try {
+            const result = await overviewPort.getShipmentsOverview(request.data);
+            if (isNativeUnsupported(result)) {
+                sendBffError(res, "UPSTREAM_UNAVAILABLE", "Native fulfillment operation unsupported", { details: result });
+                return;
+            }
+            const response = adminShipmentsOverviewResponseSchema.safeParse(result);
+            if (!response.success) {
+                sendBffError(res, "INVALID_RESPONSE", "Shipments overview returned invalid response");
+                return;
+            }
+            sendBffSuccess(res, response.data);
+        }
+        catch {
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Shipments overview read failed");
+        }
+    };
+}
+function scalarQuery(value) {
+    return Array.isArray(value) ? value[0] : value;
+}

package/dist/fulfillment/statusMap.d.ts

@@ -0,0 +1,2 @@
+export { FULFILLMENT_STATUS_MAP, CANONICAL_LOCAL_FULFILLMENT_STATUSES, CUSTOMER_STEP_SEQUENCE, canonicalStatusToken, stepForToken, customerStepFromSignals, phaseIndexForStep, stepLabelKey, timelineLabelForStep, trackingPhaseKeyForStep, stepUsesTruckIcon } from "@openlup/core/fulfillment";
+export type { FulfillmentStatusStage, FulfillmentStatusMap } from "@openlup/core/fulfillment";

package/dist/fulfillment/statusMap.js

@@ -0,0 +1 @@
+export { FULFILLMENT_STATUS_MAP, CANONICAL_LOCAL_FULFILLMENT_STATUSES, CUSTOMER_STEP_SEQUENCE, canonicalStatusToken, stepForToken, customerStepFromSignals, phaseIndexForStep, stepLabelKey, timelineLabelForStep, trackingPhaseKeyForStep, stepUsesTruckIcon } from "@openlup/core/fulfillment";

package/dist/fulfillment/trackingProgress.d.ts

@@ -0,0 +1 @@
+export { fulfillmentProgressPresentation } from "@openlup/core/fulfillment";

package/dist/fulfillment/trackingProgress.js

@@ -0,0 +1 @@
+export { fulfillmentProgressPresentation } from "@openlup/core/fulfillment";

package/dist/fulfillment/verifiedIngress.d.ts

@@ -0,0 +1,79 @@
+import type { FulfillmentObservation, FulfillmentObservationCodecs, FulfillmentObservationPort, FulfillmentRefusal } from "./contracts/index.js";
+import { applyFulfillmentObservationEffects } from "./fulfillmentObservationEffects.js";
+type EffectInput = Parameters<typeof applyFulfillmentObservationEffects<FulfillmentObservation["fact"]["canonicalStatus"], "in_transit" | "delivered">>[0];
+type DispatchRef = {
+    orderRef: string;
+    fulfillmentRef: string;
+    dispatchRef: string;
+    externalRef: string | null;
+};
+export interface FulfillmentIngressCounts {
+    invalidTimestamps: number;
+    rejectedCorrelationRefs: number;
+    rejectedTrackingRefs: number;
+    rejectedTrackingUrls: number;
+}
+export type FulfillmentIngressResult = {
+    counts: FulfillmentIngressCounts;
+} & ({
+    kind: "refused";
+    receiptId: null;
+    refusal: FulfillmentRefusal;
+    diagnostics?: {
+        invalidTimestamp?: true;
+        rejectedCorrelationRefs?: number;
+    };
+} | {
+    kind: "processed" | "ignored" | "superseded";
+    receiptId: string;
+    observation: FulfillmentObservation;
+    replayed: boolean;
+    trackingRefs: number;
+    trackingReadBacks: number;
+    supersededCause?: string;
+});
+/** Safe response classes only; the host owns HTTP and localized message text. */
+export declare function fulfillmentIngressHttpResult(result: FulfillmentIngressResult): {
+    status: 200 | 400 | 403 | 503;
+    messageClass: "accepted" | "bad_request" | "forbidden" | "upstream_unavailable";
+};
+/** Adapter verification owns auth-before-parse; the host owns durable replay. */
+export declare function verifyAndNormalizeFulfillmentObservation(input: {
+    enabled: boolean;
+    approveTrackingUrl?(url: string): boolean;
+    observationCodecs?: FulfillmentObservationCodecs;
+    provider: FulfillmentObservationPort;
+    verification: Parameters<FulfillmentObservationPort["verifyAndNormalize"]>[0];
+    localPersistence: {
+        /** G17: atomic insert by eventKey; retries keep the first stored firstReceivedAt. */
+        recordObservation(observation: FulfillmentObservation): Promise<{
+            replayed: boolean;
+            receiptId?: string;
+        }>;
+        /** Idempotent; only called after completion or a classified superseding conflict. */
+        markProcessed(eventKey: string, outcome: {
+            status: "processed" | "ignored";
+            refusal?: FulfillmentRefusal;
+            supersededCause?: string;
+        }): Promise<void>;
+    };
+    lifecycle: {
+        findDispatchRef(observation: FulfillmentObservation): Promise<DispatchRef | null>;
+        acknowledgeDispatchAcceptance(ref: DispatchRef, observation: FulfillmentObservation): Promise<void>;
+        recordStatusEvidence(ref: DispatchRef, observation: FulfillmentObservation): Promise<{
+            replayed: boolean;
+        }>;
+        effects: EffectInput["port"];
+        keys: {
+            stock(ref: string): string;
+            handoff(ref: string): string;
+            tracking(eventKey: string, number: string): string;
+        };
+        issueAccountingInvoice?(ref: string): Promise<void>;
+        /** Return a machine identity, never exception prose. */
+        supersededCause?(error: unknown): string | null;
+        classifyFailure(error: unknown): "stock_contention" | "state_conflict" | "other";
+        annotateStockContention?(eventKey: string, fulfillmentRef: string): Promise<void>;
+    };
+}): Promise<FulfillmentIngressResult>;
+export {};

package/dist/fulfillment/verifiedIngress.js

@@ -0,0 +1,94 @@
+import { safeDiagnosticCode } from "./dispatchProjection.js";
+import { applyFulfillmentObservationEffects } from "./fulfillmentObservationEffects.js";
+import { observationStatusPolicy, projectObservation } from "./observationProjection.js";
+import { uniqueTrackingReferences } from "./providerTrackingReferences.js";
+/** Safe response classes only; the host owns HTTP and localized message text. */
+export function fulfillmentIngressHttpResult(result) {
+    if (result.kind !== "refused")
+        return { status: 200, messageClass: "accepted" };
+    if (result.refusal.reason === "untrusted")
+        return { status: 403, messageClass: "forbidden" };
+    if (result.refusal.reason === "disabled" || result.refusal.reason === "not_ready" || result.refusal.retryable)
+        return { status: 503, messageClass: "upstream_unavailable" };
+    return { status: 400, messageClass: "bad_request" };
+}
+/** Adapter verification owns auth-before-parse; the host owns durable replay. */
+export async function verifyAndNormalizeFulfillmentObservation(input) {
+    const counts = { invalidTimestamps: 0, rejectedCorrelationRefs: 0, rejectedTrackingRefs: 0, rejectedTrackingUrls: 0 };
+    if (!input.enabled)
+        return { kind: "refused", receiptId: null, counts, refusal: { reason: "disabled", phase: "verify", retryable: false } };
+    const verified = await input.provider.verifyAndNormalize(input.verification);
+    if (verified.kind === "refused") {
+        if (verified.diagnostics?.invalidTimestamp)
+            counts.invalidTimestamps++;
+        const rejected = verified.diagnostics?.rejectedCorrelationRefs;
+        if (typeof rejected === "number" && Number.isSafeInteger(rejected) && rejected > 0)
+            counts.rejectedCorrelationRefs = rejected;
+        return { kind: "refused", receiptId: null, refusal: verified.refusal, counts,
+            ...(counts.invalidTimestamps || counts.rejectedCorrelationRefs ? { diagnostics: {
+                    ...(counts.invalidTimestamps ? { invalidTimestamp: true } : {}),
+                    ...(counts.rejectedCorrelationRefs ? { rejectedCorrelationRefs: counts.rejectedCorrelationRefs } : {}),
+                } } : {}) };
+    }
+    const observation = projectObservation(verified.observation, input.approveTrackingUrl, input.observationCodecs);
+    counts.rejectedTrackingRefs = observation.diagnostics?.admission?.rejectedTrackingRefs ?? 0;
+    counts.rejectedTrackingUrls = observation.diagnostics?.admission?.rejectedTrackingUrls ?? 0;
+    const inbound = await input.localPersistence.recordObservation(observation);
+    const receiptId = inbound.receiptId ?? observation.eventKey;
+    const ref = await input.lifecycle.findDispatchRef(observation);
+    if (!ref) {
+        await input.localPersistence.markProcessed(observation.eventKey, { status: "ignored", refusal: { reason: "local_missing", phase: "apply", retryable: false } });
+        return { kind: "ignored", receiptId, counts, observation, replayed: inbound.replayed, trackingRefs: 0, trackingReadBacks: 0 };
+    }
+    const externalRef = observation.correlation.externalRef?.trim() || ref.externalRef?.trim();
+    if (!externalRef)
+        throw new TypeError("fulfillment_dispatch_acceptance_external_ref_missing");
+    await input.lifecycle.acknowledgeDispatchAcceptance(ref, observation);
+    const statusEvidence = await input.lifecycle.recordStatusEvidence(ref, observation);
+    let trackingRefs = 0;
+    let trackingReadBacks = 0;
+    const effectPort = {
+        ...input.lifecycle.effects,
+        async markProviderStockConsumed(request) {
+            try {
+                return await input.lifecycle.effects.markProviderStockConsumed(request);
+            }
+            catch (error) {
+                if (input.lifecycle.classifyFailure(error) === "stock_contention") {
+                    try {
+                        await input.lifecycle.annotateStockContention?.(observation.eventKey, ref.fulfillmentRef);
+                    }
+                    catch { /* Annotation is best-effort; preserve the original stock failure. */ }
+                }
+                throw error;
+            }
+        },
+    };
+    const localStatus = observation.fact.canonicalStatus;
+    const effects = {
+        port: effectPort, localStatus, ids: { orderId: ref.orderRef, fulfillmentOrderId: ref.fulfillmentRef }, observation,
+        trackingRefs: uniqueTrackingReferences(observation.trackingRefs).map(tracking => ({ trackingNumber: tracking.trackingNumber, trackingUrl: tracking.publicUrl, carrierKind: tracking.carrierRef, service: tracking.serviceRef })),
+        stockIdempotencyKey: input.lifecycle.keys.stock(ref.fulfillmentRef), handoffIdempotencyKey: input.lifecycle.keys.handoff(ref.fulfillmentRef),
+        trackingIdempotencyKey: number => input.lifecycle.keys.tracking(observation.eventKey, number),
+        issueAccountingInvoice: input.lifecycle.issueAccountingInvoice ? () => input.lifecycle.issueAccountingInvoice(ref.fulfillmentRef) : undefined,
+        onTrackingRecorded: result => { trackingRefs += result.replayed ? 0 : 1; trackingReadBacks += result.readBack ? 1 : 0; },
+    };
+    if (!observationStatusPolicy.handsOver(localStatus))
+        await applyFulfillmentObservationEffects({ ...effects, trackingRefs: [] }, observationStatusPolicy);
+    else {
+        try {
+            await applyFulfillmentObservationEffects(effects, observationStatusPolicy);
+        }
+        catch (error) {
+            if (input.lifecycle.classifyFailure(error) !== "state_conflict")
+                throw error;
+            const cause = input.lifecycle.supersededCause ? input.lifecycle.supersededCause(error)
+                : error && typeof error === "object" && "reason" in error ? error.reason : null;
+            const supersededCause = safeDiagnosticCode(cause) ?? "fulfillment_state_conflict";
+            await input.localPersistence.markProcessed(observation.eventKey, { status: "processed", supersededCause });
+            return { kind: "superseded", receiptId, counts, supersededCause, observation, replayed: inbound.replayed || statusEvidence.replayed, trackingRefs, trackingReadBacks };
+        }
+    }
+    await input.localPersistence.markProcessed(observation.eventKey, { status: "processed" });
+    return { kind: "processed", receiptId, counts, observation, replayed: inbound.replayed || statusEvidence.replayed, trackingRefs, trackingReadBacks };
+}

package/dist/invoicing/capabilities.d.ts

@@ -0,0 +1,11 @@
+import type { InvoiceCapabilities, InvoiceCapabilitySelection } from "./contracts/capabilities.js";
+/** @consumer Host readiness / installed cold consumer. Default off and explicit
+ * provider selection precede capability use; construction never selects a provider.
+ */
+export declare function readInvoiceCapabilities(input: {
+    readonly enabled?: boolean;
+    readonly selection: {
+        readonly providerRef: string;
+    } | null;
+    readonly capability: InvoiceCapabilities | null;
+}): InvoiceCapabilitySelection;

package/dist/invoicing/capabilities.js

@@ -0,0 +1,10 @@
+/** @consumer Host readiness / installed cold consumer. Default off and explicit
+ * provider selection precede capability use; construction never selects a provider.
+ */
+export function readInvoiceCapabilities(input) {
+    if (input.enabled !== true)
+        return { kind: "refused", code: "disabled", retryable: false, effectMayHaveSucceeded: false };
+    if (!input.selection || !input.capability || input.selection.providerRef !== input.capability.providerRef)
+        return { kind: "refused", code: "selection_required", retryable: false, effectMayHaveSucceeded: false };
+    return { kind: "ready", capability: input.capability };
+}

package/dist/invoicing/contracts/capabilities.d.ts

@@ -0,0 +1,40 @@
+import type { InvoiceDiagnosticCode, InvoiceUnsupported } from "./provider.js";
+export interface InvoiceCapabilities {
+    readonly version: "invoicing.capabilities.v1";
+    readonly providerRef: string;
+    readonly fiscalScope: {
+        readonly scopeRef: string;
+        readonly version: string;
+    };
+    readonly policies: {
+        readonly identifierRef: string;
+        readonly taxRef: string;
+        readonly roundingRef: string;
+    };
+    readonly documentKinds: readonly string[];
+    readonly correctionKinds: readonly "full_reversal"[];
+    readonly numberingOwner: "provider";
+    readonly sellerTiming: "execution" | "first_claim";
+    readonly operations: Readonly<Record<"issue" | "correction" | "recovery" | "readback" | "exactAbsence" | "artifact" | "clearance" | "settlement" | "companyLookup", {
+        readonly supported: true;
+    } | {
+        readonly supported: false;
+        readonly reason: "host_required" | "not_implemented" | "not_exposed";
+    }>> & {
+        readonly remoteVoid: {
+            readonly supported: false;
+            readonly reason: "not_implemented";
+        };
+    };
+    readonly defaultOff: true;
+}
+/** Interpretation only: no environment discovery, activation, writes or provider calls. */
+export type InvoiceCapabilitySelection = InvoiceUnsupported | {
+    readonly kind: "ready";
+    readonly capability: InvoiceCapabilities;
+} | {
+    readonly kind: "refused";
+    readonly code: Extract<InvoiceDiagnosticCode, "disabled" | "selection_required">;
+    readonly retryable: false;
+    readonly effectMayHaveSucceeded: false;
+};

package/dist/invoicing/contracts/capabilities.js

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

package/dist/invoicing/contracts/companyLookup.d.ts

@@ -0,0 +1,49 @@
+import type { InvoiceProof, InvoiceUnsupported } from "./provider.js";
+/** Injected registry seam. Host owns identifier validation, freshness and fallback;
+ * lookup evidence never overwrites checkout truth or becomes a renewal prerequisite.
+ * Carrier: accountingControlContracts lookup fields, generalized per A5 fit probe.
+ */
+export interface InvoiceCompanyLookupPort {
+    lookup(input: {
+        readonly identifier: {
+            readonly scheme: string;
+            readonly value: string;
+            readonly country?: string;
+        };
+        readonly asOf: string;
+        readonly sourceRef: string;
+    }): Promise<{
+        readonly kind: "found" | "partial";
+        readonly identifier: {
+            readonly scheme: string;
+            readonly value: string;
+            readonly country?: string;
+        };
+        readonly legalName: string | null;
+        readonly registrationIds: readonly {
+            readonly scheme: string;
+            readonly value: string;
+        }[];
+        readonly address: {
+            readonly line1: string;
+            readonly postalCode: string;
+            readonly city: string;
+            readonly country: string;
+        } | null;
+        readonly taxRegistrations: readonly {
+            readonly scheme: string;
+            readonly status: "active" | "not_registered" | "exempt" | "unknown";
+        }[];
+        readonly sourceRef: string;
+        readonly proof: InvoiceProof;
+    } | {
+        readonly kind: "not_found";
+        readonly identifier: Parameters<InvoiceCompanyLookupPort["lookup"]>[0]["identifier"];
+        readonly sourceRef: string;
+        readonly proof: InvoiceProof;
+    } | {
+        readonly kind: "unknown";
+        readonly sourceRef: string;
+        readonly code: "unknown";
+    } | InvoiceUnsupported>;
+}

package/dist/invoicing/contracts/companyLookup.js

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

package/dist/invoicing/contracts/delivery.d.ts

@@ -0,0 +1,74 @@
+import type { InvoiceDocumentIdentity, InvoiceProof, InvoiceUnsupported } from "./provider.js";
+/** Durable opaque references; signed URLs and downloaded bytes are transient. */
+export type InvoiceArtifactResult = {
+    readonly kind: "found";
+    readonly identity: InvoiceDocumentIdentity;
+    readonly artifact: {
+        readonly kind: "pdf" | "structured_document" | "clearance_receipt";
+        readonly ref: string;
+        readonly owner: "provider" | "host_storage";
+        readonly mediaType: string;
+        readonly proof: InvoiceProof;
+    };
+} | {
+    readonly kind: "absent";
+    readonly identity: InvoiceDocumentIdentity;
+    readonly evidence: InvoiceProof & {
+        readonly exact: true;
+        readonly complete: true;
+        readonly scope: {
+            readonly identity: InvoiceDocumentIdentity;
+            readonly kind: "pdf" | "structured_document" | "clearance_receipt";
+            readonly artifactRef: string | null;
+        };
+    };
+} | {
+    readonly kind: "unknown";
+    readonly identity: InvoiceDocumentIdentity;
+    readonly code: "unknown";
+} | InvoiceUnsupported;
+/** Observation only; unsupported is never not_required. No clearance submission. */
+export type InvoiceClearanceObservation = {
+    readonly proof: InvoiceProof;
+} & ({
+    readonly state: "accepted";
+    readonly reference: string;
+} | {
+    readonly state: "not_submitted" | "pending" | "rejected" | "not_required" | "unsupported";
+    readonly reference: string | null;
+});
+export interface InvoiceDeliveryPort {
+    /** Host M04 content/transport; provider acceptance is not inbox delivery.
+     * Preserve delivery/request keys, recipient, filename and bytes. Validate PDF
+     * type, size and signature before send; uncertain send must never repeat sending.
+     */
+    send(input: {
+        readonly deliveryRef: string;
+        readonly requestKey: string;
+        readonly attemptCount: number;
+        readonly documentRef: string;
+        readonly orderId: string;
+        readonly orderRef: string;
+        readonly invoiceRef: string;
+        readonly providerDocumentRef: string;
+        readonly clientRef: string | null;
+        readonly recipient: string;
+        readonly source: string | null;
+        readonly providerDocumentNumber: string | null;
+        readonly filename: string;
+        readonly content: Uint8Array;
+        readonly contentType: string;
+    }): Promise<{
+        readonly kind: "provider_accepted";
+        readonly receiptRef: string;
+        readonly proof: InvoiceProof;
+    } | {
+        readonly kind: "failed_before_send";
+        readonly retryable: boolean;
+        readonly code: "retryable" | "invalid_artifact";
+    } | {
+        readonly kind: "uncertain";
+        readonly code: "uncertain_delivery";
+        readonly receiptRef: string | null;
+    } | InvoiceUnsupported>;
+}

package/dist/invoicing/contracts/delivery.js

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