@llblab/pi-telegram 0.9.2 → 0.9.3

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.9.3: External Handlers Rename
+
+- `[External Handlers]` Renamed the external update handlers domain to `external-handlers` across source, tests, and docs. Impact: the interop domain now has a cleaner name aligned with inbound/outbound handler naming.
+- `[Breaking]` Removed the old `external-update-handlers` module/doc path and old exported update/interceptor aliases. Impact: layered extensions should import from `@llblab/pi-telegram/lib/external-handlers.ts` and use the `TelegramExternalHandler*` names.
+- `[Package]` Bumped package metadata to `0.9.3` and kept the lockfile in sync.
+
 ## 0.9.2: External Update Interceptors
 
 - `[External Update Interceptors]` Added a versioned `globalThis` registry that lets layered pi extensions observe and optionally consume Telegram updates before pi-telegram's default routing. Impact: approval gates and other same-process extensions can react synchronously to Telegram callbacks without owning a second bot poller.

package/README.md

@@ -224,7 +224,7 @@ List the main risks first.
 <!-- telegram_button: OK -->
 ```
 
-Button prompts are routed back into the normal Telegram queue as prompt turns. Keep the opening comment unclosed until the body-ending `-->` for body-form buttons. Closed heads must use `prompt="..."` or the colon shorthand to create a button. Unknown inline-button callbacks that do not belong to pi-telegram are forwarded to π as `[callback] <data>` so other extensions can namespace and handle their own Telegram buttons without polling the bot themselves; see the [Callback Namespace Standard](./docs/callback-namespaces.md). Layered extensions that need to react to Telegram updates synchronously inside their own runtime (for example, to resolve a blocking-tool approval Promise the moment a callback arrives) can register a runtime interceptor on the shared update registry; see [External Update Handlers](./docs/external-update-handlers.md). Outbound handler details are documented in [`docs/outbound-handlers.md`](./docs/outbound-handlers.md).
+Button prompts are routed back into the normal Telegram queue as prompt turns. Keep the opening comment unclosed until the body-ending `-->` for body-form buttons. Closed heads must use `prompt="..."` or the colon shorthand to create a button. Unknown inline-button callbacks that do not belong to pi-telegram are forwarded to π as `[callback] <data>` so other extensions can namespace and handle their own Telegram buttons without polling the bot themselves; see the [Callback Namespace Standard](./docs/callback-namespaces.md). Layered extensions that need to react to Telegram updates synchronously inside their own runtime (for example, to resolve a blocking-tool approval Promise the moment a callback arrives) can register a runtime interceptor on the shared update registry; see [External Handlers](./docs/external-handlers.md). Outbound handler details are documented in [`docs/outbound-handlers.md`](./docs/outbound-handlers.md).
 
 ## Streaming
 

package/docs/README.md

@@ -10,4 +10,4 @@ Living index of project documentation in `/docs`.
 - [outbound-handlers.md](./outbound-handlers.md) — Local `pi-telegram` outbound-handler config, text/voice/button behavior, artifact outputs, and callback routing
 - [locks.md](./locks.md) — Shared `locks.json` standard for singleton extension ownership
 - [callback-namespaces.md](./callback-namespaces.md) — Shared Telegram `callback_data` namespace standard for layered extensions
-- [external-update-handlers.md](./external-update-handlers.md) — Runtime interceptor registry that lets layered extensions observe and consume Telegram updates without owning their own polling connection
+- [external-handlers.md](./external-handlers.md) — Runtime interceptor registry that lets layered extensions observe and consume Telegram updates without owning their own polling connection

package/docs/{external-update-handlers.md → external-handlers.md}

@@ -1,4 +1,4 @@
-# External Update Handlers
+# External Handlers
 
 `pi-telegram` owns a single `getUpdates` long-poll connection per bot. Other
 pi extensions cannot open a competing poller against the same bot — the
@@ -12,7 +12,7 @@ fires.
 
 It is the runtime counterpart to
 [Callback Namespaces](./callback-namespaces.md): callback namespaces define
-how to share `callback_data` cleanly; external update handlers define how to
+how to share `callback_data` cleanly; external handlers define how to
 observe and optionally short-circuit the dispatch of those updates.
 
 ## When to use it
@@ -63,9 +63,9 @@ Two equivalent paths.
 ### Typed import (recommended when you can depend on `@llblab/pi-telegram`)
 
 ```ts
-import { onTelegramUpdate } from "@llblab/pi-telegram/lib/external-update-handlers.ts";
+import { onTelegramExternalUpdate } from "@llblab/pi-telegram/lib/external-handlers.ts";
 
