@final-commerce/command-frame 0.8.0-online.4 → 0.8.0-preprod.1

package/dist/actions/resume-checkout/types.d.ts

@@ -1,59 +0,0 @@
-export interface ResumeCheckoutParams {
-    /**
-     * Where to read the provider's return data from. Defaults to the current
-     * page URL, which is where the shopper has just landed.
-     *
-     * Only override this if you moved the query string somewhere else before
-     * calling — for example if your router strips it on mount.
-     */
-    url?: string;
-}
-/**
- * What the return leg produced. Every field past `resumed` is absent when
- * `resumed` is `false`.
- */
-export interface ResumeCheckoutResult {
-    /**
-     * `false` means THIS WAS AN ORDINARY PAGE LOAD — no provider return data was
-     * in the URL, so there was nothing to finish and nothing happened. It is not
-     * an error, and it is the answer on every normal visit to the page. Call this
-     * unconditionally when your checkout or confirmation screen mounts and branch
-     * on this field.
-     */
-    resumed: boolean;
-    orderId?: string;
-    receiptId?: string;
-    /**
-     * The provider's result code for the completed attempt, e.g. `Authorised` or
-     * `Refused`. As everywhere else in this topic, `Authorised` is an
-     * authorisation and NOT a settlement.
-     */
-    resultCode?: string;
-    /** Opaque proof of the payment — see `PaymentCompletedPayload.sessionResult`. */
-    sessionResult?: string;
-    /**
-     * The one-time order password from the original checkout, recovered from
-     * browser storage. The page that held it in memory is gone, so this is the
-     * only way back to the order's status after a redirect.
-     */
-    orderPassword?: string;
-}
-export interface ResumeCheckoutResponse {
-    success: boolean;
-    timestamp: string;
-    checkout: ResumeCheckoutResult;
-}
-/**
- * Finish a checkout the shopper was redirected away from.
- *
- * SAFE TO CALL ON EVERY PAGE LOAD, and that is how it is meant to be used: on
- * an ordinary visit it finds no return data and answers `{ resumed: false }`
- * without touching the network. Calling it twice for one return is also safe —
- * the return data is consumed the first time.
- *
- * The outcome is ALSO published on the `checkout` topic (`payment-completed` or
- * `payment-failed`), exactly as it would have been had the shopper never left,
- * so a page that already subscribes needs no second code path. Subscribe first,
- * then call this, or the event fires before you are listening.
- */
-export type ResumeCheckout = (params?: ResumeCheckoutParams) => Promise<ResumeCheckoutResponse>;

package/dist/actions/resume-checkout/types.js

@@ -1,13 +0,0 @@
-// Resume Checkout Types
-//
-// The RETURN LEG of an online checkout. Some payment methods — and 3-D Secure
-// on a card — take the shopper away to their bank or wallet and send them back
-// to `returnUrl` on a FRESH PAGE LOAD. The payment is not finished at that
-// point: the provider hands the browser a one-time result in the URL, and it
-// has to be handed back to the provider to complete the charge.
-//
-// `startCheckout` cannot do this. It ran in the page that is now gone.
-//
-// Served ONLY by the storefront runtime (a published website), like
-// `startCheckout`. On a register it does not exist.
-export {};

package/dist/actions/start-checkout/action.d.ts

@@ -1,6 +0,0 @@
-/**
- * Start Checkout action
- * Calls the startCheckout action on the parent window
- */
-import type { StartCheckout } from './types';
-export declare const startCheckout: StartCheckout;

package/dist/actions/start-checkout/action.js

@@ -1,8 +0,0 @@
-/**
- * Start Checkout action
- * Calls the startCheckout action on the parent window
- */
-import { commandFrameClient } from '../../client';
-export const startCheckout = async (params) => {
-    return await commandFrameClient.call('startCheckout', params);
-};

package/dist/actions/start-checkout/mock.d.ts

@@ -1,16 +0,0 @@
-import { StartCheckout } from './types';
-/**
- * Standalone mock of the storefront checkout.
- *
- * It mirrors the REFUSALS of the real command (empty cart, missing email,
- * container not on the page) in the same order, because those are what a
- * builder actually hits first — a mock that accepted anything would let a
- * checkout screen look finished and fail on the published site.
- *
- * The mounted box is deliberately labelled as a mock. The real command mounts
- * the provider's hosted card fields (iframes owned by the payment provider);
- * nothing here takes a card number, and the placeholder must never look like
- * it does. Its button publishes `payment-completed` so a flow's subscriber —
- * the only way the outcome ever arrives — can be exercised in preview.
- */
-export declare const mockStartCheckout: StartCheckout;

