@mycroblog/mybot 0.0.0-placeholder.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The mycroblog/my contributors
+
+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,269 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# @mycroblog/mybot
+
+Build bots for [my](https://github.com/mycroblog/my), an ActivityPub microblog server, on its API client
+[`@mycroblog/mykit`](https://github.com/mycroblog/my/blob/main/pkg/mykit/ts/README.md). You write the handlers of the bot's events; the library receives the
+events so that none is lost or answered twice across disconnections and restarts, and keeps the bot polite by default.
+It is ESM only and runs on Node.js 22 or later, Bun, and Deno; it depends on `@mycroblog/mykit` and on
+[`croner`](https://github.com/hexagon/croner) (MIT, no dependencies), which computes the times of the scheduled jobs.
+
+The Go library `github.com/mycroblog/my/pkg/mybot` has the same handlers, options, defaults, idempotency keys, and
+state file; the [differences](#differences-from-the-go-library) are at the end.
+
+```sh
+npm install @mycroblog/mybot
+```
+
+## Quick start
+
+```ts
+import { Bot } from "@mycroblog/mybot";
+
+const bot = new Bot({
+  server: "https://example.com",
+  oauth: { clientId: process.env.CLIENT_ID!, clientSecret: process.env.CLIENT_SECRET! },
+  refreshToken: process.env.REFRESH_TOKEN!,
+  userAgent: "echobot/1.0",
+});
+
+bot.onCommand("ping", "answer pong", async (ctx) => {
+  await ctx.reply("pong");
+});
+bot.onMention(async (ctx) => {
+  await ctx.reply(ctx.text);
+});
+
+const controller = new AbortController();
+process.once("SIGINT", () => controller.abort());
+process.once("SIGTERM", () => controller.abort());
+await bot.run({ signal: controller.signal });
+```
+
+`bot.run` verifies the account, receives the events until the signal aborts, then shuts down gracefully and resolves.
+It rejects when the bot cannot start: `NotBotError`, `ScopeError` (with `missing`), or a `ProblemError` of the server.
+
+## Examples
+
+Each example is a `createBot` in `bot.ts`, its tests against [`@mycroblog/mybot/testing`](#testing) in `bot.test.ts`,
+and a `main.ts` that runs it; the Go library has the same examples.
+
+| Example | What it does |
+| --- | --- |
+| [`examples/echo`](https://github.com/mycroblog/my/blob/main/pkg/mybot/ts/examples/echo) | replies to every mention with its text (`onMention`) |
+| [`examples/schedule`](https://github.com/mycroblog/my/blob/main/pkg/mybot/ts/examples/schedule) | posts a greeting at 9:00 every morning in a time zone (`every` with `catchUp: "latest"`) |
+| [`examples/commands`](https://github.com/mycroblog/my/blob/main/pkg/mybot/ts/examples/commands) | answers the commands `help`, `ping`, and `dice 2d6` (`onCommand`) |
+
+The bots read `MYBOT_SERVER`, `MYBOT_CLIENT_ID`, `MYBOT_CLIENT_SECRET`, `MYBOT_REFRESH_TOKEN`, and `MYBOT_STATE` (the
+state file, `./mybot-state.json` by default) from the environment ([`examples/env.ts`](https://github.com/mycroblog/my/blob/main/pkg/mybot/ts/examples/env.ts)):
+
+```sh
+MYBOT_SERVER=https://example.com MYBOT_CLIENT_ID=... MYBOT_CLIENT_SECRET=... MYBOT_REFRESH_TOKEN=... \
+  bun examples/echo/main.ts
+```
+
+## Getting a token
+
+A bot always acts as a user: run it on an account of its own. The steps:
+
+1. Sign in to the server as the bot's account and open **Settings → Development** (`/settings/apps`).
+2. Register an app with the type **Confidential**. The form needs a redirect URI even when no redirect is used:
+   `http://127.0.0.1/callback` serves both this and the Go library's `examples/login`. Give it at least the scopes
+   below.
+3. Copy the client ID and the secret, which is shown once.
+4. Press **Issue token** on the app and choose the scopes (empty for all of the app's). The server issues an access
+   token and a refresh token for your own account, without a redirect, and shows them once.
+5. Pass the client ID and the secret as `oauth` and the refresh token as `refreshToken`. The access token is not
+   needed: the bot gets a new one with the refresh token.
+
+To authorize a bot through the consent page instead, use the Authorization Code flow with PKCE (mykit's
+`newCodeVerifier`, `codeChallenge`, and `exchange`): the Go library's
+[`examples/login`](https://github.com/mycroblog/my/blob/main/pkg/mybot/examples/login) receives the code on a loopback
+redirect and prints the refresh token, which works for a bot in either language.
+
+The scopes the default handlers need are `read:accounts`, `read:notifications`, `read:statuses` (for the event
+stream), and `write:statuses`, plus `write:accounts` with `setBotFlag`. A token without them stops the bot at start.
+
+The server rotates the refresh token on every renewal and revokes the whole token family when a used one comes back.
+The bot saves every rotated refresh token in its [store](#state) and, on the next start, uses the saved one rather than
+`refreshToken`. A `tokenSource` (such as mykit's `staticToken`) instead of `oauth` is for tests and short runs: the bot
+saves nothing for it.
+
+## Receiving the events
+
+- In the default mode `"streaming"` the bot opens the event stream (`GET /api/v1/streaming`; mykit reconnects it).
+  After every connection, the first and each reconnection, it reads the notifications newest first back to the position
+  in its store, or to `catchUpLimit` (24 hours; `0` turns the catch-up off), and handles those it missed, oldest first.
+- The catch-up covers the time the stream is closed: a stop of the bot, or a cut connection. A notification that the
+  server sends while the stream stays open but that never reaches the bot, such as one a proxy drops, is older than the
+  next one the bot processes, and the catch-up does not find it
+  ([#1291](https://github.com/mycroblog/my/issues/1291)). Behind a proxy that drops events, use `mode: "polling"`.
+- Every notification is recorded in the store after its handler returns, and one recorded before is not handled again.
+  A process that stops in the middle of a handler handles that notification again on the next start: replies carry an
+  `Idempotency-Key` derived from the notification (`replyIdempotencyKey`), so the server posts each of them once.
+- `mode: "polling"` reads the notifications every `pollInterval` (a minute) instead, for networks whose proxies do not
+  pass an event stream.
+- `onStatus` receives the new posts of the home timeline from the event stream alone: they are not caught up after a
+  disconnection or a restart, and the polling mode does not receive them.
+- Up to `concurrency` (4) handlers run at once; the events of one sender run one after the other.
+
+## Handlers
+
+| Handler | Runs for |
+| --- | --- |
+| `onMention` | a mention, replies and direct posts included (`ctx.isReply`, `ctx.isDirect`), that is no command |
+| `onCommand(name, description, h)` | a mention whose first word after the bot's own mentions is `name`, without case |
+| `onFollow` / `onFollowRequest` | `follow` / `follow_request` |
+| `onReaction` / `onFavourite` / `onBoost` / `onQuote` | the notification of the same name |
+| `onNotification` | every notification that no handler above takes |
+| `onStatus` | a new post of the home timeline (the bot's own excepted) |
+
+The context `ctx` has the `notification`, its `status` and sender `account`, `text` (the post as plain text), `command`
+and `args`, `me`, `api` (the mykit client), `logger`, and `signal`, which aborts when the bot stops. Its helpers
+`reply(text)`, `react(emoji)`, `favourite()`, and `follow()` keep the defaults below. A handler that throws is logged,
+and its notification counts as processed. `help` answers with the registered commands and their descriptions unless
+`disableHelp` is set or a command `help` is registered.
+
+Middleware is `(ctx, next) => Promise<void>`, added with `bot.use(...)` inside the default chain `recover`, `manners`,
+`sendBudget` (`noDefaultMiddleware` leaves that chain out):
+
+```ts
+bot.use(async (ctx, next) => {
+  if (ctx.command === "shutdown" && ctx.account?.acct !== "admin") return; // skip the handler
+  await next();
+});
+```
+
+The log goes to `console`, or to any `logger` with `debug`, `info`, `warn`, and `error`; each call has a message and
+an object of attributes.
+
+## Scheduled jobs
+
+`every` runs a handler at the times of a cron expression of five fields, minute hour day-of-month month day-of-week,
+in UTC or the IANA time zone `timeZone`:
+
+```ts
+bot.every(
+  "0 9 * * *",
+  async (ctx) => {
+    await ctx.post("Good morning");
+  },
+  { name: "morning", timeZone: "Asia/Tokyo" },
+);
+```
+
+- A field is `*`, a number, a range `a-b`, a step `*/n` or `a-b/n`, or a list of those; the day of the week is 0-7,
+  0 and 7 being Sunday, and a day matches when either day field does when both are other than `*`. A field of seconds,
+  the aliases such as `@daily`, the names of months and days, and `?`, `L`, `W`, and `#` throw a `ScheduleError`, so
+  that the Go library and this one take the same expressions. `parseSchedule(expr, timeZone)` gives the times without
+  a bot.
+- The times are wall-clock times of the time zone: one that a daylight saving time change skips does not run, and one
+  that the change repeats runs once.
+- `ctx.post(text)` posts once per run, with the visibility `unlisted` by default (`visibility: "public"` or `"local"`)
+  and the Idempotency-Key `mybot:every:<name>:<time in RFC 3339>` (`everyIdempotencyKey`): two processes of the bot, or
+  a restart in the middle of a run, post it once. `ctx.job` and `ctx.scheduledAt` name the run.
+- The run counts as the job's last run in the store after the handler returns. The times missed while the bot was
+  stopped are skipped by default; `catchUp: "latest"` runs the newest of them once when the bot starts (for a job that
+  never ran, its newest past time), and never a pile of them.
+- `name` (the expression by default) keys the last run and the idempotency key: keep it when the expression changes.
+
+## Manners
+
+All on by default, and each can be turned off but the first:
+
+- The bot never handles the events of its own account.
+- It does not answer accounts with the bot flag (`respondToBots: true` answers them).
+- It replies to one sender at most 5 times in 10 minutes and 15 times in an hour; the events past that are skipped
+  (`replyLimits`, or `disableReplyLimits: true`).
+- A reply is never more visible than the post it answers: `direct`, `private`, `local`, and `unlisted` keep theirs, and
+  a reply to a `public` post is `unlisted`. A `local` post reaches the accounts of the bot's server and its followers
+  alone.
+- A reply mentions its sender alone, never the other accounts of the post.
+- Writes wait for a budget of the client: 60 posts an hour and 60 other writes a minute (`postRate`, `writeRate`), and,
+  when less than a tenth of the server's rate limit remains (its `RateLimit` fields), for the limit to reset. A write
+  that would wait longer than `maxSendWait` (10 minutes) is dropped with a `BudgetExceededError` and logged.
+- The bot refuses to start on an account without the bot flag, which tells people and other servers that a program
+  posts: turn on **This is a bot** in **Settings → Profile**, or pass `setBotFlag: true` (the bot sets it, with
+  `write:accounts`) or `allowNonBot: true`. Posting from an app never sets the flag by itself.
+
+Writes through `ctx.api` skip the budget and the reply limits: give their posts an `Idempotency-Key` from
+`replyIdempotencyKey`.
+
+These are a floor: **read the rules of the server** (whether it allows bots, how often they may post) before you run
+one, and set the limits lower when they ask for it.
+
+## State
+
+The `store` keeps the processed notifications (for 7 days, `processedRetention`), the position of the catch-up, the last
+runs of the scheduled jobs, and the rotated refresh token. The default is a `FileStore` at `./mybot-state.json`: one JSON file, rewritten through a
+temporary file and a rename, readable by its owner alone, in the same format as the Go library's. `MemoryStore` is for
+tests: a restart loses the rotated refresh token, and the next start sends the used one, which revokes the token. A bot
+that runs all the time, or is started again and again, needs a `FileStore` or a `Store` of its own (such as in a
+database). Run one process per bot: the store takes no lock.
+
+## Shutting down
+
+When the signal aborts, the bot closes the event stream, takes no new events, and waits `shutdownGrace` (10 seconds) for
+the running handlers. Then it aborts `ctx.signal` of those still running; their notifications stay unprocessed and are
+handled again by the next start (without posting twice, through the idempotency keys). Give a container longer than
+the grace period to stop: `docker stop` waits 10 seconds by default, so use `docker stop -t 30`.
+
+## Running once
+
+`bot.runOnce({ signal })` catches up the notifications since the store's position (back to `catchUpLimit`), runs each
+scheduled job's newest past time after its last run, whatever its `catchUp`, waits for the handlers, and resolves: for a
+bot that cron or a job runner such as Cloud Run jobs starts again and again. Such a bot needs a store that outlives the
+process.
+
+## Testing
+
+`@mycroblog/mybot/testing` tests a bot without a server. `Server` is a fake server of the client API behind a `fetch`
+that answers the operations that the bot calls with the types of the API; `options()` gives a bot its `fetch`, a token,
+a `MemoryStore`, and the server's `Clock`, which moves only when the test moves it:
+
+```ts
+import { Bot } from "@mycroblog/mybot";
+import { Server } from "@mycroblog/mybot/testing";
+
+const srv = new Server();
+const bot = new Bot(srv.options());
+bot.onCommand("ping", "answer pong", async (ctx) => {
+  await ctx.reply("pong");
+});
+const controller = new AbortController();
+const done = bot.run({ signal: controller.signal });
+srv.inject(srv.mention(srv.account("alice"), "ping", "public"));
+const [post] = await srv.waitPosted(1); // post.request.text is "@alice pong"
+controller.abort();
+await done;
+```
+
+- `inject` sends a notification on the event stream; `injectMissed` adds one that only the catch-up finds;
+  `dropStreams`, `disconnect`, and `reconnect` cut the stream.
+- `posted()`, `reactions()`, `favourites()`, and `follows()` return what the bot did; like the server, it posts once
+  per Idempotency-Key.
+- `clock.waitForSleepers(n)` waits for the scheduled jobs (and the pruning of the store) to sleep, and
+  `clock.advance(ms)` or `clock.set(at)` moves them on. The clock starts at the current time; a test of fixed times
+  starts it before them with `new Server({ now: Date.parse("2026-10-25T08:59:00Z") })`, since `clock.set` cannot move
+  it back, so that the test runs the same on any day.
+
+## Runtimes
+
+The package uses `fetch`, web streams, and `AbortSignal`. `FileStore` loads `node:fs/promises` on first use, which
+Node.js, Bun, and Deno provide; on Deno, run the bot with `--allow-net` and with `--allow-read` and `--allow-write` for
+the state file. With another `Store`, nothing of `node:` is loaded.
+
+## Differences from the Go library
+
+- Durations are milliseconds, and times in the `Store` are milliseconds since the Unix epoch.
+- A missing value of the `Store` is `null` (the Go library uses `""` and the zero time).
+- Handlers throw instead of returning an error; the errors are classes (`NotBotError`, `ScopeError`,
+  `ReplyLimitError`, `BudgetExceededError`, `NoStatusError`, `NoAccountError`, `AlreadyRunningError`).
+- Middleware is `(ctx, next) => Promise<void>` rather than a function that wraps a handler, and `ctx.signal` replaces
+  the `context.Context` of the handler.
+- The scopes of a token are checked when they are known: for `oauth`, from the renewal; a `tokenSource` is not checked.
+- `User-Agent` ends with `mybot-ts`.
+- `catchUp` is `"skip"` or `"latest"`, and `ctx.scheduledAt` is `undefined` for an event.
+- The clock is the options `now` and `sleep` rather than a `Clock` interface.
+- The fake server of `@mycroblog/mybot/testing` is a `fetch` rather than an HTTP server, and its waits take a signal
+  (10 seconds by default) rather than a `context.Context`.

package/dist/bot.d.ts

@@ -0,0 +1,199 @@
+import { type OAuthConfig, type Sleep, type TokenSource } from "@mycroblog/mykit";
+import { type Rate } from "./budget.js";
+import { type Handler, type Middleware } from "./context.js";
+import type { EveryOptions } from "./every.js";
+import { type Command } from "./handler.js";
+import type { Logger } from "./logger.js";
+import type { Store } from "./store.js";
+/**
+ * How a bot receives its notifications: "streaming", the default, from the event stream (GET /streaming), catching up
+ * with the notifications after every connection; "polling" by reading the notifications every pollInterval, for
+ * networks whose proxies do not pass an event stream.
+ */
+export type Mode = "streaming" | "polling";
+/** The interval of the polling mode: a minute. */
+export declare const defaultPollInterval = 60000;
+/** How old a notification the catch-up still handles: 24 hours. */
+export declare const defaultCatchUpLimit: number;
+/** How long the processed notifications are remembered: 7 days, longer than the catch-up limit. */
+export declare const defaultProcessedRetention: number;
+/** How many handlers run at once. */
+export declare const defaultConcurrency = 4;
+/** How long the shutdown waits for the running handlers: 10 seconds. */
+export declare const defaultShutdownGrace = 10000;
+/** Configures a bot. Every option but server and the token has a default. Durations are in milliseconds. */
+export type BotOptions = {
+    /** The origin of the server, such as "https://example.com". */
+    server: string;
+    /** Sends the requests; the global `fetch` by default. */
+    fetch?: (input: Request) => Promise<Response>;
+    /**
+     * oauth and refreshToken make the bot renew its access token with the refresh token (mykit's RefreshingTokenSource;
+     * ADR-0094 §7): the token that the server issued to the bot's own account for an app registered on its settings
+     * page, or that an authorization code was exchanged for. Every renewal rotates the refresh token, which the bot
+     * saves in the store; when the store holds one, the bot starts from it rather than from refreshToken, which the
+     * server has seen used. The server of oauth is that of the bot when absent.
+     */
+    oauth?: Omit<OAuthConfig, "server"> & {
+        server?: string;
+    };
+    refreshToken?: string;
+    /**
+     * Gives the access token when oauth is absent: mykit's staticToken for tests and short runs, or a source of one's
+     * own. The bot does not save its tokens.
+     */
+    tokenSource?: TokenSource;
+    /** Keeps the state of the bot across restarts; a FileStore at defaultStatePath by default. */
+    store?: Store;
+    /** Receives the log of the bot; `console` by default. */
+    logger?: Logger;
+    /** The product of the bot, such as "echobot/1.0", sent before the library's own in User-Agent. */
+    userAgent?: string;
+    /** Sent as Accept-Language, for the language of the server's problems. */
+    acceptLanguage?: string;
+    /** "streaming" (the default) or "polling". */
+    mode?: Mode;
+    /** The interval of the polling mode; defaultPollInterval when absent. */
+    pollInterval?: number;
+    /**
+     * How old a notification the catch-up still handles: after a long stop, older ones are skipped. Absent means
+     * defaultCatchUpLimit; 0 turns the catch-up off (ADR-0094 §3).
+     */
+    catchUpLimit?: number;
+    /** How long the processed notifications are remembered, longer than catchUpLimit; defaultProcessedRetention when absent. */
+    processedRetention?: number;
+    /** How many handlers run at once; the events of one sender run one after the other. defaultConcurrency when absent. */
+    concurrency?: number;
+    /**
+     * How long run waits for the running handlers when it stops; then it aborts their signals, and their events are
+     * handled again by the next start. defaultShutdownGrace when absent.
+     */
+    shutdownGrace?: number;
+    /** Turns the bot flag of the account on when it is off (with the scope write:accounts), instead of failing to start. */
+    setBotFlag?: boolean;
+    /**
+     * Runs the bot on an account without the bot flag. By default the bot refuses to start there, since the flag is
+     * what tells people and other servers that a program posts.
+     */
+    allowNonBot?: boolean;
+    /** Hands the events of accounts with the bot flag to the handlers, which by default skip them. */
+    respondToBots?: boolean;
+    /** The most replies to one sender, each a number in a window; defaultReplyLimits when absent. */
+    replyLimits?: readonly Rate[];
+    /** Lifts the reply limits. */
+    disableReplyLimits?: boolean;
+    /** The send budget of the posts; defaultPostRate when absent. */
+    postRate?: Rate;
+    /** The send budget of the other writes; defaultWriteRate when absent. */
+    writeRate?: Rate;
+    /** The longest a write waits for the send budget; a longer wait drops it. defaultMaxSendWait when absent. */
+    maxSendWait?: number;
+    /** Turns off the answer of the command help. */
+    disableHelp?: boolean;
+    /** Formats the answer of help; defaultHelp when absent. */
+    help?: (commands: readonly Command[]) => string;
+    /** Leaves defaultMiddleware out of the chain, for a bot that builds its own with use. */
+    noDefaultMiddleware?: boolean;
+    /**
+     * The clock, in milliseconds since the Unix epoch, of the scheduled jobs, the send budget, and the reply limits; for
+     * tests, such as the Clock of @mycroblog/mybot/testing.
+     */
+    now?: () => number;
+    /** Waits for the scheduled jobs, the send budget, the pruning of the store, and between polls; for tests. */
+    sleep?: Sleep;
+};
+/** The error of run on an account without the bot flag, unless the setBotFlag or allowNonBot option. */
+export declare class NotBotError extends Error {
+    readonly name = "NotBotError";
+    constructor();
+}
+/** The error of a second run of a bot. */
+export declare class AlreadyRunningError extends Error {
+    readonly name = "AlreadyRunningError";
+    constructor();
+}
+/** The error of run when the access token lacks scopes that the bot needs. */
+export declare class ScopeError extends Error {
+    readonly name = "ScopeError";
+    /** The scopes the token lacks. */
+    readonly missing: readonly string[];
+    constructor(missing: readonly string[]);
+}
+/** The scopes of need that granted (space-separated) does not give. */
+export declare function missingScopes(granted: string, need: readonly string[]): string[];
+/**
+ * A bot: the handlers of its events, and run, which receives the events and hands them to the handlers until it
+ * stops. Register the handlers before run.
+ */
+export declare class Bot {
+    #private;
+    /** The store of the bot. */
+    readonly store: Store;
+    constructor(options: BotOptions);
+    /** Registers the handler of the mentions of the bot, replies and direct posts included, that are no registered command. */
+    onMention(handler: Handler): void;
+    /**
+     * Registers the handler of the mentions whose first word, after the mentions of the bot at their start, is name,
+     * compared without case: `@bot ping` runs the command ping, whose Context has command "ping" and args the rest of
+     * the text. description is the command's line in the answer of help, which the bot gives unless the disableHelp
+     * option is set or a command help is registered.
+     */
+    onCommand(name: string, description: string, handler: Handler): void;
+    /** Registers the handler of new followers. */
+    onFollow(handler: Handler): void;
+    /** Registers the handler of the follow requests to a locked bot account. */
+    onFollowRequest(handler: Handler): void;
+    /** Registers the handler of the emoji reactions to the bot's posts. */
+    onReaction(handler: Handler): void;
+    /** Registers the handler of the favourites of the bot's posts. */
+    onFavourite(handler: Handler): void;
+    /** Registers the handler of the boosts of the bot's posts. */
+    onBoost(handler: Handler): void;
+    /** Registers the handler of the quotes of the bot's posts. */
+    onQuote(handler: Handler): void;
+    /** Registers the handler of every notification that no handler above takes, the types without a handler of their own among them. */
+    onNotification(handler: Handler): void;
+    /**
+     * Registers the handler of the new posts of the home timeline, from the event stream alone: they are not caught up
+     * after a disconnection or a restart, and the polling mode does not receive them. The bot's own posts are left out.
+     */
+    onStatus(handler: Handler): void;
+    /**
+     * Registers a scheduled job: handler runs at each time of the cron expression expr, of the five fields minute hour
+     * day-of-month month day-of-week (parseSchedule), in options.timeZone (UTC by default). Its Context carries job and
+     * scheduledAt, and post posts with the Idempotency-Key everyIdempotencyKey. The run counts in the store as the job's
+     * last run after the handler returns. It throws for an expression or a time zone it does not take (ScheduleError),
+     * a visibility other than unlisted, public, and local, and a name that another job has.
+     */
+    every(expr: string, handler: Handler, options?: EveryOptions): void;
+    /** Adds middleware inside the default chain, in the order given. */
+    use(...middleware: Middleware[]): void;
+    /** The registered commands, by name, with help when the bot answers it. */
+    commands(): Command[];
+    /**
+     * Starts the bot and handles its events until signal aborts, then shuts down gracefully: it stops receiving, waits
+     * for the running handlers for the shutdownGrace option, aborts the signals of those still running, whose events
+     * stay unprocessed for the next start, and resolves. It rejects when the bot cannot start (NotBotError, ScopeError,
+     * a ProblemError of verifyCredentials) or when the server refuses the event stream for good, such as for a revoked
+     * token.
+     *
+     * It verifies the account, then receives the notifications: in the streaming mode from the event stream, catching
+     * up with listNotifications back to the store's position after every connection; in the polling mode by reading
+     * them every pollInterval. Each notification is handled once: it counts as processed, in the store, after its
+     * handler returns, and one that the store knows is skipped.
+     */
+    run({ signal }?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Starts the bot, handles once what is due, and resolves, for a bot that a cron or a job runner such as Cloud Run
+     * jobs starts again and again (ADR-0094 §9): the notifications since the store's position, back to the catchUpLimit
+     * option, and for each scheduled job the newest of its past times after its last run, whatever its catchUp. It
+     * resolves when their handlers have returned. When signal aborts first, it shuts down as run does, and what did not
+     * finish is due again on the next run. It rejects with the errors of starting that run rejects with, and with that
+     * of reading the notifications.
+     */
+    runOnce({ signal }?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+}