@openlup/platform 0.22.0 → 0.23.0

package/dist/invoicing/contracts/store.d.ts

@@ -0,0 +1,267 @@
+import type { InvoiceHostPorts } from "./host.js";
+import type { InvoiceFacts } from "./facts.js";
+import type { InvoiceIdentity, InvoiceDocumentIdentity, InvoiceProof, InvoiceUnsupported, InvoiceWriteResult, InvoiceReadbackResult } from "./provider.js";
+import type { InvoiceClearanceObservation, InvoiceArtifactResult, InvoiceDeliveryPort } from "./delivery.js";
+type InvoiceDutyStatus = "owed" | "blocked" | "ready" | "processing" | "unknown" | "issued" | "voided" | "unsupported" | "faulted";
+/** Native duty/lease fields map to the pinned invoicing_* fixtures. Managed hosts
+ * translate their outboxId/attemptCount fences; never claim transaction equality.
+ */
+export interface InvoiceClaim {
+    readonly dutyId: string;
+    readonly documentId: string;
+    readonly requestId: string;
+    readonly token: string;
+    readonly generation: number;
+    readonly leaseUntil: string;
+    readonly identity: InvoiceIdentity;
+    readonly facts: InvoiceFacts;
+    readonly action: "create" | "readback";
+    readonly correction: {
+        readonly before: InvoiceFacts;
+        readonly reason: string;
+        readonly after: {
+            readonly totalNetMinor: 0;
+            readonly totalTaxMinor: 0;
+            readonly totalGrossMinor: 0;
+        };
+    } | null;
+}
+/** Exact camel-case shape returned by invoicing_duty_readback. This is not
+ * payment truth's accountingRequested; empty duties never assert invoice absence.
+ * @consumer Operator owed-duty readback.
+ */
+export interface InvoiceDutyReadback {
+    readonly orderId: string;
+    readonly captureFaults: readonly {
+        readonly sourceId: string;
+        readonly state: "retryable" | "faulted" | "resolved";
+        readonly attempts: number;
+        readonly availableAt: string;
+    }[];
+    readonly duties: readonly {
+        readonly dutyId: string;
+        readonly parentDutyId: string | null;
+        readonly documentId: string | null;
+        readonly state: "owed" | "blocked" | "claimed" | "unknown" | "issued" | "voided" | "unsupported" | "faulted";
+        readonly attempts: number;
+        readonly factAttempts: number;
+        readonly diagnosticCode: "faulted" | "missing_facts" | "legacy_facts_unproved" | "retryable" | "blocked" | "unsupported" | "unknown" | "absent" | null;
+        readonly createdAt: string;
+        readonly availableAt: string;
+        readonly leaseUntil: string | null;
+    }[];
+}
+/** Every operation is one local transaction; commit before external I/O. Native
+ * success atomically saves late identity and compensation; stale catch writes nothing.
+ * Managed and native stores are bound to the selected provider at construction.
+ * No implementation, executor or migration is installed by these declarations.
+ */
+export interface InvoiceStorePort {
+    /** Never call inside a renewal money, dunning or dispatch transaction without
+     * isolation: capture failure must not propagate; the sweep recovers.
+     */
+    captureDuty(input: {
+        readonly requestKey: string;
+        readonly sourceKind: "paid" | "handoff";
+        readonly sourceId: string;
+        readonly orderId: string;
+        readonly occurredAt: string;
+        readonly evidence: {
+            readonly settlementIntentId: string;
+            readonly amountMinor: number;
+            readonly currency: string;
+        } | {
+            readonly shipmentId: string;
+            readonly handedOverAt: string;
+        };
+    }): Promise<{
+        readonly dutyId: string;
+        readonly status: InvoiceDutyStatus;
+    } | InvoiceUnsupported>;
+    installFacts(input: {
+        readonly dutyId: string;
+        readonly facts: InvoiceFacts;
+    }): Promise<{
+        readonly dutyId: string;
+        readonly status: InvoiceDutyStatus;
+        readonly replayed?: boolean;
+    } | InvoiceUnsupported>;
+    /** Pinned split facts lease: sweep and prepare commit separately; finishing
+     * requires the same token and authoritative document/fact match. No host I/O
+     * under the duty lock, and unsupported never silently drops an owed duty.
+     */
+    sweep(limit: number): Promise<{
+        readonly collected: number;
+        readonly claims: readonly {
+            readonly dutyId: string;
+            readonly token: string;
+        }[];
+    } | InvoiceUnsupported>;
+    prepareFacts(input: {
+        readonly dutyId: string;
+        readonly token: string;
+    }): Promise<{
+        readonly status: "owed" | "ready" | "issued" | "voided" | "unsupported" | "stale";
+        readonly documentId?: string;
+        readonly requestId?: string;
+        readonly code?: "retryable" | "legacy_facts_unproved";
+    } | InvoiceUnsupported>;
+    finishFacts(input: {
+        readonly dutyId: string;
+        readonly token: string;
+        readonly result: Omit<Exclude<Awaited<ReturnType<InvoiceStorePort["prepareFacts"]>>, InvoiceUnsupported>, "status"> & {
+            readonly status: "owed" | "ready" | "issued" | "voided" | "unsupported";
+        };
+    }): Promise<{
+        readonly dutyId: string;
+        readonly status: "owed" | "ready" | "issued" | "voided" | "unsupported" | "faulted" | "stale";
+    } | InvoiceUnsupported>;
+    readDuties(orderId: string): Promise<InvoiceDutyReadback | InvoiceUnsupported>;
+    /** Filter order before locking/limit; never lease unrelated orders then filter.
+     * P8 reads the injected host seller before calling the first-claim SQL wrapper;
+     * its revisionRef supplies p_revision, without requiring a duty from the caller.
+     */
+    claim(input: {
+        readonly limit: number;
+        readonly visibilitySeconds: number;
+        readonly providerRef: string;
+        readonly orderId?: string | null;
+    }): Promise<readonly InvoiceClaim[] | InvoiceUnsupported>;
+    preflight(input: {
+        readonly claim: InvoiceClaim;
+        readonly amountMinor: number | null;
+        readonly currency: string | null;
+    } & ({
+        readonly status: "succeeded" | "failed" | "pending" | "unknown" | "unavailable";
+        readonly proof: InvoiceProof | null;
+    } | {
+        readonly status: "absent";
+        readonly evidence: Extract<Awaited<ReturnType<InvoiceHostPorts["money"]["read"]>>, {
+            kind: "absent";
+        }>["evidence"];
+    })): Promise<{
+        readonly kind: "ready" | "blocked" | "mismatch" | "unavailable" | "stale";
+    } | InvoiceUnsupported>;
+    finish(input: {
+        readonly claim: InvoiceClaim;
+        readonly result: Extract<InvoiceWriteResult, {
+            kind: "issued";
+        }> | Extract<InvoiceReadbackResult, {
+            kind: "found";
+        }>;
+    }): Promise<{
+        readonly kind: "issued";
+        readonly replayed: boolean;
+    } | {
+        readonly kind: "stale";
+    } | InvoiceUnsupported>;
+    /** Retryable requires a definite refusal (effectMayHaveSucceeded:false) or a
+     * pre-I/O failure and phase before_send. Every other failure maps to unknown.
+     * Native result kinds other than stale/voided map to recorded.
+     */
+    fail(input: {
+        readonly claim: InvoiceClaim;
+        readonly retrySeconds: number;
+    } & ({
+        readonly kind: "absent";
+        readonly evidence: Extract<InvoiceReadbackResult, {
+            kind: "absent";
+        }>;
+    } | {
+        readonly kind: "retryable";
+        readonly phase: "before_send";
+        readonly proof: InvoiceProof | null;
+    } | {
+        readonly kind: "blocked" | "unsupported" | "unknown";
+        readonly proof: InvoiceProof | null;
+    })): Promise<{
+        readonly kind: "recorded" | "voided" | "stale";
+    } | InvoiceUnsupported>;
+    /** Native post-write unsupported maps to unsupported_recorded, retaining duty/replay.
+     * Missing means no M09 duty, never invoice absence: retain/retry the reversal
+     * intent and route legacy documents to the incumbent path.
+     */
+    requestReversal(input: {
+        readonly requestKey: string;
+        readonly orderId: string;
+        readonly reason: "order_canceled" | "order_refunded";
+        readonly proof: InvoiceProof;
+    }): Promise<{
+        readonly kind: "missing" | "voided" | "pending_readback" | "correction_requested";
+        readonly dutyId?: string;
+        readonly replayed?: boolean;
+    } | {
+        readonly kind: "unsupported_recorded";
+        readonly dutyId?: string;
+        readonly replayed?: boolean;
+    } | InvoiceUnsupported>;
+    /** Existing local-only request remains distinct from fiscal issuance. */
+    requestLocalDocument(input: {
+        readonly requestKey: string;
+        readonly orderId: string;
+        readonly providerRef: string;
+    }): Promise<{
+        readonly kind: "requested";
+        readonly documentId: string;
+        readonly invoiceRef: string;
+        readonly status: string;
+        readonly replayed: boolean;
+    } | InvoiceUnsupported>;
+    listClearanceTargets(limit: number): Promise<readonly {
+        readonly documentId: string;
+        readonly identity: InvoiceDocumentIdentity;
+        readonly providerDocumentRef: string;
+        readonly providerDocumentNumber: string | null;
+        readonly state: InvoiceClearanceObservation["state"];
+    }[] | InvoiceUnsupported>;
+    /** Native maps clearance state unsupported to observation kind unsupported;
+     * provider_mismatch returns InvoiceUnsupported before recording anything.
+     */
+    recordObservation(input: {
+        readonly requestKey: string;
+        readonly documentId: string;
+        readonly eventRef: string;
+        readonly eventKind: "clearance" | "artifacts" | "unsupported" | "provider_mismatch";
+        readonly identity: InvoiceDocumentIdentity;
+        readonly providerDocumentRef: string;
+        readonly providerDocumentNumber: string | null;
+        readonly clearance: InvoiceClearanceObservation | null;
+        readonly artifacts: readonly Extract<InvoiceArtifactResult, {
+            kind: "found";
+        }>["artifact"][];
+        readonly observedAt: string;
+        readonly payloadHash: string;
+        readonly source: "provider_api" | "provider_webhook" | "manual_reconciliation";
+    }): Promise<{
+        readonly replayed: boolean;
+    } | InvoiceUnsupported>;
+    /** Verify M04 binding before claiming; document rows need no M09 issue duty. */
+    claimDeliveries(input: {
+        readonly limit: number;
+        readonly visibilitySeconds: number;
+        readonly requireClearance: boolean;
+        readonly orderId?: string | null;
+    }): Promise<readonly {
+        readonly token: string;
+        readonly generation: number;
+        readonly identity: InvoiceDocumentIdentity;
+        readonly providerDocumentRef: string;
+        readonly delivery: Omit<Parameters<InvoiceDeliveryPort["send"]>[0], "filename" | "content" | "contentType">;
+    }[] | InvoiceUnsupported>;
+    /** Native uncertain settlement passes p_receipt NULL and retains a non-null
+     * receiptRef hint in p_evidence; managed uses it as the provider message id.
+     * Managed failed_before_send uses retrySeconds for backoff; native ignores it.
+     */
+    settleDelivery(input: {
+        readonly deliveryRef: string;
+        readonly token: string;
+        readonly generation: number;
+        readonly providerDocumentRef: string;
+        readonly retrySeconds: number;
+        readonly result: Exclude<Awaited<ReturnType<InvoiceDeliveryPort["send"]>>, InvoiceUnsupported>;
+    }): Promise<{
+        readonly kind: "recorded" | "stale";
+        readonly replayed: boolean;
+    } | InvoiceUnsupported>;
+}
+export {};

package/dist/invoicing/contracts/store.js

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

package/dist/invoicing/index.d.ts

@@ -0,0 +1 @@
+export { readInvoiceCapabilities } from "./capabilities.js";

package/dist/invoicing/index.js

@@ -0,0 +1 @@
+export { readInvoiceCapabilities } from "./capabilities.js";

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 {};