@contrail/extensions-sdk 1.0.18-3 → 1.0.18-4

package/README.md

@@ -1,35 +1,3 @@
 # Contrail Extensions SDK
 
-Client library for interfacing with VibeIQ's services and apps from an extension. Extensions run in an iframe inside the host (core) app and communicate via postMessage (Penpal).
-
-## Overview
-
-- **Host (core app)**: Embeds the extension in an iframe, passes initial context, and can push events (e.g. showcase frame changed) to the extension.
-- **Extension**: Connects to the host, receives context and events, and can send messages back (e.g. close, or custom commands).
-
-Detailed guides:
-
-- **[Opening the extension](docs/OPENING-THE-EXTENSION.md)** — How the host app loads the extension (iframe + register), and how the extension connects. Includes connection order and when to call each API.
-- **[Messages and events](docs/MESSAGES-AND-EVENTS.md)** — How the host sends events to the extension and how the extension subscribes to them; how the extension sends messages to the host and **how the core app reads those messages** (via `AppExtensionMessageHandler.handleMessage`).
-
-## Quick reference
-
-### Host app (core): open the extension
-
-1. Create an iframe and set its `src` to your extension's URL.
-2. When the iframe has loaded, call `AppExtensionHost.registerHostWithAppExtension(iframe, context, messageHandler)`.
-3. The host can then push updates with `AppExtensionHost.emitEvent({ type, data })`.
-
-### Extension: connect and read messages
-
-1. On your extension's page load, call `await AppExtension.registerAppExtension()` (before any code that needs context).
-2. Use `AppExtension.subscribe(eventType, (data) => { ... })` to react to events from the host.
-3. Use `getAppContext()` for the current app context (and use `getExtensionActions().sendMessageToHost(message)` for custom messages to the host).
-
-## Installation
-
-```bash
-npm install @contrail/extensions-sdk
-```
-
-Requires peer dependency `@contrail/sdk`.
+Client library for interfacing with VibeIQ's services and apps from an extension.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrail/extensions-sdk",
-  "version": "1.0.18-3",
+  "version": "1.0.18-4",
   "description": "Client library for interfacing with VibeIQ's services and apps from an extension.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/docs/MESSAGES-AND-EVENTS.md

