@openlup/platform 0.21.0 → 0.22.0

package/dist/fulfillment/adapterConformance.js

@@ -0,0 +1,223 @@
+import { dispatchEvidence, dispatchResult } from "./dispatchProjection.js";
+import { projectObservation } from "./observationProjection.js";
+import { readFulfillmentCapabilities } from "./providerCapabilities.js";
+import { runFulfillmentDispatchWorker } from "./providerDispatchWorker.js";
+/** Runner-independent offline proof using only adapter-owned fixtures. Throws on a violated contract. */
+export async function runFulfillmentAdapterConformance(subjects) {
+    const evidence = [];
+    const cases = [];
+    for (const subject of subjects) {
+        const { adapter, fixtures } = subject;
+        const caps = adapter.capabilities;
+        const passed = (operation) => { cases.push({ subjectId: subject.subjectId, operation, passed: true }); };
+        requireFact(caps.defaultOff === true, "default-off");
+        requireFact(readFulfillmentCapabilities([caps], null).kind === "refused", "selection_required");
+        const first = fixtures.dispatch[0];
+        requireFact(Boolean(first), "dispatch fixture required");
+        const disabled = readFulfillmentCapabilities([{ ...caps, selected: false }], first.input.selection);
+        requireFact(disabled.kind === "refused" && disabled.refusal.reason === "disabled", "disabled selection");
+        const missing = await adapter.dispatch.prepare({ ...first.input, selection: { ...first.input.selection, providerRef: null } });
+        requireFact(missing.kind === "refused" && missing.refusal.reason === "selection_required", "adapter selection_required");
+        passed("default-off and selection_required");
+        for (const fixture of fixtures.dispatch) {
+            const before = subject.readIoCount();
+            const prepared = await adapter.dispatch.prepare(fixture.input);
+            requireSame(prepared, fixture.expectedPrepare, "prepare fixture");
+            requireFact(subject.readIoCount() === before, "prepare before I/O");
+            assertDurable(prepared, subject);
+            if (prepared.kind === "refused") {
+                passed("dispatch refused before I/O");
+                continue;
+            }
+            requireFact(caps.operations.dispatch.supported, "unsupported dispatch refuses");
+            requireSame(prepared.evidence, dispatchEvidence(prepared.evidence), "prepared evidence allowlist");
+            requireFact(prepared.evidence.providerRef === fixture.input.selection.providerRef, "prepared provider identity");
+            requireSame(prepared.evidence.contactRevision, fixture.input.contactRevision, "prepared contact identity");
+            const mismatch = await adapter.dispatch.dispatch(fixture.input, { ...prepared.evidence, commandFingerprint: `${prepared.evidence.commandFingerprint}:mismatch` });
+            requireSame(mismatch, { kind: "not_dispatched", effectMayHaveSucceeded: false,
+                refusal: { reason: "not_dispatchable", phase: "dispatch", retryable: false } }, "mismatched preparation refusal");
+            requireFact(subject.readIoCount() === before, "mismatch before I/O");
+            requireFact(fixture.expectedDispatch !== undefined, "dispatch expected result");
+            const result = await adapter.dispatch.dispatch(fixture.input, prepared.evidence);
+            requireSame(result, fixture.expectedDispatch, "dispatch fixture");
+            requireSame(result, dispatchResult(result), "dispatch allowlist");
+            assertDurable(result, subject);
+            if (result.kind === "accepted") {
+                requireSame(result.evidence, prepared.evidence, "dispatch fingerprint identity");
+                requireFact(result.externalRef.length > 0 && result.providerAttemptKey.length > 0 && result.labelKey.length > 0, "accepted proof before local ACK");
+            }
+            else
+                requireFact(result.kind === "unknown" ? result.effectMayHaveSucceeded : !result.effectMayHaveSucceeded, "unknown versus refused");
+            if (fixture.replay) {
+                const calls = subject.readIoCount();
+                requireSame(await adapter.dispatch.dispatch(fixture.input, prepared.evidence), result, "dispatch replay");
+                requireFact(subject.readIoCount() === calls, "replay no second I/O");
+            }
+            passed(`dispatch ${result.kind}, fingerprint, mismatch and replay`);
+        }
+        for (const operation of ["create", "read", "void"]) {
+            const supported = caps.operations[operation === "create" ? "labelCreate" : operation === "read" ? "labelRead" : "labelVoid"].supported;
+            const rows = fixtures.label?.[operation] ?? [];
+            if (supported)
+                requireFact(Boolean(adapter.label) && rows.length > 0, `label ${operation} fixture`);
+            if (rows.length)
+                requireFact(Boolean(adapter.label), "label port required");
+            for (const fixture of rows) {
+                const before = subject.readIoCount();
+                const result = operation === "create" ? await adapter.label.create(fixture.input[0])
+                    : operation === "read" ? await adapter.label.read(fixture.input[0])
+                        : await adapter.label.void(fixture.input[0]);
+                requireSame(result, fixture.expected, `label ${operation}`);
+                if (!supported && !(operation === "read" && caps.labelReadOwner === "host_storage")) {
+                    requireFact("refusal" in result && result.refusal?.reason === "unsupported", `unsupported label ${operation}`);
+                    requireFact(subject.readIoCount() === before, "unsupported label before I/O");
+                }
+                if (!(operation === "read" && "kind" in result && result.kind === "available"))
+                    assertDurable(result, subject);
+                passed(`label ${operation}`);
+            }
+        }
+        if (caps.operations.verifyObservation.supported)
+            requireFact(Boolean(adapter.observation) && Boolean(fixtures.observation?.length), "observation fixtures required");
+        const events = new Map();
+        for (const fixture of fixtures.observation ?? []) {
+            requireFact(Boolean(adapter.observation), "observation port required");
+            const result = await adapter.observation.verifyAndNormalize(...fixture.input);
+            requireSame(result, fixture.expected, "observation fixture");
+            assertDurable(result, subject);
+            if (!caps.operations.verifyObservation.supported)
+                requireFact(result.kind === "refused" && result.refusal.reason === "unsupported", "unsupported observation");
+            if (result.kind === "verified") {
+                requireSame(result.observation, projectObservation(result.observation), "observation allowlist");
+                const observation = result.observation;
+                const identity = stable({ provider: observation.fact.providerKind, reference: observation.fact.fulfillmentReference,
+                    kind: observation.eventKind, outcome: observation.fact.canonicalStatus, occurredAt: observation.fact.occurredAt });
+                const previous = events.get(observation.eventKey);
+                if (previous)
+                    requireFact(previous.identity === identity, "eventKey includes outcome and occurrence");
+                events.set(observation.eventKey, { identity, occurredAt: observation.fact.occurredAt });
+                const replay = await adapter.observation.verifyAndNormalize(...fixture.input);
+                requireSame(replay, result, "observation exact retry");
+            }
+            passed("observation identity, replay and redaction");
+        }
+        if (caps.operations.readback.supported)
+            requireFact(Boolean(adapter.readback) && Boolean(fixtures.readback?.length), "readback fixtures required");
+        for (const fixture of fixtures.readback ?? []) {
+            requireFact(Boolean(adapter.readback), "readback port required");
+            const result = await adapter.readback.read(...fixture.input);
+            requireSame(result, fixture.expected, "readback fixture");
+            assertDurable(result, subject);
+            if (!caps.operations.readback.supported)
+                requireFact(result.kind === "unsupported", "unsupported readback");
+            if (fixture.localMissing)
+                requireFact(result.kind === "unknown" && result.refusal.reason === "local_missing", "local missing is never absence");
+            if (result.kind === "absent") {
+                requireFact(caps.operations.exactAbsence.supported, "unsupported exact absence refuses");
+                const { mode: _mode, ...scope } = fixture.input[0];
+                requireSame(result.scope, scope, "absence scope");
+                requireFact(result.proof.kind === "authoritative_exact_lookup" && /^evidence:.+/.test(result.proof.evidenceRef) && Number.isFinite(Date.parse(result.proof.checkedAt)), "absence proof");
+            }
+            if (result.kind === "found")
+                requireFact(result.externalRef === fixture.input[0].externalRef || fixture.input[0].externalRef === null, "found identity");
+            passed(`readback ${result.kind}`);
+        }
+        for (const name of ["stockSync", "productSync"]) {
+            const supported = caps.operations[name === "stockSync" ? "syncStock" : "syncProducts"].supported;
+            const port = adapter[name];
+            const rows = fixtures[name] ?? [];
+            if (supported)
+                requireFact(Boolean(port) && rows.length > 0, `${name} fixtures required`);
+            for (const fixture of rows) {
+                requireFact(Boolean(port), `${name} port required`);
+                let returned;
+                try {
+                    // Dispatch a typed fixture tuple to its adapter-owned operation.
+                    const method = port[fixture.operation];
+                    returned = await method.apply(port, fixture.input);
+                }
+                catch (error) {
+                    const refusal = error;
+                    requireFact(refusal.reason === "unsupported" && refusal.phase === "sync" && refusal.retryable === false, "typed unsupported sync refusal");
+                    returned = { kind: "refused", refusal };
+                }
+                requireSame(returned, fixture.expected, `${name} ${fixture.operation}`);
+                assertDurable(returned, subject);
+                if (!supported)
+                    requireFact(typeof returned === "object" && returned !== null && "kind" in returned && returned.kind === "refused", "unsupported sync");
+                passed(`${name} ${fixture.operation}`);
+            }
+        }
+        if (subject.store) {
+            await checkStore(subject);
+            passed("store G14 replay, own-key remap and one-remap bound");
+        }
+        assertDurable({ subjectId: subject.subjectId, providerRef: caps.providerRef }, subject);
+        evidence.push({ subjectId: subject.subjectId, providerRef: caps.providerRef });
+    }
+    return { subjects: evidence, cases };
+}
+async function checkStore(subject) {
+    const fixture = subject.store;
+    const store = await fixture.create();
+    const first = await store.claim(fixture.claim);
+    requireFact(first.kind === "claimed", "store initial claim");
+    const replay = await store.claim(fixture.claim);
+    requireFact(replay.kind === "claimed" && replay.record.replayed, "store same-key claim replay");
+    const attempt = () => store.recordProviderAttempt(fixture.mappedAttemptKey, fixture.claim.fulfillmentRef, fixture.claim.evidence, fixture.claim.mode, "recorded");
+    requireFact(!(await attempt()).replayed && (await attempt()).replayed, "G14 same key replays");
+    requireFact(fixture.mappedAttemptKey !== fixture.remappedAttemptKey, "G14 remap own key");
+    requireFact(fixture.claim.requestKey === fixture.remappedClaim.requestKey && fixture.claim.evidence.commandFingerprint !== fixture.remappedClaim.evidence.commandFingerprint, "draft remap fixture");
+    const remap = await store.claim(fixture.remappedClaim);
+    requireFact(remap.kind === "claimed", "draft re-claim");
+    const row = await store.read(fixture.claim.requestKey);
+    requireSame(row?.evidence, fixture.remappedClaim.evidence, "atomic remap fingerprint and evidence");
+    assertDurable(row, subject);
+    requireFact(!(await store.recordProviderAttempt(fixture.remappedAttemptKey, fixture.claim.fulfillmentRef, fixture.remappedClaim.evidence, fixture.claim.mode, "recorded")).replayed, "G14 new mapped attempt");
+    const attempts = await store.readMappedAttempts();
+    requireFact(attempts.length === 2, "G14 no duplicate durable attempts");
+    requireSame(attempts.map(row => row.attemptKey).sort(), [fixture.mappedAttemptKey, fixture.remappedAttemptKey].sort(), "G14 durable remap identity");
+    for (const attempt of attempts) {
+        requireSame(attempt.preparedEvidence, dispatchEvidence(attempt.preparedEvidence), "G14 sanitized evidence only");
+        assertDurable(attempt, subject);
+    }
+    const stale = await store.begin({ dispatchRef: row.dispatchRef, commandFingerprint: fixture.claim.evidence.commandFingerprint });
+    requireFact(stale.kind === "refused", "stale prepared command refuses");
+    let claims = 0;
+    let calls = 0;
+    let reads = 0;
+    const bounded = await runFulfillmentDispatchWorker({
+        store: { ...await fixture.create(), async read() { return null; }, async readCandidate() { reads += 1; return reads === 1 ? fixture.request : fixture.remappedRequest; },
+            async claim() { claims += 1; return { kind: "refused", refusal: { reason: "contact_stale", phase: "claim", retryable: true } }; } },
+        provider: { prepare: request => subject.adapter.dispatch.prepare(request), async dispatch() { calls += 1; throw new Error("unexpected dispatch"); } },
+        listCandidates: async () => [fixture.request], config: { mode: "stage", batchLimit: 1 },
+        keys: { request: () => fixture.claim.requestKey, mappedAttempt: (_key, index) => index === 0 ? fixture.mappedAttemptKey : fixture.remappedAttemptKey,
+            acceptance: () => ({ providerAttemptKey: "fixture-attempt", labelKey: "fixture-label" }) },
+    });
+    requireFact(claims === 2 && calls === 0 && !bounded.ok, "one-remap limit before I/O");
+}
+function assertDurable(value, subject) {
+    const text = JSON.stringify(value) ?? "";
+    requireFact(!subject.sensitiveValues.filter(Boolean).some(secret => text.includes(secret) || text.includes(JSON.stringify(secret).slice(1, -1))), "durable secret redaction");
+    const visit = (node) => {
+        if (!node || typeof node !== "object")
+            return;
+        for (const [key, child] of Object.entries(node)) {
+            requireFact(!/^(rawBody|rawPayload|rawCommand|password|secret|credential|authorization|headers|signedUrl)$/i.test(key), "durable field allowlist");
+            if (typeof child === "string")
+                requireFact(!/[?&](?:signature|sig|token|x-amz-signature|credential)=/i.test(child), "durable signed URL");
+            visit(child);
+        }
+    };
+    visit(value);
+}
+function stable(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stable).join(",")}]`;
+    if (value && typeof value === "object")
+        return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, child]) => `${JSON.stringify(key)}:${stable(child)}`).join(",")}}`;
+    return JSON.stringify(value);
+}
+function requireSame(actual, expected, label) { requireFact(stable(actual) === stable(expected), label); }
+function requireFact(value, label) { if (!value)
+    throw new Error(`fulfillment_adapter_conformance:${label}`); }

