@final-commerce/command-frame 0.4.2-preprod.1 → 0.5.0-preprod.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. package/README.md +4 -55
  2. package/dist/CommonTypes.d.ts +1 -1
  3. package/dist/actions/add-product-fee/types.d.ts +1 -2
  4. package/dist/actions/adjust-inventory/mock.js +25 -21
  5. package/dist/actions/adjust-inventory/types.d.ts +1 -1
  6. package/dist/actions/authenticate-user/mock.js +4 -0
  7. package/dist/actions/authenticate-user/types.d.ts +13 -0
  8. package/dist/actions/calculate-refund-total/action.js +2 -2
  9. package/dist/actions/can-transition/types.d.ts +1 -1
  10. package/dist/actions/cash-payment/mock.js +6 -2
  11. package/dist/actions/cash-payment/types.d.ts +11 -7
  12. package/dist/actions/delete-parked-order/types.d.ts +0 -3
  13. package/dist/actions/extension-payment/mock.js +5 -1
  14. package/dist/actions/extension-payment/types.d.ts +10 -5
  15. package/dist/actions/get-custom-table-data/types.d.ts +2 -4
  16. package/dist/actions/get-final-context/mock.js +1 -1
  17. package/dist/actions/get-refund-plan/mock.d.ts +5 -0
  18. package/dist/actions/get-refund-plan/mock.js +24 -0
  19. package/dist/actions/get-refund-plan/types.d.ts +92 -0
  20. package/dist/actions/get-refund-plan/types.js +6 -0
  21. package/dist/actions/get-refunds/types.d.ts +1 -1
  22. package/dist/actions/get-remaining-refundable-quantities/action.js +2 -2
  23. package/dist/actions/get-remaining-refundable-quantities/mock.js +2 -0
  24. package/dist/actions/get-remaining-refundable-quantities/types.d.ts +13 -0
  25. package/dist/actions/initiate-refund/types.d.ts +6 -3
  26. package/dist/actions/integration-payment/types.d.ts +5 -5
  27. package/dist/actions/park-order/types.d.ts +0 -3
  28. package/dist/actions/partial-payment/types.d.ts +0 -5
  29. package/dist/actions/print/mock.js +2 -0
  30. package/dist/actions/print/types.d.ts +7 -0
  31. package/dist/actions/process-partial-refund/mock.d.ts +1 -1
  32. package/dist/actions/process-partial-refund/mock.js +14 -5
  33. package/dist/actions/process-partial-refund/types.d.ts +65 -8
  34. package/dist/actions/redeem-payment/types.d.ts +2 -2
  35. package/dist/actions/remove-product-fee/types.d.ts +10 -1
  36. package/dist/actions/resume-parked-order/types.d.ts +0 -3
  37. package/dist/actions/select-all-refund-items/action.js +2 -2
  38. package/dist/actions/set-active-refund/types.d.ts +1 -1
  39. package/dist/actions/set-refund-stock-action/types.d.ts +1 -1
  40. package/dist/actions/tap-to-pay-payment/mock.js +5 -1
  41. package/dist/actions/tap-to-pay-payment/types.d.ts +15 -7
  42. package/dist/actions/terminal-payment/mock.js +5 -1
  43. package/dist/actions/terminal-payment/types.d.ts +11 -6
  44. package/dist/actions/upsert-custom-table-data/types.d.ts +11 -1
  45. package/dist/actions/void-order/types.d.ts +4 -6
  46. package/dist/index.d.ts +2 -10
  47. package/dist/index.js +0 -6
  48. package/dist/projects/render/mocks.js +0 -6
  49. package/dist/projects/render/types.d.ts +1 -6
  50. package/package.json +1 -1
  51. package/dist/actions/open-extension-overlay/action.d.ts +0 -2
  52. package/dist/actions/open-extension-overlay/action.js +0 -4
  53. package/dist/actions/open-extension-overlay/mock.d.ts +0 -2
  54. package/dist/actions/open-extension-overlay/mock.js +0 -1
  55. package/dist/actions/open-extension-overlay/types.d.ts +0 -9
  56. package/dist/actions/open-extension-overlay/types.js +0 -1
  57. package/dist/actions/resolve-extension-overlay/action.d.ts +0 -2
  58. package/dist/actions/resolve-extension-overlay/action.js +0 -4
  59. package/dist/actions/resolve-extension-overlay/mock.d.ts +0 -2
  60. package/dist/actions/resolve-extension-overlay/mock.js +0 -1
  61. package/dist/actions/resolve-extension-overlay/types.d.ts +0 -9
  62. package/dist/actions/resolve-extension-overlay/types.js +0 -1
  63. package/dist/actions/vendara-payment/action.d.ts +0 -6
  64. package/dist/actions/vendara-payment/action.js +0 -8
  65. package/dist/actions/vendara-payment/mock.d.ts +0 -2
  66. package/dist/actions/vendara-payment/mock.js +0 -11
  67. package/dist/actions/vendara-payment/types.d.ts +0 -26
  68. package/dist/actions/vendara-payment/types.js +0 -1
  69. package/dist/hooks/index.d.ts +0 -17
  70. package/dist/hooks/index.js +0 -39
  71. package/dist/hooks/types.d.ts +0 -15
  72. package/dist/hooks/types.js +0 -1
  73. package/dist/interceptors/index.d.ts +0 -21
  74. package/dist/interceptors/index.js +0 -53
  75. package/dist/interceptors/types.d.ts +0 -26
  76. package/dist/interceptors/types.js +0 -1
