@soulcraft/sdk 2.0.0 → 2.0.2

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.
Files changed (93) hide show
  1. package/dist/client/index.d.ts +5 -38
  2. package/dist/client/index.d.ts.map +1 -1
  3. package/dist/client/index.js +5 -47
  4. package/dist/client/index.js.map +1 -1
  5. package/dist/client/namespace-proxy.d.ts +3 -4
  6. package/dist/client/namespace-proxy.d.ts.map +1 -1
  7. package/dist/client/namespace-proxy.js +3 -4
  8. package/dist/client/namespace-proxy.js.map +1 -1
  9. package/dist/index.d.ts +6 -6
  10. package/dist/index.d.ts.map +1 -1
  11. package/dist/index.js +4 -4
  12. package/dist/index.js.map +1 -1
  13. package/dist/modules/hall/browser.d.ts +83 -27
  14. package/dist/modules/hall/browser.d.ts.map +1 -1
  15. package/dist/modules/hall/browser.js +238 -49
  16. package/dist/modules/hall/browser.js.map +1 -1
  17. package/dist/modules/hall/media.d.ts +164 -0
  18. package/dist/modules/hall/media.d.ts.map +1 -0
  19. package/dist/modules/hall/media.js +182 -0
  20. package/dist/modules/hall/media.js.map +1 -0
  21. package/dist/modules/hall/server.d.ts +83 -6
  22. package/dist/modules/hall/server.d.ts.map +1 -1
  23. package/dist/modules/hall/server.js +206 -9
  24. package/dist/modules/hall/server.js.map +1 -1
  25. package/dist/modules/hall/types.d.ts +548 -25
  26. package/dist/modules/hall/types.d.ts.map +1 -1
  27. package/dist/modules/hall/types.js +12 -7
  28. package/dist/modules/hall/types.js.map +1 -1
  29. package/dist/server/hall-handlers.d.ts +40 -12
  30. package/dist/server/hall-handlers.d.ts.map +1 -1
  31. package/dist/server/hall-handlers.js +40 -12
  32. package/dist/server/hall-handlers.js.map +1 -1
  33. package/dist/server/handlers/chat/engine.d.ts.map +1 -1
  34. package/dist/server/handlers/chat/engine.js +5 -1
  35. package/dist/server/handlers/chat/engine.js.map +1 -1
  36. package/dist/server/handlers/chat/types.d.ts +17 -2
  37. package/dist/server/handlers/chat/types.d.ts.map +1 -1
  38. package/dist/server/hono-router.d.ts +2 -9
  39. package/dist/server/hono-router.d.ts.map +1 -1
  40. package/dist/server/hono-router.js +2 -46
  41. package/dist/server/hono-router.js.map +1 -1
  42. package/dist/server/index.d.ts +4 -19
  43. package/dist/server/index.d.ts.map +1 -1
  44. package/dist/server/index.js +10 -29
  45. package/dist/server/index.js.map +1 -1
  46. package/dist/types.d.ts +2 -41
  47. package/dist/types.d.ts.map +1 -1
  48. package/docs/ADR-005-hall-integration.md +449 -0
  49. package/package.json +1 -1
  50. package/dist/client/create-client-sdk.d.ts +0 -113
  51. package/dist/client/create-client-sdk.d.ts.map +0 -1
  52. package/dist/client/create-client-sdk.js +0 -169
  53. package/dist/client/create-client-sdk.js.map +0 -1
  54. package/dist/modules/app-context/index.d.ts +0 -214
  55. package/dist/modules/app-context/index.d.ts.map +0 -1
  56. package/dist/modules/app-context/index.js +0 -569
  57. package/dist/modules/app-context/index.js.map +0 -1
  58. package/dist/modules/billing/firestore-provider.d.ts +0 -60
  59. package/dist/modules/billing/firestore-provider.d.ts.map +0 -1
  60. package/dist/modules/billing/firestore-provider.js +0 -315
  61. package/dist/modules/billing/firestore-provider.js.map +0 -1
  62. package/dist/modules/brainy/proxy.d.ts +0 -48
  63. package/dist/modules/brainy/proxy.d.ts.map +0 -1
  64. package/dist/modules/brainy/proxy.js +0 -95
  65. package/dist/modules/brainy/proxy.js.map +0 -1
  66. package/dist/server/create-sdk.d.ts +0 -74
  67. package/dist/server/create-sdk.d.ts.map +0 -1
  68. package/dist/server/create-sdk.js +0 -104
  69. package/dist/server/create-sdk.js.map +0 -1
  70. package/dist/server/from-license.d.ts +0 -252
  71. package/dist/server/from-license.d.ts.map +0 -1
  72. package/dist/server/from-license.js +0 -349
  73. package/dist/server/from-license.js.map +0 -1
  74. package/dist/server/handlers.d.ts +0 -312
  75. package/dist/server/handlers.d.ts.map +0 -1
  76. package/dist/server/handlers.js +0 -376
  77. package/dist/server/handlers.js.map +0 -1
  78. package/dist/server/postmessage-handler.d.ts +0 -152
  79. package/dist/server/postmessage-handler.d.ts.map +0 -1
  80. package/dist/server/postmessage-handler.js +0 -138
  81. package/dist/server/postmessage-handler.js.map +0 -1
  82. package/dist/transports/http.d.ts +0 -86
  83. package/dist/transports/http.d.ts.map +0 -1
  84. package/dist/transports/http.js +0 -137
  85. package/dist/transports/http.js.map +0 -1
  86. package/dist/transports/postmessage.d.ts +0 -159
  87. package/dist/transports/postmessage.d.ts.map +0 -1
  88. package/dist/transports/postmessage.js +0 -207
  89. package/dist/transports/postmessage.js.map +0 -1
  90. package/dist/transports/workshop.d.ts +0 -173
  91. package/dist/transports/workshop.d.ts.map +0 -1
  92. package/dist/transports/workshop.js +0 -307
  93. package/dist/transports/workshop.js.map +0 -1