package/dist/fulfillment/bindings.d.ts

@@ -0,0 +1,3 @@
+import type { FulfillmentServices, FulfillmentServicesOptions } from './contracts/index.js';
+/** Explicit selection; no environment readers, implicit provider or automatic dispatch. */
+export declare function createFulfillmentServices(options: FulfillmentServicesOptions): FulfillmentServices;

package/dist/fulfillment/bindings.js

@@ -0,0 +1,29 @@
+import { FULFILLMENT_NATIVE_UNSUPPORTED } from './nativeUnsupported.js';
+import { readFulfillmentCapabilities } from './providerCapabilities.js';
+import { runFulfillmentDispatchWorker } from './providerDispatchWorker.js';
+/** Explicit selection; no environment readers, implicit provider or automatic dispatch. */
+export function createFulfillmentServices(options) {
+    const { enabled, selection, capability, store, provider, readiness: observe, listCandidates, now } = options;
+    const config = { ...options.config }, keys = { ...options.keys };
+    const readiness = async () => {
+        if (enabled !== true)
+            return { ready: false, refusal: { reason: 'disabled', phase: 'selection', retryable: false } };
+        const selected = readFulfillmentCapabilities(capability ? [capability] : [], selection);
+        if (selected.kind === 'refused')
+            return { ready: false, refusal: selected.refusal };
+        if (!selected.descriptor.operations.dispatch.supported)
+            return { ready: false, refusal: { reason: 'unsupported', phase: 'selection', retryable: false } };
+        if (!store || !provider)
+            return { ready: false, refusal: FULFILLMENT_NATIVE_UNSUPPORTED };
+        return observe();
+    };
+    return {
+        readiness,
+        async runDispatch() {
+            const state = await readiness();
+            if (!state.ready)
+                return 'kind' in state.refusal ? state.refusal : { kind: 'refused', refusal: state.refusal };
+            return runFulfillmentDispatchWorker({ store: store, provider, listCandidates, keys, config, now });
+        },
+    };
+}