-const off = onTelegramUpdate(async (update) => {
+const off = onTelegramExternalUpdate(async (update) => {
   const cb = (update as { callback_query?: { id?: string; data?: string } })
     .callback_query;
   if (!cb?.data?.startsWith("myext:")) return "pass";
@@ -83,7 +83,7 @@ When the layered extension prefers no `import` from `@llblab/pi-telegram` (so
 load order between the two extensions does not matter, and either can be
 installed first), it must implement the **full v1 registry contract**, not
 just `version` and `add`. pi-telegram's polling runtime calls `dispatch` on
-whatever object it finds at `globalThis.__piTelegramExternalUpdateRegistry__`,
+whatever object it finds at `globalThis.__piTelegramExternalHandlerRegistry__`,
 so a partial object would silently break the first update.
 
 pi-telegram defensively re-creates the registry if the object on `globalThis`
@@ -100,19 +100,19 @@ type PiTelegramVerdict =
   | Promise<"consume" | "pass" | void>;
 type PiTelegramInterceptor = (update: unknown) => PiTelegramVerdict;
 
-interface PiTelegramExternalUpdateRegistry {
+interface PiTelegramExternalHandlerRegistry {
   readonly version: 1;
   add: (handler: PiTelegramInterceptor) => () => void;
   // Required: pi-telegram's polling loop calls this on every update.
   dispatch: (update: unknown) => Promise<"consume" | "pass">;
 }
 
-const REGISTRY_KEY = "__piTelegramExternalUpdateRegistry__";
+const REGISTRY_KEY = "__piTelegramExternalHandlerRegistry__";
 
-function getOrCreateRegistry(): PiTelegramExternalUpdateRegistry {
+function getOrCreateRegistry(): PiTelegramExternalHandlerRegistry {
   const g = globalThis as Record<string, unknown>;
   const existing = g[REGISTRY_KEY] as
-    | PiTelegramExternalUpdateRegistry
+    | PiTelegramExternalHandlerRegistry
     | undefined;
   if (
     existing &&
@@ -123,7 +123,7 @@ function getOrCreateRegistry(): PiTelegramExternalUpdateRegistry {
     return existing;
   }
   const handlers = new Set<PiTelegramInterceptor>();
-  const registry: PiTelegramExternalUpdateRegistry = {
+  const registry: PiTelegramExternalHandlerRegistry = {
     version: 1,
     add(handler) {
       handlers.add(handler);
@@ -151,7 +151,7 @@ const off = getOrCreateRegistry().add((update) => {
 });
 ```
 
-The registry object on `globalThis.__piTelegramExternalUpdateRegistry__` is
+The registry object on `globalThis.__piTelegramExternalHandlerRegistry__` is
 versioned (`version: 1`) and stable across pi-telegram releases; future
 breaking changes will use a new schema version and a new key.
 

package/index.ts

@@ -8,7 +8,7 @@ import * as Api from "./lib/api.ts";
 import * as CommandTemplates from "./lib/command-templates.ts";
 import * as Commands from "./lib/commands.ts";
 import * as Config from "./lib/config.ts";
-import { createTelegramInterceptedHandleUpdate } from "./lib/external-update-handlers.ts";
+import { createTelegramExternalHandleUpdate } from "./lib/external-handlers.ts";
 import * as InboundHandlers from "./lib/inbound-handlers.ts";
 import * as Keyboard from "./lib/keyboard.ts";
 import * as Lifecycle from "./lib/lifecycle.ts";
@@ -359,7 +359,7 @@ export default function (pi: Pi.ExtensionAPI) {
     deleteWebhook,
     getUpdates,
     persistConfig: configStore.persist,
-    handleUpdate: createTelegramInterceptedHandleUpdate({
+    handleUpdate: createTelegramExternalHandleUpdate({
       defaultHandle: inboundRouteRuntime.handleUpdate,
     }),
     stopTypingLoop: typing.stop,

package/lib/{external-update-handlers.ts → external-handlers.ts}

@@ -1,5 +1,5 @@
 /**
- * External Telegram update interceptor registry
+ * 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
  */
@@ -10,16 +10,16 @@
  * - `"consume"` — the interceptor handled this update; pi-telegram skips default routing.
  * - `"pass"` (or `void`/`undefined`) — pi-telegram routes the update normally.
  */
-export type TelegramExternalUpdateVerdict = "consume" | "pass";
+export type TelegramExternalHandlerVerdict = "consume" | "pass";
 
-export type TelegramExternalUpdateInterceptor = (
+export type TelegramExternalHandler = (
   update: unknown,
 ) =>
-  | TelegramExternalUpdateVerdict
+  | TelegramExternalHandlerVerdict
   | void
-  | Promise<TelegramExternalUpdateVerdict | void>;
+  | Promise<TelegramExternalHandlerVerdict | void>;
 
-export interface TelegramExternalUpdateRegistry {
+export interface TelegramExternalHandlerRegistry {
   /** Schema version of this registry shape. */
   readonly version: 1;
   /**
@@ -29,17 +29,17 @@ export interface TelegramExternalUpdateRegistry {
    * before pi-telegram's own routing. The first interceptor that returns
    * `"consume"` wins and stops the chain for that update.
    */
-  add: (handler: TelegramExternalUpdateInterceptor) => () => void;
+  add: (handler: TelegramExternalHandler) => () => void;
   /**
    * Run all registered interceptors against an update.
    *
    * Used by pi-telegram's polling runtime; layered extensions should call
-   * {@link onTelegramUpdate} or `add` instead of dispatching directly.
+   * {@link onTelegramExternalUpdate} or `add` instead of dispatching directly.
    */
-  dispatch: (update: unknown) => Promise<TelegramExternalUpdateVerdict>;
+  dispatch: (update: unknown) => Promise<TelegramExternalHandlerVerdict>;
 }
 
-const REGISTRY_KEY = "__piTelegramExternalUpdateRegistry__";
+const REGISTRY_KEY = "__piTelegramExternalHandlerRegistry__";
 
 /**
  * Validate that a value on `globalThis` matches the full v1 registry contract.
@@ -55,9 +55,9 @@ const REGISTRY_KEY = "__piTelegramExternalUpdateRegistry__";
  */
 function isValidV1Registry(
   candidate: unknown,
-): candidate is TelegramExternalUpdateRegistry {
+): candidate is TelegramExternalHandlerRegistry {
   if (!candidate || typeof candidate !== "object") return false;
-  const r = candidate as Partial<TelegramExternalUpdateRegistry>;
+  const r = candidate as Partial<TelegramExternalHandlerRegistry>;
   return (
     r.version === 1 &&
     typeof r.add === "function" &&
@@ -65,12 +65,12 @@ function isValidV1Registry(
   );
 }
 
-function getOrCreateRegistry(): TelegramExternalUpdateRegistry {
+function getOrCreateRegistry(): TelegramExternalHandlerRegistry {
   const g = globalThis as Record<string, unknown>;
   const existing = g[REGISTRY_KEY];
   if (isValidV1Registry(existing)) return existing;
-  const handlers = new Set<TelegramExternalUpdateInterceptor>();
-  const registry: TelegramExternalUpdateRegistry = {
+  const handlers = new Set<TelegramExternalHandler>();
+  const registry: TelegramExternalHandlerRegistry = {
     version: 1,
     add(handler) {
       handlers.add(handler);
@@ -95,16 +95,18 @@ function getOrCreateRegistry(): TelegramExternalUpdateRegistry {
 /**
  * Called by pi-telegram's own runtime to obtain the registry it dispatches
  * through. Layered extensions should not call this; use
- * {@link onTelegramUpdate} instead.
+ * {@link onTelegramExternalUpdate} instead.
  */
-export function getTelegramExternalUpdateRegistry(): TelegramExternalUpdateRegistry {
+export function getTelegramExternalHandlerRegistry(): TelegramExternalHandlerRegistry {
   return getOrCreateRegistry();
 }
 
-export interface TelegramExternalInterceptorWrapDeps<TUpdate, TContext> {
+export interface TelegramExternalHandlerWrapDeps<TUpdate, TContext> {
   defaultHandle: (update: TUpdate, ctx: TContext) => Promise<void>;
-  registry?: TelegramExternalUpdateRegistry;
+  registry?: TelegramExternalHandlerRegistry;
 }
+export type TelegramExternalInterceptorWrapDeps<TUpdate, TContext> =
+  TelegramExternalHandlerWrapDeps<TUpdate, TContext>;
 
 /**
  * Wrap a default polling `handleUpdate` with the external interceptor registry.
@@ -115,8 +117,8 @@ export interface TelegramExternalInterceptorWrapDeps<TUpdate, TContext> {
  * Composition-root callers (pi-telegram's `index.ts`) should use this builder
  * instead of writing the lifting logic inline.
  */
-export function createTelegramInterceptedHandleUpdate<TUpdate, TContext>(
-  deps: TelegramExternalInterceptorWrapDeps<TUpdate, TContext>,
+export function createTelegramExternalHandleUpdate<TUpdate, TContext>(
+  deps: TelegramExternalHandlerWrapDeps<TUpdate, TContext>,
 ): (update: TUpdate, ctx: TContext) => Promise<void> {
   const registry = deps.registry ?? getOrCreateRegistry();
   const { defaultHandle } = deps;
@@ -140,9 +142,9 @@ export function createTelegramInterceptedHandleUpdate<TUpdate, TContext>(
  *
  * @example
  * ```ts
- * import { onTelegramUpdate } from "@llblab/pi-telegram/lib/external-update-handlers.ts";
+ * import { onTelegramExternalUpdate } from "@llblab/pi-telegram/lib/external-handlers.ts";
  *
- * const off = onTelegramUpdate(async (update) => {
+ * 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);
@@ -154,12 +156,12 @@ export function createTelegramInterceptedHandleUpdate<TUpdate, TContext>(
  * ```
  *
  * Extensions that prefer zero coupling can also reach the registry directly
- * via `globalThis.__piTelegramExternalUpdateRegistry__` (versioned object,
- * see {@link TelegramExternalUpdateRegistry}). This avoids importing
+ * via `globalThis.__piTelegramExternalHandlerRegistry__` (versioned object,
+ * see {@link TelegramExternalHandlerRegistry}). This avoids importing
  * `@llblab/pi-telegram` and tolerates either install order.
  */
-export function onTelegramUpdate(
-  handler: TelegramExternalUpdateInterceptor,
+export function onTelegramExternalUpdate(
+  handler: TelegramExternalHandler,
 ): () => void {
   return getOrCreateRegistry().add(handler);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "private": false,
   "description": "Better Telegram DM bridge extension for π",
   "type": "module",