@pikku/cli 0.12.21 → 0.12.23

package/dist/src/functions/wirings/permissions/pikku-command-permissions.d.ts

@@ -1 +1 @@
-export declare const pikkuPermissions: import("#pikku").PikkuFunctionConfig<void, boolean | undefined, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<void, boolean | undefined, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean | undefined, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
+export declare const pikkuPermissions: import("#pikku").PikkuFunctionConfig<void, boolean | undefined, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, boolean | undefined, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean | undefined, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

package/dist/src/functions/wirings/queue/pikku-command-queue-map.d.ts

@@ -1 +1 @@
-export declare const pikkuCommandQueueMap: import("#pikku").PikkuFunctionConfig<void, void, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<void, void, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
+export declare const pikkuCommandQueueMap: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

package/dist/src/functions/wirings/queue/pikku-command-queue-service.d.ts

@@ -1 +1 @@
-export declare const pikkuQueueService: import("#pikku").PikkuFunctionConfig<void, void, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<void, void, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
+export declare const pikkuQueueService: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

package/dist/src/functions/wirings/queue/pikku-command-queue-types.d.ts

@@ -1 +1 @@
-export declare const pikkuQueueTypes: import("#pikku").PikkuFunctionConfig<void, void, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<void, void, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
+export declare const pikkuQueueTypes: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

package/dist/src/functions/wirings/queue/pikku-command-queue.d.ts

@@ -1 +1 @@
-export declare const pikkuCommandQueue: import("#pikku").PikkuFunctionConfig<void, boolean | undefined, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<void, boolean | undefined, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean | undefined, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
+export declare const pikkuCommandQueue: import("#pikku").PikkuFunctionConfig<void, boolean | undefined, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, boolean | undefined, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean | undefined, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

package/dist/src/functions/wirings/queue/pikku-queue-map.d.ts

@@ -1 +1 @@
-export declare const pikkuQueueMap: import("#pikku").PikkuFunctionConfig<void, void, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<void, void, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
+export declare const pikkuQueueMap: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

package/dist/src/functions/wirings/queue/pikku-queue.d.ts

@@ -1 +1 @@
-export declare const pikkuQueue: import("#pikku").PikkuFunctionConfig<void, boolean, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<void, boolean, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
+export declare const pikkuQueue: import("#pikku").PikkuFunctionConfig<void, boolean, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, boolean, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

package/dist/src/functions/wirings/realtime/pikku-command-events-scaffold.d.ts

@@ -0,0 +1 @@
+export declare const pikkuEventsScaffold: import("#pikku").PikkuFunctionConfig<void, boolean, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, boolean, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

package/dist/src/functions/wirings/realtime/pikku-command-events-scaffold.js

@@ -0,0 +1,26 @@
+import { pikkuSessionlessFunc } from '#pikku';
+import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
+import { writeFileInDir } from '../../../utils/file-writer.js';
+import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
+import { serializeEventsScaffold } from './serialize-events-scaffold.js';
+export const pikkuEventsScaffold = pikkuSessionlessFunc({
+    func: async ({ logger, config }) => {
+        if (!config.scaffold?.events || !config.eventsChannelFile) {
+            logger.debug({
+                message: 'Skipping events scaffold (set scaffold.events in pikku.config.json to enable).',
+                type: 'skip',
+            });
+            return false;
+        }
+        const authRequired = config.scaffold.events === 'auth';
+        const pikkuTypesImportPath = getFileImportRelativePath(config.eventsChannelFile, config.typesDeclarationFile, config.packageMappings);
+        await writeFileInDir(logger, config.eventsChannelFile, serializeEventsScaffold(authRequired, pikkuTypesImportPath));
+        return true;
+    },
+    middleware: [
+        logCommandInfoAndTime({
+            commandStart: 'Generating events channel scaffold',
+            commandEnd: 'Generated events channel scaffold',
+        }),
+    ],
+});

