aurival 0.5.0 → 0.7.0

package/dist/caps.js

@@ -56,4 +56,45 @@ export const CAP_BUTTON_MISSING_LABEL = 'Every button needs `label`. A button wi
  * refused here rather than sent for the server to refuse as empty text.
  */
 export const EMPTY_MESSAGE = 'a message needs text, embeds or buttons';
+/**
+ * AMENDMENT-07 §7's one new code, `nothing_to_edit`: a PATCH body carrying
+ * none of `text`, `embeds` or `buttons` has nothing to change, so the SDK
+ * refuses it here rather than spending a round trip on it.
+ *
+ * The sentence is copied VERBATIM from AMENDMENT-07 §7's table because L1 has
+ * not landed `errors_v1.go`'s row yet — when it does, this string and the Go
+ * catalogue's must stay byte-identical, as they are for every other sentence
+ * shared between `errors_v1.go`, `ERRORS-V1.md` §3, `sdk/python/aurival/caps.py`
+ * and this file.
+ */
+export const NOTHING_TO_EDIT = 'an edit needs text, embeds or buttons';
+/**
+ * AMENDMENT-08 §4: the command-cooldown notice, sent through `ctx.reply`
+ * once per bucket per window. `{name}` is the command as the developer
+ * registered it; `{n}` is `Math.max(1, Math.ceil(retryAfterSeconds))`
+ * (`cooldown.ts`'s `roundSeconds`) — the SAME rounding rule the button
+ * toast's `{n}` uses (§5.4), stated once there. Lives byte-identically in
+ * `sdk/python/aurival/caps.py` and the docs page; never a Go template, since
+ * the server has no part in a command cooldown.
+ */
+export const COMMAND_COOLDOWN_NOTICE_TEMPLATE = 'Slow down. Try /{name} again in {n} s.';
+/** Renders {@link COMMAND_COOLDOWN_NOTICE_TEMPLATE} for one refusal. */
+export function commandCooldownNotice(name, n) {
+    return COMMAND_COOLDOWN_NOTICE_TEMPLATE.replace('{name}', name).replace('{n}', String(n));
+}
+/**
+ * AMENDMENT-08 §5.1/§8's two new ack refusals: `cooldown` mixed with a
+ * `text`/`embeds`/`buttons` body, and a `retry_after_ms` outside
+ * `[MIN_COOLDOWN_RETRY_AFTER_MS, MAX_COOLDOWN_RETRY_AFTER_MS]`. These DO
+ * have a Go twin (`errors_v1.go`'s `CodeCooldownWithBody` /
+ * `CodeCooldownRetryAfterInvalid`, §8's table) — unlike `cooldown.ts`'s four
+ * attachment-time sentences, which never reach the wire and so are never
+ * Go's to send back. L1 has not landed `errors_v1.go`'s rows yet (verified
+ * empty on `origin/main`); these ship ahead on §8's authority, following the
+ * `NOTHING_TO_EDIT` precedent above.
+ */
+export const MIN_COOLDOWN_RETRY_AFTER_MS = 1;
+export const MAX_COOLDOWN_RETRY_AFTER_MS = 60000;
+export const CAP_COOLDOWN_WITH_BODY = 'a cooldown ack carries no text, embeds or buttons';
+export const CAP_COOLDOWN_RETRY_AFTER_INVALID = `a cooldown retry_after_ms is a whole number of milliseconds between ${MIN_COOLDOWN_RETRY_AFTER_MS} and ${MAX_COOLDOWN_RETRY_AFTER_MS}`;
 //# sourceMappingURL=caps.js.map

package/dist/caps.js.map

