@openlup/core 0.0.0 → 0.7.0

package/dist/payment/providerAttemptIdempotency.d.ts

@@ -0,0 +1,23 @@
+/** @beta */
+export interface ProviderAttemptIdentityInput {
+    namespace: string;
+    provider: string;
+    localExecutionIdempotencyKey: string;
+    paymentIntentId: string;
+    amountMinor: number;
+    currency: string;
+    mode: "one_time" | "subscription_cycle";
+    orderRef: string;
+}
+/** @beta */
+export interface ProviderAttemptIdentity {
+    providerIdempotencyKey: string;
+    providerRequestFingerprint: string;
+}
+/** @beta */
+export declare function buildProviderAttemptIdentity(input: ProviderAttemptIdentityInput): ProviderAttemptIdentity;
+/** @beta */
+export declare function isProviderAttemptReplaySafe(input: {
+    existingFingerprint: string;
+    nextFingerprint: string;
+}): boolean;

package/dist/payment/providerAttemptIdempotency.js

@@ -0,0 +1,31 @@
+/** @beta */
+export function buildProviderAttemptIdentity(input) {
+    const normalizedNamespace = normalizeSegment(input.namespace);
+    const normalizedProvider = normalizeSegment(input.provider);
+    const normalizedLocalKey = normalizeSegment(input.localExecutionIdempotencyKey);
+    const normalizedCurrency = input.currency.trim().toUpperCase();
+    const providerIdempotencyKey = [
+        normalizedNamespace,
+        normalizedProvider,
+        input.paymentIntentId,
+        normalizedLocalKey,
+    ].join(":");
+    return {
+        providerIdempotencyKey,
+        providerRequestFingerprint: [
+            normalizedProvider,
+            input.paymentIntentId,
+            input.amountMinor.toString(),
+            normalizedCurrency,
+            input.mode,
+            input.orderRef,
+        ].join("|"),
+    };
+}
+/** @beta */
+export function isProviderAttemptReplaySafe(input) {
+    return input.existingFingerprint === input.nextFingerprint;
+}
+function normalizeSegment(value) {
+    return value.trim().toLowerCase().replace(/[^a-z0-9_.:-]+/g, "_");
+}