@@ -1,176 +0,0 @@
-# Messages and Events
-
-This guide explains how the **core app (host)** sends events to the extension and how the **extension** reads those events and sends messages back to the host.
-
-## Events: host → extension
-
-The host pushes updates to the extension by emitting **events**. The extension subscribes to event types and receives the payload (and optionally the current value immediately).
-
-### Event types
-
-Events are defined by `AppEventType` and carry a `data` payload:
-
-| Event type | Description | `data` shape |
-|------------|-------------|---------------|
-| `SelectedElementsChanged` | Selected elements in the app changed | Selected elements array |
-| `ShowcaseFramesChanged` | List of showcase frames changed | `Frame[]` |
-| `ShowcaseCurrentFrameChanged` | Current showcase frame changed | `Frame` |
-
-(Exact types are in `AppExtensionEvent` and the app-context types from the SDK.)
-
-### Host: emitting events
-
-After the host has called `AppExtensionHost.registerHostWithAppExtension(...)` and the promise has resolved, use:
-
-```ts
-import { AppExtensionHost } from '@contrail/extensions-sdk';
-import { AppEventType } from '@contrail/extensions-sdk';
-
-// Notify the extension that the current frame changed
-AppExtensionHost.emitEvent({
-  type: AppEventType.ShowcaseCurrentFrameChanged,
-  data: newCurrentFrame,
-});
-
-// Notify that the frames list changed
-AppExtensionHost.emitEvent({
-  type: AppEventType.ShowcaseFramesChanged,
-  data: framesArray,
-});
-```
-
-- **When to emit**: Whenever the corresponding state changes in the core app (e.g. user switches frame, selection changes). The extension’s subscribed listeners will be called with the new `data`.
-- **No extension connected**: If the extension is not connected, `emitEvent` is a no-op (the host may log a warning).
-
-### Extension: reading events (subscribe)
-
-In the extension, after `AppExtension.registerAppExtension()` has resolved, subscribe to one or more event types:
-
-```ts
-import { AppExtension, AppEventType } from '@contrail/extensions-sdk';
-
-// Subscribe to current frame changes
-const unsubscribe = AppExtension.subscribe(
-  AppEventType.ShowcaseCurrentFrameChanged,
-  (frame) => {
-    console.log('Current frame:', frame);
-    // Update your UI, load frame-specific data, etc.
-  }
-);
-
-// Subscribe to frames list changes
-AppExtension.subscribe(AppEventType.ShowcaseFramesChanged, (frames) => {
-  console.log('Frames list:', frames);
-});
-
-// Later: remove the first listener
-unsubscribe();
-```
-
-**Behavior:**
-
-- **Immediate callback**: The listener is called once immediately with the **current** value for that event (if the host has already set context or emitted that event). After that, it is called again whenever the host emits that event type.
-- **Return value**: `subscribe` returns an **unsubscribe** function. Call it to stop receiving that listener (e.g. on component destroy).
-
-You can subscribe at any time after `registerAppExtension()` has resolved. If you subscribe before the host has emitted an event, the first call to the listener may still happen with the current value from `getAppContext()` (e.g. from `init(context)`).
-
-### Extension: reading current context without subscribing
-
-For the current app context (user, showcase, plan, board, etc.) without listening for updates:
-
-```ts
-import { getAppContext } from '@contrail/extensions-sdk';
-
-const ctx = getAppContext();
-const showcase = ctx.appContext?.showcase;
-const currentFrame = showcase?.currentFrame;
-```
-
-This is the same context that is updated when the host calls `init(context)` and when the host emits events (the SDK merges event data into the stored context). So after an event, `getAppContext()` reflects the latest state.
-
----
-
-## Messages: extension → host
-
-The extension can send **messages** to the host. The host receives them in the `AppExtensionMessageHandler` it passed to `registerHostWithAppExtension`.
-
-### Message format
-
-Messages are plain objects:
-
-```ts
-interface AppExtensionMessage {
-  command: string;  // e.g. 'close', 'navigate', or a custom command
-  data?: any;       // optional payload
-}
-```
-
-### Extension: sending messages to the host
-
-Use the actions object that the SDK stores after connection. The main entry point for custom host messages is `sendMessageToHost`:
-
-```ts
-import { getExtensionActions } from '@contrail/extensions-sdk';
-
-// Send a message to the host
-getExtensionActions().sendMessageToHost({
-  command: 'close',
-});
-
-// Custom command with data
-getExtensionActions().sendMessageToHost({
-  command: 'navigate',
-  data: { route: '/some-path' },
-});
-```
-
-- **When to use**: For any action that the host must perform (close panel, navigate, open a dialog, etc.). The host implements the behavior in `handleMessage`.
-- **If not connected**: `getExtensionActions()` may be undefined or the methods may no-op if the host has not yet registered. Ensure `registerAppExtension()` has resolved before calling.
-
-### Host: handling messages from the extension
-
-When you call `AppExtensionHost.registerHostWithAppExtension(iframe, context, customMessageHandler)`, the `customMessageHandler` is invoked whenever the extension calls `sendMessageToHost(message)`. Implement `handleMessage` to handle each `command`:
-
-```ts
-const messageHandler: AppExtensionMessageHandler = {
-  async handleMessage(message) {
-    switch (message.command) {
-      case 'close':
-        // Close the extension panel, remove iframe, etc.
-        closeExtensionPanel();
-        break;
-      case 'navigate':
-        router.navigate(message.data?.route ?? '/');
-        break;
-      default:
-        console.warn('Unknown extension command:', message.command);
-    }
-  },
-};
-```
-
-You can return a value from `handleMessage`; the extension’s `sendMessageToHost` returns a Promise that resolves to that value if the host returns it.
-
----
-
-## Other extension → host actions
-
-The SDK also exposes:
-
-- **`close()`** — Convenience: the host can implement this as “close the extension” in its message handler (e.g. when handling `command: 'close'`). The extension can call `AppExtension.close()`, which invokes the host’s `close` action.
-- **`sendMessageToEntitiesClient(message)`** / **`sendMessageToTypesClient(message)`** — For entity/types client actions from the extension. Document these in your own API docs if you use them.
-
-The host provides the implementation for these when it registers (via `ExtensionActions`). The extension gets them from `getExtensionActions()` after `registerAppExtension()` has resolved.
-
----
-
-## Summary
-
-| Direction | Mechanism | Host | Extension |
-|-----------|------------|------|-----------|
-| Host → extension | **Events** | `AppExtensionHost.emitEvent({ type, data })` | `AppExtension.subscribe(eventType, (data) => { ... })` |
-| Host → extension | **Initial context** | Pass `context` in `registerHostWithAppExtension(iframe, context, ...)` | `getAppContext()` after `registerAppExtension()` |
-| Extension → host | **Messages** | Implement `AppExtensionMessageHandler.handleMessage(message)` | `getExtensionActions().sendMessageToHost({ command, data })` |
-| Extension → host | **Close** | Handled in message handler (e.g. `command: 'close'`) or via host’s `close` action | `AppExtension.close()` or `sendMessageToHost({ command: 'close' })` |
-
-For a working setup, the host must [open the extension](OPENING-THE-EXTENSION.md) first; then events and messages can flow as described above.