package/dist/fulfillment/commerceFulfillmentHandlers.d.ts

@@ -0,0 +1,29 @@
+import type { FulfillmentOperatorMutationPort as CommerceFulfillmentMutationPort } from './contracts/operator.js';
+import type { FulfillmentCommerceReadPort as CommerceFulfillmentReadPort } from './contracts/read.js';
+import { type BaseDeps, type FulfillmentHandlerRequest } from './handlerSupport.js';
+type PortRef<T> = T | (() => T);
+export declare function createAdminCommerceFulfillmentOrdersListHandler<Response>({ authorizeAdmin, respond, fulfillmentPort, }: BaseDeps<Response> & {
+    fulfillmentPort: PortRef<Pick<CommerceFulfillmentReadPort, "listCommerceFulfillmentOrders">>;
+}): (req: FulfillmentHandlerRequest, res: Response) => Promise<void>;
+export declare function createAdminCommerceFulfillmentOrderDetailHandler<Response>({ authorizeAdmin, respond, fulfillmentPort, }: BaseDeps<Response> & {
+    fulfillmentPort: PortRef<Pick<CommerceFulfillmentReadPort, "getCommerceFulfillmentOrderDetail">>;
+}): (req: FulfillmentHandlerRequest, res: Response) => Promise<void>;
+export declare function createAdminCommerceFulfillmentCreateOrderHandler<Response>({ authorizeAdmin, respond, fulfillmentPort, }: BaseDeps<Response> & {
+    fulfillmentPort: PortRef<Pick<CommerceFulfillmentMutationPort, "createCommerceFulfillmentOrder">>;
+}): (req: FulfillmentHandlerRequest, res: Response) => Promise<void>;
+export declare function createAdminCommerceFulfillmentRecordProviderAttemptHandler<Response>({ authorizeAdmin, respond, fulfillmentPort, }: BaseDeps<Response> & {
+    fulfillmentPort: PortRef<Pick<CommerceFulfillmentMutationPort, "recordCommerceFulfillmentProviderAttempt">>;
+}): (req: FulfillmentHandlerRequest, res: Response) => Promise<void>;
+export declare function createAdminCommerceFulfillmentRecordLabelHandler<Response>({ authorizeAdmin, respond, fulfillmentPort, }: BaseDeps<Response> & {
+    fulfillmentPort: PortRef<Pick<CommerceFulfillmentMutationPort, "recordCommerceFulfillmentLabel">>;
+}): (req: FulfillmentHandlerRequest, res: Response) => Promise<void>;
+export declare function createAdminCommerceFulfillmentHandOffHandler<Response>({ authorizeAdmin, respond, fulfillmentPort, }: BaseDeps<Response> & {
+    fulfillmentPort: PortRef<Pick<CommerceFulfillmentMutationPort, "handOffCommerceFulfillmentOrder">>;
+}): (req: FulfillmentHandlerRequest, res: Response) => Promise<void>;
+export declare function createAdminCommerceFulfillmentTrackingEventHandler<Response>({ authorizeAdmin, respond, fulfillmentPort, }: BaseDeps<Response> & {
+    fulfillmentPort: PortRef<Pick<CommerceFulfillmentMutationPort, "recordCommerceFulfillmentTrackingEvent">>;
+}): (req: FulfillmentHandlerRequest, res: Response) => Promise<void>;
+export declare function createAdminCommerceFulfillmentCancelOrderHandler<Response>({ authorizeAdmin, respond, fulfillmentPort, }: BaseDeps<Response> & {
+    fulfillmentPort: PortRef<Pick<CommerceFulfillmentMutationPort, "cancelCommerceFulfillmentOrder">>;
+}): (req: FulfillmentHandlerRequest, res: Response) => Promise<void>;
+export {};

