@openlup/platform 0.21.0 → 0.23.0

package/dist/fulfillment/currentFulfillmentParcel.js

@@ -0,0 +1 @@
+export { parcelSequenceNo, compareParcelPrecedence, currentParcel, currentParcelFor, currentParcelPerOrder, currentParcelFirst, belongsToParcel, rowsForParcel } from "@openlup/core/fulfillment";

package/dist/fulfillment/delayReadModel.d.ts

@@ -0,0 +1,11 @@
+import type { CustomerDeliveryAlignment, FulfillmentCustomerAlignmentRowsReader } from './contracts/customerAlignment.js';
+import type { FulfillmentNativeUnsupported } from './contracts/nativeUnsupported.js';
+export type DeliveryAlignmentRow = Record<string, unknown>;
+export type DeliveryAlignmentRowsReader = FulfillmentCustomerAlignmentRowsReader;
+/**
+ * Reads only customer-safe current cases. An aligned case remains current while
+ * its aligned schedule is still the subscription's next schedule; once a paid
+ * cycle advances `next_cycle_at`, the historical ledger row disappears from UI.
+ */
+export declare function readFulfillmentDelay(readRows: DeliveryAlignmentRowsReader | undefined, nextCycleAtBySubscription: ReadonlyMap<string, string | null>): Promise<Map<string, CustomerDeliveryAlignment> | FulfillmentNativeUnsupported>;
+export declare function mapCurrentDeliveryAlignments(rows: DeliveryAlignmentRow[], nextCycleAtBySubscription: ReadonlyMap<string, string | null>): Map<string, CustomerDeliveryAlignment>;

package/dist/fulfillment/delayReadModel.js

@@ -0,0 +1,45 @@
+import { isNativeUnsupported } from './handlerSupport.js';
+/**
+ * Reads only customer-safe current cases. An aligned case remains current while
+ * its aligned schedule is still the subscription's next schedule; once a paid
+ * cycle advances `next_cycle_at`, the historical ledger row disappears from UI.
+ */
+export async function readFulfillmentDelay(readRows, nextCycleAtBySubscription) {
+    const subscriptionIds = [...nextCycleAtBySubscription.keys()].filter(Boolean);
+    if (!readRows || subscriptionIds.length === 0)
+        return new Map();
+    const rows = await readRows(subscriptionIds);
+    if (isNativeUnsupported(rows))
+        return rows;
+    return mapCurrentDeliveryAlignments(rows, nextCycleAtBySubscription);
+}
+export function mapCurrentDeliveryAlignments(rows, nextCycleAtBySubscription) {
+    const result = new Map();
+    for (const row of rows) {
+        const subscriptionId = text(row.subscription_id);
+        if (!subscriptionId || result.has(subscriptionId))
+            continue;
+        const state = text(row.state);
+        if (state === "protected") {
+            result.set(subscriptionId, { state });
+            continue;
+        }
+        if (state === "aligned" && sameInstant(nullableText(row.aligned_next_cycle_at), nextCycleAtBySubscription.get(subscriptionId) ?? null)) {
+            result.set(subscriptionId, { state });
+        }
+    }
+    return result;
+}
+function sameInstant(left, right) {
+    if (!left || !right)
+        return false;
+    const leftTime = new Date(left).getTime();
+    const rightTime = new Date(right).getTime();
+    return Number.isFinite(leftTime) && leftTime === rightTime;
+}
+function text(value) {
+    return typeof value === "string" ? value : "";
+}
+function nullableText(value) {
+    return typeof value === "string" && value ? value : null;
+}

package/dist/fulfillment/deliveryAlignmentReadModel.d.ts

@@ -0,0 +1,4 @@
+import type { DeliveryAlignmentPort } from './contracts/index.js';
+import type { PgExecutor } from './postgresDispatchStore.js';
+/** Server-authorized projection; database browser roles have no direct access. */
+export declare function readDeliveryAlignment(db: PgExecutor, fulfillmentRef: string): ReturnType<DeliveryAlignmentPort['read']>;