package/dist/src/functions/wirings/realtime/pikku-command-realtime.d.ts

@@ -0,0 +1 @@
+export declare const pikkuRealtime: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

package/dist/src/functions/wirings/realtime/pikku-command-realtime.js

@@ -0,0 +1,35 @@
+import { pikkuSessionlessFunc } from '#pikku';
+import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
+import { writeFileInDir } from '../../../utils/file-writer.js';
+import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
+import { serializeRealtimeClient } from './serialize-realtime-client.js';
+export const pikkuRealtime = pikkuSessionlessFunc({
+    func: async ({ logger, config }) => {
+        const realtimeFile = config.clientFiles?.realtimeFile;
+        const fetchFile = config.clientFiles?.fetchFile;
+        if (!realtimeFile) {
+            logger.debug({
+                message: 'Skipping realtime client (set clientFiles.realtimeFile in pikku.config.json to enable).',
+                type: 'skip',
+            });
+            return;
+        }
+        if (!fetchFile) {
+            logger.debug({
+                message: 'Skipping realtime client (clientFiles.fetchFile is required so PikkuRealtime can wrap PikkuFetch).',
+                type: 'skip',
+            });
+            return;
+        }
+        const topicsImport = config.clientFiles?.realtimeEventHubTopicsImport;
+        const fetchImportPath = getFileImportRelativePath(realtimeFile, fetchFile, config.packageMappings);
+        const content = serializeRealtimeClient(topicsImport, fetchImportPath);
+        await writeFileInDir(logger, realtimeFile, content);
+    },
+    middleware: [
+        logCommandInfoAndTime({
+            commandStart: 'Generating realtime client',
+            commandEnd: 'Generated realtime client',
+        }),
+    ],
+});

package/dist/src/functions/wirings/realtime/serialize-events-scaffold.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Generates the server-side `events.gen.ts` scaffold.
+ *
+ * This file lives in the user's project and wires two transports against the
+ * project's `eventHub` service:
+ *
+ *   1. WebSocket channel at `/events` — bidirectional. Clients send
+ *      `{action: 'subscribe' | 'unsubscribe', topic}` over the same socket;
+ *      multiple topic subscriptions per connection. On disconnect the
+ *      eventHub's onChannelClosed hook auto-cleans subscriptions.
+ *
+ *   2. SSE endpoint at `GET /events/:topic` — one connection = one topic.
+ *      Subscribes the channel, returns; the eventHub fans out via
+ *      `channel.send` until the client closes. onChannelClosed cleans up.
+ *
+ * Both routes call `eventHub.subscribe`/`unsubscribe` with the channel id;
+ * publish-side ergonomics (envelope shape) are documented in the
+ * pikku-realtime skill.
+ *
+ * Uses TypeScript generics (not named Zod schema constants) so schemas and
+ * wiring calls can safely coexist in a single generated file.
+ */
+export declare const serializeEventsScaffold: (authRequired: boolean, pikkuTypesImportPath: string) => string;

package/dist/src/functions/wirings/realtime/serialize-events-scaffold.js

