@openlup/core 0.0.0 → 0.7.0

package/dist/inventory/atp.js

@@ -0,0 +1,211 @@
+import { z } from "zod";
+/** @beta */
+export const INVENTORY_CONTRACT_VERSION = "inventory.v0";
+const uuidSchema = z.guid();
+const datetimeSchema = z.string().datetime({ offset: true });
+const quantitySchema = z.number().int().nonnegative();
+const positiveQuantitySchema = z.number().int().positive();
+/** @beta */
+export const inventoryLocationKindSchema = z.enum([
+    "internal_warehouse",
+    "third_party_logistics",
+    "supplier",
+    "quarantine",
+    "virtual",
+]);
+/** @beta */
+export const inventoryLocationStatusSchema = z.enum(["active", "inactive"]);
+/** @beta */
+export const inventoryLotStatusSchema = z.enum(["available", "quarantined", "expired", "recalled"]);
+/** @beta */
+export const inventoryAtpStatusSchema = z.enum(["fulfillable", "insufficient", "review_required", "unsupported"]);
+/** @beta */
+export const inventoryStockLineSchema = z.object({
+    skuId: uuidSchema,
+    sku: z.string().trim().min(1),
+    locationId: uuidSchema,
+    locationCode: z.string().trim().min(1),
+    locationKind: inventoryLocationKindSchema,
+    locationStatus: inventoryLocationStatusSchema,
+    fulfillable: z.boolean(),
+    lotId: uuidSchema.nullable(),
+    lotCode: z.string().trim().min(1).nullable(),
+    lotStatus: inventoryLotStatusSchema.nullable(),
+    expiresAt: datetimeSchema.nullable(),
+    onHand: quantitySchema,
+    reserved: quantitySchema,
+    unavailable: quantitySchema,
+    incoming: quantitySchema,
+    safetyStock: quantitySchema,
+}).strict();
+/** @beta */
+export const inventoryAtpRequestLineSchema = z.object({
+    skuId: uuidSchema,
+    sku: z.string().trim().min(1),
+    quantity: positiveQuantitySchema,
+}).strict();
+/** @beta */
+export const inventoryAtpRequestSchema = z.object({
+    contractVersion: z.literal(INVENTORY_CONTRACT_VERSION),
+    lines: z.array(inventoryAtpRequestLineSchema).min(1),
+    requestedAt: datetimeSchema,
+    orderMode: z.enum(["one_time", "subscription_cycle"]),
+    region: z.string().trim().min(2).max(32).optional(),
+    noSplitShipment: z.boolean().default(true),
+    minShelfLifeDays: z.number().int().min(0).max(730).default(0),
+}).strict();
+/** @beta */
+export const inventoryAllocationSchema = z.object({
+    skuId: uuidSchema,
+    sku: z.string().trim().min(1),
+    locationId: uuidSchema,
+    locationCode: z.string().trim().min(1),
+    lotId: uuidSchema.nullable(),
+    lotCode: z.string().trim().min(1).nullable(),
+    quantity: positiveQuantitySchema,
+    expiresAt: datetimeSchema.nullable(),
+}).strict();
+/** @beta */
+export const inventoryAtpLineResultSchema = z.object({
+    skuId: uuidSchema,
+    sku: z.string().trim().min(1),
+    requestedQuantity: positiveQuantitySchema,
+    availableQuantity: quantitySchema,
+    missingQuantity: quantitySchema,
+    status: inventoryAtpStatusSchema,
+    allocations: z.array(inventoryAllocationSchema),
+}).strict();
+/** @beta */
+export const inventoryAtpResultSchema = z.object({
+    contractVersion: inventoryAtpRequestSchema.shape.contractVersion,
+    status: inventoryAtpStatusSchema,
+    reason: z.string().trim().min(1).nullable(),
+    locationId: uuidSchema.nullable(),
+    locationCode: z.string().trim().min(1).nullable(),
+    lines: z.array(inventoryAtpLineResultSchema),
+}).strict();
+/** @beta */
+export function availableNow(line) {
+    return Math.max(0, line.onHand - line.reserved - line.unavailable - line.safetyStock);
+}
+/** @beta */
+export function calculateInventoryAtp(input) {
+    if (input.request.noSplitShipment === false) {
+        return inventoryAtpResultSchema.parse({
+            contractVersion: INVENTORY_CONTRACT_VERSION,
+            status: "unsupported",
+            reason: "split_shipment_unsupported",
+            locationId: null,
+            locationCode: null,
+            lines: input.request.lines.map((line) => ({
+                skuId: line.skuId,
+                sku: line.sku,
+                requestedQuantity: line.quantity,
+                availableQuantity: 0,
+                missingQuantity: line.quantity,
+                status: "unsupported",
+                allocations: [],
+            })),
+        });
+    }
+    const usableStock = input.stock.filter((line) => isUsable(line, input.request.requestedAt, input.request.minShelfLifeDays ?? 0));
+    const locationIds = [...new Set(usableStock.map((line) => line.locationId))];
+    const preferredLocation = locationIds
+        .map((locationId) => allocationForLocation(input.request, usableStock, locationId))
+        .find((candidate) => candidate.status === "fulfillable");
+    if (preferredLocation) {
+        return inventoryAtpResultSchema.parse({
+            contractVersion: INVENTORY_CONTRACT_VERSION,
+            status: "fulfillable",
+            reason: null,
+            locationId: preferredLocation.locationId,
+            locationCode: preferredLocation.locationCode,
+            lines: preferredLocation.lines,
+        });
+    }
+    const lines = input.request.lines.map((requestLine) => {
+        const matching = usableStock.filter((line) => line.skuId === requestLine.skuId);
+        const availableQuantity = matching.reduce((sum, line) => sum + availableNow(line), 0);
+        return {
+            skuId: requestLine.skuId,
+            sku: requestLine.sku,
+            requestedQuantity: requestLine.quantity,
+            availableQuantity,
+            missingQuantity: Math.max(0, requestLine.quantity - availableQuantity),
+            status: availableQuantity >= requestLine.quantity ? "review_required" : "insufficient",
+            allocations: [],
+        };
+    });
+    const hasEnoughInAggregate = lines.every((line) => line.missingQuantity === 0);
+    return inventoryAtpResultSchema.parse({
+        contractVersion: INVENTORY_CONTRACT_VERSION,
+        status: hasEnoughInAggregate ? "review_required" : "insufficient",
+        reason: hasEnoughInAggregate
+            ? "stock_available_only_with_split_shipment"
+            : "insufficient_available_stock",
+        locationId: null,
+        locationCode: null,
+        lines,
+    });
+}
+function allocationForLocation(request, stock, locationId) {
+    const locationStock = stock.filter((line) => line.locationId === locationId);
+    const locationCode = locationStock[0]?.locationCode ?? null;
+    const lines = request.lines.map((requestLine) => {
+        let remaining = requestLine.quantity;
+        const allocations = locationStock
+            .filter((line) => line.skuId === requestLine.skuId && availableNow(line) > 0)
+            .sort(fefoSort)
+            .flatMap((line) => {
+            if (remaining <= 0)
+                return [];
+            const quantity = Math.min(remaining, availableNow(line));
+            remaining -= quantity;
+            return [{
+                    skuId: requestLine.skuId,
+                    sku: requestLine.sku,
+                    locationId: line.locationId,
+                    locationCode: line.locationCode,
+                    lotId: line.lotId,
+                    lotCode: line.lotCode,
+                    quantity,
+                    expiresAt: line.expiresAt,
+                }];
+        });
+        return {
+            skuId: requestLine.skuId,
+            sku: requestLine.sku,
+            requestedQuantity: requestLine.quantity,
+            availableQuantity: requestLine.quantity - remaining,
+            missingQuantity: remaining,
+            status: remaining === 0 ? "fulfillable" : "insufficient",
+            allocations,
+        };
+    });
+    return {
+        status: lines.every((line) => line.status === "fulfillable") ? "fulfillable" : "insufficient",
+        locationId,
+        locationCode,
+        lines,
+    };
+}
+function isUsable(line, requestedAt, minShelfLifeDays) {
+    if (!line.fulfillable || line.locationStatus !== "active")
+        return false;
+    if (line.lotStatus && line.lotStatus !== "available")
+        return false;
+    if (line.expiresAt && Date.parse(line.expiresAt) <= minAcceptableExpiry(requestedAt, minShelfLifeDays)) {
+        return false;
+    }
+    return availableNow(line) > 0;
+}
+function minAcceptableExpiry(requestedAt, minShelfLifeDays) {
+    return Date.parse(requestedAt) + minShelfLifeDays * 24 * 60 * 60 * 1000;
+}
+function fefoSort(a, b) {
+    const aExpiry = a.expiresAt ? Date.parse(a.expiresAt) : Number.POSITIVE_INFINITY;
+    const bExpiry = b.expiresAt ? Date.parse(b.expiresAt) : Number.POSITIVE_INFINITY;
+    if (aExpiry !== bExpiry)
+        return aExpiry - bExpiry;
+    return a.locationCode.localeCompare(b.locationCode) || (a.lotCode ?? "").localeCompare(b.lotCode ?? "");
+}