package/dist/fulfillment/deliveryAlignmentReadModel.js

@@ -0,0 +1,12 @@
+/** Server-authorized projection; database browser roles have no direct access. */
+export async function readDeliveryAlignment(db, fulfillmentRef) {
+    const result = await db.query(`SELECT alignment.state, alignment.aligned_next_cycle_at
+    FROM public.fulfillment_shipments shipment
+    LEFT JOIN public.subscription_delivery_alignment_cases alignment ON alignment.predecessor_order_id=shipment.order_id
+    WHERE shipment.id=$1::uuid
+    ORDER BY (alignment.state IN ('protected','manual_review')) DESC, alignment.created_at ASC LIMIT 1`, [fulfillmentRef]);
+    const row = result.rows[0];
+    const date = row?.aligned_next_cycle_at;
+    return { disposition: row?.state === 'aligned' ? 'aligned' : row?.state === 'protected' ? 'outstanding' : 'manual_review',
+        nextCycleAt: date instanceof Date ? date.toISOString() : typeof date === 'string' ? date : null };
+}

package/dist/fulfillment/dispatchProjection.d.ts

@@ -0,0 +1,26 @@
+import type { DispatchEvidence, DispatchRecord, FulfillmentDispatchRequest, FulfillmentDispatchResult, FulfillmentOperationError } from "./contracts/index.js";
+/** Machine identities only: arbitrary exception prose, URLs and credentials are omitted. */
+export declare function safeDiagnosticCode(value: unknown): string | null;
+export declare function localFailureReason(stage: string, error: unknown, privacy?: {
+    token(value: string | null | undefined, codec?: (value: string) => string | null): string | null;
+    readonly redactedFieldCount: number;
+}): string;
+export declare function operationError(error: Omit<FulfillmentOperationError, "cause"> & {
+    cause?: unknown;
+}): FulfillmentOperationError;
+export declare const reference: (value: unknown) => string | null;
+/** Opaque by default; an explicit allowlist can admit wider incumbent references. */
+export declare function admittedReference(value: string | null | undefined, approve?: (value: string) => boolean): string | null;
+/** One counted sanitizer for durable projections; codecs are explicit host policy. */
+export declare function durableStrings(priorCount?: number): {
+    token(value: string | null | undefined, codec?: (value: string) => string | null): string | null;
+    readonly redactedFieldCount: number;
+};
+/** Copy only the durable allowlist, including when an adapter object has extra runtime properties. */
+export declare function dispatchEvidence(evidence: DispatchEvidence): DispatchEvidence;
+/** Shadow has a local command identity; it never invokes a provider or resolves credentials. */
+export declare function shadowDispatchEvidence(request: FulfillmentDispatchRequest): DispatchEvidence;
+export declare function dispatchResult(result: FulfillmentDispatchResult): FulfillmentDispatchResult;
+export declare function acceptedProviderProof(record: DispatchRecord | null): record is DispatchRecord & {
+    externalRef: string;
+};

package/dist/fulfillment/dispatchProjection.js