@@ -0,0 +1,98 @@
+/**
+ * Generates the server-side `events.gen.ts` scaffold.
+ *
+ * This file lives in the user's project and wires two transports against the
+ * project's `eventHub` service:
+ *
+ *   1. WebSocket channel at `/events` — bidirectional. Clients send
+ *      `{action: 'subscribe' | 'unsubscribe', topic}` over the same socket;
+ *      multiple topic subscriptions per connection. On disconnect the
+ *      eventHub's onChannelClosed hook auto-cleans subscriptions.
+ *
+ *   2. SSE endpoint at `GET /events/:topic` — one connection = one topic.
+ *      Subscribes the channel, returns; the eventHub fans out via
+ *      `channel.send` until the client closes. onChannelClosed cleans up.
+ *
+ * Both routes call `eventHub.subscribe`/`unsubscribe` with the channel id;
+ * publish-side ergonomics (envelope shape) are documented in the
+ * pikku-realtime skill.
+ *
+ * Uses TypeScript generics (not named Zod schema constants) so schemas and
+ * wiring calls can safely coexist in a single generated file.
+ */
+export const serializeEventsScaffold = (authRequired, pikkuTypesImportPath) => {
+    const auth = authRequired ? 'true' : 'false';
+    return `import {
+  pikkuChannelFunc,
+  pikkuSessionlessFunc,
+  wireChannel,
+  wireHTTP,
+  defineChannelRoutes,
+} from '${pikkuTypesImportPath}'
+
+/**
+ * Topic envelope clients receive: \`{ topic, data }\`. Functions that publish
+ * events should send this shape:
+ *
+ *   await eventHub.publish('todo-created', null, { topic: 'todo-created', data: { todo } })
+ *
+ * The pikku-realtime skill covers a thin \`publishEvent\` helper to remove
+ * the duplication; pick whichever style your project prefers.
+ */
+
+export const realtimeSubscribe = pikkuChannelFunc<{ topic: string }>({
+  func: async ({ eventHub }, { topic }, { channel }) => {
+    await eventHub?.subscribe(topic, channel.channelId)
+  },
+})
+
+export const realtimeUnsubscribe = pikkuChannelFunc<{ topic: string }>({
+  func: async ({ eventHub }, { topic }, { channel }) => {
+    await eventHub?.unsubscribe(topic, channel.channelId)
+  },
+})
+
+// Pikku dispatches by the \`action\` field; client sends
+//   { action: 'subscribe',   topic: 'todo-created' }
+//   { action: 'unsubscribe', topic: 'todo-created' }
+export const realtimeRoutes = defineChannelRoutes({
+  subscribe: realtimeSubscribe,
+  unsubscribe: realtimeUnsubscribe,
+})
+
+wireChannel({
+  name: 'events',
+  route: '/events',
+  auth: ${auth},
+  onMessageWiring: {
+    action: realtimeRoutes,
+  },
+  tags: ['pikku:realtime'],
+})
+
+/**
+ * SSE per-topic stream. One connection = one subscription. The eventHub
+ * cleans up automatically when the channel closes (onChannelClosed).
+ */
+export const realtimeEventStream = pikkuSessionlessFunc<{ topic: string }, void>({
+  description: 'Auto-generated SSE stream for a single event-hub topic',
+  func: async ({ eventHub }, { topic }, { channel }) => {
+    if (!channel) {
+      throw new Error('Realtime SSE handler invoked without a channel')
+    }
+    await eventHub?.subscribe(topic, channel.channelId)
+    // Function returns; eventHub continues pushing via channel.send until
+    // the client disconnects, at which point onChannelClosed unsubscribes.
+  },
+})
+
+wireHTTP({
+  method: 'get',
+  route: '/events/:topic',
+  func: realtimeEventStream,
+  auth: ${auth},
+  sse: true,
+  tags: ['pikku:realtime', 'sse'],
+})
+`;
+};

package/dist/src/functions/wirings/realtime/serialize-realtime-client.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Generates the client-side `realtime.gen.ts`.
+ *
+ * `PikkuRealtime` mirrors the `PikkuRPC` pattern: it wraps the project's
+ * generated `PikkuFetch` (so server URL + auth come from one place) and
+ * exposes:
+ *
+ *   - `subscribe(topic, handler)` / `unsubscribe(topic)` — typed pub/sub
+ *     over the websocket at `/events`. Multi-topic per connection.
+ *   - `subscribeToTopic(topic, handler)` — same shape but via SSE
+ *     (one EventSource per topic, auto-cleanup on close).
+ *   - `subscribeToSSE(path, handler)` — generic SSE subscribe for any
+ *     `sse: true` route (workflow streams, agent streams, etc.).
+ *   - `connectToChannel(channelRoute, protocols?)` — open a raw WebSocket
+ *     for any wireChannel route, ready to wrap in
+ *     `PikkuWebSocket<'channel-name'>` for typed subscribe/send.
+ *
+ * Topic types come from `EventHubTopics` if the user supplies an import
+ * via `clientFiles.realtimeEventHubTopicsImport`. Otherwise topics fall
+ * back to `Record<string, unknown>`.
+ */
+export declare const serializeRealtimeClient: (topicsImport: string | undefined, fetchImportPath: string) => string;