package/dist/payment/providerCapability.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Payment provider capability contracts.
+ *
+ * Renewal and dunning orchestration must decide what it can do with a stored
+ * consent by reading CAPABILITIES, never by comparing a provider identity
+ * string. This module is the neutral vocabulary those decisions are expressed
+ * in; the values live in each adapter, so nothing here names a provider.
+ *
+ * Every field exists because a live branch consumes it. Capabilities without a
+ * consumer (capture flows, status reads, limits) are deliberately absent and
+ * arrive with the code that needs them.
+ */
+/**
+ * Why a stored consent cannot back an unattended (off-session) charge.
+ *
+ * Neutral by construction: a provider-native refusal code never reaches a
+ * caller through this contract, so the orchestrator can route a blocked
+ * renewal into customer repair without learning provider vocabulary.
+ */
+export type UnattendedChargeBlockReason = "mandate_model_unsupported_for_unattended_charge";
+/**
+ * The stored consent evidence a capability judges, as read from local records
+ * rather than from a provider call. Optional everywhere: a provider whose
+ * consent carries no model simply ignores the field.
+ */
+export interface StoredMandateSnapshot {
+    /** Recurring/mandate model recorded when the payer gave consent. */
+    recurringModel?: string | null;
+}
+/** The verdict on whether a stored consent may be charged unattended. */
+export interface UnattendedMandateAssessment {
+    chargeable: boolean;
+    blockReason?: UnattendedChargeBlockReason;
+}
+/**
+ * What an unattended charge request must carry about the payer.
+ *
+ * Models the two payer-shaped branches on the renewal path: whether the
+ * request needs a payer block at all, and whether the customer reference may
+ * fall back to the stored contact email when no provider customer exists.
+ */
+export interface PayerContextRequirements {
+    requiresPayerBlock: boolean;
+    customerRefFallsBackToContactEmail: boolean;
+}
+/**
+ * What the stored-method health check must see before a charge is attempted.
+ *
+ * Models the per-provider preconditions the payment-method lifecycle applies
+ * to a stored method; the lifecycle keeps owning the reason vocabulary it
+ * reports, this contract owns only the expectations.
+ */
+export interface PaymentMethodHealthExpectations {
+    /** A provider-side customer reference is mandatory for a charge. */
+    requiresCustomerRef: boolean;
+    /** The stored method must be of exactly this kind, or null when any kind charges. */
+    requiredMethodKind: string | null;
+    /** A stored payer contact (email) is mandatory for a charge. */
+    requiresPayerContact: boolean;
+}
+/**
+ * How a customer-present client must drive one method-capture flow.
+ *
+ * Closed on purpose: a client can only offer a flow it knows how to drive, so a
+ * provider that invents a handoff no client implements must widen this union
+ * together with the surface that renders it, rather than have a repair page
+ * present a control that leads nowhere.
+ */
+export type PaymentMethodCaptureHandoff = "embedded_client_secret" | "payer_supplied_code";
+/**
+ * One way a payer can hand this provider a reusable payment consent while
+ * present at the keyboard — the repair path out of a failed unattended charge.
+ *
+ * `kind` is neutral vocabulary the renderer may label and key on; it is never a
+ * provider identity. A declared flow is an offer of capability, not a promise
+ * that any given client implements it: the client filters by `handoff`.
+ */
+export interface PaymentMethodCaptureFlow {
+    kind: string;
+    handoff: PaymentMethodCaptureHandoff;
+}
+/**
+ * Where a terminal outcome becomes visible on a rail, and how long the absence
+ * of one is still normal.
+ *
+ * Reconciliation cannot tell "still running" from "stuck" by polling alone: a
+ * rail that answers non-terminally forever looks identical to a healthy slow
+ * one. Declaring the shape makes silence measurable per rail instead of
+ * guessed at globally, and makes the question something a new adapter must
+ * answer up front rather than discover through an incident.
+ */
+export interface TerminalOutcomeReporting {
+    /**
+     * Where the outcome lands. Line comments on purpose: a member-level doc
+     * comment makes the extractor emit a trailing-whitespace alias line the diff
+     * guard refuses.
+     */
+    kind: "status_field" | "attempt_records" | "inbound_event";
+    /**
+     * Minutes of non-terminal answers after which this rail is behaving
+     * abnormally and the attempt deserves a human, not another poll. This is a
+     * suspicion threshold, never a verdict: elapsed time is not evidence about
+     * money, so nothing may terminalize a charge from this value alone.
+     */
+    silenceBecomesSuspectAfterMinutes: number;
+}
+/**
+ * One provider's unattended-charge capabilities, published by its adapter.
+ *
+ * `providerKind` is the registry key only. Consumers must read the capability
+ * fields; branching on this value re-creates the coupling the contract exists
+ * to remove.
+ */
+export interface PaymentProviderCapabilityDescriptor {
+    providerKind: string;
+    /**
+     * Every customer-present capture flow this provider can complete. Empty means
+     * a payer cannot repair this rail's consent without leaving the product.
+     */
+    captureFlows: readonly PaymentMethodCaptureFlow[];
+    /**
+     * The stored consent evidence must be loaded from local records before a
+     * charge is prepared. False means `assessMandate` decides without it, and the
+     * caller must not pay for the read.
+     */
+    requiresStoredMandateEvidence: boolean;
+    /** Judges stored consent evidence before any durable provider attempt is created. */
+    assessMandate(snapshot: StoredMandateSnapshot): UnattendedMandateAssessment;
+    /** The provider flow an unattended renewal charge must be dispatched under. */
+    unattendedChargeFlow: string;
+    payerContext: PayerContextRequirements;
+    methodHealth: PaymentMethodHealthExpectations;
+    /** How this rail reports a terminal outcome, and when its silence stops being normal. */
+    terminalOutcomeReporting: TerminalOutcomeReporting;
+    /**
+     * The stored consent belongs to one subscription rather than to the payer
+     * account, so persisting it from a webhook must use the subscription-scoped
+     * guarded write.
+     */
+    mandateUpsertIsSubscriptionScoped: boolean;
+}
+/** Lookup of published capabilities, keyed by provider kind. */
+export interface PaymentProviderCapabilityRegistry {
+    /** The descriptor published for this kind, or null when the kind is unknown. */
+    get(providerKind: string): PaymentProviderCapabilityDescriptor | null;
+    /** Every published kind, for inventory and conformance proofs. */
+    kinds(): readonly string[];
+}

