@soulcraft/sdk 1.6.2 → 2.0.0

package/dist/server/handlers/publish.d.ts

@@ -0,0 +1,102 @@
+/**
+ * @module server/handlers/publish
+ * @description Publish namespace handler — Living Links, Venue deploy, and
+ * Academy publish.
+ *
+ * Absorbs Workshop `routes/publish.ts`, `routes/deploy.ts`, and
+ * `routes/academy-publish.ts`. The handler delegates to an injected
+ * `PublishBackend` interface for link management and destination deployments.
+ *
+ * Methods:
+ * - `createLink` — Create a Living Link for sharing
+ * - `getLink` — Get an existing link by ID
+ * - `deleteLink` — Delete a link
+ * - `listLinks` — List all links for the workspace
+ * - `checkSlug` — Check slug availability
+ * - `getProjectInfo` — Get project info for publishing
+ * - `deployToVenue` — Deploy workspace to Venue
+ * - `publishToAcademy` — Publish content as Academy course
+ * - `to` — Unified publish dispatcher
+ */
+import type { NamespaceProvider } from '../namespace-router.js';
+import type { PublishedLink } from '../../namespaces.js';
+/**
+ * Publish backend interface for link management and deployment.
+ *
+ * Products implement this to connect to their publish registry and
+ * deployment infrastructure.
+ */
+export interface PublishBackend {
+    /** Create a Living Link entry. */
+    createLink(userId: string, workspaceId: string, options: {
+        type: string;
+        slug?: string;
+        entityIds?: string[];
+        expiresIn?: number;
+    }): Promise<PublishedLink>;
+    /** Get a link by ID. */
+    getLink(linkId: string): Promise<PublishedLink | null>;
+    /** Delete a link. */
+    deleteLink(linkId: string): Promise<void>;
+    /** List all links for a workspace. */
+    listLinks(userId: string, workspaceId: string): Promise<PublishedLink[]>;
+    /** Check if a slug is available. */
+    checkSlug(slug: string): Promise<boolean>;
+}
+/**
+ * Venue deployment service interface.
+ */
+export interface VenueDeployService {
+    deploy(options: {
+        venueHandle: string;
+        venueSlug: string;
+        deploySecret: string;
+        workspaceId: string;
+        userId: string;
+    }): Promise<{
+        url: string;
+        deployedAt: string;
+    }>;
+}
+/**
+ * Academy publish service interface.
+ */
+export interface AcademyPublishService {
+    publish(options: {
+        academyUrl: string;
+        publishSecret: string;
+        courseTitle?: string;
+        lessonIds?: string[];
+        workspaceId: string;
+        userId: string;
+    }): Promise<{
+        courseId: string;
+        url: string;
+    }>;
+}
+/**
+ * Options for {@link createPublishHandler}.
+ */
+export interface PublishHandlerOptions {
+    /** Publish backend for link management. */
+    publishBackend: PublishBackend;
+    /** Venue deployment service. Optional — `deployToVenue` throws if missing. */
+    venueService?: VenueDeployService;
+    /** Academy publish service. Optional — `publishToAcademy` throws if missing. */
+    academyService?: AcademyPublishService;
+    /** Pre-configured Venue deploy secret (for `to('venue')` unified API). */
+    venueDeploySecret?: string;
+    /** Pre-configured Academy URL and secret (for `to('academy')` unified API). */
+    academyConfig?: {
+        url: string;
+        secret: string;
+    };
+}
+/**
+ * Creates the `publish` namespace handler.
+ *
+ * @param options - Publish handler dependencies.
+ * @returns A {@link NamespaceProvider} implementing {@link PublishNamespace}.
+ */
+export declare function createPublishHandler(options: PublishHandlerOptions): NamespaceProvider;
+//# sourceMappingURL=publish.d.ts.map

