@mj-biz-apps/orders-core-entities-server 5.1.0 → 5.2.0

package/dist/CheckoutSessionService.d.ts

@@ -0,0 +1,258 @@
+/**
+ * @fileoverview CheckoutSessionService
+ *
+ * Provides generic server-side orchestration for anonymous checkout sessions, widget token
+ * initialization, draft order graph composition with polymorphic product extensions,
+ * and payment completion handling.
+ *
+ * @module @mj-biz-apps/orders-core-entities-server/CheckoutSessionService
+ */
+import { UserInfo } from '@memberjunction/core';
+import { type CheckoutWidgetConfiguration } from '@mj-biz-apps/orders-entities';
+export interface InitSessionResult {
+    Success: boolean;
+    ErrorMessage?: string;
+    SessionID?: string;
+    ClientSessionKey?: string;
+    WidgetID?: string;
+    WidgetName?: string;
+    CompanyID?: string;
+    DistributionSlug?: string;
+    Configuration?: CheckoutWidgetConfiguration;
+    CustomCSS?: string | null;
+    CustomJS?: string | null;
+    ExpiresAt?: string;
+}
+export interface CheckoutAttendeeInput {
+    FirstName: string;
+    LastName: string;
+    Email: string;
+    Company?: string;
+    PersonID?: string;
+    DietaryPreferences?: string;
+    Comments?: string;
+}
+export type AttendeeInput = CheckoutAttendeeInput;
+export interface CheckoutLineExtensionData {
+    /** Target extension entity name (e.g. 'MJ_BizApps_Orders: Event Order Lines') */
+    EntityName?: string;
+    /** Key-value dictionary of extension fields */
+    Fields?: Record<string, unknown>;
+    /** For multi-unit items (e.g. 3 tickets), array of per-unit field dictionaries */
+    Units?: Array<Record<string, unknown>>;
+}
+export interface CheckoutLineInput {
+    ProductID: string;
+    Quantity: number;
+    /** Generic polymorphic extension payload */
+    ExtensionData?: CheckoutLineExtensionData;
+    /** Generic field dictionary directly on line input */
+    ExtensionFields?: Record<string, unknown>;
+    /** Per-unit field dictionaries */
+    Units?: Array<Record<string, unknown>>;
+    /** Legacy attendee input compatibility */
+    Attendees?: CheckoutAttendeeInput[];
+}
+export interface CheckoutLineSummary {
+    ID: string;
+    ProductID: string;
+    Quantity: number;
+    UnitPrice: number;
+    ExtendedPrice: number;
+    Description?: string;
+}
+export interface UpdateDraftResult {
+    Success: boolean;
+    ErrorMessage?: string;
+    SessionID: string;
+    OrderID?: string;
+    OrderNumber?: string;
+    Subtotal: number;
+    Tax: number;
+    Adjustments: number;
+    TotalGross: number;
+    RequiresPayment: boolean;
+    Lines: CheckoutLineSummary[];
+}
+/** Outcome of booking CapturePayment after a checkout order is already confirmed. */
+export interface BookCheckoutPaymentResult {
+    /** True when CapturePayment was invoked (or would have been, but a pre-check failed). */
+    Attempted: boolean;
+    /** True when the order is paid (already, or as a result of this call). */
+    Booked: boolean;
+    ErrorMessage?: string;
+    /**
+     * When Attempted && !Booked: a later attempt might succeed. Unclassified defaults
+     * true. The webhook 500s only when this is true (and the event is still inside
+     * the retry window).
+     */
+    Retryable?: boolean;
+}
+export interface CompleteCheckoutResult {
+    Success: boolean;
+    ErrorMessage?: string;
+    SessionID: string;
+    Status: string;
+    OrderID?: string;
+    OrderNumber?: string;
+    TotalGross?: number;
+    PaymentIntentID?: string;
+    ClientSecret?: string;
+    /**
+     * The IdentityClaim row id minted for the buyer's email (the actual verification token is
+     * only ever delivered in the claim email — it is never returned through the checkout path).
+     */
+    ClaimToken?: string;
+}
+export interface OpenSessionPaymentIntentResult {
+    Success: boolean;
+    ErrorMessage?: string;
+    SessionID: string;
+    PaymentIntentID?: string;
+    /** Returned to the caller for Stripe.js confirmation — never persisted. */
+    ClientSecret?: string;
+    Status?: string;
+    Amount?: number;
+}
+export declare class CheckoutSessionService {
+    /**
+     * Resolves a public distribution slug, validates widget status, and mints an active CheckoutSession.
+     */
+    static InitializeSession(slug: string, clientSessionKey: string, contextUser?: UserInfo): Promise<InitSessionResult>;
+    /**
+     * Strips obviously sensitive keys from a widget Configuration before it ships to an
+     * anonymous caller. `Configuration` is admin-authored JSON with an open index signature,
+     * so a future secret-shaped key (a webhook secret, an API credential, a server-side
+     * payment provider ref) must never ride along to the browser. `stripePublishableKey`
+     * is publishable by definition and survives.
+     */
+    /**
+     * Keys that may cross to an unauthenticated browser. Anything else in the
+     * admin-authored Configuration JSON stays on the server (allowlist, not denylist).
+     */
+    private static readonly PUBLIC_CONFIGURATION_KEYS;
+    private static sanitizeConfigurationForClient;
+    private static idsEqual;
+    /**
+     * Catalog this anonymous session is allowed to sell. Explicit `productId` /
+     * `allowedProductIds` / SKU-resolved id. An empty result is a misconfigured
+     * anonymous widget unless `allowAnyProduct` is set (open catalog still
+     * requires a company match).
+     */
+    private static resolveAllowedProductIds;
+    /** Marks expired-but-still-Open sessions Expired. Bounded; best-effort. */
+    static ReapExpiredOpenSessions(contextUser?: UserInfo, limit?: number): Promise<number>;
+    /**
+     * Verifies a caller-presented client session key against the session row's stored key.
+     * The session GUID alone must never be sufficient to drive a session — both values are
+     * required on every mutating call. Constant-time comparison over char codes (this package
+     * deliberately avoids Node globals, so no crypto.timingSafeEqual); a length mismatch is a
+     * plain refusal — it leaks only the length, which the caller already knows from their own key.
+     */
+    private static verifyClientSessionKey;
+    /**
+     * Enforces the session TTL on mutating calls (it was previously only enforced at
+     * session reuse). An expired-but-Open session is transitioned to 'Expired' (best-effort)
+     * and refused.
+     */
+    private static enforceSessionExpiry;
+    /**
+     * Discovers extension field definitions from metadata for the target product's extension entity.
+     */
+    /**
+     * ProductType.Configuration is the reusable presentation layer (customUI CSS/JS/theme,
+     * unitMode, quantity). Widget Configuration overlays it; widget wins on conflict.
+     */
+    private static mergeProductTypePresentation;
+    private static discoverExtensionFields;
+    /**
+     * Resolves — and optionally creates — a Person entity record based on provided fields.
+     * Lookup is by normalized email. Creation only happens when `createIfMissing` is true:
+     * draft updates resolve-only (so abandoned checkouts never mint Person rows), while
+     * completion creates the payer/attendee records it genuinely needs.
+     */
+    private static resolveOrEnsurePerson;
+    /**
+     * Creates an order line entity instance attached to the order's Lines collection.
+     */
+    private static createOrderLine;
+    /**
+     * Dynamically populates and coerces extension companion properties from a field map.
+     */
+    private static hydrateLineExtension;
+    /**
+     * Extracts unit field maps from an input line across all polymorphic formats.
+     */
+    private static extractUnitPayloads;
+    /**
+     * Builds and prices draft order lines in memory, persisting the checkout state to the
+     * CheckoutSession without creating premature draft rows in the OrderHeader database table.
+     */
+    static UpdateDraft(sessionID: string, clientSessionKey: string, email: string, lines: CheckoutLineInput[], contextUser?: UserInfo): Promise<UpdateDraftResult>;
+    /**
+     * Opens (or idempotently re-opens) a payment intent for a session's CURRENT server-priced
+     * total. This is the only way a checkout session acquires a `PaymentIntentID`.
+     *
+     * Everything money-shaped is resolved server-side, per the checkout pricing-input rule:
+     * the amount comes from the session's own priced snapshot (never the client), and the
+     * payment provider comes from the widget's admin-authored Configuration
+     * (`paymentProviderId`) — the client supplies only its session id + key. The gateway
+     * client secret is returned for Stripe.js confirmation and never persisted.
+     */
+    static OpenPaymentIntentForSession(sessionID: string, clientSessionKey: string, contextUser?: UserInfo): Promise<OpenSessionPaymentIntentResult>;
+    /**
+     * Completes an existing CheckoutSession, constructing the final Order,
+     * executing lifecycle confirmation (with accounting GL bookings and deferred revenue),
+     * and generating a claim token if unauthenticated.
+     */
+    static CompleteCheckout(sessionID: string, clientSessionKey: string, contextUser?: UserInfo): Promise<CompleteCheckoutResult>;
+    /**
+     * Verifies the paid-order gate for a session against a server-computed total. Returns a
+     * refusal message, or null when payment checks out. The intent must exist, belong to this
+     * session, be in a settled state, and cover the freshly re-priced total.
+     */
+    private static verifySessionPayment;
+    /**
+     * Gateway-side retry for a checkout whose order confirmed but CapturePayment did not book.
+     *
+     * `applyEvent` only stamps PaymentIntent status — it does not write a PaymentHeader (D19).
+     * Card checkout books via CapturePayment after Confirm. If that fails, two things retry
+     * the same idempotent CapturePayment (`checkout-complete:${session.ID}`):
+     *   1. POST /checkout/complete against a Confirmed session (client replay)
+     *   2. This method, from `payment_intent.succeeded` — including AlreadyApplied deliveries,
+     *      so a 500 after the intent row is stamped still converges on the next Stripe retry.
+     *
+     * No-ops when the intent is not a confirmed checkout session (back-office captures).
+     */
+    static BookSettledCheckoutPaymentIfNeeded(paymentIntentID: string, contextUser: UserInfo): Promise<BookCheckoutPaymentResult>;
+    /**
+     * After the order is committed, book `Orders.CapturePayment` against the session's
+     * settled PaymentIntent and stamp PaymentIntent.OrderHeaderID.
+     *
+     * Fail-soft and post-commit: a capture problem must not un-confirm the order.
+     * Retries are CompleteCheckout replay and `BookSettledCheckoutPaymentIfNeeded`
+     * from the payment_intent.succeeded webhook (including AlreadyApplied).
+     */
+    private static applySettledPaymentToOrder;
+    private static captureFailed;
+    /**
+     * Pull the gateway's current intent status onto our row. Fail-soft: a retrieve
+     * error leaves the local status unchanged and the paid gate still refuses.
+     */
+    private static refreshIntentFromGateway;
+    /**
+     * Atomically stamps a Processing session as Confirmed with its completed order id — the
+     * repair path when the entity-level save cannot run after the order has committed.
+     */
+    private static stampSessionConfirmedAtomic;
+    /**
+     * Executes atomic single-use Compare-And-Swap (CAS) state transition on CheckoutSession
+     * from 'Open' to 'Processing'. Returns true iff this execution successfully transitioned the record.
+     */
+    private static latchSessionProcessingAtomic;
+    /**
+     * Reverts atomic CAS state from 'Processing' back to 'Open' if order confirmation fails.
+     */
+    private static revertSessionOpenAtomic;
+}
+//# sourceMappingURL=CheckoutSessionService.d.ts.map

package/dist/CheckoutSessionService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CheckoutSessionService.d.ts","sourceRoot":"","sources":["../src/CheckoutSessionService.ts"],"names":[],"mappings":"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"}