@corto-ai/integrations-messenger 0.0.6 → 0.0.8-dev.1

package/README-internal.md

@@ -109,22 +109,40 @@ Buildspec behavior:
 3. Runs `npm run pack:integrations-messenger` and moves the generated `.tgz` into `dist/libs/integrations-messenger/`.
 4. Copies `buildspecs/integrations-messenger-deployspec.yml` into that artifact directory for the deploy stage.
 
-Deployspec derives release mode and dist-tag from `BUILD_ARGS` (`dev`, `test`, `live`).
+Deployspec derives the npm package version and dist-tag from `BUILD_ARGS` (`dev`, `test`, `live`). All environments publish a package version; we no longer promote an existing version by moving dist-tags.
 
-Environment mapping (required values):
+Environment mapping:
 
-1. `dev` -> publish mode with `dev` tag
-2. `test` -> promote mode with `test` tag
-3. `live` -> promote mode with `latest` tag
+1. `dev` -> publishes `{version}-dev.{devVersion}` with `dev` tag
+2. `test` -> publishes `{version}-test.{devVersion}` with `test` tag
+3. `live` -> publishes `{version}` with `latest` tag
+
+`version` and `devVersion` come from `libs/integrations-messenger/package.json`.
+
+Example package metadata:
+
+```json
+{
+  "version": "0.0.8",
+  "devVersion": "1"
+}
+```
+
+Generated npm versions:
+
+1. `dev` -> `0.0.8-dev.1`
+2. `test` -> `0.0.8-test.1`
+3. `live` -> `0.0.8`
 
 Additional deployspec checks/requirements:
 
 1. Package name must be exactly `@corto-ai/integrations-messenger` (validated against `EXPECTED_NAME`).
 2. `NPM_TOKEN` is loaded from SSM Parameter Store path `/FrontEnd/Npm/AuthToken`.
-3. For `publish` mode, deployspec skips publish if the exact version already exists on npm.
-4. For `promote` mode, deployspec fails if the exact version does not already exist on npm.
+3. `devVersion` is required for `dev` and `test` releases.
+4. Deployspec skips publish if the exact generated version already exists on npm.
+5. When publishing, deployspec unpacks the build-created `.tgz`, rewrites only the unpacked `package.json` version, and publishes that unpacked package with the derived tag.
 
-In this flow, publish vs promote and dist-tag are not set manually; they are derived from `BUILD_ARGS`.
+In this flow, `version` and `devVersion` are maintained in package metadata. `BUILD_ARGS` determines how those values are combined into the npm version and which dist-tag is used.
 
 Tag semantics:
 
@@ -134,9 +152,9 @@ Tag semantics:
 
 Examples:
 
-1. Publish `0.0.1` with `dev` -> `dev` points to `0.0.1`.
-2. Publish `0.0.2` with `dev` -> `dev` now points to `0.0.2`.
-3. `0.0.1` still exists and can be installed directly with `@corto-ai/integrations-messenger@0.0.1`.
+1. Publish `0.0.8-dev.1` with `dev` -> `dev` points to `0.0.8-dev.1`.
+2. Publish `0.0.8-dev.2` with `dev` -> `dev` now points to `0.0.8-dev.2`.
+3. `0.0.8-dev.1` still exists and can be installed directly with `@corto-ai/integrations-messenger@0.0.8-dev.1`.
 
 The npm token is loaded from SSM Parameter Store in deployspec:
 
@@ -152,7 +170,7 @@ Current branch strategy:
 This keeps publishing idempotent:
 
 - Re-running deploy on unchanged versions does not republish.
-- Tag updates on `test` and `master-integrations-messenger` are safe to run repeatedly.
+- Existing generated versions are treated as already deployed.
 
 ### Versioning policy
 
@@ -162,4 +180,5 @@ Reason:
 
 1. This package is published to npm, where each new version is immutable.
 2. Forcing version bumps during general CI validation creates unnecessary publishes and burns version numbers without meaningful package changes.