@@ -1,207 +0,0 @@
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`. Always pass the explicit Workshop origin
44
- * (e.g. `'https://workshop.soulcraft.com'`). Using `'*'` broadcasts to any origin
45
- * and must never be used in production — it leaks Brainy RPC responses to third-party
46
- * frames. The parent handler validates `event.source` and `event.origin` before dispatching.
47
- */
48
- import { SDKDisconnectedError, SDKTimeoutError, SDKAuthError, SDKForbiddenError, SDKRpcError, } from '../modules/brainy/errors.js';
49
- /**
50
- * PostMessage transport for kit apps running inside Workshop WebContainer iframes.
51
- *
52
- * Each `call()` posts a `brainy:request` message to `window.parent` and waits for
53
- * a matching `brainy:response` message. Responses are correlated by a UUID `id` field
54
- * generated per request.
55
- *
56
- * The transport installs a single `message` listener on `window` at construction time
57
- * and removes it when `close()` is called.
58
- */
59
- export class PostMessageTransport {
60
- _targetOrigin;
61
- _timeoutMs;
62
- _pending = new Map();
63
- _eventHandlers = new Set();
64
- _closed = false;
65
- _messageListener;
66
- _listenerWindow;
67
- _parentWindow;
68
- /**
69
- * @param targetOrigin - The origin to which requests are sent.
70
- * Must be an explicit origin (e.g. `'https://workshop.soulcraft.com'`).
71
- * Never use `'*'` in production — it broadcasts RPC responses to any origin.
72
- * @param timeoutMs - Per-call timeout in milliseconds. Default: 30 000.
73
- * @param listenerWindow - Window on which to listen for responses. Defaults to `window`.
74
- * Pass a custom object in tests or non-browser environments.
75
- * @param parentWindow - Window to which requests are posted. Defaults to `window.parent`.
76
- * Pass a custom object in tests or non-browser environments.
77
- */
78
- constructor(targetOrigin, timeoutMs = 30_000, listenerWindow, parentWindow) {
79
- this._targetOrigin = targetOrigin;
80
- this._timeoutMs = timeoutMs;
81
- this._listenerWindow = listenerWindow ?? window;
82
- this._parentWindow = parentWindow ?? window.parent;
83
- this._messageListener = (event) => this._handleMessage(event);
84
- this._listenerWindow.addEventListener('message', this._messageListener);
85
- }
86
- // ── Internal ──────────────────────────────────────────────────────────────
87
- _handleMessage(event) {
88
- const data = event.data;
89
- if (!data || typeof data.type !== 'string')
90
- return;
91
- // Real-time change event forwarded from the parent frame.
92
- if (data.type === 'brainy:event') {
93
- const msg = data;
94
- for (const handler of this._eventHandlers) {
95
- try {
96
- handler(msg.event);
97
- }
98
- catch (err) {
99
- console.error('[SDK/postmessage] Event handler threw', err);
100
- }
101
- }
102
- return;
103
- }
104
- if (data.type !== 'brainy:response' || !('id' in data) || !data.id)
105
- return;
106
- const pending = this._pending.get(data.id);
107
- if (!pending)
108
- return;
109
- clearTimeout(pending.timer);
110
- this._pending.delete(data.id);
111
- if ('error' in data && data.error) {
112
- const { code, message } = data.error;
113
- if (code === 'AUTH_ERROR') {
114
- pending.reject(new SDKAuthError());
115
- }
116
- else if (code === 'FORBIDDEN') {
117
- pending.reject(new SDKForbiddenError());
118
- }
119
- else {
120
- pending.reject(new SDKRpcError(code, message));
121
- }
122
- }
123
- else {
124
- pending.resolve(data.result);
125
- }
126
- }
127
- _generateId() {
128
- // Use crypto.randomUUID if available (all modern browsers), fall back to
129
- // a timestamp + random suffix for older environments.
130
- if (typeof crypto !== 'undefined' && crypto.randomUUID) {
131
- return crypto.randomUUID();
132
- }
133
- return `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
134
- }
135
- // ── SDKTransport interface ─────────────────────────────────────────────────
136
- /**
137
- * Dispatch a Brainy RPC call via `window.parent.postMessage`.
138
- *
139
- * @param method - Dot-separated Brainy method name (e.g. `'find'`, `'vfs.readFile'`).
140
- * @param args - Positional arguments forwarded to Brainy on the parent frame.
141
- * @returns A Promise that resolves with the Brainy method's return value.
142
- * @throws {@link SDKDisconnectedError} if the transport has been closed.
143
- * @throws {@link SDKTimeoutError} if no response arrives within `timeoutMs`.
144
- * @throws {@link SDKAuthError} if the parent responds with an auth error.
145
- * @throws {@link SDKRpcError} if the parent responds with a Brainy-level error.
146
- */
147
- async call(method, args) {
148
- if (this._closed)
149
- throw new SDKDisconnectedError();
150
- const id = this._generateId();
151
- return new Promise((resolve, reject) => {
152
- const timer = setTimeout(() => {
153
- this._pending.delete(id);
154
- reject(new SDKTimeoutError(method));
155
- }, this._timeoutMs);
156
- this._pending.set(id, { resolve, reject, timer });
157
- const message = { type: 'brainy:request', id, method, args };
158
- this._parentWindow.postMessage(message, this._targetOrigin);
159
- });
160
- }
161
- /**
162
- * Register a handler for real-time Brainy change events.
163
- *
164
- * Change events are forwarded from the parent frame via `brainy:event` messages.
165
- * The parent handler posts these when Brainy fires a data change.
166
- *
167
- * @param handler - Called with each {@link BrainyChangeEvent}.
168
- */
169
- onEvent(handler) {
170
- this._eventHandlers.add(handler);
171
- }
172
- /**
173
- * Remove a previously registered change event handler.
174
- *
175
- * @param handler - The same function reference passed to {@link onEvent}.
176
- */
177
- offEvent(handler) {
178
- this._eventHandlers.delete(handler);
179
- }
180
- /**
181
- * Returns `true` when the transport is open.
182
- *
183
- * PostMessage is always available as long as the transport has not been closed —
184
- * it relies on `window.parent` which is always present inside an iframe.
185
- */
186
- isAlive() {
187
- return !this._closed;
188
- }
189
- /**
190
- * Close the transport, removing the message listener and rejecting all pending calls.
191
- *
192
- * After calling `close()`, any further `call()` invocations throw `SDKDisconnectedError`.
193
- */
194
- async close() {
195
- if (this._closed)
196
- return;
197
- this._closed = true;
198
- this._listenerWindow.removeEventListener('message', this._messageListener);
199
- const error = new SDKDisconnectedError();
200
- for (const [id, pending] of this._pending) {
201
- clearTimeout(pending.timer);
202
- pending.reject(error);
203
- this._pending.delete(id);
204
- }
205
- }
206
- }
207
- //# sourceMappingURL=postmessage.js.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"postmessage.js","sourceRoot":"","sources":["../../src/transports/postmessage.ts"],"names":[],"mappings":"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"}
@@ -1,173 +0,0 @@
1
- /**
2
- * @module transports/workshop
3
- * @description PostMessage transport for non-brainy API calls from kit iframes to
4
- * the Workshop parent frame.
5
- *
6
- * While {@link PostMessageTransport} handles Brainy RPC (`brainy:request` /
7
- * `brainy:response`), this transport handles generic HTTP-style API calls —
8
- * AI chat streaming, Hall room joins, Pulse analytics, file operations, and
9
- * notifications — using the `workshop:request` / `workshop:response` /
10
- * `workshop:stream` wire protocol.
11
- *
12
- * The parent frame (PreviewFrame.svelte) receives `workshop:request` messages,
13
- * forwards them as real HTTP requests to Workshop's backend, and relays the
14
- * response back via `workshop:response` (JSON) or `workshop:stream` (SSE chunks).
15
- *
16
- * ## Wire protocol
17
- *
18
- * **Request** (kit iframe → parent):
19
- * ```json
20
- * { "type": "workshop:request", "id": "<uuid>", "path": "/api/ai/chat",
21
- * "method": "POST", "body": "{...}", "stream": true, "headers": {} }
22
- * ```
23
- *
24
- * **Response** (parent → kit iframe, non-streaming):
25
- * ```json
26
- * { "type": "workshop:response", "id": "<uuid>", "result": {...} }
27
- * { "type": "workshop:response", "id": "<uuid>", "error": { "code": "...", "message": "..." } }
28
- * ```
29
- *
30
- * **Stream chunk** (parent → kit iframe, streaming):
31
- * ```json
32
- * { "type": "workshop:stream", "id": "<uuid>", "chunk": "..." }
33
- * { "type": "workshop:stream", "id": "<uuid>", "done": true }
34
- * { "type": "workshop:stream", "id": "<uuid>", "error": "..." }
35
- * ```
36
- *
37
- * ## Usage
38
- *
39
- * ```typescript
40
- * import { WorkshopTransport } from '@soulcraft/sdk/client'
41
- *
42
- * const transport = new WorkshopTransport('https://workshop.soulcraft.com')
43
- *
44
- * // JSON call
45
- * const result = await transport.call('/api/hall/rooms/my-room/join', 'POST', '{"audio":true}')
46
- *
47
- * // Streaming call (AI chat)
48
- * for await (const chunk of transport.stream('/api/ai/chat', 'POST', body)) {
49
- * process.stdout.write(chunk)
50
- * }
51
- * ```
52
- *
53
- * @see {@link PostMessageTransport} for Brainy-specific RPC transport.
54
- */
55
- /** An API request posted from the kit iframe to the Workshop parent frame. */
56
- export interface WorkshopRequest {
57
- type: 'workshop:request';
58
- id: string;
59
- /** API path, e.g. '/api/ai/chat', '/api/pulse/track'. */
60
- path: string;
61
- /** HTTP method. */
62
- method: 'GET' | 'POST' | 'PUT' | 'DELETE';
63
- /** JSON-serialized body for POST/PUT. */
64
- body?: string | undefined;
65
- /** If true, the parent relays the response as `workshop:stream` chunks. */
66
- stream?: boolean | undefined;
67
- /** Extra headers (e.g. Content-Type for non-JSON bodies). */
68
- headers?: Record<string, string> | undefined;
69
- }
70
- /** A JSON response posted from the parent to the kit iframe. */
71
- export interface WorkshopResponse {
72
- type: 'workshop:response';
73
- id: string;
74
- result?: unknown;
75
- error?: {
76
- code: string;
77
- message: string;
78
- };
79
- }
80
- /** A streaming chunk posted from the parent to the kit iframe. */
81
- export interface WorkshopStreamChunk {
82
- type: 'workshop:stream';
83
- id: string;
84
- /** SSE data line content (parsed JSON string from the `data:` line). */
85
- chunk?: string;
86
- /** True when the stream has ended. */
87
- done?: boolean;
88
- /** Error message if the stream failed. */
89
- error?: string;
90
- }
91
- /** Minimal window interface for testability. */
92
- export interface WorkshopTransportWindow {
93
- addEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
94
- removeEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
95
- postMessage(message: unknown, targetOrigin: string): void;
96
- readonly parent: WorkshopTransportWindow;
97
- }
98
- /**
99
- * PostMessage transport for generic (non-brainy) API calls from kit iframes.
100
- *
101
- * Each `call()` posts a `workshop:request` message to `window.parent` and awaits
102
- * a matching `workshop:response`. For streaming endpoints, `stream()` collects
103
- * `workshop:stream` chunks and yields them as an `AsyncIterable<string>`.
104
- *
105
- * @example
106
- * ```typescript
107
- * const t = new WorkshopTransport(workshopOrigin)
108
- *
109
- * // Fire-and-forget analytics
110
- * t.call('/api/pulse/track', 'POST', JSON.stringify({ event: 'page_view' }))
111
- *
112
- * // Stream AI tokens
113
- * for await (const token of t.stream('/api/ai/chat', 'POST', body)) {
114
- * output += token
115
- * }
116
- * ```
117
- */
118
- export declare class WorkshopTransport {
119
- private readonly _targetOrigin;
120
- private readonly _timeoutMs;
121
- private readonly _pendingCalls;
122
- private readonly _pendingStreams;
123
- private _closed;
124
- private readonly _messageListener;
125
- private readonly _listenerWindow;
126
- private readonly _parentWindow;
127
- /**
128
- * @param targetOrigin - The Workshop parent frame's origin for postMessage security.
129
- * Must be an explicit origin in production; `'*'` is acceptable only in dev.
130
- * @param timeoutMs - Per-call timeout in milliseconds. Default: 60 000 (longer than
131
- * brainy RPC because AI chat streams can take a while to start).
132
- * @param listenerWindow - Window for message events. Defaults to `window`.
133
- * @param parentWindow - Window to post messages to. Defaults to `window.parent`.
134
- */
135
- constructor(targetOrigin: string, timeoutMs?: number, listenerWindow?: WorkshopTransportWindow, parentWindow?: WorkshopTransportWindow);
136
- private _handleMessage;
137
- private _streamTimeout;
138
- private _generateId;
139
- /**
140
- * Send a JSON API call through the PostMessage relay.
141
- *
142
- * @param path - API endpoint path (e.g. '/api/hall/rooms/my-room/join').
143
- * @param method - HTTP method.
144
- * @param body - JSON-serialized request body.
145
- * @param headers - Extra headers to forward.
146
- * @returns The parsed JSON response body.
147
- * @throws {Error} If the transport is closed, the request times out, or the
148
- * parent responds with an error.
149
- */
150
- call(path: string, method?: 'GET' | 'POST' | 'PUT' | 'DELETE', body?: string, headers?: Record<string, string>): Promise<unknown>;
151
- /**
152
- * Send a streaming API call through the PostMessage relay.
153
- *
154
- * The parent frame reads the HTTP response as SSE chunks and forwards each as
155
- * a `workshop:stream` message. This method yields each chunk as it arrives.
156
- *
157
- * @param path - API endpoint path (e.g. '/api/ai/chat').
158
- * @param method - HTTP method (typically 'POST').
159
- * @param body - JSON-serialized request body.
160
- * @param headers - Extra headers to forward.
161
- * @returns An async iterable of string chunks.
162
- */
163
- stream(path: string, method?: 'GET' | 'POST' | 'PUT' | 'DELETE', body?: string, headers?: Record<string, string>): AsyncIterable<string>;
164
- /**
165
- * Returns `true` if the transport is open and usable.
166
- */
167
- isAlive(): boolean;
168
- /**
169
- * Close the transport, removing the message listener and rejecting all pending calls.
170
- */
171
- close(): void;
172
- }
173
- //# sourceMappingURL=workshop.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"workshop.d.ts","sourceRoot":"","sources":["../../src/transports/workshop.ts"],"names":[],"mappings":"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"}