@contrail/extensions-sdk 1.0.18-5 → 1.0.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrail/extensions-sdk",
-  "version": "1.0.18-5",
+  "version": "1.0.18",
   "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/EXTENSION_SDK_GUIDE.md

@@ -1,183 +0,0 @@
-# Extension SDK Guide
-
-This guide explains how the Contrail Extensions SDK works, how the **host app** (Boards, Showcase, Plan) establishes the connection and passes context, and how **external developers** write extensions that consume that context.
-
----
-
-## How context works
-
-The host sends the full `AppContext` **once** over the Penpal connection when it calls `init(context)` after the extension registers. The extension receives it during `registerAppExtension()` and can read it at any time via `getAppContext()`. There is no real-time context update mechanism; the extension only has the snapshot provided at initialization.
-
----
-
-## For the Host App: Establishing the Connection
-
-The host app is responsible for loading the extension in an iframe, registering with the SDK, and passing the initial context.
-
-### 1. Install and import the SDK
-
-```ts
-import {
-  AppExtensionHost,
-  AppContext,
-  AppExtensionMessage,
-  AppExtensionMessageHandler,
-} from '@contrail/extensions-sdk'; // or your package name
-```
-
-### 2. Create the extension iframe
-
-Create an `HTMLIFrameElement` that loads your extension's entry URL (e.g. the built extension app). The extension script inside the iframe will call `AppExtension.registerAppExtension()` and use Penpal to connect to the parent.
-
-### 3. Implement the message handler
-
-The host must implement `AppExtensionMessageHandler` to handle commands from the extension (e.g. close, custom commands):
-
-```ts
-const messageHandler: AppExtensionMessageHandler = {
-  async handleMessage(message: AppExtensionMessage): Promise<unknown> {
-    switch (message.command) {
-      case 'close':
-        // Close the extension panel or navigate away
-        break;
-      // Handle other commands your extension sends via sendMessageToHost()
-      default:
-        break;
-    }
-    return undefined;
-  },
-};
-```
-
-### 4. Build initial context and register with the extension
-
-Gather the `AppContext` (user, app type, board/plan/showcase snapshot, etc.) and call `registerHostWithAppExtension`. This establishes the Penpal connection and sends the context once via `init(context)`.
-
-```ts
-const iframe = document.querySelector('iframe#extension') as HTMLIFrameElement;
-const context: AppContext = {
-  user: currentUser,
-  appContext: {
-    vibeIQApp: VibeIQAppType.SHOWCASE,
-    showcase: {
-      id: showcase.id,
-      name: showcase.name,
-      orgId: showcase.orgId,
-      currentFrame: activeFrame,
-      frames: showcase.frames,
-      // ... other fields
-    },
-    // board, plan, selectedElements, etc. as needed
-  },
-};
-
-await AppExtensionHost.registerHostWithAppExtension(iframe, context, messageHandler);
-// Connection is ready. The extension has received context via init().
-```
-
-The extension receives this context once at init. If the host needs to change what the extension sees (e.g. after navigating to a different showcase or frame), it would need to re-load or re-initialize the extension with new context; the SDK does not support pushing context updates after init.
-
----
-
-## For Extension Developers: Writing an Extension
-
-Extensions run inside an iframe loaded by the host. They use the SDK to register with the host and read the context that was passed at initialization.
-
-### 1. Install and import the SDK
-
-```ts
-import {
-  AppExtension,
-  getAppContext,
-  VibeIQAppType,
-} from '@contrail/extensions-sdk';
-```
-
-### 2. Register the extension on load
-
-Your extension entry point (e.g. main.tsx or main.ts) must call `AppExtension.registerAppExtension()` and wait for it. This sets up the Penpal connection and waits for the host to call `init(context)`.
-
-```ts
-// In your extension's bootstrap (e.g. main.tsx)
-async function bootstrap() {
-  await AppExtension.registerAppExtension();
-  // Connection is ready. Initial context is set.
-  // Mount your app (e.g. React root).
-}
-
-bootstrap().catch(console.error);
-```
-
-Do not render your UI or depend on context until `registerAppExtension()` has resolved. The host calls `init(context)` once; that is the only time context is provided.
-
-### 3. Read context
-
-Use `getAppContext()` to read the context snapshot that was passed at init:
-
-```ts
-const context = getAppContext();
-
-if (context.appContext?.vibeIQApp === VibeIQAppType.SHOWCASE) {
-  const showcase = context.appContext.showcase;
-  const currentFrame = showcase?.currentFrame;
-  const frames = showcase?.frames;
-}
-
-const selectedElements = context.appContext?.selectedElements ?? [];
-```
-
-This context does not change after init. The extension only has the snapshot the host provided when the connection was established.
-
-### 4. Showcase context
-
-When the host app is Showcase (or includes showcase in context), the host includes `showcase` in the `AppContext` passed to `registerHostWithAppExtension` / `init(context)`. The extension reads it via `getAppContext().appContext?.showcase` (e.g. `currentFrame`, `frames`). There is no API to receive showcase updates after init; the extension works with the initial snapshot.
-
-### 5. Sending messages to the host
-
-Use the SDK APIs that talk to the host over the Penpal connection:
-
-```ts
-// Close the extension (host handles in messageHandler)
-AppExtension.close();
-```
-
-For app-specific commands (e.g. Board or Plan actions), use the SDK's app modules (e.g. `Boards`, `Plan`), which send messages to the host internally. Custom commands can be sent via those modules or whatever host-messaging API your SDK exposes; the host receives them in `messageHandler.handleMessage`.
-
-### 6. Clipboard: bulk add items
-
-Extensions can request that the host bulk-add items to the user's clipboard by sending a message with a list of `{ itemId, projectItemId }`. The host dispatches its existing clipboard store action; there is no success or error response unless the host adds one later.
-
-**Board:** Use `BoardsApp.addItemsToClipboard(clipboardItems)`:
-
-```ts
-import { BoardsApp } from '@contrail/extensions-sdk';
-
-BoardsApp.addItemsToClipboard([
-  { itemId: 'item-1', projectItemId: 'proj-1' },
-  { itemId: 'item-2', projectItemId: null },
-]);
-```
-
-You can also send the command explicitly with `command: BoardCommand.ADD_ITEMS_TO_CLIPBOARD` and `data: { clipboardItems }` via your extension's host message channel.
-
-**Showcase:** Use `ShowcaseApp.addItemsToClipboard(clipboardItems)`:
-
-```ts
-import { ShowcaseApp } from '@contrail/extensions-sdk';
-
-ShowcaseApp.addItemsToClipboard([
-  { itemId: 'item-1', projectItemId: 'proj-1' },
-  { itemId: 'item-2', projectItemId: null },
-]);
-```
-
-You can also send the command explicitly with `command: ShowcaseCommand.ADD_ITEMS_TO_CLIPBOARD` and `data: { clipboardItems }` via your extension's host message channel.
-
-**Payload:** `clipboardItems: Array<{ itemId: string; projectItemId?: string | null }>`. The host normalizes and dispatches its existing clipboard action; no new API or store logic is required on the host.
-
----
-
-## Summary
-
-- **Host:** Load extension iframe → build `AppContext` → call `AppExtensionHost.registerHostWithAppExtension(iframe, context, messageHandler)`. Context is sent once via `init(context)`; there is no API to push context updates after that.
-- **Extension:** Call `AppExtension.registerAppExtension()` at startup → use `getAppContext()` to read the context snapshot received at init. Showcase and other app data are available under `getAppContext().appContext` (e.g. `appContext.showcase`).