package/dist/inventory/index.d.ts

@@ -0,0 +1,2 @@
+/** @beta */
+export * from "./atp.js";

package/dist/inventory/index.js

@@ -0,0 +1,2 @@
+/** @beta */
+export * from "./atp.js";

package/dist/marketing/research/contracts.d.ts

@@ -0,0 +1,75 @@
+import { z } from "zod";
+/** @beta */
+export type MarketingResearchJson = string | number | boolean | null | {
+    [key: string]: MarketingResearchJson | undefined;
+} | MarketingResearchJson[];
+/** @beta */
+export declare const marketingResearchJsonSchema: z.ZodCustom<MarketingResearchJson, MarketingResearchJson>;
+/** @beta */
+export declare const researchSurveyTypeSchema: z.ZodEnum<{
+    producer: "producer";
+    consumer: "consumer";
+}>;
+/** @beta */
+export declare const adminSurveyResponsesRequestSchema: z.ZodPipe<z.ZodObject<{
+    surveyType: z.ZodEnum<{
+        producer: "producer";
+        consumer: "consumer";
+    }>;
+    page: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    pageSize: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>, z.ZodTransform<{
+    pageSize: number;
+    surveyType: "producer" | "consumer";
+    page: number;
+}, {
+    surveyType: "producer" | "consumer";
+    page: number;
+    pageSize?: number | undefined;
+    limit?: number | undefined;
+}>>;
+/** @beta */
+export declare const adminSurveyResponseRowSchema: z.ZodObject<{
+    id: z.ZodString;
+    created_at: z.ZodString;
+    response_data: z.ZodCustom<MarketingResearchJson, MarketingResearchJson>;
+}, z.core.$strip>;
+/** @beta */
+export declare const adminSurveyResponsesResponseSchema: z.ZodObject<{
+    rows: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        created_at: z.ZodString;
+        response_data: z.ZodCustom<MarketingResearchJson, MarketingResearchJson>;
+    }, z.core.$strip>>;
+    totalCount: z.ZodNumber;
+    page: z.ZodNumber;
+    pageSize: z.ZodNumber;
+}, z.core.$strip>;
+/** @beta */
+export declare const researchSurveySubmitRequestSchema: z.ZodObject<{
+    surveyType: z.ZodEnum<{
+        producer: "producer";
+        consumer: "consumer";
+    }>;
+    responseData: z.ZodRecord<z.ZodString, z.ZodCustom<MarketingResearchJson, MarketingResearchJson>>;
+}, z.core.$strip>;
+/** @beta */
+export declare const researchSurveySubmitResponseSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    id: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+    email_skipped: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** @beta */
+export type ResearchSurveyType = z.infer<typeof researchSurveyTypeSchema>;
+/** @beta */
+export type AdminSurveyResponsesRequest = z.infer<typeof adminSurveyResponsesRequestSchema>;
+/** @beta */
+export type AdminSurveyResponseRow = z.infer<typeof adminSurveyResponseRowSchema>;
+/** @beta */
+export type AdminSurveyResponsesResponse = z.infer<typeof adminSurveyResponsesResponseSchema>;
+/** @beta */
+export type ResearchSurveySubmitRequest = z.infer<typeof researchSurveySubmitRequestSchema>;
+/** @beta */
+export type ResearchSurveySubmitResponse = z.infer<typeof researchSurveySubmitResponseSchema>;

