@or-sdk/idw-skill 1.1.0-beta.4024.0

package/README.md

@@ -0,0 +1,142 @@
+# Communication Protocol Specification: IDW & Web Skills (v1.0)
+
+## 1. Overview
+This document defines the formal messaging protocol for secure, asynchronous communication between the **Intelligent Digital Workforce (IDW)** (Host) and **Web Skills** (Guest) using the HTML5 `postMessage` API.
+
+---
+
+## 2. Terminology
+* **IDW:** Intelligent Digital Workforce (The Host environment).
+* **Skill:** The Web Skill/Micro-app running in an iframe (The Guest).
+* **Event:** A structured object sent via `postMessage`. The term "Event" is used to distinguish protocol actions from chat messages.
+
+---
+
+## 3. Event Structure
+All communication must implement the `IdwEvent` interface.
+
+```typescript
+
+interface IdwInitPayload {
+  orToken: string;
+  settings: {
+    id: string;
+    name: string;
+    slug: string;
+    accountId: string;
+    isPrivate: boolean;
+  }
+  user?: {
+    role: string;
+    userId: string; // UUID format
+    contactId: string; // UUID format
+    email: string;
+    firstName: string;
+    lastName: string;
+    avatarUrl: string;
+    phoneNumber: string;
+  }
+  inputParams?: {
+    [key: string]: unknown;
+  }
+}
+
+interface SkillResultPayload {
+  data: unknown;
+  [key: string]: unknown;
+}
+
+interface SkillErrorPayload {
+  code: string;
+  message: string;
+  details?: unknown;
+}
+
+interface IdwEventMap {
+  /** Delivers initial configuration to the Skill */
+  "idw:init": IdwInitPayload;
+
+  /** Used by the Skill to trigger initialization flow */
+  "skill:init:request": undefined;
+
+  /** Signal that the Skill is interactive */
+  "skill:ready": undefined;
+
+  /** Delivery of data/outcome back to the IDW */
+  "skill:result": SkillResultPayload;
+
+  /** Standardized error reporting */
+  "skill:error": SkillErrorPayload;
+}
+
+interface IdwEvent<K extends keyof IdwEventMap> {
+  /** Protocol version (e.g., "1.0") */
+  version: "1.0";
+  
+  /** * Event identifier using the 'namespace:action' convention.
+   * Namespaces: 'idw:' for Host, 'skill:' for Guest.
+   */
+  type: K;
+  
+  /** Optional UUID to track request-response pairs */
+  requestId?: string;
+  
+  /** The data payload relevant to the event type */
+  payload: IdwEventMap[K];
+}
+```
+
+---
+
+## 4. Initialization Lifecycle (Pull-based Handshake)
+To ensure the Skill is fully loaded and listening before data is sent, the Skill initiates the handshake.
+
+| Step | Sender | Event Type | Description |
+| :--- | :--- | :--- | :--- |
+| 1 | **Skill** | `skill:init:request` | Skill has loaded its JS and is ready to receive config. |
+| 2 | **IDW** | `idw:init` | IDW provides initial context, tokens, and settings. |
+| 3 | **Skill** | `skill:ready` | Skill confirms initialization is complete and UI is ready. |
+
+---
+
+## 5. Event Naming & Required Types
+
+### Required Events
+* `skill:init:request`: Used by the Skill to trigger the initialization flow.
+* `idw:init`: Delivers initial configuration to the Skill.
+* `skill:ready`: Signal that the Skill is interactive.
+* `skill:result`: Delivery of data/outcome back to the IDW.
+* `skill:error`: Standardized error reporting.
+
+---
+
+## 6. Security & Origin Validation
+To prevent unauthorized access or data leakage, the following measures are mandatory:
+
+* **Target Origin:** Never use `postMessage(data, '*')`. Always specify the exact target origin of the recipient.
+* **Payload Sanitization:** Treat all `payload` data as untrusted and validate it before use.
+
+---
+
+## 7. Error Handling
+Errors from the Skill should be communicated to the IDW using a consistent format.
+
+**Example `skill:error` Payload:**
+```json
+{
+  "version": "1.0",
+  "type": "skill:error",
+  "requestId": "abc-123",
+  "payload": {
+    "code": "VALIDATION_FAILED",
+    "message": "Required field 'userId' is missing.",
+    "retryable": false
+  }
+}
+```
+
+---
+
+## 8. Versioning
+* **Version Field:** Every event must include the `"version": "1.0"` string.
+* **Breaking Changes:** Any change that breaks backward compatibility will increment the major version to `2.0`.