@@ -1 +1 @@
-{"version":3,"file":"caps.js","sourceRoot":"","sources":["../src/caps.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC;AAC5B,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAClC,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC;AAC7B,MAAM,CAAC,MAAM,eAAe,GAAG,EAAE,CAAC;AAClC,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AACvC,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AACpC,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CAAC;AAC3C,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AACzC,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC;AACvC,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,CAAU,CAAC;AAIjF,MAAM,CAAC,MAAM,mBAAmB,GAAG,oCAAoC,CAAC;AACxE,MAAM,CAAC,MAAM,mBAAmB,GAAG,0CAA0C,CAAC;AAC9E,MAAM,CAAC,MAAM,oBAAoB,GAAG,qCAAqC,CAAC;AAC1E,MAAM,CAAC,MAAM,kBAAkB,GAAG,yCAAyC,CAAC;AAC5E,MAAM,CAAC,MAAM,sBAAsB,GAAG,sCAAsC,CAAC;AAC7E,MAAM,CAAC,MAAM,uBAAuB,GAAG,6CAA6C,CAAC;AACrF,MAAM,CAAC,MAAM,oBAAoB,GAC/B,gEAAgE,CAAC;AACnE,MAAM,CAAC,MAAM,kBAAkB,GAAG,0CAA0C,CAAC;AAC7E,MAAM,CAAC,MAAM,wBAAwB,GAAG,iDAAiD,CAAC;AAC1F,MAAM,CAAC,MAAM,uBAAuB,GAAG,uCAAuC,CAAC;AAE/E;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,qCAAqC,CAAC;AAC5E,MAAM,CAAC,MAAM,qBAAqB,GAAG,yBAAyB,kBAAkB,aAAa,CAAC;AAC9F,MAAM,CAAC,MAAM,2BAA2B,GAAG,2BAA2B,CAAC;AACvE,MAAM,CAAC,MAAM,0BAA0B,GAAG,kCAAkC,CAAC;AAC7E,MAAM,CAAC,MAAM,wBAAwB,GAAG,0CAA0C,CAAC;AACnF,MAAM,CAAC,MAAM,2BAA2B,GAAG,yCAAyC,CAAC;AACrF,MAAM,CAAC,MAAM,2BAA2B,GAAG,iDAAiD,CAAC;AAC7F,MAAM,CAAC,MAAM,8BAA8B,GAAG,4BAA4B,CAAC;AAE3E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GACnC,iFAAiF,CAAC;AAEpF;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,yCAAyC,CAAC"}
+{"version":3,"file":"caps.js","sourceRoot":"","sources":["../src/caps.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC;AAC5B,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAClC,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC;AAC7B,MAAM,CAAC,MAAM,eAAe,GAAG,EAAE,CAAC;AAClC,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AACvC,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AACpC,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CAAC;AAC3C,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AACzC,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC;AACvC,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,CAAU,CAAC;AAIjF,MAAM,CAAC,MAAM,mBAAmB,GAAG,oCAAoC,CAAC;AACxE,MAAM,CAAC,MAAM,mBAAmB,GAAG,0CAA0C,CAAC;AAC9E,MAAM,CAAC,MAAM,oBAAoB,GAAG,qCAAqC,CAAC;AAC1E,MAAM,CAAC,MAAM,kBAAkB,GAAG,yCAAyC,CAAC;AAC5E,MAAM,CAAC,MAAM,sBAAsB,GAAG,sCAAsC,CAAC;AAC7E,MAAM,CAAC,MAAM,uBAAuB,GAAG,6CAA6C,CAAC;AACrF,MAAM,CAAC,MAAM,oBAAoB,GAC/B,gEAAgE,CAAC;AACnE,MAAM,CAAC,MAAM,kBAAkB,GAAG,0CAA0C,CAAC;AAC7E,MAAM,CAAC,MAAM,wBAAwB,GAAG,iDAAiD,CAAC;AAC1F,MAAM,CAAC,MAAM,uBAAuB,GAAG,uCAAuC,CAAC;AAE/E;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,qCAAqC,CAAC;AAC5E,MAAM,CAAC,MAAM,qBAAqB,GAAG,yBAAyB,kBAAkB,aAAa,CAAC;AAC9F,MAAM,CAAC,MAAM,2BAA2B,GAAG,2BAA2B,CAAC;AACvE,MAAM,CAAC,MAAM,0BAA0B,GAAG,kCAAkC,CAAC;AAC7E,MAAM,CAAC,MAAM,wBAAwB,GAAG,0CAA0C,CAAC;AACnF,MAAM,CAAC,MAAM,2BAA2B,GAAG,yCAAyC,CAAC;AACrF,MAAM,CAAC,MAAM,2BAA2B,GAAG,iDAAiD,CAAC;AAC7F,MAAM,CAAC,MAAM,8BAA8B,GAAG,4BAA4B,CAAC;AAE3E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GACnC,iFAAiF,CAAC;AAEpF;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,yCAAyC,CAAC;AAEvE;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,uCAAuC,CAAC;AAEvE;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,wCAAwC,CAAC;AAEzF,wEAAwE;AACxE,MAAM,UAAU,qBAAqB,CAAC,IAAY,EAAE,CAAS;IAC3D,OAAO,gCAAgC,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAC5F,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC;AAC7C,MAAM,CAAC,MAAM,2BAA2B,GAAG,KAAK,CAAC;AAEjD,MAAM,CAAC,MAAM,sBAAsB,GAAG,mDAAmD,CAAC;AAC1F,MAAM,CAAC,MAAM,gCAAgC,GAAG,uEAAuE,2BAA2B,QAAQ,2BAA2B,EAAE,CAAC"}

package/dist/cooldown.d.ts

@@ -0,0 +1,164 @@
+/**
+ * `Cooldown` — the SDK-side rate-limit primitive (AMENDMENT-08 §2).
+ *
+ * SDK-side state only: the wire never carries a cooldown configuration, and
+ * the server never learns one exists (the one exception is the *button*
+ * cooldown ACK, whose `retry_after_ms` is computed FROM this primitive by
+ * `bot.ts` — `http.ts::ackCooldown` — never the other way around).
+ *
+ * **Buckets are process memory. They reset on restart, and they are never
+ * shared across instances or processes.** A bot running two workers behind
+ * a supervisor has two independent buckets, and a deploy clears every
+ * bucket it had. This is stated here, not buried, because a developer who
+ * assumes otherwise builds a quota on it — the server floor
+ * (`press.go`'s `ButtonPressRateLimit`) is what actually bounds abuse.
+ *
+ * This module is a leaf: it imports nothing from `embeds.ts`, `events.ts`,
+ * `http.ts` or `bot.ts`, so `Cooldown` itself never depends on the wire
+ * shapes that use it.
+ *
+ * Mirrors `sdk/python/aurival/cooldown.py` — the bucket algorithm, the key
+ * scheme, and the four cap sentences below are byte/logic-identical between
+ * the two SDKs (AMENDMENT-08's shared algorithm block). The command notice
+ * template and the two ack-refusal sentences that DO have a server twin live
+ * in `caps.ts`, not here — this file's header pins it to sentences with no
+ * server twin, exactly as `caps.ts`'s header pins it to sentences that do.
+ */
+/** Who a bucket is scoped to. `user` (default) is one bucket per presser/invoker; `chat` is one per conversation; `global` is one bucket for the whole attachment. */
+export type CooldownBucket = 'user' | 'chat' | 'global';
+/** A plain `{ rate, per, bucket? }` literal — accepted everywhere a `Cooldown` is, and normalized into one at attachment (R-2, R-7). */
+export interface CooldownLiteral {
+    rate: number;
+    /** seconds */
+    per: number;
+    bucket?: CooldownBucket | undefined;
+}
+/** A `Cooldown` instance, or a literal that normalizes into one. */
+export type CooldownLike = Cooldown | CooldownLiteral;
+/**
+ * The tri-state a cooldown option carries at every one of the three
+ * attachment points (`Bot(buttonCooldown)`, card-level `send(...,
+ * buttonCooldown)`, `Button(cooldown)`), and at a command's own `cooldown`
+ * option: `undefined` — inherit from the level above (or "none", for a
+ * command); `null` — explicitly disabled; a `CooldownLike` — use it.
+ */
+export type CooldownOption = CooldownLike | null;
+export declare const CAP_BUTTON_COOLDOWN_TOO_LONG = "a button cooldown is at most 60 seconds";
+export declare const CAP_COOLDOWN_RATE_TOO_LOW = "a cooldown rate is at least 1";
+export declare const CAP_COOLDOWN_PERIOD_NOT_POSITIVE = "a cooldown period is greater than zero";
+export declare const CAP_LINK_BUTTON_COOLDOWN = "a link button cannot carry a cooldown";
+/** §5.1: a button cooldown's `per` is bounded so the ack's `retry_after_ms` never exceeds the wire's 60000ms cap. Command cooldowns are unbounded (D13) — they never reach the wire. */
+export declare const MAX_BUTTON_COOLDOWN_PER_SECONDS = 60;
+/**
+ * SDK-side rate limit primitive (AMENDMENT-08 §2). One `Cooldown` instance
+ * owns its own bucket map; instances are never shared between attachments —
+ * a command's `Cooldown` is private to that command, a per-button
+ * `Cooldown` private to that button, and so on.
+ *
+ * Fixed window anchored at first use, per bucket key. Buckets and the
+ * once-per-window notice ledger both live for the process lifetime — the
+ * shared algorithm block names no eviction, so none is added here; a bot
+ * that runs for a very long time against a huge number of distinct keys
+ * accumulates entries for as long as it runs (unlike the bounded card
+ * lookup table in `bot.ts`, which is namespaced to message ids and capped).
+ */
+export declare class Cooldown {
+    #private;
+    readonly rate: number;
+    /** seconds */
+    readonly per: number;
+    readonly bucket: CooldownBucket;
+    /**
+     * `now` is an injectable monotonic clock (seconds), for tests only — it is
+     * deliberately not part of the documented public signature (`new
+     * Cooldown(rate, per, bucket)`, matching §2's examples byte for byte).
+     */
+    constructor(rate: number, per: number, bucket?: CooldownBucket, now?: () => number);
+    /** An existing `Cooldown` passes through unchanged; a plain literal is validated and wrapped. */
+    static from(value: CooldownLike, now?: () => number): Cooldown;
+    /**
+     * One synchronous check-and-consume. `null` on a pass (a token was
+     * spent); the seconds remaining on a refusal. **A refusal never consumes
+     * and never touches the window** — mashing a refused key does not push
+     * the window further out.
+     */
+    check(key: string): number | null;
+    /**
+     * The once-per-window gate for the command notice (§4): `true` only the
+     * first time it is called for this key's CURRENT window, `false` for
+     * every call after that until the window rolls over. Call this only
+     * right after a `check()` refusal on the same key — it reads the window
+     * `check()` just refused against (a refusal leaves `windowStart`
+     * untouched, so this is safe).
+     */
+    noticeOnce(key: string): boolean;
+}
+/** §5's rounding rule, shared by the command sentence's `{n}` and the button ack's `retry_after_ms`: a fractional remainder always rounds UP, and never to zero — a toast or reply that says "0 s" tells the presser to retry immediately, and they would be refused again. */
+export declare function roundSeconds(retryAfterSeconds: number): number;
+/** `retryAfterSeconds` -> the wire's `retry_after_ms`, whole milliseconds, never zero. */
+export declare function retryAfterMs(retryAfterSeconds: number): number;
+/** Refused at ATTACHMENT time (§5): a button cooldown's `per` may not exceed the wire's `retry_after_ms` cap. Command cooldowns never call this — they are unbounded (D13). */
+export declare function requireButtonCooldownBounds(cooldown: Cooldown): void;
+/**
+ * Normalizes a tri-state `CooldownOption` at one attachment point:
+ * `undefined` stays `undefined` (inherit), `null` stays `null` (disabled), a
+ * `CooldownLike` is validated and turned into a `Cooldown`. `boundToButton`
+ * runs the 60s cap — pass it for every button-family attachment
+ * (`Bot(buttonCooldown)`, card-level, per-button) and leave it off for a
+ * command's `cooldown`, which §5 leaves unbounded.
+ */
+export declare function normalizeCooldownOption(value: CooldownOption | undefined, options: {
+    boundToButton: boolean;
+}): Cooldown | null | undefined;
+/** `bucket` + the invoking/pressing user id and the chat id -> the subject half of a key (§2's three-bucket table). */
+export declare function subjectKey(bucket: CooldownBucket, userId: string, chatId: string): string;
+/**
+ * A button press's full bucket key (§3): the bot-level default has
+ * `attachmentScope = ()` — one bucket per user (or chat/global) per bot,
+ * regardless of which message or button was pressed — while a card-level or
+ * per-button `Cooldown` scopes to `(messageId, buttonId)` too, because
+ * button ids are unique only WITHIN a message
+ * (`duplicate_button_id`, ERRORS-V1 §3): two cards reusing the same button
+ * id must not share a bucket.
+ */
+export declare function buttonBucketKey(cooldown: Cooldown, scope: {
+    messageId: string;
+    buttonId: string;
+} | null, userId: string, chatId: string): string;
+/** One outgoing card's recorded cooldown configuration (§3's "card lookup on press"). `undefined` in either slot means "inherits from the level above" — the bot default for `cardCooldown`, the card's own resolved cooldown for an entry missing from `byButtonId`. */
+export interface CardCooldownRecord {
+    cardCooldown: Cooldown | null | undefined;
+    byButtonId: ReadonlyMap<string, Cooldown | null>;
+}
+/**
+ * Records, per outgoing message id, the card-level cooldown and any
+ * per-button overrides a `send()`/`reply()`/`ack()`/`edit()` call attached —
+ * because a `button.pressed` event carries only ids, never the `Button`
+ * objects that were sent, so precedence has to be resolved from somewhere
+ * that remembers them. Bounded LRU-ish (insertion order; `record` moves an
+ * existing key to the back) so a bot running for a long time does not grow
+ * this table without limit.
+ */
+export declare class CardCooldownTable {
+    #private;
+    /**
+     * `undefined` `cardCooldown` and an empty `byButtonId` together mean
+     * "nothing overrides anything on this card" — recording that is a no-op
+     * (equivalent to no entry at all, since a lookup miss already falls
+     * through to the bot default), and an existing entry for this id is
+     * cleared rather than left stale (a card edited to drop its per-button
+     * overrides must not keep the old ones).
+     */
+    record(messageId: string, entry: CardCooldownRecord): void;
+    /** `undefined` when the message is absent from the table — restarted process, or sent by another one (§3: "fall through to the bot default"). */
+    lookup(messageId: string): CardCooldownRecord | undefined;
+}
+/** What a press resolved to, and whether it is scoped to `(messageId, buttonId)` when building the bucket key. */
+export interface ResolvedButtonCooldown {
+    cooldown: Cooldown | null;
+    /** `false` only when the bot-level default is what resolved — `attachmentScope = ()` (§3). */
+    scoped: boolean;
+}
+/** Precedence: button > card > bot default (§3), read off the recorded card entry (or its absence). */
+export declare function resolveButtonCooldown(botDefault: Cooldown | null, card: CardCooldownRecord | undefined, buttonId: string): ResolvedButtonCooldown;
+//# sourceMappingURL=cooldown.d.ts.map

package/dist/cooldown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cooldown.d.ts","sourceRoot":"","sources":["../src/cooldown.ts"],"names":[],"mappings":"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"}

package/dist/cooldown.js

@@ -0,0 +1,221 @@
+/**
+ * `Cooldown` — the SDK-side rate-limit primitive (AMENDMENT-08 §2).
+ *
+ * SDK-side state only: the wire never carries a cooldown configuration, and
+ * the server never learns one exists (the one exception is the *button*
+ * cooldown ACK, whose `retry_after_ms` is computed FROM this primitive by
+ * `bot.ts` — `http.ts::ackCooldown` — never the other way around).
+ *
+ * **Buckets are process memory. They reset on restart, and they are never
+ * shared across instances or processes.** A bot running two workers behind
+ * a supervisor has two independent buckets, and a deploy clears every
+ * bucket it had. This is stated here, not buried, because a developer who
+ * assumes otherwise builds a quota on it — the server floor
+ * (`press.go`'s `ButtonPressRateLimit`) is what actually bounds abuse.
+ *
+ * This module is a leaf: it imports nothing from `embeds.ts`, `events.ts`,
+ * `http.ts` or `bot.ts`, so `Cooldown` itself never depends on the wire
+ * shapes that use it.
+ *
+ * Mirrors `sdk/python/aurival/cooldown.py` — the bucket algorithm, the key
+ * scheme, and the four cap sentences below are byte/logic-identical between
+ * the two SDKs (AMENDMENT-08's shared algorithm block). The command notice
+ * template and the two ack-refusal sentences that DO have a server twin live
+ * in `caps.ts`, not here — this file's header pins it to sentences with no
+ * server twin, exactly as `caps.ts`'s header pins it to sentences that do.
+ */
+export const CAP_BUTTON_COOLDOWN_TOO_LONG = 'a button cooldown is at most 60 seconds';
+export const CAP_COOLDOWN_RATE_TOO_LOW = 'a cooldown rate is at least 1';
+export const CAP_COOLDOWN_PERIOD_NOT_POSITIVE = 'a cooldown period is greater than zero';
+export const CAP_LINK_BUTTON_COOLDOWN = 'a link button cannot carry a cooldown';
+/** §5.1: a button cooldown's `per` is bounded so the ack's `retry_after_ms` never exceeds the wire's 60000ms cap. Command cooldowns are unbounded (D13) — they never reach the wire. */
+export const MAX_BUTTON_COOLDOWN_PER_SECONDS = 60;
+/** Seconds, monotonic. `performance.now()` never goes backwards and needs no epoch. */
+function defaultClock() {
+    return performance.now() / 1000;
+}
+/** One key's scope + subject, joined with a separator no id in this SDK can contain (`msg_…`/`btn ids`/`usr_…`/`chat_…` are all `[a-zA-Z0-9_-]`). */
+const KEY_SEP = ' ';
+/**
+ * SDK-side rate limit primitive (AMENDMENT-08 §2). One `Cooldown` instance
+ * owns its own bucket map; instances are never shared between attachments —
+ * a command's `Cooldown` is private to that command, a per-button
+ * `Cooldown` private to that button, and so on.
+ *
+ * Fixed window anchored at first use, per bucket key. Buckets and the
+ * once-per-window notice ledger both live for the process lifetime — the
+ * shared algorithm block names no eviction, so none is added here; a bot
+ * that runs for a very long time against a huge number of distinct keys
+ * accumulates entries for as long as it runs (unlike the bounded card
+ * lookup table in `bot.ts`, which is namespaced to message ids and capped).
+ */
+export class Cooldown {
+    rate;
+    /** seconds */
+    per;
+    bucket;
+    #now;
+    #buckets = new Map();
+    #notified = new Map();
+    /**
+     * `now` is an injectable monotonic clock (seconds), for tests only — it is
+     * deliberately not part of the documented public signature (`new
+     * Cooldown(rate, per, bucket)`, matching §2's examples byte for byte).
+     */
+    constructor(rate, per, bucket = 'user', now = defaultClock) {
+        if (rate < 1)
+            throw new Error(CAP_COOLDOWN_RATE_TOO_LOW);
+        if (!(per > 0))
+            throw new Error(CAP_COOLDOWN_PERIOD_NOT_POSITIVE);
+        this.rate = rate;
+        this.per = per;
+        this.bucket = bucket;
+        this.#now = now;
+    }
+    /** An existing `Cooldown` passes through unchanged; a plain literal is validated and wrapped. */
+    static from(value, now) {
+        if (value instanceof Cooldown)
+            return value;
+        return now === undefined
+            ? new Cooldown(value.rate, value.per, value.bucket ?? 'user')
+            : new Cooldown(value.rate, value.per, value.bucket ?? 'user', now);
+    }
+    /**
+     * One synchronous check-and-consume. `null` on a pass (a token was
+     * spent); the seconds remaining on a refusal. **A refusal never consumes
+     * and never touches the window** — mashing a refused key does not push
+     * the window further out.
+     */
+    check(key) {
+        const now = this.#now();
+        let state = this.#buckets.get(key);
+        if (state === undefined || now - state.windowStart >= this.per) {
+            state = { windowStart: now, tokens: this.rate };
+            this.#buckets.set(key, state);
+        }
+        if (state.tokens === 0) {
+            return this.per - (now - state.windowStart);
+        }
+        state.tokens -= 1;
+        return null;
+    }
+    /**
+     * The once-per-window gate for the command notice (§4): `true` only the
+     * first time it is called for this key's CURRENT window, `false` for
+     * every call after that until the window rolls over. Call this only
+     * right after a `check()` refusal on the same key — it reads the window
+     * `check()` just refused against (a refusal leaves `windowStart`
+     * untouched, so this is safe).
+     */
+    noticeOnce(key) {
+        const windowStart = this.#buckets.get(key)?.windowStart ?? this.#now();
+        if (this.#notified.get(key) === windowStart)
+            return false;
+        this.#notified.set(key, windowStart);
+        return true;
+    }
+}
+/** §5's rounding rule, shared by the command sentence's `{n}` and the button ack's `retry_after_ms`: a fractional remainder always rounds UP, and never to zero — a toast or reply that says "0 s" tells the presser to retry immediately, and they would be refused again. */
+export function roundSeconds(retryAfterSeconds) {
+    return Math.max(1, Math.ceil(retryAfterSeconds));
+}
+/** `retryAfterSeconds` -> the wire's `retry_after_ms`, whole milliseconds, never zero. */
+export function retryAfterMs(retryAfterSeconds) {
+    return Math.max(1, Math.ceil(retryAfterSeconds * 1000));
+}
+/** Refused at ATTACHMENT time (§5): a button cooldown's `per` may not exceed the wire's `retry_after_ms` cap. Command cooldowns never call this — they are unbounded (D13). */
+export function requireButtonCooldownBounds(cooldown) {
+    if (cooldown.per > MAX_BUTTON_COOLDOWN_PER_SECONDS)
+        throw new Error(CAP_BUTTON_COOLDOWN_TOO_LONG);
+}
+/**
+ * Normalizes a tri-state `CooldownOption` at one attachment point:
+ * `undefined` stays `undefined` (inherit), `null` stays `null` (disabled), a
+ * `CooldownLike` is validated and turned into a `Cooldown`. `boundToButton`
+ * runs the 60s cap — pass it for every button-family attachment
+ * (`Bot(buttonCooldown)`, card-level, per-button) and leave it off for a
+ * command's `cooldown`, which §5 leaves unbounded.
+ */
+export function normalizeCooldownOption(value, options) {
+    if (value === undefined)
+        return undefined;
+    if (value === null)
+        return null;
+    const cooldown = Cooldown.from(value);
+    if (options.boundToButton)
+        requireButtonCooldownBounds(cooldown);
+    return cooldown;
+}
+/** `bucket` + the invoking/pressing user id and the chat id -> the subject half of a key (§2's three-bucket table). */
+export function subjectKey(bucket, userId, chatId) {
+    if (bucket === 'user')
+        return `user${KEY_SEP}${userId}`;
+    if (bucket === 'chat')
+        return `chat${KEY_SEP}${chatId}`;
+    return 'global';
+}
+/**
+ * A button press's full bucket key (§3): the bot-level default has
+ * `attachmentScope = ()` — one bucket per user (or chat/global) per bot,
+ * regardless of which message or button was pressed — while a card-level or
+ * per-button `Cooldown` scopes to `(messageId, buttonId)` too, because
+ * button ids are unique only WITHIN a message
+ * (`duplicate_button_id`, ERRORS-V1 §3): two cards reusing the same button
+ * id must not share a bucket.
+ */
+export function buttonBucketKey(cooldown, scope, userId, chatId) {
+    const subject = subjectKey(cooldown.bucket, userId, chatId);
+    return scope === null
+        ? subject
+        : `${scope.messageId}${KEY_SEP}${scope.buttonId}${KEY_SEP}${subject}`;
+}
+/** §3: "bound the table (LRU cap ~1024 messages) so a long-lived bot does not grow without limit." */
+const CARD_TABLE_CAP = 1024;
+/**
+ * Records, per outgoing message id, the card-level cooldown and any
+ * per-button overrides a `send()`/`reply()`/`ack()`/`edit()` call attached —
+ * because a `button.pressed` event carries only ids, never the `Button`
+ * objects that were sent, so precedence has to be resolved from somewhere
+ * that remembers them. Bounded LRU-ish (insertion order; `record` moves an
+ * existing key to the back) so a bot running for a long time does not grow
+ * this table without limit.
+ */
+export class CardCooldownTable {
+    #entries = new Map();
+    /**
+     * `undefined` `cardCooldown` and an empty `byButtonId` together mean
+     * "nothing overrides anything on this card" — recording that is a no-op
+     * (equivalent to no entry at all, since a lookup miss already falls
+     * through to the bot default), and an existing entry for this id is
+     * cleared rather than left stale (a card edited to drop its per-button
+     * overrides must not keep the old ones).
+     */
+    record(messageId, entry) {
+        if (messageId === '')
+            return;
+        this.#entries.delete(messageId);
+        if (entry.cardCooldown === undefined && entry.byButtonId.size === 0)
+            return;
+        this.#entries.set(messageId, entry);
+        while (this.#entries.size > CARD_TABLE_CAP) {
+            const oldest = this.#entries.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.#entries.delete(oldest);
+        }
+    }
+    /** `undefined` when the message is absent from the table — restarted process, or sent by another one (§3: "fall through to the bot default"). */
+    lookup(messageId) {
+        return this.#entries.get(messageId);
+    }
+}
+/** Precedence: button > card > bot default (§3), read off the recorded card entry (or its absence). */
+export function resolveButtonCooldown(botDefault, card, buttonId) {
+    const buttonOverride = card?.byButtonId.get(buttonId);
+    if (buttonOverride !== undefined)
+        return { cooldown: buttonOverride, scoped: true };
+    if (card?.cardCooldown !== undefined)
+        return { cooldown: card.cardCooldown, scoped: true };
+    return { cooldown: botDefault, scoped: false };
+}
+//# sourceMappingURL=cooldown.js.map

package/dist/cooldown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cooldown.js","sourceRoot":"","sources":["../src/cooldown.ts"],"names":[],"mappings":"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"}

package/dist/embeds.d.ts

@@ -17,6 +17,8 @@
  * throws — the caps are an outbound (client -> server) contract, not an
  * inbound one, and a message already stored by the server is assumed valid.
  */
+import { Cooldown } from './cooldown.js';
+import type { CooldownOption } from './cooldown.js';
 export interface EmbedFieldValue {
     name: string;
     value: string;
@@ -84,6 +86,16 @@ export interface ButtonInit {
     style?: string;
     emoji?: string;
     url?: string;
+    /**
+     * AMENDMENT-08 §3: this button's own cooldown, overriding the card-level
+     * and bot-default one for this button only (precedence button > card >
+     * bot). `undefined` (the default) inherits; `null` disables the default
+     * for this one button; a `Cooldown` or a plain `{ rate, per, bucket? }`
+     * literal attaches one. Refused at construction — before this button ever
+     * reaches the wire — if `per` exceeds 60s, or if this is a `link` button
+     * (a link press never round-trips, so it can never carry a cooldown).
+     */
+    cooldown?: CooldownOption;
 }
 /** `new Button({ label: 'Pacific' })` — `id` defaults to a slug of `label`, `style` defaults to `'primary'`. */
 export declare class Button {
@@ -92,6 +104,15 @@ export declare class Button {
     style: string;
     emoji?: string;
     url?: string;
+    /**
+     * This button's own cooldown (AMENDMENT-08 §3), normalized to a real
+     * `Cooldown` by `validateButtonShape` (a plain literal in, a `Cooldown`
+     * out — `null` passes through unchanged). Absent entirely when the
+     * developer never set one, which reads as "inherit" at resolution time.
+     * Never serialized: `toJSON()` does not carry it, because a cooldown is
+     * SDK-side state that never reaches the wire (§2).
+     */
+    cooldown?: Cooldown | null;
     constructor(init: ButtonInit);
     /**
      * The sanctioned way to build a link pill (AMENDMENT-06 §11): a url is not
@@ -130,6 +151,23 @@ export type ButtonLike = Button | Record<string, unknown>;
  * empty, so the caller omits the key.
  */
 export declare function serialiseEmbeds(embeds: ReadonlyArray<EmbedLike> | undefined): Record<string, unknown>[];
+/** `serialiseButtonsWithCooldowns`'s return shape: the wire JSON, plus every button's cooldown (only the buttons that carried one — inherited buttons are simply absent from the map). */
+export interface SerialisedButtons {
+    json: Record<string, unknown>[];
+    /** button id -> its own `Cooldown` (`null` means explicitly disabled). A button not in this map inherits from the card, then the bot default (§3). */
+    cooldowns: ReadonlyMap<string, Cooldown | null>;
+}
+/**
+ * Validates and serialises the `buttons` a caller passed to
+ * `send`/`reply`/`edit`/`ack`, exactly as `serialiseButtons` does, and ALSO
+ * returns each button's own resolved cooldown (AMENDMENT-08 §3) — the
+ * per-button overrides `bot.ts`'s card lookup table (`cooldown.ts`'s
+ * `CardCooldownTable`) needs to resolve a later press, since the
+ * `button.pressed` event that press produces carries only ids, never the
+ * `Button` objects this call was given. One validation pass; `serialiseButtons`
+ * is a thin wrapper around this for callers that only want the wire shape.
+ */
+export declare function serialiseButtonsWithCooldowns(buttons: ReadonlyArray<ButtonLike> | undefined): SerialisedButtons;
 /**
  * Validates and serialises the `buttons` a caller passed to `send`/`reply`.
  * `[]` when `buttons` is absent or empty, so the caller omits the key.

package/dist/embeds.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"embeds.d.ts","sourceRoot":"","sources":["../src/embeds.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"embeds.d.ts","sourceRoot":"","sources":["../src/embeds.ts"],"names":[],"mappings":"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"}