package/dist/src/functions/wirings/realtime/serialize-realtime-client.js

@@ -0,0 +1,337 @@
+/**
+ * Generates the client-side `realtime.gen.ts`.
+ *
+ * `PikkuRealtime` mirrors the `PikkuRPC` pattern: it wraps the project's
+ * generated `PikkuFetch` (so server URL + auth come from one place) and
+ * exposes:
+ *
+ *   - `subscribe(topic, handler)` / `unsubscribe(topic)` — typed pub/sub
+ *     over the websocket at `/events`. Multi-topic per connection.
+ *   - `subscribeToTopic(topic, handler)` — same shape but via SSE
+ *     (one EventSource per topic, auto-cleanup on close).
+ *   - `subscribeToSSE(path, handler)` — generic SSE subscribe for any
+ *     `sse: true` route (workflow streams, agent streams, etc.).
+ *   - `connectToChannel(channelRoute, protocols?)` — open a raw WebSocket
+ *     for any wireChannel route, ready to wrap in
+ *     `PikkuWebSocket<'channel-name'>` for typed subscribe/send.
+ *
+ * Topic types come from `EventHubTopics` if the user supplies an import
+ * via `clientFiles.realtimeEventHubTopicsImport`. Otherwise topics fall
+ * back to `Record<string, unknown>`.
+ */
+export const serializeRealtimeClient = (topicsImport, fetchImportPath) => {
+    const topicsTypeImport = topicsImport
+        ? buildImportLine(topicsImport)
+        : `// No EventHubTopics import configured. Set clientFiles.realtimeEventHubTopicsImport
+// in pikku.config.json (e.g. \"../types/eventhub-topics.js#EventHubTopics\")
+// to get fully-typed subscribe/unsubscribe.
+type EventHubTopics = Record<string, unknown>`;
+    return `/**
+ * Generated by @pikku/cli — do not edit.
+ * Regenerate with \`pikku all\` (or \`pikku realtime\`).
+ */
+import { CorePikkuFetch } from '@pikku/fetch'
+import { PikkuFetch } from '${fetchImportPath}'
+${topicsTypeImport}
+
+type Handler<T> = (data: T) => void
+
+interface RealtimeOptions {
+  /** Auto-reconnect with backoff (default: true) */
+  reconnect?: boolean
+  /** Initial reconnect delay in ms (default: 500) */
+  reconnectDelayMs?: number
+  /** Cap on reconnect delay (default: 10_000) */
+  reconnectMaxDelayMs?: number
+}
+
+/**
+ * Realtime client. Mirrors the PikkuRPC pattern: wraps a PikkuFetch so
+ * the server URL + auth are configured once and shared across transports.
+ *
+ * \`\`\`ts
+ * const pikku = createPikku(PikkuFetch, PikkuRPC, { serverUrl: 'http://localhost:3000' })
+ * const realtime = new PikkuRealtime()
+ * realtime.setPikkuFetch(pikku.fetch)
+ *
+ * const off = realtime.subscribe('todo-created', ({ todo }) => { ... })
+ * // later: off(); realtime.close()
+ * \`\`\`
+ */
+export class PikkuRealtime {
+  /** The underlying HTTP client used to derive server URL + auth */
+  pikkuFetch = new PikkuFetch()
+
+  private ws: WebSocket | null = null
+  private readonly handlers = new Map<string, Set<Handler<any>>>()
+  private readonly options: Required<RealtimeOptions>
+  private reconnectAttempt = 0
+  private closed = false
+  private connectScheduled = false
+
+  constructor(options: RealtimeOptions = {}) {
+    this.options = {
+      reconnect: options.reconnect ?? true,
+      reconnectDelayMs: options.reconnectDelayMs ?? 500,
+      reconnectMaxDelayMs: options.reconnectMaxDelayMs ?? 10_000,
+    }
+  }
+
+  /**
+   * Use a shared PikkuFetch instance (typically from \`createPikku(...)\`).
+   * The realtime client picks up its server URL + auth from this fetch,
+   * so you only configure connection details in one place.
+   */
+  setPikkuFetch(pikkuFetch: PikkuFetch): void {
+    this.pikkuFetch = pikkuFetch
+  }
+
+  /** Sets the base server URL on the underlying PikkuFetch. */
+  setServerUrl(serverUrl: string): void {
+    this.pikkuFetch.setServerUrl(serverUrl)
+  }
+
+  /** Sets the JWT for auth on transports that send headers (SSE). */
+  setAuthorizationJWT(jwt: string | null): void {
+    this.pikkuFetch.setAuthorizationJWT(jwt)
+  }
+
+  /** Sets the API key for auth on transports that send headers (SSE). */
+  setAPIKey(apiKey: string | null): void {
+    this.pikkuFetch.setAPIKey(apiKey)
+  }
+
+  /**
+   * Subscribe to a typed event topic over the websocket. Returns an
+   * \`unsubscribe\` function. Auto-reconnects re-send subscriptions.
+   */
+  subscribe<K extends keyof EventHubTopics & string>(
+    topic: K,
+    handler: Handler<EventHubTopics[K]>
+  ): () => void {
+    const set = this.handlers.get(topic) ?? new Set<Handler<any>>()
+    if (set.size === 0) {
+      this.send({ action: 'subscribe', topic })
+    }
+    set.add(handler)
+    this.handlers.set(topic, set)
+    this.ensureConnected()
+    return () => this.unsubscribe(topic, handler)
+  }
+
+  unsubscribe<K extends keyof EventHubTopics & string>(
+    topic: K,
+    handler?: Handler<EventHubTopics[K]>
+  ): void {
+    const set = this.handlers.get(topic)
+    if (!set) return
+    if (handler) set.delete(handler)
+    else set.clear()
+    if (set.size === 0) {
+      this.handlers.delete(topic)
+      this.send({ action: 'unsubscribe', topic })
+    }
+  }
+
+  /**
+   * SSE alternative for a single topic stream. One EventSource per topic;
+   * close the returned object to unsubscribe (the server cleans up
+   * automatically on disconnect).
+   */
+  subscribeToTopic<K extends keyof EventHubTopics & string>(
+    topic: K,
+    handler: Handler<EventHubTopics[K]>
+  ): { close: () => void } {
+    return this.subscribeToSSE<EventHubTopics[K]>(
+      \`/events/\${encodeURIComponent(topic)}\`,
+      handler
+    )
+  }
+
+  /**
+   * Generic SSE subscribe. Use for any \`sse: true\` HTTP route in your
+   * project. Caller supplies the path (with any params/query) — the base
+   * URL comes from the wrapped PikkuFetch.
+   *
+   * \`\`\`ts
+   * const sub = realtime.subscribeToSSE<{ progress: number }>(
+   *   \`/workflow-run/\${runId}/stream\`,
+   *   (e) => setProgress(e.progress)
+   * )
+   * \`\`\`
+   */
+  subscribeToSSE<T = unknown>(
+    path: string,
+    handler: Handler<T>,
+    onError?: (err: unknown) => void
+  ): { close: () => void } {
+    const controller = new AbortController()
+    const closed = { value: false }
+
+    const run = async () => {
+      try {
+        const response = await (this.pikkuFetch as CorePikkuFetch).fetch(
+          path,
+          'GET',
+          null,
+          {
+            headers: { Accept: 'text/event-stream' },
+            signal: controller.signal,
+          }
+        )
+        if (!response.ok || !response.body) {
+          throw new Error(\`SSE request failed: \${response.status}\`)
+        }
+
+        const reader = response.body
+          .pipeThrough(new TextDecoderStream())
+          .getReader()
+        let buffer = ''
+
+        while (!closed.value) {
+          const { done, value } = await reader.read()
+          if (done) break
+          buffer += value
+
+          let sep: number
+          while ((sep = buffer.indexOf('\\n\\n')) !== -1) {
+            const raw = buffer.slice(0, sep)
+            buffer = buffer.slice(sep + 2)
+
+            const dataLines = raw
+              .split('\\n')
+              .filter((l) => l.startsWith('data:'))
+              .map((l) => l.slice(5).trimStart())
+            if (dataLines.length === 0) continue
+            const data = dataLines.join('\\n')
+
+            try {
+              handler(JSON.parse(data) as T)
+            } catch {
+              // Ignore malformed events
+            }
+          }
+        }
+      } catch (err) {
+        if (closed.value) return
+        if (onError) onError(err)
+      }
+    }
+
+    void run()
+
+    return {
+      close: () => {
+        closed.value = true
+        controller.abort()
+      },
+    }
+  }
+
+  /**
+   * Open a raw WebSocket against one of the project's wireChannel routes.
+   * Wrap the returned socket in \`PikkuWebSocket<'channel-name'>\` from the
+   * generated websocket client for typed subscribe/send.
+   */
+  connectToChannel(
+    channelPath: string,
+    protocols?: string | string[]
+  ): WebSocket {
+    return new WebSocket(this.resolveWsUrl(channelPath), protocols)
+  }
+
+  /** Disconnect the events websocket and clear all subscriptions. */
+  close(): void {
+    this.closed = true
+    this.handlers.clear()
+    this.ws?.close()
+    this.ws = null
+  }
+
+  private ensureConnected() {
+    if (this.ws || this.connectScheduled || this.closed) return
+    this.connect()
+  }
+
+  private connect() {
+    if (this.closed) return
+    this.connectScheduled = false
+    const url = this.resolveWsUrl('/events')
+    this.ws = new WebSocket(url)
+    this.ws.onopen = () => {
+      this.reconnectAttempt = 0
+      for (const topic of this.handlers.keys()) {
+        this.send({ action: 'subscribe', topic })
+      }
+    }
+    this.ws.onmessage = (e: MessageEvent) => {
+      let payload: unknown
+      try {
+        payload =
+          typeof e.data === 'string' ? JSON.parse(e.data) : (e.data as unknown)
+      } catch {
+        return
+      }
+      if (
+        payload &&
+        typeof payload === 'object' &&
+        'topic' in (payload as any) &&
+        typeof (payload as any).topic === 'string'
+      ) {
+        const { topic, data } = payload as { topic: string; data: unknown }
+        const set = this.handlers.get(topic)
+        if (set) for (const h of set) h(data)
+      }
+    }
+    this.ws.onclose = () => {
+      this.ws = null
+      if (this.closed || !this.options.reconnect) return
+      const delay = Math.min(
+        this.options.reconnectDelayMs * 2 ** this.reconnectAttempt,
+        this.options.reconnectMaxDelayMs
+      )
+      this.reconnectAttempt += 1
+      this.connectScheduled = true
+      setTimeout(() => this.connect(), delay)
+    }
+    this.ws.onerror = () => {
+      this.ws?.close()
+    }
+  }
+
+  private send(message: { action: 'subscribe' | 'unsubscribe'; topic: string }) {
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(message))
+    }
+    // If not open, onopen replays current handler keys.
+  }
+
+  private resolveHttpUrl(path: string): string {
+    const base = this.pikkuFetch.getServerUrl()
+    if (!base) {
+      throw new Error(
+        'PikkuRealtime: no server URL — call setServerUrl(...) or setPikkuFetch(...) first.'
+      )
+    }
+    return \`\${base}\${path.startsWith('/') ? path : \`/\${path}\`}\`
+  }
+
+  private resolveWsUrl(path: string): string {
+    const httpUrl = this.resolveHttpUrl(path)
+    return httpUrl.replace(/^http/i, 'ws')
+  }
+}
+`;
+};
+function buildImportLine(spec) {
+    const hashIdx = spec.lastIndexOf('#');
+    if (hashIdx === -1) {
+        return `import type { EventHubTopics } from '${spec}'`;
+    }
+    const path = spec.slice(0, hashIdx);
+    const typeName = spec.slice(hashIdx + 1);
+    if (typeName === 'EventHubTopics') {
+        return `import type { EventHubTopics } from '${path}'`;
+    }
+    return `import type { ${typeName} as EventHubTopics } from '${path}'`;
+}