package/dist/marketing/research/contracts.js

@@ -0,0 +1,60 @@
+import { z } from "zod";
+/** @beta */
+export const marketingResearchJsonSchema = z.custom(isMarketingResearchJson, { message: "Expected JSON value" });
+/** @beta */
+export const researchSurveyTypeSchema = z.enum(["producer", "consumer"]);
+/** @beta */
+export const adminSurveyResponsesRequestSchema = z
+    .object({
+    surveyType: researchSurveyTypeSchema,
+    page: z.coerce.number().int().nonnegative().default(0),
+    pageSize: z.coerce.number().int().min(1).max(100).optional(),
+    limit: z.coerce.number().int().min(1).max(500).optional(),
+})
+    .transform(({ limit, pageSize, ...request }) => ({
+    ...request,
+    pageSize: pageSize ?? Math.min(limit ?? 50, 100),
+}));
+/** @beta */
+export const adminSurveyResponseRowSchema = z.object({
+    id: z.string().min(1),
+    created_at: z.string().min(1),
+    response_data: marketingResearchJsonSchema,
+});
+/** @beta */
+export const adminSurveyResponsesResponseSchema = z.object({
+    rows: z.array(adminSurveyResponseRowSchema),
+    totalCount: z.number().int().nonnegative(),
+    page: z.number().int().nonnegative(),
+    pageSize: z.number().int().positive(),
+});
+/** @beta */
+export const researchSurveySubmitRequestSchema = z
+    .object({
+    surveyType: researchSurveyTypeSchema,
+    responseData: z.record(z.string(), marketingResearchJsonSchema),
+})
+    .refine((request) => Object.keys(request.responseData).length > 0, {
+    message: "responseData must not be empty",
+    path: ["responseData"],
+});
+/** @beta */
+export const researchSurveySubmitResponseSchema = z.object({
+    ok: z.boolean(),
+    id: z.string().min(1).optional(),
+    error: z.string().optional(),
+    email_skipped: z.string().optional(),
+});
+function isMarketingResearchJson(value) {
+    if (value === null)
+        return true;
+    if (typeof value === "string" || typeof value === "boolean")
+        return true;
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(isMarketingResearchJson);
+    if (typeof value !== "object")
+        return false;
+    return Object.values(value).every((entry) => entry === undefined || isMarketingResearchJson(entry));
+}

