@openlup/platform 0.22.0 → 0.23.0

package/dist/subscriptions/renewalCycleRefusalMechanism.d.ts

@@ -0,0 +1,41 @@
+import type { PaymentAttemptStatus, PaymentExecutionProviderDecline, ProviderAttemptIdentity } from "@openlup/core/payment";
+import type { HostedRenewalDue, SubscriptionRenewalChargeResult, SubscriptionCycleSnapshotResult, SubscriptionCycleOrderResult, RenewalIntentResult, RenewalPreflightDeps, RenewalFailureDeps, RenewalOutcomeContext, RenewalReplayContext, FailurePropagationResult } from "./contracts/renewal.js";
+import { type RenewalFailurePolicy } from "./renewalCycleFailureMechanism.js";
+export interface RenewalPreflightPolicy<D extends HostedRenewalDue, CI, IR extends RenewalIntentResult> {
+    isOperatorOnly(reason: string): boolean;
+    logOperatorBlock(fields: {
+        subscriptionId: string;
+        providerKind: string;
+        reason: string;
+    }): void;
+    readTotal(snapshot: Record<string, unknown>): number | null;
+    cycleKey(due: D): string;
+    executionKey(cycleKey: string, retry: number, sequence: number): string;
+    intentInput(due: D, key: string, snapshots: SubscriptionCycleSnapshotResult, order: SubscriptionCycleOrderResult, total: number, reason: string): CI;
+    identity(due: D, key: string, intent: IR, order: SubscriptionCycleOrderResult, total: number): ProviderAttemptIdentity;
+    normalizedProvider(provider: string): string;
+    failed(due: D, cycleId: string | null, cycleNumber: number | null, orderId: string | null, intentId: string | null, reason: string, propagation?: FailurePropagationResult): SubscriptionRenewalChargeResult;
+    invalidTotalsReason: string;
+    defaultNow(): string;
+    failure: RenewalFailurePolicy;
+}
+export interface RenewalOutcomePolicy {
+    declineReason(decline: PaymentExecutionProviderDecline): string;
+    classifyDecline(decline: PaymentExecutionProviderDecline): {
+        failureClass: string;
+        decidedBy: string;
+    };
+    scaReason: string;
+    defaultNow(): string;
+    failure: RenewalFailurePolicy;
+}
+export interface RenewalReplayPolicy extends Pick<RenewalOutcomePolicy, "scaReason" | "defaultNow" | "failure"> {
+    unacknowledgedReason(status: PaymentAttemptStatus): string;
+}
+/** Alternate preflight owns its full order/intent/failure chain, without reservation or dispatch. */
+export declare function recordRenewalPreflightBlock<D extends HostedRenewalDue, CI, IR extends RenewalIntentResult, M extends string | null | undefined>(deps: RenewalPreflightDeps<CI, IR, M>, due: D, reason: string, policy: RenewalPreflightPolicy<D, CI, IR>): Promise<SubscriptionRenewalChargeResult>;
+export declare function declinedRenewalOutcome<D extends HostedRenewalDue>(deps: RenewalFailureDeps, due: D, context: RenewalOutcomeContext & {
+    decline: PaymentExecutionProviderDecline;
+}, policy: RenewalOutcomePolicy): Promise<SubscriptionRenewalChargeResult>;
+export declare function requiresActionRenewalOutcome<D extends HostedRenewalDue>(deps: RenewalFailureDeps, due: D, context: RenewalOutcomeContext, policy: RenewalOutcomePolicy): Promise<SubscriptionRenewalChargeResult>;
+export declare function replayRenewalAttempt<D extends HostedRenewalDue>(deps: RenewalFailureDeps, due: D, ctx: RenewalReplayContext, status: PaymentAttemptStatus, policy: RenewalReplayPolicy): Promise<SubscriptionRenewalChargeResult>;

package/dist/subscriptions/renewalCycleRefusalMechanism.js

