@riseonly/sdk 0.1.1-next.0 → 0.1.2

package/README.md

@@ -15,14 +15,13 @@ import { RiseonlyBot } from '@riseonly/sdk';
 
 const bot = new RiseonlyBot(process.env.BOT_TOKEN, { polling: true });
 
-bot.on('message', async (message) => {
-  if (message.text === '/start') {
-    await bot.sendMessage({
-      chat_id: message.chat.id,
-      text: 'welcome to riseonly',
-    });
-  }
+bot.command('start', async (message) => {
+  await bot.reply(message, 'Welcome to Riseonly');
 });
+
+bot.hears(/hello/i, (message) => bot.reply(message, 'Hi!'));
+bot.action(/^track:/, (query) => bot.answer(query, 'Loading track…'));
+bot.catch((error) => console.error('Bot handler failed', error));
 ```
 
 ## Bot API client
@@ -37,7 +36,8 @@ const api = new ApiClient(process.env.BOT_TOKEN, {
 });
 
 const me = await api.getMe();
-await api.sendMessage({ chat_id: me.id, text: 'hello' });
+console.log(`Connected as @${me.username}`);
+await api.sendMessage({ chat_id: 'chat-id', text: 'hello' });
 ```
 
 ## Webhooks
@@ -65,7 +65,44 @@ await bot.startWebhook({
 });
 ```
 
-### Express / Fastify adapter
+Webhook handlers return a retryable HTTP 500 when your application handler fails. Updates are acknowledged only after handlers finish successfully.
+
+## Configure from code
+
+Keep bot commands and delivery configuration in source control instead of repeating setup by hand:
+
+```js
+await bot.setup({
+  commands: [
+    { command: 'start', description: 'Start the bot' },
+    { command: 'help', description: 'Show help' },
+  ],
+  webhook: false,
+});
+
+await bot.launch();
+```
+
+Use `webhook: { url, secret_token }` to configure webhook delivery instead. `bot.stop()` gracefully stops polling and the built-in webhook server.
+
+## Media metadata
+
+Remote HTTPS media can include metadata used by Riseonly clients:
+
+```js
+await bot.sendAudio({
+  url: 'https://cdn.example.com/song.mp3',
+  file_name: 'Artist - Song.mp3',
+  mime_type: 'audio/mpeg',
+  thumbnail_url: 'https://cdn.example.com/cover.jpg',
+  duration: 180,
+}, {
+  chat_id: 'chat-id',
+  caption: 'Artist — Song',
+});
+```
+
+## Express / Fastify webhook adapter
 
 ```js
 import express from 'express';

package/dist/index.cjs

@@ -94,6 +94,22 @@ var RiseonlyTimeoutError = class extends RiseonlyNetworkError {
     this.name = "RiseonlyTimeoutError";
   }
 };
+var RiseonlyAbortError = class extends RiseonlyNetworkError {
+  constructor(message = "Request was aborted", cause) {
+    super(message, cause, 499);
+    this.name = "RiseonlyAbortError";
+  }
+};
+var RiseonlyResponseError = class extends RiseonlyNetworkError {
+  status;
+  body;
+  constructor(message, status, body) {
+    super(message, void 0, status);
+    this.name = "RiseonlyResponseError";
+    this.status = status;
+    this.body = body;
+  }
+};
 
 // src/client.ts
 var ApiClient = class {
@@ -108,8 +124,15 @@ var ApiClient = class {
     }
     this.token = token.trim();
     this.baseUrl = (options.baseUrl ?? DEFAULT_API_BASE).replace(/\/$/, "");
-    this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== "function") {
+      throw new Error("global fetch is unavailable; provide ClientOptions.fetch");
+    }
+    this.fetchImpl = options.fetch ? fetchImpl : fetchImpl.bind(globalThis);
     this.requestTimeoutMs = options.requestTimeoutMs ?? 6e4;
+    if (!Number.isFinite(this.requestTimeoutMs) || this.requestTimeoutMs <= 0) {
+      throw new Error("requestTimeoutMs must be a positive number");
+    }
     this.useCompatibleEndpoint = options.useCompatibleEndpoint ?? false;
   }
   /**
@@ -117,15 +140,21 @@ var ApiClient = class {
    */
   async getCapabilities(signal) {
     const url = `${this.baseUrl}${CANONICAL_API_PREFIX}/capabilities`;
-    const response = await this.fetchImpl(url, {
+    const { response, body } = await this.fetchJson(url, {
       method: "GET",
-      headers: { Accept: "application/json" },
-      signal
-    });
+      headers: { Accept: "application/json" }
+    }, { signal });
     if (!response.ok) {
-      throw new RiseonlyNetworkError(`capabilities request failed with status ${response.status}`);
+      throw new RiseonlyResponseError(
+        `capabilities request failed with status ${response.status}`,
+        response.status,
+        serializeResponseBody(body)
+      );
     }
-    return response.json();
+    if (!isRecord(body) || !Array.isArray(body.methods)) {
+      throw new RiseonlyResponseError("capabilities response is invalid", response.status);
+    }
+    return body;
   }
   /**
    * Calls a Bot API method and returns the typed result.
@@ -147,37 +176,36 @@ var ApiClient = class {
     if (options.requestId) {
       headers[IDEMPOTENCY_HEADER] = options.requestId;
     }
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), this.requestTimeoutMs);
-    const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
-    let response;
-    try {
-      response = await this.fetchImpl(url, {
+    const { response, body } = await this.fetchJson(
+      url,
+      {
         method: "POST",
         headers,
-        body: JSON.stringify(payload),
-        signal
-      });
-    } catch (error) {
-      if (error instanceof Error && error.name === "AbortError") {
-        throw new RiseonlyTimeoutError();
-      }
-      throw new RiseonlyNetworkError("network request failed", error);
-    } finally {
-      clearTimeout(timeout);
-    }
-    const body = await response.json();
-    if (!body.ok) {
+        body: JSON.stringify(payload)
+      },
+      options
+    );
+    if (isApiErrorResponse(body)) {
       throw RiseonlyError.fromApiResponse(body);
     }
+    if (!response.ok) {
+      throw new RiseonlyResponseError(
+        `Bot API request failed with status ${response.status}`,
+        response.status,
+        serializeResponseBody(body)
+      );
+    }
+    if (!isRecord(body) || body.ok !== true || !("result" in body)) {
+      throw new RiseonlyResponseError("Bot API response envelope is invalid", response.status);
+    }
     return body;
   }
   async getMe(options) {
     return this.callMethod("getMe", {}, options);
   }
   async sendMessage(options) {
-    const { requestId, ...payload } = options;
-    return this.callMethod("sendMessage", payload, { requestId });
+    const { request, payload } = splitRequestOptions(options);
+    return this.callMethod("sendMessage", payload, request);
   }
   async sendPhoto(photo, options) {
     return this.sendMedia("sendPhoto", "photo", photo, options);
@@ -198,72 +226,75 @@ var ApiClient = class {
     return this.sendMedia("sendAnimation", "animation", animation, options);
   }
   async editMessageText(options) {
-    const { requestId, ...payload } = options;
-    return this.callMethod("editMessageText", payload, { requestId });
+    const { request, payload } = splitRequestOptions(options);
+    return this.callMethod("editMessageText", payload, request);
   }
   async deleteMessage(options) {
-    const { requestId, ...payload } = options;
-    return this.callMethod("deleteMessage", payload, { requestId });
+    const { request, payload } = splitRequestOptions(options);
+    return this.callMethod("deleteMessage", payload, request);
   }
   async sendChatAction(options) {
-    const { requestId, ...payload } = options;
-    return this.callMethod("sendChatAction", payload, { requestId });
+    const { request, payload } = splitRequestOptions(options);
+    return this.callMethod("sendChatAction", payload, request);
   }
   async getUpdates(options = {}) {
-    const { requestId, ...payload } = options;
-    return this.callMethod("getUpdates", payload, { requestId });
+    const { request, payload } = splitRequestOptions(options);
+    const serverTimeoutMs = (options.timeout ?? 0) * 1e3 + 5e3;
+    request.timeoutMs ??= Math.max(this.requestTimeoutMs, serverTimeoutMs);
+    return this.callMethod("getUpdates", payload, request);
   }
   async setWebhook(options) {
-    const { requestId, ...payload } = options;
-    return this.callMethod("setWebhook", payload, { requestId });
+    const { request, payload } = splitRequestOptions(options);
+    return this.callMethod("setWebhook", payload, request);
   }
   async deleteWebhook(options = {}) {
-    const { requestId, ...payload } = options;
-    return this.callMethod("deleteWebhook", payload, { requestId });
+    const { request, payload } = splitRequestOptions(options);
+    return this.callMethod("deleteWebhook", payload, request);
   }
   async getWebhookInfo(options) {
     return this.callMethod("getWebhookInfo", {}, options);
   }
   async setMyCommands(options) {
-    const { requestId, ...payload } = options;
-    return this.callMethod("setMyCommands", payload, { requestId });
+    const { request, payload } = splitRequestOptions(options);
+    return this.callMethod("setMyCommands", payload, request);
   }
   async getMyCommands(options = {}) {
-    const { requestId, ...payload } = options;
-    return this.callMethod("getMyCommands", payload, { requestId });
+    const { request, payload } = splitRequestOptions(options);
+    return this.callMethod("getMyCommands", payload, request);
   }
   async deleteMyCommands(options = {}) {
-    const { requestId, ...payload } = options;
-    return this.callMethod("deleteMyCommands", payload, { requestId });
+    const { request, payload } = splitRequestOptions(options);
+    return this.callMethod("deleteMyCommands", payload, request);
   }
   async answerCallbackQuery(options) {
-    const { requestId, ...payload } = options;
-    return this.callMethod("answerCallbackQuery", payload, { requestId });
+    const { request, payload } = splitRequestOptions(options);
+    return this.callMethod("answerCallbackQuery", payload, request);
   }
   async getChat(options) {
-    const { requestId, ...payload } = options;
-    return this.callMethod("getChat", payload, { requestId });
+    const { request, payload } = splitRequestOptions(options);
+    return this.callMethod("getChat", payload, request);
   }
   async sendMedia(method, field, media, options) {
-    const { requestId, ...payload } = options;
+    const { request, payload } = splitRequestOptions(options);
     return this.callMethod(
       method,
       {
         ...payload,
         [field]: this.normalizeMedia(media)
       },
-      { requestId }
+      request
     );
   }
   normalizeMedia(media) {
     if (typeof media === "string") {
       return media;
     }
-    if (media.file_id) {
-      return media.file_id;
-    }
-    if (media.url) {
-      return media.url;
+    if (media.file_id || media.url) {
+      return Object.fromEntries(
+        Object.entries(media).filter(
+          (entry) => typeof entry[1] === "string" || typeof entry[1] === "number"
+        )
+      );
     }
     throw new Error("media requires file_id or url");
   }
@@ -273,9 +304,77 @@ var ApiClient = class {
     }
     return `${this.baseUrl}${CANONICAL_API_PREFIX}/${method}`;
   }
+  async fetchJson(url, init, options = {}) {
+    const controller = new AbortController();
+    let timedOut = false;
+    const timeoutMs = options.timeoutMs ?? this.requestTimeoutMs;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+      throw new Error("timeoutMs must be a positive number");
+    }
+    const abortFromCaller = () => controller.abort(options.signal?.reason);
+    if (options.signal?.aborted) {
+      throw new RiseonlyAbortError("Request was aborted", options.signal.reason);
+    }
+    options.signal?.addEventListener("abort", abortFromCaller, { once: true });
+    const timeout = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, timeoutMs);
+    let response;
+    try {
+      response = await this.fetchImpl(url, { ...init, signal: controller.signal });
+    } catch (error) {
+      if (controller.signal.aborted) {
+        if (timedOut) {
+          throw new RiseonlyTimeoutError();
+        }
+        throw new RiseonlyAbortError("Request was aborted", error);
+      }
+      throw new RiseonlyNetworkError("network request failed", error);
+    } finally {
+      clearTimeout(timeout);
+      options.signal?.removeEventListener("abort", abortFromCaller);
+    }
+    let text;
+    try {
+      text = await response.text();
+    } catch (error) {
+      throw new RiseonlyNetworkError("unable to read response body", error, response.status);
+    }
+    if (!text) {
+      throw new RiseonlyResponseError("Bot API returned an empty response", response.status);
+    }
+    try {
+      return { response, body: JSON.parse(text) };
+    } catch {
+      throw new RiseonlyResponseError(
+        "Bot API returned a non-JSON response",
+        response.status,
+        text.slice(0, 4096)
+      );
+    }
+  }
 };
-
-// src/webhook.ts
+function splitRequestOptions(options) {
+  const { requestId, signal, timeoutMs, ...payload } = options;
+  return {
+    request: { requestId, signal, timeoutMs },
+    payload
+  };
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isApiErrorResponse(value) {
+  return isRecord(value) && value.ok === false && typeof value.error_code === "number" && typeof value.description === "string";
+}
+function serializeResponseBody(body) {
+  try {
+    return JSON.stringify(body).slice(0, 4096);
+  } catch {
+    return void 0;
+  }
+}
 function parseWebhookUpdate(body) {
   if (!body || typeof body !== "object") {
     throw new Error("webhook body must be an object");
@@ -290,28 +389,49 @@ function verifyWebhookSecret(headers, secretToken) {
   if (!secretToken) {
     return true;
   }
-  const headerValue = headers[WEBHOOK_SECRET_HEADER] ?? headers[WEBHOOK_SECRET_HEADER.toLowerCase()];
+  const headerEntry = Object.entries(headers).find(
+    ([name]) => name.toLowerCase() === WEBHOOK_SECRET_HEADER
+  );
+  const headerValue = headerEntry?.[1];
   if (!headerValue) {
     return false;
   }
   const received = Array.isArray(headerValue) ? headerValue[0] : headerValue;
-  return received === secretToken;
+  if (typeof received !== "string") {
+    return false;
+  }
+  const actual = Buffer.from(received);
+  const expected = Buffer.from(secretToken);
+  return actual.length === expected.length && crypto$1.timingSafeEqual(actual, expected);
 }
 function createWebhookHandler(options) {
   return async (request) => {
+    if (!verifyWebhookSecret(request.headers, options.secretToken)) {
+      return { status: 401, body: { ok: false, description: "invalid webhook secret" } };
+    }
+    let update;
+    try {
+      update = parseWebhookUpdate(request.body);
+    } catch (error) {
+      await notifyWebhookError(options.onError, error);
+      return { status: 400, body: { ok: false, description: "invalid webhook payload" } };
+    }
     try {
-      if (!verifyWebhookSecret(request.headers, options.secretToken)) {
-        return { status: 401, body: { ok: false, description: "invalid webhook secret" } };
-      }
-      const update = parseWebhookUpdate(request.body);
       await options.onUpdate(update);
       return { status: 200, body: { ok: true } };
     } catch (error) {
-      await options.onError?.(error);
-      return { status: 400, body: { ok: false, description: "invalid webhook payload" } };
+      await notifyWebhookError(options.onError, error);
+      return { status: 500, body: { ok: false, description: "webhook handler failed" } };
     }
   };
 }
+async function notifyWebhookError(handler, error) {
+  try {
+    await handler?.(error);
+  } catch {
+    return;
+  }
+}
 
 // src/bot.ts
 var RiseonlyBot = class extends ApiClient {
@@ -327,6 +447,7 @@ var RiseonlyBot = class extends ApiClient {
   webhookOptions;
   polling = false;
   pollingAbort;
+  pollingTask;
   offset = 0;
   webhookServer;
   constructor(token, options = {}) {
@@ -368,6 +489,67 @@ var RiseonlyBot = class extends ApiClient {
     });
     return this.on(event, wrapper);
   }
+  command(commands, handler) {
+    const accepted = new Set(
+      (Array.isArray(commands) ? commands : [commands]).map((command) => command.replace(/^\//, "").toLowerCase()).filter(Boolean)
+    );
+    return this.on("message", async (message, update) => {
+      const text = message.text?.trim();
+      if (!text?.startsWith("/")) {
+        return;
+      }
+      const token = text.split(/\s+/, 1)[0].slice(1).split("@", 1)[0].toLowerCase();
+      if (accepted.has(token)) {
+        await handler(message, update);
+      }
+    });
+  }
+  hears(trigger, handler) {
+    return this.on("message", async (message, update) => {
+      if (message.text === void 0) {
+        return;
+      }
+      if (typeof trigger === "string") {
+        if (message.text === trigger) {
+          await handler(message, null, update);
+        }
+        return;
+      }
+      trigger.lastIndex = 0;
+      const match = trigger.exec(message.text);
+      if (match) {
+        await handler(message, match, update);
+      }
+    });
+  }
+  action(trigger, handler) {
+    return this.on("callback_query", async (query, update) => {
+      if (query.data === void 0) {
+        return;
+      }
+      const matches = typeof trigger === "string" ? query.data === trigger : testPattern(trigger, query.data);
+      if (matches) {
+        await handler(query, update);
+      }
+    });
+  }
+  catch(handler) {
+    return this.on("error", handler);
+  }
+  async setup(options) {
+    if (options.commands) {
+      await this.setMyCommands({
+        commands: options.commands,
+        scope: options.commandScope,
+        language_code: options.languageCode
+      });
+    }
+    if (options.webhook === false) {
+      await this.deleteWebhook();
+    } else if (options.webhook) {
+      await this.setWebhook(options.webhook);
+    }
+  }
   /**
    * Starts long polling for bot updates.
    */
