@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.
- package/dist/client/index.d.ts +6 -3
- package/dist/client/index.d.ts.map +1 -1
- package/dist/client/index.js +5 -3
- package/dist/client/index.js.map +1 -1
- package/dist/modules/license/index.js +2 -2
- package/dist/modules/license/index.js.map +1 -1
- package/dist/server/from-license.d.ts +213 -0
- package/dist/server/from-license.d.ts.map +1 -0
- package/dist/server/from-license.js +305 -0
- package/dist/server/from-license.js.map +1 -0
- package/dist/server/index.d.ts +4 -0
- package/dist/server/index.d.ts.map +1 -1
- package/dist/server/index.js +4 -0
- package/dist/server/index.js.map +1 -1
- package/dist/server/postmessage-handler.d.ts +127 -0
- package/dist/server/postmessage-handler.d.ts.map +1 -0
- package/dist/server/postmessage-handler.js +125 -0
- package/dist/server/postmessage-handler.js.map +1 -0
- package/dist/transports/postmessage.d.ts +153 -0
- package/dist/transports/postmessage.d.ts.map +1 -0
- package/dist/transports/postmessage.js +191 -0
- package/dist/transports/postmessage.js.map +1 -0
- package/package.json +1 -1
|
@@ -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"}
|
package/dist/server/index.js
CHANGED
|
@@ -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';
|
package/dist/server/index.js.map
CHANGED
|
@@ -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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"}
|