package/dist/payment/providerCapability.js

@@ -0,0 +1,13 @@
+/**
+ * Payment provider capability contracts.
+ *
+ * Renewal and dunning orchestration must decide what it can do with a stored
+ * consent by reading CAPABILITIES, never by comparing a provider identity
+ * string. This module is the neutral vocabulary those decisions are expressed
+ * in; the values live in each adapter, so nothing here names a provider.
+ *
+ * Every field exists because a live branch consumes it. Capabilities without a
+ * consumer (capture flows, status reads, limits) are deliberately absent and
+ * arrive with the code that needs them.
+ */
+export {};

package/dist/platform-runtime/contracts.d.ts

@@ -0,0 +1,9 @@
+/** @beta */
+export type PlatformBundleId = string;
+/** Capability surfaces a runtime bundle can bind. */
+/** @beta */
+export type PlatformCapability = "http" | "scheduler" | "blob" | "data" | "migrations" | "analytics" | "transactional";
+/** @beta */
+export type PlatformBundleIdGuard<TId extends string = PlatformBundleId> = (value: unknown) => value is TId;
+/** @beta */
+export declare function createPlatformBundleIdGuard<const TIds extends readonly string[]>(ids: TIds): PlatformBundleIdGuard<TIds[number]>;

package/dist/platform-runtime/contracts.js

@@ -0,0 +1,13 @@
+// Platform-runtime shared contracts.
+// Provider-neutral types only: no I/O, no concrete host/provider presets. Host
+// composition and bundle catalogs stay downstream.
+/** @beta */
+export function createPlatformBundleIdGuard(ids) {
+    for (const id of ids) {
+        if (!id || id.trim() !== id) {
+            throw new Error("Platform bundle ids must be non-empty and trimmed");
+        }
+    }
+    const allowed = new Set(ids);
+    return (value) => typeof value === "string" && allowed.has(value);
+}

package/dist/platform-runtime/index.d.ts

@@ -0,0 +1,10 @@
+/** @beta */
+export { createPlatformBundleIdGuard, } from "./contracts.js";
+/** @beta */
+export type { PlatformBundleId, PlatformBundleIdGuard, PlatformCapability, } from "./contracts.js";
+/** @beta */
+export { createPlatformBundleRegistry, platformEnvSchema, } from "./platformKernel.js";
+/** @beta */
+export type { CreatePlatformBundleRegistryInput, PlatformBundleDescriptor, PlatformBundleRegistry, PlatformBundleReadiness, PlatformEnv, PlatformEnvInput, } from "./platformKernel.js";
+/** @beta */
+export type { AnalyticsPort, BlobStoragePort, DataGatewayPort, HttpRuntimePort, MigrationRunnerPort, PlatformHttpRequest, PlatformHttpResponse, SchedulerPort, TransactionalRuntimePort, } from "./ports.js";

package/dist/platform-runtime/index.js

@@ -0,0 +1,4 @@
+/** @beta */
+export { createPlatformBundleIdGuard, } from "./contracts.js";
+/** @beta */
+export { createPlatformBundleRegistry, platformEnvSchema, } from "./platformKernel.js";