@@ -2,7 +2,7 @@ import type { ExtensionPaymentResponse } from "../extension-payment/types";
2
2
  /**
3
3
  * Card display fields for an integration payment.
4
4
  *
5
- * Render JSON-serializes this object onto the order's `paymentMethod.emv` field;
5
+ * kaching JSON-serializes this object onto the order's `paymentMethod.emv` field;
6
6
  * the transactions list, split-payment refund modal, and receipt mapper parse it
7
7
  * back. Field names are translated to the platform's canonical EMV keys ("Brand",
8
8
  * "Cardholder Name", "Card Number", etc.) on the host before serialization — your
@@ -24,13 +24,13 @@ export interface IntegrationEmvData {
24
24
  expiryDate?: string;
25
25
  /** Issuer / bank name. → "Issuer" */
26
26
  issuer?: string;
27
- /** Last 4 digits of the card. Render masks to "**** **** **** XXXX" before display. → "Card Number" */
27
+ /** Last 4 digits of the card. kaching masks to "**** **** **** XXXX" before display. → "Card Number" */
28
28
  cardNumberLast4?: string;
29
29
  }
30
30
  /**
31
31
  * Integration payment (e.g. Stripe-like) — always uses paymentType `"integration"` on the wire.
32
32
  * The extension processes the payment with its own provider, then reports the result here so
33
- * Render can record the transaction + order.
33
+ * kaching can record the transaction + order.
34
34
  *
35
35
  * Required fields (compile-time enforced by TS, runtime-enforced by the host handler):
36
36
  * - `amount` — integer MINOR currency units of the captured amount (e.g. 1575 = $15.75)
@@ -51,8 +51,8 @@ export interface IntegrationPaymentParams {
51
51
  metadata?: Record<string, unknown>;
52
52
  /** Provider fee in integer MINOR currency units — stored on paymentMethod.processorFee. */
53
53
  processorFee?: number;
54
- /** Override the fulfillment landing on full payment. Omitted: preserve advanced fulfillment, auto-fulfill from draft/pending/on_hold. */
55
- targetFulfillmentState?: string;
54
+ /** Override the fulfillment state the order lands in on full payment (validated against the fulfillment state machine; invalid values throw). Omitted: preserve advanced fulfillment, auto-fulfill from draft/pending/on_hold. */
55
+ checkoutFulfillmentTarget?: string;
56
56
  }
57
57
  export type IntegrationPaymentResponse = ExtensionPaymentResponse;
58
58
  export type IntegrationPayment = (params: IntegrationPaymentParams) => Promise<IntegrationPaymentResponse>;
@@ -1,10 +1,7 @@
1
1
  import { CFOrder } from "../../CommonTypes";
2
- import type { CFTransitionResult } from "../../common-types/order-state";
3
2
  export interface ParkOrderResponse {
4
3
  success: boolean;
5
4
  order: CFOrder;
6
5
  timestamp: string;
7
- /** Present when the state machine blocked or forced the transition. */
8
- transitionResult?: CFTransitionResult;
9
6
  }
10
7
  export type ParkOrder = () => Promise<ParkOrderResponse>;
@@ -1,5 +1,4 @@
1
1
  import { CFOrder } from "../../CommonTypes";
