@effect-ak/tg-bot 1.2.4 → 1.3.0

package/dist/index.d.ts

@@ -1,32 +1,11 @@
-import * as effect_Types from 'effect/Types';
-import { Api, Update } from '@effect-ak/tg-bot-api';
-import * as Context from 'effect/Context';
-import * as Data from 'effect/Data';
-import { TgBotClient } from '@effect-ak/tg-bot-client';
-import * as effect_Cause from 'effect/Cause';
-import * as Micro from 'effect/Micro';
+import { Api, Update, Message, CallbackQuery, InlineQuery } from '@effect-ak/tg-bot-api';
 
-type BotResult = {
-    [K in keyof Api]: K extends `send_${infer R}` ? {
-        type: R;
-    } & Omit<Parameters<Api[K]>[0], "chat_id"> : never;
-}[keyof Api];
-declare const BotResponse_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => Readonly<A> & {
-    readonly _tag: "BotResponse";
-};
-declare class BotResponse extends BotResponse_base<{
-    response?: BotResult;
-}> {
-    static make(result: BotResult): BotResponse;
-    static readonly ignore: BotResponse;
-}
+/**
+ * @module polling
+ * Long-polling infrastructure: settings validation and the UpdateFetcher
+ * that pulls updates from the Telegram API in a loop.
+ */
 