package/dist/cjs/IdwSkill.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdwSkill = void 0;
+var types_1 = require("./types");
+var PROTOCOL_VERSION = '1.0';
+var IdwSkill = (function () {
+    function IdwSkill(params) {
+        this._initData = null;
+        var targetOrigin = params.targetOrigin;
+        if (!targetOrigin) {
+            throw new Error('targetOrigin is required');
+        }
+        this.targetOrigin = targetOrigin;
+    }
+    Object.defineProperty(IdwSkill.prototype, "orToken", {
+        get: function () {
+            var _a, _b;
+            return (_b = (_a = this._initData) === null || _a === void 0 ? void 0 : _a.orToken) !== null && _b !== void 0 ? _b : null;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    Object.defineProperty(IdwSkill.prototype, "initData", {
+        get: function () {
+            return this._initData;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    IdwSkill.prototype.init = function () {
+        var _this = this;
+        return new Promise(function (resolve) {
+            var handleMessage = function (event) {
+                if (event.origin !== _this.targetOrigin) {
+                    return;
+                }
+                var data = event.data;
+                if ((data === null || data === void 0 ? void 0 : data.version) === PROTOCOL_VERSION && (data === null || data === void 0 ? void 0 : data.type) === types_1.IdwEventType.Init) {
+                    window.removeEventListener('message', handleMessage);
+                    _this._initData = data.payload;
+                    resolve(data.payload);
+                }
+            };
+            window.addEventListener('message', handleMessage);
+            _this.postMessage({
+                version: PROTOCOL_VERSION,
+                type: types_1.IdwEventType.SkillInitRequest,
+                payload: undefined,
+            });
+        });
+    };
+    IdwSkill.prototype.ready = function (requestId) {
+        this.postMessage({
+            version: PROTOCOL_VERSION,
+            type: types_1.IdwEventType.SkillReady,
+            requestId: requestId,
+            payload: undefined,
+        });
+    };
+    IdwSkill.prototype.sendResult = function (payload, requestId) {
+        this.postMessage({
+            version: PROTOCOL_VERSION,
+            type: types_1.IdwEventType.SkillResult,
+            requestId: requestId,
+            payload: payload,
+        });
+    };
+    IdwSkill.prototype.sendError = function (payload, requestId) {
+        this.postMessage({
+            version: PROTOCOL_VERSION,
+            type: types_1.IdwEventType.SkillError,
+            requestId: requestId,
+            payload: payload,
+        });
+    };
+    IdwSkill.prototype.postMessage = function (event) {
+        window.parent.postMessage(event, this.targetOrigin);
+    };
+    return IdwSkill;
+}());
+exports.IdwSkill = IdwSkill;
+//# sourceMappingURL=IdwSkill.js.map

package/dist/cjs/IdwSkill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IdwSkill.js","sourceRoot":"","sources":["../../src/IdwSkill.ts"],"names":[],"mappings":";;;AAAA,iCASiB;AAEjB,IAAM,gBAAgB,GAAoB,KAAK,CAAC;AAyBhD;IAIE,kBAAY,MAAsB;QAF1B,cAAS,GAA0B,IAAI,CAAC;QAGtC,IAAA,YAAY,GAAK,MAAM,aAAX,CAAY;QAEhC,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;QAC9C,CAAC;QAED,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACnC,CAAC;IAGD,sBAAI,6BAAO;aAAX;;YACE,OAAO,MAAA,MAAA,IAAI,CAAC,SAAS,0CAAE,OAAO,mCAAI,IAAI,CAAC;QACzC,CAAC;;;OAAA;IAGD,sBAAI,8BAAQ;aAAZ;YACE,OAAO,IAAI,CAAC,SAAS,CAAC;QACxB,CAAC;;;OAAA;IASD,uBAAI,GAAJ;QAAA,iBAwBC;QAvBC,OAAO,IAAI,OAAO,CAAC,UAAC,OAAO;YACzB,IAAM,aAAa,GAAG,UAAC,KAAmB;gBACxC,IAAI,KAAK,CAAC,MAAM,KAAK,KAAI,CAAC,YAAY,EAAE,CAAC;oBACvC,OAAO;gBACT,CAAC;gBAED,IAAM,IAAI,GAAG,KAAK,CAAC,IAAmC,CAAC;gBAEvD,IAAI,CAAA,IAAI,aAAJ,IAAI,uBAAJ,IAAI,CAAE,OAAO,MAAK,gBAAgB,IAAI,CAAA,IAAI,aAAJ,IAAI,uBAAJ,IAAI,CAAE,IAAI,MAAK,oBAAY,CAAC,IAAI,EAAE,CAAC;oBAC3E,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;oBACrD,KAAI,CAAC,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC;oBAC9B,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACxB,CAAC;YACH,CAAC,CAAC;YAEF,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;YAElD,KAAI,CAAC,WAAW,CAAgC;gBAC9C,OAAO,EAAE,gBAAgB;gBACzB,IAAI,EAAE,oBAAY,CAAC,gBAAgB;gBACnC,OAAO,EAAE,SAAS;aACnB,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;IAQD,wBAAK,GAAL,UAAM,SAAkB;QACtB,IAAI,CAAC,WAAW,CAA0B;YACxC,OAAO,EAAE,gBAAgB;YACzB,IAAI,EAAE,oBAAY,CAAC,UAAU;YAC7B,SAAS,WAAA;YACT,OAAO,EAAE,SAAS;SACnB,CAAC,CAAC;IACL,CAAC;IAQD,6BAAU,GAAV,UAAW,OAA2B,EAAE,SAAkB;QACxD,IAAI,CAAC,WAAW,CAA2B;YACzC,OAAO,EAAE,gBAAgB;YACzB,IAAI,EAAE,oBAAY,CAAC,WAAW;YAC9B,SAAS,WAAA;YACT,OAAO,SAAA;SACR,CAAC,CAAC;IACL,CAAC;IAQD,4BAAS,GAAT,UAAU,OAA0B,EAAE,SAAkB;QACtD,IAAI,CAAC,WAAW,CAA0B;YACxC,OAAO,EAAE,gBAAgB;YACzB,IAAI,EAAE,oBAAY,CAAC,UAAU;YAC7B,SAAS,WAAA;YACT,OAAO,SAAA;SACR,CAAC,CAAC;IACL,CAAC;IAEO,8BAAW,GAAnB,UAAiD,KAAkB;QACjE,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;IACtD,CAAC;IACH,eAAC;AAAD,CAAC,AAzGD,IAyGC;AAzGY,4BAAQ"}

package/dist/cjs/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdwSkill = void 0;
+var IdwSkill_1 = require("./IdwSkill");
+Object.defineProperty(exports, "IdwSkill", { enumerable: true, get: function () { return IdwSkill_1.IdwSkill; } });
+__exportStar(require("./types"), exports);
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,uCAAsC;AAA7B,oGAAA,QAAQ,OAAA;AACjB,0CAAwB"}

package/dist/cjs/types.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdwEventType = void 0;
+var IdwEventType;
+(function (IdwEventType) {
+    IdwEventType["SkillInitRequest"] = "skill:init:request";
+    IdwEventType["Init"] = "idw:init";
+    IdwEventType["SkillReady"] = "skill:ready";
+    IdwEventType["SkillResult"] = "skill:result";
+    IdwEventType["SkillError"] = "skill:error";
+})(IdwEventType || (exports.IdwEventType = IdwEventType = {}));
+//# sourceMappingURL=types.js.map

package/dist/cjs/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":";;;AAmDA,IAAY,YAWX;AAXD,WAAY,YAAY;IAEtB,uDAAuC,CAAA;IAEvC,iCAAiB,CAAA;IAEjB,0CAA0B,CAAA;IAE1B,4CAA4B,CAAA;IAE5B,0CAA0B,CAAA;AAC5B,CAAC,EAXW,YAAY,4BAAZ,YAAY,QAWvB"}

package/dist/esm/IdwSkill.js

@@ -0,0 +1,68 @@
+import { IdwEventType, } from './types';
+const PROTOCOL_VERSION = '1.0';
+export class IdwSkill {
+    constructor(params) {
+        this._initData = null;
+        const { targetOrigin } = params;
+        if (!targetOrigin) {
+            throw new Error('targetOrigin is required');
+        }
+        this.targetOrigin = targetOrigin;
+    }
+    get orToken() {
+        var _a, _b;
+        return (_b = (_a = this._initData) === null || _a === void 0 ? void 0 : _a.orToken) !== null && _b !== void 0 ? _b : null;
+    }
+    get initData() {
+        return this._initData;
+    }
+    init() {
+        return new Promise((resolve) => {
+            const handleMessage = (event) => {
+                if (event.origin !== this.targetOrigin) {
+                    return;
+                }
+                const data = event.data;
+                if ((data === null || data === void 0 ? void 0 : data.version) === PROTOCOL_VERSION && (data === null || data === void 0 ? void 0 : data.type) === IdwEventType.Init) {
+                    window.removeEventListener('message', handleMessage);
+                    this._initData = data.payload;
+                    resolve(data.payload);
+                }
+            };
+            window.addEventListener('message', handleMessage);
+            this.postMessage({
+                version: PROTOCOL_VERSION,
+                type: IdwEventType.SkillInitRequest,
+                payload: undefined,
+            });
+        });
+    }
+    ready(requestId) {
+        this.postMessage({
+            version: PROTOCOL_VERSION,
+            type: IdwEventType.SkillReady,
+            requestId,
+            payload: undefined,
+        });
+    }
+    sendResult(payload, requestId) {
+        this.postMessage({
+            version: PROTOCOL_VERSION,
+            type: IdwEventType.SkillResult,
+            requestId,
+            payload,
+        });
+    }
+    sendError(payload, requestId) {
+        this.postMessage({
+            version: PROTOCOL_VERSION,
+            type: IdwEventType.SkillError,
+            requestId,
+            payload,
+        });
+    }
+    postMessage(event) {
+        window.parent.postMessage(event, this.targetOrigin);
+    }
+}
+//# sourceMappingURL=IdwSkill.js.map

package/dist/esm/IdwSkill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IdwSkill.js","sourceRoot":"","sources":["../../src/IdwSkill.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,YAAY,GAMb,MAAM,SAAS,CAAC;AAEjB,MAAM,gBAAgB,GAAoB,KAAK,CAAC;AAyBhD,MAAM,OAAO,QAAQ;IAInB,YAAY,MAAsB;QAF1B,cAAS,GAA0B,IAAI,CAAC;QAG9C,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,CAAC;QAEhC,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;QAC9C,CAAC;QAED,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACnC,CAAC;IAGD,IAAI,OAAO;;QACT,OAAO,MAAA,MAAA,IAAI,CAAC,SAAS,0CAAE,OAAO,mCAAI,IAAI,CAAC;IACzC,CAAC;IAGD,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IASD,IAAI;QACF,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YAC7B,MAAM,aAAa,GAAG,CAAC,KAAmB,EAAE,EAAE;gBAC5C,IAAI,KAAK,CAAC,MAAM,KAAK,IAAI,CAAC,YAAY,EAAE,CAAC;oBACvC,OAAO;gBACT,CAAC;gBAED,MAAM,IAAI,GAAG,KAAK,CAAC,IAAmC,CAAC;gBAEvD,IAAI,CAAA,IAAI,aAAJ,IAAI,uBAAJ,IAAI,CAAE,OAAO,MAAK,gBAAgB,IAAI,CAAA,IAAI,aAAJ,IAAI,uBAAJ,IAAI,CAAE,IAAI,MAAK,YAAY,CAAC,IAAI,EAAE,CAAC;oBAC3E,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;oBACrD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC;oBAC9B,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACxB,CAAC;YACH,CAAC,CAAC;YAEF,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;YAElD,IAAI,CAAC,WAAW,CAAgC;gBAC9C,OAAO,EAAE,gBAAgB;gBACzB,IAAI,EAAE,YAAY,CAAC,gBAAgB;gBACnC,OAAO,EAAE,SAAS;aACnB,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;IAQD,KAAK,CAAC,SAAkB;QACtB,IAAI,CAAC,WAAW,CAA0B;YACxC,OAAO,EAAE,gBAAgB;YACzB,IAAI,EAAE,YAAY,CAAC,UAAU;YAC7B,SAAS;YACT,OAAO,EAAE,SAAS;SACnB,CAAC,CAAC;IACL,CAAC;IAQD,UAAU,CAAC,OAA2B,EAAE,SAAkB;QACxD,IAAI,CAAC,WAAW,CAA2B;YACzC,OAAO,EAAE,gBAAgB;YACzB,IAAI,EAAE,YAAY,CAAC,WAAW;YAC9B,SAAS;YACT,OAAO;SACR,CAAC,CAAC;IACL,CAAC;IAQD,SAAS,CAAC,OAA0B,EAAE,SAAkB;QACtD,IAAI,CAAC,WAAW,CAA0B;YACxC,OAAO,EAAE,gBAAgB;YACzB,IAAI,EAAE,YAAY,CAAC,UAAU;YAC7B,SAAS;YACT,OAAO;SACR,CAAC,CAAC;IACL,CAAC;IAEO,WAAW,CAA8B,KAAkB;QACjE,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;IACtD,CAAC;CACF"}

package/dist/esm/index.js

@@ -0,0 +1,3 @@
+export { IdwSkill } from './IdwSkill';
+export * from './types';
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,cAAc,SAAS,CAAC"}

package/dist/esm/types.js

@@ -0,0 +1,9 @@
+export var IdwEventType;
+(function (IdwEventType) {
+    IdwEventType["SkillInitRequest"] = "skill:init:request";
+    IdwEventType["Init"] = "idw:init";
+    IdwEventType["SkillReady"] = "skill:ready";
+    IdwEventType["SkillResult"] = "skill:result";
+    IdwEventType["SkillError"] = "skill:error";
+})(IdwEventType || (IdwEventType = {}));
+//# sourceMappingURL=types.js.map

package/dist/esm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAmDA,MAAM,CAAN,IAAY,YAWX;AAXD,WAAY,YAAY;IAEtB,uDAAuC,CAAA;IAEvC,iCAAiB,CAAA;IAEjB,0CAA0B,CAAA;IAE1B,4CAA4B,CAAA;IAE5B,0CAA0B,CAAA;AAC5B,CAAC,EAXW,YAAY,KAAZ,YAAY,QAWvB"}

package/dist/types/IdwSkill.d.ts

@@ -0,0 +1,14 @@
+import { IdwInitPayload, IdwSkillConfig, SkillErrorPayload, SkillResultPayload } from './types';
+export declare class IdwSkill {
+    private readonly targetOrigin;
+    private _initData;
+    constructor(params: IdwSkillConfig);
+    get orToken(): string | null;
+    get initData(): IdwInitPayload | null;
+    init(): Promise<IdwInitPayload>;
+    ready(requestId?: string): void;
+    sendResult(payload: SkillResultPayload, requestId?: string): void;
+    sendError(payload: SkillErrorPayload, requestId?: string): void;
+    private postMessage;
+}
+//# sourceMappingURL=IdwSkill.d.ts.map

package/dist/types/IdwSkill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IdwSkill.d.ts","sourceRoot":"","sources":["../../src/IdwSkill.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,cAAc,EACd,cAAc,EAEd,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,SAAS,CAAC;AA2BjB,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,SAAS,CAA+B;gBAEpC,MAAM,EAAE,cAAc;IAWlC,IAAI,OAAO,IAAI,MAAM,GAAG,IAAI,CAE3B;IAGD,IAAI,QAAQ,IAAI,cAAc,GAAG,IAAI,CAEpC;IASD,IAAI,IAAI,OAAO,CAAC,cAAc,CAAC;IAgC/B,KAAK,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;IAe/B,UAAU,CAAC,OAAO,EAAE,kBAAkB,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;IAejE,SAAS,CAAC,OAAO,EAAE,iBAAiB,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;IAS/D,OAAO,CAAC,WAAW;CAGpB"}

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export { IdwSkill } from './IdwSkill';
+export * from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,cAAc,SAAS,CAAC"}

package/dist/types/types.d.ts

@@ -0,0 +1,57 @@
+export type ProtocolVersion = '1.0';
+export type IdwSkillConfig = {
+    targetOrigin: string;
+};
+export interface IdwSkillSettings {
+    id: string;
+    name: string;
+    slug: string;
+    accountId: string;
+    isPrivate: boolean;
+}
+export interface IdwSkillUser {
+    role: string;
+    userId: string;
+    contactId: string;
+    email: string;
+    firstName: string;
+    lastName: string;
+    avatarUrl: string;
+    phoneNumber: string;
+}
+export interface IdwInitPayload {
+    orToken: string;
+    settings: IdwSkillSettings;
+    user?: IdwSkillUser;
+    inputParams?: Record<string, unknown>;
+}
+export interface SkillResultPayload {
+    data: unknown;
+    [key: string]: unknown;
+}
+export interface SkillErrorPayload {
+    code: string;
+    message: string;
+    details?: unknown;
+}
+export declare enum IdwEventType {
+    SkillInitRequest = "skill:init:request",
+    Init = "idw:init",
+    SkillReady = "skill:ready",
+    SkillResult = "skill:result",
+    SkillError = "skill:error"
+}
+export interface IdwEventMap {
+    [IdwEventType.SkillInitRequest]: undefined;
+    [IdwEventType.Init]: IdwInitPayload;
+    [IdwEventType.SkillReady]: undefined;
+    [IdwEventType.SkillResult]: SkillResultPayload;
+    [IdwEventType.SkillError]: SkillErrorPayload;
+}
+export interface IdwEvent<K extends keyof IdwEventMap> {
+    version: ProtocolVersion;
+    type: K;
+    requestId?: string;
+    payload: IdwEventMap[K];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GAAG,KAAK,CAAC;AAEpC,MAAM,MAAM,cAAc,GAAG;IAO3B,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IAEb,MAAM,EAAE,MAAM,CAAC;IAEf,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,OAAO,CAAC;IACd,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,oBAAY,YAAY;IAEtB,gBAAgB,uBAAuB;IAEvC,IAAI,aAAa;IAEjB,UAAU,gBAAgB;IAE1B,WAAW,iBAAiB;IAE5B,UAAU,gBAAgB;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,CAAC,YAAY,CAAC,gBAAgB,CAAC,EAAE,SAAS,CAAC;IAC3C,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,cAAc,CAAC;IACpC,CAAC,YAAY,CAAC,UAAU,CAAC,EAAE,SAAS,CAAC;IACrC,CAAC,YAAY,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAC;IAC/C,CAAC,YAAY,CAAC,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAC9C;AAED,MAAM,WAAW,QAAQ,CAAC,CAAC,SAAS,MAAM,WAAW;IAEnD,OAAO,EAAE,eAAe,CAAC;IAKzB,IAAI,EAAE,CAAC,CAAC;IAER,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;CACzB"}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@or-sdk/idw-skill",
+  "version": "1.1.0-beta.4024.0",
+  "license": "Apache-2.0",
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
+  "scripts": {
+    "build": "pnpm clean && concurrently 'pnpm:build:*(!watch)'",
+    "build:cjs": "tsc --project tsconfig.json",
+    "build:esm": "tsc --project tsconfig.esm.json",
+    "build:types": "tsc --project tsconfig.types.json",
+    "build:watch": "concurrently 'pnpm:build:watch:*'",
+    "build:watch:cjs": "tsc --project tsconfig.json -w",
+    "build:watch:esm": "tsc --project tsconfig.esm.json -w",
+    "build:watch:types": "tsc --project tsconfig.types.json -w",
+    "clean": "rm -rf ./dist",
+    "dev": "pnpm build:watch:esm"
+  },
+  "dependencies": {
+    "@or-sdk/base": "^0.44.0"
+  },
+  "devDependencies": {
+    "concurrently": "9.0.1",
+    "typescript": "5.6.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/IdwSkill.ts

@@ -0,0 +1,142 @@
+import {
+  IdwEvent,
+  IdwEventMap,
+  IdwEventType,
+  IdwInitPayload,
+  IdwSkillConfig,
+  ProtocolVersion,
+  SkillErrorPayload,
+  SkillResultPayload,
+} from './types';
+
+const PROTOCOL_VERSION: ProtocolVersion = '1.0';
+
+/**
+ * OneReach IdwSkill — client for Web Skills running inside an IDW iframe.
+ *
+ * ## Installation:
+ * ```
+ * $ npm i @or-sdk/idw-skill
+ * ```
+ *
+ * ## Usage:
+ * ```ts
+ * const sdk = new IdwSkill({ targetOrigin: 'https://idw.edison.onereach.ai' });
+ *
+ * // 1. Trigger the handshake and wait for IDW configuration
+ * const initData = await sdk.init();
+ *
+ * // 2. Render your UI using initData, then signal readiness
+ * sdk.ready();
+ *
+ * // 3. Later — report a result or an error back to the IDW
+ * sdk.sendResult({ data: { answer: 42 } });
+ * sdk.sendError({ code: 'VALIDATION_FAILED', message: 'userId is missing' });
+ * ```
+ */
+export class IdwSkill {
+  private readonly targetOrigin: string;
+  private _initData: IdwInitPayload | null = null;
+
+  constructor(params: IdwSkillConfig) {
+    const { targetOrigin } = params;
+
+    if (!targetOrigin) {
+      throw new Error('targetOrigin is required');
+    }
+
+    this.targetOrigin = targetOrigin;
+  }
+
+  /** The orToken received from IDW during init, or null before init completes. */
+  get orToken(): string | null {
+    return this._initData?.orToken ?? null;
+  }
+
+  /** The full payload received from IDW during init, or null before init completes. */
+  get initData(): IdwInitPayload | null {
+    return this._initData;
+  }
+
+  /**
+   * Initiates the pull-based handshake with the IDW host.
+   *
+   * Sends `skill:init:request` to the parent frame and returns a Promise
+   * that resolves with the `IdwInitPayload` once the IDW responds with
+   * `idw:init`. Only messages originating from `targetOrigin` are accepted.
+   */
+  init(): Promise<IdwInitPayload> {
+    return new Promise((resolve) => {
+      const handleMessage = (event: MessageEvent) => {
+        if (event.origin !== this.targetOrigin) {
+          return;
+        }
+
+        const data = event.data as IdwEvent<IdwEventType.Init>;
+
+        if (data?.version === PROTOCOL_VERSION && data?.type === IdwEventType.Init) {
+          window.removeEventListener('message', handleMessage);
+          this._initData = data.payload;
+          resolve(data.payload);
+        }
+      };
+
+      window.addEventListener('message', handleMessage);
+
+      this.postMessage<IdwEventType.SkillInitRequest>({
+        version: PROTOCOL_VERSION,
+        type: IdwEventType.SkillInitRequest,
+        payload: undefined,
+      });
+    });
+  }
+
+  /**
+   * Signals to the IDW that the Skill UI is fully rendered and interactive.
+   * Call this after `init()` resolves and your component tree is ready.
+   *
+   * @param requestId - Optional UUID to correlate with a prior IDW request.
+   */
+  ready(requestId?: string): void {
+    this.postMessage<IdwEventType.SkillReady>({
+      version: PROTOCOL_VERSION,
+      type: IdwEventType.SkillReady,
+      requestId,
+      payload: undefined,
+    });
+  }
+
+  /**
+   * Delivers a result payload back to the IDW.
+   *
+   * @param payload   - The result data to send.
+   * @param requestId - Optional UUID to correlate with a prior IDW request.
+   */
+  sendResult(payload: SkillResultPayload, requestId?: string): void {
+    this.postMessage<IdwEventType.SkillResult>({
+      version: PROTOCOL_VERSION,
+      type: IdwEventType.SkillResult,
+      requestId,
+      payload,
+    });
+  }
+
+  /**
+   * Reports a standardized error to the IDW.
+   *
+   * @param payload   - The error details (code, message, optional details).
+   * @param requestId - Optional UUID to correlate with a prior IDW request.
+   */
+  sendError(payload: SkillErrorPayload, requestId?: string): void {
+    this.postMessage<IdwEventType.SkillError>({
+      version: PROTOCOL_VERSION,
+      type: IdwEventType.SkillError,
+      requestId,
+      payload,
+    });
+  }
+
+  private postMessage<K extends keyof IdwEventMap>(event: IdwEvent<K>): void {
+    window.parent.postMessage(event, this.targetOrigin);
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { IdwSkill } from './IdwSkill';
+export * from './types';

package/src/types.ts

@@ -0,0 +1,85 @@
+export type ProtocolVersion = '1.0';
+
+export type IdwSkillConfig = {
+  /**
+   * The exact origin of the IDW host (e.g. 'https://idw.edison.onereach.ai').
+   * Used as the targetOrigin for all outgoing postMessage calls and to
+   * validate the origin of every incoming message.
+   * Never use '*' — that would be a security vulnerability.
+   */
+  targetOrigin: string;
+};
+
+export interface IdwSkillSettings {
+  id: string;
+  name: string;
+  slug: string;
+  accountId: string;
+  isPrivate: boolean;
+}
+
+export interface IdwSkillUser {
+  role: string;
+  /** UUID format */
+  userId: string;
+  /** UUID format */
+  contactId: string;
+  email: string;
+  firstName: string;
+  lastName: string;
+  avatarUrl: string;
+  phoneNumber: string;
+}
+
+export interface IdwInitPayload {
+  orToken: string;
+  settings: IdwSkillSettings;
+  user?: IdwSkillUser;
+  inputParams?: Record<string, unknown>;
+}
+
+export interface SkillResultPayload {
+  data: unknown;
+  [key: string]: unknown;
+}
+
+export interface SkillErrorPayload {
+  code: string;
+  message: string;
+  details?: unknown;
+}
+
+export enum IdwEventType {
+  /** Used by the Skill to trigger the initialization flow */
+  SkillInitRequest = 'skill:init:request',
+  /** Delivers initial configuration to the Skill */
+  Init = 'idw:init',
+  /** Signal that the Skill is interactive */
+  SkillReady = 'skill:ready',
+  /** Delivery of data/outcome back to the IDW */
+  SkillResult = 'skill:result',
+  /** Standardized error reporting */
+  SkillError = 'skill:error',
+}
+
+export interface IdwEventMap {
+  [IdwEventType.SkillInitRequest]: undefined;
+  [IdwEventType.Init]: IdwInitPayload;
+  [IdwEventType.SkillReady]: undefined;
+  [IdwEventType.SkillResult]: SkillResultPayload;
+  [IdwEventType.SkillError]: SkillErrorPayload;
+}
+
+export interface IdwEvent<K extends keyof IdwEventMap> {
+  /** Protocol version */
+  version: ProtocolVersion;
+  /**
+   * Event identifier using the 'namespace:action' convention.
+   * Namespaces: 'idw:' for Host, 'skill:' for Guest.
+   */
+  type: K;
+  /** Optional UUID to track request-response pairs */
+  requestId?: string;
+  /** The data payload relevant to the event type */
+  payload: IdwEventMap[K];
+}

package/tsconfig.dev.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.esm.json",
+  "compilerOptions": {
+    "declarationDir": "./dist/types",
+    "rootDir": "./src",
+    "declaration": true
+  }
+}

package/tsconfig.esm.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist/esm",
+    "declarationDir": "./dist/types",
+    "module": "ES6",
+    "target": "es6",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true
+  }
+}

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist/cjs/",
+    "rootDir": "./src"
+  }
+}

package/tsconfig.types.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist/types/",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": true,
+    "removeComments": false
+  }
+}