@@ -378,7 +560,7 @@ var RiseonlyBot = class extends ApiClient {
     this.polling = true;
     this.pollingOptions = { ...this.pollingOptions, ...options, autoStart: true };
     this.pollingAbort = new AbortController();
-    void this.pollLoop();
+    this.pollingTask = this.pollLoop();
   }
   /**
    * Stops long polling.
@@ -386,7 +568,15 @@ var RiseonlyBot = class extends ApiClient {
   async stopPolling() {
     this.polling = false;
     this.pollingAbort?.abort();
+    await this.pollingTask;
     this.pollingAbort = void 0;
+    this.pollingTask = void 0;
+  }
+  async launch(options = {}) {
+    await this.startPolling(options);
+  }
+  async stop() {
+    await Promise.all([this.stopPolling(), this.stopWebhook()]);
   }
   /**
    * Starts a built-in HTTP server that receives webhook updates.
@@ -397,6 +587,12 @@ var RiseonlyBot = class extends ApiClient {
     const path = config.path ?? "/";
     const host = config.host ?? "0.0.0.0";
     const port = config.port ?? 3e3;
+    if (!path.startsWith("/")) {
+      throw new Error("webhook path must start with /");
+    }
+    if (config.maxBodyBytes !== void 0 && config.maxBodyBytes <= 0) {
+      throw new Error("maxBodyBytes must be positive");
+    }
     const handler = createWebhookHandler({
       secretToken: config.secretToken,
       onUpdate: (update) => this.processUpdate(update),
@@ -411,15 +607,16 @@ var RiseonlyBot = class extends ApiClient {
         return;
       }
       try {
-        const body = await readJsonBody(req);
+        const body = await readJsonBody(req, config.maxBodyBytes);
         const result = await handler({
           headers: normalizeHeaders(req.headers),
           body
         });
         respond(res, result.status, result.body);
       } catch (error) {
-        await this.emit("error", error);
-        respond(res, 500, { ok: false });
+        await this.emitError(error);
+        const status = error instanceof WebhookPayloadTooLargeError ? 413 : 500;
+        respond(res, status, { ok: false });
       }
     });
     await new Promise((resolve, reject) => {
@@ -491,8 +688,8 @@ var RiseonlyBot = class extends ApiClient {
           if (update.update_id < this.offset) {
             continue;
           }
-          this.offset = Math.max(this.offset, update.update_id + 1);
           await this.processUpdate(update);
+          this.offset = Math.max(this.offset, update.update_id + 1);
           processed += 1;
         }
         if (processed === 0) {
@@ -502,7 +699,10 @@ var RiseonlyBot = class extends ApiClient {
         if (!this.polling || isAbortError(error)) {
           return;
         }
-        await this.emit("polling_error", error);
+        try {
+          await this.emit("polling_error", error);
+        } catch {
+        }
         if (error instanceof RiseonlyError && error.retryAfter) {
           await sleep(error.retryAfter * 1e3);
         } else {
@@ -512,11 +712,27 @@ var RiseonlyBot = class extends ApiClient {
     }
   }
   async emit(event, ...args) {
+    let firstError;
     for (const listener of [...this.listeners[event]]) {
       try {
         await listener(...args);
       } catch (error) {
-        await this.emit("error", error);
+        firstError ??= error;
+        if (event !== "error") {
+          await this.emitError(error);
+        }
+      }
+    }
+    if (firstError !== void 0) {
+      throw firstError;
+    }
+  }
+  async emitError(error) {
+    for (const listener of [...this.listeners.error]) {
+      try {
+        await listener(error);
+      } catch {
+        continue;
       }
     }
   }
@@ -540,7 +756,11 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 function isAbortError(error) {
-  return error instanceof Error && error.name === "AbortError";
+  return error instanceof Error && (error.name === "AbortError" || error.name === "RiseonlyAbortError");
+}
+function testPattern(pattern, value) {
+  pattern.lastIndex = 0;
+  return pattern.test(value);
 }
 function normalizeHeaders(headers) {
   const normalized = {};
@@ -549,10 +769,19 @@ function normalizeHeaders(headers) {
   }
   return normalized;
 }
-async function readJsonBody(req) {
+var WebhookPayloadTooLargeError = class extends Error {
+};
+async function readJsonBody(req, maxBodyBytes = 1024 * 1024) {
   const chunks = [];
+  let received = 0;
   for await (const chunk of req) {
-    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    received += buffer.length;
+    if (received > maxBodyBytes) {
+      req.resume();
+      throw new WebhookPayloadTooLargeError("webhook payload is too large");
+    }
+    chunks.push(buffer);
   }
   if (chunks.length === 0) {
     return {};
@@ -595,8 +824,12 @@ function verifyInitData(botToken, encoded) {
   if (left.length !== right.length || !crypto$1.timingSafeEqual(left, right)) {
     throw new Error("init data signature is invalid");
   }
-  const expiresAt = fields.expires_at ? Number(fields.expires_at) : void 0;
-  if (expiresAt !== void 0 && Number.isFinite(expiresAt) && expiresAt < Date.now()) {
+  const authDate = Number(fields.auth_date);
+  const expiresAt = Number(fields.expires_at);
+  if (!Number.isSafeInteger(authDate) || !Number.isSafeInteger(expiresAt) || expiresAt <= authDate) {
+    throw new Error("init data timestamps are invalid");
+  }
+  if (expiresAt < Date.now()) {
     throw new Error("init data has expired");
   }
   return fields;
@@ -619,9 +852,11 @@ exports.CHAT_ACTIONS = CHAT_ACTIONS;
 exports.COMMAND_SCOPES = COMMAND_SCOPES;
 exports.DEFAULT_API_BASE = DEFAULT_API_BASE;
 exports.IDEMPOTENCY_HEADER = IDEMPOTENCY_HEADER;
+exports.RiseonlyAbortError = RiseonlyAbortError;
 exports.RiseonlyBot = RiseonlyBot;
 exports.RiseonlyError = RiseonlyError;
 exports.RiseonlyNetworkError = RiseonlyNetworkError;
+exports.RiseonlyResponseError = RiseonlyResponseError;
 exports.RiseonlyTimeoutError = RiseonlyTimeoutError;
 exports.SUPPORTED_METHODS = SUPPORTED_METHODS;
 exports.UPDATE_TYPES = UPDATE_TYPES;