@llblab/pi-telegram 0.11.1 → 0.12.0

package/lib/updates.ts

@@ -1,7 +1,7 @@
 /**
  * Telegram updates domain helpers
  * Zones: telegram inbound, authorization, routing plans
- * Owns update extraction, authorization, classification, execution planning, and runtime execution for Telegram updates
+ * Owns update extraction, authorization, classification, execution planning, runtime execution, and the public update-handler registry
  */
 
 import {
@@ -851,3 +851,123 @@ export async function executeTelegramUpdatePlan<
     if (!isTelegramStaleContextError(error)) throw error;
   }
 }
+
+// --- Public update handler registry ---
+
+/**
+ * Verdict returned by a public Telegram update handler.
+ *
+ * - `"consume"` — the handler processed this update; pi-telegram skips default routing.
+ * - `"pass"` (or `void`/`undefined`) — pi-telegram routes the update normally.
+ */
+export type TelegramUpdateHandlerVerdict = "consume" | "pass";
+
+export type TelegramUpdateHandler = (
+  update: unknown,
+) =>
+  | TelegramUpdateHandlerVerdict
+  | void
+  | Promise<TelegramUpdateHandlerVerdict | void>;
+
+export interface TelegramUpdateHandlerRegistry {
+  /** Schema version of this registry shape. */
+  readonly version: 1;
+  /**
+   * Register an update handler. Returns a disposer that removes it.
+   *
+   * Handlers are invoked in registration order on every Telegram update,
+   * before pi-telegram's own routing. The first handler that returns
+   * `"consume"` wins and stops the chain for that update.
+   */
+  add: (handler: TelegramUpdateHandler) => () => void;
+  /**
+   * Run all registered handlers against an update.
+   *
+   * Used by pi-telegram's polling runtime; companion extensions should call
+   * {@link registerTelegramUpdateHandler} or `add` instead of dispatching directly.
+   */
+  dispatch: (update: unknown) => Promise<TelegramUpdateHandlerVerdict>;
+}
+
+const UPDATE_HANDLER_REGISTRY_KEY = "__piTelegramUpdateHandlerRegistry__";
+
+function isValidV1UpdateHandlerRegistry(
+  candidate: unknown,
+): candidate is TelegramUpdateHandlerRegistry {
+  if (!candidate || typeof candidate !== "object") return false;
+  const r = candidate as Partial<TelegramUpdateHandlerRegistry>;
+  return (
+    r.version === 1 &&
+    typeof r.add === "function" &&
+    typeof r.dispatch === "function"
+  );
+}
+
+function getOrCreateUpdateHandlerRegistry(): TelegramUpdateHandlerRegistry {
+  const g = globalThis as Record<string, unknown>;
+  const existing = g[UPDATE_HANDLER_REGISTRY_KEY];
+  if (isValidV1UpdateHandlerRegistry(existing)) return existing;
+  const handlers = new Set<TelegramUpdateHandler>();
+  const registry: TelegramUpdateHandlerRegistry = {
+    version: 1,
+    add(handler) {
+      handlers.add(handler);
+      return () => handlers.delete(handler);
+    },
+    async dispatch(update) {
+      for (const handler of handlers) {
+        try {
+          const result = await handler(update);
+          if (result === "consume") return "consume";
+        } catch {
+          // Update handler errors must not break polling.
+        }
+      }
+      return "pass";
+    },
+  };
+  g[UPDATE_HANDLER_REGISTRY_KEY] = registry;
+  return registry;
+}
+
+/**
+ * Called by pi-telegram's own runtime to obtain the registry it dispatches
+ * through. Companion extensions should not call this; use
+ * {@link registerTelegramUpdateHandler} instead.
+ */
+export function getTelegramUpdateHandlerRegistry(): TelegramUpdateHandlerRegistry {
+  return getOrCreateUpdateHandlerRegistry();
+}
+
+export interface TelegramUpdateHandlerWrapDeps<TUpdate, TContext> {
+  defaultHandle: (update: TUpdate, ctx: TContext) => Promise<void>;
+  registry?: TelegramUpdateHandlerRegistry;
+}
+
+/**
+ * Wrap a default polling `handleUpdate` with the public update handler registry.
+ */
+export function createTelegramUpdateHandle<TUpdate, TContext>(
+  deps: TelegramUpdateHandlerWrapDeps<TUpdate, TContext>,
+): (update: TUpdate, ctx: TContext) => Promise<void> {
+  const registry = deps.registry ?? getOrCreateUpdateHandlerRegistry();
+  const { defaultHandle } = deps;
+  return async function handleTelegramUpdate(update, ctx) {
+    const verdict = await registry.dispatch(update);
+    if (verdict === "consume") return;
+    await defaultHandle(update, ctx);
+  };
+}
+
+/**
+ * Register a handler that runs before pi-telegram routes a Telegram update
+ * through its built-in handlers.
+ *
+ * This is the low-level public surface for companion extensions that share
+ * the same bot and pi process with pi-telegram.
+ */
+export function registerTelegramUpdateHandler(
+  handler: TelegramUpdateHandler,
+): () => void {
+  return getOrCreateUpdateHandlerRegistry().add(handler);
+}