package/dist/marketing/research/index.d.ts

@@ -0,0 +1,4 @@
+/** @beta */
+export * from "./contracts.js";
+/** @beta */
+export * from "./ports.js";

package/dist/marketing/research/index.js

@@ -0,0 +1,4 @@
+/** @beta */
+export * from "./contracts.js";
+/** @beta */
+export * from "./ports.js";

package/dist/marketing/research/ports.d.ts

@@ -0,0 +1,15 @@
+import type { AdminSurveyResponsesRequest, AdminSurveyResponsesResponse, ResearchSurveySubmitRequest, ResearchSurveySubmitResponse } from "./contracts.js";
+/** @beta */
+export interface MarketingResearchSurveyResponsesReadPort {
+    getAdminSurveyResponses(request: AdminSurveyResponsesRequest): Promise<AdminSurveyResponsesResponse>;
+}
+/** @beta */
+export interface MarketingResearchSurveyRequestHeaders {
+    forEach(callbackfn: (value: string, key: string) => void): void;
+}
+/** @beta */
+export interface MarketingResearchSurveySubmitPort {
+    submitSurveyResponse(request: ResearchSurveySubmitRequest, context?: {
+        headers?: MarketingResearchSurveyRequestHeaders;
+    }): Promise<ResearchSurveySubmitResponse>;
+}

package/dist/marketing/research/ports.js

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