2
- import type { CFTransitionResult } from "../../common-types/order-state";
3
2
  export interface PartialPaymentParams {
4
3
  /** The payment amount in integer MINOR currency units (required if openUI is false). If isPercent is true, this is a percentage (0-100) instead. */
5
4
  amount?: number;
@@ -7,8 +6,6 @@ export interface PartialPaymentParams {
7
6
  isPercent?: boolean;
8
7
  /** If true, opens the split payment UI. */
9
8
  openUI?: boolean;
10
- /** Override the fulfillment landing on full payment. Omitted: preserve advanced fulfillment, auto-fulfill from draft/pending/on_hold. */
11
- targetFulfillmentState?: string;
12
9
  }
13
10
  export interface PartialPaymentResponse {
14
11
  success: boolean;
@@ -17,7 +14,5 @@ export interface PartialPaymentResponse {
17
14
  openUI: boolean;
18
15
  order: CFOrder | null;
19
16
  timestamp: string;
20
- /** Present when the state machine blocked or forced the transition. */
21
- transitionResult?: CFTransitionResult;
22
17
  }
23
18
  export type PartialPayment = (params?: PartialPaymentParams) => Promise<PartialPaymentResponse>;
@@ -9,9 +9,11 @@ export const mockPrint = (params) => {
9
9
  console.log("[Mock] Would print image:", params.data.image?.substring(0, 50) + "...");
10
10
  break;
11
11
  case "html":
12
+ console.warn("[Mock] print type 'html' is DEPRECATED — rasterize and use type: 'image'.");
12
13
  console.log("[Mock] Would print HTML:", params.data.html?.substring(0, 100) + "...");
13
14
  break;
14
15
  case "receipt":
16
+ console.warn("[Mock] print type 'receipt' is DEPRECATED — rasterize and use type: 'image'.");
15
17
  console.log("[Mock] Would print receipt for order:", params.data.order);
16
18
  break;
17
19
  }
@@ -7,12 +7,18 @@ export type PrintParams = {
7
7
  };
8
8
  options?: PrintOptions;
9
9
  } | {
10
+ /** @deprecated Rasterize your HTML and use `type: "image"`. The native path posts raw HTML to the shell (no html2canvas/sanitization) and PrintOptions may be dropped. */
10
11
  type: "html";
11
12
  data: {
12
13
  html: string;
13
14
  };
14
15
  options?: PrintOptions;
15
16
  } | {
17
+ /**
18
+ * @deprecated Compose + rasterize your receipt and use `type: "image"`.
19
+ * The station requires `order` (no active-order fallback), ignores
20
+ * `globalBlockId`, and drops ALL PrintOptions (including tag routing).
21
+ */
16
22
  type: "receipt";
17
23
  data: {
18
24
  order?: Omit<CFActiveOrder, "_id">;
@@ -27,6 +33,7 @@ export interface PrintOptions {
27
33
  bottom?: number;
28
34
  left?: number;
29
35
  };
36
+ /** @deprecated Not consumed by the runtime — paper size comes from the station's per-printer settings. */
30
37
  paperSize?: string;
31
38
  width?: string;
32
39
  /**
@@ -1,2 +1,2 @@
1
- import { ProcessPartialRefund } from "./types";
1
+ import { ProcessPartialRefund } from './types';
2
2
  export declare const mockProcessPartialRefund: ProcessPartialRefund;
@@ -1,16 +1,25 @@
1
1
  export const mockProcessPartialRefund = async (params) => {
2
2
  // The mock has no split-payment modal or order engine, so `openUI` (default
3
- // true on the real command), `legs` (the headless per-tender allocation) and
4
- // any per-leg `giftCard` destination (mixed returns) are inert here — the
5
- // shape is accepted and echoed, nothing else. No gift card is credited.
6
- console.log("[Mock] processPartialRefund called", {
3
+ // true on the real command), `legs` (the headless per-tender allocation), a
4
+ // per-leg `giftCard` destination (mixed returns) and the top-level `giftCard`
5
+ // routing are all inert here — the shape is accepted and echoed, nothing
6
+ // else. No gift card is credited.
7
+ //
8
+ // The one rule worth mirroring is the mutual exclusion, so a flow built
9
+ // against the mock fails the same way it will against the runtime.
10
+ if (params?.legs && params?.giftCard) {
11
+ throw new Error('refund.giftCardAndLegs: pass either `legs` (you allocate) or `giftCard` (the engine allocates), not both');
12
+ }
13
+ console.log('[Mock] processPartialRefund called', {
7
14
  ...params,
8
15
  openUI: params?.openUI ?? true,
9
16
  legs: params?.legs ?? null,
17
+ giftCard: params?.giftCard ?? null,
10
18
  });
11
19
  return {
12
20
  success: true,
13
21
  refundId: 'mock_refund_' + Date.now(),
14
- timestamp: new Date().toISOString()
22
+ modalRaised: false,
23
+ timestamp: new Date().toISOString(),
15
24
  };
16
25
  };
@@ -1,12 +1,12 @@
1
- import type { CFTransitionResult } from "../../common-types/order-state";
2
1
  export interface ProcessPartialRefundParams {
3
2
  /**
4
3
  * Optional refund reason.
5
4
  *
6
- * KNOWN LIMITATION: not currently persisted on the `Refund` doc or the
7
- * state-event audit row via this command the runtime falls back to a
8
- * fixed 'partial-refund' label instead. Unlike `redeemRefund`, whose
9
- * `reason` IS recorded. See the README's "Known limitation" section.
5
+ * Recorded verbatim on the persisted `Refund` doc's `reason` field and on
6
+ * the state-event audit row — same as `redeemRefund`. When omitted, the
7
+ * refund doc's `reason` stays unset and only the audit row carries the
8
+ * 'partial-refund' fallback label. See the README's "`reason` persistence"
9
+ * section.
10
10
  */
11
11
  reason?: string;
12
12
  /** Optional: specify which order to refund (sets it as active). */
@@ -88,6 +88,47 @@ export interface ProcessPartialRefundParams {
88
88
  label?: string;
89
89
  };
90
90
  }[];
91
+ /**
92
+ * Route part (or all) of the refund onto ONE gift-card / store-credit tender
93
+ * and let the engine send whatever is left back to the original payments.
94
+ *
95
+ * This is the declarative alternative to hand-building `legs`: state the card
96
+ * and how much lands on it, and the engine does the allocation — it already
97
+ * owns that math for every other refund path. Prefer it over `legs` for a
98
+ * gift-card destination; a flow that computes its own split is duplicating
99
+ * engine arithmetic that will drift (see "Query, never recompute").
100
+ *
101
+ * - `amount` omitted → the WHOLE refund lands on the card (what an
102
+ * all-`giftCard` `legs` staging does today).
103
+ * - `amount` set → that much lands on the card, in minor units; the
104
+ * remainder returns to the original payments, allocated by the engine.
105
+ *
106
+ * DRAWING ORDER — the card is filled from the tenders that cannot be
107
+ * refunded to source first (a redeem tender has nowhere to return to), then
108
+ * proportionally from the rest. So `amount` can never be lower than what
109
+ * those tenders must contribute: below that the call throws
110
+ * `REFUND_GIFT_AMOUNT_BELOW_MINIMUM`, naming the minimum, and nothing is
111
+ * committed. Surface that message — it is the number to clamp the field to,
112
+ * so the flow never has to derive it.
113
+ *
114
+ * Exactly one destination card, therefore exactly ONE credit for the caller
115
+ * to place and one to reverse. **Credit-first:** credit `referenceId` for
116
+ * `amount` (or the full refund total when omitted) BEFORE calling; on any
117
+ * throw nothing was recorded — reverse it.
118
+ *
119
+ * Requires `openUI: false`. Mutually exclusive with `legs` — passing both
120
+ * throws, since they are two answers to the same question.
121
+ */
122
+ giftCard?: {
123
+ /** Card/account id the flow already credited (stored raw). */
124
+ referenceId: string;
125
+ /** Minor units landing on the card. Omit for the whole refund. */
126
+ amount?: number;
127
+ /** Provider/program name. Defaults to `giftCard`. */
128
+ processor?: string;
129
+ /** Human label for the destination tender. */
130
+ label?: string;
131
+ };
91
132
  /** Optional items to refund. */
92
133
  items?: {
93
134
  /** internalId or variantId or customSaleId. */
@@ -112,9 +153,25 @@ export interface ProcessPartialRefundParams {
112
153
  }
113
154
  export interface ProcessPartialRefundResponse {
114
155
  success: boolean;
115
- refundId: string;
156
+ /**
157
+ * The persisted Refund document's id — the REAL one, usable to look the
158
+ * refund up. `null` means nothing has committed: the split-payment modal
159
+ * was raised (`modalRaised: true`) and owns the commit from there.
160
+ *
161
+ * Before kaching 1.9.5-preprod.17 this was the hardcoded string
162
+ * `'processed'` regardless of outcome, so a truthiness check could not
163
+ * detect a refund that silently didn't happen. Guard on it now:
164
+ * `if (!res.refundId && !res.modalRaised) …` is unreachable (such paths
165
+ * throw instead), so `res.refundId` alone answers "did money move".
166
+ */
167
+ refundId: string | null;
168
+ /**
169
+ * True when a multi-tender order raised the split-payment refund modal
170
+ * (`openUI` omitted or `true`): the cashier allocates there and the modal
171
+ * drives the commit — this call wrote nothing. Headless calls
172
+ * (`openUI: false`) never raise it.
173
+ */
174
+ modalRaised: boolean;
116
175
  timestamp: string;
117
- /** Present when the state machine blocked or forced the transition. */
118
- transitionResult?: CFTransitionResult;
119
176
  }
120
177
  export type ProcessPartialRefund = (params?: ProcessPartialRefundParams) => Promise<ProcessPartialRefundResponse>;
@@ -12,8 +12,8 @@ export interface RedeemPaymentParams {
12
12
  processor?: string;
13
13
  referenceId?: string;
14
14
  metadata?: Record<string, unknown>;
15
- /** Override the fulfillment landing on full payment. Omitted: preserve advanced fulfillment, auto-fulfill from draft/pending/on_hold. */
16
- targetFulfillmentState?: string;
15
+ /** Override the fulfillment state the order lands in on full payment (validated against the fulfillment state machine; invalid values throw). Omitted: preserve advanced fulfillment, auto-fulfill from draft/pending/on_hold. */
16
+ checkoutFulfillmentTarget?: string;
17
17
  }
18
18
  export type RedeemPaymentResponse = ExtensionPaymentResponse;
19
19
  export type RedeemPayment = (params: RedeemPaymentParams) => Promise<RedeemPaymentResponse>;
@@ -1,10 +1,19 @@
1
1
  export interface RemoveProductFeeParams {
2
- /** If provided, removes fee from specific cart item. Otherwise uses active product. */
2
+ /** If provided, removes fee(s) from a specific cart item. Otherwise uses active product. */
3
3
  internalId?: string;
4
+ /**
5
+ * 0-based index of the single fee to remove, in the order the line's fees
6
+ * were added (fees STACK — `addProductFee` appends). Omit to clear ALL
7
+ * fees on the line (the legacy behavior). Out-of-range indexes are a
8
+ * no-op.
9
+ */
10
+ index?: number;
4
11
  }
5
12
  export interface RemoveProductFeeResponse {
6
13
  success: boolean;
7
14
  internalId?: string;
15
+ /** Echoed when a single fee was targeted. */
16
+ index?: number;
8
17
  timestamp: string;
9
18
  }
10
19
  export type RemoveProductFee = (params?: RemoveProductFeeParams) => Promise<RemoveProductFeeResponse>;
@@ -1,5 +1,4 @@
1
1
  import { CFOrder } from "../../CommonTypes";
2
- import type { CFTransitionResult } from "../../common-types/order-state";
3
2
  export interface ResumeParkedOrderParams {
4
3
  orderId: string;
5
4
  }
@@ -7,7 +6,5 @@ export interface ResumeParkedOrderResponse {
7
6
  success: boolean;
8
7
  order: CFOrder;
9
8
  timestamp: string;
10
- /** Present when the state machine blocked or forced the transition. */
11
- transitionResult?: CFTransitionResult;
12
9
  }
13
10
  export type ResumeParkedOrder = (params?: ResumeParkedOrderParams) => Promise<ResumeParkedOrderResponse>;
@@ -3,6 +3,6 @@
3
3
  * Calls the selectAllRefundItems action on the parent window
4
4
  */
5
5
  import { commandFrameClient } from "../../client";
6
- export const selectAllRefundItems = async () => {
7
- return await commandFrameClient.call("selectAllRefundItems");
6
+ export const selectAllRefundItems = async (params) => {
7
+ return await commandFrameClient.call("selectAllRefundItems", params);
8
8
  };
@@ -7,4 +7,4 @@ export interface SetActiveRefundResponse {
7
7
  refund: CFActiveRefundDetails;
8
8
  timestamp: string;
9
9
  }
10
- export type SetActiveRefund = (params?: SetActiveRefundParams) => Promise<SetActiveRefundResponse>;
10
+ export type SetActiveRefund = (params: SetActiveRefundParams) => Promise<SetActiveRefundResponse>;
@@ -1,6 +1,6 @@
1
1
  export interface SetRefundStockActionParams {
2
2
  orderId?: string;
3
- /** The 'key' field from getLineItemsByOrder response (internalId || variantId || productId). */
3
+ /** The 'key' field from getLineItemsByOrder response (internalId, falling back to variantId). */
4
4
  itemKey: string;
5
5
  action: 'RESTOCK' | 'REFUND_DAMAGE';
6
6
  }
@@ -10,6 +10,10 @@ export const mockTapToPayPayment = async (params) => {
10
10
  amount: due,
11
11
  paymentType: "tapToPay",
12
12
  order,
13
- timestamp: new Date().toISOString()
13
+ timestamp: new Date().toISOString(),
14
+ change: 0,
15
+ cashRounding: 0,
16
+ saleFinalized: true,
17
+ remainingBalance: 0
14
18
  };
15
19
  };
@@ -1,17 +1,19 @@
1
1
  import { CFOrder } from "../../CommonTypes";
2
- import type { CFTransitionResult } from "../../common-types/order-state";
3
2
  export interface TapToPayPaymentParams {
4
3
  /**
5
4
  * The amount to pay with this tender, in integer MINOR currency units
6
- * (e.g. 1575 = $15.75). Required. Semantics against the cart's balance due:
7
- * - missing → error
5
+ * (e.g. 1575 = $15.75). Required whenever the balance due is greater than
6
+ * $0; may be omitted only on a cart that already nets to a $0 balance due
7
+ * (e.g. fully discounted), where it defaults to 0. Semantics against the
8
+ * cart's balance due:
9
+ * - missing → error, unless the balance due is $0 (→ 0)
8
10
  * - less than balance → partial payment (the POS enters a fixed
9
11
  * split-payment leg for this amount)
10
12
  * - equal to balance → full payment
11
13
  * - more than balance → error
12
14
  */
13
- amount: number;
14
- /** Override the fulfillment state after full payment. Render resolves the cascade. */
15
+ amount?: number;
16
+ /** Override the fulfillment state after full payment. kaching resolves the cascade. */
15
17
  checkoutFulfillmentTarget?: string;
16
18
  }
17
19
  export interface TapToPayPaymentResponse {
@@ -20,7 +22,13 @@ export interface TapToPayPaymentResponse {
20
22
  paymentType: string;
21
23
  order: CFOrder | null;
22
24
  timestamp: string;
23
- /** Present when the state machine blocked or forced the transition. */
24
- transitionResult?: CFTransitionResult;
25
+ /** Change due back to the customer in integer MINOR currency units (0 for non-cash tenders). */
26
+ change: number;
27
+ /** Signed cash-rounding delta applied to the charge, in integer MINOR currency units (positive = rounded up); 0 when the company has no cash-rounding setting. */
28
+ cashRounding: number;
29
+ /** True when this tender settled the cart's remaining balance (the sale completed). */
30
+ saleFinalized: boolean;
31
+ /** Balance still due after this tender, in integer MINOR currency units (0 once the sale is finalized). */
32
+ remainingBalance: number;
25
33
  }
26
34
  export type TapToPayPayment = (params?: TapToPayPaymentParams) => Promise<TapToPayPaymentResponse>;
@@ -11,6 +11,10 @@ export const mockTerminalPayment = async (params) => {
11
11
  amount: due,
12
12
  paymentType: "terminal",
13
13
  order,
14
- timestamp: new Date().toISOString()
14
+ timestamp: new Date().toISOString(),
15
+ change: 0,
16
+ cashRounding: 0,
17
+ saleFinalized: true,
18
+ remainingBalance: 0
15
19
  };
16
20
  };
@@ -1,5 +1,4 @@
1
1
  import { CFOrder } from "../../CommonTypes";
2
- import type { CFTransitionResult } from "../../common-types/order-state";
3
2
  export interface TerminalPaymentParams {
4
3
  /**
5
4
  * The amount to pay with this tender, in integer MINOR currency units
@@ -11,10 +10,10 @@ export interface TerminalPaymentParams {
11
10
  * - more than balance → error
12
11
  */
13
12
  amount: number;
14
- /** "Bluetooth" or "Cloud". Defaults to "Cloud". */
13
+ /** "Bluetooth" or "Cloud". Only "Cloud" routes to the cloud processor; omitted or "Bluetooth" uses the native card reader. */
15
14
  paymentType?: "Bluetooth" | "Cloud";
16
- /** Override the fulfillment landing on full payment. Omitted: preserve advanced fulfillment, auto-fulfill from draft/pending/on_hold. */
17
- targetFulfillmentState?: string;
15
+ /** Override the fulfillment state the order lands in on full payment (validated against the fulfillment state machine; invalid values throw). Omitted: preserve advanced fulfillment, auto-fulfill from draft/pending/on_hold. */
16
+ checkoutFulfillmentTarget?: string;
18
17
  }
19
18
  export interface TerminalPaymentResponse {
20
19
  success: boolean;
@@ -22,7 +21,13 @@ export interface TerminalPaymentResponse {
22
21
  paymentType: string;
23
22
  order: CFOrder | null;
24
23
  timestamp: string;
25
- /** Present when the state machine blocked or forced the transition. */
26
- transitionResult?: CFTransitionResult;
24
+ /** Change due back to the customer in integer MINOR currency units (0 for non-cash tenders). */
25
+ change: number;
26
+ /** Signed cash-rounding delta applied to the charge, in integer MINOR currency units (positive = rounded up); 0 when the company has no cash-rounding setting. */
27
+ cashRounding: number;
28
+ /** True when this tender settled the cart's remaining balance (the sale completed). */
29
+ saleFinalized: boolean;
30
+ /** Balance still due after this tender, in integer MINOR currency units (0 once the sale is finalized). */
31
+ remainingBalance: number;
27
32
  }
28
33
  export type TerminalPayment = (params?: TerminalPaymentParams) => Promise<TerminalPaymentResponse>;
@@ -1,6 +1,16 @@
1
+ /** The persisted custom-table row: your `data` fields plus the platform-generated identity. */
2
+ export type UpsertedCustomTableRow<T = any> = T & {
3
+ /** Generated row id (present on both insert and update). */
4
+ _id: string;
5
+ /** ISO timestamp; present on insert. */
6
+ createdAt?: string;
7
+ /** ISO timestamp; set on every upsert. */
8
+ updatedAt?: string;
9
+ };
1
10
  export interface UpsertCustomTableDataResponse<T = any> {
2
11
  success: boolean;
3
- data: T;
12
+ /** The PERSISTED row (with the generated `_id`/timestamps), not a bare echo of the input. */
13
+ data: UpsertedCustomTableRow<T>;
4
14
  timestamp: string;
5
15
  }
6
16
  export interface UpsertCustomTableDataParams<T = any> {
@@ -1,12 +1,12 @@
1
- import type { CFTransitionResult } from '../../common-types/order-state';
2
1
  export type VoidOrderOutcome = 'voided' | 'refunded';
3
2
  export interface VoidOrderParams {
4
3
  /** Order to void; defaults to the active order. */
5
4
  orderId?: string;
6
5
  /**
7
- * Optional cashier-facing reason. On a pure void, recorded on the void audit
8
- * row and carried on the `order-voided` event. On the refund branch it rides
9
- * the event only the refund dispatcher does not consume it.
6
+ * Optional cashier-facing reason. Recorded on both branches the void audit
7
+ * trail on a pure void, and (verbatim) on the persisted refund plus its own
8
+ * audit trail on the refund branch and always carried on the
9
+ * `order-voided` event either way.
10
10
  */
11
11
  reason?: string;
12
12
  }
@@ -21,7 +21,5 @@ export interface VoidOrderResponse {
21
21
  */
22
22
  outcome: VoidOrderOutcome;
23
23
  timestamp: string;
24
- /** Present when the state machine blocked or forced the transition. */
25
- transitionResult?: CFTransitionResult;
26
24
  }
27
25
  export type VoidOrder = (params?: VoidOrderParams) => Promise<VoidOrderResponse>;
package/dist/index.d.ts CHANGED
@@ -38,7 +38,6 @@ export declare const command: {
38
38
  readonly getCashRoundingAmount: import(".").GetCashRoundingAmount;
39
39
  readonly tapToPayPayment: import(".").TapToPayPayment;
40
40
  readonly terminalPayment: import(".").TerminalPayment;
41
- readonly vendaraPayment: import(".").VendaraPayment;
42
41
  readonly extensionPayment: import(".").ExtensionPayment;
43
42
  readonly redeemPayment: import(".").RedeemPayment;
44
43
  readonly integrationPayment: import(".").IntegrationPayment;
@@ -142,11 +141,9 @@ export type { CalculateRefundTotal, CalculateRefundTotalParams, CalculateRefundT
142
141
  export type { GetRemainingRefundableQuantities, GetRemainingRefundableQuantitiesParams, GetRemainingRefundableQuantitiesResponse, } from './actions/get-remaining-refundable-quantities/types';
143
142
  export type { ProcessPartialRefund, ProcessPartialRefundParams, ProcessPartialRefundResponse, } from './actions/process-partial-refund/types';
144
143
  export type { RedeemRefund, RedeemRefundParams, RedeemRefundResponse } from './actions/redeem-refund/types';
145
- export type { GetRefundPlan, GetRefundPlanParams, GetRefundPlanResponse, RefundPlanSource, } from './actions/get-refund-plan/types';
146
- export type { CheckPermission, CheckPermissionParams, CheckPermissionResponse, } from './actions/check-permission/types';
144
+ export type { GetRefundPlan, GetRefundPlanParams, GetRefundPlanResponse, RefundPlanSource, RefundPlanAllocation, RefundPlanLeg, } from './actions/get-refund-plan/types';
145
+ export type { CheckPermission, CheckPermissionParams, CheckPermissionResponse } from './actions/check-permission/types';
147
146
  export type { InitiateRefund, InitiateRefundParams, InitiateRefundResponse } from './actions/initiate-refund/types';
148
- export type { OpenExtensionOverlay, OpenExtensionOverlayParams, OpenExtensionOverlayResponse, } from './actions/open-extension-overlay/types';
149
- export type { ResolveExtensionOverlay, ResolveExtensionOverlayParams, ResolveExtensionOverlayResponse, } from './actions/resolve-extension-overlay/types';
150
147
  export type { GetCurrentCart, GetCurrentCartResponse } from './actions/get-current-cart/types';
151
148
  export type { AddProductDiscount, AddProductDiscountParams, AddProductDiscountResponse, } from './actions/add-product-discount/types';
152
149
  export type { AddProductToCart, AddProductToCartParams, AddProductToCartResponse, } from './actions/add-product-to-cart/types';
@@ -173,7 +170,6 @@ export type { CashPayment, CashPaymentParams, CashPaymentResponse } from './acti
173
170
  export type { GetCashRoundingAmount, GetCashRoundingAmountParams, GetCashRoundingAmountResponse, } from './actions/get-cash-rounding-amount/types';
174
171
  export type { TapToPayPayment, TapToPayPaymentParams, TapToPayPaymentResponse, } from './actions/tap-to-pay-payment/types';
175
172
  export type { TerminalPayment, TerminalPaymentParams, TerminalPaymentResponse } from './actions/terminal-payment/types';
176
- export type { VendaraPayment, VendaraPaymentParams, VendaraPaymentResponse } from './actions/vendara-payment/types';
177
173
  export type { ExtensionPayment, ExtensionPaymentParams, ExtensionPaymentResponse, } from './actions/extension-payment/types';
178
174
  export type { RedeemPayment, RedeemPaymentParams, RedeemPaymentResponse } from './actions/redeem-payment/types';
179
175
  export type { IntegrationPayment, IntegrationPaymentParams, IntegrationPaymentResponse, IntegrationEmvData, } from './actions/integration-payment/types';
@@ -226,10 +222,6 @@ export type { PostMessageRequest, PostMessageResponse } from './client';
226
222
  export { topics } from './pubsub/topics';
227
223
  export type { TopicDefinition, TopicEvent, TopicEventType, TopicSubscriptionCallback, TopicSubscription, HookCallback, HookOptions, HookRegistration, } from './pubsub/types';
228
224
  export type { TopicEventPayloadMap } from './pubsub/topics/types';
229
- export { hooks } from './hooks';
230
- export type { HookFunction, HookRegisterOptions } from './hooks';
231
- export { interceptors } from './interceptors';
232
- export type { InterceptorFunction, InterceptorPoint, InterceptorRegisterOptions, InterceptorReturn, InterceptorOverlayContext, InterceptorHostCommands, } from './interceptors';
233
225
  export { customersTopic } from './pubsub/topics/customers';
234
226
  export { ordersTopic } from './pubsub/topics/orders';
235
227
  export { refundsTopic } from './pubsub/topics/refunds';
package/dist/index.js CHANGED
@@ -38,7 +38,6 @@ import { cashPayment } from './actions/cash-payment/action';
38
38
  import { getCashRoundingAmount } from './actions/get-cash-rounding-amount/action';
39
39
  import { tapToPayPayment } from './actions/tap-to-pay-payment/action';
40
40
  import { terminalPayment } from './actions/terminal-payment/action';
41
- import { vendaraPayment } from './actions/vendara-payment/action';
42
41
  import { extensionPayment } from './actions/extension-payment/action';
43
42
  import { redeemPayment } from './actions/redeem-payment/action';
44
43
  import { integrationPayment } from './actions/integration-payment/action';
@@ -172,7 +171,6 @@ export const command = {
172
171
  getCashRoundingAmount,
173
172
  tapToPayPayment,
174
173
  terminalPayment,
175
- vendaraPayment,
176
174
  extensionPayment,
177
175
  redeemPayment,
178
176
  integrationPayment,
@@ -277,10 +275,6 @@ export * from './projects/manage';
277
275
  export { commandFrameClient, CommandFrameClient } from './client';
278
276
  // Export Pub/Sub
279
277
  export { topics } from './pubsub/topics';
280
- // Export Hooks (extension iframe API for session-scoped event callbacks)
281
- export { hooks } from './hooks';
282
- // Export Interceptors (extension iframe API for gating host flows)
283
- export { interceptors } from './interceptors';
284
278
  // Export Pub/Sub Topics
285
279
  export { customersTopic } from './pubsub/topics/customers';
286
280
  export { ordersTopic } from './pubsub/topics/orders';
@@ -44,8 +44,6 @@ import { mockGetTaxTables } from '../../actions/get-tax-tables/mock';
44
44
  import { mockGetRemainingRefundableQuantities } from '../../actions/get-remaining-refundable-quantities/mock';
45
45
  import { mockGoToStationHome } from '../../actions/go-to-station-home/mock';
46
46
  import { mockInitiateRefund } from '../../actions/initiate-refund/mock';
47
- import { mockOpenExtensionOverlay } from '../../actions/open-extension-overlay/mock';
48
- import { mockResolveExtensionOverlay } from '../../actions/resolve-extension-overlay/mock';
49
47
  import { mockOpenCashDrawer } from '../../actions/open-cash-drawer/mock';
50
48
  import { mockParkOrder } from '../../actions/park-order/mock';
51
49
  import { mockPartialPayment } from '../../actions/partial-payment/mock';
@@ -63,7 +61,6 @@ import { mockShowNotification } from '../../actions/show-notification/mock';
63
61
  import { mockSwitchUser } from '../../actions/switch-user/mock';
64
62
  import { mockTapToPayPayment } from '../../actions/tap-to-pay-payment/mock';
65
63
  import { mockTerminalPayment } from '../../actions/terminal-payment/mock';
66
- import { mockVendaraPayment } from '../../actions/vendara-payment/mock';
67
64
  import { mockExtensionPayment } from '../../actions/extension-payment/mock';
68
65
  import { mockRedeemPayment } from '../../actions/redeem-payment/mock';
69
66
  import { mockIntegrationPayment } from '../../actions/integration-payment/mock';
@@ -141,8 +138,6 @@ export const RENDER_MOCKS = {
141
138
  getRemainingRefundableQuantities: mockGetRemainingRefundableQuantities,
142
139
  goToStationHome: mockGoToStationHome,
143
140
  initiateRefund: mockInitiateRefund,
144
- openExtensionOverlay: mockOpenExtensionOverlay,
145
- resolveExtensionOverlay: mockResolveExtensionOverlay,
146
141
  openCashDrawer: mockOpenCashDrawer,
147
142
  parkOrder: mockParkOrder,
148
143
  partialPayment: mockPartialPayment,
@@ -161,7 +156,6 @@ export const RENDER_MOCKS = {
161
156
  switchUser: mockSwitchUser,
162
157
  tapToPayPayment: mockTapToPayPayment,
163
158
  terminalPayment: mockTerminalPayment,
164
- vendaraPayment: mockVendaraPayment,
165
159
  extensionPayment: mockExtensionPayment,
166
160
  redeemPayment: mockRedeemPayment,
167
161
  integrationPayment: mockIntegrationPayment,
@@ -1,6 +1,4 @@
1
- import type { ExampleFunction, GetProducts, AddCustomSale, EditCustomSale, GetCustomers, AssignCustomer, AddCustomer, EditCustomer, GetCategories, GetOrders, GetRefunds, GetTaxTables, AddProductDiscount, AddProductToCart, RemoveProductFromCart, UpdateCartItemQuantity, AddCartDiscount, GetContext, GetFinalContext, AddProductNote, AddProductFee, SetActiveProductFee, SetActiveProductDiscount, GetActiveProduct, SetActiveProduct, AdjustInventory, AddOrderNote, AddCartFee, ClearCart, ParkOrder, ResumeParkedOrder, DeleteParkedOrder, VoidOrder, InitiateRefund, CashPayment, GetCashRoundingAmount, TapToPayPayment, TerminalPayment, VendaraPayment, 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 } from '../../index';
2
- import type { OpenExtensionOverlay } from '../../actions/open-extension-overlay/types';
3
- import type { ResolveExtensionOverlay } from '../../actions/resolve-extension-overlay/types';
1
+ import type { ExampleFunction, GetProducts, AddCustomSale, EditCustomSale, GetCustomers, AssignCustomer, AddCustomer, EditCustomer, GetCategories, GetOrders, GetRefunds, GetTaxTables, AddProductDiscount, AddProductToCart, RemoveProductFromCart, UpdateCartItemQuantity, AddCartDiscount, GetContext, GetFinalContext, AddProductNote, AddProductFee, 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 } from '../../index';
4
2
  export interface RenderProviderActions {
5
3
  exampleFunction: ExampleFunction;
6
4
  getProducts: GetProducts;
@@ -36,13 +34,10 @@ export interface RenderProviderActions {
36
34
  deleteParkedOrder: DeleteParkedOrder;
37
35
  voidOrder: VoidOrder;
38
36
  initiateRefund: InitiateRefund;
39
- openExtensionOverlay: OpenExtensionOverlay;
40
- resolveExtensionOverlay: ResolveExtensionOverlay;
41
37
  cashPayment: CashPayment;
42
38
  getCashRoundingAmount: GetCashRoundingAmount;
43
39
  tapToPayPayment: TapToPayPayment;
44
40
  terminalPayment: TerminalPayment;
45
- vendaraPayment: VendaraPayment;
46
41
  extensionPayment: ExtensionPayment;
47
42
  redeemPayment: RedeemPayment;
48
43
  integrationPayment: IntegrationPayment;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@final-commerce/command-frame",
3
- "version": "0.4.2-preprod.1",
3
+ "version": "0.5.0-preprod.10",
4
4
  "description": "Commands Frame library",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
@@ -1,2 +0,0 @@
1
- import type { OpenExtensionOverlay } from "./types";
2
- export declare const openExtensionOverlay: OpenExtensionOverlay;
@@ -1,4 +0,0 @@
1
- import { commandFrameClient } from "../../client";
2
- export const openExtensionOverlay = async (params) => {
3
- return await commandFrameClient.call("openExtensionOverlay", params);
4
- };
@@ -1,2 +0,0 @@
1
- import type { OpenExtensionOverlay } from "./types";
2
- export declare const mockOpenExtensionOverlay: OpenExtensionOverlay;
@@ -1 +0,0 @@
1
- export const mockOpenExtensionOverlay = async (_params) => true;