@openlup/platform 0.22.0 → 0.24.0

package/dist/invoicing/settlementSync.d.ts

@@ -0,0 +1,18 @@
+import type { InvoiceSettlementPort, InvoiceSettlementItem } from "./contracts/settlement.js";
+/** Preserve each immutable balance item, nullable links and original host key.
+ * Transport, resolution and richer durable item storage remain host-owned.
+ * Legacy batch/payment receipts may collapse items: later reuse is returned as
+ * identity_mismatch without another write; processing continues. Only an item-capable
+ * recorder can produce distinct recorded receipts. This records bank evidence only and has no payment-success writer.
+ */
+export declare function syncInvoicePayoutSettlements<Item>(input: {
+    list(limit: number): Promise<readonly Item[]>;
+    project(item: Item): InvoiceSettlementItem | Promise<InvoiceSettlementItem>;
+    settlement: Pick<InvoiceSettlementPort, "record">;
+    limit?: number;
+}): Promise<{
+    checked: number;
+    recorded: number;
+    replayed: number;
+    items: Awaited<ReturnType<InvoiceSettlementPort["record"]>>[];
+}>;

package/dist/invoicing/settlementSync.js

@@ -0,0 +1,32 @@
+/** Preserve each immutable balance item, nullable links and original host key.
+ * Transport, resolution and richer durable item storage remain host-owned.
+ * Legacy batch/payment receipts may collapse items: later reuse is returned as
+ * identity_mismatch without another write; processing continues. Only an item-capable
+ * recorder can produce distinct recorded receipts. This records bank evidence only and has no payment-success writer.
+ */
+export async function syncInvoicePayoutSettlements(input) {
+    const items = await input.list(input.limit ?? 10);
+    const result = { checked: items.length, recorded: 0, replayed: 0, items: [] };
+    const receipts = new Map();
+    for (const item of items) {
+        const evidence = await input.project(item);
+        const write = await input.settlement.record(evidence);
+        if (write.kind !== "recorded" || write.itemRef !== evidence.itemRef) {
+            // Unknown/conflict/unsupported are never counted as accepted evidence.
+            throw new Error(write.kind === "conflict" ? write.code : write.kind === "unknown" ? "unknown" : "unsupported");
+        }
+        const scope = JSON.stringify([evidence.providerRef, evidence.batchRef, evidence.itemRef, evidence.providerPaymentRef]);
+        const previous = receipts.get(write.settlementItemRef);
+        if (previous !== undefined && previous !== scope) {
+            result.items.push({ kind: "conflict", itemRef: evidence.itemRef, code: "identity_mismatch" });
+            continue;
+        }
+        receipts.set(write.settlementItemRef, scope);
+        result.items.push(write);
+        if (write.replayed)
+            result.replayed += 1;
+        else
+            result.recorded += 1;
+    }
+    return result;
+}

package/dist/invoicing/snapshot.d.ts

@@ -0,0 +1,52 @@
+interface Options {
+    defaultLineLabel: string;
+    deliveryLabel: string;
+    defaultTaxRate: string;
+}
+/** Compatibility projection of a claimed host snapshot, not a second store contract.
+ * Seller/date/kind/payment selection remains with the host; no environment is read.
+ */
+export declare function mapInvoiceClaimToProviderSnapshot<Seller, Kind, Payment>(input: {
+    orderRef: string;
+    issueDate: string;
+    sellDate: string;
+    currency: string;
+    seller: Seller;
+    buyerSnapshot: Record<string, unknown>;
+    documentKind: Kind;
+    governmentClearanceRequired: boolean;
+    payment: Payment;
+    linesSnapshot: unknown[];
+    totalGrossMinor: number;
+    totalNetMinor: number;
+    orderMoney: unknown;
+}, options: Options & {
+    defaultBuyerLabel: string;
+}): {
+    orderRef: string;
+    issueDate: string;
+    sellDate: string;
+    currency: string;
+    seller: Seller;
+    buyer: {
+        name: string;
+        email: string | null;
+        taxId: string | null;
+        companyName: string | null;
+        address: {
+            readonly line1: string | null;
+            readonly postalCode: string | null;
+            readonly city: string | null;
+            readonly country: string | null;
+        };
+    };
+    documentKind: Kind;
+    governmentClearanceRequired: boolean;
+    payment: Payment;
+    lines: (Pick<import("./contracts/facts.js").InvoiceLine, "quantity" | "unitGrossMinor" | "unitNetMinor" | "totalGrossMinor" | "totalNetMinor"> & {
+        name: string;
+        vatRate: string;
+    })[];
+    chargedTotalGrossMinor: number;
+};
+export {};