@@ -0,0 +1,107 @@
+import { createHash } from "node:crypto";
+/** Machine identities only: arbitrary exception prose, URLs and credentials are omitted. */
+export function safeDiagnosticCode(value) {
+    return reference(value) && typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9_]{0,95}$/u.test(value) ? value : null;
+}
+export function localFailureReason(stage, error, privacy = durableStrings()) {
+    if (!error || typeof error !== "object")
+        return stage;
+    const fields = error;
+    const diagnostic = (value) => typeof value === "string" ? privacy.token(value, safeDiagnosticCode) : null;
+    const ownCode = diagnostic(fields.code), causeCode = diagnostic(fields.causeCode), causeMessage = diagnostic(fields.causeMessage);
+    const messagePattern = /^([A-Za-z][A-Za-z0-9_]*)(?::([A-Z0-9]{5}))?$/u;
+    const safeMessage = typeof fields.message === "string" ? privacy.token(fields.message, value => messagePattern.test(value) ? value : null) : null;
+    const message = safeMessage?.match(messagePattern);
+    const cause = causeMessage ?? (message && (message[2] || /_(?:failed|down|missing|invalid|conflict|not_found)$/u.test(message[1])) ? safeDiagnosticCode(message[1]) : null);
+    const code = causeCode ?? ownCode ?? message?.[2];
+    return [stage, cause, code].filter(Boolean).join(":");
+}
+export function operationError(error) {
+    const privacy = durableStrings(error.redactedFieldCount);
+    const code = privacy.token(error.code, safeDiagnosticCode) ?? "operation_failed";
+    const cause = typeof error.cause === "string" ? privacy.token(error.cause, value => /^ack(?::[A-Za-z0-9_]{1,96}){0,2}$/u.test(value) ? value.slice(0, 180) : null) : null;
+    return { code, status: Number.isInteger(error.status) && error.status >= 100 && error.status <= 599 ? error.status : null,
+        retryable: error.retryable === true, mayHaveSucceeded: error.mayHaveSucceeded === true,
+        ...(cause ? { cause } : {}), ...(privacy.redactedFieldCount ? { redactedFieldCount: privacy.redactedFieldCount } : {}) };
+}
+// The fulfillment opaque-ID rule; never accept free-form metadata as a reference.
+export const reference = (value) => typeof value === "string"
+    && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u.test(value) ? value : null;
+/** Opaque by default; an explicit allowlist can admit wider incumbent references. */
+export function admittedReference(value, approve) {
+    if (typeof value !== "string" || /[\p{Cc}\p{Cf}]/u.test(value))
+        return null;
+    const admitted = approve ? approve(value) : reference(value) !== null;
+    const text = value.trim();
+    return admitted && text && text.length <= 256 && !/[@]|[a-z][a-z0-9+.-]*:\/\//iu.test(text) ? text : null;
+}
+const isoDate = (value) => typeof value === "string"
+    && /^\d{4}-\d\d-\d\d$/u.test(value) && Number.isFinite(Date.parse(value))
+    && new Date(value).toISOString().slice(0, 10) === value ? value : null;
+/** One counted sanitizer for durable projections; codecs are explicit host policy. */
+export function durableStrings(priorCount = 0) {
+    let count = Number.isSafeInteger(priorCount) && priorCount > 0 ? priorCount : 0;
+    return {
+        token(value, codec = reference) {
+            if (value == null)
+                return null;
+            const safe = codec(value);
+            if (safe === null)
+                count += 1;
+            return safe;
+        },
+        get redactedFieldCount() { return count; },
+    };
+}
+/** Copy only the durable allowlist, including when an adapter object has extra runtime properties. */
+export function dispatchEvidence(evidence) {
+    const privacy = durableStrings(evidence.redactedFieldCount ?? evidence.transcript?.redactedFieldCount);
+    const sanitize = privacy.token;
+    const commandFingerprint = evidence.commandFingerprint;
+    const source = evidence.contactRevision.source;
+    const providerRef = sanitize(evidence.providerRef) ?? "redacted", carrierRef = sanitize(evidence.carrierRef), serviceRef = sanitize(evidence.serviceRef);
+    const mode = evidence.mapping ? (sanitize(evidence.mapping.mode) ?? "shadow") : null;
+    const transcript = evidence.transcript ? {
+        itemCount: evidence.transcript.items.length,
+        items: evidence.transcript.items.map(item => ({ skuRef: sanitize(item.skuRef) ?? "redacted", quantity: Number.isSafeInteger(item.quantity) && item.quantity > 0 ? item.quantity : 0,
+            lotRef: sanitize(item.lotRef), expirationDate: sanitize(item.expirationDate, isoDate) })),
+        deliveryKind: evidence.transcript.deliveryKind === "parcel-locker" ? "parcel-locker" : "courier",
+        pickupPointRef: sanitize(evidence.transcript.pickupPointRef),
+        ...(privacy.redactedFieldCount > 0 ? { redactedFieldCount: privacy.redactedFieldCount } : {}),
+    } : null;
+    return {
+        commandFingerprint,
+        contactRevision: { schemaVersion: evidence.contactRevision.schemaVersion, source, revision: evidence.contactRevision.revision },
+        providerRef, carrierRef, serviceRef,
+        ...(transcript ? { transcript } : privacy.redactedFieldCount ? { redactedFieldCount: privacy.redactedFieldCount } : {}),
+        ...(evidence.mapping ? { mapping: { source: "dispatch_worker", mode: mode, shadowMode: evidence.mapping.mode === "shadow" } } : {}),
+    };
+}
+/** Shadow has a local command identity; it never invokes a provider or resolves credentials. */
+export function shadowDispatchEvidence(request) {
+    if (!request.selection.providerRef || !request.lines.length || request.lines.some(line => !Number.isSafeInteger(line.quantity) || line.quantity <= 0))
+        throw new Error("dispatch_shadow_command_invalid");
+    return dispatchEvidence({ commandFingerprint: createHash("sha256").update(JSON.stringify(request)).digest("hex"),
+        contactRevision: request.contactRevision, providerRef: request.selection.providerRef,
+        carrierRef: request.selection.carrierRef, serviceRef: request.selection.serviceRef,
+        transcript: { itemCount: request.lines.length, items: request.lines.map(line => ({ skuRef: line.skuRef, quantity: line.quantity,
+                lotRef: line.lotRef ?? null, expirationDate: line.expirationDate ?? null })),
+            deliveryKind: request.selection.deliveryKind, pickupPointRef: request.selection.pickupPoint?.id ?? null } });
+}
+export function dispatchResult(result) {
+    const privacy = durableStrings(result.redactedFieldCount);
+    const externalRef = result.kind === "accepted" ? privacy.token(result.externalRef) ?? "redacted" : null;
+    const refusal = result.kind !== "accepted" ? { reason: (privacy.token(result.refusal.reason) ?? "malformed"),
+        phase: (privacy.token(result.refusal.phase) ?? "normalize"), retryable: result.refusal.retryable } : null;
+    const redactions = privacy.redactedFieldCount ? { redactedFieldCount: privacy.redactedFieldCount } : {};
+    const error = result.error ? { error: operationError({ ...result.error, mayHaveSucceeded: result.kind !== "not_dispatched" }) } : {};
+    switch (result.kind) {
+        case "accepted": return { kind: "accepted", externalRef: externalRef, providerAttemptKey: result.providerAttemptKey, labelKey: result.labelKey, ...redactions, evidence: dispatchEvidence(result.evidence), ...error,
+            ...(result.recovery ? { recovery: { source: "persisted_acceptance", proof: "persisted_external_ref", noProviderPost: true } } : {}) };
+        case "not_dispatched": return { kind: "not_dispatched", effectMayHaveSucceeded: false, refusal: refusal, ...redactions, ...error };
+        case "unknown": return { kind: "unknown", effectMayHaveSucceeded: true, refusal: refusal, ...redactions, ...error };
+    }
+}
+export function acceptedProviderProof(record) {
+    return Boolean(record?.externalRef && (record.status === "created" || record.status === "uncertain"));
+}

