@final-commerce/command-frame 0.1.33 → 0.1.34

package/README.md

@@ -6,43 +6,44 @@ A TypeScript library for type-safe communication between iframes and their paren
 
 Command Frame provides a structured way to build integrations that run inside Final Commerce applications (like Render POS or Manage Dashboard). It handles the underlying `postMessage` communication while enforcing strict type safety for both the host application (Provider) and the embedded app (Client).
 
+The library provides three main capabilities:
+
+| Capability | Purpose | Scope |
+|-----------|---------|-------|
+| **Commands** | Call host functions from the iframe (e.g. get products, open cash drawer) | Request/response per call |
+| **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) |
+
 ## Installation
 
 ```bash
 npm install @final-commerce/command-frame
 ```
 
-## Available Integrations
+## Commands
 
-This library supports multiple host environments. Choose the client that matches the platform you are building for.
+Commands let the extension iframe call typed functions on the host. Each host environment (Render, Manage) exposes its own set of commands.
 
-### 1. Render (POS System)
+### Render (POS System)
 
 For building applications that run inside the Render Point of Sale interface.
 
 - **[Render Documentation](./src/projects/render/README.md)**
-- **Features:** Order management, Product catalog, Customer management, Payments, Hardware integration (Cash drawer, Printer).
-
-**Quick Start:**
+- **Features:** Order management, Product catalog, Customer management, Payments, Hardware integration (Cash drawer, Printer), Custom tables, Secrets storage.
 
 ```typescript
 import { RenderClient } from '@final-commerce/command-frame';
 
-// Initialize the client
 const client = new RenderClient();
-
-// Use typed methods
 const products = await client.getProducts();
 ```
 
-### 2. Manage (Dashboard)
+### Manage (Dashboard)
 
 For building applications that run inside the Final Commerce Management Dashboard.
 
 - **[Manage Documentation](./src/projects/manage/README.md)**
-- **Features:** Context information, Dashboard widgets (More coming soon).
-
-**Quick Start:**
+- **Features:** Context information, Dashboard widgets (more coming soon).
 
 ```typescript
 import { ManageClient } from '@final-commerce/command-frame';
@@ -51,6 +52,46 @@ const client = new ManageClient();
 const context = await client.getContext();
 ```
 
+## Pub/Sub
+
+The pub/sub system allows iframe extensions to subscribe to topics and receive real-time events published by the host (Render). Subscriptions are **page-scoped** -- they fire only while the iframe is mounted on the current page.
+
+- **[Pub/Sub Documentation](./src/pubsub/README.md)**
+- **Topics:** Cart (8 events), Customers (6), Orders (2), Payments (2), Products (2), Refunds (2), Print (3).
+
+```typescript
+import { topics } from '@final-commerce/command-frame';
+
+const subscriptionId = topics.subscribe('cart', (event) => {
+    console.log('Cart event:', event.type, event.data);
+});
+
+// Unsubscribe when done
+topics.unsubscribe('cart', subscriptionId);
+```
+
+## Hooks
+
+Hooks are **session-scoped** event callbacks that run in the host (Render) context and persist across all page navigations -- even when the extension iframe is no longer on the current page. Use hooks for business logic that must run on every event (e.g. logging to custom tables, triggering webhooks).
+
+- **[Hooks Documentation](./src/hooks/README.md)**
+- The callback is serialized and sent to the host; it must be **self-contained** (no closures, no imports).
+- A stable `hookId` is required for deduplication (safe on iframe reload).
+
+```typescript
+import { hooks } from '@final-commerce/command-frame';
+
+hooks.register('cart', async (event, hostCommands) => {
+    await hostCommands.upsertCustomTableData({
+        tableName: 'cart-events-log',
+        data: { eventType: event.type, payload: event.data, timestamp: event.timestamp },
+    });
+}, { hookId: 'my-extension:cart-log' });
+
+// Unregister when no longer needed
+hooks.unregister('my-extension:cart-log');
+```
+
 ## Development & Testing
 
 ### Demo Mode / Mocking

package/dist/hooks/index.d.ts

@@ -0,0 +1,17 @@
+import type { HookFunction, HookRegisterOptions } from "./types";
+/**
+ * Register a session-scoped hook. The callback is serialized and sent to the host (Render);
+ * once registered, it runs in the host context even when the extension iframe is not on the current page.
+ * The callback must be self-contained (only use event, hostCommands, callCommand).
+ * Uses options.hookId as a stable dedup key: re-registering with the same hookId replaces the previous hook.
+ */
+declare function register(topic: string, callback: HookFunction, options: HookRegisterOptions): string;
+/**
+ * Unregister a hook by ID. Sends a message to the host to remove the hook.
+ */
+declare function unregister(hookId: string): void;
+export declare const hooks: {
+    register: typeof register;
+    unregister: typeof unregister;
+};
+export type { HookFunction, HookRegisterOptions } from "./types";