package/dist/src/functions/wirings/rpc/pikku-command-public-rpc.d.ts

@@ -1 +1 @@
-export declare const pikkuPublicRPC: import("#pikku").PikkuFunctionConfig<void, boolean, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<void, boolean, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
+export declare const pikkuPublicRPC: import("#pikku").PikkuFunctionConfig<void, boolean, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, boolean, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

package/dist/src/functions/wirings/rpc/pikku-command-react-query.d.ts

@@ -1 +1 @@
-export declare const pikkuReactQuery: import("#pikku").PikkuFunctionConfig<void, void, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<void, void, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
+export declare const pikkuReactQuery: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

package/dist/src/functions/wirings/rpc/pikku-command-remote-rpc.d.ts

@@ -1 +1 @@
-export declare const pikkuRemoteRPC: import("#pikku").PikkuFunctionConfig<void, boolean, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<void, boolean, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
+export declare const pikkuRemoteRPC: import("#pikku").PikkuFunctionConfig<void, boolean, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, boolean, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

package/dist/src/functions/wirings/rpc/pikku-command-rpc-client.d.ts

@@ -1 +1 @@
-export declare const pikkuRPCClient: import("#pikku").PikkuFunctionConfig<void, void, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<void, void, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
+export declare const pikkuRPCClient: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

