@yaebal/again 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 neverlane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,13 @@
+# @yaebal/again
+
+max retries after the first attempt. defaults to 3.
+
+## install
+
+```sh
+pnpm add @yaebal/again
+```
+
+---
+
+part of [**yaebal**](https://github.com/neverlane/yaebal) — a type-safe, runtime-agnostic Telegram Bot API framework. MIT.

package/lib/index.d.ts

@@ -0,0 +1,17 @@
+import { type Api, type ErrorAction } from "@yaebal/core";
+export interface AutoRetryOptions {
+    /** max retries after the first attempt. defaults to 3. */
+    maxRetries?: number;
+    /** cap on a single wait, in ms. defaults to 30_000. */
+    maxDelayMs?: number;
+    /** also retry transient 5xx server errors. defaults to true. */
+    retryOnInternal?: boolean;
+}
+/**
+ * decide whether a failed call should be retried, and after how long.
+ * pure (no I/O) — exported so the policy is unit-testable on its own.
+ */
+export declare function decideRetry(error: unknown, attempt: number, options?: AutoRetryOptions): ErrorAction | undefined;
+/** install auto-retry on a bot's API: `autoRetry(bot.api)`. */
+export declare function autoRetry(api: Api, options?: AutoRetryOptions): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,GAAG,EAAE,KAAK,WAAW,EAAiB,MAAM,cAAc,CAAC;AAEzE,MAAM,WAAW,gBAAgB;IAChC,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,eAAe,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAC1B,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,gBAAqB,GAC5B,WAAW,GAAG,SAAS,CAsBzB;AAED,+DAA+D;AAC/D,wBAAgB,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,GAAE,gBAAqB,GAAG,IAAI,CAExE"}

package/lib/index.js

@@ -0,0 +1,34 @@
+import { TelegramError } from "@yaebal/core";
+/**
+ * decide whether a failed call should be retried, and after how long.
+ * pure (no I/O) — exported so the policy is unit-testable on its own.
+ */
+export function decideRetry(error, attempt, options = {}) {
+    const maxRetries = options.maxRetries ?? 3;
+    const maxDelayMs = options.maxDelayMs ?? 30_000;
+    const retryOnInternal = options.retryOnInternal ?? true;
+    if (attempt > maxRetries)
+        return undefined;
+    if (!(error instanceof TelegramError))
+        return undefined;
+    // 429: respect telegram's "retry after N", else exponential backoff.
+    if (error.code === 429) {
+        const retryAfter = parseRetryAfter(error.message);
+        const seconds = retryAfter ?? 2 ** attempt;
+        return { retry: true, delayMs: Math.min(seconds * 1000, maxDelayMs) };
+    }
+    // 5xx: transient server-side failure.
+    if (retryOnInternal && error.code >= 500) {
+        return { retry: true, delayMs: Math.min(2 ** attempt * 1000, maxDelayMs) };
+    }
+    return undefined;
+}
+/** install auto-retry on a bot's API: `autoRetry(bot.api)`. */
+export function autoRetry(api, options = {}) {
+    api.onError((_method, error, attempt) => decideRetry(error, attempt, options));
+}
+function parseRetryAfter(message) {
+    const m = message.match(/retry after (\d+)/i);
+    return m ? Number(m[1]) : undefined;
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8B,aAAa,EAAE,MAAM,cAAc,CAAC;AAWzE;;;GAGG;AACH,MAAM,UAAU,WAAW,CAC1B,KAAc,EACd,OAAe,EACf,UAA4B,EAAE;IAE9B,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,CAAC,CAAC;IAC3C,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,MAAM,CAAC;IAChD,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,IAAI,CAAC;IAExD,IAAI,OAAO,GAAG,UAAU;QAAE,OAAO,SAAS,CAAC;IAC3C,IAAI,CAAC,CAAC,KAAK,YAAY,aAAa,CAAC;QAAE,OAAO,SAAS,CAAC;IAExD,qEAAqE;IACrE,IAAI,KAAK,CAAC,IAAI,KAAK,GAAG,EAAE,CAAC;QACxB,MAAM,UAAU,GAAG,eAAe,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAClD,MAAM,OAAO,GAAG,UAAU,IAAI,CAAC,IAAI,OAAO,CAAC;QAE3C,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,OAAO,GAAG,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC;IACvE,CAAC;IAED,sCAAsC;IACtC,IAAI,eAAe,IAAI,KAAK,CAAC,IAAI,IAAI,GAAG,EAAE,CAAC;QAC1C,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,OAAO,GAAG,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC;IAC5E,CAAC;IAED,OAAO,SAAS,CAAC;AAClB,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,SAAS,CAAC,GAAQ,EAAE,UAA4B,EAAE;IACjE,GAAG,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;AAChF,CAAC;AAED,SAAS,eAAe,CAAC,OAAe;IACvC,MAAM,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;IAE9C,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACrC,CAAC"}

package/lib/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

package/lib/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":""}

package/lib/index.test.js

@@ -0,0 +1,29 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { TelegramError } from "@yaebal/core";
+import { decideRetry } from "./index.js";
+test("429 with retry_after waits exactly that long", () => {
+    assert.deepEqual(decideRetry(new TelegramError("sendMessage", 429, "Too Many Requests: retry after 7"), 1), { retry: true, delayMs: 7000 });
+});
+test("5xx retries with exponential backoff", () => {
+    assert.deepEqual(decideRetry(new TelegramError("sendMessage", 502, "Bad Gateway"), 1), {
+        retry: true,
+        delayMs: 2000,
+    });
+});
+test("stops once attempts exceed maxRetries", () => {
+    assert.equal(decideRetry(new TelegramError("sendMessage", 429, "retry after 1"), 4), undefined);
+});
+test("4xx client errors are not retried", () => {
+    assert.equal(decideRetry(new TelegramError("sendMessage", 400, "Bad Request"), 1), undefined);
+});
+test("non-Telegram errors are not retried", () => {
+    assert.equal(decideRetry(new Error("socket hang up"), 1), undefined);
+});
+test("maxDelayMs caps the wait", () => {
+    assert.deepEqual(decideRetry(new TelegramError("x", 429, "retry after 999"), 1, { maxDelayMs: 5000 }), { retry: true, delayMs: 5000 });
+});
+test("retryOnInternal:false skips 5xx", () => {
+    assert.equal(decideRetry(new TelegramError("x", 503, "Service Unavailable"), 1, { retryOnInternal: false }), undefined);
+});
+//# sourceMappingURL=index.test.js.map

package/lib/index.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.js","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,IAAI,CAAC,8CAA8C,EAAE,GAAG,EAAE;IACzD,MAAM,CAAC,SAAS,CACf,WAAW,CAAC,IAAI,aAAa,CAAC,aAAa,EAAE,GAAG,EAAE,kCAAkC,CAAC,EAAE,CAAC,CAAC,EACzF,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAC9B,CAAC;AACH,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,sCAAsC,EAAE,GAAG,EAAE;IACjD,MAAM,CAAC,SAAS,CAAC,WAAW,CAAC,IAAI,aAAa,CAAC,aAAa,EAAE,GAAG,EAAE,aAAa,CAAC,EAAE,CAAC,CAAC,EAAE;QACtF,KAAK,EAAE,IAAI;QACX,OAAO,EAAE,IAAI;KACb,CAAC,CAAC;AACJ,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,uCAAuC,EAAE,GAAG,EAAE;IAClD,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,aAAa,CAAC,aAAa,EAAE,GAAG,EAAE,eAAe,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;AACjG,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,mCAAmC,EAAE,GAAG,EAAE;IAC9C,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,aAAa,CAAC,aAAa,EAAE,GAAG,EAAE,aAAa,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;AAC/F,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,qCAAqC,EAAE,GAAG,EAAE;IAChD,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,KAAK,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;AACtE,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,0BAA0B,EAAE,GAAG,EAAE;IACrC,MAAM,CAAC,SAAS,CACf,WAAW,CAAC,IAAI,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,iBAAiB,CAAC,EAAE,CAAC,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,EACpF,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAC9B,CAAC;AACH,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,iCAAiC,EAAE,GAAG,EAAE;IAC5C,MAAM,CAAC,KAAK,CACX,WAAW,CAAC,IAAI,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,qBAAqB,CAAC,EAAE,CAAC,EAAE,EAAE,eAAe,EAAE,KAAK,EAAE,CAAC,EAC9F,SAAS,CACT,CAAC;AACH,CAAC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@yaebal/again",
+  "version": "0.0.1",
+  "description": "yaebal auto-retry plugin — retries on 429/flood-wait and transient 5xx.",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "dependencies": {
+    "@yaebal/core": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "latest"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "telegram",
+    "telegram-bot",
+    "yaebal",
+    "retry",
+    "flood-wait"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neverlane/yaebal",
+    "directory": "packages/again"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test lib"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,44 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { TelegramError } from "@yaebal/core";
+import { decideRetry } from "./index.js";
+
+test("429 with retry_after waits exactly that long", () => {
+	assert.deepEqual(
+		decideRetry(new TelegramError("sendMessage", 429, "Too Many Requests: retry after 7"), 1),
+		{ retry: true, delayMs: 7000 },
+	);
+});
+
+test("5xx retries with exponential backoff", () => {
+	assert.deepEqual(decideRetry(new TelegramError("sendMessage", 502, "Bad Gateway"), 1), {
+		retry: true,
+		delayMs: 2000,
+	});
+});
+
+test("stops once attempts exceed maxRetries", () => {
+	assert.equal(decideRetry(new TelegramError("sendMessage", 429, "retry after 1"), 4), undefined);
+});
+
+test("4xx client errors are not retried", () => {
+	assert.equal(decideRetry(new TelegramError("sendMessage", 400, "Bad Request"), 1), undefined);
+});
+
+test("non-Telegram errors are not retried", () => {
+	assert.equal(decideRetry(new Error("socket hang up"), 1), undefined);
+});
+
+test("maxDelayMs caps the wait", () => {
+	assert.deepEqual(
+		decideRetry(new TelegramError("x", 429, "retry after 999"), 1, { maxDelayMs: 5000 }),
+		{ retry: true, delayMs: 5000 },
+	);
+});
+
+test("retryOnInternal:false skips 5xx", () => {
+	assert.equal(
+		decideRetry(new TelegramError("x", 503, "Service Unavailable"), 1, { retryOnInternal: false }),
+		undefined,
+	);
+});

package/src/index.ts

@@ -0,0 +1,53 @@
+import { type Api, type ErrorAction, TelegramError } from "@yaebal/core";
+
+export interface AutoRetryOptions {
+	/** max retries after the first attempt. defaults to 3. */
+	maxRetries?: number;
+	/** cap on a single wait, in ms. defaults to 30_000. */
+	maxDelayMs?: number;
+	/** also retry transient 5xx server errors. defaults to true. */
+	retryOnInternal?: boolean;
+}
+
+/**
+ * decide whether a failed call should be retried, and after how long.
+ * pure (no I/O) — exported so the policy is unit-testable on its own.
+ */
+export function decideRetry(
+	error: unknown,
+	attempt: number,
+	options: AutoRetryOptions = {},
+): ErrorAction | undefined {
+	const maxRetries = options.maxRetries ?? 3;
+	const maxDelayMs = options.maxDelayMs ?? 30_000;
+	const retryOnInternal = options.retryOnInternal ?? true;
+
+	if (attempt > maxRetries) return undefined;
+	if (!(error instanceof TelegramError)) return undefined;
+
+	// 429: respect telegram's "retry after N", else exponential backoff.
+	if (error.code === 429) {
+		const retryAfter = parseRetryAfter(error.message);
+		const seconds = retryAfter ?? 2 ** attempt;
+
+		return { retry: true, delayMs: Math.min(seconds * 1000, maxDelayMs) };
+	}
+
+	// 5xx: transient server-side failure.
+	if (retryOnInternal && error.code >= 500) {
+		return { retry: true, delayMs: Math.min(2 ** attempt * 1000, maxDelayMs) };
+	}
+	
+	return undefined;
+}
+
+/** install auto-retry on a bot's API: `autoRetry(bot.api)`. */
+export function autoRetry(api: Api, options: AutoRetryOptions = {}): void {
+	api.onError((_method, error, attempt) => decideRetry(error, attempt, options));
+}
+
+function parseRetryAfter(message: string): number | undefined {
+	const m = message.match(/retry after (\d+)/i);
+	
+	return m ? Number(m[1]) : undefined;
+}