package/dist/hooks/index.js

@@ -0,0 +1,39 @@
+const DEFAULT_ORIGIN = "*";
+function getOrigin() {
+    return typeof window !== "undefined" ? window.__COMMAND_FRAME_ORIGIN__ ?? DEFAULT_ORIGIN : DEFAULT_ORIGIN;
+}
+/**
+ * Register a session-scoped hook. The callback is serialized and sent to the host (Render);
+ * once registered, it runs in the host context even when the extension iframe is not on the current page.
+ * The callback must be self-contained (only use event, hostCommands, callCommand).
+ * Uses options.hookId as a stable dedup key: re-registering with the same hookId replaces the previous hook.
+ */
+function register(topic, callback, options) {
+    const hookId = options.hookId;
+    const functionBody = callback.toString();
+    if (typeof window !== "undefined" && window.parent && window.parent !== window) {
+        window.parent.postMessage({
+            type: "hook-register",
+            topic,
+            functionBody,
+            eventTypes: options.eventTypes,
+            hookId
+        }, getOrigin());
+    }
+    return hookId;
+}
+/**
+ * Unregister a hook by ID. Sends a message to the host to remove the hook.
+ */
+function unregister(hookId) {
+    if (typeof window !== "undefined" && window.parent && window.parent !== window) {
+        window.parent.postMessage({
+            type: "hook-unregister",
+            hookId
+        }, getOrigin());
+    }
+}
+export const hooks = {
+    register,
+    unregister
+};

package/dist/hooks/types.d.ts

@@ -0,0 +1,15 @@
+import type { TopicEvent } from "../pubsub/types";
+/**
+ * Function signature for extension hook callbacks.
+ * The function is serialized and sent to the host; it receives event and hostCommands when executed.
+ */
+export type HookFunction = (event: TopicEvent, hostCommands: Record<string, (params?: any) => Promise<any>>, callCommand: (action: string, params?: any) => Promise<any>) => void | Promise<void>;
+/**
+ * Options when registering a hook from the extension iframe.
+ */
+export interface HookRegisterOptions {
+    /** Stable identifier for this hook. Used to deduplicate on reload. Must be unique per hook. */
+    hookId: string;
+    /** Only fire for these event types; omit to receive all events for the topic */
+    eventTypes?: string[];
+}

package/dist/hooks/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -123,7 +123,9 @@ export * from "./projects/manage";
 export { commandFrameClient, CommandFrameClient } from "./client";
 export type { PostMessageRequest, PostMessageResponse } from "./client";
 export { topics } from "./pubsub/topics";
-export type { TopicDefinition, TopicEvent, TopicEventType, TopicSubscriptionCallback, TopicSubscription } from "./pubsub/types";
+export type { TopicDefinition, TopicEvent, TopicEventType, TopicSubscriptionCallback, TopicSubscription, HookCallback, HookOptions, HookRegistration } from "./pubsub/types";
+export { hooks } from "./hooks";
+export type { HookFunction, HookRegisterOptions } from "./hooks";
 export { customersTopic } from "./pubsub/topics/customers";
 export { ordersTopic } from "./pubsub/topics/orders";
 export { refundsTopic } from "./pubsub/topics/refunds";

package/dist/index.js

@@ -161,6 +161,8 @@ export * from "./projects/manage";
 export { commandFrameClient, CommandFrameClient } from "./client";
 // Export Pub/Sub
 export { topics } from "./pubsub/topics";
+// Export Hooks (extension iframe API for session-scoped event callbacks)
+export { hooks } from "./hooks";
 // Export Pub/Sub Topics
 export { customersTopic } from "./pubsub/topics/customers";
 export { ordersTopic } from "./pubsub/topics/orders";

package/dist/pubsub/types.d.ts

@@ -49,3 +49,25 @@ export interface TopicRegistration {
         subscriptionCount: number;
     }[];
 }
+/**
+ * Hook callback function type (host-side, session-scoped)
+ */
+export type HookCallback<T = any> = (event: TopicEvent<T>) => void | Promise<void>;
+/**
+ * Options when registering a host-side hook
+ */
+export interface HookOptions {
+    /** Only fire for these event types; omit to receive all event types for the topic */
+    eventTypes?: string[];
+}
+/**
+ * Single hook registration (stored by TopicPublisher)
+ */
+export interface HookRegistration {
+    id: string;
+    topicId: string;
+    callback: HookCallback;
+    eventTypes?: string[];
+    /** Origin of the iframe that registered this hook (for debugging) */
+    sourceOrigin?: string;
+}

package/package.json

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