@@ -0,0 +1,160 @@
+import { propagateRenewalFailure } from "./renewalCycleFailureMechanism.js";
+/** Alternate preflight owns its full order/intent/failure chain, without reservation or dispatch. */
+export async function recordRenewalPreflightBlock(deps, due, reason, policy) {
+    if (policy.isOperatorOnly(reason)) {
+        policy.logOperatorBlock({ subscriptionId: due.subscriptionId, providerKind: due.providerKind, reason });
+        return policy.failed(due, null, null, null, null, reason);
+    }
+    const snapshots = await deps.persistence.buildCycleSnapshots({
+        subscriptionId: due.subscriptionId,
+        scheduledAt: due.nextCycleAt,
+    });
+    const totalGrossMinor = policy.readTotal(snapshots.orderSnapshot);
+    if (totalGrossMinor === null) {
+        return policy.failed(due, null, snapshots.cycleNumber, null, null, policy.invalidTotalsReason);
+    }
+    const cycleKey = policy.cycleKey(due);
+    const cycleOrder = await deps.persistence.createCycleOrder({
+        idempotencyKey: cycleKey,
+        subscriptionId: due.subscriptionId,
+        cycleNumber: snapshots.cycleNumber,
+        scheduledAt: due.nextCycleAt,
+        templateSnapshot: snapshots.templateSnapshot,
+        pricingSnapshot: snapshots.pricingSnapshot,
+        orderSnapshot: snapshots.orderSnapshot,
+    });
+    const intent = await deps.paymentPort.createIntent(policy.intentInput(due, cycleKey, snapshots, cycleOrder, totalGrossMinor, reason));
+    const executionKey = policy.executionKey(cycleKey, snapshots.retryAttempt, snapshots.providerAttemptSequence);
+    const attempt = policy.identity(due, executionKey, intent, cycleOrder, totalGrossMinor);
+    const propagation = await propagateRenewalFailure(deps.chargeFailurePropagation, {
+        kind: "preflight_block",
+        executionIdempotencyKey: executionKey,
+        providerIdempotencyKey: attempt.providerIdempotencyKey,
+        providerRequestFingerprint: attempt.providerRequestFingerprint,
+        paymentIntentId: intent.paymentIntentId,
+        cycleId: cycleOrder.cycleId,
+        subscriptionId: due.subscriptionId,
+        orderUuid: cycleOrder.orderUuid,
+        providerKind: policy.normalizedProvider(due.providerKind),
+        failureReason: reason,
+        occurredAt: (deps.now ?? policy.defaultNow)(),
+    }, policy.failure);
+    return policy.failed(due, cycleOrder.cycleId, snapshots.cycleNumber, cycleOrder.orderUuid, intent.paymentIntentId, reason, propagation);
+}
+export async function declinedRenewalOutcome(deps, due, context, policy) {
+    const propagation = await propagateRenewalFailure(deps.chargeFailurePropagation, {
+        kind: "provider_declined",
+        executionIdempotencyKey: context.executionIdempotencyKey,
+        providerIdempotencyKey: context.attemptIdentity.providerIdempotencyKey,
+        providerRequestFingerprint: context.attemptIdentity.providerRequestFingerprint,
+        paymentIntentId: context.intent.paymentIntentId,
+        cycleId: context.cycleOrder.cycleId,
+        subscriptionId: due.subscriptionId,
+        orderUuid: context.cycleOrder.orderUuid,
+        providerKind: due.providerKind,
+        failureReason: policy.declineReason(context.decline),
+        failureClassification: policy.classifyDecline(context.decline),
+        occurredAt: (deps.now ?? policy.defaultNow)(),
+        attemptAlreadyPrepared: true,
+    }, policy.failure);
+    return {
+        subscriptionId: due.subscriptionId,
+        outcome: "failed",
+        cycleId: context.cycleOrder.cycleId,
+        cycleNumber: context.snapshots.cycleNumber,
+        orderId: context.cycleOrder.orderUuid,
+        paymentIntentId: context.intent.paymentIntentId,
+        attemptStatus: "failed",
+        replayed: context.cycleOrder.replayed || context.intent.replayed,
+        dunningCaseId: propagation.dunningCaseId,
+        retryAttempt: propagation.retryAttempt,
+        applyReplayed: propagation.applyReplayed,
+        dunningPropagationFailed: propagation.dunningPropagationFailed,
+    };
+}
+export async function requiresActionRenewalOutcome(deps, due, context, policy) {
+    const propagation = await propagateRenewalFailure(deps.chargeFailurePropagation, {
+        kind: "off_session_requires_action",
+        executionIdempotencyKey: context.executionIdempotencyKey,
+        providerIdempotencyKey: context.attemptIdentity.providerIdempotencyKey,
+        providerRequestFingerprint: context.attemptIdentity.providerRequestFingerprint,
+        paymentIntentId: context.intent.paymentIntentId,
+        cycleId: context.cycleOrder.cycleId,
+        subscriptionId: due.subscriptionId,
+        orderUuid: context.cycleOrder.orderUuid,
+        providerKind: due.providerKind,
+        failureReason: policy.scaReason,
+        occurredAt: (deps.now ?? policy.defaultNow)(),
+        attemptAlreadyPrepared: true,
+    }, policy.failure);
+    return {
+        subscriptionId: due.subscriptionId,
+        outcome: "requires_action",
+        cycleId: context.cycleOrder.cycleId,
+        cycleNumber: context.snapshots.cycleNumber,
+        orderId: context.cycleOrder.orderUuid,
+        paymentIntentId: context.intent.paymentIntentId,
+        attemptStatus: context.finalizedAttempt.status,
+        replayed: context.cycleOrder.replayed || context.intent.replayed,
+        dunningCaseId: propagation.dunningCaseId,
+        retryAttempt: propagation.retryAttempt,
+        applyReplayed: propagation.applyReplayed,
+        dunningPropagationFailed: propagation.dunningPropagationFailed,
+    };
+}
+export async function replayRenewalAttempt(deps, due, ctx, status, policy) {
+    if (status === "requires_action") {
+        const propagation = await propagateRenewalFailure(deps.chargeFailurePropagation, {
+            kind: "off_session_requires_action",
+            executionIdempotencyKey: ctx.executionIdempotencyKey,
+            providerIdempotencyKey: ctx.providerIdempotencyKey,
+            providerRequestFingerprint: ctx.providerRequestFingerprint,
+            paymentIntentId: ctx.paymentIntentId,
+            cycleId: ctx.cycleId,
+            subscriptionId: due.subscriptionId,
+            orderUuid: ctx.orderId,
+            providerKind: ctx.providerKind,
+            failureReason: policy.scaReason,
+            occurredAt: (deps.now ?? policy.defaultNow)(),
+            attemptAlreadyPrepared: true,
+        }, policy.failure);
+        return {
+            subscriptionId: due.subscriptionId,
+            outcome: "requires_action",
+            cycleId: ctx.cycleId,
+            cycleNumber: ctx.cycleNumber,
+            orderId: ctx.orderId,
+            paymentIntentId: ctx.paymentIntentId,
+            attemptStatus: status,
+            replayed: true,
+            dunningCaseId: propagation.dunningCaseId,
+            retryAttempt: propagation.retryAttempt,
+            applyReplayed: propagation.applyReplayed,
+        };
+    }
+    if (status === "sent_to_provider" || status === "processing") {
+        return {
+            subscriptionId: due.subscriptionId,
+            outcome: "charged",
+            cycleId: ctx.cycleId,
+            cycleNumber: ctx.cycleNumber,
+            orderId: ctx.orderId,
+            paymentIntentId: ctx.paymentIntentId,
+            attemptStatus: status,
+            replayed: true,
+        };
+    }
+    return {
+        subscriptionId: due.subscriptionId,
+        outcome: "failed",
+        cycleId: ctx.cycleId,
+        cycleNumber: ctx.cycleNumber,
+        orderId: ctx.orderId,
+        paymentIntentId: ctx.paymentIntentId,
+        attemptStatus: status,
+        replayed: true,
+        dunningCaseId: null,
+        retryAttempt: null,
+        reason: policy.unacknowledgedReason(status),
+    };
+}

