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

package/README.md

@@ -16,7 +16,7 @@ The library provides three main capabilities:
 | **Pub/Sub**         | Subscribe to real-time events from the host (e.g. cart changes, payments) | Page-scoped (while iframe is mounted)     |
 | **Hooks**           | Register business-logic callbacks that persist across all pages           | Session-scoped (survives page navigation) |
 | **Interceptors**    | Gate POS flows (approve / modify / block) at named points                 | Blocking; host waits for your response    |
-| **Refund commands** | Refund payments to gift cards or redeem tenders via `redeemRefund`, or mixed-destination legs on `processPartialRefund`; query engine capacity with `getRefundPlan` | Request/response per call                 |
+| **Refund commands** | Refund payments to gift cards or redeem tenders via `redeemRefund`, or mixed-destination legs on `processPartialRefund`; query engine capacity with `getRefundPlan`; pre-gate UI with `checkPermission` (`issue_refunds` is enforced runtime-side) | Request/response per call                 |
 
 Domain models (orders, cart, customers, products, and related types) are documented in **[Types reference](./src/types/README.md)**.
 

package/dist/actions/check-permission/action.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Check permission action
+ * Calls the checkPermission action on the parent window
+ */
+import type { CheckPermission } from './types';
+export declare const checkPermission: CheckPermission;

package/dist/actions/check-permission/action.js

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

package/dist/actions/check-permission/mock.d.ts

@@ -0,0 +1,8 @@
+import { CheckPermission } from './types';
+/**
+ * Standalone mock: `allowed: true` for every permission EXCEPT the magic name
+ * `'mock_denied'`, which returns `allowed: false` — so flows can exercise both
+ * UI branches outside the iframe. The runtime answers from the hydrated
+ * active user's role instead.
+ */
+export declare const mockCheckPermission: CheckPermission;

package/dist/actions/check-permission/mock.js

@@ -0,0 +1,18 @@
+/**
+ * Standalone mock: `allowed: true` for every permission EXCEPT the magic name
+ * `'mock_denied'`, which returns `allowed: false` — so flows can exercise both
+ * UI branches outside the iframe. The runtime answers from the hydrated
+ * active user's role instead.
+ */
+export const mockCheckPermission = async (params) => {
+    console.log('[Mock] checkPermission called', params);
+    if (!params?.permission) {
+        throw new Error('permission is required');
+    }
+    return {
+        success: true,
+        permission: params.permission,
+        allowed: params.permission !== 'mock_denied',
+        timestamp: new Date().toISOString(),
+    };
+};

package/dist/actions/check-permission/types.d.ts

@@ -0,0 +1,17 @@
+export interface CheckPermissionParams {
+    /** Permission name, e.g. 'issue_refunds'. */
+    permission: string;
+}
+export interface CheckPermissionResponse {
+    success: boolean;
+    /** Echo of the permission that was checked. */
+    permission: string;
+    /**
+     * True when the active user holds the permission — either explicitly on
+     * their role, or implicitly because their user type does not carry a role
+     * (company owner, final/org staff).
+     */
+    allowed: boolean;
+    timestamp: string;
+}
+export type CheckPermission = (params: CheckPermissionParams) => Promise<CheckPermissionResponse>;

package/dist/actions/check-permission/types.js

@@ -0,0 +1,9 @@
+// Check Permission Types
+//
+// READ-ONLY query: does the ACTIVE user hold a named permission? Truth source
+// is the runtime's hydrated active user (role + permissions from the synced
+// `users`/`roles` collections). Use it to PRE-GATE UI (hide/disable a Refund
+// button, show "You are not allowed to initiate refunds") — it is not the
+// security boundary: mutating refund commands enforce `issue_refunds`
+// runtime-side regardless (`REFUND_PERMISSION_DENIED: ` prefix).
+export {};

package/dist/actions/redeem-refund/mock.js

@@ -1,6 +1,4 @@
 import { MOCK_ORDERS, mockPublishEvent } from '../../demo/database';