package/dist/actions/start-checkout/mock.js

@@ -1,80 +0,0 @@
-import { MOCK_CART, MOCK_COMPANY, mockPublishEvent } from '../../demo/database';
-/**
- * Standalone mock of the storefront checkout.
- *
- * It mirrors the REFUSALS of the real command (empty cart, missing email,
- * container not on the page) in the same order, because those are what a
- * builder actually hits first — a mock that accepted anything would let a
- * checkout screen look finished and fail on the published site.
- *
- * The mounted box is deliberately labelled as a mock. The real command mounts
- * the provider's hosted card fields (iframes owned by the payment provider);
- * nothing here takes a card number, and the placeholder must never look like
- * it does. Its button publishes `payment-completed` so a flow's subscriber —
- * the only way the outcome ever arrives — can be exercised in preview.
- */
-export const mockStartCheckout = async (params) => {
-    console.log('[Mock] startCheckout called', params);
-    if (!params)
-        throw new Error('Params required');
-    if (!params.contact?.email || !params.contact.email.trim()) {
-        throw new Error('startCheckout: contact.email is required — it is where the receipt goes');
-    }
-    if (!params.container || typeof params.container !== 'string') {
-        throw new Error('startCheckout: container must be a CSS selector string (e.g. "#card-fields") — a DOM element cannot cross the command boundary');
-    }
-    const lineCount = (MOCK_CART.products?.length ?? 0) + (MOCK_CART.customSales?.length ?? 0);
-    if (!lineCount) {
-        throw new Error('startCheckout: cannot check out an empty cart');
-    }
-    // Resolved BEFORE the order is "created", exactly as the real command does:
-    // finding out the selector is wrong after an order exists would leave an
-    // unpaid order behind for a typo that cost nothing to catch first.
-    const container = typeof document === 'undefined' ? null : document.querySelector(params.container);
-    if (!container) {
-        throw new Error(`startCheckout: checkout container "${params.container}" was not found on the page`);
-    }
-    const serverTotal = Math.round(MOCK_CART.amountToBeCharged || MOCK_CART.total);
-    const currency = MOCK_COMPANY.settings?.currency ?? 'USD';
-    const suffix = String(Date.now()).slice(-6);
-    const order = {
-        orderId: `mock-order-${suffix}`,
-        receiptId: `ON-001-${suffix}`,
-        serverTotal,
-        currency,
-        paymentStatus: 'ready',
-        orderPassword: `mock-pw-${suffix}`,
-    };
-    mockPublishEvent('checkout', 'checkout-started', { ...order });
-    container.replaceChildren();
-    const box = document.createElement('div');
-    box.setAttribute('data-mock-checkout', 'true');
-    box.style.cssText =
-        'border:1px dashed #9aa;border-radius:8px;padding:16px;font:14px system-ui,sans-serif;text-align:center;color:#334';
-    const label = document.createElement('div');
-    label.textContent = 'Mock payment fields — the published site shows the real hosted card fields here.';
-    label.style.cssText = 'margin-bottom:12px;opacity:.75';
-    const button = document.createElement('button');
-    button.type = 'button';
-    button.textContent = `Simulate paying ${(serverTotal / 100).toFixed(2)} ${currency}`;
-    button.style.cssText =
-        'padding:10px 16px;border:0;border-radius:6px;background:#111;color:#fff;font-size:14px;cursor:pointer';
-    button.addEventListener('click', () => {
-        button.disabled = true;
-        // `Authorised` is what the real provider reports for a successful card
-        // entry. It is NOT settlement — see the checkout topic docs.
-        mockPublishEvent('checkout', 'payment-completed', {
-            orderId: order.orderId,
-            receiptId: order.receiptId,
-            resultCode: 'Authorised',
-        });
-    });
-    box.appendChild(label);
-    box.appendChild(button);
-    container.appendChild(box);
-    return {
-        success: true,
-        timestamp: new Date().toISOString(),
-        order,
-    };
-};

package/dist/actions/start-checkout/types.d.ts