package/dist/fulfillment/commerceFulfillmentHandlers.js

@@ -0,0 +1,184 @@
+import { adminCommerceFulfillmentCancelRequestSchema, adminCommerceFulfillmentCreateRequestSchema, adminCommerceFulfillmentHandOffRequestSchema, adminCommerceFulfillmentMutationResponseSchema, adminCommerceFulfillmentOrderDetailRequestSchema, adminCommerceFulfillmentOrderDetailResponseSchema, adminCommerceFulfillmentOrdersListRequestSchema, adminCommerceFulfillmentOrdersListResponseSchema, adminCommerceFulfillmentRecordLabelRequestSchema, adminCommerceFulfillmentRecordProviderAttemptRequestSchema, adminCommerceFulfillmentTrackingEventRequestSchema, } from "./handlerSchemas.js";
+import { CommerceFulfillmentConflictError, authorize, isNativeUnsupported } from './handlerSupport.js';
+export function createAdminCommerceFulfillmentOrdersListHandler({ authorizeAdmin, respond, fulfillmentPort, }) {
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = respond;
+    return async function handler(req, res) {
+        if (req.method !== "GET")
+            return sendMethodNotAllowed(res, ["GET"]);
+        if (!(await authorize(req, res, authorizeAdmin, respond)))
+            return;
+        const request = adminCommerceFulfillmentOrdersListRequestSchema.safeParse(req.query);
+        if (!request.success) {
+            sendBffError(res, "BAD_REQUEST", "Invalid admin commerce fulfillment orders request", {
+                details: request.error.flatten(),
+            });
+            return;
+        }
+        try {
+            const port = resolvePort(fulfillmentPort);
+            const result = await port.listCommerceFulfillmentOrders(request.data);
+            if (isNativeUnsupported(result)) {
+                sendBffError(res, "UPSTREAM_UNAVAILABLE", "Native fulfillment operation unsupported", { details: result });
+                return;
+            }
+            const response = adminCommerceFulfillmentOrdersListResponseSchema.safeParse(result);
+            if (!response.success) {
+                sendBffError(res, "INVALID_RESPONSE", "Admin commerce fulfillment orders response invalid");
+                return;
+            }
+            sendBffSuccess(res, response.data);
+        }
+        catch {
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin commerce fulfillment orders read failed");
+        }
+    };
+}
+export function createAdminCommerceFulfillmentOrderDetailHandler({ authorizeAdmin, respond, fulfillmentPort, }) {
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = respond;
+    return async function handler(req, res) {
+        if (req.method !== "GET")
+            return sendMethodNotAllowed(res, ["GET"]);
+        if (!(await authorize(req, res, authorizeAdmin, respond)))
+            return;
+        const request = adminCommerceFulfillmentOrderDetailRequestSchema.safeParse(req.query);
+        if (!request.success) {
+            sendBffError(res, "BAD_REQUEST", "Invalid admin commerce fulfillment detail request", {
+                details: request.error.flatten(),
+            });
+            return;
+        }
+        try {
+            const port = resolvePort(fulfillmentPort);
+            const result = await port.getCommerceFulfillmentOrderDetail(request.data);
+            if (isNativeUnsupported(result)) {
+                sendBffError(res, "UPSTREAM_UNAVAILABLE", "Native fulfillment operation unsupported", { details: result });
+                return;
+            }
+            if (!result) {
+                sendBffError(res, "NOT_FOUND", "Commerce fulfillment order not found");
+                return;
+            }
+            const response = adminCommerceFulfillmentOrderDetailResponseSchema.safeParse(result);
+            if (!response.success) {
+                sendBffError(res, "INVALID_RESPONSE", "Admin commerce fulfillment detail response invalid");
+                return;
+            }
+            sendBffSuccess(res, response.data);
+        }
+        catch {
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin commerce fulfillment detail read failed");
+        }
+    };
+}
+export function createAdminCommerceFulfillmentCreateOrderHandler({ authorizeAdmin, respond, fulfillmentPort, }) {
+    return createMutationHandler({
+        authorizeAdmin,
+        respond,
+        requestSchema: adminCommerceFulfillmentCreateRequestSchema,
+        invalidMessage: "Invalid admin commerce fulfillment create request",
+        execute: (request, actorUserId) => {
+            const port = resolvePort(fulfillmentPort);
+            return port.createCommerceFulfillmentOrder({ ...request, actorUserId });
+        },
+    });
+}
+export function createAdminCommerceFulfillmentRecordProviderAttemptHandler({ authorizeAdmin, respond, fulfillmentPort, }) {
+    return createMutationHandler({
+        authorizeAdmin,
+        respond,
+        requestSchema: adminCommerceFulfillmentRecordProviderAttemptRequestSchema,
+        invalidMessage: "Invalid admin commerce fulfillment provider attempt request",
+        execute: (request, actorUserId) => {
+            const port = resolvePort(fulfillmentPort);
+            return port.recordCommerceFulfillmentProviderAttempt({ ...request, actorUserId });
+        },
+    });
+}
+export function createAdminCommerceFulfillmentRecordLabelHandler({ authorizeAdmin, respond, fulfillmentPort, }) {
+    return createMutationHandler({
+        authorizeAdmin,
+        respond,
+        requestSchema: adminCommerceFulfillmentRecordLabelRequestSchema,
+        invalidMessage: "Invalid admin commerce fulfillment label request",
+        execute: (request, actorUserId) => {
+            const port = resolvePort(fulfillmentPort);
+            return port.recordCommerceFulfillmentLabel({ ...request, actorUserId });
+        },
+    });
+}
+export function createAdminCommerceFulfillmentHandOffHandler({ authorizeAdmin, respond, fulfillmentPort, }) {
+    return createMutationHandler({
+        authorizeAdmin,
+        respond,
+        requestSchema: adminCommerceFulfillmentHandOffRequestSchema,
+        invalidMessage: "Invalid admin commerce fulfillment handoff request",
+        execute: (request, actorUserId) => {
+            const port = resolvePort(fulfillmentPort);
+            return port.handOffCommerceFulfillmentOrder({ ...request, actorUserId });
+        },
+    });
+}
+export function createAdminCommerceFulfillmentTrackingEventHandler({ authorizeAdmin, respond, fulfillmentPort, }) {
+    return createMutationHandler({
+        authorizeAdmin,
+        respond,
+        requestSchema: adminCommerceFulfillmentTrackingEventRequestSchema,
+        invalidMessage: "Invalid admin commerce fulfillment tracking event request",
+        execute: (request, actorUserId) => {
+            const port = resolvePort(fulfillmentPort);
+            return port.recordCommerceFulfillmentTrackingEvent({ ...request, actorUserId });
+        },
+    });
+}
+export function createAdminCommerceFulfillmentCancelOrderHandler({ authorizeAdmin, respond, fulfillmentPort, }) {
+    return createMutationHandler({
+        authorizeAdmin,
+        respond,
+        requestSchema: adminCommerceFulfillmentCancelRequestSchema,
+        invalidMessage: "Invalid admin commerce fulfillment cancel request",
+        execute: (request, actorUserId) => {
+            const port = resolvePort(fulfillmentPort);
+            return port.cancelCommerceFulfillmentOrder({ ...request, actorUserId });
+        },
+    });
+}
+function resolvePort(port) {
+    return typeof port === "function" ? port() : port;
+}
+function createMutationHandler({ authorizeAdmin, respond, requestSchema, invalidMessage, execute, }) {
+    const { sendBffError, sendBffSuccess, 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 = requestSchema.safeParse(req.body ?? {});
+        if (request.success === false) {
+            sendBffError(res, "BAD_REQUEST", invalidMessage, { details: request.error.flatten() });
+            return;
+        }
+        try {
+            const result = await execute(request.data, auth.userId);
+            if (isNativeUnsupported(result)) {
+                sendBffError(res, "UPSTREAM_UNAVAILABLE", "Native fulfillment operation unsupported", { details: result });
+                return;
+            }
+            const response = adminCommerceFulfillmentMutationResponseSchema.safeParse(result);
+            if (!response.success) {
+                sendBffError(res, "INVALID_RESPONSE", "Admin commerce fulfillment mutation response invalid");
+                return;
+            }
+            sendBffSuccess(res, response.data);
+        }
+        catch (error) {
+            if (error instanceof CommerceFulfillmentConflictError) {
+                sendBffError(res, "CONFLICT", error.message, { details: error.details });
+                return;
+            }
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin commerce fulfillment mutation failed", {
+                details: { reason: "fulfillment_mutation_failed" },
+            });
+        }
+    };
+}