-3. We only increment this package version when there is an actual change to `integrations-messenger` that should be released.
+3. We only increment this package `version` when there is an actual change to `integrations-messenger` that should be released to live.
+4. We increment `devVersion` when a new dev/test prerelease needs to be published for the same base `version`.

package/README.md

@@ -8,8 +8,6 @@ This package is currently in early development and is being published to npm to
 
 This package is intended for teams adding applications into the CORTO platform (for example, iframe-based integrations).
 
-For product information about CORTO, visit <https://www.docorto.ai>.
-
 ## Status
 
 - Early development
@@ -22,18 +20,115 @@ For product information about CORTO, visit <https://www.docorto.ai>.
 npm install @corto-ai/integrations-messenger
 ```
 
+## Capabilities
+
+- **Handshake & identity** -- every window (host or integration) registers itself with a unique `id`. Nested windows automatically perform a handshake with their parent so both sides know who they're talking to before any action is sent.
+- **Origin-checked messaging** -- once the handshake completes, messages from a given source are only accepted if they come from the origin observed during that handshake, protecting against messages from unexpected origins.
+- **Request/response actions** -- typed helpers for the actions below, each with a `send{{Action}}` (caller side) and `handle{{Action}}` (implementer side) pair that resolves once a matching response is received.
+- **Streaming/pubsub notifications** -- a channel-based notification action that can be sent or handled repeatedly, useful for pushing multiple updates over time rather than a single request/response.
+- **Automatic forwarding across nested iframes** -- if a window has no handler registered for an action, the message is forwarded up/down the iframe tree automatically, so multi-level nesting doesn't require every level to implement every action.
+- **Optional debug logging** -- pass `withLogging: true` to `init` to log handshake and message activity to the console while integrating.
+
 ## Usage
 
+### Initialization
+
+Every window that uses this package -- host and embedded integrations alike -- must call `init` first:
+
 ```ts
 import messenger from '@corto-ai/integrations-messenger';
 
 await messenger.init({ id: 'my-integration-app' });
