@openlup/platform 0.21.0 → 0.22.0

package/dist/fulfillment/verifiedIngress.js

@@ -0,0 +1,66 @@
+import { applyFulfillmentObservationEffects } from "./fulfillmentObservationEffects.js";
+import { observationStatusPolicy, projectObservation } from "./observationProjection.js";
+import { uniqueTrackingReferences } from "./providerTrackingReferences.js";
+/** Adapter verification owns auth-before-parse; the host owns durable replay. */
+export async function verifyAndNormalizeFulfillmentObservation(input) {
+    if (!input.enabled)
+        return { kind: "refused", 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);
+    const inbound = await input.localPersistence.recordObservation(observation);
+    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 };
+    }
+    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;
+            await input.localPersistence.markProcessed(observation.eventKey, { status: "processed" });
+            return { kind: "superseded", 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 };
+}

package/dist/payments/stripe/index.d.ts

@@ -14,3 +14,28 @@ export interface StripePaymentAdapterConfig {
 export declare const stripePaymentCapabilities: Readonly<PaymentAdapterCapabilities>;
 /** Explicit construction is the only activation point; importing performs no I/O. */
 export declare function createStripePaymentAdapter(config: StripePaymentAdapterConfig): PaymentAdapter;
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/adapters/stripe/stripeAdapterFactory.ts`.
+ */
+export { createStripeSandboxPaymentExecutionAdapter } from "./stripeSandboxPaymentExecutionAdapter.js";
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/runtime/paymentProviderReadbackRegistry.ts`.
+ */
+export { createStripePaymentReconciliationProvider } from "./stripePaymentReconciliationProvider.js";
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/infra/stripe/stripeApiClient.ts`.
+ */
+export { mapStripeIntent } from "./intentMapper.js";
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/infra/stripe/stripeApiClient.ts`.
+ */
+export { mapSetupIntent } from "./intentMapper.js";
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/adapters/paymentRecoveryGuidance.ts`.
+ */
+export { normalizeStripeFailureEvidence } from "./stripeFailureEvidence.js";

package/dist/payments/stripe/index.js

@@ -237,3 +237,28 @@ function mapVerifiedStripeEvent(raw) {
     return { ...result, fingerprint: createHash("sha256").update(JSON.stringify(result)).digest("hex"),
         providerAuditPayload: normalized.rawPayload };
 }
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/adapters/stripe/stripeAdapterFactory.ts`.
+ */
+export { createStripeSandboxPaymentExecutionAdapter } from "./stripeSandboxPaymentExecutionAdapter.js";
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/runtime/paymentProviderReadbackRegistry.ts`.
+ */
+export { createStripePaymentReconciliationProvider } from "./stripePaymentReconciliationProvider.js";
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/infra/stripe/stripeApiClient.ts`.
+ */
+export { mapStripeIntent } from "./intentMapper.js";
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/infra/stripe/stripeApiClient.ts`.
+ */
+export { mapSetupIntent } from "./intentMapper.js";
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/adapters/paymentRecoveryGuidance.ts`.
+ */
+export { normalizeStripeFailureEvidence } from "./stripeFailureEvidence.js";

package/dist/payments/tpay/index.d.ts

@@ -41,3 +41,33 @@ export interface TpayPaymentAdapterConfig {
 }
 /** Construction explicitly selects this adapter; the host owns account activation and I/O policy. */
 export declare function createTpayPaymentAdapter(config: TpayPaymentAdapterConfig): PaymentAdapter;
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/adapters/tpay/tpayAdapterFactory.ts`.
+ */
+export { createTpayPaymentExecutionAdapter } from "./tpayPaymentExecutionAdapter.js";
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/runtime/paymentProviderReadbackRegistry.ts`.
+ */
+export { createTpayPaymentReconciliationProvider } from "./tpayPaymentReconciliationProvider.js";
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/bff/commerce/tpay-channels.ts`.
+ */
+export { createTpayHttpClient } from "./tpayHttpClient.js";
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/adapters/paymentRecoveryGuidance.ts`.
+ */
+export { normalizeTpayFailureEvidence } from "./tpayFailureEvidence.js";
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/adapters/supabase/payment/tpaySubscriptionActivation.ts`.
+ */
+export { aliasValue } from "./tpayCreateTransactionInput.js";
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/shared/preparedProviderAttempt.ts`.
+ */
+export { ProviderAttemptPreDispatchError } from "./preparedProviderAttempt.js";

package/dist/payments/tpay/index.js

@@ -262,3 +262,33 @@ function mapVerifiedTpayEvent(rawBody, occurred, mode, supportedCurrencies) {
     return { ...evidence, fingerprint: createHash("sha256").update(JSON.stringify(evidence)).digest("hex"),
         providerAuditPayload: payload };
 }
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/adapters/tpay/tpayAdapterFactory.ts`.
+ */
+export { createTpayPaymentExecutionAdapter } from "./tpayPaymentExecutionAdapter.js";
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/runtime/paymentProviderReadbackRegistry.ts`.
+ */
+export { createTpayPaymentReconciliationProvider } from "./tpayPaymentReconciliationProvider.js";
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/bff/commerce/tpay-channels.ts`.
+ */
+export { createTpayHttpClient } from "./tpayHttpClient.js";
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/adapters/paymentRecoveryGuidance.ts`.
+ */
+export { normalizeTpayFailureEvidence } from "./tpayFailureEvidence.js";
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/adapters/supabase/payment/tpaySubscriptionActivation.ts`.
+ */
+export { aliasValue } from "./tpayCreateTransactionInput.js";
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/shared/preparedProviderAttempt.ts`.
+ */
+export { ProviderAttemptPreDispatchError } from "./preparedProviderAttempt.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlup/platform",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "private": false,
   "description": "Runnable server substrate: Node HTTP runtime, BFF dispatch, scheduler, storage, data gateways and bundle composition; development preview.",
   "license": "Apache-2.0",
@@ -31,7 +31,7 @@
     "api:update": "npm run build && node --experimental-strip-types ./scripts/api-contract.ts --update"
   },
   "peerDependencies": {
-    "@openlup/core": "0.21.0",
+    "@openlup/core": "0.22.0",
     "pg": "^8.22.0",
     "@aws-sdk/client-s3": "^3.1144.0",
     "@types/pg": "^8.20.0"
@@ -195,6 +195,21 @@
       "types": "./dist/payments/tpay/index.d.ts",
       "import": "./dist/payments/tpay/index.js",
       "default": "./dist/payments/tpay/index.js"
+    },
+    "./fulfillment": {
+      "types": "./dist/fulfillment/index.d.ts",
+      "import": "./dist/fulfillment/index.js",
+      "default": "./dist/fulfillment/index.js"
+    },
+    "./fulfillment/contracts": {
+      "types": "./dist/fulfillment/contracts/index.d.ts",
+      "import": "./dist/fulfillment/contracts/index.js",
+      "default": "./dist/fulfillment/contracts/index.js"
+    },
+    "./fulfillment/omnipack": {
+      "types": "./dist/fulfillment/omnipack/index.d.ts",
+      "import": "./dist/fulfillment/omnipack/index.js",
+      "default": "./dist/fulfillment/omnipack/index.js"
     }
   },
   "repository": {

package/release-gates.json

@@ -415,6 +415,46 @@
       ],
       "entrypoint": "dist/payments/tpay/index.d.ts",
       "snapshot": "api/payments-tpay.api.md"
