@final-commerce/command-frame 0.11.1-preprod.1 → 0.11.1-preprod.3

package/dist/actions/get-checkout-status/types.d.ts

@@ -1,5 +1,7 @@
 /** The shopper-facing vocabulary: never the platform's payment / fulfilment states. */
 export type CheckoutOrderStatus = 'awaiting_payment' | 'confirming' | 'payment_failed' | 'paid' | 'fulfilled' | 'partially_refunded' | 'refunded' | 'cancelled';
+/** Why the server cancelled an order the shopper paid for. */
+export type CheckoutCancelReason = 'sold_out';
 export interface GetCheckoutStatusParams {
     /**
      * The receipt `startCheckout` returned, to name which order. Omitted: the checkout in flight,
@@ -13,6 +15,11 @@ export interface GetCheckoutStatusResponse {
     status: CheckoutOrderStatus | null;
     /** True once the money is in: `paid`, `fulfilled`, or refunded since. */
     paid: boolean;
+    /**
+     * Why a `cancelled` order was cancelled, when the server cancelled it. `sold_out`: the stock ran out
+     * before the payment was captured, so the payment was released and nothing was charged.
+     */
+    cancelReason?: CheckoutCancelReason;
     receiptId: string | null;
     timestamp: string;
 }

package/dist/actions/record-external-payment/mock.js

@@ -19,11 +19,16 @@ export const mockRecordExternalPayment = async (params) => {
     if (amount > balanceDue) {
         throw new Error(`recordExternalPayment: amount ${amount} exceeds the balance due ${balanceDue}`);
     }
+    const tip = params.tip?.amount ?? 0;
+    if (params.tip !== undefined && (!Number.isInteger(tip) || tip <= 0)) {
+        throw new Error('recordExternalPayment: tip.amount must be a positive integer (minor units)');
+    }
     const order = applyMockPayment(amount, 'external', label);
     const remainingBalance = MOCK_CART.remainingBalance ?? 0;
     return {
         success: true,
         amount,
+        tip,
         label,
         paymentType: 'external',
         change: 0,

package/dist/actions/record-external-payment/types.d.ts

@@ -1,4 +1,11 @@
 import { CFOrder } from '../../CommonTypes';
+/** A tip the customer already paid wherever the money was taken (the website, a delivery app). */
+export interface RecordExternalPaymentTip {
+    /** Tip in integer MINOR currency units. Must be positive. */
+    amount: number;
+    /** User id the tip belongs to. Defaults to the cashier recording the payment. */
+    tipTo?: string;
+}
 export interface RecordExternalPaymentParams {
     /**
      * What the payment was — shown on the order and in reports, e.g. 'Paid online',
@@ -12,13 +19,21 @@ export interface RecordExternalPaymentParams {
      * the rest can be taken with any other tender. Above the balance due is an error.
      */
     amount?: number;
+    /**
+     * Tip paid along with it. Recorded ON TOP of `amount` — it never counts toward the
+     * balance due — and stored on the payment like a card tip, so reports and tip-outs
+     * see it. Omit for no tip.
+     */
+    tip?: RecordExternalPaymentTip;
     /** Fulfillment state to land on after full payment, e.g. 'pending' to keep the order going to the kitchen. */
     checkoutFulfillmentTarget?: string;
 }
 export interface RecordExternalPaymentResponse {
     success: boolean;
-    /** The amount recorded, in integer MINOR currency units. */
+    /** The amount recorded against the balance, in integer MINOR currency units. Excludes the tip. */
     amount: number;
+    /** The tip recorded on top of `amount`, in integer MINOR currency units; 0 when none. */
+    tip: number;
     /** The label, as recorded. */
     label: string;
     paymentType: 'external';

package/dist/index.d.ts

@@ -223,7 +223,7 @@ export type { GetOrderStatuses, GetOrderStatusesResponse } from './actions/get-o
 export type { DeleteParkedOrder, DeleteParkedOrderParams, DeleteParkedOrderResponse, } from './actions/delete-parked-order/types';
 export type { VoidOrder, VoidOrderParams, VoidOrderResponse, VoidOrderOutcome } from './actions/void-order/types';
 export type { CashPayment, CashPaymentParams, CashPaymentResponse } from './actions/cash-payment/types';
-export type { RecordExternalPayment, RecordExternalPaymentParams, RecordExternalPaymentResponse, } from './actions/record-external-payment/types';
+export type { RecordExternalPayment, RecordExternalPaymentParams, RecordExternalPaymentResponse, RecordExternalPaymentTip, } from './actions/record-external-payment/types';
 export type { GetCashRoundingAmount, GetCashRoundingAmountParams, GetCashRoundingAmountResponse, } from './actions/get-cash-rounding-amount/types';
 export type { TapToPayPayment, TapToPayPaymentParams, TapToPayPaymentResponse, } from './actions/tap-to-pay-payment/types';
 export type { TerminalPayment, TerminalPaymentParams, TerminalPaymentResponse } from './actions/terminal-payment/types';
@@ -240,7 +240,7 @@ export type { GetShippingOptions, GetShippingOptionsResponse, ShippingOptionView
 export type { SelectShippingOption, SelectShippingOptionParams, SelectShippingOptionResponse, } from './actions/select-shipping-option/types';
 export type { SetOutlet, SetOutletParams, SetOutletResponse } from './actions/set-outlet/types';
 export type { ResumeCheckout, ResumeCheckoutParams, ResumeCheckoutResponse, ResumeCheckoutResult, } from './actions/resume-checkout/types';
-export type { GetCheckoutStatus, GetCheckoutStatusParams, GetCheckoutStatusResponse, CheckoutOrderStatus, } from './actions/get-checkout-status/types';
+export type { GetCheckoutStatus, GetCheckoutStatusParams, GetCheckoutStatusResponse, CheckoutOrderStatus, CheckoutCancelReason, } from './actions/get-checkout-status/types';
 export type { GetMotoConfig, GetMotoConfigResponse, MotoUnavailableReason } from './actions/get-moto-config/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/pubsub/topics/checkout/payment-failed/types.d.ts

@@ -1,4 +1,4 @@
-import type { TopicEvent } from "../../../types";
+import type { TopicEvent } from '../../../types';
 /**
  * Payload for payment-failed event
  *
@@ -9,7 +9,10 @@ import type { TopicEvent } from "../../../types";
 export interface PaymentFailedPayload {
     orderId: string;
     receiptId: string;
-    /** The provider's result code, e.g. `Refused`, or an error name. */
+    /**
+     * The provider's result code, e.g. `Refused`, or an error name. `SoldOut`: the shopper pressed Pay
+     * and something in the cart can no longer be sold, so the card was never sent.
+     */
     resultCode: string;
     /** Present when the failure carried a message worth showing. */
     message?: string;

package/package.json

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