package/dist/subscriptions/renewalIdentity.d.ts

@@ -0,0 +1,3 @@
+import type { RenewalIdentity, RenewalSchedule } from "./contracts/renewal.js";
+/** The host's existing dialect owns every byte; no normalization or new prefix. */
+export declare function renewalIdentity(schedule: RenewalSchedule, keys: (schedule: RenewalSchedule) => RenewalIdentity): RenewalIdentity;

package/dist/subscriptions/renewalIdentity.js

@@ -0,0 +1,4 @@
+/** The host's existing dialect owns every byte; no normalization or new prefix. */
+export function renewalIdentity(schedule, keys) {
+    return keys(schedule);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlup/platform",
-  "version": "0.22.0",
+  "version": "0.23.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.22.0",
+    "@openlup/core": "0.23.0",
     "pg": "^8.22.0",
     "@aws-sdk/client-s3": "^3.1144.0",
     "@types/pg": "^8.20.0"
@@ -210,6 +210,26 @@
       "types": "./dist/fulfillment/omnipack/index.d.ts",
       "import": "./dist/fulfillment/omnipack/index.js",
       "default": "./dist/fulfillment/omnipack/index.js"
+    },
+    "./subscriptions": {
+      "types": "./dist/subscriptions/index.d.ts",
+      "import": "./dist/subscriptions/index.js",
+      "default": "./dist/subscriptions/index.js"
+    },
+    "./subscriptions/contracts": {
+      "types": "./dist/subscriptions/contracts/index.d.ts",
+      "import": "./dist/subscriptions/contracts/index.js",
+      "default": "./dist/subscriptions/contracts/index.js"
+    },
+    "./invoicing": {
+      "types": "./dist/invoicing/index.d.ts",
+      "import": "./dist/invoicing/index.js",
+      "default": "./dist/invoicing/index.js"
+    },
+    "./invoicing/contracts": {
+      "types": "./dist/invoicing/contracts/index.d.ts",
+      "import": "./dist/invoicing/contracts/index.js",
+      "default": "./dist/invoicing/contracts/index.js"
     }
   },
   "repository": {

package/release-gates.json

@@ -455,6 +455,57 @@
       ],
       "entrypoint": "dist/fulfillment/omnipack/index.d.ts",
       "snapshot": "api/fulfillment-omnipack.api.md"
