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

package/dist/actions/attach-checkout-contact/action.d.ts

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

package/dist/actions/attach-checkout-contact/action.js

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

package/dist/actions/attach-checkout-contact/mock.d.ts

@@ -0,0 +1,15 @@
+import type { AttachCheckoutContact } from './types';
+/**
+ * Standalone mock of attaching contact to an online order.
+ *
+ * It mirrors the one REFUSAL the real command makes — a missing email — because
+ * that is the mistake a builder actually hits, and a mock that accepted anything
+ * would let a checkout screen look finished and lose receipts on the published
+ * site.
+ *
+ * It does NOT mirror "no order to attach to". The real command answers
+ * `attached: false` there rather than throwing, precisely so a flow can call it
+ * optimistically and still let the shopper pay; the mock always has a checkout
+ * to attach to, so it reports `true`.
+ */
+export declare const mockAttachCheckoutContact: AttachCheckoutContact;

package/dist/actions/attach-checkout-contact/mock.js

@@ -0,0 +1,22 @@
+/**
+ * Standalone mock of attaching contact to an online order.
+ *
+ * It mirrors the one REFUSAL the real command makes — a missing email — because
+ * that is the mistake a builder actually hits, and a mock that accepted anything
+ * would let a checkout screen look finished and lose receipts on the published
+ * site.
+ *
+ * It does NOT mirror "no order to attach to". The real command answers
+ * `attached: false` there rather than throwing, precisely so a flow can call it
+ * optimistically and still let the shopper pay; the mock always has a checkout
+ * to attach to, so it reports `true`.
+ */
+export const mockAttachCheckoutContact = async (params) => {
+    console.log('[Mock] attachCheckoutContact called', params);
+    if (!params)
+        throw new Error('Params required');
+    if (!params.email || !params.email.trim()) {
+        throw new Error('attachCheckoutContact: email is required — it is where the receipt goes');
+    }
+    return { attached: true, timestamp: new Date().toISOString() };
+};

package/dist/actions/attach-checkout-contact/types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 AttachCheckoutContactParams {
+    email: string;
+    name?: string;
+    phone?: string;
+    /** Defaults to the outlet the storefront booted against. */
+    outletId?: string;
+}
+export interface AttachCheckoutContactResponse {
+    /**
+     * `false` means there was nothing to attach to — no checkout had been started
+     * for this cart. It is NOT a failure to record the contact on an order that
+     * exists, and it never means the shopper was charged.
+     */
+    attached: boolean;
+    timestamp: string;
+}
+/**
+ * Put the shopper's contact on the order `startCheckout` already created.
+ *
+ * Call it BEFORE paying, whenever the email is known — on blur, on submit, or
+ * as the shopper leaves the contact step. It reuses the order's idempotency
+ * key, so it updates that order rather than creating a second one.
+ *
+ * SAFE TO CALL TWICE. The server only ever ADDS contact to an order that has
+ * none, so a later call cannot redirect a receipt that was already addressed.
+ *
+ * NEVER THROWS FOR A MISSING ORDER. Failing to record an email must not stop a
+ * payment the shopper is trying to make, so the caller gets `attached: false`
+ * and can carry on to pay.
+ */
+export type AttachCheckoutContact = (params: AttachCheckoutContactParams) => Promise<AttachCheckoutContactResponse>;

package/dist/actions/attach-checkout-contact/types.js

@@ -0,0 +1,16 @@
+// Attach Checkout Contact Types
+//
+// The second half of the online checkout. `startCheckout` creates the order and
+// mounts the payment fields the moment a shopper ARRIVES; this puts their email
+// on that same order once they have typed it.
+//
+// WHY THESE ARE TWO COMMANDS. The card fields cannot render without a payment
+// session, a session needs a server-priced amount, and an amount needs an order.
+// So the order has to exist before the shopper has typed anything. Demanding an
+// email first is what forced the old "fill the form, then see the card fields"
+// checkout — and it also meant every cart edit minted a NEW order, because the
+// idempotency key moved with the cart.
+//
+// Served ONLY by the storefront runtime (a published website), like
+// `startCheckout` itself. On a register it does not exist.
+export {};

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

@@ -2,7 +2,7 @@ import { StartCheckout } from './types';
 /**
  * Standalone mock of the storefront checkout.
  *
- * It mirrors the REFUSALS of the real command (empty cart, missing email,
+ * It mirrors the REFUSALS of the real command (empty cart,
  * 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.

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

@@ -2,7 +2,7 @@ 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,
+ * It mirrors the REFUSALS of the real command (empty cart,
  * 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.
@@ -17,9 +17,9 @@ 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');
-    }
+    // No email check: contact is optional now, because checkout starts on arrival.
+    // Refusing here would make "start on arrival" fail in PREVIEW while working on
+    // the published site, which is the worst way for this to be wrong.
     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');
     }

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

@@ -8,7 +8,16 @@ export interface StartCheckoutContact {
     phone?: string;
 }
 export interface StartCheckoutParams {
-    contact: StartCheckoutContact;
+    /**
+     * OPTIONAL, because checkout starts when the shopper ARRIVES rather than when
+     * they submit a form. The card fields cannot render without a payment session,
+     * a session needs a server-priced amount, and an amount needs an order — so the
+     * order has to exist before they have typed anything.
+     *
+     * Supply it afterwards with `attachCheckoutContact`, which re-sends the same
+     * idempotency key and so reaches the SAME order.
+     */
+    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