package/dist/fulfillment/fulfillmentObservationEffects.d.ts

@@ -0,0 +1,66 @@
+import type { FulfillmentObservation } from "./contracts/index.js";
+/** Ledger effects for an already accepted observation; acceptance and retry belong to the caller. */
+interface FulfillmentObservationPort<TrackingStatus> {
+    markProviderStockConsumed(input: {
+        idempotencyKey: string;
+        fulfillmentOrderId: string;
+    }): Promise<{
+        replayed: boolean;
+    }>;
+    markHandedOver(input: {
+        idempotencyKey: string;
+        fulfillmentOrderId: string;
+        suppressDispatched: boolean;
+    }): Promise<{
+        replayed: boolean;
+    }>;
+    recordTrackingReference(input: {
+        idempotencyKey: string;
+        orderId: string;
+        fulfillmentOrderId: string;
+        trackingNumber: string;
+        trackingUrl: string | null;
+        carrierKind: string | null;
+        service: string | null;
+        status: TrackingStatus;
+        observation: FulfillmentObservation;
+    }): Promise<{
+        replayed: boolean;
+        readBack: boolean;
+    }>;
+}
+interface FulfillmentObservationTrackingReference {
+    trackingNumber: string;
+    trackingUrl?: string | null;
+    carrierKind?: string | null;
+    service?: string | null;
+}
+interface FulfillmentObservationInput<LocalStatus, TrackingStatus> {
+    port: FulfillmentObservationPort<TrackingStatus>;
+    localStatus: LocalStatus;
+    ids: {
+        orderId: string;
+        fulfillmentOrderId: string;
+    };
+    observation: FulfillmentObservation;
+    trackingRefs: readonly FulfillmentObservationTrackingReference[];
+    stockIdempotencyKey: string;
+    handoffIdempotencyKey: string;
+    trackingIdempotencyKey: (trackingNumber: string) => string;
+    issueAccountingInvoice?: () => Promise<void>;
+    onReplayed?: () => void;
+    onTrackingRecorded?: (result: {
+        replayed: boolean;
+        readBack: boolean;
+    }) => void;
+}
+/** Pure status decisions/projection; the mechanism owns every effect and await. */
+interface FulfillmentObservationStatusPolicy<LocalStatus, TrackingStatus> {
+    consumesStock(status: LocalStatus): boolean;
+    handsOver(status: LocalStatus): boolean;
+    suppressDispatched(status: LocalStatus): boolean;
+    trackingStatus(status: LocalStatus): TrackingStatus;
+}
+/** Stock → durable handover → every tracking reference → optional invoice. No catches or retries. */
+export declare function applyFulfillmentObservationEffects<LocalStatus, TrackingStatus>(input: FulfillmentObservationInput<LocalStatus, TrackingStatus>, policy: FulfillmentObservationStatusPolicy<LocalStatus, TrackingStatus>): Promise<void>;
+export {};