package/dist/partners/index.d.ts

@@ -0,0 +1,4 @@
+/** @beta */
+export * from "./status.js";
+/** @beta */
+export * from "./ports.js";

package/dist/partners/index.js

@@ -0,0 +1,4 @@
+/** @beta */
+export * from "./status.js";
+/** @beta */
+export * from "./ports.js";

package/dist/partners/ports.d.ts

@@ -0,0 +1,12 @@
+import type { PartnersB2BInquiryStatusUpdateRequest, PartnersB2BInquiryStatusUpdateResponse } from "./status.js";
+/**
+ * Persistence seam for advancing a B2B inquiry's pipeline status. The host
+ * application supplies the adapter (e.g. a DB-backed store, a CRM bridge); the
+ * core only owns this contract, not where inquiries are stored. Implementations
+ * should reject (throw) when the inquiry does not exist or the transition is
+ * not allowed, rather than resolving with a non-updated result.
+ */
+/** @beta */
+export interface PartnersB2BInquiryStatusUpdatePort {
+    updateB2BInquiryStatus(request: PartnersB2BInquiryStatusUpdateRequest): Promise<PartnersB2BInquiryStatusUpdateResponse>;
+}

package/dist/partners/ports.js

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

package/dist/partners/status.d.ts

@@ -0,0 +1,48 @@
+import { z } from "zod";
+/**
+ * Lifecycle stage of a B2B / partner inquiry as it moves through a sales
+ * pipeline. Neutral, provider-agnostic vocabulary:
+ * - `new` — just received, not yet triaged;
+ * - `contacted` — outreach made, awaiting response;
+ * - `qualified` — a real, in-scope opportunity;
+ * - `disqualified` — not a fit (out of scope / spam / no intent);
+ * - `closed_won` — converted;
+ * - `closed_lost` — did not convert.
+ * The inquiry payload itself (contact details, CRM ids, PII) is NOT part of the
+ * core contract; it lives in the host application's downstream adapter.
+ */
+/** @beta */
+export declare const partnersB2BInquiryStatusSchema: z.ZodEnum<{
+    new: "new";
+    contacted: "contacted";
+    qualified: "qualified";
+    disqualified: "disqualified";
+    closed_won: "closed_won";
+    closed_lost: "closed_lost";
+}>;
+/** Request to move one inquiry (`id`) to a new pipeline `status`. */
+/** @beta */
+export declare const partnersB2BInquiryStatusUpdateRequestSchema: z.ZodObject<{
+    id: z.ZodString;
+    status: z.ZodEnum<{
+        new: "new";
+        contacted: "contacted";
+        qualified: "qualified";
+        disqualified: "disqualified";
+        closed_won: "closed_won";
+        closed_lost: "closed_lost";
+    }>;
+}, z.core.$strip>;
+/** Successful status-update acknowledgement. `updated` is always `true`; a
+ * failed update is surfaced as a rejected promise / error by the port, not as
+ * `{ updated: false }`. */
+/** @beta */
+export declare const partnersB2BInquiryStatusUpdateResponseSchema: z.ZodObject<{
+    updated: z.ZodLiteral<true>;
+}, z.core.$strip>;
+/** @beta */
+export type PartnersB2BInquiryStatus = z.infer<typeof partnersB2BInquiryStatusSchema>;
+/** @beta */
+export type PartnersB2BInquiryStatusUpdateRequest = z.infer<typeof partnersB2BInquiryStatusUpdateRequestSchema>;
+/** @beta */
+export type PartnersB2BInquiryStatusUpdateResponse = z.infer<typeof partnersB2BInquiryStatusUpdateResponseSchema>;