package/docs/OPENING-THE-EXTENSION.md

@@ -1,154 +0,0 @@
-# Opening the Extension
-
-This guide describes how to **open** (load and connect) an extension from the core app, and what the extension must do to connect back. Both sides must complete their steps for the channel to work.
-
-## 1. Core app (host): load and register the extension
-
-The host app is responsible for embedding the extension and establishing the connection.
-
-### Step 1: Create the iframe
-
-Create an `HTMLIFrameElement` and set its `src` to the URL where your extension app is served (e.g. the extension’s route or deployment URL).
-
-```ts
-const iframe = document.createElement('iframe');
-iframe.src = 'https://your-extension-origin.com/extension'; // Your extension's URL
-iframe.setAttribute('data-penpal-iframe', 'true'); // optional, for Penpal
-document.getElementById('extension-container').appendChild(iframe);
-```
-
-The extension app will load inside this iframe. It must call `AppExtension.registerAppExtension()` when it boots (see “Extension side” below).
-
-### Step 2: Wait for the iframe to load
-
-Before calling the SDK, the iframe content must have loaded so the extension script has run and is waiting for the host. Use the iframe’s `load` event:
-
-```ts
-iframe.addEventListener('load', async () => {
-  // Extension has loaded; now register the host (see Step 3).
-});
-```
-
-If you call `registerHostWithAppExtension` before the iframe has loaded and the extension has called `registerAppExtension()`, the connection will not be established.
-
-### Step 3: Register the host with the extension
-
-Once the iframe has loaded, call `AppExtensionHost.registerHostWithAppExtension` with:
-
-1. **`iframe`** — The same iframe element whose `src` points to the extension.
-2. **`context`** — The initial `AppContext` to inject into the extension (user, app type, plan/board/showcase context, etc.).
-3. **`customMessageHandler`** — An object that implements `AppExtensionMessageHandler` (a `handleMessage(message)` method). This is where the host receives messages **from** the extension (e.g. “close” or custom commands).
-
-```ts
-import { AppExtensionHost } from '@contrail/extensions-sdk';
-import type { AppContext } from '@contrail/extensions-sdk';
-import type { AppExtensionMessageHandler } from '@contrail/extensions-sdk';
-
-const context: AppContext = {
-  appContext: {
-    vibeIQApp: VibeIQAppType.SHOWCASE,
-    showcase: { id: '...', name: '...', orgId: '...', currentFrame: {...}, frames: [...] },
-    // ...
-  },
-  user: currentUser,
-};
-
-const messageHandler: AppExtensionMessageHandler = {
-  async handleMessage(message) {
-    if (message.command === 'close') {
-      // Close the extension panel / iframe.
-    }
-    // Handle other commands...
-  },
-};
-
-await AppExtensionHost.registerHostWithAppExtension(iframe, context, messageHandler);
-// Optional: pass a timeout to fail fast if the extension never connects
-await AppExtensionHost.registerHostWithAppExtension(iframe, context, messageHandler, { timeoutMs: 15000 });
-```
-
-After this promise resolves, the host and extension are connected **and** the extension has received and applied the initial context. Only then should you treat the extension as open (e.g. emit events or show UI). The host can then:
-
-- Call `AppExtensionHost.emitEvent({ type, data })` to push events to the extension.
-- Receive messages from the extension via `messageHandler.handleMessage(message)`.
-
-### Summary: host flow
-
-1. Create iframe, set `iframe.src` to extension URL.
-2. Append iframe to DOM.
-3. On iframe `load`, call `AppExtensionHost.registerHostWithAppExtension(iframe, context, messageHandler)`.
-4. Use `AppExtensionHost.emitEvent(...)` to send events; handle incoming messages in `messageHandler.handleMessage`.
-
----
-
-## 2. Extension: connect and receive context
-
-The extension runs inside the iframe. It must register with the host so that the SDK can receive context and events.
-
-### Step 1: Call `registerAppExtension()` on page load
-
-As early as possible in your extension’s application bootstrap (e.g. in `main.ts`, or the top-level component that mounts the extension UI), call:
-
-```ts
-import { AppExtension } from '@contrail/extensions-sdk';
-
-async function bootstrap() {
-  await AppExtension.registerAppExtension();
-  // Optional: await AppExtension.registerAppExtension({ timeoutMs: 15000 });
-  // Now getAppContext() and subscribe() will work.
-  startYourApp();
-}
-bootstrap();
-```
-
-- This method **must** be called from the extension’s iframe (the same document that the host loads in the iframe).
-- It establishes the postMessage channel with the parent window (the host) and waits for the host to call `registerHostWithAppExtension`. Once the host registers, the extension receives the initial `AppContext` and the promise resolves.
-- Do **not** rely on `getAppContext()` or `AppExtension.subscribe()` before this promise has resolved; the context will be empty and events will not be received until the host has sent `init(context)`.
-
-### Step 2: Use context and subscribe to events
-
-After `registerAppExtension()` has resolved:
-
-- **Context**: Use `getAppContext()` from `@contrail/extensions-sdk` to read the current app context (user, showcase, plan, board, etc.).
-- **Events**: Use `AppExtension.subscribe(eventType, (data) => { ... })` to react to events pushed by the host (e.g. `ShowcaseCurrentFrameChanged`). See [Messages and events](MESSAGES-AND-EVENTS.md).
-
-### Summary: extension flow
-
-1. Extension page loads inside the host’s iframe.
-2. On load, call `await AppExtension.registerAppExtension()` and wait for it to resolve.
-3. After that, use `getAppContext()` and `AppExtension.subscribe(...)` to read context and react to host events.
-
----
-
-## Connection order
-
-For the connection to succeed:
-
-1. Host creates iframe and sets `src` → extension page loads.
-2. Extension script runs and calls `registerAppExtension()` → extension waits for the host.
-3. Host’s iframe fires `load` → host calls `registerHostWithAppExtension(iframe, context, messageHandler)`.
-4. SDK (Penpal) links the two → host’s `init(context)` runs in the extension, then both sides can use `emitEvent` / `subscribe` and the message handler.
-
-If the host registers too early (before the iframe has loaded and the extension has called `registerAppExtension()`), the connection will fail. Always register the host in the iframe’s `load` callback (or an equivalent “extension ready” signal).
-
----
-
-## Troubleshooting: extension won’t open
-
-If the extension never opens or the connection never completes:
-
-1. **Check the iframe URL** — Ensure `iframe.src` points to the correct extension origin and path. Open the URL in a tab and confirm the extension app loads without script errors.
-
-2. **Extension must call `registerAppExtension()` on load** — The extension’s entry point (e.g. `main.ts`) must call `await AppExtension.registerAppExtension()` before any code that uses `getAppContext()` or `subscribe()`. If your app bootstraps Angular or other services first, they may run before context is available; consider awaiting `registerAppExtension()` before bootstrapping.
-
-3. **Host must register after the iframe has loaded** — Call `registerHostWithAppExtension(...)` inside the iframe’s `load` event (or after you know the extension script has run). If you call it before the extension has called `registerAppExtension()`, the host will wait indefinitely unless you use `timeoutMs`.
-
-4. **Use optional timeout** — Pass `{ timeoutMs: 15000 }` (or similar) as the fourth argument to `registerHostWithAppExtension`, or `{ timeoutMs: 15000 }` to `registerAppExtension()`. If the other side doesn’t connect in time, you’ll get `HostConnectionTimeoutError` or `ExtensionConnectionTimeoutError` instead of hanging.
-
-5. **Check the console** — Look for Penpal or SDK errors in both the host and the extension (inspect the iframe’s context in devtools). Common issues: wrong origin, script errors in the extension before `registerAppExtension()` runs, or the host never calling `registerHostWithAppExtension`.
-
-6. **Await `registerHostWithAppExtension`** — The host should `await` the call and only then consider the extension “open” and emit events. The promise resolves after the extension has received and applied the initial context.
-
----
-
-**Next:** To send events to the extension and **read messages from the extension** in the core app, see [Messages and events](MESSAGES-AND-EVENTS.md).