package/dist/platform-runtime/platformKernel.d.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { type PlatformBundleId, type PlatformCapability } from "./contracts.js";
+/** @beta */
+export interface PlatformBundleReadiness {
+    ok: boolean;
+    error?: string;
+}
+/** @beta */
+export interface PlatformBundleDescriptor {
+    id: PlatformBundleId;
+    /** Declarative capability provider kind, bound by downstream composition. */
+    capabilities: Record<PlatformCapability, string>;
+    readReadiness(env: PlatformEnvInput): PlatformBundleReadiness;
+}
+/** @beta */
+export type PlatformEnvInput = Record<string, string | undefined>;
+/** @beta */
+export declare const platformEnvSchema: z.ZodObject<{
+    PLATFORM_BUNDLE: z.ZodOptional<z.ZodString>;
+    APP_BASE_URL: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** @beta */
+export type PlatformEnv = z.infer<typeof platformEnvSchema>;
+/** @beta */
+export interface PlatformBundleRegistry<TId extends string = PlatformBundleId> {
+    readonly defaultBundleId: TId;
+    readonly bundleIds: readonly TId[];
+    readonly descriptors: readonly PlatformBundleDescriptor[];
+    isBundleId(value: unknown): value is TId;
+    resolveBundleId(env: PlatformEnvInput): TId;
+    getBundleDescriptor(id: TId): PlatformBundleDescriptor;
+}
+/** @beta */
+export interface CreatePlatformBundleRegistryInput<TId extends string = PlatformBundleId> {
+    descriptors: readonly PlatformBundleDescriptor[];
+    defaultBundleId: TId;
+}
+/** @beta */
+export declare function createPlatformBundleRegistry<const TIds extends readonly string[]>(input: {
+    descriptors: readonly (PlatformBundleDescriptor & {
+        id: TIds[number];
+    })[];
+    defaultBundleId: TIds[number];
+}): PlatformBundleRegistry<TIds[number]>;

package/dist/platform-runtime/platformKernel.js

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import { createPlatformBundleIdGuard } from "./contracts.js";
+/** @beta */
+export const platformEnvSchema = z.object({
+    PLATFORM_BUNDLE: z.string().trim().min(1).optional(),
+    APP_BASE_URL: z.string().url().optional(),
+});
+/** @beta */
+export function createPlatformBundleRegistry(input) {
+    const bundleIds = input.descriptors.map((descriptor) => descriptor.id);
+    const isBundleId = createPlatformBundleIdGuard(bundleIds);
+    const descriptorsById = new Map();
+    for (const descriptor of input.descriptors) {
+        if (descriptorsById.has(descriptor.id)) {
+            throw new Error(`Duplicate platform bundle descriptor: ${descriptor.id}`);
+        }
+        descriptorsById.set(descriptor.id, descriptor);
+    }
+    if (!descriptorsById.has(input.defaultBundleId)) {
+        throw new Error(`Default platform bundle is not declared: ${input.defaultBundleId}`);
+    }
+    return {
+        defaultBundleId: input.defaultBundleId,
+        bundleIds,
+        descriptors: input.descriptors,
+        isBundleId,
+        resolveBundleId(env) {
+            const raw = env.PLATFORM_BUNDLE;
+            return isBundleId(raw) ? raw : input.defaultBundleId;
+        },
+        getBundleDescriptor(id) {
+            const descriptor = descriptorsById.get(id);
+            if (!descriptor) {
+                throw new Error(`Unknown platform bundle descriptor: ${id}`);
+            }
+            return descriptor;
+        },
+    };
+}

package/dist/platform-runtime/ports.d.ts

@@ -0,0 +1,100 @@
+/** Structural request shape for host HTTP adapters. */
+/** @beta */
+export interface PlatformHttpRequest {
+    url?: string;
+    method?: string;
+    headers: Record<string, string | string[] | undefined>;
+    query: Record<string, string | string[] | undefined>;
+    cookies?: Record<string, string>;
+    body?: unknown;
+}
+/** Structural response shape for host HTTP adapters. */
+/** @beta */
+export interface PlatformHttpResponse {
+    statusCode?: number;
+    headersSent?: boolean;
+    writableEnded?: boolean;
+    status(code: number): this;
+    setHeader?(name: string, value: string | number | readonly string[]): this;
+    json(body: unknown): this;
+    send(body: unknown): this;
+    end?(body?: unknown): this;
+    redirect(url: string): this;
+    redirect(status: number, url: string): this;
+}
+/** Host runtime: turn an incoming request into a handled response + mount a server. */
+/** @beta */
+export interface HttpRuntimePort {
+    /** Dispatch a single request through downstream routes. */
+    handle(req: PlatformHttpRequest, res: PlatformHttpResponse): Promise<unknown> | unknown;
+    /** Start listening. Serverless adapters may no-op. */
+    listen?(options: {
+        port: number;
+        host?: string;
+    }): Promise<void> | void;
+}
+/** Scheduled jobs: register cron-like work. */
+/** @beta */
+export interface SchedulerPort {
+    register(input: {
+        jobId: string;
+        schedule: string;
+        handler: () => Promise<void> | void;
+    }): void;
+    /** Verify a scheduler invocation is authentic. */
+    verifyInvocation(req: PlatformHttpRequest): boolean;
+}
+/** Object storage. */
+/** @beta */
+export interface BlobStoragePort {
+    upload(key: string, data: Uint8Array, options?: {
+        contentType?: string;
+    }): Promise<{
+        url: string;
+        pathname: string;
+    }>;
+    exists(key: string): Promise<boolean>;
+    delete(keyOrUrl: string): Promise<void>;
+    list(prefix?: string): Promise<{
+        keys: string[];
+    }>;
+    urlFor(key: string): string;
+}
+/** Persistence gateway: run reads/writes as a given actor. */
+/** @beta */
+export interface DataGatewayPort {
+    /** Execute a unit of work bound to an actor's claims. */
+    asActor<T>(claims: {
+        sub?: string;
+        role?: string;
+    } | null, work: (gateway: unknown) => Promise<T>): Promise<T>;
+    /** Service-role/elevated access. */
+    asService<T>(work: (gateway: unknown) => Promise<T>): Promise<T>;
+}
+/** Schema apply. */
+/** @beta */
+export interface MigrationRunnerPort {
+    status(): Promise<{
+        pending: string[];
+        applied: string[];
+    }>;
+    apply(options?: {
+        dryRun?: boolean;
+    }): Promise<{
+        applied: string[];
+    }>;
+}
+/** Frontend analytics. */
+/** @beta */
+export interface AnalyticsPort {
+    trackPageView(pathname: string): void;
+    trackEvent(name: string, properties?: Record<string, unknown>): void;
+}
+/** Transactional runtime for queue/function dispatch. */
+/** @beta */
+export interface TransactionalRuntimePort {
+    invoke(functionName: string, payload: unknown): Promise<{
+        ok: boolean;
+        status: number;
+    }>;
+}

package/dist/platform-runtime/ports.js

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

package/dist/pricing/index.d.ts

@@ -0,0 +1,8 @@
+/** @beta */
+export * from "./types.js";
+/** @beta */
+export * from "./ports.js";
+/** @beta */
+export * from "./pricingBreakdown.js";
+/** @beta */
+export * from "./targetPriceAllocation.js";

package/dist/pricing/index.js

@@ -0,0 +1,8 @@
+/** @beta */
+export * from "./types.js";
+/** @beta */
+export * from "./ports.js";
+/** @beta */
+export * from "./pricingBreakdown.js";
+/** @beta */
+export * from "./targetPriceAllocation.js";

package/dist/pricing/ports.d.ts

@@ -0,0 +1,22 @@
+import type { ResolvedPrice, ResolvePriceQuery } from "./types.js";
+/**
+ * Pricing resolver port - deterministic price resolution from a data-driven
+ * price-list / price-entry table.
+ *
+ * Caller computes eligible cart quantity for the line's pricing mode and
+ * passes it in alongside the line's own quantity. Implementations select the
+ * matching price entry for variant, mode, region, currency, and request time.
+ * Any fallback policy, including fallback to a generic mode, is owned by the
+ * adapter implementation; the port preserves the requested mode.
+ *
+ * Returns null when no entry matches; callers must surface a meaningful error
+ * rather than silently quote zero.
+ */
+/** @beta */
+export interface PricingResolverPort {
+    resolvePrice(query: ResolvePriceQuery): Promise<ResolvedPrice | null>;
+}
+/** @beta */
+export declare class PricingResolverNotConfiguredError extends Error {
+    constructor(query: ResolvePriceQuery);
+}

package/dist/pricing/ports.js

@@ -0,0 +1,7 @@
+/** @beta */
+export class PricingResolverNotConfiguredError extends Error {
+    constructor(query) {
+        super(`No price entry for ${query.variantId} (${query.mode}) in ${query.regionCode}/${query.currency}`);
+        this.name = "PricingResolverNotConfiguredError";
+    }
+}

package/dist/pricing/pricingBreakdown.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Pricing breakdown builder — pure functions that emit signed pricing components for
+ * a given (cart, resolved unit price) tuple. Sums always reconcile to the order /
+ * order_line totals via two persistence-ready invariants:
+ *
+ *   perLine:  sum(line_components.amount) = order_line.line_total_minor
+ *   perOrder: sum(all_components.amount)  = order.total_minor (including shipping)
+ *
+ * Current components: base_unit (always), mode_discount (when subscription resolves
+ * below the base unit price), qty_tier (when a quantity tier above 1 matched),
+ * bundle (line-scoped and negative, carrying the share of a composed bundle's
+ * target-price discount that the allocator assigned to this line), shipping
+ * (order-scoped, when a rule or non-zero amount applies), and promo (one negative
+ * order-scoped component per applied discount). loyalty remains a reserved
+ * component type for downstream engines.
+ */
+/** @beta */
+export declare const PRICING_COMPONENT_TYPES: readonly ["base_unit", "mode_discount", "qty_tier", "bundle", "promo", "loyalty", "shipping"];
+/** @beta */
+export type PricingComponentType = (typeof PRICING_COMPONENT_TYPES)[number];
+/** @beta */
+export interface PricingComponent {
+    sequence: number;
+    component_type: PricingComponentType;
+    amount_minor: number;
+    reason_code: string;
+    reason_payload: Record<string, unknown>;
+}
+/** @beta */
+export interface LinePricingInput {
+    variant_id: string;
+    line_qty: number;
+    base_unit_price_minor: number;
+    resolved_unit_price_minor: number;
+    matched_tier_min_qty: number;
+    mode_at_line: "one_time" | "subscription";
+    mode_resolved_via_fallback: boolean;
+    /**
+     * Positive amount-off this line carries because it is a component of a bundle sold
+     * at one target price — `discountAllocatedMinor` from the target-price allocator,
+     * already summed over the one or two lines a component may split into. Positive on
+     * the way in, exactly like an order discount; the emitted component carries it as a
+     * negative adjustment. Absent or zero emits nothing.
+     */
+    bundle_allocated_discount_minor?: number;
+}
+/** @beta */
+export interface OrderShippingInput {
+    amount_minor: number;
+    applied_rule_id: string | null;
+    carrier_kind: string | null;
+    vat_rate_bps: number | null;
+}
+/** @beta */
+export interface OrderDiscountInput {
+    promotionId: string;
+    amountOffMinor: number;
+    reasonCode: string;
+}
+/** @beta */
+export interface BuildOrderBreakdownInput {
+    lines: ReadonlyArray<LinePricingInput>;
+    shipping: OrderShippingInput;
+    discounts?: ReadonlyArray<OrderDiscountInput>;
+}
+/** @beta */
+export interface BuildOrderBreakdownResult {
+    lineBreakdowns: Array<{
+        variant_id: string;
+        line_total_minor: number;
+        components: PricingComponent[];
+    }>;
+    orderComponents: PricingComponent[];
+    orderTotalMinor: number;
+}
+/** @beta */
+export declare function buildLineBreakdown(input: LinePricingInput): PricingComponent[];
+/** @beta */
+export declare function buildOrderBreakdown(input: BuildOrderBreakdownInput): BuildOrderBreakdownResult;
+/**
+ * Cart-level invariant: every order's total_minor equals the sum of all components
+ * (line + order-level). Callers must assert this before persisting to commerce_orders
+ * to prevent a sale from going out with a hidden price-snapshot drift.
+ */
+/** @beta */
+export declare function assertBreakdownInvariant(result: BuildOrderBreakdownResult, orderTotalMinor: number): void;