package/lib/voice.ts

@@ -12,13 +12,14 @@
  *
  * Separation of concerns:
  * - All decision logic and domain rules live here.
- * - Actual delivery (sending the audio via Telegram) stays in outbound-handlers.ts.
+ * - Actual delivery (sending the audio via Telegram) stays in outbound.ts.
  *
  * Keeps voice policy, turn tagging, prompt contributions, and markup helpers
  * out of the queue, preview, turn-building, and delivery domains.
  */
 
-const VOICE_SYNTHESIS_PROVIDER_REGISTRY_KEY = "__piTelegramVoiceSynthesisProviders__";
+const VOICE_SYNTHESIS_PROVIDER_REGISTRY_KEY =
+  "__piTelegramVoiceSynthesisProviders__";
 const VOICE_TRANSCRIPTION_PROVIDER_REGISTRY_KEY =
   "__piTelegramVoiceTranscriptionProviders__";
 
@@ -81,11 +82,20 @@ function getOrCreateVoiceSynthesisProviderRegistry(): Map<
   if (existing instanceof Map)
     return existing as Map<string, TelegramVoiceSynthesisProvider>;
   const registry = new Map<string, TelegramVoiceSynthesisProvider>();
-  (globalThis as Record<string, unknown>)[VOICE_SYNTHESIS_PROVIDER_REGISTRY_KEY] =
-    registry;
+  (globalThis as Record<string, unknown>)[
+    VOICE_SYNTHESIS_PROVIDER_REGISTRY_KEY
+  ] = registry;
   return registry;
 }
 
+/**
+ * Register a high-level Telegram voice synthesis provider.
+ *
+ * Stable public API callers must pass a stable `options.id` so diagnostics,
+ * replacement, and cleanup can identify the provider. Omitted ids remain a
+ * compatibility path for pre-matrix callers and receive generated session-local
+ * ids.
+ */
 export function registerTelegramVoiceSynthesisProvider(
   provider:
     | TelegramVoiceSynthesisProvider
@@ -103,9 +113,11 @@ export function registerTelegramVoiceSynthesisProvider(
           (text: string, options?: { lang?: string; rate?: string }) =>
             provider(text, options),
           {
-            getVoicePolicy: (provider as TelegramVoiceSynthesisProvider).getVoicePolicy,
-            getVoicePromptContribution: (provider as TelegramVoiceSynthesisProvider)
-              .getVoicePromptContribution,
+            getVoicePolicy: (provider as TelegramVoiceSynthesisProvider)
+              .getVoicePolicy,
+            getVoicePromptContribution: (
+              provider as TelegramVoiceSynthesisProvider
+            ).getVoicePromptContribution,
           },
         ) as TelegramVoiceSynthesisProvider)
       : provider;
@@ -144,6 +156,13 @@ function getOrCreateVoiceTranscriptionProviderRegistry(): Map<
   return registry;
 }
 
