@soulcraft/sdk 1.2.0 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,oBAAoB,CAAA;AAC3B,YAAY,EACV,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,oBAAoB,CAAA;AAG3B,OAAO,EACL,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,eAAe,CAAA;AACtB,YAAY,EACV,mBAAmB,EACnB,qBAAqB,EACrB,eAAe,EACf,SAAS,GACV,MAAM,eAAe,CAAA;AAGtB,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,UAAU,GACX,MAAM,oBAAoB,CAAA;AAC3B,YAAY,EACV,qBAAqB,EACrB,UAAU,EACV,qBAAqB,EACrB,eAAe,GAChB,MAAM,oBAAoB,CAAA;AAC3B,YAAY,EACV,QAAQ,EACR,cAAc,EACd,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,eAAe,EACf,aAAa,GACd,MAAM,0BAA0B,CAAA;AAGjC,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,aAAa,GACd,MAAM,+BAA+B,CAAA;AACtC,YAAY,EACV,qBAAqB,EACrB,cAAc,EACd,WAAW,EACX,cAAc,EACd,4BAA4B,GAC7B,MAAM,+BAA+B,CAAA;AACtC,OAAO,EAAE,8BAA8B,EAAE,MAAM,gCAAgC,CAAA;AAC/E,YAAY,EACV,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,gCAAgC,CAAA;AAGvC,OAAO,EACL,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,kCAAkC,CAAA;AAGzC,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,WAAW,EACX,mBAAmB,GACpB,MAAM,2BAA2B,CAAA;AAGlC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAGvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AACjE,YAAY,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAA;AAC7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AACjE,YAAY,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAA;AAC7E,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAC3D,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAA;AAG7E,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AACnD,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAA;AACxF,YAAY,EAAE,4BAA4B,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAA;AACpG,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,oBAAoB,CAAA;AAC3B,YAAY,EACV,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,oBAAoB,CAAA;AAG3B,OAAO,EACL,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,eAAe,CAAA;AACtB,YAAY,EACV,mBAAmB,EACnB,qBAAqB,EACrB,eAAe,EACf,SAAS,GACV,MAAM,eAAe,CAAA;AAGtB,OAAO,EAAE,8BAA8B,EAAE,MAAM,0BAA0B,CAAA;AACzE,YAAY,EACV,8BAA8B,EAC9B,wBAAwB,GACzB,MAAM,0BAA0B,CAAA;AAGjC,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,UAAU,GACX,MAAM,oBAAoB,CAAA;AAC3B,YAAY,EACV,qBAAqB,EACrB,UAAU,EACV,qBAAqB,EACrB,eAAe,GAChB,MAAM,oBAAoB,CAAA;AAC3B,YAAY,EACV,QAAQ,EACR,cAAc,EACd,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,eAAe,EACf,aAAa,GACd,MAAM,0BAA0B,CAAA;AAGjC,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,aAAa,GACd,MAAM,+BAA+B,CAAA;AACtC,YAAY,EACV,qBAAqB,EACrB,cAAc,EACd,WAAW,EACX,cAAc,EACd,4BAA4B,GAC7B,MAAM,+BAA+B,CAAA;AACtC,OAAO,EAAE,8BAA8B,EAAE,MAAM,gCAAgC,CAAA;AAC/E,YAAY,EACV,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,gCAAgC,CAAA;AAGvC,OAAO,EACL,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,kCAAkC,CAAA;AAGzC,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,WAAW,EACX,mBAAmB,GACpB,MAAM,2BAA2B,CAAA;AAGlC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAGvD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACnD,YAAY,EACV,SAAS,EACT,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AACjE,YAAY,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAA;AAC7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AACjE,YAAY,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAA;AAC7E,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAC3D,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAA;AAG7E,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AACnD,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAA;AACxF,YAAY,EAAE,4BAA4B,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAA;AACpG,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA"}
@@ -36,6 +36,8 @@
36
36
  export { BrainyInstancePool, BrainyInitializingError, computeEmailHash, } from './instance-pool.js';
37
37
  // ── Handler factories ─────────────────────────────────────────────────────────
38
38
  export { createBrainyHandler, createBrainyWsHandler, } from './handlers.js';
39
+ // ── PostMessage handler (Workshop parent-frame ↔ kit iframe) ──────────────────
40
+ export { createBrainyPostMessageHandler } from './postmessage-handler.js';
39
41
  // ── Hall module factory + TURN utilities ─────────────────────────────────────
40
42
  export { createHallModule, generateTurnCredentials, HallClient, } from './hall-handlers.js';
41
43
  // ── Auth middleware + backchannel logout ──────────────────────────────────────
@@ -47,6 +49,8 @@ export { verifyServiceToken, extractBearerToken, } from '../modules/auth/service
47
49
  export { SOULCRAFT_USER_FIELDS, SOULCRAFT_SESSION_CONFIG, getAuthMode, getOIDCClientConfig, } from '../modules/auth/config.js';
48
50
  // ── createSDK factory ─────────────────────────────────────────────────────────
49
51
  export { createSDK } from './create-sdk.js';
