@final-commerce/command-frame 0.0.7 → 0.1.0

package/README.md

@@ -146,6 +146,342 @@ console.log('Current build:', context.buildName);
 
 For complete usage examples and detailed parameter descriptions, see the documentation for each action in the [Actions Documentation](#actions-documentation) section.
 
+## Pub/Sub System
+
+The library includes a pub/sub system that allows iframe apps to subscribe to topics and receive events published by the host application (Render).
+
+### Quick Start - Pub/Sub
+
+```typescript
+import { topics } from '@final-commerce/command-frame';
+
+// Get available topics
+const availableTopics = await topics.getTopics();
+console.log('Available topics:', availableTopics);
+
+// Subscribe to a topic with a callback
+const subscriptionId = topics.subscribe('customers', (event) => {
+  if (event.type === 'customer-created') {
+    console.log('New customer created:', event.data);
+    // Handle the event
+  }
+});
+
+// Later, unsubscribe when done
+topics.unsubscribe('customers', subscriptionId);
+```
+
+### Pub/Sub API
+
+#### `topics.getTopics()`
+
+Retrieves the list of available topics from the host application.
+
+**Returns:** `Promise<TopicDefinition[]>`
+
+**Example:**
+```typescript
+const topics = await topics.getTopics();
+topics.forEach(topic => {
+  console.log(`Topic: ${topic.name} (${topic.id})`);
+  console.log(`Event types: ${topic.eventTypes.map(et => et.id).join(', ')}`);
+});
+```
+
+#### `topics.subscribe(topic, callback)`
+
+Subscribes to a topic and receives events via the callback function.
+
+**Parameters:**
+- `topic: string` - The topic ID to subscribe to
+- `callback: (event: TopicEvent) => void` - Function called when an event is received
+
+**Returns:** `string` - Subscription ID (use this to unsubscribe)
+
+**Example:**
+```typescript
+const subscriptionId = topics.subscribe('customers', (event) => {
+  console.log('Received event:', event.type);
+  console.log('Event data:', event.data);
+  console.log('Timestamp:', event.timestamp);
+});
+```
+
+#### `topics.unsubscribe(topic, subscriptionId)`
+
+Unsubscribes from a topic using the subscription ID returned from `subscribe()`.
+
+**Parameters:**
+- `topic: string` - The topic ID
+- `subscriptionId: string` - The subscription ID returned from `subscribe()`
+
+**Returns:** `boolean` - `true` if successfully unsubscribed
+
+**Example:**
+```typescript
+const success = topics.unsubscribe('customers', subscriptionId);
+```
+
+#### `topics.unsubscribeAll(topic)`
+
+Unsubscribes all callbacks for a specific topic.
+
+**Parameters:**
+- `topic: string` - The topic ID
+
+**Returns:** `number` - Number of subscriptions removed
+
+**Example:**
+```typescript
+const removed = topics.unsubscribeAll('customers');
+console.log(`Removed ${removed} subscriptions`);
+```
+
+### Topic and Event Types
+
+```typescript
+interface TopicDefinition {
+  id: string;
+  name: string;
+  description?: string;
+  eventTypes: TopicEventType[];
+}
+
+interface TopicEvent<T = any> {
+  topic: string;
+  type: string;
+  data: T;
+  timestamp: string;
+}
+```
+
+### Example: React Component with Pub/Sub
+
+```typescript
+import { useEffect, useState } from 'react';
+import { topics, type TopicEvent } from '@final-commerce/command-frame';
+
+function CustomerEvents() {
+  const [events, setEvents] = useState<TopicEvent[]>([]);
+
+  useEffect(() => {
+    // Subscribe on mount
+    const subscriptionId = topics.subscribe('customers', (event) => {
+      if (event.type === 'customer-created') {
+        setEvents(prev => [event, ...prev]);
+      }
+    });
+
+    // Unsubscribe on unmount
+    return () => {
+      topics.unsubscribe('customers', subscriptionId);
+    };
+  }, []);
+
+  return (
+    <div>
+      <h2>Customer Events ({events.length})</h2>
+      {events.map((event, index) => (
+        <div key={index}>
+          <p>Type: {event.type}</p>
+          <pre>{JSON.stringify(event.data, null, 2)}</pre>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### Available Topics
+
+#### Customers Topic (`customers`)
+
+The customers topic provides events related to customer lifecycle and cart assignment.
+
+**Event Types:**
+
+1. **`customer-created`** - Fired when a new customer is created
+   - **Event Data:**
+     ```typescript
+     {
+       customer: {
+         _id: string;
+         companyId: string;
+         email: string;
+         firstName: string;
+         lastName: string;
+         phone?: string;
+         tags?: string[];
+         metadata?: Record<string, string>[];
+         notes?: CustomerNote[];
+         billing: Address | null;
+         shipping: Address | null;
+         createdAt: string;
+         updatedAt: string;
+         // ... other customer fields
+       }
+     }
+     ```
+
+2. **`customer-updated`** - Fired when a customer's information is updated
+   - **Event Data:**
+     ```typescript
+     {
+       customer: {
+         // Updated customer object with all fields
+       }
+     }
+     ```
+
+3. **`customer-note-added`** - Fired when a note is added to a customer
+   - **Event Data:**
+     ```typescript
+     {
+       customer: {
+         // Customer object with updated notes array
+       },
+       note: {
+         createdAt: string;
+         message: string;
+       }
+     }
+     ```
+
+4. **`customer-note-deleted`** - Fired when a note is deleted from a customer
+   - **Event Data:**
+     ```typescript
+     {
+       customer: {
+         // Customer object with updated notes array
+       },
+       note: {
+         createdAt: string;
+         message: string;
+       }
+     }
+     ```
+
+5. **`customer-assigned`** - Fired when a customer is assigned to the cart
+   - **Event Data:**
+     ```typescript
+     {
+       customer: {
+         // Full customer object
+       }
+     }
+     ```
+
+6. **`customer-unassigned`** - Fired when a customer is unassigned from the cart
+   - **Event Data:**
+     ```typescript
+     {
+       customer: {
+         // Full customer object (before removal)
+       }
+     }
+     ```
+
+**Example: Subscribing to Customer Events**
+
+```typescript
+import { topics, type TopicEvent } from '@final-commerce/command-frame';
+
+// Subscribe to all customer events
+const subscriptionId = topics.subscribe('customers', (event: TopicEvent) => {
+  switch (event.type) {
+    case 'customer-created':
+      console.log('New customer created:', event.data.customer);
+      // Update your customer list, show notification, etc.
+      break;
+    
+    case 'customer-updated':
+      console.log('Customer updated:', event.data.customer);
+      // Refresh customer details in your UI
+      break;
+    
+    case 'customer-note-added':
+      console.log('Note added to customer:', event.data.customer._id);
+      console.log('Note:', event.data.note);
+      // Update customer notes display
+      break;
+    
+    case 'customer-note-deleted':
+      console.log('Note deleted from customer:', event.data.customer._id);
+      // Update customer notes display
+      break;
+    
+    case 'customer-assigned':
+      console.log('Customer assigned to cart:', event.data.customer);
+      // Update cart UI to show customer info
+      break;
+    
+    case 'customer-unassigned':
+      console.log('Customer unassigned from cart:', event.data.customer);
+      // Clear customer info from cart UI
+      break;
+  }
+});
+
+// Later, unsubscribe
+topics.unsubscribe('customers', subscriptionId);
+```
+
+**Example: Filtering Specific Event Types**
+
+```typescript
+import { topics, type TopicEvent } from '@final-commerce/command-frame';
+
+// Only listen for customer assignment/unassignment
+const subscriptionId = topics.subscribe('customers', (event: TopicEvent) => {
+  if (event.type === 'customer-assigned' || event.type === 'customer-unassigned') {
+    console.log(`Customer ${event.type}:`, event.data.customer);
+    // Update your cart UI accordingly
+  }
+});
+```
+
+### Host Application (Render) - Publishing Events
+
+In the Render application, use the `topicPublisher` to publish events:
+
+```typescript
+import { topicPublisher } from '@render/command-frame';
+
+// When a customer is created
+topicPublisher.publish('customers', 'customer-created', {
+  customer: newCustomer
+});
+
+// When a customer is updated
+topicPublisher.publish('customers', 'customer-updated', {
+  customer: updatedCustomer
+});
+
+// When a note is added to a customer
+topicPublisher.publish('customers', 'customer-note-added', {
+  customer: updatedCustomer,
+  note: newNote
+});
+
+// When a note is deleted from a customer
+topicPublisher.publish('customers', 'customer-note-deleted', {
+  customer: updatedCustomer,
+  note: deletedNote
+});
+
+// When a customer is assigned to the cart
+topicPublisher.publish('customers', 'customer-assigned', {
+  customer: customer
+});
+
+// When a customer is unassigned from the cart
+topicPublisher.publish('customers', 'customer-unassigned', {
+  customer: customer
+});
+```
+
+The host application must register topics before they can be used. Topics are registered automatically when the `TopicPublisher` is initialized. See the Render application's pub/sub implementation for details on topic registration.
+
 ## Actions Documentation
 
 Each action has detailed documentation with complete parameter descriptions, response structures, and multiple usage examples:

package/dist/index.d.ts

@@ -108,3 +108,5 @@ export type { TriggerZapierWebhook, TriggerZapierWebhookParams, TriggerZapierWeb
 export * from "./CommonTypes";
 export { commandFrameClient, CommandFrameClient } from "./client";
 export type { PostMessageRequest, PostMessageResponse } from "./client";
+export { topics } from "./pubsub";
+export type { TopicDefinition, TopicEvent, TopicEventType, TopicSubscriptionCallback, TopicSubscription } from "./pubsub/types";

package/dist/index.js

@@ -121,3 +121,5 @@ export const command = {
 export * from "./CommonTypes";
 // Export client
 export { commandFrameClient, CommandFrameClient } from "./client";
+// Export Pub/Sub
+export { topics } from "./pubsub";

package/dist/pubsub/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Pub/Sub module for Command Frame
+ * Provides topic subscription functionality for iframe apps
+ */
+export * from "./types";
+export { TopicSubscriber } from "./subscriber";
+import { TopicSubscriber } from "./subscriber";
+/**
+ * Get or create the singleton TopicSubscriber instance
+ */
+export declare function getTopicSubscriber(options?: {
+    origin?: string;
+    debug?: boolean;
+}): TopicSubscriber;
+/**
+ * Topics API for iframe apps
+ */
+declare const topicsApi: {
+    /**
+     * Subscribe to a topic
+     */
+    subscribe: <T = any>(topic: string, callback: (event: import("./types").TopicEvent<T>) => void) => string;
+    /**
+     * Unsubscribe from a topic
+     */
+    unsubscribe: (topic: string, subscriptionId: string) => boolean;
+    /**
+     * Unsubscribe all callbacks for a topic
+     */
+    unsubscribeAll: (topic: string) => number;
+    /**
+     * Get available topics
+     */
+    getTopics: () => Promise<import("./types").TopicDefinition[]>;
+};
+export { topicsApi as topics };

package/dist/pubsub/index.js

@@ -0,0 +1,52 @@
+/**
+ * Pub/Sub module for Command Frame
+ * Provides topic subscription functionality for iframe apps
+ */
+export * from "./types";
+export { TopicSubscriber } from "./subscriber";
+// Singleton instance
+import { TopicSubscriber } from "./subscriber";
+let subscriberInstance = null;
+/**
+ * Get or create the singleton TopicSubscriber instance
+ */
+export function getTopicSubscriber(options) {
+    if (!subscriberInstance) {
+        subscriberInstance = new TopicSubscriber(options);
+    }
+    return subscriberInstance;
+}
+/**
+ * Topics API for iframe apps
+ */
+const topicsApi = {
+    /**
+     * Subscribe to a topic
+     */
+    subscribe: (topic, callback) => {
+        const subscriber = getTopicSubscriber();
+        return subscriber.subscribe(topic, callback);
+    },
+    /**
+     * Unsubscribe from a topic
+     */
+    unsubscribe: (topic, subscriptionId) => {
+        const subscriber = getTopicSubscriber();
+        return subscriber.unsubscribe(topic, subscriptionId);
+    },
+    /**
+     * Unsubscribe all callbacks for a topic
+     */
+    unsubscribeAll: (topic) => {
+        const subscriber = getTopicSubscriber();
+        return subscriber.unsubscribeAll(topic);
+    },
+    /**
+     * Get available topics
+     */
+    getTopics: async () => {
+        const subscriber = getTopicSubscriber();
+        return await subscriber.getTopics();
+    }
+};
+export { topicsApi as topics };

package/dist/pubsub/subscriber.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Topic Subscriber for iframe communication
+ * Manages subscriptions to topics and receives events from the host window
+ */
+import type { TopicDefinition, TopicSubscriptionCallback } from "./types";
+export declare class TopicSubscriber {
+    private subscriptions;
+    private topics;
+    private origin;
+    private debug;
+    private useGlobalDebug;
+    private boundHandleMessage;
+    private subscriptionIdCounter;
+    constructor(options?: {
+        origin?: string;
+        debug?: boolean;
+    });
+    private isDebugEnabled;
+    /**
+     * Request the list of available topics from the host
+     */
+    private requestTopics;
+    /**
+     * Subscribe to a topic with a callback
+     * Returns a subscription ID that can be used to unsubscribe
+     */
+    subscribe<T = any>(topic: string, callback: TopicSubscriptionCallback<T>): string;
+    /**
+     * Unsubscribe from a topic using subscription ID
+     */
+    unsubscribe(topic: string, subscriptionId: string): boolean;
+    /**
+     * Unsubscribe all callbacks for a topic
+     */
+    unsubscribeAll(topic: string): number;
+    /**
+     * Get list of available topics
+     */
+    getTopics(): Promise<TopicDefinition[]>;
+    /**
+     * Notify host about subscription changes
+     */
+    private notifySubscription;
+    /**
+     * Handle incoming messages from host
+     */
+    private handleMessage;
+    /**
+     * Handle incoming topic event and dispatch to callbacks
+     */
+    private handleTopicEvent;
+    /**
+     * Cleanup and destroy the subscriber
+     */
+    destroy(): void;
+}

package/dist/pubsub/subscriber.js

@@ -0,0 +1,226 @@
+/**
+ * Topic Subscriber for iframe communication
+ * Manages subscriptions to topics and receives events from the host window
+ */
+export class TopicSubscriber {
+    constructor(options = {}) {
+        this.subscriptions = new Map();
+        this.topics = [];
+        this.subscriptionIdCounter = 0;
+        this.origin = options.origin || "*";
+        this.debug = options.debug ?? false;
+        this.useGlobalDebug = options.debug === undefined;
+        // Store bound handler for cleanup
+        this.boundHandleMessage = this.handleMessage.bind(this);
+        if (typeof window !== "undefined") {
+            window.addEventListener("message", this.boundHandleMessage);
+        }
+        // Request topics list on initialization
+        this.requestTopics();
+        if (this.isDebugEnabled()) {
+            console.log("[TopicSubscriber] Initialized", {
+                origin: this.origin,
+                debug: this.isDebugEnabled()
+            });
+        }
+    }
+    isDebugEnabled() {
+        if (!this.useGlobalDebug) {
+            return this.debug;
+        }
+        return typeof window !== "undefined" && window.__POSTMESSAGE_DEBUG__ === true;
+    }
+    /**
+     * Request the list of available topics from the host
+     */
+    requestTopics() {
+        if (typeof window !== "undefined" && window.parent && window.parent !== window) {
+            const message = {
+                type: "pubsub-request-topics",
+                requestId: `topics_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`
+            };
+            if (this.isDebugEnabled()) {
+                console.log("[TopicSubscriber] Requesting topics list", message);
+            }
+            window.parent.postMessage(message, this.origin);
+        }
+    }
+    /**
+     * Subscribe to a topic with a callback
+     * Returns a subscription ID that can be used to unsubscribe
+     */
+    subscribe(topic, callback) {
+        const subscriptionId = `sub_${++this.subscriptionIdCounter}_${Date.now()}`;
+        if (!this.subscriptions.has(topic)) {
+            this.subscriptions.set(topic, []);
+        }
+        const subscription = {
+            id: subscriptionId,
+            topic,
+            callback: callback
+        };
+        this.subscriptions.get(topic).push(subscription);
+        // Notify host about the subscription
+        this.notifySubscription(topic, true);
+        if (this.isDebugEnabled()) {
+            console.log("[TopicSubscriber] Subscribed to topic", {
+                topic,
+                subscriptionId,
+                totalSubscriptions: this.subscriptions.get(topic).length
+            });
+        }
+        return subscriptionId;
+    }
+    /**
+     * Unsubscribe from a topic using subscription ID
+     */
+    unsubscribe(topic, subscriptionId) {
+        const topicSubscriptions = this.subscriptions.get(topic);
+        if (!topicSubscriptions) {
+            if (this.isDebugEnabled()) {
+                console.warn("[TopicSubscriber] Topic not found for unsubscribe", { topic });
+            }
+            return false;
+        }
+        const index = topicSubscriptions.findIndex(sub => sub.id === subscriptionId);
+        if (index === -1) {
+            if (this.isDebugEnabled()) {
+                console.warn("[TopicSubscriber] Subscription ID not found", { topic, subscriptionId });
+            }
+            return false;
+        }
+        topicSubscriptions.splice(index, 1);
+        // If no more subscriptions for this topic, remove it
+        if (topicSubscriptions.length === 0) {
+            this.subscriptions.delete(topic);
+            // Notify host about unsubscription
+            this.notifySubscription(topic, false);
+        }
+        if (this.isDebugEnabled()) {
+            console.log("[TopicSubscriber] Unsubscribed from topic", {
+                topic,
+                subscriptionId,
+                remainingSubscriptions: topicSubscriptions.length
+            });
+        }
+        return true;
+    }
+    /**
+     * Unsubscribe all callbacks for a topic
+     */
+    unsubscribeAll(topic) {
+        const topicSubscriptions = this.subscriptions.get(topic);
+        if (!topicSubscriptions) {
+            return 0;
+        }
+        const count = topicSubscriptions.length;
+        this.subscriptions.delete(topic);
+        this.notifySubscription(topic, false);
+        if (this.isDebugEnabled()) {
+            console.log("[TopicSubscriber] Unsubscribed all from topic", { topic, count });
+        }
+        return count;
+    }
+    /**
+     * Get list of available topics
+     */
+    async getTopics() {
+        // Request fresh topics list
+        this.requestTopics();
+        // Return cached topics (host will send updated list via message)
+        return [...this.topics];
+    }
+    /**
+     * Notify host about subscription changes
+     */
+    notifySubscription(topic, isSubscribed) {
+        if (typeof window !== "undefined" && window.parent && window.parent !== window) {
+            const message = {
+                type: isSubscribed ? "pubsub-subscribe" : "pubsub-unsubscribe",
+                topic,
+                requestId: `sub_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`
+            };
+            if (this.isDebugEnabled()) {
+                console.log("[TopicSubscriber] Notifying subscription change", message);
+            }
+            window.parent.postMessage(message, this.origin);
+        }
+    }
+    /**
+     * Handle incoming messages from host
+     */
+    handleMessage(event) {
+        if (this.origin !== "*" && event.origin !== this.origin) {
+            if (this.isDebugEnabled()) {
+                console.warn("[TopicSubscriber] Origin mismatch", {
+                    expected: this.origin,
+                    received: event.origin
+                });
+            }
+            return;
+        }
+        const data = event.data;
+        // Handle topic event
+        if (data && data.type === "pubsub-event") {
+            const eventMessage = data;
+            this.handleTopicEvent(eventMessage.payload);
+            return;
+        }
+        // Handle topics list
+        if (data && data.type === "pubsub-topics-list") {
+            const topicsMessage = data;
+            this.topics = topicsMessage.payload || [];
+            if (this.isDebugEnabled()) {
+                console.log("[TopicSubscriber] Received topics list", this.topics);
+            }
+            return;
+        }
+    }
+    /**
+     * Handle incoming topic event and dispatch to callbacks
+     */
+    handleTopicEvent(event) {
+        const topicSubscriptions = this.subscriptions.get(event.topic);
+        if (!topicSubscriptions || topicSubscriptions.length === 0) {
+            if (this.isDebugEnabled()) {
+                console.warn("[TopicSubscriber] Received event for topic with no subscriptions", {
+                    topic: event.topic
+                });
+            }
+            return;
+        }
+        if (this.isDebugEnabled()) {
+            console.log("[TopicSubscriber] Dispatching event to callbacks", {
+                topic: event.topic,
+                type: event.type,
+                subscriptionCount: topicSubscriptions.length
+            });
+        }
+        // Call all callbacks for this topic
+        topicSubscriptions.forEach(subscription => {
+            try {
+                subscription.callback(event);
+            }
+            catch (error) {
+                console.error("[TopicSubscriber] Error in subscription callback", {
+                    topic: event.topic,
+                    subscriptionId: subscription.id,
+                    error
+                });
+            }
+        });
+    }
+    /**
+     * Cleanup and destroy the subscriber
+     */
+    destroy() {
+        this.subscriptions.clear();
+        this.topics = [];
+        if (typeof window !== "undefined") {
+            window.removeEventListener("message", this.boundHandleMessage);
+        }
+        if (this.isDebugEnabled()) {
+            console.log("[TopicSubscriber] Destroyed");
+        }
+    }
+}

package/dist/pubsub/types.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Pub/Sub Types for Command Frame
+ * Defines topic and event structures for pub/sub communication
+ */
+/**
+ * Event type definition for a topic
+ */
+export interface TopicEventType {
+    id: string;
+    name: string;
+    description?: string;
+}
+/**
+ * Topic definition with metadata
+ */
+export interface TopicDefinition {
+    id: string;
+    name: string;
+    description?: string;
+    eventTypes: TopicEventType[];
+}
+/**
+ * Event payload structure
+ */
+export interface TopicEvent<T = any> {
+    topic: string;
+    type: string;
+    data: T;
+    timestamp: string;
+}
+/**
+ * Subscription callback function type
+ */
+export type TopicSubscriptionCallback<T = any> = (event: TopicEvent<T>) => void;
+/**
+ * Subscription information
+ */
+export interface TopicSubscription {
+    id: string;
+    topic: string;
+    callback: TopicSubscriptionCallback;
+}

package/dist/pubsub/types.js

@@ -0,0 +1,5 @@
+/**
+ * Pub/Sub Types for Command Frame
+ * Defines topic and event structures for pub/sub communication
+ */
+export {};

package/package.json

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