@@ -1,81 +0,0 @@
-/**
- * Guest contact for the order. There is no shopper account, so this is the only
- * way to reach them — `email` is where the receipt goes and is required.
- */
-export interface StartCheckoutContact {
-    email: string;
-    name?: string;
-    phone?: string;
-}
-export interface StartCheckoutParams {
-    contact: StartCheckoutContact;
-    /**
-     * CSS SELECTOR for the element the payment fields mount into, e.g.
-     * `'#card-fields'`. The element must already be in the DOM when this is
-     * called.
-     *
-     * A SELECTOR, NOT AN ELEMENT — and this is not a style preference. Command
-     * params cross a `postMessage` boundary, which serializes them with the
-     * structured clone algorithm; a DOM node is not cloneable, so passing
-     * `ref.current` throws `DataCloneError: HTMLDivElement object could not be
-     * cloned` before the command is ever sent. The string is resolved on the
-     * runtime's side against the same document the page rendered.
-     */
-    container: string;
-    /**
-     * Where the provider returns the shopper after a redirect payment method
-     * (bank apps, wallets). Defaults to the current URL.
-     *
-     * Must be HTTPS and on the SAME ORIGIN the storefront token was minted for;
-     * the server rejects anything else, since this URL is handed to a payment
-     * provider and an open redirect on a checkout is a phishing primitive.
-     */
-    returnUrl?: string;
-    /**
-     * Overrides the cart-derived idempotency key. Leave unset: the default is
-     * derived from the cart, which is what makes a shopper's double-tap on "Pay"
-     * return the SAME order instead of creating a second, abandoned one.
-     */
-    idempotencyKey?: string;
-    /** Defaults to the outlet the storefront booted against. */
-    outletId?: string;
-    /** Forwarded verbatim to the provider's Drop-in (`showPayButton`, `locale`, field styling, …). */
-    dropinConfiguration?: Record<string, unknown>;
-}
-/**
- * The created order. Deliberately says nothing about money having moved — see
- * `paymentStatus` and the `checkout` topic.
- */
-export interface StartCheckoutOrder {
-    orderId: string;
-    receiptId: string;
-    /** The SERVER-computed total in integer minor units — the only total that matters. */
-    serverTotal: number;
-    currency: string;
-    /**
-     * `ready` — the payment fields are mounted and the shopper can pay.
-     * `unavailable` — THE ORDER EXISTS but no payment could be started, so the
-     * shopper has NOT been charged. Never report this as a failed order.
-     */
-    paymentStatus: 'ready' | 'unavailable';
-    /**
-     * One-time password for reading this order back, returned only on the first
-     * create. It is the ONLY route to this order's status — the guest token
-     * grants order creation and deliberately not order reads — so a caller that
-     * drops it cannot check whether the payment settled.
-     */
-    orderPassword?: string;
-}
-export interface StartCheckoutResponse {
-    success: boolean;
-    timestamp: string;
-    order: StartCheckoutOrder;
-}
-/**
- * Creates the server-priced order and mounts the provider's hosted card fields.
- *
- * RESOLVES WHEN THE SHOPPER *CAN* PAY, NOT WHEN THEY HAVE. The shopper has not
- * typed a card yet when this returns. The outcome arrives on the `checkout`
- * topic instead.
- */
-export type StartCheckout = (params: StartCheckoutParams) => Promise<StartCheckoutResponse>;

package/dist/actions/start-checkout/types.js

@@ -1,10 +0,0 @@
-// Start Checkout Types
-//
-// The ONLINE counterpart of the POS tenders: a shopper on a published website
-// pays for the current cart with their own card. Mirrors kaching's storefront
-// `startCheckout` input and result. All money is integer MINOR currency units.
-//
-// This command is served ONLY by the storefront runtime (a published website).
-// On a register it does not exist, exactly as the till tenders (`cashPayment`,
-// `terminalPayment`, `tapToPayPayment`, `chargeMoto`) do not exist online.
-export {};

package/dist/pubsub/topics/checkout/checkout-started/types.d.ts

@@ -1,26 +0,0 @@
-import type { TopicEvent } from "../../../types";
-/**
- * Payload for checkout-started event
- *
- * The order EXISTS and is unpaid. `serverTotal` is the server's own price for
- * the cart, in integer minor units — the browser never sends a price, so this
- * is the first and only authoritative total.
- */
-export interface CheckoutStartedPayload {
-    orderId: string;
-    receiptId: string;
-    serverTotal: number;
-    currency: string;
-    /**
-     * `ready` — the payment fields are mounted and the shopper can pay.
-     * `unavailable` — the order exists but no payment could be started, so the
-     * shopper has NOT been charged.
-     */
-    paymentStatus: "ready" | "unavailable";
-    /** One-time password for reading this order back. Returned only on the first create. */
-    orderPassword?: string;
-}
-/**
- * Typed event for checkout-started
- */
-export type CheckoutStartedEvent = TopicEvent<CheckoutStartedPayload>;