package/dist/invoicing/snapshot.js

@@ -0,0 +1,141 @@
+import { mapCanonicalIssueLines } from "./accountingCanonicalProviderLines.js";
+import { allocateChargedGrossTotals } from "./accountingLineAllocation.js";
+/** Compatibility projection of a claimed host snapshot, not a second store contract.
+ * Seller/date/kind/payment selection remains with the host; no environment is read.
+ */
+export function mapInvoiceClaimToProviderSnapshot(input, options) {
+    return {
+        orderRef: input.orderRef,
+        issueDate: input.issueDate,
+        sellDate: input.sellDate,
+        currency: input.currency,
+        seller: input.seller,
+        buyer: {
+            name: textValue(input.buyerSnapshot.name) ?? options.defaultBuyerLabel,
+            email: textValue(input.buyerSnapshot.email),
+            taxId: textValue(input.buyerSnapshot.taxId),
+            companyName: textValue(input.buyerSnapshot.companyName),
+            address: mapBuyerAddress(input.buyerSnapshot.address),
+        },
+        documentKind: input.documentKind,
+        governmentClearanceRequired: input.governmentClearanceRequired,
+        payment: input.payment,
+        lines: mapIssueLinesToChargedTotal(input.linesSnapshot, input.totalGrossMinor, input.totalNetMinor, input.orderMoney, options),
+        chargedTotalGrossMinor: input.totalGrossMinor,
+    };
+}
+// Canonical issue snapshots already carry effective item and explicit delivery
+// positions and are verified as a zero-delta passthrough. Historical snapshots
+// without positionKind retain the independent #1693 reconciliation below.
+function mapIssueLinesToChargedTotal(linesSnapshot, chargedTotalGrossMinor, chargedTotalNetMinor, orderMoney, options) {
+    const canonicalKinds = linesSnapshot.map((line) => textValue(isRecord(line) ? line.positionKind : null));
+    if (canonicalKinds.some(Boolean)) {
+        if (!canonicalKinds.every((kind) => kind === "item" || kind === "delivery")) {
+            throw new Error("accounting_invoice_canonical_positions_mixed_or_invalid");
+        }
+        return mapCanonicalIssueLines(linesSnapshot, chargedTotalGrossMinor, chargedTotalNetMinor, options.defaultLineLabel);
+    }
+    const parsed = linesSnapshot.map((line) => parseLineSnapshot(line, options));
+    const deliveryGrossMinor = readDeliveryGrossMinor(orderMoney, chargedTotalGrossMinor);
+    const chargedTotals = allocateChargedGrossTotals(parsed.map((line) => line.totalGrossMinor), chargedTotalGrossMinor - deliveryGrossMinor);
+    const positions = parsed.map((line, index) => {
+        const totalGrossMinor = chargedTotals[index];
+        const totalNetMinor = estimateNetMinor(totalGrossMinor, line.vatRate);
+        return {
+            name: line.name,
+            quantity: line.quantity,
+            unitGrossMinor: Math.round(totalGrossMinor / line.quantity),
+            unitNetMinor: Math.round(totalNetMinor / line.quantity),
+            totalGrossMinor,
+            totalNetMinor,
+            vatRate: line.vatRate,
+        };
+    });
+    if (deliveryGrossMinor > 0) {
+        positions.push(buildDeliveryPosition(deliveryGrossMinor, parsed, options));
+    }
+    return positions;
+}
+// Legacy-only compatibility: pre-canonical claims had no explicit delivery
+// position, so their effective delivery is the closed header residual. Current
+// canonical claims never enter this path and use persisted shipping columns.
+// Every inconsistent legacy shape degrades to 0 and then fails closed if the
+// catalog lines cannot reconcile to the charged header.
+function readDeliveryGrossMinor(orderMoney, chargedTotalGrossMinor) {
+    if (!isRecord(orderMoney))
+        return 0;
+    const subtotal = numberValue(orderMoney.subtotalCents);
+    const discount = numberValue(orderMoney.discountCents);
+    const total = numberValue(orderMoney.totalCents);
+    if (subtotal === null || discount === null || total === null)
+        return 0;
+    if (![subtotal, discount, total].every((value) => Number.isInteger(value) && value >= 0))
+        return 0;
+    if (discount > subtotal)
+        return 0;
+    if (total !== chargedTotalGrossMinor)
+        return 0;
+    const deliveryGrossMinor = chargedTotalGrossMinor - (subtotal - discount);
+    return deliveryGrossMinor > 0 ? deliveryGrossMinor : 0;
+}
+// Delivery is an ancillary supply and follows the goods' VAT rate; with mixed
+// item rates (or no item line to source a rate from) the correct rate is
+// ambiguous, so the claim fails closed into the outbox last_error.
+function buildDeliveryPosition(deliveryGrossMinor, itemLines, options) {
+    const rates = [...new Set(itemLines.map((line) => line.vatRate.trim()))];
+    if (rates.length === 0) {
+        throw new Error(`accounting_invoice_delivery_vat_rate_unavailable delivery=${deliveryGrossMinor}`);
+    }
+    if (rates.length > 1) {
+        throw new Error(`accounting_invoice_delivery_vat_rates_mixed rates=${rates.join(",")}`);
+    }
+    const vatRate = rates[0];
+    const totalNetMinor = estimateNetMinor(deliveryGrossMinor, vatRate);
+    return {
+        name: options.deliveryLabel,
+        quantity: 1,
+        unitGrossMinor: deliveryGrossMinor,
+        unitNetMinor: totalNetMinor,
+        totalGrossMinor: deliveryGrossMinor,
+        totalNetMinor,
+        vatRate,
+    };
+}
+function mapBuyerAddress(value) {
+    const address = isRecord(value) ? value : {};
+    return {
+        line1: textValue(address.line1),
+        postalCode: textValue(address.postalCode),
+        city: textValue(address.city),
+        country: textValue(address.country),
+    };
+}
+function parseLineSnapshot(value, options) {
+    const row = isRecord(value) ? value : {};
+    const quantity = numberValue(row.quantity) || 1;
+    const vatRate = textValue(row.vatRate) ?? options.defaultTaxRate;
+    // Legacy (pre-#1693) lines_snapshot rows carry only the per-unit
+    // unitGrossMinor, so the line total is unit price times quantity.
+    const unitGrossMinor = numberValue(row.unitGrossMinor);
+    const totalGrossMinor = numberValue(row.totalGrossMinor) ??
+        (unitGrossMinor === null ? 0 : unitGrossMinor * quantity);
+    return {
+        name: textValue(row.name) ?? options.defaultLineLabel,
+        quantity,
+        totalGrossMinor,
+        vatRate,
+    };
+}
+function estimateNetMinor(grossMinor, vatRate) {
+    const rate = Number(vatRate.replace(",", "."));
+    return Number.isFinite(rate) ? Math.round(grossMinor / (1 + rate / 100)) : grossMinor;
+}
+function textValue(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function numberValue(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

package/dist/subscriptions/automaticRenewal.d.ts

@@ -0,0 +1,44 @@
+import type { RenewalDue, RenewalExecutionRequest, RenewalFrozenSnapshot, RenewalPaymentRail, RenewalPreparedSettlement, RenewalReadback, RenewalReservationResult, RenewalSettlementPort, RenewalStorePort } from "./contracts/renewal.js";
+import type { RenewalFailureHandoffPort } from "./contracts/dunning.js";
+export type AutomaticRenewalRunStatus = "succeeded" | "refused" | "deferred" | "awaiting_provider" | "error" | "lease_active" | "terminal_replay";
+export interface AutomaticRenewalRunResult {
+    subscriptionId: string;
+    identityKey: string;
+    operationId: string;
+    status: AutomaticRenewalRunStatus;
+    replayed: boolean;
+    reason: string | null;
+    caseRef?: string;
+}
+export interface AutomaticRenewalPolicy {
+    executionInput(due: RenewalDue, operation: RenewalReadback, prepared: Pick<RenewalPreparedSettlement, "orderId" | "settlementIntentId">): RenewalExecutionRequest;
+    validateInput(input: RenewalExecutionRequest): void;
+    classifyFailure(reason: string): string;
+    identityKey(due: RenewalDue): string;
+}
+export interface AutomaticRenewalRunDeps {
+    store: RenewalStorePort;
+    inventory: {
+        expireReservations(input: {
+            now: string;
+            limit?: number;
+        }): Promise<number>;
+        reserve(input: {
+            operationId: string;
+            claimToken: string;
+            now: string;
+        }): Promise<RenewalReservationResult>;
+    };
+    settlement: RenewalSettlementPort;
+    paymentRails: {
+        resolve(channelKey: string): RenewalPaymentRail | null;
+    };
+    failureHandoff: RenewalFailureHandoffPort;
+    policy: AutomaticRenewalPolicy;
+    workerId: string;
+    now?: () => string;
+}
+export declare function runAutomaticSubscriptionRenewals(deps: AutomaticRenewalRunDeps, limit?: number): Promise<AutomaticRenewalRunResult[]>;
+export declare function runOneAutomaticSubscriptionRenewal(deps: AutomaticRenewalRunDeps, due: RenewalDue, occurredAt?: string): Promise<AutomaticRenewalRunResult>;
+/** No implicit +1: ambiguous history must be resolved by the host before opening a repair case. */
+export declare function correlatedLogicalCycle(snapshot: RenewalFrozenSnapshot): number;

package/dist/subscriptions/automaticRenewal.js

@@ -0,0 +1,81 @@
+import { automaticRenewalResult, handoffRefusal, recoverPreparedExternalAttempt, refuseRenewalBeforePayment, runRenewalBatchRows } from "./automaticRenewalExecution.js";
+import { readAndApplyProviderOutcome } from "./paymentOutcomes.js";
+export async function runAutomaticSubscriptionRenewals(deps, limit = 50) {
+    const now = (deps.now ?? defaultNow)();
+    await deps.inventory.expireReservations({ now, limit: Math.max(limit, 100) });
+    const due = await deps.store.listDue(limit, now);
+    return runRenewalBatchRows(due, row => runOneAutomaticSubscriptionRenewal(deps, row, now), deps.policy);
+}
+export async function runOneAutomaticSubscriptionRenewal(deps, due, occurredAt = (deps.now ?? defaultNow)()) {
+    const schedule = { subscriptionId: due.subscriptionId, scheduledAt: due.scheduledAt, scheduledInstant: due.scheduledInstant };
+    const snapshot = await deps.store.buildCycleSnapshots(schedule);
+    const claim = await deps.store.claimDue({ snapshot, workerId: deps.workerId, now: occurredAt });
+    if (claim.state === "succeeded" || claim.state === "refused")
+        return automaticRenewalResult(claim, "terminal_replay", claim.terminalReason);
+    if (!claim.acquired)
+        return automaticRenewalResult(claim, "lease_active", claim.reason);
+    const rail = deps.paymentRails.resolve(snapshot.settlementChannelKey);
+    if (!rail)
+        return refuseRenewalBeforePayment({ store: deps.store, operation: claim, reason: "settlement_channel_not_configured", occurredAt });
+    if (claim.state === "attempt_prepared")
+        return resumePreparedAttempt(deps, claim, rail, occurredAt);
+    const mandate = await deps.store.readMandateEvidence(schedule);
+    if (!mandate.authorized || mandate.authorizationRef !== snapshot.authorizationRef)
+        return refuseRenewalBeforePayment({ store: deps.store, operation: claim, reason: "authorization_evidence_mismatch", occurredAt });
+    const delivery = await deps.store.admitDeliveryAlignment({ ...schedule, occurredAt });
+    if (!delivery.allowed) {
+        if (delivery.deferred)
+            return { ...automaticRenewalResult(claim, "deferred", delivery.reason), ...(delivery.caseRef ? { caseRef: delivery.caseRef } : {}) };
+        return refuseRenewalBeforePayment({ store: deps.store, operation: claim, reason: delivery.reason, occurredAt });
+    }
+    const reservation = await deps.inventory.reserve({ operationId: claim.operationId, claimToken: claim.claimToken, now: occurredAt });
+    if (!reservation.reserved)
+        return automaticRenewalResult(claim, "refused", reservation.reason ?? "insufficient_atp");
+    const prepared = await deps.settlement.prepareRenewal({ operationId: claim.operationId, claimToken: claim.claimToken, now: occurredAt });
+    if (prepared.replayed) {
+        const readback = await deps.store.readRenewal(claim.identityKey);
+        if (!readback)
+            throw new Error("subscription_renewal_prepared_readback_missing");
+        return resumePreparedAttempt(deps, readback, rail, occurredAt);
+    }
+    const executionInput = deps.policy.executionInput(due, claim, prepared);
+    try {
+        deps.policy.validateInput(executionInput);
+    }
+    catch {
+        await deps.settlement.recordTerminalOutcome({ operationId: claim.operationId, eventKey: `${claim.identityKey}:provider-preflight`, operationFingerprint: claim.operationFingerprint, outcome: "refused", reason: "provider_input_invalid", occurredAt });
+        return automaticRenewalResult(claim, "refused", "provider_input_invalid");
+    }
+    let execution;
+    try {
+        execution = await rail.execute(executionInput);
+    }
+    catch {
+        return automaticRenewalResult(claim, "awaiting_provider", "provider_execution_indeterminate");
+    }
+    const externalAttemptRef = execution.externalAttemptRef?.trim() || null;
+    if (externalAttemptRef)
+        await deps.settlement.acknowledgeExternalAttempt({ operationId: claim.operationId, operationFingerprint: claim.operationFingerprint, externalAttemptRef, acknowledgedAt: occurredAt });
+    if (execution.failure || execution.status === "requires_action") {
+        const reason = execution.failure?.reason ?? (execution.status === "requires_action" ? "off_session_sca_required" : "provider_failed");
+        return handoffRefusal(deps, claim, prepared, externalAttemptRef, reason, execution.failure?.failureClass ?? deps.policy.classifyFailure(reason), occurredAt);
+    }
+    if (!externalAttemptRef)
+        return automaticRenewalResult(claim, "awaiting_provider", "provider_attempt_ack_missing");
+    return readAndApplyProviderOutcome(deps, claim, prepared, rail, externalAttemptRef, occurredAt);
+}
+async function resumePreparedAttempt(deps, operation, rail, occurredAt) {
+    if (!operation.cycleId || !operation.orderId || !operation.settlementIntentId)
+        throw new Error("subscription_renewal_prepared_artifacts_missing");
+    const externalAttemptRef = await recoverPreparedExternalAttempt({ operation, rail, settlement: deps.settlement, occurredAt });
+    if (!externalAttemptRef)
+        return automaticRenewalResult(operation, "awaiting_provider", "prepared_attempt_ack_missing");
+    return readAndApplyProviderOutcome(deps, operation, { cycleId: operation.cycleId, orderId: operation.orderId, settlementIntentId: operation.settlementIntentId }, rail, externalAttemptRef, occurredAt);
+}
+function defaultNow() { return new Date().toISOString(); }
+/** No implicit +1: ambiguous history must be resolved by the host before opening a repair case. */
+export function correlatedLogicalCycle(snapshot) {
+    if (snapshot.cycle.status !== "correlated")
+        throw new Error("subscription_renewal_cycle_correlation_required");
+    return snapshot.cycle.logicalCycleNumber;
+}

package/dist/subscriptions/automaticRenewalExecution.d.ts

@@ -0,0 +1,21 @@
+import type { RenewalDue, RenewalPaymentRail, RenewalReadback, RenewalSettlementPort, RenewalStorePort } from "./contracts/renewal.js";
+import type { AutomaticRenewalPolicy, AutomaticRenewalRunDeps, AutomaticRenewalRunResult, AutomaticRenewalRunStatus } from "./automaticRenewal.js";
+export declare function automaticRenewalResult(operation: RenewalReadback, status: AutomaticRenewalRunStatus, reason: string | null): AutomaticRenewalRunResult;
+export declare function recoverPreparedExternalAttempt(input: {
+    operation: RenewalReadback;
+    rail: RenewalPaymentRail;
+    settlement: RenewalSettlementPort;
+    occurredAt: string;
+}): Promise<string | null>;
+export declare function runRenewalBatchRows(due: RenewalDue[], run: (row: RenewalDue) => Promise<AutomaticRenewalRunResult>, policy: Pick<AutomaticRenewalPolicy, "identityKey">): Promise<AutomaticRenewalRunResult[]>;
+export declare function refuseRenewalBeforePayment(input: {
+    store: RenewalStorePort;
+    operation: RenewalReadback;
+    reason: string;
+    occurredAt: string;
+}): Promise<AutomaticRenewalRunResult>;
+export declare function handoffRefusal(deps: AutomaticRenewalRunDeps, operation: RenewalReadback, prepared: {
+    cycleId: string;
+    orderId: string;
+    settlementIntentId: string;
+}, externalAttemptRef: string | null, reason: string, failureClass: string, occurredAt: string): Promise<AutomaticRenewalRunResult>;

package/dist/subscriptions/automaticRenewalExecution.js

@@ -0,0 +1,44 @@
+import { nextRetryAttemptAt } from "@openlup/core/subscription";
+export function automaticRenewalResult(operation, status, reason) {
+    return { subscriptionId: operation.subscriptionId, identityKey: operation.identityKey, operationId: operation.operationId, status, replayed: operation.replayed, reason };
+}
+export async function recoverPreparedExternalAttempt(input) {
+    if (input.operation.externalAttemptRef)
+        return input.operation.externalAttemptRef;
+    if (!input.operation.settlementIntentId)
+        return null;
+    const externalAttemptRef = await input.rail.findExternalAttempt({ settlementIntentId: input.operation.settlementIntentId });
+    if (!externalAttemptRef)
+        return null;
+    await input.settlement.acknowledgeExternalAttempt({ operationId: input.operation.operationId, operationFingerprint: input.operation.operationFingerprint, externalAttemptRef, acknowledgedAt: input.occurredAt });
+    return externalAttemptRef;
+}
+export async function runRenewalBatchRows(due, run, policy) {
+    const results = [];
+    for (const row of due) {
+        try {
+            results.push(await run(row));
+        }
+        catch {
+            results.push({ subscriptionId: row.subscriptionId, identityKey: policy.identityKey(row), operationId: "", status: "error", replayed: false, reason: "renewal_processing_failed" });
+        }
+    }
+    return results;
+}
+export async function refuseRenewalBeforePayment(input) {
+    const refused = await input.store.refuseBeforePayment({ operationId: input.operation.operationId, claimToken: input.operation.claimToken, reason: input.reason, occurredAt: input.occurredAt });
+    return automaticRenewalResult(refused, "refused", input.reason);
+}
+const HANDOFF_OPENS_AT_RETRY_ATTEMPT = 1;
+export async function handoffRefusal(deps, operation, prepared, externalAttemptRef, reason, failureClass, occurredAt) {
+    await deps.failureHandoff.handoffFailure({
+        idempotencyKey: `${operation.identityKey}:failure-handoff`, subscriptionId: operation.subscriptionId,
+        clientId: operation.cycleSnapshot.clientId, cycleId: prepared.cycleId, orderId: prepared.orderId,
+        paymentIntentId: prepared.settlementIntentId, retryAttempt: HANDOFF_OPENS_AT_RETRY_ATTEMPT,
+        failureClass, failureReason: reason,
+        nextRetryAt: nextRetryAttemptAt(occurredAt, HANDOFF_OPENS_AT_RETRY_ATTEMPT, undefined, failureClass),
+        occurredAt, amountMinor: operation.cycleSnapshot.pricingSnapshot.totalAmountMinor, currency: operation.cycleSnapshot.pricingSnapshot.currency,
+    });
+    await deps.settlement.recordTerminalOutcome({ operationId: operation.operationId, eventKey: `${operation.identityKey}:provider-refusal`, operationFingerprint: operation.operationFingerprint, outcome: "refused", externalRef: externalAttemptRef, reason, occurredAt });
+    return automaticRenewalResult(operation, "refused", reason);
+}

package/dist/subscriptions/contracts/commands.d.ts

@@ -0,0 +1,115 @@
+export interface SubscriptionCommandContext {
+    actor: {
+        kind: "customer" | "operator";
+        actorId: string;
+        clientId: string;
+    };
+    subscriptionId: string;
+    idempotencyKey: string;
+    now: string;
+}
+export type SubscriptionCommand = SubscriptionCommandContext & ({
+    action: "pause";
+    pausePreset: string;
+    reason: string | null;
+    survey: string | null;
+    saveOffer: string | null;
+} | {
+    action: "resume" | "skip" | "cancel";
+    reason: string | null;
+    confirmedChargeTiming: boolean;
+} | {
+    action: "slide";
+    newNextCycleAt: string;
+    confirmedChargeTiming: boolean;
+} | {
+    action: "edit_future_terms";
+    shippingAddressId: string;
+    planDays: number;
+    cadenceDays: number;
+    expectedTemplateVersion: number;
+    acceptedQuoteHash: string;
+    confirmedChargeTiming: boolean;
+    coreLines: readonly SubscriptionBundleLine[];
+    addonLines: readonly SubscriptionBundleLine[];
+    compositionConstraint: string;
+});
+export interface SubscriptionBundleLine {
+    sku: string;
+    quantity: number;
+}
+export interface SubscriptionCommandReceipt {
+    actorId: string;
+    idempotencyKey: string;
+    commandFingerprint: string;
+    outcome: "applied" | "replayed" | "noop";
+    subscriptionId: string;
+    originalState: string;
+    nextCycleAt: string | null;
+    revision: string;
+    eventId: string | null;
+}
+export type SubscriptionUnsupportedCode = "multi_cycle_prepaid_unsupported" | "native_generic_bundle_commands_unsupported" | "native_command_bound_receipts_unsupported" | "native_prepared_attempt_store_unsupported";
+export interface SubscriptionUnsupported {
+    supported: false;
+    refusalCode: SubscriptionUnsupportedCode;
+}
+/** Readiness must be selected explicitly; a port declaration does not install a store. */
+export interface SubscriptionCapabilities {
+    graph: "managed" | "native";
+    multiCyclePrepaid: {
+        supported: false;
+        refusalCode: "multi_cycle_prepaid_unsupported";
+    };
+    genericBundleCommands: {
+        supported: true;
+    } | {
+        supported: false;
+        refusalCode: "native_generic_bundle_commands_unsupported";
+    };
+    commandBoundReceipts: {
+        supported: true;
+    } | {
+        supported: false;
+        refusalCode: "native_command_bound_receipts_unsupported";
+    };
+    preparedAttemptStore: {
+        supported: true;
+    } | {
+        supported: false;
+        refusalCode: "native_prepared_attempt_store_unsupported";
+    };
+    retryRecovery: "unavailable" | "selected";
+    stockRecovery: "unavailable" | "selected";
+    deliveryAdmission: "required";
+    executorCount: 1;
+    defaultEnabled: false;
+}
+export interface SubscriptionCommandPort {
+    readonly capabilities: SubscriptionCapabilities;
+    /** Future term writes, actor/command receipt and events must commit atomically. */
+    apply(command: SubscriptionCommand): Promise<SubscriptionCommandReceipt | SubscriptionUnsupported>;
+}
+export interface SubscriptionActivationPort {
+    activate(input: {
+        idempotencyKey: string;
+        orderId: string;
+        paymentIntentId: string;
+        paidEvidenceRef: string;
+        paidAt: string;
+        paymentMethodRef: string;
+        paymentMethodKind: string;
+        checkoutKind: string;
+    }): Promise<{
+        outcome: "noop" | "blocked";
+        reason: string;
+    } | {
+        outcome: "active";
+        subscriptionId: string;
+        orderId: string;
+        paymentIntentId: string;
+        nextCycleAt: string;
+        cadenceDays: number;
+        replayed: boolean;
+    }>;
+}

package/dist/subscriptions/contracts/commands.js

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