+    },
+    "./subscriptions": {
+      "role": "capability",
+      "maturity": "experimental",
+      "compatibilityPolicy": "internal-candidate",
+      "packageSmokeEvidence": [
+        "test/packageBoundary.test.ts",
+        "test/subscriptions/contracts.test.ts",
+        "test/subscriptions/portFit.test.ts",
+        "test/subscriptions/renewalKeys.test.ts",
+        "test/subscriptions/renewalCycleMechanism.test.ts"
+      ],
+      "entrypoint": "dist/subscriptions/index.d.ts",
+      "snapshot": "api/subscriptions.api.md"
+    },
+    "./subscriptions/contracts": {
+      "role": "capability",
+      "maturity": "experimental",
+      "compatibilityPolicy": "internal-candidate",
+      "packageSmokeEvidence": [
+        "test/packageBoundary.test.ts",
+        "test/subscriptions/contracts.test.ts",
+        "test/subscriptions/portFit.test.ts",
+        "test/subscriptions/renewalKeys.test.ts"
+      ],
+      "entrypoint": "dist/subscriptions/contracts/index.d.ts",
+      "snapshot": "api/subscriptions-contracts.api.md"
+    },
+    "./invoicing": {
+      "role": "capability",
+      "maturity": "experimental",
+      "compatibilityPolicy": "internal-candidate",
+      "packageSmokeEvidence": [
+        "test/packageBoundary.test.ts",
+        "test/invoicing/contracts.test.ts",
+        "test/invoicing/portFit.test.ts"
+      ],
+      "entrypoint": "dist/invoicing/index.d.ts",
+      "snapshot": "api/invoicing.api.md"
+    },
+    "./invoicing/contracts": {
+      "role": "capability",
+      "maturity": "experimental",
+      "compatibilityPolicy": "internal-candidate",
+      "packageSmokeEvidence": [
+        "test/packageBoundary.test.ts",
+        "test/invoicing/contracts.test.ts",
+        "test/invoicing/portFit.test.ts"
+      ],
+      "entrypoint": "dist/invoicing/contracts/index.d.ts",
+      "snapshot": "api/invoicing-contracts.api.md"
     }
   },
   "pack": {
@@ -470,8 +521,8 @@
     "maxUnpackedBytes": 5734400,
     "maxFiles": 2100,
     "baseline": {
-      "version": "0.21.0",
-      "packedBytes": 1008887
+      "version": "0.22.0",
+      "packedBytes": 1185082
     },
     "browserEntries": {
       "./catalog/contracts": 4096,
@@ -482,7 +533,9 @@
       "./promotions/contracts": 32,
       "./shipping/contracts": 32,
       "./payments/contracts": 32,
-      "./fulfillment/contracts": 32
+      "./fulfillment/contracts": 32,
+      "./subscriptions/contracts": 32,
+      "./invoicing/contracts": 32
     }
   }
 }