package/dist/fulfillment/commerceFulfillmentReadModel.d.ts

@@ -0,0 +1,86 @@
+import type { FulfillmentCommerceReadPolicy, FulfillmentPaymentStatus, FulfillmentOrderStatus as OrderStatus } from './contracts/read.js';
+import type { SubscriptionCycleStatus } from '@openlup/core/subscription';
+import { type AdminCommerceFulfillmentOrderDetailResponse, type AdminCommerceFulfillmentOrdersListResponse, type CommerceFulfillmentOrder, type CommerceFulfillmentOperationType, type CommerceFulfillmentStatus } from "./handlerSchemas.js";
+export interface CommerceFulfillmentOrderRow {
+    id: string;
+    order_id: string;
+    client_id: string | null;
+    status: CommerceFulfillmentStatus;
+    provider_kind: string | null;
+    shipping_address_snapshot: CommerceFulfillmentOrder["shippingAddress"];
+    created_at: string;
+    updated_at: string;
+}
+export interface CommerceFulfillmentLineRow {
+    id: string;
+    fulfillment_order_id: string;
+    order_item_id: string;
+    sku_id: string;
+    sku: string;
+    title: string | null;
+    quantity: number;
+    inventory_reservation_ids: string[];
+    product_snapshot: Record<string, unknown>;
+}
+export interface CommerceFulfillmentOperationRow {
+    id: string;
+    fulfillment_order_id: string;
+    operation_type: CommerceFulfillmentOperationType;
+    actor_user_id: string | null;
+    occurred_at: string;
+    payload: Record<string, unknown>;
+}
+export interface CommerceFulfillmentOrderContextRow {
+    id: string;
+    status: OrderStatus;
+    mode: "one_time" | "subscription_cycle";
+    shipping_address_id: string | null;
+    subscription_cycle_id: string | null;
+}
+export interface CommerceFulfillmentPaymentIntentRow {
+    id: string;
+    order_id: string;
+    status: FulfillmentPaymentStatus;
+    provider_payment_id: string | null;
+}
+export interface CommerceFulfillmentInventoryReservationRow {
+    id: string;
+    order_id: string;
+    status: "reserved" | "released" | "consumed" | "expired";
+    expires_at: string | null;
+    location_id: string | null;
+    inventory_locations?: {
+        code?: string | null;
+    } | null;
+}
+export interface CommerceFulfillmentShipmentRefRow {
+    order_id: string;
+    provider_tracking_id: string;
+    active: boolean;
+    created_at?: string | null;
+}
+export declare function buildCommerceFulfillmentOrdersListResponse(input: {
+    fulfillmentOrders: CommerceFulfillmentOrderRow[];
+    lines: CommerceFulfillmentLineRow[];
+    latestOperations: CommerceFulfillmentOperationRow[];
+    orderContexts: CommerceFulfillmentOrderContextRow[];
+    paymentIntents: CommerceFulfillmentPaymentIntentRow[];
+    inventoryReservations: CommerceFulfillmentInventoryReservationRow[];
+    shipmentRefs: CommerceFulfillmentShipmentRefRow[];
+    activeHoldCounts: Record<string, number>;
+    subscriptionCycleStatuses: Record<string, SubscriptionCycleStatus | null>;
+    totalCount: number;
+    page: number;
+    pageSize: number;
+}, policy: FulfillmentCommerceReadPolicy): AdminCommerceFulfillmentOrdersListResponse;
+export declare function buildCommerceFulfillmentOrderDetailResponse(input: {
+    fulfillmentOrder: CommerceFulfillmentOrderRow;
+    lines: CommerceFulfillmentLineRow[];
+    latestOperation: CommerceFulfillmentOperationRow | null;
+    orderContext: CommerceFulfillmentOrderContextRow;
+    paymentIntent: CommerceFulfillmentPaymentIntentRow;
+    inventoryReservations: CommerceFulfillmentInventoryReservationRow[];
+    shipmentRef: CommerceFulfillmentShipmentRefRow | null;
+    activeHoldCount: number;
+    subscriptionCycleStatus: SubscriptionCycleStatus | null;
+}, policy: FulfillmentCommerceReadPolicy): AdminCommerceFulfillmentOrderDetailResponse;