-// Payment states in which an order is refundable
-const REFUNDABLE_PAYMENT_STATES = ['paid', 'partially_refunded'];
 // Track refunded amounts per order to enforce remaining capacity gate
 const mockRefundedAmounts = {};
 export const mockRedeemRefund = async (params) => {
@@ -18,10 +16,8 @@ export const mockRedeemRefund = async (params) => {
         throw new Error(`Order with ID ${params.orderId} not found`);
     }
     const orderId = order._id;
-    // Check if order is in a refundable state
-    if (!REFUNDABLE_PAYMENT_STATES.includes(order.paymentState)) {
-        throw new Error(`ORDER_NOT_REFUNDABLE: order ${orderId} is '${order.paymentState}' — only 'paid' or 'partially_refunded' orders can be refunded`);
-    }
+    // NO payment-state gate — the runtime has none (partially_paid orders are
+    // refundable too); mirroring it here would teach devs a phantom error class.
     // Track refunded amounts and check remaining capacity
     const refundedSoFar = mockRefundedAmounts[orderId] || 0;
     const remainingCapacity = order.summary.total - refundedSoFar;

package/dist/index.d.ts

@@ -82,6 +82,7 @@ export declare const command: {
     readonly processPartialRefund: import(".").ProcessPartialRefund;
     readonly redeemRefund: import(".").RedeemRefund;
     readonly getRefundPlan: import(".").GetRefundPlan;
+    readonly checkPermission: import(".").CheckPermission;
     readonly addProduct: import(".").AddProduct;
     readonly editProduct: import(".").EditProduct;
     readonly editProductVariants: import(".").EditProductVariants;
@@ -142,6 +143,7 @@ export type { GetRemainingRefundableQuantities, GetRemainingRefundableQuantities
 export type { ProcessPartialRefund, ProcessPartialRefundParams, ProcessPartialRefundResponse, } from './actions/process-partial-refund/types';
 export type { RedeemRefund, RedeemRefundParams, RedeemRefundResponse } from './actions/redeem-refund/types';
 export type { GetRefundPlan, GetRefundPlanParams, GetRefundPlanResponse, RefundPlanSource, } from './actions/get-refund-plan/types';
+export type { CheckPermission, CheckPermissionParams, CheckPermissionResponse, } from './actions/check-permission/types';
 export type { InitiateRefund, InitiateRefundParams, InitiateRefundResponse } from './actions/initiate-refund/types';
 export type { OpenExtensionOverlay, OpenExtensionOverlayParams, OpenExtensionOverlayResponse, } from './actions/open-extension-overlay/types';
 export type { ResolveExtensionOverlay, ResolveExtensionOverlayParams, ResolveExtensionOverlayResponse, } from './actions/resolve-extension-overlay/types';

package/dist/index.js

@@ -89,6 +89,7 @@ import { getRemainingRefundableQuantities } from './actions/get-remaining-refund
 import { processPartialRefund } from './actions/process-partial-refund/action';
 import { redeemRefund } from './actions/redeem-refund/action';
 import { getRefundPlan } from './actions/get-refund-plan/action';
+import { checkPermission } from './actions/check-permission/action';
 // Custom Tables Actions
 import { getCustomTables } from './actions/get-custom-tables/action';
 import { getCustomTableFields } from './actions/get-custom-table-fields/action';
@@ -221,6 +222,7 @@ export const command = {
     processPartialRefund,
     redeemRefund,
     getRefundPlan,
+    checkPermission,
     // Product CRUD Actions
     addProduct,
     editProduct,

package/dist/projects/render/mocks.js

@@ -52,6 +52,7 @@ import { mockPartialPayment } from '../../actions/partial-payment/mock';
 import { mockProcessPartialRefund } from '../../actions/process-partial-refund/mock';
 import { mockRedeemRefund } from '../../actions/redeem-refund/mock';
 import { mockGetRefundPlan } from '../../actions/get-refund-plan/mock';
+import { mockCheckPermission } from '../../actions/check-permission/mock';
 import { mockRemoveCustomerFromCart } from '../../actions/remove-customer-from-cart/mock';
 import { mockResetRefundDetails } from '../../actions/reset-refund-details/mock';
 import { mockResumeParkedOrder } from '../../actions/resume-parked-order/mock';
@@ -148,6 +149,7 @@ export const RENDER_MOCKS = {
     processPartialRefund: mockProcessPartialRefund,
     redeemRefund: mockRedeemRefund,
     getRefundPlan: mockGetRefundPlan,
+    checkPermission: mockCheckPermission,
     removeCustomerFromCart: mockRemoveCustomerFromCart,
     removeCartDiscount: mockRemoveCartDiscount,
     resetRefundDetails: mockResetRefundDetails,

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, 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, 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';
+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';
 import type { OpenExtensionOverlay } from '../../actions/open-extension-overlay/types';
 import type { ResolveExtensionOverlay } from '../../actions/resolve-extension-overlay/types';
 export interface RenderProviderActions {
@@ -66,6 +66,7 @@ export interface RenderProviderActions {
     processPartialRefund: ProcessPartialRefund;
     redeemRefund: RedeemRefund;
     getRefundPlan: GetRefundPlan;
+    checkPermission: CheckPermission;
     getCurrentCart: GetCurrentCart;
     print: Print;
     setActiveOrder: SetActiveOrder;

package/package.json

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