-declare const BotUpdateHandlersTag_base: Context.TagClass<BotUpdateHandlersTag, "BotUpdateHandlers", BotMode>;
-declare class BotUpdateHandlersTag extends BotUpdateHandlersTag_base {
-}
-declare const BotTgClientTag_base: Context.TagClass<BotTgClientTag, "BotTgClient", TgBotClient>;
-declare class BotTgClientTag extends BotTgClientTag_base {
-}
 interface PollSettings {
     log_level: "info" | "debug";
     on_error: "stop" | "continue";
@@ -34,29 +13,57 @@ interface PollSettings {
     poll_timeout: number;
     max_empty_responses: number | undefined;
 }
-declare class BotPollSettings extends Data.Class<PollSettings> {
-    static make(input: Partial<PollSettings>): BotPollSettings;
+
+type BotResult = {
+    [K in keyof Api]: K extends `send_${infer R}` ? {
+        type: R;
+    } & Omit<Parameters<Api[K]>[0], "chat_id"> : never;
+}[keyof Api];
+declare class BotResponse {
+    readonly response: BotResult | undefined;
+    constructor(response?: BotResult);
+    static make(result: BotResult): BotResponse;
+    static readonly ignore: BotResponse;
 }
-declare const BotPollSettingsTag_base: Context.ReferenceClass<BotPollSettings, "BotSettings", BotPollSettings>;
-declare class BotPollSettingsTag extends BotPollSettingsTag_base {
+interface HandleResult {
+    update: Update;
+    updateType: string;
+    status: "handled" | "ignored" | "no_handler" | "error";
+    responseType?: string;
+    error?: string;
+    duration: number;
+}
+interface BotLogger {
+    debug: (message: string, data?: unknown) => void;
+    info: (message: string, data?: unknown) => void;
+    warn: (message: string, data?: unknown) => void;
+    error: (message: string, data?: unknown) => void;
 }
-
 type RunBotInput = RunBotInputSingle | RunBotInputBatch;
 interface RunBotInputSingle extends BotUpdatesHandlers {
     bot_token: string;
     mode: "single";
     poll?: Partial<PollSettings>;
+    onUpdate?: (update: Update) => void;
+    onHandleResult?: (result: HandleResult) => void;
+    logger?: BotLogger;
 }
 interface RunBotInputBatch extends HandleBatchUpdateFunction {
     bot_token: string;
     mode: "batch";
     poll?: Partial<PollSettings>;
+    onUpdate?: (update: Update) => void;
+    onHandleResult?: (result: HandleResult) => void;
+    logger?: BotLogger;
 }
 type ExtractedUpdate<K extends AvailableUpdateTypes> = {
     type: K;
 } & Update[K];
 type AvailableUpdateTypes = Exclude<keyof Update, "update_id">;
 type HandleUpdateFunction<U> = (update: U) => BotResponse | PromiseLike<BotResponse>;
+type BotResponseParams<T extends string> = Extract<Parameters<typeof BotResponse.make>[0], {
+    type: T;
+}>;
 interface BotContext {
     readonly command: string | undefined;
     readonly reply: (text: string, options?: Omit<BotResponseParams<"message">, "text" | "type">) => BotResponse;
@@ -64,9 +71,6 @@ interface BotContext {
     readonly replyWithPhoto: (photo: BotResponseParams<"photo">["photo"], options?: Omit<BotResponseParams<"photo">, "photo" | "type">) => BotResponse;
     readonly ignore: BotResponse;
 }
-type BotResponseParams<T extends string> = Extract<Parameters<typeof BotResponse.make>[0], {
-    type: T;
-}>;
 interface HandlerInput<U> {
     readonly update: U;
     readonly ctx: BotContext;
@@ -82,68 +86,93 @@ type BotUpdatesHandlers = {
 interface HandleBatchUpdateFunction {
     readonly on_batch: (update: Update[]) => boolean | PromiseLike<boolean>;
 }
-interface BotSingleMode extends BotUpdatesHandlers {
+interface BotSingleBehavior extends BotUpdatesHandlers {
     type: "single";
 }
-interface BotBatchMode extends HandleBatchUpdateFunction {
+interface BotBatchBehavior extends HandleBatchUpdateFunction {
     type: "batch";
 }
-type BotMode = BotSingleMode | BotBatchMode;
-
+type BotBehavior = BotSingleBehavior | BotBatchBehavior;
 declare const createBotContext: (update: unknown) => BotContext;
 
+/**
+ * @module bot-processor
+ * Update processing pipeline: extracts the update type, matches it to
+ * the registered handler (function, guard, or guard array), executes
+ * the handler, and sends the response back to Telegram.
+ */
+
 declare const extractUpdate: <U extends AvailableUpdateTypes>(input: Update) => ExtractedUpdate<U> | undefined;
-declare class BatchUpdateResult extends Data.Class<{
-    hasErrors: boolean;
-    updates: Update[];
-}> {
-}
-declare const handleUpdates: (updates: Update[]) => Micro.Micro<BatchUpdateResult, never, BotUpdateHandlersTag | BotTgClientTag>;
-declare const handleEntireBatch: (updates: Update[], handlers: HandleBatchUpdateFunction) => Micro.Micro<BatchUpdateResult, never, never>;
-declare const HandleUpdateError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
-    readonly _tag: "HandleUpdateError";
-} & Readonly<A>;
-declare class HandleUpdateError extends HandleUpdateError_base<{
-    name: "UnknownUpdate" | "HandlerNotDefined" | "BotHandlerError";
-    update: Update;
-    cause?: unknown;
-}> {
-    logInfo(): {
-        error?: string;
-        updateId: number;
-        updateKey: string | undefined;
-        name: "HandleUpdateError";
-    };
-}
-declare const handleOneByOne: (updates: Update[], handlers: BotUpdatesHandlers, pollSettings: PollSettings) => Micro.Micro<BatchUpdateResult, never, BotTgClientTag>;
-declare const handleOneUpdate: (updateObject: Update, handlers: BotUpdatesHandlers) => Micro.Micro<HandleUpdateError | undefined, unknown, BotTgClientTag>;
 
-type BotInstance = Micro.Micro.Success<ReturnType<typeof launchBot>>;
-declare const launchBot: (input: RunBotInput) => Micro.Micro<{
-    readonly reload: (mode: BotMode) => Promise<void>;
-    readonly fiber: () => Micro.MicroFiber<BatchUpdateResult, unknown> | undefined;
-}, never, never>;
+/**
+ * @module run
+ * Bot execution entry points: long-polling runner ({@link runBot})
+ * and webhook handler ({@link createWebhook}).
+ */
 
-declare const BotRunService_base: Context.ReferenceClass<BotRunService, "BotRunService", {
-    readonly runBotInBackground: Micro.Micro<void, never, BotUpdateHandlersTag | BotTgClientTag>;
-    readonly getFiber: () => Micro.MicroFiber<BatchUpdateResult, unknown> | undefined;
-}>;
-declare class BotRunService extends BotRunService_base {
+interface BotInstance {
+    stop(): void;
+    reload(behavior: BotBehavior): void;
 }
-
-declare const runTgChatBot: (input: RunBotInput) => Promise<{
-    readonly reload: (mode: BotMode) => Promise<void>;
-    readonly fiber: () => Micro.MicroFiber<BatchUpdateResult, unknown> | undefined;
-}>;
+declare const runBot: (input: RunBotInput) => Promise<BotInstance>;
 declare const defineBot: (input: BotUpdatesHandlers) => BotUpdatesHandlers;
-
 interface WebhookBotConfig extends BotUpdatesHandlers {
     bot_token: string;
+    onHandleResult?: (result: HandleResult) => void;
+    logger?: BotLogger;
 }
 interface WebhookHandler {
     (request: Request): Promise<Response>;
     handleUpdate: (update: Update) => Promise<void>;
 }
-declare const createWebhookHandler: (config: WebhookBotConfig) => WebhookHandler;
+declare const createWebhook: (config: WebhookBotConfig) => WebhookHandler;
+
+type HandlerFn<U> = (input: HandlerInput<U>) => BotResponse | PromiseLike<BotResponse>;
+interface MessageHelpers {
+    command: (cmd: string, handler: HandlerFn<Message>) => GuardedHandler<Message>;
+    text: (handler: HandlerFn<Message>) => GuardedHandler<Message>;
+    photo: (handler: HandlerFn<Message>) => GuardedHandler<Message>;
+    document: (handler: HandlerFn<Message>) => GuardedHandler<Message>;
+    sticker: (handler: HandlerFn<Message>) => GuardedHandler<Message>;
+    fallback: (handler: HandlerFn<Message>) => GuardedHandler<Message>;
+}
+interface CallbackQueryHelpers {
+    data: (pattern: string | RegExp, handler: HandlerFn<CallbackQuery>) => GuardedHandler<CallbackQuery>;
+    fallback: (handler: HandlerFn<CallbackQuery>) => GuardedHandler<CallbackQuery>;
+}
+interface InlineQueryHelpers {
+    query: (pattern: string | RegExp, handler: HandlerFn<InlineQuery>) => GuardedHandler<InlineQuery>;
+    fallback: (handler: HandlerFn<InlineQuery>) => GuardedHandler<InlineQuery>;
+}
+interface GenericHelpers<U> {
+    fallback: (handler: HandlerFn<U>) => GuardedHandler<U>;
+}
+type HandlerRegistration<U, H> = ((helpers: H) => GuardedHandler<U>[]) | GuardedHandler<U>[];
+interface BotRunConfig {
+    bot_token: string;
+    poll?: Partial<PollSettings>;
+    onUpdate?: (update: Update) => void;
+    onHandleResult?: (result: HandleResult) => void;
+    logger?: BotLogger;
+}
+interface BotWebhookConfig {
+    bot_token: string;
+    onHandleResult?: (result: HandleResult) => void;
+    logger?: BotLogger;
+}
+interface Bot {
+    onMessage(input: HandlerRegistration<Message, MessageHelpers>): Bot;
+    onEditedMessage(input: HandlerRegistration<Message, GenericHelpers<Message>>): Bot;
+    onChannelPost(input: HandlerRegistration<Message, GenericHelpers<Message>>): Bot;
+    onEditedChannelPost(input: HandlerRegistration<Message, GenericHelpers<Message>>): Bot;
+    onBusinessMessage(input: HandlerRegistration<Message, GenericHelpers<Message>>): Bot;
+    onEditedBusinessMessage(input: HandlerRegistration<Message, GenericHelpers<Message>>): Bot;
+    onCallbackQuery(input: HandlerRegistration<CallbackQuery, CallbackQueryHelpers>): Bot;
+    onInlineQuery(input: HandlerRegistration<InlineQuery, InlineQueryHelpers>): Bot;
+    on<K extends AvailableUpdateTypes>(type: K, input: HandlerRegistration<NonNullable<Update[K]>, GenericHelpers<NonNullable<Update[K]>>>): Bot;
+    run(config: BotRunConfig): Promise<BotInstance>;
+    webhook(config: BotWebhookConfig): WebhookHandler;
+}
+declare function createBot(): Bot;
 
-export { type AvailableUpdateTypes, BatchUpdateResult, type BotBatchMode, type BotContext, type BotInstance, type BotMode, BotPollSettings, BotPollSettingsTag, BotResponse, BotRunService, type BotSingleMode, BotTgClientTag, BotUpdateHandlersTag, type BotUpdatesHandlers, type ExtractedUpdate, type GuardedHandler, type HandleBatchUpdateFunction, HandleUpdateError, type HandleUpdateFunction, type HandlerInput, type PollSettings, type RunBotInput, type RunBotInputBatch, type RunBotInputSingle, type UpdateHandler, type WebhookBotConfig, type WebhookHandler, createBotContext, createWebhookHandler, defineBot, extractUpdate, handleEntireBatch, handleOneByOne, handleOneUpdate, handleUpdates, launchBot, runTgChatBot };
+export { type Bot, type BotContext, type BotInstance, type BotLogger, BotResponse, type BotUpdatesHandlers, type GuardedHandler, type HandleResult, type HandleUpdateFunction, type HandlerInput, type PollSettings, type RunBotInput, type UpdateHandler, type WebhookBotConfig, type WebhookHandler, createBot, createBotContext, createWebhook, defineBot, extractUpdate, runBot };