@riseonly/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,535 @@
+declare const DEFAULT_API_BASE = "https://api.riseonly.net";
+declare const CANONICAL_API_PREFIX = "/api/bot/v1";
+declare const WEBHOOK_SECRET_HEADER = "x-riseonly-bot-api-secret-token";
+declare const IDEMPOTENCY_HEADER = "x-request-id";
+declare const SUPPORTED_METHODS: readonly ["getMe", "sendMessage", "sendPhoto", "sendVideo", "sendDocument", "sendAudio", "sendVoice", "sendAnimation", "editMessageText", "deleteMessage", "sendChatAction", "getUpdates", "setWebhook", "deleteWebhook", "getWebhookInfo", "setMyCommands", "getMyCommands", "deleteMyCommands", "answerCallbackQuery", "getChat"];
+type BotApiMethod = (typeof SUPPORTED_METHODS)[number];
+declare const UPDATE_TYPES: readonly ["message", "edited_message", "callback_query", "chat_member", "my_chat_member"];
+type UpdateType = (typeof UPDATE_TYPES)[number];
+declare const CHAT_ACTIONS: readonly ["typing", "upload_photo", "record_video", "upload_video", "record_voice", "upload_voice", "upload_document", "choose_sticker", "find_location", "record_video_note", "upload_video_note"];
+type ChatAction = (typeof CHAT_ACTIONS)[number];
+declare const COMMAND_SCOPES: readonly ["default", "all_private_chats", "all_group_chats", "all_chat_administrators"];
+type CommandScope = (typeof COMMAND_SCOPES)[number] | `chat:${string}` | `chat_administrators:${string}`;
+
+interface ApiResponse<T> {
+    ok: true;
+    result: T;
+}
+interface ApiErrorResponse {
+    ok: false;
+    error_code: number;
+    description: string;
+    parameters?: {
+        retry_after?: number;
+    };
+}
+type ApiEnvelope<T> = ApiResponse<T> | ApiErrorResponse;
+interface Capabilities {
+    platform: string;
+    api_version: string;
+    canonical_endpoint: string;
+    compatible_endpoint: string;
+    authorization: string;
+    idempotency_header: string;
+    webhook_secret_header: string;
+    update_delivery: string[];
+    mini_app_production_scheme: string;
+    methods: BotApiMethod[];
+}
+interface ClientOptions {
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    requestTimeoutMs?: number;
+    useCompatibleEndpoint?: boolean;
+}
+interface RequestOptions {
+    requestId?: string;
+    signal?: AbortSignal;
+}
+interface User {
+    id: string;
+    is_bot: boolean;
+    first_name: string;
+    name?: string;
+    username?: string;
+    description?: string;
+    avatar_url?: string;
+    banner_url?: string;
+    is_premium?: boolean;
+    is_official?: boolean;
+    is_online?: boolean;
+    last_seen?: string;
+    bot_owner_id?: string;
+    can_join_groups?: boolean;
+    supports_inline_queries?: boolean;
+    privacy_mode?: boolean;
+}
+interface Chat {
+    id: string;
+    type: 'private' | 'group' | 'channel' | string;
+    title?: string;
+    username?: string;
+    description?: string;
+    avatar_url?: string;
+    member_count?: number;
+}
+interface MediaVariant {
+    variant_type?: string;
+    width?: number;
+    height?: number;
+    size?: number;
+    file_url?: string;
+    file_id?: string;
+    bitrate?: number;
+    quality?: string;
+}
+interface MediaFile {
+    type?: string;
+    media_type?: string;
+    file_id?: string;
+    file_url?: string;
+    thumbnail_url?: string;
+    duration?: number;
+    width?: number;
+    height?: number;
+    file_name?: string;
+    file_size?: number;
+    mime_type?: string;
+    bitrate?: number;
+    fps?: number;
+    codec?: string;
+    sticker_id?: string;
+    pack_id?: string;
+    sticker_type?: string;
+    associated_emojis?: string[];
+    variants?: MediaVariant[];
+}
+interface MessageEntity {
+    type: string;
+    offset: number;
+    length: number;
+    url?: string;
+    user?: User;
+}
+interface WebAppInfo {
+    url: string;
+    bot_id?: string;
+    mini_app_id?: string;
+}
+interface InlineKeyboardButton {
+    text: string;
+    url?: string;
+    callback_data?: string;
+    web_app?: WebAppInfo;
+}
+interface ReplyKeyboardButton {
+    text: string;
+    request_contact?: boolean;
+    request_location?: boolean;
+    web_app?: WebAppInfo;
+}
+interface InlineKeyboardMarkup {
+    inline_keyboard: InlineKeyboardButton[][];
+}
+interface ReplyKeyboardMarkup {
+    keyboard: ReplyKeyboardButton[][];
+    resize_keyboard?: boolean;
+    one_time_keyboard?: boolean;
+    selective?: boolean;
+}
+interface ReplyKeyboardRemove {
+    remove_keyboard: true;
+    selective?: boolean;
+}
+interface ForceReply {
+    force_reply: true;
+    selective?: boolean;
+}
+type ReplyMarkup = InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply;
+interface WebAppData {
+    data: string;
+    button_text: string;
+}
+interface ForwardOrigin {
+    chat_id: string;
+    message_id: string;
+    sender_id?: string;
+    sender_name?: string;
+    sender_logo?: string;
+    date?: number;
+    forward_chain_count?: number;
+    original_message_id?: string;
+}
+interface ReactionCount {
+    reaction: string;
+    count: number;
+    reacted_by_you?: boolean;
+}
+interface Message {
+    message_id: string;
+    date: number;
+    timestamp?: number;
+    chat: Chat;
+    from?: User;
+    text?: string;
+    content?: string;
+    original_content?: string;
+    content_type?: string;
+    is_edited?: boolean;
+    is_bot_message?: boolean;
+    edit_date?: number;
+    caption?: string;
+    entities?: MessageEntity[];
+    reply_markup?: ReplyMarkup;
+    web_app_data?: WebAppData;
+    reply_to_message?: Message;
+    forward_origin?: ForwardOrigin;
+    via_bot?: User;
+    message_thread_id?: string;
+    temp_id?: string;
+    media_items?: MediaFile[];
+    photo?: MediaFile[];
+    video?: MediaFile;
+    video_note?: MediaFile;
+    audio?: MediaFile;
+    voice?: MediaFile;
+    document?: MediaFile;
+    animation?: MediaFile;
+    sticker?: MediaFile;
+    reactions?: ReactionCount[];
+}
+interface CallbackQuery {
+    id: string;
+    from: User;
+    message?: Message;
+    inline_message_id?: string;
+    chat_instance?: string;
+    data?: string;
+    game_short_name?: string;
+}
+interface Update {
+    update_id: number;
+    message?: Message;
+    edited_message?: Message;
+    callback_query?: CallbackQuery;
+    chat_member?: unknown;
+    my_chat_member?: unknown;
+}
+interface BotCommand {
+    command: string;
+    description: string;
+}
+interface WebhookInfo {
+    url: string;
+    has_custom_certificate: boolean;
+    pending_update_count: number;
+    last_error_date?: number;
+    last_error_message?: string;
+    max_connections?: number;
+    allowed_updates?: UpdateType[];
+    enabled?: boolean;
+}
+interface SetWebhookResult {
+    url: string;
+    enabled: boolean;
+}
+interface SendMessageOptions {
+    chat_id: string;
+    text?: string;
+    caption?: string;
+    parse_mode?: string;
+    disable_notification?: boolean;
+    reply_to_message_id?: string;
+    reply_markup?: ReplyMarkup;
+    requestId?: string;
+}
+interface SendMediaOptions {
+    chat_id: string;
+    caption?: string;
+    disable_notification?: boolean;
+    reply_to_message_id?: string;
+    reply_markup?: ReplyMarkup;
+    requestId?: string;
+}
+interface EditMessageTextOptions {
+    chat_id?: string;
+    message_id?: string;
+    inline_message_id?: string;
+    text: string;
+    parse_mode?: string;
+    reply_markup?: ReplyMarkup;
+    requestId?: string;
+}
+interface DeleteMessageOptions {
+    chat_id: string;
+    message_id: string;
+    requestId?: string;
+}
+interface SendChatActionOptions {
+    chat_id: string;
+    action: ChatAction;
+    requestId?: string;
+}
+interface GetUpdatesOptions {
+    offset?: number;
+    limit?: number;
+    timeout?: number;
+    allowed_updates?: UpdateType[];
+    requestId?: string;
+    signal?: AbortSignal;
+}
+interface SetWebhookOptions {
+    url: string;
+    secret_token?: string;
+    max_connections?: number;
+    allowed_updates?: UpdateType[];
+    drop_pending_updates?: boolean;
+    requestId?: string;
+}
+interface DeleteWebhookOptions {
+    drop_pending_updates?: boolean;
+    requestId?: string;
+}
+interface SetMyCommandsOptions {
+    commands: BotCommand[];
+    scope?: CommandScope;
+    language_code?: string;
+    requestId?: string;
+}
+interface GetMyCommandsOptions {
+    scope?: CommandScope;
+    language_code?: string;
+    requestId?: string;
+}
+interface DeleteMyCommandsOptions {
+    scope?: CommandScope;
+    language_code?: string;
+    requestId?: string;
+}
+interface AnswerCallbackQueryOptions {
+    callback_query_id: string;
+    text?: string;
+    show_alert?: boolean;
+    url?: string;
+    requestId?: string;
+}
+interface GetChatOptions {
+    chat_id: string;
+    requestId?: string;
+}
+type MediaInput = string | {
+    file_id?: string;
+    url?: string;
+};
+interface PollingOptions {
+    interval?: number;
+    timeout?: number;
+    limit?: number;
+    allowed_updates?: UpdateType[];
+    autoStart?: boolean;
+}
+interface WebhookServerOptions {
+    path?: string;
+    host?: string;
+    port?: number;
+    secretToken?: string;
+}
+interface BotOptions extends ClientOptions {
+    polling?: boolean | PollingOptions;
+    webhook?: false | WebhookServerOptions;
+    allowed_updates?: UpdateType[];
+}
+type MessageHandler = (message: Message, update: Update) => void | Promise<void>;
+type EditedMessageHandler = (message: Message, update: Update) => void | Promise<void>;
+type CallbackQueryHandler = (query: CallbackQuery, update: Update) => void | Promise<void>;
+type UpdateHandler = (update: Update) => void | Promise<void>;
+type ErrorHandler = (error: unknown) => void | Promise<void>;
+type PollingErrorHandler = (error: unknown) => void | Promise<void>;
+type BotEventMap = {
+    message: MessageHandler;
+    edited_message: EditedMessageHandler;
+    callback_query: CallbackQueryHandler;
+    update: UpdateHandler;
+    polling_error: PollingErrorHandler;
+    error: ErrorHandler;
+};
+type BotEvent = keyof BotEventMap;
+
+declare class ApiClient {
+    readonly token: string;
+    readonly baseUrl: string;
+    readonly fetchImpl: typeof fetch;
+    readonly requestTimeoutMs: number;
+    readonly useCompatibleEndpoint: boolean;
+    constructor(token: string, options?: ClientOptions);
+    /**
+     * Returns the platform capabilities document.
+     */
+    getCapabilities(signal?: AbortSignal): Promise<Capabilities>;
+    /**
+     * Calls a Bot API method and returns the typed result.
+     */
+    callMethod<T>(method: string, payload?: Record<string, unknown>, options?: RequestOptions): Promise<T>;
+    /**
+     * Performs a raw Bot API request and returns the full envelope.
+     */
+    request<T>(method: string, payload?: Record<string, unknown>, options?: RequestOptions): Promise<ApiEnvelope<T> & {
+        ok: true;
+        result: T;
+    }>;
+    getMe(options?: RequestOptions): Promise<User>;
+    sendMessage(options: SendMessageOptions): Promise<Message>;
+    sendPhoto(photo: MediaInput, options: SendMediaOptions): Promise<Message>;
+    sendVideo(video: MediaInput, options: SendMediaOptions): Promise<Message>;
+    sendDocument(document: MediaInput, options: SendMediaOptions): Promise<Message>;
+    sendAudio(audio: MediaInput, options: SendMediaOptions): Promise<Message>;
+    sendVoice(voice: MediaInput, options: SendMediaOptions): Promise<Message>;
+    sendAnimation(animation: MediaInput, options: SendMediaOptions): Promise<Message>;
+    editMessageText(options: EditMessageTextOptions): Promise<Message>;
+    deleteMessage(options: DeleteMessageOptions): Promise<boolean>;
+    sendChatAction(options: SendChatActionOptions): Promise<boolean>;
+    getUpdates(options?: GetUpdatesOptions): Promise<Update[]>;
+    setWebhook(options: SetWebhookOptions): Promise<SetWebhookResult>;
+    deleteWebhook(options?: DeleteWebhookOptions): Promise<boolean>;
+    getWebhookInfo(options?: RequestOptions): Promise<WebhookInfo>;
+    setMyCommands(options: SetMyCommandsOptions): Promise<boolean>;
+    getMyCommands(options?: GetMyCommandsOptions): Promise<BotCommand[]>;
+    deleteMyCommands(options?: DeleteMyCommandsOptions): Promise<boolean>;
+    answerCallbackQuery(options: AnswerCallbackQueryOptions): Promise<boolean>;
+    getChat(options: GetChatOptions): Promise<Chat>;
+    private sendMedia;
+    private normalizeMedia;
+    private buildMethodUrl;
+}
+
+declare class RiseonlyBot extends ApiClient {
+    private readonly listeners;
+    private pollingOptions;
+    private webhookOptions?;
+    private polling;
+    private pollingAbort?;
+    private offset;
+    private webhookServer?;
+    constructor(token: string, options?: BotOptions);
+    /**
+     * Registers an event listener.
+     */
+    on<T extends BotEvent>(event: T, handler: BotEventMap[T]): this;
+    /**
+     * Removes a previously registered listener.
+     */
+    off<T extends BotEvent>(event: T, handler: BotEventMap[T]): this;
+    /**
+     * Registers a one-time event listener.
+     */
+    once<T extends BotEvent>(event: T, handler: BotEventMap[T]): this;
+    /**
+     * Starts long polling for bot updates.
+     */
+    startPolling(options?: PollingOptions): Promise<void>;
+    /**
+     * Stops long polling.
+     */
+    stopPolling(): Promise<void>;
+    /**
+     * Starts a built-in HTTP server that receives webhook updates.
+     */
+    startWebhook(options?: WebhookServerOptions): Promise<void>;
+    /**
+     * Stops the built-in webhook server.
+     */
+    stopWebhook(): Promise<void>;
+    /**
+     * Processes a single update and dispatches events.
+     */
+    processUpdate(update: Update): Promise<void>;
+    /**
+     * Sends a text message to a chat.
+     */
+    reply(message: Message, text: string, extra?: Record<string, unknown>): Promise<Message>;
+    /**
+     * Answers a callback query and optionally sends a toast.
+     */
+    answer(query: CallbackQuery, text?: string, showAlert?: boolean): Promise<boolean>;
+    private pollLoop;
+    private emit;
+}
+
+declare class RiseonlyError extends Error {
+    readonly code: number;
+    readonly retryAfter?: number;
+    readonly response?: unknown;
+    constructor(message: string, code: number, retryAfter?: number, response?: unknown);
+    static fromApiResponse(body: {
+        error_code: number;
+        description: string;
+        parameters?: {
+            retry_after?: number;
+        };
+    }): RiseonlyError;
+}
+declare class RiseonlyNetworkError extends RiseonlyError {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown, code?: number);
+}
+declare class RiseonlyTimeoutError extends RiseonlyNetworkError {
+    constructor(message?: string);
+}
+
+interface WebhookRequest {
+    headers: Record<string, string | string[] | undefined>;
+    body: unknown;
+}
+/**
+ * Parses a webhook request body into an Update object.
+ */
+declare function parseWebhookUpdate(body: unknown): Update;
+/**
+ * Verifies the webhook secret header sent by Riseonly.
+ */
+declare function verifyWebhookSecret(headers: Record<string, string | string[] | undefined>, secretToken?: string): boolean;
+/**
+ * Creates a minimal request handler for frameworks like Express or Fastify.
+ */
+declare function createWebhookHandler(options: {
+    secretToken?: string;
+    onUpdate: (update: Update) => void | Promise<void>;
+    onError?: (error: unknown) => void | Promise<void>;
+}): (request: WebhookRequest) => Promise<{
+    status: number;
+    body?: unknown;
+}>;
+
+interface InitDataFields {
+    [key: string]: string;
+}
+/**
+ * Parses URL-encoded init data into key/value fields.
+ */
+declare function parseInitData(encoded: string): InitDataFields;
+/**
+ * Builds the data check string used for init data signature verification.
+ */
+declare function buildInitDataCheckString(fields: InitDataFields): string;
+/**
+ * Derives the HMAC secret from a bot token.
+ */
+declare function deriveInitDataSecret(botToken: string): Buffer;
+/**
+ * Computes the expected init data hash for a bot token.
+ */
+declare function signInitData(botToken: string, dataCheckString: string): string;
+/**
+ * Verifies signed mini app init data.
+ */
+declare function verifyInitData(botToken: string, encoded: string): InitDataFields;
+/**
+ * Extracts init data from a launch URL hash fragment.
+ */
+declare function extractInitDataFromLaunchUrl(launchUrl: string): string | null;
+/**
+ * Creates a random idempotency key for Bot API requests.
+ */
+declare function createRequestId(): string;
+
+export { type AnswerCallbackQueryOptions, ApiClient, type ApiEnvelope, type ApiErrorResponse, type ApiResponse, type BotCommand, type BotEvent, type BotEventMap, type BotOptions, CANONICAL_API_PREFIX, CHAT_ACTIONS, COMMAND_SCOPES, type CallbackQuery, type CallbackQueryHandler, type Capabilities, type Chat, type ClientOptions, DEFAULT_API_BASE, type DeleteMessageOptions, type DeleteMyCommandsOptions, type DeleteWebhookOptions, type EditMessageTextOptions, type EditedMessageHandler, type ErrorHandler, type ForceReply, type ForwardOrigin, type GetChatOptions, type GetMyCommandsOptions, type GetUpdatesOptions, IDEMPOTENCY_HEADER, type InlineKeyboardButton, type InlineKeyboardMarkup, type MediaFile, type MediaInput, type MediaVariant, type Message, type MessageEntity, type MessageHandler, type PollingErrorHandler, type PollingOptions, type ReactionCount, type ReplyKeyboardButton, type ReplyKeyboardMarkup, type ReplyKeyboardRemove, type ReplyMarkup, type RequestOptions, RiseonlyBot, RiseonlyError, RiseonlyNetworkError, RiseonlyTimeoutError, SUPPORTED_METHODS, type SendChatActionOptions, type SendMediaOptions, type SendMessageOptions, type SetMyCommandsOptions, type SetWebhookOptions, type SetWebhookResult, UPDATE_TYPES, type Update, type UpdateHandler, type User, WEBHOOK_SECRET_HEADER, type WebAppData, type WebAppInfo, type WebhookInfo, type WebhookServerOptions, buildInitDataCheckString, createRequestId, createWebhookHandler, deriveInitDataSecret, extractInitDataFromLaunchUrl, parseInitData, parseWebhookUpdate, signInitData, verifyInitData, verifyWebhookSecret };