@openlup/platform 0.22.0 → 0.23.0

package/dist/fulfillment/verifiedIngress.d.ts

@@ -1,4 +1,4 @@
-import type { FulfillmentObservation, FulfillmentObservationPort, FulfillmentRefusal } from "./contracts/index.js";
+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 = {
@@ -7,20 +7,54 @@ type DispatchRef = {
     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: {
@@ -36,17 +70,10 @@ export declare function verifyAndNormalizeFulfillmentObservation(input: {
             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<{
-    kind: "refused";
-    refusal: FulfillmentRefusal;
-} | {
-    kind: "processed" | "ignored" | "superseded";
-    observation: FulfillmentObservation;
-    replayed: boolean;
-    trackingRefs: number;
-    trackingReadBacks: number;
-}>;
+}): Promise<FulfillmentIngressResult>;
 export {};

package/dist/fulfillment/verifiedIngress.js

@@ -1,19 +1,44 @@
+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", refusal: { reason: "disabled", phase: "verify", retryable: false } };
+        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")
-        return verified;
-    const observation = projectObservation(verified.observation);
+    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", observation, replayed: inbound.replayed, trackingRefs: 0, trackingReadBacks: 0 };
+        return { kind: "ignored", receiptId, counts, observation, replayed: inbound.replayed, trackingRefs: 0, trackingReadBacks: 0 };
     }
     const externalRef = observation.correlation.externalRef?.trim() || ref.externalRef?.trim();
     if (!externalRef)
@@ -57,10 +82,13 @@ export async function verifyAndNormalizeFulfillmentObservation(input) {
         catch (error) {
             if (input.lifecycle.classifyFailure(error) !== "state_conflict")
                 throw error;
-            await input.localPersistence.markProcessed(observation.eventKey, { status: "processed" });
-            return { kind: "superseded", observation, replayed: inbound.replayed || statusEvidence.replayed, trackingRefs, trackingReadBacks };
+            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", observation, replayed: inbound.replayed || statusEvidence.replayed, trackingRefs, trackingReadBacks };
+    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 {};

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

@@ -0,0 +1,100 @@
+/** Frozen host facts; no catalogue, registry or country-policy reread on retry.
+ * Carrier: donor providerPorts snapshot and invoiceContracts LocalInvoiceSnapshot;
+ * native invoicing_install_facts adds dates/refs/policyVersion and explicit totals.
+ */
+export interface InvoiceSeller {
+    readonly name: string;
+    readonly address: {
+        readonly line1: string;
+        readonly postalCode: string;
+        readonly city: string;
+    };
+    readonly taxIdentifier: {
+        readonly scheme: string;
+        readonly value: string;
+    };
+    readonly registrationIds?: readonly {
+        readonly scheme: string;
+        readonly value: string;
+    }[];
+    readonly bankAccount: string | null;
+    /** Opaque host routing reference, interpreted only by the selected adapter. */
+    readonly routingRef: string | null;
+}
+export interface InvoiceBuyer {
+    readonly name: string;
+    readonly email: string | null;
+    readonly taxIdentifier: {
+        readonly scheme: string;
+        readonly value: string;
+    } | null;
+    readonly companyName: string | null;
+    readonly address: {
+        readonly line1: string | null;
+        readonly postalCode: string | null;
+        readonly city: string | null;
+        readonly country: string | null;
+    } | null;
+}
+/** Safe integer minor amounts; taxRateBps is a rate, never a fiscal-support claim.
+ * Preserve array order and quantityUnit; no inferred shipping residual or FX.
+ */
+export interface InvoiceLine {
+    readonly description: string;
+    readonly quantity: number;
+    readonly quantityUnit?: string;
+    readonly unitNetMinor: number;
+    readonly unitGrossMinor: number;
+    readonly totalNetMinor: number;
+    readonly totalTaxMinor: number;
+    readonly totalGrossMinor: number;
+    readonly taxRateBps: number;
+    readonly taxRateLabel?: string;
+    readonly positionKind: "item" | "delivery" | null;
+    readonly catalogTotalGrossMinor: number | null;
+    readonly discountAllocatedMinor: number | null;
+    readonly shippingGrossMinor: number | null;
+    readonly shippingDiscountMinor: number | null;
+}
+export interface InvoiceFacts {
+    readonly factRevision: string;
+    readonly policyVersion: string;
+    readonly refs: {
+        readonly orderId: string;
+        readonly orderRef: string;
+        readonly invoiceRef: string;
+    };
+    readonly dates: {
+        readonly issueDate: string;
+        readonly sellDate: string;
+        readonly handedOverAt: string | null;
+        readonly paymentCompletedAt: string | null;
+    };
+    /** Host-defined kind selected through the identifier/tax seam, never guessed. */
+    readonly documentKind: string;
+    readonly clearanceRequired: boolean;
+    readonly currency: string;
+    readonly buyer: InvoiceBuyer;
+    /** Supplied separately for execution; P8 freezes it at first claim before provider I/O. */
+    readonly seller?: InvoiceSeller;
+    readonly payment: {
+        readonly intentRef: string;
+        readonly providerRef: string | null;
+        readonly providerPaymentRef: string | null;
+        readonly amountMinor: number;
+        readonly currency: string;
+        readonly localSettlementState: "matched" | "unavailable";
+    };
+    readonly orderMoney: {
+        readonly subtotalMinor: number;
+        readonly discountMinor: number;
+        readonly shippingMinor: number;
+        readonly shippingDiscountMinor: number;
+        readonly totalMinor: number;
+    } | null;
+    readonly lines: readonly InvoiceLine[];
+    readonly totalNetMinor: number;
+    readonly totalTaxMinor: number;
+    readonly totalGrossMinor: number;
+    readonly chargedTotalGrossMinor: number;
+}

package/dist/invoicing/contracts/facts.js

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