package/dist/server/handlers/publish.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/publish.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAkB,MAAM,wBAAwB,CAAA;AAC/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAMxD;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,kCAAkC;IAClC,UAAU,CACR,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GACjF,OAAO,CAAC,aAAa,CAAC,CAAA;IAEzB,wBAAwB;IACxB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAA;IAEtD,qBAAqB;IACrB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEzC,sCAAsC;IACtC,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAA;IAExE,oCAAoC;IACpC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CAC1C;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,OAAO,EAAE;QACd,WAAW,EAAE,MAAM,CAAA;QACnB,SAAS,EAAE,MAAM,CAAA;QACjB,YAAY,EAAE,MAAM,CAAA;QACpB,WAAW,EAAE,MAAM,CAAA;QACnB,MAAM,EAAE,MAAM,CAAA;KACf,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACjD;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,OAAO,EAAE;QACf,UAAU,EAAE,MAAM,CAAA;QAClB,aAAa,EAAE,MAAM,CAAA;QACrB,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;QACpB,WAAW,EAAE,MAAM,CAAA;QACnB,MAAM,EAAE,MAAM,CAAA;KACf,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAC/C;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,2CAA2C;IAC3C,cAAc,EAAE,cAAc,CAAA;IAC9B,8EAA8E;IAC9E,YAAY,CAAC,EAAE,kBAAkB,CAAA;IACjC,gFAAgF;IAChF,cAAc,CAAC,EAAE,qBAAqB,CAAA;IACtC,0EAA0E;IAC1E,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,+EAA+E;IAC/E,aAAa,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;CAChD;AAMD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,iBAAiB,CAyItF"}

package/dist/server/handlers/publish.js

@@ -0,0 +1,130 @@
+/**
+ * @module server/handlers/publish
+ * @description Publish namespace handler — Living Links, Venue deploy, and
+ * Academy publish.
+ *
+ * Absorbs Workshop `routes/publish.ts`, `routes/deploy.ts`, and
+ * `routes/academy-publish.ts`. The handler delegates to an injected
+ * `PublishBackend` interface for link management and destination deployments.
+ *
+ * Methods:
+ * - `createLink` — Create a Living Link for sharing
+ * - `getLink` — Get an existing link by ID
+ * - `deleteLink` — Delete a link
+ * - `listLinks` — List all links for the workspace
+ * - `checkSlug` — Check slug availability
+ * - `getProjectInfo` — Get project info for publishing
+ * - `deployToVenue` — Deploy workspace to Venue
+ * - `publishToAcademy` — Publish content as Academy course
+ * - `to` — Unified publish dispatcher
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Handler factory
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Creates the `publish` namespace handler.
+ *
+ * @param options - Publish handler dependencies.
+ * @returns A {@link NamespaceProvider} implementing {@link PublishNamespace}.
+ */
+export function createPublishHandler(options) {
+    const { publishBackend, venueService, academyService, venueDeploySecret, academyConfig } = options;
+    return {
+        async createLink(linkOptions, ctx) {
+            return publishBackend.createLink(ctx.user.emailHash, ctx.workspaceId, linkOptions);
+        },
+        async getLink(linkId) {
+            return publishBackend.getLink(linkId);
+        },
+        async deleteLink(linkId) {
+            return publishBackend.deleteLink(linkId);
+        },
+        async listLinks(ctx) {
+            return publishBackend.listLinks(ctx.user.emailHash, ctx.workspaceId);
+        },
+        async checkSlug(slug) {
+            const available = await publishBackend.checkSlug(slug);
+            return { available };
+        },
+        async getProjectInfo(ctx) {
+            const { brain } = ctx;
+            const stats = await brain.indexStats();
+            let kitId = '';
+            try {
+                const meta = await brain.vfs.getxattr('/', 'workshop.project');
+                kitId = meta?.kitId || '';
+            }
+            catch { /* no project metadata */ }
+            let fileCount = 0;
+            try {
+                const entries = await brain.vfs.readdir('/', { recursive: true });
+                fileCount = Array.isArray(entries) ? entries.length : 0;
+            }
+            catch { /* empty VFS */ }
+            return {
+                name: ctx.workspaceId, // Products override via xattr
+                kitId,
+                entityCount: stats.entities ?? 0,
+                fileCount,
+            };
+        },
+        async deployToVenue(deployOptions, ctx) {
+            if (!venueService) {
+                throw new Error('Venue deployment is not configured — provide a VenueDeployService');
+            }
+            return venueService.deploy({
+                ...deployOptions,
+                workspaceId: ctx.workspaceId,
+                userId: ctx.user.emailHash,
+            });
+        },
+        async publishToAcademy(academyOptions, ctx) {
+            if (!academyService) {
+                throw new Error('Academy publish is not configured — provide an AcademyPublishService');
+            }
+            return academyService.publish({
+                ...academyOptions,
+                workspaceId: ctx.workspaceId,
+                userId: ctx.user.emailHash,
+            });
+        },
+        async to(destination, toOptions, ctx) {
+            const now = new Date().toISOString();
+            if (destination === 'venue') {
+                if (!venueService) {
+                    throw new Error('Venue deployment is not configured');
+                }
+                if (!venueDeploySecret) {
+                    throw new Error('Venue deploy secret is not configured — set WORKSHOP_DEPLOY_SECRET');
+                }
+                const result = await venueService.deploy({
+                    venueHandle: toOptions?.handle || '',
+                    venueSlug: toOptions?.slug || 'main',
+                    deploySecret: venueDeploySecret,
+                    workspaceId: ctx.workspaceId,
+                    userId: ctx.user.emailHash,
+                });
+                return { url: result.url, publishedAt: result.deployedAt };
+            }
+            if (destination === 'academy') {
+                if (!academyService) {
+                    throw new Error('Academy publish is not configured');
+                }
+                if (!academyConfig) {
+                    throw new Error('Academy URL/secret not configured — set ACADEMY_PUBLISH_SECRET');
+                }
+                const result = await academyService.publish({
+                    academyUrl: academyConfig.url,
+                    publishSecret: academyConfig.secret,
+                    ...(toOptions?.courseTitle != null ? { courseTitle: toOptions.courseTitle } : {}),
+                    ...(toOptions?.entityIds != null ? { lessonIds: toOptions.entityIds } : {}),
+                    workspaceId: ctx.workspaceId,
+                    userId: ctx.user.emailHash,
+                });
+                return { url: result.url, destinationId: result.courseId, publishedAt: now };
+            }
+            throw new Error(`Unknown publish destination: ${destination}`);
+        },
+    };
+}
+//# sourceMappingURL=publish.js.map