+    },
+    "./fulfillment": {
+      "role": "capability",
+      "maturity": "experimental",
+      "compatibilityPolicy": "internal-candidate",
+      "packageSmokeEvidence": [
+        "test/packageBoundary.test.ts",
+        "test/fulfillment/contracts.test.ts",
+        "test/fulfillment/portFit.test.ts",
+        "test/fulfillment/dispatchRecovery.test.ts",
+        "test/fulfillment/paidHandoff.test.ts",
+        "test/fulfillment/providerCommandLedger.test.ts",
+        "test/fulfillment/postgresStore.test.ts"
+      ],
+      "entrypoint": "dist/fulfillment/index.d.ts",
+      "snapshot": "api/fulfillment.api.md"
+    },
+    "./fulfillment/contracts": {
+      "role": "capability",
+      "maturity": "experimental",
+      "compatibilityPolicy": "internal-candidate",
+      "packageSmokeEvidence": [
+        "test/packageBoundary.test.ts",
+        "test/fulfillment/contracts.test.ts",
+        "test/fulfillment/portFit.test.ts"
+      ],
+      "entrypoint": "dist/fulfillment/contracts/index.d.ts",
+      "snapshot": "api/fulfillment-contracts.api.md"
+    },
+    "./fulfillment/omnipack": {
+      "role": "capability",
+      "maturity": "experimental",
+      "compatibilityPolicy": "internal-candidate",
+      "packageSmokeEvidence": [
+        "test/fulfillment/omnipack/conformance.test.ts",
+        "test/fulfillment/omnipack/factory.test.ts",
+        "test/fulfillment/omnipack/transportAdaptation.test.ts"
+      ],
+      "entrypoint": "dist/fulfillment/omnipack/index.d.ts",
+      "snapshot": "api/fulfillment-omnipack.api.md"
     }
   },
   "pack": {
@@ -430,8 +470,8 @@
     "maxUnpackedBytes": 5734400,
     "maxFiles": 2100,
     "baseline": {
-      "version": "0.20.0",
-      "packedBytes": 809376
+      "version": "0.21.0",
+      "packedBytes": 1008887
     },
     "browserEntries": {
       "./catalog/contracts": 4096,
@@ -441,7 +481,8 @@
       "./pricing/contracts": 416,
       "./promotions/contracts": 32,
       "./shipping/contracts": 32,
-      "./payments/contracts": 32
+      "./payments/contracts": 32,
+      "./fulfillment/contracts": 32
     }
   }
 }