package/dist/pubsub/topics/checkout/index.d.ts

@@ -1,7 +0,0 @@
-/**
- * Checkout Topic Definition
- * Defines the checkout topic and its available event types
- */
-import type { TopicDefinition } from "../../types";
-export declare const checkoutTopic: TopicDefinition;
-export * from "./types";

package/dist/pubsub/topics/checkout/index.js

@@ -1,28 +0,0 @@
-/**
- * Checkout Topic Definition
- * Defines the checkout topic and its available event types
- */
-export const checkoutTopic = {
-    id: "checkout",
-    name: "Checkout",
-    description: "Topic for online (website) checkout events",
-    eventTypes: [
-        {
-            id: "checkout-started",
-            name: "Checkout Started",
-            description: "Published when the order has been created and the payment fields are mounted"
-        },
-        {
-            id: "payment-completed",
-            name: "Payment Completed",
-            description: "Published when the shopper's payment succeeds on their side (authorisation, not settlement)"
-        },
-        {
-            id: "payment-failed",
-            name: "Payment Failed",
-            description: "Published when a payment attempt is refused or errors; the shopper can retry"
-        }
-    ]
-};
-// Re-export types
-export * from "./types";

package/dist/pubsub/topics/checkout/payment-completed/types.d.ts

@@ -1,31 +0,0 @@
-import type { TopicEvent } from "../../../types";
-/**
- * Payload for payment-completed event
- *
- * THIS IS NOT SETTLEMENT. It reports that the SHOPPER'S side finished —
- * `resultCode` is the provider's own outcome, typically `Authorised`. The money
- * is confirmed by the provider's capture webhook reaching the backend, out of
- * band and after this page is done, so this event cannot and does not claim it.
- */
-export interface PaymentCompletedPayload {
-    orderId: string;
-    receiptId: string;
-    /** The provider's result code, e.g. `Authorised`. */
-    resultCode: string;
-    /**
-     * OPAQUE PROOF OF THIS PAYMENT, handed to the browser by the provider and to
-     * nobody else. Pass it to the order-status read and the server verifies it
-     * with the provider before believing a word of it.
-     *
-     * It is the only evidence of an outcome that exists outside the provider's
-     * webhook, so it is what recovers an order whose confirmation never arrived.
-     * Treat it as a credential: do not log it, do not put it in a URL you share.
-     *
-     * Absent when the provider reported no payment (see `resultCode`).
-     */
-    sessionResult?: string;
-}
-/**
- * Typed event for payment-completed
- */
-export type PaymentCompletedEvent = TopicEvent<PaymentCompletedPayload>;

package/dist/pubsub/topics/checkout/payment-failed/types.d.ts

@@ -1,20 +0,0 @@
-import type { TopicEvent } from "../../../types";
-/**
- * Payload for payment-failed event
- *
- * ONE DECLINED ATTEMPT, NOT A DEAD CHECKOUT. The order and the mounted payment
- * fields both survive, so the shopper can try another card without the page
- * starting a new checkout.
- */
-export interface PaymentFailedPayload {
-    orderId: string;
-    receiptId: string;
-    /** The provider's result code, e.g. `Refused`, or an error name. */
-    resultCode: string;
-    /** Present when the failure carried a message worth showing. */
-    message?: string;
-}
-/**
- * Typed event for payment-failed
- */
-export type PaymentFailedEvent = TopicEvent<PaymentFailedPayload>;

package/dist/pubsub/topics/checkout/types.d.ts

@@ -1,12 +0,0 @@
-/**
- * Checkout Topic Types
- * Aggregated types for all online-checkout events
- */
-export * from "./checkout-started/types";
-export * from "./payment-completed/types";
-export * from "./payment-failed/types";
-import type { CheckoutStartedPayload } from "./checkout-started/types";
-import type { PaymentCompletedPayload } from "./payment-completed/types";
-import type { PaymentFailedPayload } from "./payment-failed/types";
-export type CheckoutEventPayload = CheckoutStartedPayload | PaymentCompletedPayload | PaymentFailedPayload;
-export type CheckoutEventType = "checkout-started" | "payment-completed" | "payment-failed";

package/dist/pubsub/topics/checkout/types.js

@@ -1,8 +0,0 @@
-/**
- * Checkout Topic Types
- * Aggregated types for all online-checkout events
- */
-// Re-export all event types
-export * from "./checkout-started/types";
-export * from "./payment-completed/types";
-export * from "./payment-failed/types";