package/dist/server/handlers/publish.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish.js","sourceRoot":"","sources":["../../../src/server/handlers/publish.ts"],"names":[],"mappings":"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"}

package/dist/server/handlers/pulse.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @module server/handlers/pulse
+ * @description Pulse namespace handler — fire-and-forget analytics event forwarding.
+ *
+ * Absorbs the `pulse` section of Workshop `routes/app-services.ts`. Events are
+ * forwarded to the configured analytics sink URL via HTTP POST. The call returns
+ * immediately; delivery is best-effort (failures are logged, not thrown).
+ *
+ * Methods:
+ * - `track` — Forward an analytics event to the configured sink
+ */
+import type { NamespaceProvider } from '../namespace-router.js';
+/**
+ * Options for {@link createPulseHandler}.
+ */
+export interface PulseHandlerOptions {
+    /**
+     * Analytics sink URL to forward events to.
+     * If not provided, events are logged to the console in dev mode and silently
+     * dropped in production.
+     */
+    sinkUrl?: string;
+    /**
+     * Optional bearer token for authenticating with the analytics sink.
+     */
+    sinkToken?: string;
+    /**
+     * Request timeout in milliseconds. Default: 5000.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Creates the `pulse` namespace handler.
+ *
+ * @param options - Pulse handler configuration.
+ * @returns A {@link NamespaceProvider} implementing {@link PulseNamespace}.
+ */
+export declare function createPulseHandler(options?: PulseHandlerOptions): NamespaceProvider;
+//# sourceMappingURL=pulse.d.ts.map

package/dist/server/handlers/pulse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pulse.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/pulse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAkB,MAAM,wBAAwB,CAAA;AAM/E;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAMD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,iBAAiB,CAiEnF"}

package/dist/server/handlers/pulse.js

@@ -0,0 +1,78 @@
+/**
+ * @module server/handlers/pulse
+ * @description Pulse namespace handler — fire-and-forget analytics event forwarding.
+ *
+ * Absorbs the `pulse` section of Workshop `routes/app-services.ts`. Events are
+ * forwarded to the configured analytics sink URL via HTTP POST. The call returns
+ * immediately; delivery is best-effort (failures are logged, not thrown).
+ *
+ * Methods:
+ * - `track` — Forward an analytics event to the configured sink
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Handler factory
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Creates the `pulse` namespace handler.
+ *
+ * @param options - Pulse handler configuration.
+ * @returns A {@link NamespaceProvider} implementing {@link PulseNamespace}.
+ */
+export function createPulseHandler(options) {
+    const sinkUrl = options?.sinkUrl;
+    const sinkToken = options?.sinkToken;
+    const timeoutMs = options?.timeoutMs ?? 5000;
+    return {
+        /**
+         * Track an analytics event.
+         *
+         * Forwards the event to the configured sink URL. Best-effort delivery —
+         * failures are logged but do not throw. When no sink URL is configured,
+         * events are silently dropped (or logged in development).
+         *
+         * @param event - Event name (e.g. `'page_view'`, `'entity_created'`).
+         * @param properties - Optional key-value metadata for the event.
+         * @param ctx - Handler context with user identity.
+         */
+        async track(event, properties, ctx) {
+            const payload = {
+                event,
+                properties: properties ?? {},
+                userId: ctx.user.id,
+                emailHash: ctx.user.emailHash,
+                workspaceId: ctx.workspaceId,
+                timestamp: new Date().toISOString(),
+            };
+            if (!sinkUrl) {
+                // No sink configured — log in dev, silent in prod
+                if (process.env.NODE_ENV !== 'production') {
+                    console.log(`[pulse] ${event}`, properties ?? '');
+                }
+                return;
+            }
+            // Fire and forget — don't await in the request path
+            const headers = {
+                'Content-Type': 'application/json',
+            };
+            if (sinkToken) {
+                headers['Authorization'] = `Bearer ${sinkToken}`;
+            }
+            try {
+                const controller = new AbortController();
+                const timeout = setTimeout(() => controller.abort(), timeoutMs);
+                await fetch(sinkUrl, {
+                    method: 'POST',
+                    headers,
+                    body: JSON.stringify(payload),
+                    signal: controller.signal,
+                });
+                clearTimeout(timeout);
+            }
+            catch (err) {
+                // Best-effort — log and continue
+                console.warn(`[pulse] Failed to forward event "${event}":`, err.message);
+            }
+        },
+    };
+}
+//# sourceMappingURL=pulse.js.map

package/dist/server/handlers/pulse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pulse.js","sourceRoot":"","sources":["../../../src/server/handlers/pulse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA8BH,gFAAgF;AAChF,kBAAkB;AAClB,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAA6B;IAC9D,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,CAAA;IAChC,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,CAAA;IACpC,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,IAAI,CAAA;IAE5C,OAAO;QACL;;;;;;;;;;WAUG;QACH,KAAK,CAAC,KAAK,CACT,KAAa,EACb,UAA+C,EAC/C,GAAmB;YAEnB,MAAM,OAAO,GAAG;gBACd,KAAK;gBACL,UAAU,EAAE,UAAU,IAAI,EAAE;gBAC5B,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,EAAE;gBACnB,SAAS,EAAE,GAAG,CAAC,IAAI,CAAC,SAAS;gBAC7B,WAAW,EAAE,GAAG,CAAC,WAAW;gBAC5B,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;aACpC,CAAA;YAED,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,kDAAkD;gBAClD,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,EAAE,CAAC;oBAC1C,OAAO,CAAC,GAAG,CAAC,WAAW,KAAK,EAAE,EAAE,UAAU,IAAI,EAAE,CAAC,CAAA;gBACnD,CAAC;gBACD,OAAM;YACR,CAAC;YAED,oDAAoD;YACpD,MAAM,OAAO,GAA2B;gBACtC,cAAc,EAAE,kBAAkB;aACnC,CAAA;YACD,IAAI,SAAS,EAAE,CAAC;gBACd,OAAO,CAAC,eAAe,CAAC,GAAG,UAAU,SAAS,EAAE,CAAA;YAClD,CAAC;YAED,IAAI,CAAC;gBACH,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAA;gBACxC,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAA;gBAE/D,MAAM,KAAK,CAAC,OAAO,EAAE;oBACnB,MAAM,EAAE,MAAM;oBACd,OAAO;oBACP,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;oBAC7B,MAAM,EAAE,UAAU,CAAC,MAAM;iBAC1B,CAAC,CAAA;gBAEF,YAAY,CAAC,OAAO,CAAC,CAAA;YACvB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,iCAAiC;gBACjC,OAAO,CAAC,IAAI,CAAC,oCAAoC,KAAK,IAAI,EAAG,GAAa,CAAC,OAAO,CAAC,CAAA;YACrF,CAAC;QACH,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/server/handlers/realtime.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @module server/handlers/realtime
+ * @description Realtime namespace handler — topic-based pub/sub messaging,
+ * broadcast, and presence tracking.
+ *
+ * Backed by the Hall server (hall.soulcraft.com). The handler delegates all
+ * operations to an injected `RealtimeBackend` interface. When no backend is
+ * configured, all methods throw with a clear "not configured" error.
+ *
+ * Hall is working on their realtime pipeline implementation. This handler is
+ * the SDK-side contract — once Hall publishes their backend, products wire
+ * it in via `providers.realtime`.
+ *
+ * Methods:
+ * - `subscribe` — Subscribe to a topic and receive messages
+ * - `broadcast` — Send a message to all topic subscribers
+ * - `presence` — Get peers currently subscribed to a topic
+ */
+import type { NamespaceProvider } from '../namespace-router.js';
+/**
+ * Realtime backend interface — implemented by Hall.
+ *
+ * Products inject their Hall realtime client via `providers.realtime` in
+ * the SDK server config.
+ */
+export interface RealtimeBackend {
+    /** Subscribe to a topic. Returns a subscription handle. */
+    subscribe(topic: string, handler: (data: unknown) => void, userId: string): Promise<{
+        id: string;
+        unsubscribe: () => void;
+    }>;
+    /** Broadcast a message to all subscribers of a topic. */
+    broadcast(topic: string, data: unknown, senderId: string): Promise<void>;
+    /** Get the list of peers currently subscribed to a topic. */
+    presence(topic: string): Promise<Array<{
+        userId: string;
+        name: string;
+        joinedAt: string;
+    }>>;
+}
+/**
+ * Options for {@link createRealtimeHandler}.
+ */
+export interface RealtimeHandlerOptions {
+    /** Hall realtime backend. */
+    backend: RealtimeBackend;
+}
+/**
+ * Creates the `realtime` namespace handler.
+ *
+ * @param options - Realtime handler dependencies. If omitted, all methods throw.
+ * @returns A {@link NamespaceProvider} implementing {@link RealtimeNamespace}.
+ */
+export declare function createRealtimeHandler(options?: RealtimeHandlerOptions): NamespaceProvider;
+//# sourceMappingURL=realtime.d.ts.map

package/dist/server/handlers/realtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/realtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAkB,MAAM,wBAAwB,CAAA;AAM/E;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,2DAA2D;IAC3D,SAAS,CACP,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,EAChC,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC,CAAA;IAEnD,yDAAyD;IACzD,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAExE,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QACrC,MAAM,EAAE,MAAM,CAAA;QACd,IAAI,EAAE,MAAM,CAAA;QACZ,QAAQ,EAAE,MAAM,CAAA;KACjB,CAAC,CAAC,CAAA;CACJ;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,6BAA6B;IAC7B,OAAO,EAAE,eAAe,CAAA;CACzB;AAMD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,iBAAiB,CAkCzF"}

package/dist/server/handlers/realtime.js

@@ -0,0 +1,49 @@
+/**
+ * @module server/handlers/realtime
+ * @description Realtime namespace handler — topic-based pub/sub messaging,
+ * broadcast, and presence tracking.
+ *
+ * Backed by the Hall server (hall.soulcraft.com). The handler delegates all
+ * operations to an injected `RealtimeBackend` interface. When no backend is
+ * configured, all methods throw with a clear "not configured" error.
+ *
+ * Hall is working on their realtime pipeline implementation. This handler is
+ * the SDK-side contract — once Hall publishes their backend, products wire
+ * it in via `providers.realtime`.
+ *
+ * Methods:
+ * - `subscribe` — Subscribe to a topic and receive messages
+ * - `broadcast` — Send a message to all topic subscribers
+ * - `presence` — Get peers currently subscribed to a topic
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Handler factory
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Creates the `realtime` namespace handler.
+ *
+ * @param options - Realtime handler dependencies. If omitted, all methods throw.
+ * @returns A {@link NamespaceProvider} implementing {@link RealtimeNamespace}.
+ */
+export function createRealtimeHandler(options) {
+    const backend = options?.backend;
+    function requireBackend() {
+        if (!backend) {
+            throw new Error('realtime namespace is not configured — provide a RealtimeBackend via providers.realtime. ' +
+                'The realtime pipeline is implemented by the Hall server.');
+        }
+        return backend;
+    }
+    return {
+        async subscribe(topic, handler, ctx) {
+            return requireBackend().subscribe(topic, handler, ctx.user.id);
+        },
+        async broadcast(topic, data, ctx) {
+            return requireBackend().broadcast(topic, data, ctx.user.id);
+        },
+        async presence(topic) {
+            return requireBackend().presence(topic);
+        },
+    };
+}
+//# sourceMappingURL=realtime.js.map

package/dist/server/handlers/realtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime.js","sourceRoot":"","sources":["../../../src/server/handlers/realtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAyCH,gFAAgF;AAChF,kBAAkB;AAClB,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAgC;IACpE,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,CAAA;IAEhC,SAAS,cAAc;QACrB,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,2FAA2F;gBAC3F,0DAA0D,CAC3D,CAAA;QACH,CAAC;QACD,OAAO,OAAO,CAAA;IAChB,CAAC;IAED,OAAO;QACL,KAAK,CAAC,SAAS,CACb,KAAa,EACb,OAAgC,EAChC,GAAmB;YAEnB,OAAO,cAAc,EAAE,CAAC,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;QAChE,CAAC;QAED,KAAK,CAAC,SAAS,CACb,KAAa,EACb,IAAa,EACb,GAAmB;YAEnB,OAAO,cAAc,EAAE,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;QAC7D,CAAC;QAED,KAAK,CAAC,QAAQ,CAAC,KAAa;YAC1B,OAAO,cAAc,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;QACzC,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/server/handlers/search.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @module server/handlers/search
+ * @description Search namespace handler — semantic vector search, unified search with
+ * rich results, and file content highlighting.
+ *
+ * Absorbs Workshop `routes/search.ts`. Uses Brainy's `brain.find()` for semantic
+ * vector search and `brain.highlight()` for in-file content matching.
+ *
+ * Methods:
+ * - `query` — Simple semantic search returning entity matches
+ * - `unified` — Rich search with type grouping, scope filtering, and context
+ * - `highlight` — Find text + semantic matches within a specific file
+ */
+import type { NamespaceProvider } from '../namespace-router.js';
+/**
+ * Creates the `search` namespace handler.
+ *
+ * @returns A {@link NamespaceProvider} implementing {@link SearchNamespace}.
+ */
+export declare function createSearchHandler(): NamespaceProvider;
+//# sourceMappingURL=search.d.ts.map

package/dist/server/handlers/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAkB,MAAM,wBAAwB,CAAA;AAsB/E;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,iBAAiB,CAsPvD"}