@llblab/pi-kit 0.29.1 → 0.30.0

package/node_modules/@llblab/pi-telegram/lib/bus-api.ts

@@ -6,12 +6,11 @@
 
 import {
   markTelegramBusCrossTargetDelivery,
+  parseTelegramBusSelectedMenuTextEffect,
   stripTelegramBusApiMetadata,
+  type TelegramBusSelectedMenuDeliveryObservation,
+  type TelegramBusSelectedMenuTextEffect,
 } from "./bus.ts";
-import {
-  buildTelegramAnswerGuestQueryBody,
-  isTelegramMessageNotModifiedError,
-} from "./telegram-api.ts";
 import type { TelegramAttachmentSource } from "./media.ts";
 import type {
   TelegramAnswerGuestQueryOptions,
@@ -26,6 +25,13 @@ import type {
   TelegramSentMessage,
   TelegramUpdate,
 } from "./telegram-api.ts";
+import {
+  buildTelegramAnswerGuestQueryBody,
+  isTelegramApiCommitUnknownError,
+  isTelegramMessageNotModifiedError,
+  TelegramApiAuthorityError,
+  TelegramApiCommitUnknownError,
+} from "./telegram-api.ts";
 
 export type TelegramBusApiCall = (
   method: string,
@@ -83,6 +89,167 @@ function rejectTelegramDirectOwnership(method: string): Promise<never> {
   );
 }
 
+/** Bound selected-menu projection only; no ordinary/raw API fallback and no activation during preparation. */
+export function createTelegramSelectedMenuTextApi(deps: {
+  operationId: string;
+  registrationGeneration: string;
+  target: { chatId: number; threadId: number };
+  assertAuthority: () => void;
+  deliver(
+    effect: TelegramBusSelectedMenuTextEffect,
+    assertAuthority: () => void,
+  ): Promise<TelegramBusSelectedMenuDeliveryObservation>;
+}): Pick<TelegramBridgeApiRuntime, "sendMessage" | "editMessageText"> {
+  const { operationId, registrationGeneration, assertAuthority, deliver } =
+      deps,
+    target = { ...deps.target };
+  if (
+    typeof assertAuthority !== "function" ||
+    typeof deliver !== "function" ||
+    !operationId?.trim() ||
+    operationId.length > 128 ||
+    !registrationGeneration?.trim() ||
+    registrationGeneration.length > 128 ||
+    !Number.isSafeInteger(target.chatId) ||
+    target.chatId <= 0 ||
+    !Number.isSafeInteger(target.threadId) ||
+    target.threadId <= 0
+  )
+    throw new TelegramApiAuthorityError(false);
+  const invoke = async (
+    edit: boolean,
+    raw: Record<string, unknown>,
+    options?: Pick<TelegramApiCallOptions, "assertAuthority">,
+  ) => {
+    let issued = false;
+    const assertCurrent = () => {
+      try {
+        assertAuthority();
+      } catch {
+        throw new TelegramApiAuthorityError(issued);
+      }
+    };
+    try {
+      if (
+        options?.assertAuthority !== assertAuthority ||
+        Reflect.ownKeys(raw).some(
+          (key) =>
+            typeof key !== "string" ||
+            ![
+              "chat_id",
+              "message_thread_id",
+              "text",
+              "parse_mode",
+              "reply_markup",
+              ...(edit ? ["message_id"] : ["reply_parameters"]),
+            ].includes(key),
+        )
+      )
+        throw new TelegramApiAuthorityError(false);
+      const body = structuredClone(raw),
+        reply = body.reply_parameters;
+      if (
+        body.chat_id !== target.chatId ||
+        body.message_thread_id !== target.threadId ||
+        (reply !== undefined &&
+          (!reply ||
+            typeof reply !== "object" ||
+            Array.isArray(reply) ||
+            Object.keys(reply).some(
+              (key) =>
+                !["message_id", "allow_sending_without_reply"].includes(key),
+            ) ||
+            (reply as Record<string, unknown>).allow_sending_without_reply !==
+              true ||
+            !Number.isSafeInteger(
+              (reply as Record<string, unknown>).message_id,
+            ) ||
+            ((reply as Record<string, unknown>).message_id as number) <= 0))
+      )
+        throw new TelegramApiAuthorityError(false);
+      const effect = parseTelegramBusSelectedMenuTextEffect({
+        kind: edit ? "edit-text" : "send-text",
+        text: body.text,
+        ...(body.parse_mode !== undefined
+          ? { parseMode: body.parse_mode }
+          : {}),
+        ...(body.reply_markup !== undefined
+          ? { replyMarkup: body.reply_markup }
+          : {}),
+        ...(edit
+          ? { messageId: body.message_id }
+          : reply !== undefined
+            ? {
+                replyToMessageId: (reply as Record<string, unknown>).message_id,
+              }
+            : {}),
+      });
+      if (!effect) throw new TelegramApiAuthorityError(false);
+      assertCurrent();
+      issued = true;
+      const observed = await deliver.call(deps, effect, assertAuthority);
+      assertCurrent();
+      if (
+        observed.operationId !== operationId ||
+        observed.registrationGeneration !== registrationGeneration ||
+        observed.effect !== effect.kind ||
+        observed.recipient.target.chatId !== target.chatId ||
+        observed.recipient.target.threadId !== target.threadId ||
+        !Number.isSafeInteger(observed.messageId) ||
+        observed.messageId <= 0 ||
+        (effect.kind === "edit-text" && observed.messageId !== effect.messageId)
+      )
+        throw new Error("Selected-menu transport result is unconfirmed.");
+      assertCurrent();
+      return observed.messageId;
+    } catch (error) {
+      if (
+        error instanceof TelegramApiAuthorityError ||
+        isTelegramApiCommitUnknownError(error)
+      )
+        throw error;
+      if (issued)
+        throw new TelegramApiCommitUnknownError(
+          edit ? "editMessageText" : "sendMessage",
+          error,
+        );
+      throw new TelegramApiAuthorityError(false);
+    }
+  };
+  return {
+    sendMessage: async (body, options) => ({
+      message_id: await invoke(false, body, options),
+    }),
+    editMessageText: async (body, options) => {
+      await invoke(true, body, options);
+      return "edited";
+    },
+  };
+}
+
+/** Followers route every chat action through the leader's generic `sendChatAction` call. */
+function sendTelegramFollowerChatAction(
+  deps: Pick<
+    TelegramBusAwareApiRuntimeDeps,
+    "callFollowerApi" | "getDefaultTarget"
+  >,
+  chatId: number,
+  action: string,
+  options?: { message_thread_id?: number },
+): Promise<boolean> {
+  const body = withDefaultThreadTarget(
+    {
+      chat_id: chatId,
+      action,
+      ...(options?.message_thread_id !== undefined
+        ? { message_thread_id: options.message_thread_id }
+        : {}),
+    },
+    deps.getDefaultTarget?.(),
+  );
+  return deps.callFollowerApi("call", ["sendChatAction", body]).then(asBoolean);
+}
+
 export function createTelegramBusAwareApiRuntime(
   deps: TelegramBusAwareApiRuntimeDeps,
 ): TelegramBridgeApiRuntime {
@@ -92,13 +259,16 @@ export function createTelegramBusAwareApiRuntime(
       body: Record<string, unknown>,
       options?: TelegramApiCallOptions,
     ): Promise<TResponse> {
-      return deps.ownsDirect()
-        ? deps.directRuntime.call<TResponse>(method, body, options)
-        : (deps.callFollowerApi("call", [
-            method,
-            body,
-            options,
-          ]) as Promise<TResponse>);
+      if (deps.ownsDirect())
+        return deps.directRuntime.call<TResponse>(method, body, options);
+      // A process-local authority callback cannot cross IPC as an enforceable grant.
+      if (options?.assertAuthority)
+        return Promise.reject(new TelegramApiAuthorityError(false));
+      return deps.callFollowerApi("call", [
+        method,
+        body,
+        options,
+      ]) as Promise<TResponse>;
     },
     callMultipart<TResponse>(
       method: string,
@@ -108,25 +278,31 @@ export function createTelegramBusAwareApiRuntime(
       fileName: string,
       options?: TelegramApiCallOptions,
     ): Promise<TResponse> {
-      return deps.ownsDirect()
-        ? deps.directRuntime.callMultipart<TResponse>(
-            method,
-            fields,
-            fileField,
-            filePath,
-            fileName,
-            options,
-          )
-        : (deps.callFollowerApi("callMultipart", [
-            method,
-            fields,
-            fileField,
-            filePath,
-            fileName,
-            options,
-          ]) as Promise<TResponse>);
+      if (deps.ownsDirect())
+        return deps.directRuntime.callMultipart<TResponse>(
+          method,
+          fields,
+          fileField,
+          filePath,
+          fileName,
+          options,
+        );
+      if (options?.assertAuthority)
+        return Promise.reject(new TelegramApiAuthorityError(false));
+      return deps.callFollowerApi("callMultipart", [
+        method,
+        fields,
+        fileField,
+        filePath,
+        fileName,
+        options,
+      ]) as Promise<TResponse>;
     },
-    downloadFile(fileId: string, suggestedName: string, source?: TelegramAttachmentSource): Promise<string> {
+    downloadFile(
+      fileId: string,
+      suggestedName: string,
+      source?: TelegramAttachmentSource,
+    ): Promise<string> {
       // The source names the file (kind-scope-message); dropping it falls back to the bare generated name.
       return deps.ownsDirect()
         ? deps.directRuntime.downloadFile(fileId, suggestedName, source)
@@ -149,73 +325,39 @@ export function createTelegramBusAwareApiRuntime(
         ? deps.directRuntime.getUpdates(body, signal)
         : rejectTelegramDirectOwnership("getUpdates");
     },
-    setMyCommands(commands): Promise<boolean> {
-      return deps.ownsDirect()
-        ? deps.directRuntime.setMyCommands(commands)
-        : deps
-            .callFollowerApi("call", ["setMyCommands", { commands }])
-            .then(asBoolean);
+    setMyCommands(commands, options): Promise<boolean> {
+      if (deps.ownsDirect())
+        return deps.directRuntime.setMyCommands(commands, options);
+      if (options?.assertAuthority)
+        return Promise.reject(new TelegramApiAuthorityError(false));
+      return deps
+        .callFollowerApi("call", ["setMyCommands", { commands }])
+        .then(asBoolean);
     },
     sendChatAction(
       chatId: number,
       action: string,
       options?: { message_thread_id?: number },
     ): Promise<boolean> {
-      const body = withDefaultThreadTarget(
-        {
-          chat_id: chatId,
-          action,
-          ...(options?.message_thread_id !== undefined
-            ? { message_thread_id: options.message_thread_id }
-            : {}),
-        },
-        deps.getDefaultTarget?.(),
-      );
       return deps.ownsDirect()
         ? deps.directRuntime.sendChatAction(chatId, action, options)
-        : deps
-            .callFollowerApi("call", ["sendChatAction", body])
-            .then(asBoolean);
+        : sendTelegramFollowerChatAction(deps, chatId, action, options);
     },
     sendTypingAction(
       chatId: number,
       options?: { message_thread_id?: number },
     ): Promise<unknown> {
-      const body = withDefaultThreadTarget(
-        {
-          chat_id: chatId,
-          action: "typing",
-          ...(options?.message_thread_id !== undefined
-            ? { message_thread_id: options.message_thread_id }
-            : {}),
-        },
-        deps.getDefaultTarget?.(),
-      );
       return deps.ownsDirect()
         ? deps.directRuntime.sendTypingAction(chatId, options)
-        : deps
-            .callFollowerApi("call", ["sendChatAction", body])
-            .then(asBoolean);
+        : sendTelegramFollowerChatAction(deps, chatId, "typing", options);
     },
     sendRecordVoiceAction(
       chatId: number,
       options?: { message_thread_id?: number },
     ): Promise<unknown> {
-      const body = withDefaultThreadTarget(
-        {
-          chat_id: chatId,
-          action: "record_voice",
-          ...(options?.message_thread_id !== undefined
-            ? { message_thread_id: options.message_thread_id }
-            : {}),
-        },
-        deps.getDefaultTarget?.(),
-      );
       return deps.ownsDirect()
         ? deps.directRuntime.sendRecordVoiceAction(chatId, options)
-        : deps
-            .callFollowerApi("call", ["sendChatAction", body])
-            .then(asBoolean);
+        : sendTelegramFollowerChatAction(deps, chatId, "record_voice", options);
     },
     sendMessageDraft(
       chatId: number,
@@ -250,33 +392,41 @@ export function createTelegramBusAwareApiRuntime(
             .callFollowerApi("call", ["sendMessageDraft", scopedBody])
             .then(asBoolean);
     },
-    sendMessage(body: TelegramSendMessageBody): Promise<TelegramSentMessage> {
-      return deps.ownsDirect()
-        ? deps.directRuntime.sendMessage(stripTelegramBusApiMetadata(body))
-        : deps
-            .callFollowerApi("call", [
-              "sendMessage",
-              markFollowerCrossTargetDelivery(
-                body,
-                deps.getDefaultTarget?.(),
-              ),
-            ])
-            .then(asSentMessage);
+    sendMessage(
+      body: TelegramSendMessageBody,
+      options?: Pick<TelegramApiCallOptions, "assertAuthority">,
+    ): Promise<TelegramSentMessage> {
+      if (deps.ownsDirect())
+        return deps.directRuntime.sendMessage(
+          stripTelegramBusApiMetadata(body),
+          options,
+        );
+      if (options?.assertAuthority)
+        return Promise.reject(new TelegramApiAuthorityError(false));
+      return deps
+        .callFollowerApi("call", [
+          "sendMessage",
+          markFollowerCrossTargetDelivery(body, deps.getDefaultTarget?.()),
+        ])
+        .then(asSentMessage);
     },
     sendRichMessage(
       body: TelegramSendRichMessageBody,
+      options?: Pick<TelegramApiCallOptions, "assertAuthority">,
     ): Promise<TelegramSentMessage> {
-      return deps.ownsDirect()
-        ? deps.directRuntime.sendRichMessage(stripTelegramBusApiMetadata(body))
-        : deps
-            .callFollowerApi("call", [
-              "sendRichMessage",
-              markFollowerCrossTargetDelivery(
-                body,
-                deps.getDefaultTarget?.(),
-              ),
-            ])
-            .then(asSentMessage);
+      if (deps.ownsDirect())
+        return deps.directRuntime.sendRichMessage(
+          stripTelegramBusApiMetadata(body),
+          options,
+        );
+      if (options?.assertAuthority)
+        return Promise.reject(new TelegramApiAuthorityError(false));
+      return deps
+        .callFollowerApi("call", [
+          "sendRichMessage",
+          markFollowerCrossTargetDelivery(body, deps.getDefaultTarget?.()),
+        ])
+        .then(asSentMessage);
     },
     sendRichMessageDraft(
       body: TelegramSendRichMessageDraftBody,
@@ -289,8 +439,11 @@ export function createTelegramBusAwareApiRuntime(
     },
     async editMessageText(
       body: TelegramEditMessageTextBody,
+      options?: Pick<TelegramApiCallOptions, "assertAuthority">,
     ): Promise<"edited" | "unchanged"> {
-      if (deps.ownsDirect()) return deps.directRuntime.editMessageText(body);
+      if (deps.ownsDirect())
+        return deps.directRuntime.editMessageText(body, options);
+      if (options?.assertAuthority) throw new TelegramApiAuthorityError(false);
       try {
         await deps.callFollowerApi("call", ["editMessageText", body]);
         return "edited";
@@ -320,11 +473,21 @@ export function createTelegramBusAwareApiRuntime(
     async answerCallbackQuery(
       callbackQueryId: string,
       text?: string,
+      options?: Pick<TelegramApiCallOptions, "assertAuthority">,
     ): Promise<void> {
+      const assertAuthority = options?.assertAuthority;
       if (deps.ownsDirect()) {
-        await deps.directRuntime.answerCallbackQuery(callbackQueryId, text);
+        const authorityOptions:
+          [] | [Pick<TelegramApiCallOptions, "assertAuthority">] =
+          assertAuthority ? [{ assertAuthority }] : [];
+        await deps.directRuntime.answerCallbackQuery(
+          callbackQueryId,
+          text,
+          ...authorityOptions,
+        );
         return;
       }
+      if (assertAuthority) throw new TelegramApiAuthorityError(false);
       await deps.callFollowerApi("call", [
         "answerCallbackQuery",
         {