aurival 0.6.0 → 0.8.0

package/README.md

@@ -435,6 +435,151 @@ is single-use, and acking one a second time doesn't throw locally, the server 40
 The full set of showcase examples (trivia, giveaways, DJ bots, moderation reports…) is in the
 [cookbook](https://bots.aurival.com/docs/cookbook).
 
+## Buttons only the caller can press
+
+By default nobody is locked: any member in the chat can press a card's buttons, exactly as
+before this existed. Pass `forUser` to `reply`, `send`, `edit` or `ack` to lock the press to one
+member.
+
+```ts
+await ctx.reply('Question 1 of 5', { buttons, forUser: ctx.sender });
+```
+
+`forUser` takes a `User` (`ctx.sender` is one) or a bare `usr_…` id string. Either one
+serializes to the same id on the wire.
+
+Everyone still sees the card and its text. Only the press is gated: a non-caller's buttons
+render at `.56` opacity with no checkmark, are not tappable, and the app shows a `For {name}`
+hint under the row. A link button on a locked card stays pressable by anyone. It never
+round-trips to the server, so there is nothing for the lock to gate.
+
+A non-caller who presses anyway is refused by the server with a `403`, before anything is
+spent. `used` stays unset and the card is unchanged. That refusal never reaches your bot: a bot
+never presses a button, so there is no SDK exception for it.
+
+Omitting `forUser` on a `reply`/`edit`/`ack` that replaces a card **keeps the existing lock**.
+Passing `forUser: null` **clears** it, and the card opens to everyone. Passing a new id **moves**
+the lock to that member. This matters most on `ack`, where a quiz redraws its own card between
+questions and must not silently unlock itself by leaving `forUser` out.
+
+A caller-only quiz, start to finish:
+
+```ts
+import { Button } from 'aurival';
+
+bot.command('quiz', async (ctx) => {
+  await ctx.reply('Which planet is largest?', {
+    buttons: [
+      new Button({ label: 'Mars', style: 'secondary' }),
+      new Button({ label: 'Jupiter', style: 'secondary' }),
+    ],
+    forUser: ctx.sender,
+  });
+});
+
+bot.on('button.pressed', async (ctx) => {
+  const correct = ctx.button === 'jupiter';
+  const text = correct
+    ? 'Correct. Jupiter is about eleven Earths across.'
+    : 'Not quite. Jupiter is about eleven Earths across.';
+  await ctx.ack({ text, buttons: [] });
+});
+```
+
+`ButtonContext` carries no `forUser` field. The presser is always the locked user by
+construction: the server refuses everyone else before your handler ever runs, so there is
+nothing on the press for it to expose. If you need the lock on a card you are acking, you
+already have it: you set it on the send.
+
+## Cooldowns
+
+A cooldown paces a command or a button. You attach it, the SDK keeps the bucket, and the wire
+never carries it — the server does not know one exists.
+
+```ts
+import { Bot, Cooldown } from 'aurival';
+
+const bot = new Bot();                      // buttonCooldown: Cooldown(1, 2) already
+
+bot.command('roll', { cooldown: { rate: 1, per: 5 } }, async (ctx) => { /* … */ });
+bot.command('leaderboard', { cooldown: new Cooldown(3, 60, 'chat') }, async (ctx) => { /* … */ });
+```
+
+**`per` is seconds, not milliseconds.** That is deliberate and it is the one place this SDK
+departs from JS habit: `AurivalAPIError.retryAfter` is already seconds, and a developer who
+catches one and a developer who writes a cooldown should not hold two meanings of one number.
+
+The options object is a third form of `command()`. The two you already use —
+`command(name, handler)` and `command(name, description, handler)` — are untouched, and
+`description` is a field on the options object when you want all three.
+
+Three buckets, and each one says who shares the limit:
+
+| bucket             | key                            | reads as                                        |
+| ------------------ | ------------------------------ | ----------------------------------------------- |
+| `user` (default)   | the invoking or pressing user  | each person gets one every N seconds            |
+| `chat`             | the conversation               | this chat gets one every N seconds, whoever asks |
+| `global`           | nothing                        | this bot answers one every N seconds, everywhere |
+
+A command that is refused never reaches your handler, and a refusal spends nothing — the token
+is taken only when the call passes.
+
+### What the member sees
+
+One plain reply per bucket per window, then silence for the rest of it. Somebody who types
+`/roll` eight times in five seconds gets one sentence, not eight:
+
+```
+Slow down. Try /roll again in 3 s.
+```
+
+Replace it, or suppress it, with a hook. A registered hook owns the whole response: the SDK
+sends nothing and the hook either replies or stays quiet. There is no return value to get right.
+
+```ts
+bot.onCooldown(async (ctx, retryAfter) => {          // bot-level
+  await ctx.reply(`easy, ${Math.ceil(retryAfter)}s`);
+});
+
+bot.command('roll', { cooldown: { rate: 1, per: 5 }, onCooldown }, handler); // this one wins
+```
+
+`retryAfter` is seconds remaining, unrounded. The hook is called once per bucket per window too,
+so replacing the sentence does not re-introduce the spam it existed to stop.
+
+### Buttons already have one
+
+Every bot ships with `Cooldown(1, 2, 'user')` on its buttons, without asking: one press every two
+seconds per person, one bucket per person per bot. A press inside the window is answered rather
+than handled — the presser's pending ink clears and their device shows a toast — and the button
+stays live, because a cooldown is a wait, not a spend.
+
+Override it where it belongs, and precedence is button, then card, then the bot default:
+
+```ts
+const bot = new Bot({ buttonCooldown: { rate: 1, per: 5 } }); // this bot's buttons
+await ctx.reply({ buttons, buttonCooldown: null });           // this card's buttons, off
+new Button({ label: 'Paint', cooldown: null });               // this one button, off
+```
+
+A per-card or per-button cooldown gets its own buckets, keyed on the message, the button id and
+the bucket subject — button ids are unique within a message and nowhere else, so two cards that
+both call a button `roll` never share a limit. `null` disables at any level.
+
+A button cooldown is at most 60 seconds and is refused where you write it, not later inside an
+ack you cannot see. Command cooldowns have no cap: `{ rate: 1, per: 3600 }` on a command is a
+legitimate once an hour.
+
+Link buttons are outside all of this — a link opens on the device and never round-trips, so it
+cannot carry a cooldown and `Button.link` has no `cooldown` field.
+
+### The caveat, said plainly
+
+**Buckets are process memory.** They reset on restart, and they are not shared between
+instances: a bot running two processes has two independent buckets, and a deploy clears every
+bucket it had. Cooldowns pace a conversation. They are not a quota, and they are not the abuse
+bound — the server keeps its own floor underneath them.
+
 ## Upgrading from 0.2.x
 
 There is one `Context` per event family now, instead of one class for every event with most of
@@ -561,6 +706,27 @@ await ctx.edit(sent, { embeds: [new Embed({ title: 'Starting in 3…' })] });
 await ctx.edit(sent, { buttons: [] });   // the row is gone, the plate stays
 ```
 
+### Upgrading from 0.6.x
+
+0.7.0 adds cooldowns and takes nothing away. `Cooldown` is a new export, `command()` gained a
+third options form, `Bot` gained `buttonCooldown`, `reply()`/`send()` gained `buttonCooldown`,
+and `Button` gained `cooldown`. Every one of them has a default that keeps 0.6.0 behaviour, with
+**one exception you should know about**: buttons now carry `Cooldown(1, 2, 'user')` by default,
+so a member cannot press the same bot's buttons faster than once every two seconds. That is
+deliberate and it is on by default. If your bot's buttons are something a member is meant to
+mash, turn it off explicitly:
+
+```ts
+const bot = new Bot({ buttonCooldown: null });
+```
+
+Both existing `command()` overloads keep their exact signatures, so no call you have written
+changes shape.
+
+Two new error classes ship with it, `CooldownWithBody` and `CooldownRetryAfterInvalid`, both
+`InvalidRequestError`. You will not normally see either: the SDK builds the cooldown ack itself
+and refuses an out-of-range button cooldown where you write it.
+
 ## Shadowed commands
 
 A bot can declare up to 50 commands, the SDK refuses to connect past that.
@@ -576,6 +742,42 @@ aurival warn: /ping is shadowed by another bot in chat_01j…, so it will not re
 Rename the command, or get the other bot out of that chat. Nothing else in the SDK reacts
 to it — a shadowed command in one chat is still live in every other.
 
+## Command aliases
+
+`aliases` on `bot.command(...)` gives one command several spellings, all handled by the same
+function. `/roll` and `/r` fire the same handler, share the same cooldown bucket, and are one
+command everywhere the server or the app talks about it.
+
+```ts
+bot.command('roll', { description: 'Roll dice', aliases: ['r'] }, async (ctx) => {
+  await ctx.reply(`/${ctx.invokedAs} ran ${ctx.command}, dice rolled`);
+});
+```
+
+`ctx.command` is always the canonical name, `'roll'`, whichever spelling fired the handler.
+`ctx.invokedAs` is the token the human actually typed, lowercased: `'roll'` or `'r'`. They are
+equal on a canonical call. Code that checks `ctx.command === 'roll'` keeps working no matter
+which spelling reached it.
+
+The options object also takes `cooldown`, same as any other command. It is one bucket, keyed on
+the canonical name, shared across every spelling:
+
+```ts
+bot.command('roll', { description: 'Roll dice', aliases: ['r'], cooldown: { rate: 1, per: 5 } }, handler);
+```
+
+At most three aliases per command. A fourth throws locally, before anything is synced. It is the
+same validation path as a bad command name: lowercase letters, digits, hyphens and underscores
+only, and none of the reserved names (`help`, `report`, `block`, `mute`, `kick`, `ban`, `admin`,
+`staff`, `support`, `aurival`).
+
+The cooldown notice echoes the typed token: hit the limit through `/r` and you get `Slow down.
+Try /r again in 3 s.`, never `/roll`.
+
+In the app, the command picker lists a command's aliases as a muted secondary line under its
+row: `also /r`. Picking a row that matched by alias fills that alias, not the canonical
+spelling: typing `/r` and picking the row inserts `/r `, not `/roll `.
+
 ## Environment
 
 | variable           | what it does                                                                                                                                              |

package/dist/bot.d.ts

@@ -5,8 +5,20 @@ import { Context, Event } from './events.js';
 import { HttpClient } from './http.js';
 import type { AnyContext, BotContext, BotEventType, ButtonContext, ButtonEventType, EventContext, MemberContext, MemberEventType, ReactionContext, ReactionEventType } from './events.js';
 import type { Logger } from './http.js';
+import type { CooldownLike, CooldownOption } from './cooldown.js';
 /** A `bot.command()` handler. */
 export type Handler = (ctx: Context) => Promise<void> | void;
+/**
+ * A per-command or bot-level cooldown hook (AMENDMENT-08 §4). `retryAfter`
+ * is the raw, unrounded seconds `Cooldown.check()` returned — round it
+ * yourself (`Math.max(1, Math.ceil(retryAfter))`, §5's rule) to reproduce
+ * the built-in sentence's `{n}`. Replaces the built-in "Slow down…" notice
+ * entirely: a hook that does nothing suppresses the notice, a hook that
+ * replies sends whatever it wants instead. Gated by the same once-per-window
+ * ledger as the built-in notice — a hook runs once per bucket per window,
+ * not on every refused call.
+ */
+export type OnCooldownHook = (ctx: Context, retryAfter: number) => Promise<void> | void;
 /** A `member.joined` / `member.left` handler. */
 export type MemberHandler = (ctx: MemberContext) => Promise<void> | void;
 /** A `bot.added` / `bot.removed` handler. */
@@ -40,6 +52,45 @@ export interface BotOptions {
      * keeps typing entirely in your hands (`ctx.withTyping()`). Default `true`.
      */
     autoTyping?: boolean | undefined;
+    /**
+     * The default cooldown a button press checks when neither its card nor
+     * the button itself carries one (AMENDMENT-08 §3). Defaults to `new
+     * Cooldown(1, 2.0, 'user')` — one press per user per two seconds — when
+     * omitted; pass `null` to disable it bot-wide, leaving only card/button
+     * cooldowns (if any) in effect. Bound by the same 60s cap as every other
+     * button-family cooldown, checked at construction. **Its bucket lives in
+     * process memory: it resets on every restart, and it is never shared
+     * across instances or processes** — a bot running two workers has two
+     * independent buckets (see {@link Cooldown}'s own doc comment for why).
+     */
+    buttonCooldown?: CooldownOption | undefined;
+}
+/**
+ * A command's third form: `bot.command(name, { cooldown, onCooldown,
+ * description }, handler)`. `description` here is equivalent to the
+ * two-argument string overload's — the options object is a third spelling
+ * of the same call, not a different feature (R-9's two string overloads are
+ * unchanged; this is additive). `cooldown` accepts a `Cooldown` instance or
+ * a plain `{ rate, per, bucket? }` literal, normalized at registration.
+ * Command cooldowns have no 60s cap (D13) — they never reach the wire.
+ */
+export interface CommandOptions {
+    description?: string | undefined;
+    cooldown?: CooldownLike | undefined;
+    onCooldown?: OnCooldownHook | undefined;
+    /**
+     * AMENDMENT-09 §2.1: alternate spellings that fire this same handler —
+     * `/r` and `/dice` for a command registered as `roll`, say. At most
+     * {@link MAX_ALIASES_PER_COMMAND}, checked locally at registration; every
+     * other rule an alias obeys (the name pattern, the reserved list,
+     * uniqueness) is the server's alone (§2.1) — this SDK reuses
+     * `invalid_command_name` for those exactly as the server does, by simply
+     * not re-validating them here and letting the sync refusal surface.
+     * Dispatch, the cooldown bucket and `onCooldown` all stay keyed on the
+     * canonical name; an alias only ever changes which typed token reaches
+     * that same handler (`ctx.invokedAs`, `Context`).
+     */
+    aliases?: readonly string[] | undefined;
 }
 /**
  * How long a command handler runs before the chat is told the bot is thinking
@@ -59,6 +110,17 @@ export declare function ensurePaired(http: HttpClient, keyFile: KeyFile, host: s
     machine: Machine;
     paired: boolean;
 }>;
+/**
+ * One `PUT /v1/bots/{bot}/commands` row. `aliases` is optional and, when
+ * present, always non-empty — the caller omits the key entirely for a
+ * command with no aliases (AMENDMENT-09 §2.1: absent and `[]` mean the same
+ * thing, so there is no reason to send the empty spelling).
+ */
+export interface SyncPayloadEntry {
+    name: string;
+    description: string;
+    aliases?: string[];
+}
 /**
  * The one door to command sync, so the lane that syncs is always the lane that
  * reports. Both `Bot` call sites go through here.
@@ -66,10 +128,7 @@ export declare function ensurePaired(http: HttpClient, keyFile: KeyFile, host: s
  * Exported for the tests, not from `index.ts` — the package's export list
  * mirrors Python's `__all__` (SDK-7) and this is not on it.
  */
-export declare function syncCommandsAndReport(http: HttpClient, bot: string, payload: Array<{
-    name: string;
-    description: string;
-}>, log: Logger): Promise<void>;
+export declare function syncCommandsAndReport(http: HttpClient, bot: string, payload: SyncPayloadEntry[], log: Logger): Promise<void>;
 /**
  * One warning line per shadowed chat (S11). Silently dropping `conflicts` is
  * the silence the field exists to end: the developer whose command never fires.
@@ -93,6 +152,13 @@ export declare class Bot {
      */
     command(name: string, handler: Handler): void;
     command(name: string, description: string, handler: Handler): void;
+    /**
+     * The options form (AMENDMENT-08 §4/seat ruling): a per-command cooldown
+     * is an option here, not a decorator. `{ cooldown, onCooldown }` beats
+     * `bot.onCooldown()` for this command alone — only one hook ever runs for
+     * a given refusal.
+     */
+    command(name: string, options: CommandOptions, handler: Handler): void;
     /**
      * Register a handler for an event. Which context the handler gets follows
      * from the type, and your editor knows it (BA-R68):
@@ -127,6 +193,12 @@ export declare class Bot {
      * handler that threw, a `problem` frame, a backlog overflow.
      */
     onError(fn: ErrorHook): void;
+    /**
+     * The bot-level cooldown hook (AMENDMENT-08 §4) — runs for any refused
+     * command that does not carry its own `onCooldown` option. A per-command
+     * hook always wins; only one hook ever runs for a given refusal.
+     */
+    onCooldown(fn: OnCooldownHook): void;
     /** Installs signal handlers and runs until SIGINT/SIGTERM or something fatal. */
     run(): Promise<void>;
     start(signal?: AbortSignal): Promise<void>;

package/dist/bot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bot.d.ts","sourceRoot":"","sources":["../src/bot.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF,OAAO,EAAQ,OAAO,EAAmC,MAAM,WAAW,CAAC;AAC3E,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAErD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAc,MAAM,aAAa,CAAC;AACzD,OAAO,EAAgB,UAAU,EAAiB,MAAM,WAAW,CAAC;AACpE,OAAO,KAAK,EACV,UAAU,EACV,UAAU,EACV,YAAY,EACZ,aAAa,EACb,eAAe,EAEf,YAAY,EACZ,aAAa,EACb,eAAe,EACf,eAAe,EACf,iBAAiB,EAClB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAiBxC,iCAAiC;AACjC,MAAM,MAAM,OAAO,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAC7D,iDAAiD;AACjD,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AACzE,6CAA6C;AAC7C,MAAM,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AACnE,kCAAkC;AAClC,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAC7E,kCAAkC;AAClC,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AACzE,iFAAiF;AACjF,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAGvE;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,KAAK,CAAC;AACzC,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,GAAG,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAE5F,oFAAoF;AACpF,eAAO,MAAM,iBAAiB,QAAS,CAAC;AAMxC,eAAO,MAAM,YAAY,KAAK,CAAC;AAE/B,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,2FAA2F;IAC3F,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAClC;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAoBxC;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC;IAAE,GAAG,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC,CAYjE;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,EACrD,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAcpF;AAED;;;;;GAKG;AACH,qBAAa,GAAG;;IAoBd,YAAY,OAAO,GAAE,UAAe,EAMnC;IAID;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9C,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAUnE;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;IACxD,EAAE,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;IAClD,EAAE,CAAC,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI,CAAC;IAC5D,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;IAGxD,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,EAAE,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI,CAAC;IAWnD;;;OAGG;IACH,OAAO,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI,CAE3B;IAID,iFAAiF;IAC3E,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAuBzB;IAEK,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CA6C/C;CAwMF"}
+{"version":3,"file":"bot.d.ts","sourceRoot":"","sources":["../src/bot.ts"],"names":[],"mappings":"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"}

package/dist/bot.js

@@ -1,8 +1,10 @@
 /** The developer-facing surface: declare commands, call run(), we hold the socket. */
 import { Auth, KeyFile, machineLabel, pair, resolveHost } from './auth.js';
-import { AurivalError, BotSuspended, RateLimitError, SessionSuperseded } from './errors.js';
+import { AurivalError, BotSuspended, ButtonAlreadyUsed, NotFound, RateLimitError, SessionSuperseded } from './errors.js';
 import { Context, Event, contextFor } from './events.js';
 import { DEFAULT_HOST, HttpClient, defaultLogger } from './http.js';
+import { CAP_TOO_MANY_ALIASES, MAX_ALIASES_PER_COMMAND, commandCooldownNotice } from './caps.js';
+import { Cooldown, buttonBucketKey, normalizeCooldownOption, resolveButtonCooldown, retryAfterMs, roundSeconds, subjectKey, } from './cooldown.js';
 import { EVENT_BACKLOG_OVERFLOWED, EVENT_COMMAND_INVOKED, Socket } from './socket.js';
 import * as status from './status.js';
 /** Types `on()` refuses, and why — each is a STRUCTURAL case where a
@@ -118,22 +120,57 @@ export class Bot {
     #http = null;
     #quiet;
     #autoTyping;
+    #buttonCooldown;
+    #cooldownHook = null;
     constructor(options = {}) {
         this.#log = options.logger ?? defaultLogger();
         this.#host = options.host;
         this.#keyPath = options.keyPath;
         this.#quiet = status.isQuiet(options.quiet);
         this.#autoTyping = options.autoTyping ?? true;
+        const resolvedButtonCooldown = normalizeCooldownOption(options.buttonCooldown, {
+            boundToButton: true,
+        });
+        this.#buttonCooldown =
+            resolvedButtonCooldown === undefined ? new Cooldown(1, 2.0, 'user') : resolvedButtonCooldown;
     }
     command(name, second, third) {
-        const description = typeof second === 'string' ? second : '';
-        const handler = typeof second === 'string' ? third : second;
+        let description = '';
+        let handler;
+        let cooldownLike;
+        let onCooldownHook;
+        let aliasesLike;
+        if (typeof second === 'string') {
+            description = second;
+            handler = third;
+        }
+        else if (typeof second === 'function') {
+            handler = second;
+        }
+        else {
+            description = second.description ?? '';
+            cooldownLike = second.cooldown;
+            onCooldownHook = second.onCooldown;
+            aliasesLike = second.aliases;
+            handler = third;
+        }
         if (handler === undefined)
             throw new AurivalError(`command(${name}) needs a handler`);
+        // AMENDMENT-09 §2.1: `[]` in every state but never `undefined` — a
+        // `Command` this SDK constructs always carries the list, even empty.
+        const aliases = aliasesLike !== undefined ? [...aliasesLike] : [];
+        if (aliases.length > MAX_ALIASES_PER_COMMAND) {
+            throw new AurivalError(CAP_TOO_MANY_ALIASES);
+        }
         const key = lookupKey(name);
         if (this.#registered.has(key))
             status.duplicateCommand(name, this.#quiet);
-        this.#registered.set(key, { command: { name, description }, handler });
+        const registered = { command: { name, description, aliases }, handler };
+        if (cooldownLike !== undefined)
+            registered.cooldown = Cooldown.from(cooldownLike);
+        if (onCooldownHook !== undefined)
+            registered.onCooldown = onCooldownHook;
+        this.#registered.set(key, registered);
     }
     on(type, handler) {
         const reason = NEVER_DISPATCHED_TO_ON.get(type);
@@ -153,6 +190,14 @@ export class Bot {
     onError(fn) {
         this.#errorHook = fn;
     }
+    /**
+     * The bot-level cooldown hook (AMENDMENT-08 §4) — runs for any refused
+     * command that does not carry its own `onCooldown` option. A per-command
+     * hook always wins; only one hook ever runs for a given refusal.
+     */
+    onCooldown(fn) {
+        this.#cooldownHook = fn;
+    }
     // -- running -----------------------------------------------------------
     /** Installs signal handlers and runs until SIGINT/SIGTERM or something fatal. */
     async run() {
@@ -209,7 +254,16 @@ export class Bot {
             onProblem: (problem) => {
                 void this.#callErrorHook(problem, null);
             },
-            hasHandler: (type) => this.#onHandlers.has(type),
+            // `button.pressed` always claims a handler exists, whether or not a
+            // developer ever called `on('button.pressed', ...)` — a press must
+            // reach `#handleButtonPress` so the cooldown check (and its ack on
+            // refusal) always runs, even for a bot that only sends cards and
+            // handles presses nowhere, or not yet (AMENDMENT-08 §1/§5: the button
+            // default applies to every bot with no line of code, and the presser
+            // must never be left staring at pending ink). A press that passes
+            // with no registered handler simply falls through `#handleGeneric`
+            // with nothing to call; the socket-level ack still fires either way.
+            hasHandler: (type) => type === 'button.pressed' || this.#onHandlers.has(type),
             logger: this.#log,
             botName: machine.bot,
             commandCount: this.#registered.size,
@@ -239,10 +293,16 @@ export class Bot {
      * and land the sync in the background.
      */
     async #syncCommands(http, bot, signal) {
-        const payload = [...this.#registered.values()].map((r) => ({
-            name: r.command.name,
-            description: r.command.description,
-        }));
+        const payload = [...this.#registered.values()].map((r) => {
+            const entry = { name: r.command.name, description: r.command.description };
+            // AMENDMENT-09 §2.1: the key is present only when the list is
+            // non-empty — absent and `[]` mean the same thing on this wire, so
+            // there is nothing to gain from sending the empty spelling.
+            if (r.command.aliases !== undefined && r.command.aliases.length > 0) {
+                entry.aliases = [...r.command.aliases];
+            }
+            return entry;
+        });
         try {
             await syncCommandsAndReport(http, bot, payload, this.#log);
             return null;
@@ -303,6 +363,10 @@ export class Bot {
             await this.#handleCommand(event);
             return;
         }
+        if (event.type === 'button.pressed') {
+            await this.#handleButtonPress(event);
+            return;
+        }
         await this.#handleGeneric(event);
     }
     async #handleCommand(event) {
@@ -317,6 +381,13 @@ export class Bot {
         if (this.#http === null)
             return;
         const ctx = Context.fromEvent(event, this.#http);
+        // AMENDMENT-08: the cooldown check runs before auto-typing and before the
+        // handler — a refused invocation never reaches either.
+        if (registered.cooldown !== undefined) {
+            const refused = await this.#handleCommandCooldown(ctx, registered);
+            if (refused)
+                return;
+        }
         const typing = this.#startAutoTyping(ctx);
         try {
             await registered.handler(ctx);
@@ -330,6 +401,109 @@ export class Bot {
             await typing.stop();
         }
     }
+    /**
+     * A registered command's own cooldown (AMENDMENT-08 §4). Returns `true`
+     * when the invocation was refused (dispatch stops here). Its bucket key
+     * carries no message/button scope (`attachmentScope = ()`) — each
+     * command's `Cooldown` is its own instance, so nothing else could collide
+     * with it anyway.
+     *
+     * Once per bucket per window: either the per-command hook, the bot-level
+     * one, or — with neither registered — the fixed reply. A hook does not
+     * run on every refused call; it shares the same `noticeOnce` gate the
+     * built-in notice uses, so mashing a refused command inside one window
+     * produces one hook call (or one reply), not a flood of them.
+     */
+    async #handleCommandCooldown(ctx, registered) {
+        const cooldown = registered.cooldown;
+        if (cooldown === undefined)
+            return false;
+        const key = subjectKey(cooldown.bucket, ctx.sender.id, ctx.chat.id);
+        const refusedAfterSeconds = cooldown.check(key);
+        if (refusedAfterSeconds === null)
+            return false;
+        if (!cooldown.noticeOnce(key))
+            return true;
+        // Per-command beats bot-level; only one hook ever runs.
+        const hook = registered.onCooldown ?? this.#cooldownHook;
+        if (hook !== null && hook !== undefined) {
+            try {
+                await hook(ctx, refusedAfterSeconds);
+            }
+            catch (exc) {
+                this.#log.error(`cooldown hook for ${JSON.stringify(ctx.command)} threw: ${exc instanceof Error ? (exc.stack ?? exc.message) : String(exc)}`);
+                await this.#callErrorHook(exc, ctx);
+            }
+            return true;
+        }
+        const n = roundSeconds(refusedAfterSeconds);
+        try {
+            // AMENDMENT-09 §13.1: names the token the human actually typed, not
+            // the canonical spelling — the bucket is still the canonical
+            // command's (one bucket, all spellings); only the rendered sentence
+            // changes.
+            await ctx.reply(commandCooldownNotice(ctx.invokedAs, n));
+        }
+        catch (exc) {
+            this.#log.error(`cooldown notice for ${JSON.stringify(ctx.command)} failed: ${exc instanceof Error ? (exc.stack ?? exc.message) : String(exc)}`);
+            await this.#callErrorHook(exc, ctx);
+        }
+        return true;
+    }
+    /**
+     * AMENDMENT-08 §3: resolve the pressed button's cooldown (button > card >
+     * bot default), check it, and — on refusal — send the cooldown ack
+     * instead of dispatching to any `on('button.pressed', ...)` handler. The
+     * socket still acks the underlying event exactly as it does for any other
+     * dispatch; only the handler is skipped.
+     */
+    async #handleButtonPress(event) {
+        if (this.#http === null)
+            return;
+        const ctx = contextFor(event, this.#http);
+        const card = this.#http.cardCooldowns.lookup(ctx.message.id);
+        const resolved = resolveButtonCooldown(this.#buttonCooldown, card, ctx.button);
+        if (resolved.cooldown !== null) {
+            const scope = resolved.scoped ? { messageId: ctx.message.id, buttonId: ctx.button } : null;
+            const key = buttonBucketKey(resolved.cooldown, scope, ctx.user.id, ctx.chat.id);
+            const refusedAfterSeconds = resolved.cooldown.check(key);
+            if (refusedAfterSeconds !== null) {
+                await this.#ackButtonCooldown(ctx, retryAfterMs(refusedAfterSeconds));
+                return;
+            }
+        }
+        await this.#handleGeneric(event);
+    }
+    /**
+     * The SDK's own automatic answer to a refused press (§5.1). Swallows
+     * `ButtonAlreadyUsed`/`NotFound` silently — a debug line, never `onError`,
+     * never thrown — because the press already resolved some other way (a
+     * double-tap, an expired row) and the cooldown refusal is moot. Every
+     * other status still goes through the normal error path.
+     */
+    async #ackButtonCooldown(ctx, ms) {
+        if (this.#http === null)
+            return;
+        try {
+            await this.#http.ackCooldown(ctx.interaction, ms);
+            // The ack landed. Without this line a button cooldown is invisible to
+            // the bot author: the SDK answers the press itself, the handler never
+            // runs, and nothing is written anywhere — so a cooldown firing and a
+            // press vanishing look identical from the outside. `info`, not
+            // `debug`, because the swallowed-refusal lines below are the ones a
+            // reader can ignore; this one is the cooldown working. Byte-mirrors
+            // `sdk/python/aurival/bot.py`'s sentence (SDK-7).
+            this.#log.info(`cooldown: acked press on ${ctx.message.id}/${ctx.button} for ${ctx.user.id}, retry_after_ms=${ms}`);
+        }
+        catch (exc) {
+            if (exc instanceof ButtonAlreadyUsed || exc instanceof NotFound) {
+                this.#log.debug(`cooldown ack for ${JSON.stringify(ctx.interaction)} found the press already resolved: ${exc instanceof Error ? exc.message : String(exc)}`);
+                return;
+            }
+            this.#log.error(`cooldown ack for ${JSON.stringify(ctx.interaction)} failed: ${exc instanceof Error ? (exc.stack ?? exc.message) : String(exc)}`);
+            await this.#callErrorHook(exc, ctx);
+        }
+    }
     // -- auto-typing (SDK-41) ------------------------------------------------
     #startAutoTyping(ctx) {
         if (!this.#autoTyping || ctx.chat.id === '')