package/dist/partners/status.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+/**
+ * Lifecycle stage of a B2B / partner inquiry as it moves through a sales
+ * pipeline. Neutral, provider-agnostic vocabulary:
+ * - `new` — just received, not yet triaged;
+ * - `contacted` — outreach made, awaiting response;
+ * - `qualified` — a real, in-scope opportunity;
+ * - `disqualified` — not a fit (out of scope / spam / no intent);
+ * - `closed_won` — converted;
+ * - `closed_lost` — did not convert.
+ * The inquiry payload itself (contact details, CRM ids, PII) is NOT part of the
+ * core contract; it lives in the host application's downstream adapter.
+ */
+/** @beta */
+export const partnersB2BInquiryStatusSchema = z.enum([
+    "new",
+    "contacted",
+    "qualified",
+    "disqualified",
+    "closed_won",
+    "closed_lost",
+]);
+/** Request to move one inquiry (`id`) to a new pipeline `status`. */
+/** @beta */
+export const partnersB2BInquiryStatusUpdateRequestSchema = z.object({
+    id: z.string().min(1),
+    status: partnersB2BInquiryStatusSchema,
+});
+/** Successful status-update acknowledgement. `updated` is always `true`; a
+ * failed update is surfaced as a rejected promise / error by the port, not as
+ * `{ updated: false }`. */
+/** @beta */
+export const partnersB2BInquiryStatusUpdateResponseSchema = z.object({
+    updated: z.literal(true),
+});

package/dist/payment/executionBaseContracts.d.ts

@@ -0,0 +1,81 @@
+import type { PaymentAttemptStatus } from "./paymentControlTypes.js";
+import type { PaymentFailureHint } from "./paymentFailureTaxonomyContracts.js";
+/** @beta */
+export declare const PAYMENT_EXECUTION_MODES: readonly ["one_time", "subscription_cycle"];
+/** @beta */
+export type PaymentExecutionMode = (typeof PAYMENT_EXECUTION_MODES)[number];
+/** @beta */
+export declare const PAYMENT_EXECUTION_ATTEMPT_STATUSES: readonly ["sent_to_provider", "requires_action", "processing"];
+/** @beta */
+export type PaymentExecutionAttemptStatus = Extract<PaymentAttemptStatus, (typeof PAYMENT_EXECUTION_ATTEMPT_STATUSES)[number]>;
+/** @beta */
+export interface PaymentExecutionBaseInput {
+    idempotencyKey: string;
+    providerIdempotencyKey: string;
+    providerRequestFingerprint: string;
+    paymentIntentId: string;
+    amountMinor: number;
+    currency: string;
+    mode: PaymentExecutionMode;
+}
+/**
+ * A provider that refused the attempt inside the execution call itself, rather
+ * than through a later callback.
+ *
+ * Execution adapters cannot express this as an attempt status: only the control
+ * plane performs terminal transitions, so {@link PaymentExecutionAttemptStatus}
+ * is deliberately non-terminal. The adapter therefore reports the refusal as a
+ * fact and lets the caller finalize the attempt.
+ *
+ * Reporting it matters because some providers offer no second chance to learn of
+ * the failure: where a provider's callback fires only for successful payments, a
+ * synchronous decline that is not surfaced here is never reported at all, and
+ * the attempt hangs until it expires.
+ */
+/** @beta */
+export interface PaymentExecutionProviderDecline {
+    /** Provider-native code, for correlation. Low-cardinality; never a free-form message. */
+    code: string;
+    /** True when the provider states the payer's bank cannot register a reusable mandate. */
+    mandateUnsupported: boolean;
+    /**
+     * The finer refusal reason the payer's bank returned, when the provider passes
+     * one through beside {@link code}. Optional because most providers report a
+     * single code; still a code, never a message.
+     */
+    declineCode?: string;
+    /**
+     * The provider's machine-readable recommendation for what a retry should do
+     * (for example: do not retry this instrument again). Optional and advisory —
+     * nothing in the decline path branches on it yet; it is carried so a later
+     * retry policy is not forced to re-query the provider for evidence that only
+     * existed at refusal time.
+     */
+    adviceCode?: string;
+    /**
+     * What the adapter is willing to ASSERT about this refusal, already translated
+     * out of its own code vocabulary into {@link PaymentFailureHint}.
+     *
+     * Carried on the decline so a classifier can read a refusal without learning
+     * which adapter produced it: the acquirer's codes stop at the adapter that
+     * owns them, and only the neutral reading crosses into the control plane.
+     * Absent when the adapter has no opinion, which classifies as `indeterminate`
+     * rather than as a guess.
+     */
+    neutralReasonHints?: readonly PaymentFailureHint[];
+}
+/** @beta */
+export interface PaymentExecutionBaseResult {
+    provider: string;
+    providerAttemptId: string | null;
+    providerSessionId: string | null;
+    attemptStatus: PaymentExecutionAttemptStatus;
+    nextActionKind: string | null;
+    /**
+     * Set when the provider refused synchronously. `null` for the normal path,
+     * where the outcome arrives later via callback or polling.
+     */
+    providerDecline?: PaymentExecutionProviderDecline | null;
+    requestPayload: Record<string, unknown>;
+    responsePayload: Record<string, unknown>;
+}