package/dist/fulfillment/fulfillmentObservationEffects.js

@@ -0,0 +1,36 @@
+/** Stock → durable handover → every tracking reference → optional invoice. No catches or retries. */
+export async function applyFulfillmentObservationEffects(input, policy) {
+    const { fulfillmentOrderId, orderId } = input.ids;
+    if (policy.consumesStock(input.localStatus)) {
+        const consumed = await input.port.markProviderStockConsumed({
+            idempotencyKey: input.stockIdempotencyKey,
+            fulfillmentOrderId,
+        });
+        if (consumed.replayed)
+            input.onReplayed?.();
+    }
+    if (!policy.handsOver(input.localStatus))
+        return;
+    const handoff = await input.port.markHandedOver({
+        idempotencyKey: input.handoffIdempotencyKey,
+        fulfillmentOrderId,
+        suppressDispatched: policy.suppressDispatched(input.localStatus),
+    });
+    if (handoff.replayed)
+        input.onReplayed?.();
+    for (const trackingRef of input.trackingRefs) {
+        const tracking = await input.port.recordTrackingReference({
+            idempotencyKey: input.trackingIdempotencyKey(trackingRef.trackingNumber),
+            orderId,
+            fulfillmentOrderId,
+            trackingNumber: trackingRef.trackingNumber,
+            trackingUrl: trackingRef.trackingUrl ?? null,
+            carrierKind: trackingRef.carrierKind ?? null,
+            service: trackingRef.service ?? null,
+            status: policy.trackingStatus(input.localStatus),
+            observation: input.observation,
+        });
+        input.onTrackingRecorded?.(tracking);
+    }
+    await input.issueAccountingInvoice?.();
+}