@mycroblog/mybot 0.0.0-placeholder.0

package/dist/budget.d.ts

@@ -0,0 +1,45 @@
+/** A number of events in a window of time, in milliseconds, such as 60 posts an hour. */
+export type Rate = {
+    readonly n: number;
+    readonly per: number;
+};
+/** The budget of posts, replies included: 60 an hour, six tenths of the server's 300 in three hours (ADR-0094 §6). */
+export declare const defaultPostRate: Rate;
+/** The budget of the other writes (reactions, favourites, follows): 60 a minute. */
+export declare const defaultWriteRate: Rate;
+/** The most replies to one sender: 5 in 10 minutes and 15 in an hour (ADR-0094 §8). */
+export declare const defaultReplyLimits: readonly Rate[];
+/** The longest a write waits for the send budget before it is dropped: 10 minutes. */
+export declare const defaultMaxSendWait: number;
+/** The budget a write draws on. */
+export type SendKind = "post" | "write";
+/**
+ * The client-side send budget of a bot: a token bucket for posts and one for the other writes, and the pause that the
+ * server's RateLimit fields ask for when less than a tenth of the limit remains.
+ */
+export declare class Budget {
+    #private;
+    constructor(post: Rate, write: Rate);
+    /**
+     * Reserves a send of kind at now and returns how long to wait before sending it; null, reserving nothing, when the
+     * wait would be longer than maxWait.
+     */
+    reserve(kind: SendKind, now: number, maxWait: number): number | null;
+    /**
+     * Reads the RateLimit and RateLimit-Policy fields of an answer (draft-ietf-httpapi-ratelimit-headers,
+     * `"name";r=<remaining>;t=<seconds>` and `"name";q=<quota>;w=<window>`): when less than a tenth of a policy's quota
+     * remains, the writes wait until its window resets.
+     */
+    observe(headers: Headers, now: number): void;
+}
+/** Counts the replies to each sender, for the reply limits of ADR-0094 §8. */
+export declare class ReplyLimiter {
+    #private;
+    constructor(limits: readonly Rate[]);
+    /** Whether one more reply to sender at now would go over a limit. */
+    full(sender: string, now: number): boolean;
+    /** Records a reply to sender at now; false, recording nothing, when it would go over a limit. */
+    take(sender: string, now: number): boolean;
+    /** Forgets the reply to sender recorded at at, which was not sent. */
+    untake(sender: string, at: number): void;
+}

package/dist/budget.js