package/dist/src/functions/wirings/rpc/pikku-command-rpc-client.js

@@ -16,7 +16,9 @@ export const pikkuRPCClient = pikkuSessionlessFunc({
             return;
         }
         const rpcMapDeclarationPath = getFileImportRelativePath(rpcWiringsFile, rpcMapDeclarationFile, packageMappings);
-        const content = [serializeRPCWrapper(rpcMapDeclarationPath, config.globalHTTPPrefix || '')];
+        const content = [
+            serializeRPCWrapper(rpcMapDeclarationPath, config.globalHTTPPrefix || ''),
+        ];
         await writeFileInDir(logger, rpcWiringsFile, content.join('\n'));
     },
     middleware: [

package/dist/src/functions/wirings/rpc/pikku-command-rpc-map.d.ts

@@ -1,2 +1,2 @@
-export declare const pikkuRPCInternalMap: import("#pikku").PikkuFunctionConfig<void, void, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<void, void, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
-export declare const pikkuRPCExposedMap: import("#pikku").PikkuFunctionConfig<void, void, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<void, void, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
+export declare const pikkuRPCInternalMap: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;
+export declare const pikkuRPCExposedMap: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

package/dist/src/functions/wirings/rpc/pikku-command-rpc.d.ts

@@ -1 +1,2 @@
-export declare const pikkuRPC: import("#pikku").PikkuFunctionConfig<void, boolean, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<void, boolean, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
+export declare function filterInternalRPCMeta(internalMeta: Record<string, string>, functionsMeta: Record<string, unknown>): Record<string, string>;
+export declare const pikkuRPC: import("#pikku").PikkuFunctionConfig<void, boolean, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, boolean, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;