52
+ // ── createServerSDK.fromLicense() — license-driven server SDK ─────────────────
53
+ export { createServerSDK } from './from-license.js';
50
54
  // ── Module factories (for advanced use — createSDK assembles these automatically) ─
51
55
  export { createBillingModule } from '../modules/billing/index.js';
52
56
  export { createLicenseModule } from '../modules/license/index.js';
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,iFAAiF;AACjF,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,oBAAoB,CAAA;AAM3B,iFAAiF;AACjF,OAAO,EACL,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,eAAe,CAAA;AAQtB,gFAAgF;AAChF,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,UAAU,GACX,MAAM,oBAAoB,CAAA;AAqB3B,iFAAiF;AACjF,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,aAAa,GACd,MAAM,+BAA+B,CAAA;AAQtC,OAAO,EAAE,8BAA8B,EAAE,MAAM,gCAAgC,CAAA;AAM/E,iFAAiF;AACjF,OAAO,EACL,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,kCAAkC,CAAA;AAEzC,mFAAmF;AACnF,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,WAAW,EACX,mBAAmB,GACpB,MAAM,2BAA2B,CAAA;AAElC,iFAAiF;AACjF,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAG3C,qFAAqF;AACrF,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AAEjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AAEjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAC3D,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAA;AAI7E,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAA;AAExF,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,iFAAiF;AACjF,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,oBAAoB,CAAA;AAM3B,iFAAiF;AACjF,OAAO,EACL,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,eAAe,CAAA;AAQtB,iFAAiF;AACjF,OAAO,EAAE,8BAA8B,EAAE,MAAM,0BAA0B,CAAA;AAMzE,gFAAgF;AAChF,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,UAAU,GACX,MAAM,oBAAoB,CAAA;AAqB3B,iFAAiF;AACjF,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,aAAa,GACd,MAAM,+BAA+B,CAAA;AAQtC,OAAO,EAAE,8BAA8B,EAAE,MAAM,gCAAgC,CAAA;AAM/E,iFAAiF;AACjF,OAAO,EACL,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,kCAAkC,CAAA;AAEzC,mFAAmF;AACnF,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,WAAW,EACX,mBAAmB,GACpB,MAAM,2BAA2B,CAAA;AAElC,iFAAiF;AACjF,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAG3C,iFAAiF;AACjF,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAOnD,qFAAqF;AACrF,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AAEjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AAEjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAC3D,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAA;AAI7E,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAA;AAExF,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA"}
@@ -0,0 +1,127 @@
1
+ /**
2
+ * @module server/postmessage-handler
3
+ * @description Parent-frame PostMessage handler for Workshop WebContainer kit iframes.
4
+ *
5
+ * Workshop kit apps run as WebContainer iframes inside the Workshop editor. They use
6
+ * {@link PostMessageTransport} from `@soulcraft/sdk/client` to post Brainy RPC calls to the
7
+ * parent Workshop frame. This module provides the parent-side handler that receives those
8
+ * calls, dispatches them to the live Brainy instance, and posts the response back.
9
+ *
10
+ * ## Wire protocol
11
+ *
12
+ * **Inbound** (from kit iframe):
13
+ * ```json
14
+ * { "type": "brainy:request", "id": "<uuid>", "method": "find", "args": [{...}] }
15
+ * ```
16
+ *
17
+ * **Outbound** (to kit iframe):
18
+ * ```json
19
+ * { "type": "brainy:response", "id": "<uuid>", "result": [...] }
20
+ * { "type": "brainy:response", "id": "<uuid>", "error": { "code": "...", "message": "..." } }
21
+ * ```
22
+ *
23
+ * ## Usage (Workshop parent frame)
24
+ *
25
+ * ```typescript
26
+ * import { createBrainyPostMessageHandler } from '@soulcraft/sdk/server'
27
+ * import { createSDK, BrainyInstancePool } from '@soulcraft/sdk/server'
28
+ *
29
+ * const pool = new BrainyInstancePool({ ... })
30
+ *
31
+ * // Mount once per kit iframe window:
32
+ * const handler = createBrainyPostMessageHandler({
33
+ * resolveBrain: async (method) => {
34
+ * const brain = await pool.forUser(currentUser.emailHash, currentWorkspaceId)
35
+ * return brain
36
+ * },
37
+ * allowedOrigin: 'null', // WebContainer iframes have origin 'null'
38
+ * targetWindow: kitIframeRef.contentWindow!,
39
+ * })
40
+ *
41
+ * // When the kit iframe is torn down:
42
+ * handler.dispose()
43
+ * ```
44
+ *
45
+ * ## Security
46
+ *
47
+ * The handler validates the `event.origin` against `allowedOrigin` before dispatching.
48
+ * WebContainer iframes have `origin: 'null'` — pass `'null'` (string) for those.
49
+ * For externally hosted kit apps, pass the expected origin string.
50
+ *
51
+ * Optionally, set `allowedSource` to the `contentWindow` of the specific iframe to
52
+ * reject messages from other frames on the same origin.
53
+ */
54
+ import type { Brainy } from '@soulcraft/brainy';
55
+ /**
56
+ * Configuration for {@link createBrainyPostMessageHandler}.
57
+ */
58
+ export interface BrainyPostMessageHandlerConfig {
59
+ /**
60
+ * Resolve the Brainy instance to use for a given RPC call.
61
+ *
62
+ * Called once per request. Workshop typically resolves from a `BrainyInstancePool`
63
+ * keyed to the current user and workspace.
64
+ *
65
+ * @param method - The Brainy method being called (e.g. `'find'`, `'vfs.readFile'`).
66
+ * @returns A live Brainy instance.
67
+ */
68
+ resolveBrain: (method: string) => Promise<Brainy> | Brainy;
69
+ /**
70
+ * The expected `event.origin` of inbound messages.
71
+ *
72
+ * Messages from any other origin are silently ignored.
73
+ * Pass `'null'` (string) for WebContainer iframes, which always report origin `'null'`.
74
+ * Pass `'*'` to accept any origin (not recommended in production).
75
+ */
76
+ allowedOrigin: string;
77
+ /**
78
+ * The window to which responses are posted.
79
+ *
80
+ * Defaults to the `source` of the inbound message event. Pass the kit iframe's
81
+ * `contentWindow` explicitly to further restrict which window receives responses.
82
+ */
83
+ targetWindow?: Window;
84
+ /**
85
+ * The window on which to listen for inbound `message` events.
86
+ *
87
+ * Defaults to the global `window`. Override in tests or if the handler should
88
+ * listen on a specific frame's window.
89
+ */
90
+ listenerWindow?: Window & typeof globalThis;
91
+ }
92
+ /**
93
+ * A mounted PostMessage handler. Call `dispose()` when the kit iframe is torn down
94
+ * to remove the message listener and prevent memory leaks.
95
+ */
96
+ export interface BrainyPostMessageHandler {
97
+ /**
98
+ * Remove the `message` event listener from the listener window.
99
+ *
100
+ * Call this when the associated kit iframe is unmounted or navigated away.
101
+ */
102
+ dispose(): void;
103
+ }
104
+ /**
105
+ * Mount a PostMessage handler in the parent Workshop frame.
106
+ *
107
+ * Listens for `brainy:request` messages from kit iframes, dispatches each call to
108
+ * the resolved Brainy instance via a {@link LocalTransport}, and posts the result
109
+ * back as a `brainy:response` message.
110
+ *
111
+ * @param config - Handler configuration including brain resolver and allowed origin.
112
+ * @returns A {@link BrainyPostMessageHandler} with a `dispose()` method.
113
+ *
114
+ * @example
115
+ * ```typescript
116
+ * const handler = createBrainyPostMessageHandler({
117
+ * resolveBrain: () => pool.forUser(user.emailHash, workspaceId),
118
+ * allowedOrigin: 'null', // WebContainer iframes report origin 'null'
119
+ * targetWindow: iframe.contentWindow!,
120
+ * })
121
+ *
122
+ * // On iframe unmount:
123
+ * handler.dispose()
124
+ * ```
125
+ */
126
+ export declare function createBrainyPostMessageHandler(config: BrainyPostMessageHandlerConfig): BrainyPostMessageHandler;
127
+ //# sourceMappingURL=postmessage-handler.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"postmessage-handler.d.ts","sourceRoot":"","sources":["../../src/server/postmessage-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAQ/C;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C;;;;;;;;OAQG;IACH,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAA;IAE1D;;;;;;OAMG;IACH,aAAa,EAAE,MAAM,CAAA;IAErB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IAErB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,UAAU,CAAA;CAC5C;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,OAAO,IAAI,IAAI,CAAA;CAChB;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,8BAA8B,GACrC,wBAAwB,CA8C1B"}
@@ -0,0 +1,125 @@
1
+ /**
2
+ * @module server/postmessage-handler
3
+ * @description Parent-frame PostMessage handler for Workshop WebContainer kit iframes.
4
+ *
5
+ * Workshop kit apps run as WebContainer iframes inside the Workshop editor. They use
6
+ * {@link PostMessageTransport} from `@soulcraft/sdk/client` to post Brainy RPC calls to the
7
+ * parent Workshop frame. This module provides the parent-side handler that receives those
8
+ * calls, dispatches them to the live Brainy instance, and posts the response back.
9
+ *
10
+ * ## Wire protocol
11
+ *
12
+ * **Inbound** (from kit iframe):
13
+ * ```json
14
+ * { "type": "brainy:request", "id": "<uuid>", "method": "find", "args": [{...}] }
15
+ * ```
16
+ *
17
+ * **Outbound** (to kit iframe):
18
+ * ```json
19
+ * { "type": "brainy:response", "id": "<uuid>", "result": [...] }
20
+ * { "type": "brainy:response", "id": "<uuid>", "error": { "code": "...", "message": "..." } }
21
+ * ```
22
+ *
23
+ * ## Usage (Workshop parent frame)
24
+ *
25
+ * ```typescript
26
+ * import { createBrainyPostMessageHandler } from '@soulcraft/sdk/server'
27
+ * import { createSDK, BrainyInstancePool } from '@soulcraft/sdk/server'
28
+ *
29
+ * const pool = new BrainyInstancePool({ ... })
30
+ *
31
+ * // Mount once per kit iframe window:
32
+ * const handler = createBrainyPostMessageHandler({
33
+ * resolveBrain: async (method) => {
34
+ * const brain = await pool.forUser(currentUser.emailHash, currentWorkspaceId)
35
+ * return brain
36
+ * },
37
+ * allowedOrigin: 'null', // WebContainer iframes have origin 'null'
38
+ * targetWindow: kitIframeRef.contentWindow!,
39
+ * })
40
+ *
41
+ * // When the kit iframe is torn down:
42
+ * handler.dispose()
43
+ * ```
44
+ *
45
+ * ## Security
46
+ *
47
+ * The handler validates the `event.origin` against `allowedOrigin` before dispatching.
48
+ * WebContainer iframes have `origin: 'null'` — pass `'null'` (string) for those.
49
+ * For externally hosted kit apps, pass the expected origin string.
50
+ *
51
+ * Optionally, set `allowedSource` to the `contentWindow` of the specific iframe to
52
+ * reject messages from other frames on the same origin.
53
+ */
54
+ import { LocalTransport } from '../transports/local.js';
55
+ // ─────────────────────────────────────────────────────────────────────────────
56
+ // Factory
57
+ // ─────────────────────────────────────────────────────────────────────────────
58
+ /**
59
+ * Mount a PostMessage handler in the parent Workshop frame.
60
+ *
61
+ * Listens for `brainy:request` messages from kit iframes, dispatches each call to
62
+ * the resolved Brainy instance via a {@link LocalTransport}, and posts the result
63
+ * back as a `brainy:response` message.
64
+ *
65
+ * @param config - Handler configuration including brain resolver and allowed origin.
66
+ * @returns A {@link BrainyPostMessageHandler} with a `dispose()` method.
67
+ *
68
+ * @example
69
+ * ```typescript
70
+ * const handler = createBrainyPostMessageHandler({
71
+ * resolveBrain: () => pool.forUser(user.emailHash, workspaceId),
72
+ * allowedOrigin: 'null', // WebContainer iframes report origin 'null'
73
+ * targetWindow: iframe.contentWindow!,
74
+ * })
75
+ *
76
+ * // On iframe unmount:
77
+ * handler.dispose()
78
+ * ```
79
+ */
80
+ export function createBrainyPostMessageHandler(config) {
81
+ const listenerWin = config.listenerWindow ?? window;
82
+ async function _handleMessage(event) {
83
+ // Validate origin.
84
+ if (config.allowedOrigin !== '*' && event.origin !== config.allowedOrigin)
85
+ return;
86
+ const data = event.data;
87
+ if (!data || data.type !== 'brainy:request' || !data.id)
88
+ return;
89
+ const { id, method, args } = data;
90
+ // Determine the window to reply to.
91
+ const replyTo = config.targetWindow ?? event.source;
92
+ if (!replyTo)
93
+ return;
94
+ let response;
95
+ try {
96
+ const brain = await config.resolveBrain(method);
97
+ const transport = new LocalTransport(brain);
98
+ const result = await transport.call(method, args);
99
+ response = { type: 'brainy:response', id, result };
100
+ }
101
+ catch (err) {
102
+ const message = err instanceof Error ? err.message : String(err);
103
+ // Map known error names to codes the client can deserialize.
104
+ let code = 'RPC_ERROR';
105
+ if (err instanceof Error) {
106
+ if (err.name === 'SDKAuthError' || message.includes('Unauthorized'))
107
+ code = 'AUTH_ERROR';
108
+ else if (err.name === 'SDKForbiddenError' || message.includes('Forbidden'))
109
+ code = 'FORBIDDEN';
110
+ else if (err.name === 'BrainyMethodNotFoundError')
111
+ code = 'METHOD_NOT_FOUND';
112
+ }
113
+ response = { type: 'brainy:response', id, error: { code, message } };
114
+ }
115
+ replyTo.postMessage(response, '*');
116
+ }
117
+ const listener = (event) => { void _handleMessage(event); };
118
+ listenerWin.addEventListener('message', listener);
119
+ return {
120
+ dispose() {
121
+ listenerWin.removeEventListener('message', listener);
122
+ },
123
+ };
124
+ }
125
+ //# sourceMappingURL=postmessage-handler.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"postmessage-handler.js","sourceRoot":"","sources":["../../src/server/postmessage-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AA6DvD,gFAAgF;AAChF,UAAU;AACV,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,8BAA8B,CAC5C,MAAsC;IAEtC,MAAM,WAAW,GAA+B,MAAM,CAAC,cAAc,IAAI,MAAM,CAAA;IAE/E,KAAK,UAAU,cAAc,CAAC,KAAmB;QAC/C,mBAAmB;QACnB,IAAI,MAAM,CAAC,aAAa,KAAK,GAAG,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM,CAAC,aAAa;YAAE,OAAM;QAEjF,MAAM,IAAI,GAAG,KAAK,CAAC,IAA0B,CAAA;QAC7C,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,KAAK,gBAAgB,IAAI,CAAC,IAAI,CAAC,EAAE;YAAE,OAAM;QAE/D,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,IAAI,CAAA;QAEjC,oCAAoC;QACpC,MAAM,OAAO,GAAW,MAAM,CAAC,YAAY,IAAK,KAAK,CAAC,MAAiB,CAAA;QACvE,IAAI,CAAC,OAAO;YAAE,OAAM;QAEpB,IAAI,QAA6B,CAAA;QAEjC,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,CAAA;YAC/C,MAAM,SAAS,GAAG,IAAI,cAAc,CAAC,KAAK,CAAC,CAAA;YAC3C,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,IAAiB,CAAC,CAAA;YAC9D,QAAQ,GAAG,EAAE,IAAI,EAAE,iBAAiB,EAAE,EAAE,EAAE,MAAM,EAAE,CAAA;QACpD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YAChE,6DAA6D;YAC7D,IAAI,IAAI,GAAG,WAAW,CAAA;YACtB,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;gBACzB,IAAI,GAAG,CAAC,IAAI,KAAK,cAAc,IAAI,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC;oBAAE,IAAI,GAAG,YAAY,CAAA;qBACnF,IAAI,GAAG,CAAC,IAAI,KAAK,mBAAmB,IAAI,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;oBAAE,IAAI,GAAG,WAAW,CAAA;qBACzF,IAAI,GAAG,CAAC,IAAI,KAAK,2BAA2B;oBAAE,IAAI,GAAG,kBAAkB,CAAA;YAC9E,CAAC;YACD,QAAQ,GAAG,EAAE,IAAI,EAAE,iBAAiB,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,CAAA;QACtE,CAAC;QAED,OAAO,CAAC,WAAW,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAA;IACpC,CAAC;IAED,MAAM,QAAQ,GAAG,CAAC,KAAmB,EAAE,EAAE,GAAG,KAAK,cAAc,CAAC,KAAK,CAAC,CAAA,CAAC,CAAC,CAAA;IACxE,WAAW,CAAC,gBAAgB,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAA;IAEjD,OAAO;QACL,OAAO;YACL,WAAW,CAAC,mBAAmB,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAA;QACtD,CAAC;KACF,CAAA;AACH,CAAC"}
@@ -0,0 +1,153 @@
1
+ /**
2
+ * @module transports/postmessage
3
+ * @description PostMessage transport — sends Brainy RPC calls from a child iframe to its
4
+ * parent frame via `window.postMessage`.
5
+ *
6
+ * Designed for Workshop kit apps running inside WebContainer iframes. The kit app calls
7
+ * Brainy methods as normal via `createBrainyProxy(transport)`, and each call is forwarded
8
+ * to the parent Workshop frame which owns the actual Brainy instance.
9
+ *
10
+ * ## Wire protocol
11
+ *
12
+ * **Request** (kit iframe → parent):
13
+ * ```json
14
+ * { "type": "brainy:request", "id": "<uuid>", "method": "find", "args": [{ "query": "..." }] }
15
+ * ```
16
+ *
17
+ * **Response** (parent → kit iframe):
18
+ * ```json
19
+ * { "type": "brainy:response", "id": "<uuid>", "result": [...] }
20
+ * { "type": "brainy:response", "id": "<uuid>", "error": { "code": "RPC_ERROR", "message": "..." } }
21
+ * ```
22
+ *
23
+ * The `id` field correlates each response to its originating request. Pending calls are
24
+ * resolved or rejected when the matching response arrives.
25
+ *
26
+ * ## Usage
27
+ *
28
+ * ```typescript
29
+ * // Kit app (iframe):
30
+ * import { PostMessageTransport, createBrainyProxy } from '@soulcraft/sdk/client'
31
+ *
32
+ * const transport = new PostMessageTransport()
33
+ * const brainy = createBrainyProxy(transport)
34
+ *
35
+ * const results = await brainy.find({ query: 'candle inventory', limit: 10 })
36
+ * ```
37
+ *
38
+ * The parent frame must mount a `createBrainyPostMessageHandler` from `@soulcraft/sdk/server`
39
+ * to receive and respond to these messages.
40
+ *
41
+ * ## Security
42
+ *
43
+ * Messages are sent to `targetOrigin` (default `'*'`). For production use, pass the
44
+ * Workshop origin (e.g. `'https://workshop.soulcraft.com'`) to restrict delivery.
45
+ * The parent handler validates `event.source` and `event.origin` before dispatching.
46
+ */
47
+ import type { SDKTransport } from './transport.js';
48
+ import type { BrainyChangeEvent } from '../modules/brainy/events.js';
49
+ /** A Brainy RPC request posted from the kit iframe to the parent. */
50
+ export interface PostMessageRequest {
51
+ type: 'brainy:request';
52
+ id: string;
53
+ method: string;
54
+ args: unknown[];
55
+ }
56
+ /** A successful Brainy RPC response posted from the parent to the kit iframe. */
57
+ export interface PostMessageSuccessResponse {
58
+ type: 'brainy:response';
59
+ id: string;
60
+ result: unknown;
61
+ }
62
+ /** An error Brainy RPC response posted from the parent to the kit iframe. */
63
+ export interface PostMessageErrorResponse {
64
+ type: 'brainy:response';
65
+ id: string;
66
+ error: {
67
+ code: string;
68
+ message: string;
69
+ };
70
+ }
71
+ /** Union of all response shapes. */
72
+ export type PostMessageResponse = PostMessageSuccessResponse | PostMessageErrorResponse;
73
+ /** Minimal window-like interface required by the transport. */
74
+ export interface PostMessageWindow {
75
+ addEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
76
+ removeEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
77
+ postMessage(message: unknown, targetOrigin: string): void;
78
+ readonly parent: PostMessageWindow;
79
+ }
80
+ /**
81
+ * PostMessage transport for kit apps running inside Workshop WebContainer iframes.
82
+ *
83
+ * Each `call()` posts a `brainy:request` message to `window.parent` and waits for
84
+ * a matching `brainy:response` message. Responses are correlated by a UUID `id` field
85
+ * generated per request.
86
+ *
87
+ * The transport installs a single `message` listener on `window` at construction time
88
+ * and removes it when `close()` is called.
89
+ */
90
+ export declare class PostMessageTransport implements SDKTransport {
91
+ private readonly _targetOrigin;
92
+ private readonly _timeoutMs;
93
+ private readonly _pending;
94
+ private readonly _eventHandlers;
95
+ private _closed;
96
+ private readonly _messageListener;
97
+ private readonly _listenerWindow;
98
+ private readonly _parentWindow;
99
+ /**
100
+ * @param targetOrigin - The origin to which requests are sent. Defaults to `'*'`.
101
+ * Pass the Workshop origin in production for security
102
+ * (e.g. `'https://workshop.soulcraft.com'`).
103
+ * @param timeoutMs - Per-call timeout in milliseconds. Default: 30 000.
104
+ * @param listenerWindow - Window on which to listen for responses. Defaults to `window`.
105
+ * Pass a custom object in tests or non-browser environments.
106
+ * @param parentWindow - Window to which requests are posted. Defaults to `window.parent`.
107
+ * Pass a custom object in tests or non-browser environments.
108
+ */
109
+ constructor(targetOrigin?: string, timeoutMs?: number, listenerWindow?: PostMessageWindow, parentWindow?: PostMessageWindow);
110
+ private _handleMessage;
111
+ private _generateId;
112
+ /**
113
+ * Dispatch a Brainy RPC call via `window.parent.postMessage`.
114
+ *
115
+ * @param method - Dot-separated Brainy method name (e.g. `'find'`, `'vfs.readFile'`).
116
+ * @param args - Positional arguments forwarded to Brainy on the parent frame.
117
+ * @returns A Promise that resolves with the Brainy method's return value.
118
+ * @throws {@link SDKDisconnectedError} if the transport has been closed.
119
+ * @throws {@link SDKTimeoutError} if no response arrives within `timeoutMs`.
120
+ * @throws {@link SDKAuthError} if the parent responds with an auth error.
121
+ * @throws {@link SDKRpcError} if the parent responds with a Brainy-level error.
122
+ */
123
+ call(method: string, args: unknown[]): Promise<unknown>;
124
+ /**
125
+ * Register a handler for real-time Brainy change events.
126
+ *
127
+ * Change events are forwarded from the parent frame via `brainy:event` messages.
128
+ * The parent handler posts these when Brainy fires a data change.
129
+ *
130
+ * @param handler - Called with each {@link BrainyChangeEvent}.
131
+ */
132
+ onEvent(handler: (event: BrainyChangeEvent) => void): void;
133
+ /**
134
+ * Remove a previously registered change event handler.
135
+ *
136
+ * @param handler - The same function reference passed to {@link onEvent}.
137
+ */
138
+ offEvent(handler: (event: BrainyChangeEvent) => void): void;
139
+ /**
140
+ * Returns `true` when the transport is open.
141
+ *
142
+ * PostMessage is always available as long as the transport has not been closed —
143
+ * it relies on `window.parent` which is always present inside an iframe.
144
+ */
145
+ isAlive(): boolean;
146
+ /**
147
+ * Close the transport, removing the message listener and rejecting all pending calls.
148
+ *
149
+ * After calling `close()`, any further `call()` invocations throw `SDKDisconnectedError`.
150
+ */
151
+ close(): Promise<void>;
152
+ }
153
+ //# sourceMappingURL=postmessage.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"postmessage.d.ts","sourceRoot":"","sources":["../../src/transports/postmessage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AAapE,qEAAqE;AACrE,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,gBAAgB,CAAA;IACtB,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,OAAO,EAAE,CAAA;CAChB;AAED,iFAAiF;AACjF,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,iBAAiB,CAAA;IACvB,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,OAAO,CAAA;CAChB;AAED,6EAA6E;AAC7E,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,iBAAiB,CAAA;IACvB,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAA;QACZ,OAAO,EAAE,MAAM,CAAA;KAChB,CAAA;CACF;AAED,oCAAoC;AACpC,MAAM,MAAM,mBAAmB,GAAG,0BAA0B,GAAG,wBAAwB,CAAA;AAavF,+DAA+D;AAC/D,MAAM,WAAW,iBAAiB;IAChC,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,IAAI,CAAA;IAChF,mBAAmB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,IAAI,CAAA;IACnF,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IACzD,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;CACnC;AAED;;;;;;;;;GASG;AACH,qBAAa,oBAAqB,YAAW,YAAY;IACvD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAQ;IACtC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiC;IAC1D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgD;IAC/E,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA+B;IAChE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAmB;IACnD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmB;IAEjD;;;;;;;;;OASG;gBAED,YAAY,SAAM,EAClB,SAAS,SAAS,EAClB,cAAc,CAAC,EAAE,iBAAiB,EAClC,YAAY,CAAC,EAAE,iBAAiB;IAalC,OAAO,CAAC,cAAc;IAwBtB,OAAO,CAAC,WAAW;IAWnB;;;;;;;;;;OAUG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAkB7D;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,IAAI;IAI1D;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,IAAI;IAI3D;;;;;OAKG;IACH,OAAO,IAAI,OAAO;IAIlB;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAa7B"}
@@ -0,0 +1,191 @@
1
+ /**
2
+ * @module transports/postmessage
3
+ * @description PostMessage transport — sends Brainy RPC calls from a child iframe to its
4
+ * parent frame via `window.postMessage`.
5
+ *
6
+ * Designed for Workshop kit apps running inside WebContainer iframes. The kit app calls
7
+ * Brainy methods as normal via `createBrainyProxy(transport)`, and each call is forwarded
8
+ * to the parent Workshop frame which owns the actual Brainy instance.
9
+ *
10
+ * ## Wire protocol
11
+ *
12
+ * **Request** (kit iframe → parent):
13
+ * ```json
14
+ * { "type": "brainy:request", "id": "<uuid>", "method": "find", "args": [{ "query": "..." }] }
15
+ * ```
16
+ *
17
+ * **Response** (parent → kit iframe):
18
+ * ```json
19
+ * { "type": "brainy:response", "id": "<uuid>", "result": [...] }
20
+ * { "type": "brainy:response", "id": "<uuid>", "error": { "code": "RPC_ERROR", "message": "..." } }
21
+ * ```
22
+ *
23
+ * The `id` field correlates each response to its originating request. Pending calls are
24
+ * resolved or rejected when the matching response arrives.
25
+ *
26
+ * ## Usage
27
+ *
28
+ * ```typescript
29
+ * // Kit app (iframe):
30
+ * import { PostMessageTransport, createBrainyProxy } from '@soulcraft/sdk/client'
31
+ *
32
+ * const transport = new PostMessageTransport()
33
+ * const brainy = createBrainyProxy(transport)
34
+ *
35
+ * const results = await brainy.find({ query: 'candle inventory', limit: 10 })
36
+ * ```
37
+ *
38
+ * The parent frame must mount a `createBrainyPostMessageHandler` from `@soulcraft/sdk/server`
39
+ * to receive and respond to these messages.
40
+ *
41
+ * ## Security
42
+ *
43
+ * Messages are sent to `targetOrigin` (default `'*'`). For production use, pass the
44
+ * Workshop origin (e.g. `'https://workshop.soulcraft.com'`) to restrict delivery.
45
+ * The parent handler validates `event.source` and `event.origin` before dispatching.
46
+ */
47
+ import { SDKDisconnectedError, SDKTimeoutError, SDKAuthError, SDKForbiddenError, SDKRpcError, } from '../modules/brainy/errors.js';
48
+ /**
49
+ * PostMessage transport for kit apps running inside Workshop WebContainer iframes.
50
+ *
51
+ * Each `call()` posts a `brainy:request` message to `window.parent` and waits for
52
+ * a matching `brainy:response` message. Responses are correlated by a UUID `id` field
53
+ * generated per request.
54
+ *
55
+ * The transport installs a single `message` listener on `window` at construction time
56
+ * and removes it when `close()` is called.
57
+ */
58
+ export class PostMessageTransport {
59
+ _targetOrigin;
60
+ _timeoutMs;
61
+ _pending = new Map();
62
+ _eventHandlers = new Set();
63
+ _closed = false;
64
+ _messageListener;
65
+ _listenerWindow;
66
+ _parentWindow;
67
+ /**
68
+ * @param targetOrigin - The origin to which requests are sent. Defaults to `'*'`.
69
+ * Pass the Workshop origin in production for security
70
+ * (e.g. `'https://workshop.soulcraft.com'`).
71
+ * @param timeoutMs - Per-call timeout in milliseconds. Default: 30 000.
72
+ * @param listenerWindow - Window on which to listen for responses. Defaults to `window`.
73
+ * Pass a custom object in tests or non-browser environments.
74
+ * @param parentWindow - Window to which requests are posted. Defaults to `window.parent`.
75
+ * Pass a custom object in tests or non-browser environments.
76
+ */
77
+ constructor(targetOrigin = '*', timeoutMs = 30_000, listenerWindow, parentWindow) {
78
+ this._targetOrigin = targetOrigin;
79
+ this._timeoutMs = timeoutMs;
80
+ this._listenerWindow = listenerWindow ?? window;
81
+ this._parentWindow = parentWindow ?? window.parent;
82
+ this._messageListener = (event) => this._handleMessage(event);
83
+ this._listenerWindow.addEventListener('message', this._messageListener);
84
+ }
85
+ // ── Internal ──────────────────────────────────────────────────────────────
86
+ _handleMessage(event) {
87
+ const data = event.data;
88
+ if (!data || data.type !== 'brainy:response' || !data.id)
89
+ return;
90
+ const pending = this._pending.get(data.id);
91
+ if (!pending)
92
+ return;
93
+ clearTimeout(pending.timer);
94
+ this._pending.delete(data.id);
95
+ if ('error' in data && data.error) {
96
+ const { code, message } = data.error;
97
+ if (code === 'AUTH_ERROR') {
98
+ pending.reject(new SDKAuthError());
99
+ }
100
+ else if (code === 'FORBIDDEN') {
101
+ pending.reject(new SDKForbiddenError());
102
+ }
103
+ else {
104
+ pending.reject(new SDKRpcError(code, message));
105
+ }
106
+ }
107
+ else {
108
+ pending.resolve(data.result);
109
+ }
110
+ }
111
+ _generateId() {
112
+ // Use crypto.randomUUID if available (all modern browsers), fall back to
113
+ // a timestamp + random suffix for older environments.
114
+ if (typeof crypto !== 'undefined' && crypto.randomUUID) {
115
+ return crypto.randomUUID();
116
+ }
117
+ return `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
118
+ }
119
+ // ── SDKTransport interface ─────────────────────────────────────────────────
120
+ /**
121
+ * Dispatch a Brainy RPC call via `window.parent.postMessage`.
122
+ *
123
+ * @param method - Dot-separated Brainy method name (e.g. `'find'`, `'vfs.readFile'`).
124
+ * @param args - Positional arguments forwarded to Brainy on the parent frame.
125
+ * @returns A Promise that resolves with the Brainy method's return value.
126
+ * @throws {@link SDKDisconnectedError} if the transport has been closed.
127
+ * @throws {@link SDKTimeoutError} if no response arrives within `timeoutMs`.
128
+ * @throws {@link SDKAuthError} if the parent responds with an auth error.
129
+ * @throws {@link SDKRpcError} if the parent responds with a Brainy-level error.
130
+ */
131
+ async call(method, args) {
132
+ if (this._closed)
133
+ throw new SDKDisconnectedError();
134
+ const id = this._generateId();
135
+ return new Promise((resolve, reject) => {
136
+ const timer = setTimeout(() => {
137
+ this._pending.delete(id);
138
+ reject(new SDKTimeoutError(method));
139
+ }, this._timeoutMs);
140
+ this._pending.set(id, { resolve, reject, timer });
141
+ const message = { type: 'brainy:request', id, method, args };
142
+ this._parentWindow.postMessage(message, this._targetOrigin);
143
+ });
144
+ }
145
+ /**
146
+ * Register a handler for real-time Brainy change events.
147
+ *
148
+ * Change events are forwarded from the parent frame via `brainy:event` messages.
149
+ * The parent handler posts these when Brainy fires a data change.
150
+ *
151
+ * @param handler - Called with each {@link BrainyChangeEvent}.
152
+ */
153
+ onEvent(handler) {
154
+ this._eventHandlers.add(handler);
155
+ }
156
+ /**
157
+ * Remove a previously registered change event handler.
158
+ *
159
+ * @param handler - The same function reference passed to {@link onEvent}.
160
+ */
161
+ offEvent(handler) {
162
+ this._eventHandlers.delete(handler);
163
+ }
164
+ /**
165
+ * Returns `true` when the transport is open.
166
+ *
167
+ * PostMessage is always available as long as the transport has not been closed —
168
+ * it relies on `window.parent` which is always present inside an iframe.
169
+ */
170
+ isAlive() {
171
+ return !this._closed;
172
+ }
173
+ /**
174
+ * Close the transport, removing the message listener and rejecting all pending calls.
175
+ *
176
+ * After calling `close()`, any further `call()` invocations throw `SDKDisconnectedError`.
177
+ */
178
+ async close() {
179
+ if (this._closed)
180
+ return;
181
+ this._closed = true;
182
+ this._listenerWindow.removeEventListener('message', this._messageListener);
183
+ const error = new SDKDisconnectedError();
184
+ for (const [id, pending] of this._pending) {
185
+ clearTimeout(pending.timer);
186
+ pending.reject(error);
187
+ this._pending.delete(id);
188
+ }
189
+ }
190
+ }
191
+ //# sourceMappingURL=postmessage.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"postmessage.js","sourceRoot":"","sources":["../../src/transports/postmessage.ts"],"names":[],"mappings":"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"}