+```
+
+- `id` is required and must be unique for the window calling `init`.
+- `parentRef` is optional and defaults to `window.parent`. Only override it if the page isn't communicating with its direct parent.
+- `withLogging` is optional and enables console logging for debugging the handshake/messaging flow.
+- If the window is nested (its `parentRef` isn't `window` itself), `init` also kicks off the handshake with the parent. `init` resolves once setup is complete; the handshake with the parent finishes asynchronously.
+
+Host applications that embed an integration in an iframe must also call `registerChild` with a reference to the iframe's `contentWindow` and the same `id` the child passed to `init`:
+
+```ts
+messenger.registerChild(iframe.contentWindow, 'my-integration-app');
+```
 
-// Use messenger.actions to send or handle integration actions.
-// Parent apps can also register child windows when needed.
+`registerChild` listens for the handshake from that child and resolves once it completes. Call it before the iframe's own `init` call runs, or the handshake may be missed.
+
+### Actions
+
+`messenger.actions` groups all supported actions by the entity/flow they affect:
+
+| Group      | Action                                                    | Description                                                                                                                        |
+| ---------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `matter`   | `sendOpenMatter` / `handleOpenMatter`                     | Open a matter by `matterId`.                                                                                                       |
+| `matter`   | `sendOpenChatSession` / `handleOpenChatSession`           | Open a specific chat session (`sessionId`) on a matter.                                                                            |
+| `matter`   | `sendOpenAgentSession` / `handleOpenAgentSession`         | Open a specific agent session (`sessionId`) on a matter.                                                                           |
+| `matter`   | `sendOpenDetails` / `handleOpenDetails`                   | Open the details view for a matter.                                                                                                |
+| `matter`   | `sendOpenEdit` / `handleOpenEdit`                         | Open the edit view for a matter.                                                                                                   |
+| `matter`   | `sendOpenDocumentStatus` / `handleOpenDocumentStatus`     | Open the document status view for a matter.                                                                                        |
+| `matter`   | `sendOpenPrompt` / `handleOpenPrompt`                     | Open a specific prompt (`promptId`) on a matter.                                                                                   |
+| `matter`   | `sendOpenPromptLibrary` / `handleOpenPromptLibrary`       | Open the prompt library for a matter.                                                                                              |
+| `matter`   | `sendPreviewDocument` / `handlePreviewDocument`           | Preview a document (`documentId`, `documentName`) on a matter.                                                                     |
+| `contact`  | `sendOpenContact` / `handleOpenContact`                   | Open a contact by `contactId`.                                                                                                     |
+| `contact`  | `sendOpenEditContact` / `handleOpenEditContact`           | Open the edit view for a contact.                                                                                                  |
+| `settings` | `sendOpenSettings` / `handleOpenSettings`                 | Open the host application's settings.                                                                                              |
+| `branding` | `sendGetBranding` / `handleGetBranding`                   | Request the active brand name and logo URL, or pass an optional `brandName` to request a specific brand instead of the active one. |
+| `auth`     | `sendExchangeTokenRequest` / `handleExchangeTokenRequest` | Exchange a `clientId` for an auth token.                                                                                           |
+| `pubsub`   | `sendNotificationRequest` / `handleNotificationRequest`   | Subscribe to (or publish) notifications on a `channel`, supporting multiple responses over time.                                   |
+
+All `matter`, `contact`, and `settings` actions accept an optional `newTab` flag to indicate the host should open the target in a new tab, and `matter` actions also accept an optional `matterId` beyond what's called out above.
+
+For each action, the `send...` function is intended for the embedded integration to call, to ask the host application to perform some action or return some data. The matching `handle...` function is intended to be implemented by the host application: it registers a callback that receives the request and returns the response to send back.
+
+```typescript
+// in the host application
+await messenger.init({ id: 'host' });
+
+messenger.registerChild(iframe.contentWindow, 'child');
+
+messenger.actions.matter.handleOpenChatSession(async ({ matterId, sessionId }) => {
+  try {
+    await someService.openSession(matterId, sessionId);
+    return { success: true };
+  } catch (err) {
+    return { success: false, error: err.message };
+  }
+});
+
+// in the embedded integration
+await messenger.init({ id: 'child' });
+
+const response = await messenger.actions.matter.sendOpenChatSession({
+  matterId: '123',
+  sessionId: 'abc'
+});
+
+if (response.success) {
+  // happy path
+} else {
+  // sad path
+}
 ```
 
-More complete usage examples and API documentation will be added in upcoming releases.
+#### Streaming actions (pubsub)
+
+`pubsub` notifications differ from the other actions: instead of resolving once with a single response, `sendNotificationRequest` and `handleNotificationRequest` can fire their callback multiple times for the same `channel`, and both return a handle with a `remove()` function to stop listening.
+
+```typescript
+// listen for notifications on a channel
+const handle = messenger.actions.pubsub.sendNotificationRequest({ channel: 'documents' }, (notification) => {
+  console.log('received', notification.data);
+});
+
+// later, stop listening
+handle.remove();
+```
+
+### Forwarding
+
+In order to support multiple levels of iframe nesting, the package inherently has a "forwarding" mechanic: for any action, if no handler is defined in a given window, the message continues up or down the iframe tree until a handler picks it up. This is enabled by default and requires no opt-in.
+
+Adding a handler in a child application can shadow the same action's handling in a parent application, since forwarding only happens when a handler isn't defined. If you're not sure whether you should implement a handler for a given action, don't -- let it forward to the host.
 
 ## Demo Repository
 

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@corto-ai/integrations-messenger",
-  "version": "0.0.6",
+  "version": "0.0.8-dev.1",
+  "devVersion": "1",
   "private": false,
   "type": "module",
   "main": "./src/index.js",
@@ -9,4 +10,4 @@
     "tslib": "^2.3.0"
   },
   "module": "./src/index.js"
-}
+}

package/src/lib/models/branding.d.ts

@@ -7,6 +7,5 @@ export declare enum BrandNameEnum {
 }
 export type GetBrandingResponseDTO = ActionResponseBaseDTO & {
     brandName: BrandNameEnum;
-    stylesheetUrl?: string;
     logoUrl?: string;
 };