@@ -0,0 +1,141 @@
+// SPDX-License-Identifier: MIT
+const minute = 60_000;
+const hour = 60 * minute;
+/** The budget of posts, replies included: 60 an hour, six tenths of the server's 300 in three hours (ADR-0094 §6). */
+export const defaultPostRate = { n: 60, per: hour };
+/** The budget of the other writes (reactions, favourites, follows): 60 a minute. */
+export const defaultWriteRate = { n: 60, per: minute };
+/** The most replies to one sender: 5 in 10 minutes and 15 in an hour (ADR-0094 §8). */
+export const defaultReplyLimits = [
+    { n: 5, per: 10 * minute },
+    { n: 15, per: hour },
+];
+/** The longest a write waits for the send budget before it is dropped: 10 minutes. */
+export const defaultMaxSendWait = 10 * minute;
+/** A token bucket that holds up to rate.n tokens and gains rate.n every rate.per. */
+class Bucket {
+    #rate;
+    #tokens;
+    #last = null;
+    constructor(rate) {
+        this.#rate = rate;
+        this.#tokens = rate.n;
+    }
+    /** Refills the bucket at now and returns how long until it holds one token. */
+    wait(now) {
+        const { n, per } = this.#rate;
+        if (n <= 0 || per <= 0)
+            return 0;
+        if (this.#last !== null)
+            this.#tokens = Math.min(n, this.#tokens + ((now - this.#last) * n) / per);
+        this.#last = now;
+        if (this.#tokens >= 1)
+            return 0;
+        return ((1 - this.#tokens) * per) / n;
+    }
+    /** Uses one token, which wait made sure of or reserved. */
+    take() {
+        if (this.#rate.n > 0 && this.#rate.per > 0)
+            this.#tokens--;
+    }
+}
+/**
+ * The client-side send budget of a bot: a token bucket for posts and one for the other writes, and the pause that the
+ * server's RateLimit fields ask for when less than a tenth of the limit remains.
+ */
+export class Budget {
+    #buckets;
+    #pause = 0;
+    constructor(post, write) {
+        this.#buckets = { post: new Bucket(post), write: new Bucket(write) };
+    }
+    /**
+     * Reserves a send of kind at now and returns how long to wait before sending it; null, reserving nothing, when the
+     * wait would be longer than maxWait.
+     */
+    reserve(kind, now, maxWait) {
+        const bucket = this.#buckets[kind];
+        const wait = Math.max(bucket.wait(now), this.#pause - now);
+        if (wait > maxWait)
+            return null;
+        bucket.take();
+        return Math.max(wait, 0);
+    }
+    /**
+     * Reads the RateLimit and RateLimit-Policy fields of an answer (draft-ietf-httpapi-ratelimit-headers,
+     * `"name";r=<remaining>;t=<seconds>` and `"name";q=<quota>;w=<window>`): when less than a tenth of a policy's quota
+     * remains, the writes wait until its window resets.
+     */
+    observe(headers, now) {
+        const limits = headers.get("RateLimit");
+        if (limits === null)
+            return;
+        const quotas = new Map();
+        for (const item of structuredItems(headers.get("RateLimit-Policy") ?? "")) {
+            const q = item.params.get("q");
+            if (q !== undefined)
+                quotas.set(item.name, q);
+        }
+        for (const item of structuredItems(limits)) {
+            const r = item.params.get("r");
+            const t = item.params.get("t");
+            const q = quotas.get(item.name);
+            if (r === undefined || t === undefined || q === undefined || q <= 0 || r * 10 >= q)
+                continue;
+            this.#pause = Math.max(this.#pause, now + t * 1000);
+        }
+    }
+}
+/** Reads the members of a list field such as `"api";r=12;t=30, "posts";r=1;t=600`, skipping the parameters that are not integers. */
+function structuredItems(value) {
+    if (value.trim() === "")
+        return [];
+    return value.split(",").map((member) => {
+        const [name = "", ...params] = member.split(";");
+        const item = { name: name.trim().replaceAll(/^"|"$/g, ""), params: new Map() };
+        for (const p of params) {
+            const eq = p.indexOf("=");
+            if (eq < 0)
+                continue;
+            const v = p.slice(eq + 1).trim();
+            if (/^-?\d+$/.test(v))
+                item.params.set(p.slice(0, eq).trim(), Number(v));
+        }
+        return item;
+    });
+}
+/** Counts the replies to each sender, for the reply limits of ADR-0094 §8. */
+export class ReplyLimiter {
+    #limits;
+    #sent = new Map();
+    constructor(limits) {
+        this.#limits = limits;
+    }
+    /** Whether one more reply to sender at now would go over a limit. */
+    full(sender, now) {
+        const longest = Math.max(0, ...this.#limits.map((r) => r.per));
+        // Drop what no window reaches any more.
+        const keep = (this.#sent.get(sender) ?? []).filter((at) => now - at < longest);
+        if (keep.length === 0)
+            this.#sent.delete(sender);
+        else
+            this.#sent.set(sender, keep);
+        return this.#limits.some((r) => r.n > 0 && r.per > 0 && keep.filter((at) => now - at < r.per).length >= r.n);
+    }
+    /** Records a reply to sender at now; false, recording nothing, when it would go over a limit. */
+    take(sender, now) {
+        if (this.full(sender, now))
+            return false;
+        this.#sent.set(sender, [...(this.#sent.get(sender) ?? []), now]);
+        return true;
+    }
+    /** Forgets the reply to sender recorded at at, which was not sent. */
+    untake(sender, at) {
+        const times = this.#sent.get(sender);
+        if (times === undefined)
+            return;
+        const i = times.lastIndexOf(at);
+        if (i >= 0)
+            times.splice(i, 1);
+    }
+}

package/dist/context.d.ts

@@ -0,0 +1,158 @@
+import type { Api, components, Sleep } from "@mycroblog/mykit";
+import type { Budget, Rate, ReplyLimiter } from "./budget.js";
+import type { Job } from "./dispatch.js";
+import { type EveryJob } from "./every.js";
+import { type Logger } from "./logger.js";
+type Notification = components["schemas"]["Notification"];
+type Status = components["schemas"]["Status"];
+type Account = components["schemas"]["Account"];
+type CredentialAccount = components["schemas"]["CredentialAccount"];
+type Visibility = components["schemas"]["Visibility"];
+/**
+ * The Idempotency-Key of the n-th reply (from 1) that a handler posts for the event source: a notification ID, or for
+ * onStatus the ID of the post (ADR-0094 §6). The server keeps the keys of each account, so the same event processed
+ * twice (after a restart in the middle of its handler) posts each reply once. Use it when posting with mykit directly:
+ *
+ * ```ts
+ * await api.POST("/statuses", { params: { header: { "Idempotency-Key": replyIdempotencyKey(id, 1) } }, body });
+ * ```
+ */
+export declare function replyIdempotencyKey(source: string, n: number): string;
+/**
+ * The visibility of a reply to a post of visibility v: never wider than v (ADR-0094 §8), and unlisted for a public
+ * post, so that a bot's replies stay out of the public timelines.
+ */
+export declare function replyVisibility(v: Visibility): Visibility;
+/** The error of reply, react, and favourite for an event without a post, such as a follow. */
+export declare class NoStatusError extends Error {
+    readonly name = "NoStatusError";
+    constructor();
+}
+/** The error of follow for an event without an account. */
+export declare class NoAccountError extends Error {
+    readonly name = "NoAccountError";
+    constructor();
+}
+/** The error of reply when the replies to the sender reached a limit of the replyLimits option. The reply was not sent. */
+export declare class ReplyLimitError extends Error {
+    readonly name = "ReplyLimitError";
+    constructor();
+}
+/** The error of a write that would have waited for the send budget longer than the maxSendWait option. It was not sent. */
+export declare class BudgetExceededError extends Error {
+    readonly name = "BudgetExceededError";
+    constructor();
+}
+/** Handles one event. What it throws is logged; the event counts as processed all the same, so that a failing event is not retried for ever. */
+export type Handler = (ctx: Context) => void | Promise<void>;
+/**
+ * Wraps the handlers, such as to check who may run a command, or to log in a format of one's own: it calls next to
+ * run the rest of the chain and the handler, or returns without calling it to skip them.
+ */
+export type Middleware = (ctx: Context, next: () => Promise<void>) => Promise<void>;
+/** The data of an answer, which mykit sets whenever the call resolves; an error when the answer has none. */
+export declare function answered<T>(data: T | undefined, operation: string): T;
+/** What the contexts of a running bot share. */
+export type Runtime = {
+    readonly me: CredentialAccount;
+    readonly api: Api;
+    readonly logger: Logger;
+    readonly now: () => number;
+    readonly sleep: Sleep;
+    readonly budget: Budget;
+    readonly replies: ReplyLimiter;
+    /** The reply limits, null when they are lifted. */
+    readonly replyLimits: readonly Rate[] | null;
+    readonly maxSendWait: number;
+    readonly respondToBots: boolean;
+};
+/** The key of the library's state of a Context, which the default middleware reads. */
+export declare const internal: unique symbol;
+/** The library's state of a Context. */
+export type ContextState = {
+    readonly runtime: Runtime;
+    /** The ID that the idempotency keys of the replies derive from. */
+    readonly source: string;
+    /** The key of the account for the reply limits and the order of processing. */
+    readonly sender: string;
+    replies: number;
+    /** The scheduled job of the run, undefined for an event. */
+    readonly every: EveryJob | undefined;
+    /** Whether the run of the scheduled job posted. */
+    posted: boolean;
+    /** Makes the helpers wait for the send budget (the sendBudget middleware). */
+    budgeted: boolean;
+};
+/**
+ * What a handler receives: the event, its post and its sender, the plain text and the command of a mention, and
+ * helpers that answer within the defaults of the library; or for a scheduled job its name and time, and post. Its
+ * signal aborts when the bot stops and the grace period is over.
+ */
+export declare class Context {
+    #private;
+    /** The notification of the event; undefined for onStatus. */
+    readonly notification: Notification | undefined;
+    /**
+     * The post of the event: the post that mentions the bot, the bot's post that was reacted to, favourited, boosted, or
+     * quoted, the quote, or the post of onStatus. Undefined for an event without one.
+     */
+    readonly status: Status | undefined;
+    /** The sender: the account that acted. Undefined for a notification without one. */
+    readonly account: Account | undefined;
+    /** The content of status as plain text (plainText), "" without a status. */
+    readonly text: string;
+    /** Whether status replies to a post. */
+    readonly isReply: boolean;
+    /** Whether status is a direct post. */
+    readonly isDirect: boolean;
+    /** The lowercase name of the command of onCommand, "" otherwise. */
+    command: string;
+    /** The text after the command's name, with the spaces around it trimmed. */
+    args: string;
+    /** The name of the scheduled job (Bot.every) that the context runs, "" for an event. */
+    readonly job: string;
+    /**
+     * The time of the run of the scheduled job, in milliseconds since the Unix epoch, which may be earlier than now for
+     * a run that catches up; undefined for an event.
+     */
+    readonly scheduledAt: number | undefined;
+    /** Aborts when the bot stops and the grace period is over; pass it to the requests of the handler. */
+    readonly signal: AbortSignal;
+    /** The library's state; not for handlers. */
+    readonly [internal]: ContextState;
+    /** A context is made by the bot for each event. */
+    constructor(runtime: Runtime, job: Job, signal: AbortSignal);
+    /** The bot's own account, as verifyCredentials returned it when the bot started. */
+    get me(): CredentialAccount;
+    /**
+     * The client of the server, for what the helpers do not cover. Writes through it skip the send budget and the reply
+     * limits: use replyIdempotencyKey for the posts.
+     */
+    get api(): Api;
+    /** The logger of the bot, with the event's attributes. */
+    get logger(): Logger;
+    /**
+     * Posts text as a reply to status. The reply mentions the sender alone, never the other accounts that the post
+     * mentions; its visibility is replyVisibility of the post's; and it carries the Idempotency-Key
+     * replyIdempotencyKey(event, n) for the n-th reply of the handler, so that processing the event again posts it once.
+     * It counts toward the reply limits of the sender and waits for the send budget.
+     */
+    reply(text: string): Promise<Status>;
+    /**
+     * Reacts to status with emoji: a Unicode emoji, or the shortcode of a custom emoji of the server. Reacting again
+     * with the same emoji changes nothing, so it needs no idempotency key. It waits for the send budget.
+     */
+    react(emoji: string): Promise<void>;
+    /** Favourites status. A second favourite changes nothing. It waits for the send budget. */
+    favourite(): Promise<void>;
+    /** Follows the sender (for a locked account, requests to). Following again changes nothing. It waits for the send budget. */
+    follow(): Promise<void>;
+    /**
+     * Posts text from the handler of a scheduled job, with the visibility of its EveryOptions and the Idempotency-Key
+     * everyIdempotencyKey(job, scheduledAt): a run posts once, even when two processes of the bot run it, or a restart
+     * runs it again. It waits for the send budget. Outside a scheduled job it throws a NotScheduledError, and a second
+     * post of a run a PostedAlreadyError.
+     */
+    post(text: string): Promise<Status>;
+}
+export {};

package/dist/context.js

@@ -0,0 +1,255 @@
+import { everyIdempotencyKey, NotScheduledError, PostedAlreadyError } from "./every.js";
+import { withAttributes } from "./logger.js";
+import { plainText } from "./text.js";
+/**
+ * The Idempotency-Key of the n-th reply (from 1) that a handler posts for the event source: a notification ID, or for
+ * onStatus the ID of the post (ADR-0094 §6). The server keeps the keys of each account, so the same event processed
+ * twice (after a restart in the middle of its handler) posts each reply once. Use it when posting with mykit directly:
+ *
+ * ```ts
+ * await api.POST("/statuses", { params: { header: { "Idempotency-Key": replyIdempotencyKey(id, 1) } }, body });
+ * ```
+ */
+export function replyIdempotencyKey(source, n) {
+    return `mybot:reply:${source}:${String(n)}`;
+}
+/**
+ * The visibility of a reply to a post of visibility v: never wider than v (ADR-0094 §8), and unlisted for a public
+ * post, so that a bot's replies stay out of the public timelines.
+ */
+export function replyVisibility(v) {
+    switch (v) {
+        case "direct":
+        case "private":
+        case "local":
+        case "unlisted":
+            return v;
+        default:
+            return "unlisted";
+    }
+}
+/** The error of reply, react, and favourite for an event without a post, such as a follow. */
+export class NoStatusError extends Error {
+    name = "NoStatusError";
+    constructor() {
+        super("mybot: the event has no post");
+    }
+}
+/** The error of follow for an event without an account. */
+export class NoAccountError extends Error {
+    name = "NoAccountError";
+    constructor() {
+        super("mybot: the event has no account");
+    }
+}
+/** The error of reply when the replies to the sender reached a limit of the replyLimits option. The reply was not sent. */
+export class ReplyLimitError extends Error {
+    name = "ReplyLimitError";
+    constructor() {
+        super("mybot: the replies to this sender reached their limit");
+    }
+}
+/** The error of a write that would have waited for the send budget longer than the maxSendWait option. It was not sent. */
+export class BudgetExceededError extends Error {
+    name = "BudgetExceededError";
+    constructor() {
+        super("mybot: the send budget is used up for longer than the longest wait");
+    }
+}
+/** The data of an answer, which mykit sets whenever the call resolves; an error when the answer has none. */
+export function answered(data, operation) {
+    if (data === undefined)
+        throw new Error(`mybot: ${operation} answered no data`);
+    return data;
+}
+/** The key of the library's state of a Context, which the default middleware reads. */
+export const internal = Symbol("mybot.internal");
+/**
+ * What a handler receives: the event, its post and its sender, the plain text and the command of a mention, and
+ * helpers that answer within the defaults of the library; or for a scheduled job its name and time, and post. Its
+ * signal aborts when the bot stops and the grace period is over.
+ */
+export class Context {
+    /** The notification of the event; undefined for onStatus. */
+    notification;
+    /**
+     * The post of the event: the post that mentions the bot, the bot's post that was reacted to, favourited, boosted, or
+     * quoted, the quote, or the post of onStatus. Undefined for an event without one.
+     */
+    status;
+    /** The sender: the account that acted. Undefined for a notification without one. */
+    account;
+    /** The content of status as plain text (plainText), "" without a status. */
+    text;
+    /** Whether status replies to a post. */
+    isReply;
+    /** Whether status is a direct post. */
+    isDirect;
+    /** The lowercase name of the command of onCommand, "" otherwise. */
+    command = "";
+    /** The text after the command's name, with the spaces around it trimmed. */
+    args = "";
+    /** The name of the scheduled job (Bot.every) that the context runs, "" for an event. */
+    job;
+    /**
+     * The time of the run of the scheduled job, in milliseconds since the Unix epoch, which may be earlier than now for
+     * a run that catches up; undefined for an event.
+     */
+    scheduledAt;
+    /** Aborts when the bot stops and the grace period is over; pass it to the requests of the handler. */
+    signal;
+    /** The library's state; not for handlers. */
+    [internal];
+    /** A context is made by the bot for each event. */
+    constructor(runtime, job, signal) {
+        this.signal = signal;
+        this.job = job.every?.name ?? "";
+        this.scheduledAt = job.every === undefined ? undefined : job.at;
+        if (job.every !== undefined) {
+            this.notification = undefined;
+            this.status = undefined;
+            this.account = undefined;
+        }
+        else if (job.notification !== undefined) {
+            this.notification = job.notification;
+            this.status = job.notification.status;
+            this.account = job.notification.account;
+        }
+        else {
+            this.notification = undefined;
+            this.status = job.status;
+            this.account = job.status.account;
+        }
+        this.text = this.status === undefined ? "" : plainText(this.status.content);
+        this.isReply = this.status?.in_reply_to_id !== undefined;
+        this.isDirect = this.status?.visibility === "direct";
+        this[internal] = {
+            runtime,
+            source: job.notification?.id ?? job.status?.id ?? "",
+            sender: job.sender,
+            replies: 0,
+            every: job.every,
+            posted: false,
+            budgeted: false,
+        };
+    }
+    /** The bot's own account, as verifyCredentials returned it when the bot started. */
+    get me() {
+        return this[internal].runtime.me;
+    }
+    /**
+     * The client of the server, for what the helpers do not cover. Writes through it skip the send budget and the reply
+     * limits: use replyIdempotencyKey for the posts.
+     */
+    get api() {
+        return this[internal].runtime.api;
+    }
+    /** The logger of the bot, with the event's attributes. */
+    get logger() {
+        const { logger } = this[internal].runtime;
+        if (this.notification !== undefined)
+            return withAttributes(logger, { notification: this.notification.id, type: this.notification.type });
+        if (this.status !== undefined)
+            return withAttributes(logger, { status: this.status.id });
+        if (this.job !== "")
+            return withAttributes(logger, { job: this.job, scheduledAt: new Date(this.scheduledAt ?? 0).toISOString() });
+        return logger;
+    }
+    /**
+     * Posts text as a reply to status. The reply mentions the sender alone, never the other accounts that the post
+     * mentions; its visibility is replyVisibility of the post's; and it carries the Idempotency-Key
+     * replyIdempotencyKey(event, n) for the n-th reply of the handler, so that processing the event again posts it once.
+     * It counts toward the reply limits of the sender and waits for the send budget.
+     */
+    async reply(text) {
+        const st = this.status;
+        if (st === undefined)
+            throw new NoStatusError();
+        const state = this[internal];
+        const { runtime } = state;
+        state.replies++;
+        const key = replyIdempotencyKey(state.source, state.replies);
+        const body = this.account !== undefined && this.account.id !== runtime.me.id ? `@${this.account.acct} ${text}` : text;
+        const limited = runtime.replyLimits !== null && this.account !== undefined;
+        const at = runtime.now();
+        if (limited && !runtime.replies.take(state.sender, at))
+            throw new ReplyLimitError();
+        try {
+            await this.#waitBudget("post");
+        }
+        catch (error) {
+            if (limited)
+                runtime.replies.untake(state.sender, at);
+            throw error;
+        }
+        const { data } = await runtime.api.POST("/statuses", {
+            params: { header: { "Idempotency-Key": key } },
+            body: { text: body, visibility: replyVisibility(st.visibility), in_reply_to_id: st.id },
+            signal: this.signal,
+        });
+        return answered(data, "createStatus");
+    }
+    /**
+     * Reacts to status with emoji: a Unicode emoji, or the shortcode of a custom emoji of the server. Reacting again
+     * with the same emoji changes nothing, so it needs no idempotency key. It waits for the send budget.
+     */
+    async react(emoji) {
+        if (this.status === undefined)
+            throw new NoStatusError();
+        await this.#waitBudget("write");
+        await this.api.PUT("/statuses/{id}/reaction", { params: { path: { id: this.status.id } }, body: { emoji }, signal: this.signal });
+    }
+    /** Favourites status. A second favourite changes nothing. It waits for the send budget. */
+    async favourite() {
+        if (this.status === undefined)
+            throw new NoStatusError();
+        await this.#waitBudget("write");
+        await this.api.POST("/statuses/{id}/favourite", { params: { path: { id: this.status.id } }, signal: this.signal });
+    }
+    /** Follows the sender (for a locked account, requests to). Following again changes nothing. It waits for the send budget. */
+    async follow() {
+        if (this.account === undefined)
+            throw new NoAccountError();
+        await this.#waitBudget("write");
+        await this.api.POST("/accounts/{id}/follow", { params: { path: { id: this.account.id } }, body: {}, signal: this.signal });
+    }
+    /**
+     * Posts text from the handler of a scheduled job, with the visibility of its EveryOptions and the Idempotency-Key
+     * everyIdempotencyKey(job, scheduledAt): a run posts once, even when two processes of the bot run it, or a restart
+     * runs it again. It waits for the send budget. Outside a scheduled job it throws a NotScheduledError, and a second
+     * post of a run a PostedAlreadyError.
+     */
+    async post(text) {
+        const state = this[internal];
+        const { every } = state;
+        if (every === undefined || this.scheduledAt === undefined)
+            throw new NotScheduledError();
+        if (state.posted)
+            throw new PostedAlreadyError();
+        await this.#waitBudget("post");
+        state.posted = true;
+        const { data } = await state.runtime.api.POST("/statuses", {
+            params: { header: { "Idempotency-Key": everyIdempotencyKey(every.name, this.scheduledAt) } },
+            body: { text, visibility: every.visibility },
+            signal: this.signal,
+        });
+        return answered(data, "createStatus");
+    }
+    /**
+     * Waits for the send budget of kind when the sendBudget middleware is in the chain. A wait longer than the
+     * maxSendWait option drops the write, logged, with a BudgetExceededError.
+     */
+    async #waitBudget(kind) {
+        const state = this[internal];
+        if (!state.budgeted)
+            return;
+        const { runtime } = state;
+        const wait = runtime.budget.reserve(kind, runtime.now(), runtime.maxSendWait);
+        if (wait === null) {
+            this.logger.warn("mybot: dropped a write that would wait too long for the send budget", { maxWait: runtime.maxSendWait });
+            throw new BudgetExceededError();
+        }
+        if (wait > 0)
+            await runtime.sleep(wait, this.signal);
+    }
+}

package/dist/dispatch.d.ts

@@ -0,0 +1,60 @@
+import type { components } from "@mycroblog/mykit";
+import type { EveryJob } from "./every.js";
+type Notification = components["schemas"]["Notification"];
+type Status = components["schemas"]["Status"];
+type Account = components["schemas"]["Account"];
+/** One job to run: a notification, a post of the home timeline, or the run at of a scheduled job. */
+export type Job = {
+    notification: Notification;
+    status?: undefined;
+    every?: undefined;
+    sender: string;
+} | {
+    notification?: undefined;
+    status: Status;
+    every?: undefined;
+    sender: string;
+} | {
+    notification?: undefined;
+    status?: undefined;
+    every: EveryJob;
+    at: number;
+    sender: string;
+};
+/** The key of the account that acted, "" for an event without one. */
+export declare function senderOf(account: Account | undefined): string;
+/**
+ * Runs the jobs: up to its limit at once, those of one sender one after the other in the order they came (ADR-0094
+ * §4). A notification that is queued or running is not queued again, so that the catch-up and the event stream may
+ * both bring it. run must not reject.
+ */
+export declare class Dispatcher {
+    #private;
+    constructor(concurrency: number, run: (job: Job) => Promise<void>);
+    /** Queues job and reports whether it did: not after stop, and not for a notification already queued. */
+    submit(job: Job): boolean;
+    /** Makes the dispatcher take no more jobs and start none of those queued. */
+    stop(): void;
+    /** Resolves when every running job has returned. */
+    idle(): Promise<void>;
+}
+/**
+ * Computes the position of the catch-up (ADR-0094 §3): the newest notification up to which every notification handed
+ * to the bot was processed. Handlers end out of order, so a processed notification moves the position only when no
+ * older one is still pending; while a catch-up hands out notifications, the position holds still, so that a restart
+ * in the middle of it reads them again. Notification IDs are UUIDv7 strings, whose order is the order of time.
+ */
+export declare class Tracker {
+    #private;
+    /** Marks the notification id pending. */
+    add(id: string): void;
+    /** Drops a pending notification that was not handed out after all. */
+    forget(id: string): void;
+    /** Marks the notification id processed and returns the new position, null when it does not move. */
+    complete(id: string): string | null;
+    /** Keeps the position where it is until release. */
+    hold(): void;
+    /** Ends a hold and returns the new position, null when it does not move. */
+    release(): string | null;
+}
+export {};