package/dist/index.d.ts

@@ -46,6 +46,7 @@ export declare const command: {
     readonly createPaymentLink: import(".").CreatePaymentLink;
     readonly chargeMoto: import(".").ChargeMoto;
     readonly startCheckout: import(".").StartCheckout;
+    readonly attachCheckoutContact: import(".").AttachCheckoutContact;
     readonly resumeCheckout: import(".").ResumeCheckout;
     readonly addCustomerNote: import(".").AddCustomerNote;
     readonly removeCustomerNote: import(".").RemoveCustomerNote;
@@ -185,6 +186,7 @@ export type { IntegrationPayment, IntegrationPaymentParams, IntegrationPaymentRe
 export type { CreatePaymentLink, CreatePaymentLinkParams, CreatePaymentLinkResponse, } from './actions/create-payment-link/types';
 export type { ChargeMoto, ChargeMotoParams, ChargeMotoResponse, ChargeMotoCardFields, } from './actions/charge-moto/types';
 export type { StartCheckout, StartCheckoutParams, StartCheckoutResponse, StartCheckoutContact, StartCheckoutOrder, } from './actions/start-checkout/types';
+export type { AttachCheckoutContact, AttachCheckoutContactParams, AttachCheckoutContactResponse, } from './actions/attach-checkout-contact/types';
 export type { ResumeCheckout, ResumeCheckoutParams, ResumeCheckoutResponse, ResumeCheckoutResult, } from './actions/resume-checkout/types';
 export type { AddCustomerNote, AddCustomerNoteParams, AddCustomerNoteResponse, } from './actions/add-customer-note/types';
 export type { RemoveCustomerNote, RemoveCustomerNoteParams, RemoveCustomerNoteResponse, } from './actions/remove-customer-note/types';

package/dist/index.js

@@ -46,6 +46,7 @@ import { integrationPayment } from './actions/integration-payment/action';
 import { createPaymentLink } from './actions/create-payment-link/action';
 import { chargeMoto } from './actions/charge-moto/action';
 import { startCheckout } from './actions/start-checkout/action';
+import { attachCheckoutContact } from './actions/attach-checkout-contact/action';
 import { resumeCheckout } from './actions/resume-checkout/action';
 // Customer Actions
 import { addCustomerNote } from './actions/add-customer-note/action';
@@ -187,6 +188,7 @@ export const command = {
     createPaymentLink,
     chargeMoto,
     startCheckout,
+    attachCheckoutContact,
     resumeCheckout,
     // Customer Actions
     addCustomerNote,

package/dist/projects/render/mocks.js

@@ -34,6 +34,7 @@ import { mockGetCashRoundingAmount } from '../../actions/get-cash-rounding-amoun
 import { mockCreatePaymentLink } from '../../actions/create-payment-link/mock';
 import { mockChargeMoto } from '../../actions/charge-moto/mock';
 import { mockStartCheckout } from '../../actions/start-checkout/mock';
+import { mockAttachCheckoutContact } from '../../actions/attach-checkout-contact/mock';
 import { mockResumeCheckout } from '../../actions/resume-checkout/mock';
 import { mockGetTimeClockStatus } from '../../actions/get-time-clock-status/mock';
 import { mockClearCart } from '../../actions/clear-cart/mock';
@@ -135,6 +136,7 @@ export const RENDER_MOCKS = {
     createPaymentLink: mockCreatePaymentLink,
     chargeMoto: mockChargeMoto,
     startCheckout: mockStartCheckout,
+    attachCheckoutContact: mockAttachCheckoutContact,
     resumeCheckout: mockResumeCheckout,
     clearCart: mockClearCart,
     deleteParkedOrder: mockDeleteParkedOrder,

package/dist/projects/render/types.d.ts

@@ -1,4 +1,4 @@
-import type { ExampleFunction, GetProducts, AddCustomSale, EditCustomSale, GetCustomers, AssignCustomer, AddCustomer, EditCustomer, GetCategories, GetOrders, GetRefunds, GetTaxTables, AddProductDiscount, AddProductToCart, RemoveProductFromCart, UpdateCartItemQuantity, AddCartDiscount, GetContext, GetFinalContext, AddProductNote, AddProductFee, GetProductModifierSelections, SetProductModifierSelections, SetActiveProductFee, SetActiveProductDiscount, GetActiveProduct, SetActiveProduct, AdjustInventory, AddOrderNote, AddCartFee, ClearCart, ParkOrder, ResumeParkedOrder, DeleteParkedOrder, VoidOrder, InitiateRefund, CashPayment, GetCashRoundingAmount, TapToPayPayment, TerminalPayment, ExtensionPayment, RedeemPayment, AddNonRevenueItem, AddCustomerNote, RemoveCustomerNote, RemoveCustomerFromCart, GoToStationHome, OpenCashDrawer, ShowNotification, ShowConfirmation, AuthenticateUser, PartialPayment, SwitchUser, SetRefundStockAction, SelectAllRefundItems, ResetRefundDetails, CalculateRefundTotal, GetRemainingRefundableQuantities, ProcessPartialRefund, RedeemRefund, GetRefundPlan, CheckPermission, GetCurrentCart, Print, SetActiveOrder, GetCustomTables, GetCustomTableData, UpsertCustomTableData, DeleteCustomTableData, GetCustomExtensions, GetCurrentCompanyCustomExtensions, GetCustomExtensionCustomTables, GetCustomTableFields, GetSecretsKeys, GetSecretVal, SetSecretVal, GetUsers, GetRoles, RemoveCartDiscount, GetActiveOrder, GetActiveCustomer, SetActiveCustomer, GetActiveOutlet, GetActiveStation, GetActiveSession, GetActiveUser, SetActiveUser, SetActiveRefund, RemoveProductDiscount, RemoveProductFee, RemoveProductNote, RemoveCartFee, RemoveOrderNote, RemoveCustomSale, RemoveNonRevenueItem, CanTransition, GetAvailableTransitions, ApplyTransition, IntegrationPayment, GetSmartGridLayout, SaveSmartGridLayout, SendEmail, SendSms, CreatePaymentLink, ChargeMoto, StartCheckout, ResumeCheckout, GetTimeClockStatus } from '../../index';
+import type { ExampleFunction, GetProducts, AddCustomSale, EditCustomSale, GetCustomers, AssignCustomer, AddCustomer, EditCustomer, GetCategories, GetOrders, GetRefunds, GetTaxTables, AddProductDiscount, AddProductToCart, RemoveProductFromCart, UpdateCartItemQuantity, AddCartDiscount, GetContext, GetFinalContext, AddProductNote, AddProductFee, GetProductModifierSelections, SetProductModifierSelections, SetActiveProductFee, SetActiveProductDiscount, GetActiveProduct, SetActiveProduct, AdjustInventory, AddOrderNote, AddCartFee, ClearCart, ParkOrder, ResumeParkedOrder, DeleteParkedOrder, VoidOrder, InitiateRefund, CashPayment, GetCashRoundingAmount, TapToPayPayment, TerminalPayment, ExtensionPayment, RedeemPayment, AddNonRevenueItem, AddCustomerNote, RemoveCustomerNote, RemoveCustomerFromCart, GoToStationHome, OpenCashDrawer, ShowNotification, ShowConfirmation, AuthenticateUser, PartialPayment, SwitchUser, SetRefundStockAction, SelectAllRefundItems, ResetRefundDetails, CalculateRefundTotal, GetRemainingRefundableQuantities, ProcessPartialRefund, RedeemRefund, GetRefundPlan, CheckPermission, GetCurrentCart, Print, SetActiveOrder, GetCustomTables, GetCustomTableData, UpsertCustomTableData, DeleteCustomTableData, GetCustomExtensions, GetCurrentCompanyCustomExtensions, GetCustomExtensionCustomTables, GetCustomTableFields, GetSecretsKeys, GetSecretVal, SetSecretVal, GetUsers, GetRoles, RemoveCartDiscount, GetActiveOrder, GetActiveCustomer, SetActiveCustomer, GetActiveOutlet, GetActiveStation, GetActiveSession, GetActiveUser, SetActiveUser, SetActiveRefund, RemoveProductDiscount, RemoveProductFee, RemoveProductNote, RemoveCartFee, RemoveOrderNote, RemoveCustomSale, RemoveNonRevenueItem, CanTransition, GetAvailableTransitions, ApplyTransition, IntegrationPayment, GetSmartGridLayout, SaveSmartGridLayout, SendEmail, SendSms, CreatePaymentLink, ChargeMoto, StartCheckout, AttachCheckoutContact, ResumeCheckout, GetTimeClockStatus } from '../../index';
 export interface RenderProviderActions {
     exampleFunction: ExampleFunction;
     getProducts: GetProducts;
@@ -51,6 +51,7 @@ export interface RenderProviderActions {
      * a register, because the two declare different things to the card networks.
      */
     startCheckout: StartCheckout;
+    attachCheckoutContact: AttachCheckoutContact;
     /**
      * The RETURN LEG of an online checkout, after a redirect payment method or
      * 3-D Secure sent the shopper away and back. Storefront-only, like

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@final-commerce/command-frame",
-  "version": "0.8.0-online.4",
+  "version": "0.8.0-online.5",
   "description": "Commands Frame library",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",