@thediscordlist/discord.js 0.1.1 → 0.2.0

package/README.md

@@ -30,7 +30,7 @@ It starts three publishers:
 | Publisher | What it sends | Cadence |
 | --- | --- | --- |
 | Stats | `server_count`, `shard_count` | 5s after ready, then every 5 min, debounced on guild join/leave |
-| Heartbeat | per-shard status, latency and guild counts | every ~30s, plus immediately on any shard transition |
+| Heartbeat | per-shard status, latency and guild counts | every ~30s, plus soon after any shard transition |
 | Commands | your registered slash commands | once, ~10s after ready |
 
 Your **stats token** is on the listing's manage page, under the API tab. It is
@@ -38,7 +38,28 @@ scoped to one listing, so it is the only credential this package needs.
 
 `autopost` is safe to call before or after `login()`. With a missing token it
 warns once and returns an inert object — a forgotten environment variable never
-takes down a deploy.
+takes down a deploy. A token pasted with surrounding whitespace or a leading
+`Bearer ` works as is.
+
+### Defaults
+
+- **Stats:** checked every 300s, and 20s after the last guild join or leave.
+  Never two posts within 60s. An unchanged count is skipped until 30 minutes
+  have passed.
+- **Heartbeat:** every 30s plus 0–5s of jitter, retuned from each response to a
+  third of the server's grace window and kept within 15–60s. A shard
+  transition beats out of band, at least 10s after the previous beat; it never
+  moves the regular schedule.
+- **Commands:** once, 10s after ready.
+- **A `403`** (the endpoint needs a higher plan) pauses that publisher for 30
+  minutes, then it tries again.
+- **Requests** time out after 10s and get three attempts, backing off
+  1s · 2ⁿ (capped at 30s, jittered to 50–100%) and never past the publisher's
+  next run. Only network errors, `408`, `425`, `429` and `5xx` are retried. A
+  `429` waits out `Retry-After` or `X-RateLimit-Reset` — 60s when neither is
+  sent, never more than an hour. Every wait runs on a monotonic clock.
+- **Webhooks:** a signature more than 300s from now is rejected. The handlers
+  cap the body at 1 MiB and give `onEvent` 8s before answering `202`.
 
 ## Sharding
 
@@ -142,7 +163,8 @@ app.use(express.json()); // everything else, after the webhook route
 ```
 
 The handler reads the raw stream itself, so mount it **before** any body
-parser. If your framework forces one in front, it must hand over raw bytes:
+parser. If your framework forces one in front, it must hand over raw bytes; a
+`Buffer` in `req.body` is verified as is:
 
 ```ts
 app.post('/webhooks/tdl', express.raw({ type: 'application/json' }), handler);
@@ -153,6 +175,9 @@ and silently skips JSON, leaving `req.body` undefined. The handler detects an
 already-parsed body and reports a `BODY_CONSUMED` error rather than failing
 verification for reasons nobody can see.
 
+Both handlers, and `verifyWebhook`, throw a `TypeError` for an empty secret
+rather than checking signatures against an empty key.
+
 ### Hono, Next App Router, Workers, Bun, Deno
 
 ```ts
@@ -202,6 +227,7 @@ signature covers bytes, not meaning.
 ```ts
 type TdlWebhookEventName =
   | 'listing.bumped'
+  | 'listing.bump_ready' // the bump cooldown lifted; data.ready_at
   | 'listing.upvoted'
   | 'server.joined'   // server listings only — a bot listing never receives it
   | 'bot.added'
@@ -227,9 +253,9 @@ heartbeat's internal stats forward.
   and **a 2xx to that probe re-enables it**.
 - **Register an exact `https://` URL with no redirect.** The sender treats 3xx
   as a failure, so an `http → https` or trailing-slash redirect burns all five
-  retries and counts toward the disable streak.
+  attempts and counts toward the disable streak.
 - **Deduplicate on `ctx.delivery`.** It equals `X-TDL-Delivery` and is stable