package/dist/payment/executionBaseContracts.js

@@ -0,0 +1,8 @@
+/** @beta */
+export const PAYMENT_EXECUTION_MODES = ["one_time", "subscription_cycle"];
+/** @beta */
+export const PAYMENT_EXECUTION_ATTEMPT_STATUSES = [
+    "sent_to_provider",
+    "requires_action",
+    "processing",
+];

package/dist/payment/index.d.ts

@@ -0,0 +1,36 @@
+/** @beta */
+export { LIVE_ATTEMPT_STATUSES, PAYMENT_ATTEMPT_STATUSES, PAYMENT_CONTROL_EVENT_TYPES, PAYMENT_INTENT_STATUSES, PAYMENT_TARGET_KINDS, RETRYABLE_ATTEMPT_STATUSES, isLiveAttemptStatus, isRetryableAttemptStatus, providerAckedButNeverConfirmed, } from "./paymentControlTypes.js";
+/** @beta */
+export { PAYMENT_EXECUTION_ATTEMPT_STATUSES, PAYMENT_EXECUTION_MODES, } from "./executionBaseContracts.js";
+/** @beta */
+export type { CanonicalPaymentControlEvent, PaymentAttemptAggregate, PaymentAttemptStatus, PaymentControlDecision, PaymentControlDecisionKind, PaymentControlEventType, PaymentControlFailureReason, PaymentControlResult, PaymentIntentAggregate, PaymentIntentStatus, PaymentTargetKind, } from "./paymentControlTypes.js";
+/** @beta */
+export type { PaymentExecutionAttemptStatus, PaymentExecutionBaseInput, PaymentExecutionBaseResult, PaymentExecutionProviderDecline, PaymentExecutionMode, } from "./executionBaseContracts.js";
+/** @beta */
+export { PAYMENT_FAILURE_CLASSES, PAYMENT_FAILURE_CUSTOMER_CAUSES, PAYMENT_FAILURE_HINTS, PAYMENT_RETRY_ADVICE_CODES, customerCauseForFailureClass, failureClassDecision, } from "./paymentFailureTaxonomyContracts.js";
+/** @beta */
+export type { PaymentFailureClass, PaymentFailureCustomerCause, PaymentFailureDecision, PaymentFailureEvidence, PaymentFailureHint, PaymentRetryAdviceCode, PaymentRetryProfile, } from "./paymentFailureTaxonomyContracts.js";
+/** @beta */
+export { PAYMENT_FAILURE_CLASSIFICATION_SOURCES, SCHEME_RETRY_ATTEMPT_CEILING, SCHEME_RETRY_WINDOW_DAYS, classifyPaymentFailure, isPaymentRetryAdviceCode, withinSchemeRetryCeiling, } from "./paymentFailureTaxonomy.js";
+/** @beta */
+export type { PaymentFailureClassification, PaymentFailureClassificationOptions, PaymentFailureClassificationSource, } from "./paymentFailureTaxonomy.js";
+/** @beta */
+export { applyProviderPaymentEvent, canTransitionPaymentAttempt, canTransitionPaymentIntent, transitionPaymentAttempt, transitionPaymentIntent, } from "./paymentStateMachine.js";
+/** @beta */
+export { buildProviderAttemptIdentity, isProviderAttemptReplaySafe, } from "./providerAttemptIdempotency.js";
+/** @beta */
+export type { ProviderAttemptIdentity, ProviderAttemptIdentityInput, } from "./providerAttemptIdempotency.js";
+/** @beta */
+export { PAYMENT_METHOD_LIFECYCLE_EVENT_KINDS, endsStoredMethodUsability, expiryInstantFromMonthYear, isPaymentMethodLifecycleEventKind, } from "./methodLifecycle.js";
+/** @beta */
+export type { PaymentMethodLifecycleEvent, PaymentMethodLifecycleEventKind, PaymentMethodReplacementFacts, } from "./methodLifecycle.js";
+/** @beta */
+export type { PayerContextRequirements, PaymentMethodCaptureFlow, PaymentMethodCaptureHandoff, PaymentMethodHealthExpectations, PaymentProviderCapabilityDescriptor, PaymentProviderCapabilityRegistry, StoredMandateSnapshot, UnattendedChargeBlockReason, UnattendedMandateAssessment, } from "./providerCapability.js";
+/** @beta */
+export { PAYMENT_RECOVERY_CAUSES, PAYMENT_RECOVERY_ACTIONS } from "./paymentRecoveryContracts.js";
+/** @beta */
+export type { PaymentRecoveryCause, PaymentRecoveryAction, PaymentRecoveryOperation, PaymentRecoveryMethod, PaymentRecoveryAdvice, PaymentRecoveryEvidence, PaymentRecoveryCandidate, PaymentRecoveryNormalizer, } from "./paymentRecoveryContracts.js";
+/** @beta */
+export { derivePaymentRecoveryGuidance, availablePaymentRecoveryActions } from "./paymentRecovery.js";
+/** @beta */
+export type { PaymentRecoveryAttempt, PaymentRecoveryGuidance } from "./paymentRecovery.js";