+/**
+ * Register a high-level Telegram voice transcription provider.
+ *
+ * Stable public API callers must pass a stable `options.id`. Omitted ids remain
+ * a compatibility path for pre-matrix callers and receive generated
+ * session-local ids.
+ */
 export function registerTelegramVoiceTranscriptionProvider(
   provider: TelegramVoiceTranscriptionProvider,
   options?: { id?: string },
@@ -182,9 +201,9 @@ export const TELEGRAM_VOICE_REPLY_MODES = [
  * Pi-telegram owns reply-mode policy through telegram.json. If
  * config.voice.replyMode is missing or invalid, the safe default is manual.
  */
-export function getTelegramVoiceReplyMode(
-  config?: { voice?: { replyMode?: string } },
-): TelegramVoiceReplyMode {
+export function getTelegramVoiceReplyMode(config?: {
+  voice?: { replyMode?: string };
+}): TelegramVoiceReplyMode {
   const configMode = config?.voice?.replyMode;
   if (
     configMode &&
@@ -202,9 +221,9 @@ export function getTelegramVoiceReplyMode(
  * Reads from `config.voice.sendTranscript`.
  * Default: false (no transcript text sent at all).
  */
-export function getTelegramVoiceSendTranscript(
-  config?: { voice?: { sendTranscript?: boolean } },
-): boolean {
+export function getTelegramVoiceSendTranscript(config?: {
+  voice?: { sendTranscript?: boolean };
+}): boolean {
   return !!config?.voice?.sendTranscript;
 }
 
@@ -292,4 +311,4 @@ export {
   stripTelegramCommentMarkupForDelivery,
   stripTelegramVoiceMarkupForPreview,
   normalizeMarkdownAfterVoiceExtraction,
-} from "./outbound-handlers.ts";
+} from "./outbound.ts";

package/package.json

@@ -1,12 +1,21 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "private": false,
   "publishConfig": {
     "access": "public"
   },
   "description": "Telegram runtime adapter for π",
   "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./inbound": "./api/inbound.ts",
+    "./outbound": "./api/outbound.ts",
+    "./updates": "./api/updates.ts",
+    "./sections": "./api/sections.ts",
+    "./voice": "./api/voice.ts",
+    "./keyboard": "./api/keyboard.ts"
+  },
   "keywords": [
     "pi-package",
     "pi",
@@ -35,6 +44,7 @@
   },
   "files": [
     "index.ts",
+    "api/",
     "lib/",
     "README.md",
     "AGENTS.md",

package/lib/external-handlers.ts

@@ -1,166 +0,0 @@
-/**
- * External Telegram handler registry
- * Zones: telegram transport, layered extension interop
- * Lets other pi extensions hook into the polling loop without owning their own getUpdates connection
- */
-
-/**
- * Verdict returned by an interceptor.
- *
- * - `"consume"` — the interceptor handled this update; pi-telegram skips default routing.
- * - `"pass"` (or `void`/`undefined`) — pi-telegram routes the update normally.
- */
-export type TelegramExternalHandlerVerdict = "consume" | "pass";
-
-export type TelegramExternalHandler = (
-  update: unknown,
-) =>
-  | TelegramExternalHandlerVerdict
-  | void
-  | Promise<TelegramExternalHandlerVerdict | void>;
-
-export interface TelegramExternalHandlerRegistry {
-  /** Schema version of this registry shape. */
-  readonly version: 1;
-  /**
-   * Register an interceptor. Returns a disposer that removes it.
-   *
-   * Interceptors are invoked in registration order on every Telegram update,
-   * before pi-telegram's own routing. The first interceptor that returns
-   * `"consume"` wins and stops the chain for that update.
-   */
-  add: (handler: TelegramExternalHandler) => () => void;
-  /**
-   * Run all registered interceptors against an update.
-   *
-   * Used by pi-telegram's polling runtime; layered extensions should call
-   * {@link onTelegramExternalUpdate} or `add` instead of dispatching directly.
-   */
-  dispatch: (update: unknown) => Promise<TelegramExternalHandlerVerdict>;
-}
-
-const REGISTRY_KEY = "__piTelegramExternalHandlerRegistry__";
-
-/**
- * Validate that a value on `globalThis` matches the full v1 registry contract.
- *
- * pi-telegram's polling runtime invokes `dispatch`, so a partial object that
- * only carries `version` and `add` (which an early draft of the zero-coupling
- * docs showed) would silently break the first update. We treat any object
- * tagged `version === 1` but missing required methods as malformed and
- * replace it with a fresh, fully-formed registry. Layered extensions that
- * follow the full documented shape are unaffected; ones that don't lose any
- * handlers they registered against the malformed object, which is the
- * desired fail-loud-during-development behavior.
- */
-function isValidV1Registry(
-  candidate: unknown,
-): candidate is TelegramExternalHandlerRegistry {
-  if (!candidate || typeof candidate !== "object") return false;
-  const r = candidate as Partial<TelegramExternalHandlerRegistry>;
-  return (
-    r.version === 1 &&
-    typeof r.add === "function" &&
-    typeof r.dispatch === "function"
-  );
-}
-
-function getOrCreateRegistry(): TelegramExternalHandlerRegistry {
-  const g = globalThis as Record<string, unknown>;
-  const existing = g[REGISTRY_KEY];
-  if (isValidV1Registry(existing)) return existing;
-  const handlers = new Set<TelegramExternalHandler>();
-  const registry: TelegramExternalHandlerRegistry = {
-    version: 1,
-    add(handler) {
-      handlers.add(handler);
-      return () => handlers.delete(handler);
-    },
-    async dispatch(update) {
-      for (const handler of handlers) {
-        try {
-          const result = await handler(update);
-          if (result === "consume") return "consume";
-        } catch {
-          // External handler errors must not break polling.
-        }
-      }
-      return "pass";
-    },
-  };
-  g[REGISTRY_KEY] = registry;
-  return registry;
-}
-
-/**
- * Called by pi-telegram's own runtime to obtain the registry it dispatches
- * through. Layered extensions should not call this; use
- * {@link onTelegramExternalUpdate} instead.
- */
-export function getTelegramExternalHandlerRegistry(): TelegramExternalHandlerRegistry {
-  return getOrCreateRegistry();
-}
-
-export interface TelegramExternalHandlerWrapDeps<TUpdate, TContext> {
-  defaultHandle: (update: TUpdate, ctx: TContext) => Promise<void>;
-  registry?: TelegramExternalHandlerRegistry;
-}
-export type TelegramExternalInterceptorWrapDeps<TUpdate, TContext> =
-  TelegramExternalHandlerWrapDeps<TUpdate, TContext>;
-
-/**
- * Wrap a default polling `handleUpdate` with the external interceptor registry.
- *
- * Returned function dispatches `update` through registered interceptors first;
- * if any returns `"consume"`, default routing is skipped for that update.
- *
- * Composition-root callers (pi-telegram's `index.ts`) should use this builder
- * instead of writing the lifting logic inline.
- */
-export function createTelegramExternalHandleUpdate<TUpdate, TContext>(
-  deps: TelegramExternalHandlerWrapDeps<TUpdate, TContext>,
-): (update: TUpdate, ctx: TContext) => Promise<void> {
-  const registry = deps.registry ?? getOrCreateRegistry();
-  const { defaultHandle } = deps;
-  return async function handleInterceptedUpdate(update, ctx) {
-    const verdict = await registry.dispatch(update);
-    if (verdict === "consume") return;
-    await defaultHandle(update, ctx);
-  };
-}
-
-/**
- * Register an interceptor that runs before pi-telegram routes a Telegram
- * update through its built-in handlers (commands, app menu, queue menu,
- * model menu, default prompt routing).
- *
- * This is the recommended public surface for layered extensions that share
- * the same bot and pi process with pi-telegram (single bot ↔ single
- * `getUpdates` poller).
- *
- * Returns a disposer that removes the interceptor.
- *
- * @example
- * ```ts
- * import { onTelegramExternalUpdate } from "@llblab/pi-telegram/lib/external-handlers.ts";
- *
- * const off = onTelegramExternalUpdate(async (update) => {
- *   const cb = (update as { callback_query?: { data?: string } }).callback_query;
- *   if (!cb?.data?.startsWith("myext:")) return "pass";
- *   await handleMyCallback(cb);
- *   return "consume"; // skip pi-telegram's default routing for this update
- * });
- *
- * // later, e.g. on session shutdown:
- * off();
- * ```
- *
- * Extensions that prefer zero coupling can also reach the versioned registry
- * directly on `globalThis`. This avoids importing `@llblab/pi-telegram` and
- * tolerates either install order.
- */
-export function onTelegramExternalUpdate(
-  handler: TelegramExternalHandler,
-): () => void {
-  return getOrCreateRegistry().add(handler);
-}