-  across all five retries of one delivery:
+  across all five attempts of one delivery:
 
   ```ts
   if (await redis.set(ctx.delivery, 1, 'EX', 86400, 'NX') === null) return;
@@ -249,11 +275,11 @@ heartbeat's internal stats forward.
 - **Heartbeats need Gold or higher.** On a `403` the heartbeat publisher
   suspends and reprobes every 30 minutes rather than disabling: the tier is
   derived per request, so a bot can gain it mid-run.
-- **Rate limits are shared.** The API counts stats, heartbeats and commands
-  against one budget keyed by client IP. This package keeps one client-side
-  budget to match, and drops stats before heartbeats when it is scarce — a
-  stale number beats a false "down" on your status page. On shared hosting,
-  other bots behind the same egress IP count against you.
+- **Rate limits are shared.** The API counts stats and commands against one
+  budget per bot (60/min; heartbeats have their own 120/min). A `429` suspends
+  stats and commands together for `Retry-After` (or until `X-RateLimit-Reset`,
+  at most an hour); heartbeats bypass it — a stale number beats a false "down"
+  on your status page.
 - **`404` never means "bad token".** It means the id is unknown or belongs to a
   server listing. The distinction is deliberate, so probing cannot enumerate.
 - **Guild counts can drift upward permanently.** If Discord re-IDENTIFYs a

package/dist/index.cjs

@@ -2,11 +2,16 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let node_events = require("node:events");
 let discord_js = require("discord.js");
 //#region package.json
-var version$1 = "0.1.1";
+var version$1 = "0.2.0";
+/** However far out Retry-After or X-RateLimit-Reset points, never go quiet for longer. */
+const MAX_RATE_LIMIT_WAIT_MS = 36e5;
+const MAX_ATTEMPTS = 3;
 /**
-* Drops `undefined` keys recursively. An explicit `null` survives, and must:
-* the API's `prepareForValidation` only defaults keys that are *absent*, and
-* none of its rules are `nullable`, so a serialised `undefined` is a 422.
+* Drops `undefined` keys recursively, so an unset value arrives absent rather
+* than `null`. The API's `prepareForValidation` only defaults keys that are
+* *absent*, and `cluster`, `cluster_count` and `shards` are not `nullable`, so
+* a `null` there is a 422. An explicit `null` survives: where a rule is
+* nullable it is a deliberate "unknown".
 */
 function stripUndefined(value) {
 	if (Array.isArray(value)) return value.map((item) => stripUndefined(item));
@@ -15,6 +20,9 @@ function stripUndefined(value) {
 	for (const [key, item] of Object.entries(value)) if (item !== void 0) out[key] = stripUndefined(item);
 	return out;
 }
+function isRetryable(outcome) {
+	return outcome.kind === "transient" || outcome.kind === "throttled";
+}
 /** Full jitter in the upper half, capped at 30s. */
 function backoffMs(attempt, random = Math.random) {
 	return Math.round(Math.min(1e3 * 2 ** attempt, 3e4) * (.5 + random() * .5));
@@ -41,10 +49,6 @@ function classify(status, body, retryAfterHeader) {
 		kind: "config",
 		status
 	};
-	if (status === 400 || status === 422) return {
-		kind: "payload",
-		status
-	};
 	if (status === 429) {
 		const seconds = Number(retryAfterHeader);
 		return {
@@ -53,22 +57,32 @@ function classify(status, body, retryAfterHeader) {
 			retryAfterMs: Number.isFinite(seconds) && seconds > 0 ? seconds * 1e3 : 6e4
 		};
 	}
+	if (status >= 400 && status < 500 && status !== 408 && status !== 425) return {
+		kind: "payload",
+		status
+	};
 	return {
 		kind: "transient",
 		status,
 		error: /* @__PURE__ */ new Error(`TheDiscordList responded ${status}.`)
 	};
 }
+function sleep(ms) {
+	return new Promise((resolve) => {
+		setTimeout(resolve, ms).unref?.();
+	});
+}
 function createApiClient(options) {
+	const baseUrl = options.baseUrl.replace(/\/+$/, "");
 	let suspendedUntil = 0;
-	return { async post(path, body, priority) {
-		if (priority !== "heartbeat" && Date.now() < suspendedUntil) return {
+	async function once(path, body, ignoreLimit) {
+		if (!ignoreLimit && performance.now() < suspendedUntil) return {
 			kind: "dropped",
 			status: null
 		};
 		let response;
 		try {
-			response = await fetch(`${options.baseUrl}${path}`, {
+			response = await fetch(`${baseUrl}${path}`, {
 				method: "POST",
 				headers: {
 					authorization: `Bearer ${options.token}`,
@@ -104,8 +118,22 @@ function createApiClient(options) {
 		const outcome = classify(response.status, parsed, response.headers.get("retry-after"));
 		if (outcome.kind === "throttled") {
 			const reset = Number(response.headers.get("x-ratelimit-reset"));
-			const untilReset = Number.isFinite(reset) && reset > 0 ? reset * 1e3 : 0;
-			suspendedUntil = Math.max(Date.now() + outcome.retryAfterMs, untilReset) + Math.round(Math.random() * 2e3);
+			const untilReset = Number.isFinite(reset) && reset > 0 ? reset * 1e3 - Date.now() : 0;
+			suspendedUntil = performance.now() + Math.min(Math.max(outcome.retryAfterMs, untilReset), MAX_RATE_LIMIT_WAIT_MS) + Math.round(Math.random() * 2e3);
+		}
+		return outcome;
+	}
+	return { async post(path, body, priority, nextTickInMs) {
+		let outcome = {
+			kind: "dropped",
+			status: null
+		};
+		for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+			outcome = await once(path, body, priority === "heartbeat" || outcome.kind === "throttled");
+			if (!isRetryable(outcome) || attempt === 2) break;
+			const delay = outcome.kind === "throttled" ? suspendedUntil - performance.now() : backoffMs(attempt);
+			if (nextTickInMs !== void 0 && delay >= nextTickInMs) break;
+			await sleep(delay);
 		}
 		return outcome;
 	} };
@@ -245,16 +273,24 @@ async function measureServerCount(client, topology, getServerCount) {
 	}
 	return total;
 }
+//#endregion
+//#region src/publishers.ts
+const STATS_INTERVAL_MS = 3e5;
+const STATS_DEBOUNCE_MS = 2e4;
+const STATS_MIN_GAP_MS = 6e4;
 const STATS_FIRST_POST_DELAY_MS = 5e3;
 const STATS_REMEASURE_MS = 6e4;
+const HEARTBEAT_DEFAULT_INTERVAL_MS = 3e4;
 const HEARTBEAT_MIN_INTERVAL_MS = 15e3;
 const HEARTBEAT_MAX_INTERVAL_MS = 6e4;
 const HEARTBEAT_JITTER_MS = 5e3;
+/** An out-of-band beat never follows the previous beat more closely than this. */
+const HEARTBEAT_OUT_OF_BAND_GAP_MS = 1e4;
+const BEAT_NOW_DELAY_MS = 1e3;
 /** Offset from the stats post: the two share one server-side rate budget. */
 const COMMANDS_DELAY_MS = 1e4;
 /** The Gold tier is derived per request from Stripe, so it can flip mid-run. */
 const PLAN_REPROBE_MS = 18e5;
-const MAX_ATTEMPTS = 3;
 function publisherError(message, type, status, retryable) {
 	return Object.assign(new Error(message), {
 		type,
@@ -262,11 +298,6 @@ function publisherError(message, type, status, retryable) {
 		retryable
 	});
 }
-function sleep(ms) {
-	return new Promise((resolve) => {
-		setTimeout(resolve, ms).unref?.();
-	});
-}
 var Publisher = class {
 	deps;
 	timer;
@@ -314,27 +345,9 @@ var Publisher = class {
 		this.reported.add(status);
 		this.deps.emit.error(publisherError(message, this.kind, status, retryable));
 	}
-	/**
-	* Sends one request, retrying only transient failures.
-	*
-	* `nextTickInMs` is the time until this publisher's next scheduled run. If a
-	* backoff would outlast it, the attempt is dropped: the next tick carries
-	* fresher data, and a failed request still burns rate-limit budget.
-	*/
+	/** `nextTickInMs` is the time until this publisher's next scheduled run; no retry outlasts it. */
 	async send(path, body, priority, nextTickInMs) {
-		let outcome = {
-			kind: "dropped",
-			status: null
-		};
-		for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
-			outcome = await this.deps.api.post(path, body, priority);
-			if (outcome.kind !== "transient") break;
-			const delay = backoffMs(attempt);
-			if (attempt === 2) break;
-			if (nextTickInMs !== void 0 && delay >= nextTickInMs) break;
-			await sleep(delay);
-		}
-		return this.react(outcome);
+		return this.react(await this.deps.api.post(path, body, priority, nextTickInMs));
 	}
 	react(outcome) {
 		switch (outcome.kind) {
@@ -366,7 +379,7 @@ var Publisher = class {
 					status: 401
 				};
 			case "plan":
-				this.suspendedUntil = Date.now() + PLAN_REPROBE_MS;
+				this.suspendedUntil = performance.now() + PLAN_REPROBE_MS;
 				this.reportOnce(403, `The ${this.kind} endpoint needs a higher plan. Reprobing in 30 minutes.`, false);
 				return {
 					ok: false,
@@ -403,7 +416,7 @@ var StatsPublisher = class extends Publisher {
 	debounce;
 	minGap;
 	getServerCount;
-	lastPostAt = 0;
+	lastPostAt = -Infinity;
 	lastCount;
 	lastShardCount;
 	debounceCap = 0;
@@ -421,7 +434,7 @@ var StatsPublisher = class extends Publisher {
 	/** Trailing debounce, hard-capped so a join storm cannot starve the post. */
 	onGuildChange() {
 		if (this.disabledReason !== void 0) return;
-		const now = Date.now();
+		const now = performance.now();
 		if (this.debounceCap === 0) this.debounceCap = now + this.minGap;
 		this.schedule(Math.min(now + this.debounce, this.debounceCap) - now, () => this.tick());
 	}
@@ -444,7 +457,7 @@ var StatsPublisher = class extends Publisher {
 			status: null,
 			skipped: "in-flight"
 		};
-		const now = Date.now();
+		const now = performance.now();
 		if (!manual && now < this.suspendedUntil) {
 			this.schedule(this.suspendedUntil - now, () => this.tick());
 			return {
@@ -453,7 +466,7 @@ var StatsPublisher = class extends Publisher {
 				skipped: "plan"
 			};
 		}
-		if (this.lastPostAt !== 0 && now < this.lastPostAt + this.minGap) {
+		if (now < this.lastPostAt + this.minGap) {
 			this.schedule(this.lastPostAt + this.minGap - now, () => this.tick());
 			return {
 				ok: false,
@@ -473,7 +486,7 @@ var StatsPublisher = class extends Publisher {
 				};
 			}
 			const shardCount = this.deps.topology.shardCount;
-			if (count === this.lastCount && shardCount === this.lastShardCount && Date.now() < this.lastPostAt + 18e5) {
+			if (count === this.lastCount && shardCount === this.lastShardCount && performance.now() < this.lastPostAt + 18e5) {
 				this.schedule(this.interval, () => this.tick());
 				return {
 					ok: false,
@@ -481,7 +494,7 @@ var StatsPublisher = class extends Publisher {
 					skipped: "unchanged"
 				};
 			}
-			this.lastPostAt = Date.now();
+			this.lastPostAt = performance.now();
 			const result = await this.send(`/bots/${this.deps.botId}/stats`, {
 				server_count: count,
 				shard_count: shardCount
@@ -500,13 +513,14 @@ var StatsPublisher = class extends Publisher {
 var HeartbeatPublisher = class extends Publisher {
 	kind = "heartbeat";
 	interval;
-	startedAt = 0;
-	beats = 0;
+	nextTarget = 0;
+	lastBeatAt = -Infinity;
+	beatNowPending = false;
 	inFlight = false;
 	nextBeatWithinSeconds;
 	constructor(deps, options = {}) {
 		super(deps);
-		this.interval = options.interval ?? 3e4;
+		this.interval = clampInterval(options.interval ?? 3e4);
 	}
 	/** Starts on construction, not on ready: a booting bot must read "connecting", not dead. */
 	start() {
@@ -514,14 +528,16 @@ var HeartbeatPublisher = class extends Publisher {
 			this.disable(null, "cluster-count-unknown");
 			return;
 		}
-		this.startedAt = Date.now();
-		this.beats = 0;
+		this.nextTarget = performance.now();
 		this.schedule(0, () => this.tick());
 	}
-	/** Out-of-band beat after a shard event. Repeated calls coalesce into one. */
+	/** Out-of-band beat after a shard event. Calls before it fires coalesce into one. */
 	beatNow() {
-		if (this.disabledReason !== void 0) return;
-		this.schedule(1e3, () => this.tick());
+		const now = performance.now();
+		if (this.disabledReason !== void 0 || this.beatNowPending || now < this.suspendedUntil) return;
+		this.beatNowPending = true;
+		const delay = Math.max(BEAT_NOW_DELAY_MS, this.lastBeatAt + HEARTBEAT_OUT_OF_BAND_GAP_MS - now);
+		this.schedule(delay, () => this.tick());
 	}
 	async post() {
 		this.rearm();
@@ -533,6 +549,7 @@ var HeartbeatPublisher = class extends Publisher {
 		return this.beat(true);
 	}
 	async tick() {
+		this.beatNowPending = false;
 		await this.beat(false);
 	}
 	async beat(manual) {
@@ -567,6 +584,7 @@ var HeartbeatPublisher = class extends Publisher {
 			shards
 		};
 		this.inFlight = true;
+		this.lastBeatAt = performance.now();
 		let result;
 		try {
 			result = await this.send(`/bots/${this.deps.botId}/heartbeat`, body, "heartbeat", this.interval);
@@ -587,8 +605,7 @@ var HeartbeatPublisher = class extends Publisher {
 	*/
 	retune() {
 		if (this.nextBeatWithinSeconds === void 0) return;
-		const proposed = Math.round(this.nextBeatWithinSeconds / 3 * 1e3);
-		this.interval = Math.min(Math.max(proposed, HEARTBEAT_MIN_INTERVAL_MS), HEARTBEAT_MAX_INTERVAL_MS);
+		this.interval = clampInterval(Math.round(this.nextBeatWithinSeconds / 3 * 1e3));
 	}
 	react(outcome) {
 		if (outcome.kind === "ok") {
@@ -597,15 +614,22 @@ var HeartbeatPublisher = class extends Publisher {
 		}
 		return super.react(outcome);
 	}
-	/** Absolute-time scheduling, so a slow request cannot drift the cadence. */
+	/**
+	* Absolute targets, so a slow request cannot drift the cadence and an
+	* out-of-band beat does not push the next regular one back. Missed slots
+	* are skipped, so the end of a long suspension is one beat, not a burst.
+	*/
 	scheduleNext(minDelayMs = 0) {
-		this.beats += 1;
+		const now = performance.now();
+		if (this.nextTarget <= now) this.nextTarget += (Math.floor((now - this.nextTarget) / this.interval) + 1) * this.interval;
 		const jitter = Math.round(Math.random() * HEARTBEAT_JITTER_MS);
-		const target = this.startedAt + this.beats * this.interval + jitter;
-		const delay = Math.max(target - Date.now(), minDelayMs, 1e3, this.suspendedUntil - Date.now());
+		const delay = Math.max(this.nextTarget + jitter - now, minDelayMs, BEAT_NOW_DELAY_MS, this.suspendedUntil - now);
 		this.schedule(delay, () => this.tick());
 	}
 };
+function clampInterval(ms) {
+	return Math.min(Math.max(ms, HEARTBEAT_MIN_INTERVAL_MS), HEARTBEAT_MAX_INTERVAL_MS);
+}
 var CommandsPublisher = class extends Publisher {
 	rest;
 	options;
@@ -630,7 +654,7 @@ var CommandsPublisher = class extends Publisher {
 			status: null,
 			skipped: "disabled"
 		};
-		if (Date.now() < this.suspendedUntil) return {
+		if (performance.now() < this.suspendedUntil) return {
 			ok: false,
 			status: null,
 			skipped: "plan"
@@ -680,6 +704,11 @@ var CommandsPublisher = class extends Publisher {
 const version = version$1;
 const DEFAULT_BASE_URL = "https://thediscordlist.com/api";
 const LOG_PREFIX = "[@thediscordlist/discord.js]";
+const DISABLED = Object.freeze({
+	ok: false,
+	status: null,
+	skipped: "disabled"
+});
 var Autoposter = class extends node_events.EventEmitter {
 	stats;
 	heartbeat;
@@ -769,25 +798,13 @@ var Autoposter = class extends node_events.EventEmitter {
 		this.commands?.stop();
 	}
 	postStats() {
-		return this.stats?.post() ?? Promise.resolve({
-			ok: false,
-			status: null,
-			skipped: "disabled"
-		});
+		return this.stats?.post() ?? Promise.resolve(DISABLED);
 	}
 	postHeartbeat() {
-		return this.heartbeat?.post() ?? Promise.resolve({
-			ok: false,
-			status: null,
-			skipped: "disabled"
-		});
+		return this.heartbeat?.post() ?? Promise.resolve(DISABLED);
 	}
 	postCommands() {
-		return this.commands?.post() ?? Promise.resolve({
-			ok: false,
-			status: null,
-			skipped: "disabled"
-		});
+		return this.commands?.post() ?? Promise.resolve(DISABLED);
 	}
 	/** Clears every timer and detaches every client listener. Not restartable. */
 	stop() {
@@ -810,13 +827,14 @@ function checkIntents(client, poster) {
 */
 function autopost(client, token, options = {}) {
 	const poster = new Autoposter();
-	if (!token) {
+	const cleaned = token?.trim().replace(/^bearer\s+/i, "");
+	if (!cleaned) {
 		poster.warnOnce("no-token", "No stats token supplied; auto-posting is disabled.");
 		return poster;
 	}
 	const api = createApiClient({
 		baseUrl: options.baseUrl ?? "https://thediscordlist.com/api",
-		token,
+		token: cleaned,
 		userAgent: `@thediscordlist/discord.js/${version} (discord.js ${discord_js.version})`
 	});
 	if (options.botId) {
@@ -841,5 +859,9 @@ function autopost(client, token, options = {}) {
 //#endregion
 exports.Autoposter = Autoposter;
 exports.DEFAULT_BASE_URL = DEFAULT_BASE_URL;
+exports.HEARTBEAT_DEFAULT_INTERVAL_MS = HEARTBEAT_DEFAULT_INTERVAL_MS;
+exports.STATS_DEBOUNCE_MS = STATS_DEBOUNCE_MS;
+exports.STATS_INTERVAL_MS = STATS_INTERVAL_MS;
+exports.STATS_MIN_GAP_MS = STATS_MIN_GAP_MS;
 exports.autopost = autopost;
 exports.version = version;

package/dist/index.d.cts

@@ -31,7 +31,14 @@ type Outcome = {
 };
 type Priority = 'normal' | 'heartbeat';
 interface ApiClient {
-  post(path: string, body: unknown, priority: Priority): Promise<Outcome>;
+  /**
+   * One request, retrying transient failures and, once its window lifts, a 429.
+   *
+   * `nextTickInMs` is the time until the caller runs again. If a wait would
+   * outlast it, the attempt is dropped: the next tick carries fresher data,
+   * and a failed request still burns rate-limit budget.
+   */
+  post(path: string, body: unknown, priority: Priority, nextTickInMs?: number): Promise<Outcome>;
 }
 //#endregion
 //#region src/topology.d.ts
@@ -89,6 +96,10 @@ interface ClientLike {
 }
 //#endregion
 //#region src/publishers.d.ts
+declare const STATS_INTERVAL_MS = 300000;
+declare const STATS_DEBOUNCE_MS = 20000;
+declare const STATS_MIN_GAP_MS = 60000;
+declare const HEARTBEAT_DEFAULT_INTERVAL_MS = 30000;
 type PublisherKind = 'stats' | 'heartbeat' | 'commands';
 interface PostResult {
   ok: boolean;
@@ -126,17 +137,20 @@ interface AutopostOptions {
   stats?: {
     /** Default: true. */
     enabled?: boolean | undefined;
-    /** Default: 300000. */
+    /** Default: {@link STATS_INTERVAL_MS}. */
     interval?: number | undefined;
-    /** Trailing debounce after guildCreate/guildDelete. Default: 20000. */
+    /** Trailing debounce after guildCreate/guildDelete. Default: {@link STATS_DEBOUNCE_MS}. */
     debounce?: number | undefined;
-    /** Hard floor between two POSTs. Default: 60000. */
+    /** Hard floor between two POSTs. Default: {@link STATS_MIN_GAP_MS}. */
     minGap?: number | undefined;
   } | undefined;
   heartbeat?: {
     /** Default: true. */
     enabled?: boolean | undefined;
-    /** Starting cadence; retuned from the API response. Default: 30000. */
+    /**
+     * Starting cadence, clamped to 15–60s and retuned from the API response.
+     * Default: {@link HEARTBEAT_DEFAULT_INTERVAL_MS}.
+     */
     interval?: number | undefined;
   } | undefined;
   commands?: {
@@ -203,4 +217,4 @@ declare class Autoposter extends EventEmitter<AutoposterEvents> {
  */
 declare function autopost(client: Client, token: string | undefined, options?: AutopostOptions): Autoposter;
 //#endregion
-export { AutopostOptions, Autoposter, AutoposterEvents, type ClientLike, DEFAULT_BASE_URL, type Outcome, type PostResult, type Priority, type PublisherError, type PublisherKind, type ShardReport, type ShardStatus, type Topology, type TopologyKind, autopost, version };
+export { AutopostOptions, Autoposter, AutoposterEvents, type ClientLike, DEFAULT_BASE_URL, HEARTBEAT_DEFAULT_INTERVAL_MS, type Outcome, type PostResult, type Priority, type PublisherError, type PublisherKind, STATS_DEBOUNCE_MS, STATS_INTERVAL_MS, STATS_MIN_GAP_MS, type ShardReport, type ShardStatus, type Topology, type TopologyKind, autopost, version };

package/dist/index.d.mts

@@ -31,7 +31,14 @@ type Outcome = {
 };
 type Priority = 'normal' | 'heartbeat';
 interface ApiClient {
-  post(path: string, body: unknown, priority: Priority): Promise<Outcome>;
+  /**
+   * One request, retrying transient failures and, once its window lifts, a 429.
+   *
+   * `nextTickInMs` is the time until the caller runs again. If a wait would
+   * outlast it, the attempt is dropped: the next tick carries fresher data,
+   * and a failed request still burns rate-limit budget.
+   */
+  post(path: string, body: unknown, priority: Priority, nextTickInMs?: number): Promise<Outcome>;
 }
 //#endregion
 //#region src/topology.d.ts
@@ -89,6 +96,10 @@ interface ClientLike {
 }
 //#endregion
 //#region src/publishers.d.ts
+declare const STATS_INTERVAL_MS = 300000;
+declare const STATS_DEBOUNCE_MS = 20000;
+declare const STATS_MIN_GAP_MS = 60000;
+declare const HEARTBEAT_DEFAULT_INTERVAL_MS = 30000;
 type PublisherKind = 'stats' | 'heartbeat' | 'commands';
 interface PostResult {
   ok: boolean;
@@ -126,17 +137,20 @@ interface AutopostOptions {
   stats?: {
     /** Default: true. */
     enabled?: boolean | undefined;
-    /** Default: 300000. */
+    /** Default: {@link STATS_INTERVAL_MS}. */
     interval?: number | undefined;
-    /** Trailing debounce after guildCreate/guildDelete. Default: 20000. */
+    /** Trailing debounce after guildCreate/guildDelete. Default: {@link STATS_DEBOUNCE_MS}. */
     debounce?: number | undefined;
-    /** Hard floor between two POSTs. Default: 60000. */
+    /** Hard floor between two POSTs. Default: {@link STATS_MIN_GAP_MS}. */
     minGap?: number | undefined;
   } | undefined;
   heartbeat?: {
     /** Default: true. */
     enabled?: boolean | undefined;
-    /** Starting cadence; retuned from the API response. Default: 30000. */
+    /**
+     * Starting cadence, clamped to 15–60s and retuned from the API response.
+     * Default: {@link HEARTBEAT_DEFAULT_INTERVAL_MS}.
+     */
     interval?: number | undefined;
   } | undefined;
   commands?: {
@@ -203,4 +217,4 @@ declare class Autoposter extends EventEmitter<AutoposterEvents> {
  */
 declare function autopost(client: Client, token: string | undefined, options?: AutopostOptions): Autoposter;
 //#endregion
-export { AutopostOptions, Autoposter, AutoposterEvents, type ClientLike, DEFAULT_BASE_URL, type Outcome, type PostResult, type Priority, type PublisherError, type PublisherKind, type ShardReport, type ShardStatus, type Topology, type TopologyKind, autopost, version };
+export { AutopostOptions, Autoposter, AutoposterEvents, type ClientLike, DEFAULT_BASE_URL, HEARTBEAT_DEFAULT_INTERVAL_MS, type Outcome, type PostResult, type Priority, type PublisherError, type PublisherKind, STATS_DEBOUNCE_MS, STATS_INTERVAL_MS, STATS_MIN_GAP_MS, type ShardReport, type ShardStatus, type Topology, type TopologyKind, autopost, version };

package/dist/index.mjs

@@ -1,11 +1,16 @@
 import { EventEmitter } from "node:events";
 import { Events, GatewayIntentBits, Status, version as version$1 } from "discord.js";
 //#region package.json
-var version$2 = "0.1.1";
+var version$2 = "0.2.0";
+/** However far out Retry-After or X-RateLimit-Reset points, never go quiet for longer. */
+const MAX_RATE_LIMIT_WAIT_MS = 36e5;
+const MAX_ATTEMPTS = 3;
 /**
-* Drops `undefined` keys recursively. An explicit `null` survives, and must:
-* the API's `prepareForValidation` only defaults keys that are *absent*, and
-* none of its rules are `nullable`, so a serialised `undefined` is a 422.
+* Drops `undefined` keys recursively, so an unset value arrives absent rather
+* than `null`. The API's `prepareForValidation` only defaults keys that are
+* *absent*, and `cluster`, `cluster_count` and `shards` are not `nullable`, so
+* a `null` there is a 422. An explicit `null` survives: where a rule is
+* nullable it is a deliberate "unknown".
 */
 function stripUndefined(value) {
 	if (Array.isArray(value)) return value.map((item) => stripUndefined(item));
@@ -14,6 +19,9 @@ function stripUndefined(value) {
 	for (const [key, item] of Object.entries(value)) if (item !== void 0) out[key] = stripUndefined(item);
 	return out;
 }
+function isRetryable(outcome) {
+	return outcome.kind === "transient" || outcome.kind === "throttled";
+}
 /** Full jitter in the upper half, capped at 30s. */
 function backoffMs(attempt, random = Math.random) {
 	return Math.round(Math.min(1e3 * 2 ** attempt, 3e4) * (.5 + random() * .5));
@@ -40,10 +48,6 @@ function classify(status, body, retryAfterHeader) {
 		kind: "config",
 		status
 	};
-	if (status === 400 || status === 422) return {
-		kind: "payload",
-		status
-	};
 	if (status === 429) {
 		const seconds = Number(retryAfterHeader);
 		return {
@@ -52,22 +56,32 @@ function classify(status, body, retryAfterHeader) {
 			retryAfterMs: Number.isFinite(seconds) && seconds > 0 ? seconds * 1e3 : 6e4
 		};
 	}
+	if (status >= 400 && status < 500 && status !== 408 && status !== 425) return {
+		kind: "payload",
+		status
+	};
 	return {
 		kind: "transient",
 		status,
 		error: /* @__PURE__ */ new Error(`TheDiscordList responded ${status}.`)
 	};
 }
+function sleep(ms) {
+	return new Promise((resolve) => {
+		setTimeout(resolve, ms).unref?.();
+	});
+}
 function createApiClient(options) {
+	const baseUrl = options.baseUrl.replace(/\/+$/, "");
 	let suspendedUntil = 0;
-	return { async post(path, body, priority) {
-		if (priority !== "heartbeat" && Date.now() < suspendedUntil) return {
+	async function once(path, body, ignoreLimit) {
+		if (!ignoreLimit && performance.now() < suspendedUntil) return {
 			kind: "dropped",
 			status: null
 		};
 		let response;
 		try {
-			response = await fetch(`${options.baseUrl}${path}`, {
+			response = await fetch(`${baseUrl}${path}`, {
 				method: "POST",
 				headers: {
 					authorization: `Bearer ${options.token}`,
@@ -103,8 +117,22 @@ function createApiClient(options) {
 		const outcome = classify(response.status, parsed, response.headers.get("retry-after"));
 		if (outcome.kind === "throttled") {
 			const reset = Number(response.headers.get("x-ratelimit-reset"));
-			const untilReset = Number.isFinite(reset) && reset > 0 ? reset * 1e3 : 0;
-			suspendedUntil = Math.max(Date.now() + outcome.retryAfterMs, untilReset) + Math.round(Math.random() * 2e3);
+			const untilReset = Number.isFinite(reset) && reset > 0 ? reset * 1e3 - Date.now() : 0;
+			suspendedUntil = performance.now() + Math.min(Math.max(outcome.retryAfterMs, untilReset), MAX_RATE_LIMIT_WAIT_MS) + Math.round(Math.random() * 2e3);
+		}
+		return outcome;
+	}
+	return { async post(path, body, priority, nextTickInMs) {
+		let outcome = {
+			kind: "dropped",
+			status: null
+		};
+		for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+			outcome = await once(path, body, priority === "heartbeat" || outcome.kind === "throttled");
+			if (!isRetryable(outcome) || attempt === 2) break;
+			const delay = outcome.kind === "throttled" ? suspendedUntil - performance.now() : backoffMs(attempt);
+			if (nextTickInMs !== void 0 && delay >= nextTickInMs) break;
+			await sleep(delay);
 		}
 		return outcome;
 	} };
@@ -244,16 +272,24 @@ async function measureServerCount(client, topology, getServerCount) {
 	}
 	return total;
 }
+//#endregion
+//#region src/publishers.ts
+const STATS_INTERVAL_MS = 3e5;
+const STATS_DEBOUNCE_MS = 2e4;
+const STATS_MIN_GAP_MS = 6e4;
 const STATS_FIRST_POST_DELAY_MS = 5e3;
 const STATS_REMEASURE_MS = 6e4;
+const HEARTBEAT_DEFAULT_INTERVAL_MS = 3e4;
 const HEARTBEAT_MIN_INTERVAL_MS = 15e3;
 const HEARTBEAT_MAX_INTERVAL_MS = 6e4;
 const HEARTBEAT_JITTER_MS = 5e3;
+/** An out-of-band beat never follows the previous beat more closely than this. */
+const HEARTBEAT_OUT_OF_BAND_GAP_MS = 1e4;
+const BEAT_NOW_DELAY_MS = 1e3;
 /** Offset from the stats post: the two share one server-side rate budget. */
 const COMMANDS_DELAY_MS = 1e4;
 /** The Gold tier is derived per request from Stripe, so it can flip mid-run. */
 const PLAN_REPROBE_MS = 18e5;
-const MAX_ATTEMPTS = 3;
 function publisherError(message, type, status, retryable) {
 	return Object.assign(new Error(message), {
 		type,
@@ -261,11 +297,6 @@ function publisherError(message, type, status, retryable) {
 		retryable
 	});
 }
-function sleep(ms) {
-	return new Promise((resolve) => {
-		setTimeout(resolve, ms).unref?.();
-	});
-}
 var Publisher = class {
 	deps;
 	timer;
@@ -313,27 +344,9 @@ var Publisher = class {
 		this.reported.add(status);
 		this.deps.emit.error(publisherError(message, this.kind, status, retryable));
 	}
-	/**
-	* Sends one request, retrying only transient failures.
-	*
-	* `nextTickInMs` is the time until this publisher's next scheduled run. If a
-	* backoff would outlast it, the attempt is dropped: the next tick carries
-	* fresher data, and a failed request still burns rate-limit budget.
-	*/
+	/** `nextTickInMs` is the time until this publisher's next scheduled run; no retry outlasts it. */
 	async send(path, body, priority, nextTickInMs) {
-		let outcome = {
-			kind: "dropped",
-			status: null
-		};
-		for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
-			outcome = await this.deps.api.post(path, body, priority);
-			if (outcome.kind !== "transient") break;
-			const delay = backoffMs(attempt);
-			if (attempt === 2) break;
-			if (nextTickInMs !== void 0 && delay >= nextTickInMs) break;
-			await sleep(delay);
-		}
-		return this.react(outcome);
+		return this.react(await this.deps.api.post(path, body, priority, nextTickInMs));
 	}
 	react(outcome) {
 		switch (outcome.kind) {
@@ -365,7 +378,7 @@ var Publisher = class {
 					status: 401
 				};
 			case "plan":
-				this.suspendedUntil = Date.now() + PLAN_REPROBE_MS;
+				this.suspendedUntil = performance.now() + PLAN_REPROBE_MS;
 				this.reportOnce(403, `The ${this.kind} endpoint needs a higher plan. Reprobing in 30 minutes.`, false);
 				return {
 					ok: false,
@@ -402,7 +415,7 @@ var StatsPublisher = class extends Publisher {
 	debounce;
 	minGap;
 	getServerCount;
-	lastPostAt = 0;
+	lastPostAt = -Infinity;
 	lastCount;
 	lastShardCount;
 	debounceCap = 0;
@@ -420,7 +433,7 @@ var StatsPublisher = class extends Publisher {
 	/** Trailing debounce, hard-capped so a join storm cannot starve the post. */
 	onGuildChange() {
 		if (this.disabledReason !== void 0) return;
-		const now = Date.now();
+		const now = performance.now();
 		if (this.debounceCap === 0) this.debounceCap = now + this.minGap;
 		this.schedule(Math.min(now + this.debounce, this.debounceCap) - now, () => this.tick());
 	}
@@ -443,7 +456,7 @@ var StatsPublisher = class extends Publisher {
 			status: null,
 			skipped: "in-flight"
 		};
-		const now = Date.now();
+		const now = performance.now();
 		if (!manual && now < this.suspendedUntil) {
 			this.schedule(this.suspendedUntil - now, () => this.tick());
 			return {
@@ -452,7 +465,7 @@ var StatsPublisher = class extends Publisher {
 				skipped: "plan"
 			};
 		}
-		if (this.lastPostAt !== 0 && now < this.lastPostAt + this.minGap) {
+		if (now < this.lastPostAt + this.minGap) {
 			this.schedule(this.lastPostAt + this.minGap - now, () => this.tick());
 			return {
 				ok: false,
@@ -472,7 +485,7 @@ var StatsPublisher = class extends Publisher {
 				};
 			}
 			const shardCount = this.deps.topology.shardCount;
-			if (count === this.lastCount && shardCount === this.lastShardCount && Date.now() < this.lastPostAt + 18e5) {
+			if (count === this.lastCount && shardCount === this.lastShardCount && performance.now() < this.lastPostAt + 18e5) {
 				this.schedule(this.interval, () => this.tick());
 				return {
 					ok: false,
@@ -480,7 +493,7 @@ var StatsPublisher = class extends Publisher {
 					skipped: "unchanged"
 				};
 			}
-			this.lastPostAt = Date.now();
+			this.lastPostAt = performance.now();
 			const result = await this.send(`/bots/${this.deps.botId}/stats`, {
 				server_count: count,
 				shard_count: shardCount
@@ -499,13 +512,14 @@ var StatsPublisher = class extends Publisher {
 var HeartbeatPublisher = class extends Publisher {
 	kind = "heartbeat";
 	interval;
-	startedAt = 0;
-	beats = 0;
+	nextTarget = 0;
+	lastBeatAt = -Infinity;
+	beatNowPending = false;
 	inFlight = false;
 	nextBeatWithinSeconds;
 	constructor(deps, options = {}) {
 		super(deps);
-		this.interval = options.interval ?? 3e4;
+		this.interval = clampInterval(options.interval ?? 3e4);
 	}
 	/** Starts on construction, not on ready: a booting bot must read "connecting", not dead. */
 	start() {
@@ -513,14 +527,16 @@ var HeartbeatPublisher = class extends Publisher {
 			this.disable(null, "cluster-count-unknown");
 			return;
 		}
-		this.startedAt = Date.now();
-		this.beats = 0;
+		this.nextTarget = performance.now();
 		this.schedule(0, () => this.tick());
 	}
-	/** Out-of-band beat after a shard event. Repeated calls coalesce into one. */
+	/** Out-of-band beat after a shard event. Calls before it fires coalesce into one. */
 	beatNow() {
-		if (this.disabledReason !== void 0) return;
-		this.schedule(1e3, () => this.tick());
+		const now = performance.now();
+		if (this.disabledReason !== void 0 || this.beatNowPending || now < this.suspendedUntil) return;
+		this.beatNowPending = true;
+		const delay = Math.max(BEAT_NOW_DELAY_MS, this.lastBeatAt + HEARTBEAT_OUT_OF_BAND_GAP_MS - now);
+		this.schedule(delay, () => this.tick());
 	}
 	async post() {
 		this.rearm();
@@ -532,6 +548,7 @@ var HeartbeatPublisher = class extends Publisher {
 		return this.beat(true);
 	}
 	async tick() {
+		this.beatNowPending = false;
 		await this.beat(false);
 	}
 	async beat(manual) {
@@ -566,6 +583,7 @@ var HeartbeatPublisher = class extends Publisher {
 			shards
 		};
 		this.inFlight = true;
+		this.lastBeatAt = performance.now();
 		let result;
 		try {
 			result = await this.send(`/bots/${this.deps.botId}/heartbeat`, body, "heartbeat", this.interval);
@@ -586,8 +604,7 @@ var HeartbeatPublisher = class extends Publisher {
 	*/
 	retune() {
 		if (this.nextBeatWithinSeconds === void 0) return;
-		const proposed = Math.round(this.nextBeatWithinSeconds / 3 * 1e3);
-		this.interval = Math.min(Math.max(proposed, HEARTBEAT_MIN_INTERVAL_MS), HEARTBEAT_MAX_INTERVAL_MS);
+		this.interval = clampInterval(Math.round(this.nextBeatWithinSeconds / 3 * 1e3));
 	}
 	react(outcome) {
 		if (outcome.kind === "ok") {
@@ -596,15 +613,22 @@ var HeartbeatPublisher = class extends Publisher {
 		}
 		return super.react(outcome);
 	}
-	/** Absolute-time scheduling, so a slow request cannot drift the cadence. */
+	/**
+	* Absolute targets, so a slow request cannot drift the cadence and an
+	* out-of-band beat does not push the next regular one back. Missed slots
+	* are skipped, so the end of a long suspension is one beat, not a burst.
+	*/
 	scheduleNext(minDelayMs = 0) {
-		this.beats += 1;
+		const now = performance.now();
+		if (this.nextTarget <= now) this.nextTarget += (Math.floor((now - this.nextTarget) / this.interval) + 1) * this.interval;
 		const jitter = Math.round(Math.random() * HEARTBEAT_JITTER_MS);
-		const target = this.startedAt + this.beats * this.interval + jitter;
-		const delay = Math.max(target - Date.now(), minDelayMs, 1e3, this.suspendedUntil - Date.now());
+		const delay = Math.max(this.nextTarget + jitter - now, minDelayMs, BEAT_NOW_DELAY_MS, this.suspendedUntil - now);
 		this.schedule(delay, () => this.tick());
 	}
 };
+function clampInterval(ms) {
+	return Math.min(Math.max(ms, HEARTBEAT_MIN_INTERVAL_MS), HEARTBEAT_MAX_INTERVAL_MS);
+}
 var CommandsPublisher = class extends Publisher {
 	rest;
 	options;
@@ -629,7 +653,7 @@ var CommandsPublisher = class extends Publisher {
 			status: null,
 			skipped: "disabled"
 		};
-		if (Date.now() < this.suspendedUntil) return {
+		if (performance.now() < this.suspendedUntil) return {
 			ok: false,
 			status: null,
 			skipped: "plan"
@@ -679,6 +703,11 @@ var CommandsPublisher = class extends Publisher {
 const version = version$2;
 const DEFAULT_BASE_URL = "https://thediscordlist.com/api";
 const LOG_PREFIX = "[@thediscordlist/discord.js]";
+const DISABLED = Object.freeze({
+	ok: false,
+	status: null,
+	skipped: "disabled"
+});
 var Autoposter = class extends EventEmitter {
 	stats;
 	heartbeat;
@@ -768,25 +797,13 @@ var Autoposter = class extends EventEmitter {
 		this.commands?.stop();
 	}
 	postStats() {
-		return this.stats?.post() ?? Promise.resolve({
-			ok: false,
-			status: null,
-			skipped: "disabled"
-		});
+		return this.stats?.post() ?? Promise.resolve(DISABLED);
 	}
 	postHeartbeat() {
-		return this.heartbeat?.post() ?? Promise.resolve({
-			ok: false,
-			status: null,
-			skipped: "disabled"
-		});
+		return this.heartbeat?.post() ?? Promise.resolve(DISABLED);
 	}
 	postCommands() {
-		return this.commands?.post() ?? Promise.resolve({
-			ok: false,
-			status: null,
-			skipped: "disabled"
-		});
+		return this.commands?.post() ?? Promise.resolve(DISABLED);
 	}
 	/** Clears every timer and detaches every client listener. Not restartable. */
 	stop() {
@@ -809,13 +826,14 @@ function checkIntents(client, poster) {
 */
 function autopost(client, token, options = {}) {
 	const poster = new Autoposter();
-	if (!token) {
+	const cleaned = token?.trim().replace(/^bearer\s+/i, "");
+	if (!cleaned) {
 		poster.warnOnce("no-token", "No stats token supplied; auto-posting is disabled.");
 		return poster;
 	}
 	const api = createApiClient({
 		baseUrl: options.baseUrl ?? "https://thediscordlist.com/api",
-		token,
+		token: cleaned,
 		userAgent: `@thediscordlist/discord.js/${version} (discord.js ${version$1})`
 	});
 	if (options.botId) {
@@ -838,4 +856,4 @@ function autopost(client, token, options = {}) {
 	return poster;
 }
 //#endregion
-export { Autoposter, DEFAULT_BASE_URL, autopost, version };
+export { Autoposter, DEFAULT_BASE_URL, HEARTBEAT_DEFAULT_INTERVAL_MS, STATS_DEBOUNCE_MS, STATS_INTERVAL_MS, STATS_MIN_GAP_MS, autopost, version };

package/dist/webhooks.cjs

@@ -20,6 +20,10 @@ var TdlWebhookError = class extends Error {
 		this.name = "TdlWebhookError";
 	}
 };
+/** An empty key would make every signature computable by anyone, so it is a setup error. */
+function requireSecret(secret) {
+	if (typeof secret !== "string" || secret.trim() === "") throw new TypeError("A webhook secret is required.");
+}
 /** Length is not secret, and `timingSafeEqual` throws when lengths differ. */
 function safeEqual(a, b) {
 	if (a.length !== b.length || a.length === 0) return false;
@@ -33,9 +37,11 @@ function safeEqual(a, b) {
 * and posts that same string, so `JSON.stringify(req.body)` re-escapes slashes
 * and non-ASCII and can never verify.
 *
-* @throws {TdlWebhookError} and nothing else.
+* @throws {TdlWebhookError} when the delivery does not verify.
+* @throws {TypeError} when `secret` is empty.
 */
 function verifyWebhook(rawBody, signatureHeader, secret, options = {}) {
+	requireSecret(secret);
 	const header = Array.isArray(signatureHeader) ? signatureHeader[0] : signatureHeader;
 	if (!header) throw new TdlWebhookError("MISSING_SIGNATURE", `Missing ${WEBHOOK_SIGNATURE_HEADER} header.`);
 	let timestamp;
@@ -110,6 +116,7 @@ function verifyOptions(options) {
 * ```
 */
 function createFetchWebhookHandler(options) {
+	requireSecret(options.secret);
 	return async (request) => {
 		if (request.method !== "POST") return new Response(null, { status: 405 });
 		const raw = await request.text();
@@ -127,13 +134,15 @@ function createFetchWebhookHandler(options) {
 }
 /**
 * `node:http` and express/connect handler. It reads the stream itself, so it
-* must be mounted before any JSON body parser.
+* must be mounted before any JSON body parser; a raw `Buffer` body from
+* `express.raw()` is used as is.
 *
 * ```ts
 * app.post('/tdl', createWebhookHandler({ secret, onEvent }));
 * ```
 */
 function createWebhookHandler(options) {
+	requireSecret(options.secret);
 	return (req, res) => {
 		(async () => {
 			const end = (status) => {
@@ -141,26 +150,32 @@ function createWebhookHandler(options) {
 				res.end();
 			};
 			if (req.method !== "POST") return end(405);
-			if (req.body !== void 0) {
+			let raw;
+			if (req.body instanceof Uint8Array) {
+				raw = req.body;
+				if (raw.byteLength > 1048576) return end(413);
+			} else if (req.body !== void 0) {
 				options.onError?.(new TdlWebhookError("BODY_CONSUMED", "Request body was already parsed, so the signed bytes are gone. Mount this handler before any JSON body parser, or use express.raw({ type: 'application/json' }) on this route."));
 				return end(500);
-			}
-			let size = 0;
-			const chunks = [];
-			try {
-				for await (const chunk of req) {
-					const buf = Buffer.from(chunk);
-					size += buf.length;
-					if (size > 1048576) return end(413);
-					chunks.push(buf);
+			} else {
+				let size = 0;
+				const chunks = [];
+				try {
+					for await (const chunk of req) {
+						const buf = Buffer.from(chunk);
+						size += buf.length;
+						if (size > 1048576) return end(413);
+						chunks.push(buf);
+					}
+				} catch (error) {
+					options.onError?.(error);
+					return end(400);
 				}
-			} catch (error) {
-				options.onError?.(error);
-				return end(400);
+				raw = Buffer.concat(chunks);
 			}
 			let event;
 			try {
-				event = verifyWebhook(Buffer.concat(chunks), req.headers[WEBHOOK_SIGNATURE_HEADER], options.secret, verifyOptions(options));
+				event = verifyWebhook(raw, req.headers[WEBHOOK_SIGNATURE_HEADER], options.secret, verifyOptions(options));
 			} catch (error) {
 				options.onError?.(error);
 				return end(statusForError(error));

package/dist/webhooks.d.cts

@@ -25,7 +25,7 @@ interface TdlWebhookListing {
   url: string;
 }
 interface TdlEnvelope<E extends string, D> {
-  /** UUID, equals `X-TDL-Delivery`, stable across all 5 retries. Idempotency key. */
+  /** UUID, equals `X-TDL-Delivery`, stable across all 5 attempts. Idempotency key. */
   id: string;
   event: E;
   /** Enqueue time, NOT send time. Do not use it for freshness. */
@@ -38,6 +38,8 @@ type TdlWebhookPayload = TdlEnvelope<'listing.bumped', {
   bumped_at: TdlIsoDate;
   next_bump_at: TdlIsoDate;
   user: TdlWebhookUser | null;
+}> | TdlEnvelope<'listing.bump_ready', {
+  ready_at: TdlIsoDate;
 }> | TdlEnvelope<'listing.upvoted', {
   voted_at: TdlIsoDate;
   total_upvotes: number;
@@ -75,7 +77,8 @@ interface VerifyWebhookOptions {
  * and posts that same string, so `JSON.stringify(req.body)` re-escapes slashes
  * and non-ASCII and can never verify.
  *
- * @throws {TdlWebhookError} and nothing else.
+ * @throws {TdlWebhookError} when the delivery does not verify.
+ * @throws {TypeError} when `secret` is empty.
  */
 declare function verifyWebhook(rawBody: string | Uint8Array, signatureHeader: string | string[] | undefined, secret: string, options?: VerifyWebhookOptions): TdlWebhookPayload;
 interface WebhookContext {
@@ -103,7 +106,8 @@ interface WebhookHandlerOptions {
 declare function createFetchWebhookHandler(options: WebhookHandlerOptions): (request: Request) => Promise<Response>;
 /**
  * `node:http` and express/connect handler. It reads the stream itself, so it
- * must be mounted before any JSON body parser.
+ * must be mounted before any JSON body parser; a raw `Buffer` body from
+ * `express.raw()` is used as is.
  *
  * ```ts
  * app.post('/tdl', createWebhookHandler({ secret, onEvent }));

package/dist/webhooks.d.mts

@@ -25,7 +25,7 @@ interface TdlWebhookListing {
   url: string;
 }
 interface TdlEnvelope<E extends string, D> {
-  /** UUID, equals `X-TDL-Delivery`, stable across all 5 retries. Idempotency key. */
+  /** UUID, equals `X-TDL-Delivery`, stable across all 5 attempts. Idempotency key. */
   id: string;
   event: E;
   /** Enqueue time, NOT send time. Do not use it for freshness. */
@@ -38,6 +38,8 @@ type TdlWebhookPayload = TdlEnvelope<'listing.bumped', {
   bumped_at: TdlIsoDate;
   next_bump_at: TdlIsoDate;
   user: TdlWebhookUser | null;
+}> | TdlEnvelope<'listing.bump_ready', {
+  ready_at: TdlIsoDate;
 }> | TdlEnvelope<'listing.upvoted', {
   voted_at: TdlIsoDate;
   total_upvotes: number;
@@ -75,7 +77,8 @@ interface VerifyWebhookOptions {
  * and posts that same string, so `JSON.stringify(req.body)` re-escapes slashes
  * and non-ASCII and can never verify.
  *
- * @throws {TdlWebhookError} and nothing else.
+ * @throws {TdlWebhookError} when the delivery does not verify.
+ * @throws {TypeError} when `secret` is empty.
  */
 declare function verifyWebhook(rawBody: string | Uint8Array, signatureHeader: string | string[] | undefined, secret: string, options?: VerifyWebhookOptions): TdlWebhookPayload;
 interface WebhookContext {
@@ -103,7 +106,8 @@ interface WebhookHandlerOptions {
 declare function createFetchWebhookHandler(options: WebhookHandlerOptions): (request: Request) => Promise<Response>;
 /**
  * `node:http` and express/connect handler. It reads the stream itself, so it
- * must be mounted before any JSON body parser.
+ * must be mounted before any JSON body parser; a raw `Buffer` body from
+ * `express.raw()` is used as is.
  *
  * ```ts
  * app.post('/tdl', createWebhookHandler({ secret, onEvent }));

package/dist/webhooks.mjs

@@ -19,6 +19,10 @@ var TdlWebhookError = class extends Error {
 		this.name = "TdlWebhookError";
 	}
 };
+/** An empty key would make every signature computable by anyone, so it is a setup error. */
+function requireSecret(secret) {
+	if (typeof secret !== "string" || secret.trim() === "") throw new TypeError("A webhook secret is required.");
+}
 /** Length is not secret, and `timingSafeEqual` throws when lengths differ. */
 function safeEqual(a, b) {
 	if (a.length !== b.length || a.length === 0) return false;
@@ -32,9 +36,11 @@ function safeEqual(a, b) {
 * and posts that same string, so `JSON.stringify(req.body)` re-escapes slashes
 * and non-ASCII and can never verify.
 *
-* @throws {TdlWebhookError} and nothing else.
+* @throws {TdlWebhookError} when the delivery does not verify.
+* @throws {TypeError} when `secret` is empty.
 */
 function verifyWebhook(rawBody, signatureHeader, secret, options = {}) {
+	requireSecret(secret);
 	const header = Array.isArray(signatureHeader) ? signatureHeader[0] : signatureHeader;
 	if (!header) throw new TdlWebhookError("MISSING_SIGNATURE", `Missing ${WEBHOOK_SIGNATURE_HEADER} header.`);
 	let timestamp;
@@ -109,6 +115,7 @@ function verifyOptions(options) {
 * ```
 */
 function createFetchWebhookHandler(options) {
+	requireSecret(options.secret);
 	return async (request) => {
 		if (request.method !== "POST") return new Response(null, { status: 405 });
 		const raw = await request.text();
@@ -126,13 +133,15 @@ function createFetchWebhookHandler(options) {
 }
 /**
 * `node:http` and express/connect handler. It reads the stream itself, so it
-* must be mounted before any JSON body parser.
+* must be mounted before any JSON body parser; a raw `Buffer` body from
+* `express.raw()` is used as is.
 *
 * ```ts
 * app.post('/tdl', createWebhookHandler({ secret, onEvent }));
 * ```
 */
 function createWebhookHandler(options) {
+	requireSecret(options.secret);
 	return (req, res) => {
 		(async () => {
 			const end = (status) => {
@@ -140,26 +149,32 @@ function createWebhookHandler(options) {
 				res.end();
 			};
 			if (req.method !== "POST") return end(405);
-			if (req.body !== void 0) {
+			let raw;
+			if (req.body instanceof Uint8Array) {
+				raw = req.body;
+				if (raw.byteLength > 1048576) return end(413);
+			} else if (req.body !== void 0) {
 				options.onError?.(new TdlWebhookError("BODY_CONSUMED", "Request body was already parsed, so the signed bytes are gone. Mount this handler before any JSON body parser, or use express.raw({ type: 'application/json' }) on this route."));
 				return end(500);
-			}
-			let size = 0;
-			const chunks = [];
-			try {
-				for await (const chunk of req) {
-					const buf = Buffer.from(chunk);
-					size += buf.length;
-					if (size > 1048576) return end(413);
-					chunks.push(buf);
+			} else {
+				let size = 0;
+				const chunks = [];
+				try {
+					for await (const chunk of req) {
+						const buf = Buffer.from(chunk);
+						size += buf.length;
+						if (size > 1048576) return end(413);
+						chunks.push(buf);
+					}
+				} catch (error) {
+					options.onError?.(error);
+					return end(400);
 				}
-			} catch (error) {
-				options.onError?.(error);
-				return end(400);
+				raw = Buffer.concat(chunks);
 			}
 			let event;
 			try {
-				event = verifyWebhook(Buffer.concat(chunks), req.headers[WEBHOOK_SIGNATURE_HEADER], options.secret, verifyOptions(options));
+				event = verifyWebhook(raw, req.headers[WEBHOOK_SIGNATURE_HEADER], options.secret, verifyOptions(options));
 			} catch (error) {
 				options.onError?.(error);
 				return end(statusForError(error));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thediscordlist/discord.js",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Publish your discord.js bot's stats, heartbeat and commands to TheDiscordList automatically, and verify its webhooks.",
   "license": "MIT",
   "type": "module",