package/dist/payment/index.js

@@ -0,0 +1,18 @@
+/** @beta */
+export { LIVE_ATTEMPT_STATUSES, PAYMENT_ATTEMPT_STATUSES, PAYMENT_CONTROL_EVENT_TYPES, PAYMENT_INTENT_STATUSES, PAYMENT_TARGET_KINDS, RETRYABLE_ATTEMPT_STATUSES, isLiveAttemptStatus, isRetryableAttemptStatus, providerAckedButNeverConfirmed, } from "./paymentControlTypes.js";
+/** @beta */
+export { PAYMENT_EXECUTION_ATTEMPT_STATUSES, PAYMENT_EXECUTION_MODES, } from "./executionBaseContracts.js";
+/** @beta */
+export { PAYMENT_FAILURE_CLASSES, PAYMENT_FAILURE_CUSTOMER_CAUSES, PAYMENT_FAILURE_HINTS, PAYMENT_RETRY_ADVICE_CODES, customerCauseForFailureClass, failureClassDecision, } from "./paymentFailureTaxonomyContracts.js";
+/** @beta */
+export { PAYMENT_FAILURE_CLASSIFICATION_SOURCES, SCHEME_RETRY_ATTEMPT_CEILING, SCHEME_RETRY_WINDOW_DAYS, classifyPaymentFailure, isPaymentRetryAdviceCode, withinSchemeRetryCeiling, } from "./paymentFailureTaxonomy.js";
+/** @beta */
+export { applyProviderPaymentEvent, canTransitionPaymentAttempt, canTransitionPaymentIntent, transitionPaymentAttempt, transitionPaymentIntent, } from "./paymentStateMachine.js";
+/** @beta */
+export { buildProviderAttemptIdentity, isProviderAttemptReplaySafe, } from "./providerAttemptIdempotency.js";
+/** @beta */
+export { PAYMENT_METHOD_LIFECYCLE_EVENT_KINDS, endsStoredMethodUsability, expiryInstantFromMonthYear, isPaymentMethodLifecycleEventKind, } from "./methodLifecycle.js";
+/** @beta */
+export { PAYMENT_RECOVERY_CAUSES, PAYMENT_RECOVERY_ACTIONS } from "./paymentRecoveryContracts.js";
+/** @beta */
+export { derivePaymentRecoveryGuidance, availablePaymentRecoveryActions } from "./paymentRecovery.js";