aurival 0.4.0 → 0.6.0

package/README.md

@@ -249,10 +249,11 @@ bot.on('member.joined', async (ctx) => {
 
 `Embed` is a builder — every `setAuthor`/`setThumbnail`/`addField`/`setFooter` call returns the
 same instance, so you chain them off the constructor. `Button` is a separate, flat object:
-`new Button({ label, id, style })`, where `style` is one of `'primary' | 'secondary' | 'danger'`
-— `'link'` isn't supported yet, and passing it throws a plain error naming the bad style. Pass
-arrays of both into the existing options-object shape `ctx.reply(text, { embeds, buttons })`,
-the same convention `ctx.send(chat, text, { mentions })` already uses:
+`new Button({ label, id, style })`, where `style` is one of
+`'primary' | 'secondary' | 'danger' | 'link'`, and anything else throws a plain error naming the
+bad style. Pass arrays of both into the existing options-object shape
+`ctx.reply(text, { embeds, buttons })`, the same convention `ctx.send(chat, text, { mentions })`
+already uses:
 
 ```ts
 import { Embed, Button } from 'aurival';
@@ -273,10 +274,148 @@ const buttons = [
 await ctx.reply('Ready when you are.', { embeds: [embed], buttons });
 ```
 
-There are caps, and the SDK checks them locally before the frame ever goes out, so a bad bot
-fails fast with a plain error naming which cap it hit: a message carries at most 3 embeds, an
-embed at most 6 fields, a message at most 5 buttons, and a button label is at most 24
-characters.
+A card earns its place when there is something to put on it: buttons, fields, an image. A reply
+that one line of text covers — a coin flip, a joke, a status line — reads better as that line,
+and a plate wrapped around it is chrome the reader has to look past.
+
+### A button that opens a link
+
+`Button.link({ label, url })` builds a pill that opens a url instead of coming back to your bot.
+It is the only sanctioned way to build one — `style: 'link'` on the plain constructor without a
+url throws, because a link button with nowhere to go is a dead pill:
+
+```ts
+import { Button } from 'aurival';
+
+const buttons = [
+  Button.link({ label: 'Full lineup', url: 'https://aurival.com/spaces/deepcuts/lineup' }),
+  Button.link({ label: 'Set notes', url: 'https://example.com/notes' }),
+  new Button({ label: 'Remind me', id: 'remind', style: 'primary' }),
+];
+
+await ctx.reply('Doors at 21:00.', { buttons });
+```
+
+A link button never comes back to you: no `button.pressed` event, ever, and it never flips the
+row to used. It also stays tappable after a sibling is pressed, and while a sibling is still
+waiting on your `ack()` — the row greys out around it, the link does not. `id` still has to be
+there and still has to be unique in the message, and the SDK still slugs it from the label when
+you leave it out, so that `Set notes` pill gets `id: 'set-notes'` like any other button. Link
+buttons count toward the five-button cap, and a message made only of link buttons is fine.
+
+A url is `https://` and at most 2048 characters, everywhere a url is a link target. A non-link
+button must not carry a `url`, and passing one throws rather than being quietly dropped — a typo
+you cannot see is worse than an error you can.
+
+### Emoji on a button
+
+`emoji` puts one glyph in front of the label, inside the pill:
+
+```ts
+import { Button } from 'aurival';
+
+const buttons = [
+  new Button({ label: 'Maybe', id: 'maybe', style: 'secondary', emoji: '🤔' }),
+  new Button({ label: 'Remind me', id: 'remind', style: 'primary', emoji: '⏰' }),
+];
+
+await ctx.reply('Set starts in an hour.', { buttons });
+```
+
+Exactly one unicode emoji, no custom emoji, no `:shortcode:`, no image url. The emoji does not
+count toward the 24-character label cap — it is its own field, and folding it into the label
+count would make one cap mean two things. The label is still required, so there is no
+emoji-only button: a pill with no words is unguessable to everyone and unreadable to a screen
+reader.
+
+### A footer icon, a linked title, a linked author
+
+`setFooter(text, icon)` puts a small image beside the footer text, `url` on the embed makes its
+title tappable, and the third argument to `setAuthor` does the same for the author line:
+
+```ts
+import { Embed } from 'aurival';
+
+const embed = new Embed({
+  title: "Tonight's set",
+  description: 'Deep cuts only, and nothing after midnight.',
+  color: '#3E6E8E',
+  url: 'https://aurival.com/spaces/deepcuts',
+})
+  .setAuthor('Deep Cuts', 'https://cdn.aurival.com/dc.png', 'https://aurival.com/u/deepcuts')
+  .setThumbnail('https://cdn.aurival.com/cover.jpg')
+  .setFooter('set by deepcuts', 'https://cdn.aurival.com/dc-small.png');
+
+await ctx.reply("Tonight's lineup.", { embeds: [embed] });
+```
+
+Each of the three needs the thing it attaches to: a footer icon needs footer text, an embed url
+needs a title to hang the tap on, and an author url needs an author name. Without them there is
+nothing for a reader to press, and dropping the url silently would fail where nobody could see
+it.
+
+### Markdown in the description
+
+The description is rendered as markdown. Nothing else on the card is — title, field names, field
+values, footer text and author name are all plain text, so a `**bold**` in a field name arrives
+as four asterisks and two words:
+
+```ts
+import { Embed } from 'aurival';
+
+const embed = new Embed({
+  title: 'House rules',
+  description:
+    '**Deep cuts** only. No *requests* after the ~~third~~ second hour.\n' +
+    'Type `!queue` to see what is next.',
+}).addField('Set length', '3 hours', true);
+
+await ctx.reply('Welcome in.', { embeds: [embed] });
+```
+
+Supported: bold, italic, bold-italic, strikethrough and inline code. Headings render as bold
+text at body size rather than as larger type, because a card is not a document. Not supported:
+images, tables, code panels and autolink — a fenced block renders as plain styled text, not a
+panel, and a bare URL never becomes a tap target.
+
+Italic is `*text*`; underscores are not a delimiter and render as typed.
+
+The 1024-character description cap counts the raw markdown source you typed, not what the reader
+sees, so the asterisks and backticks are part of your budget.
+
+A markdown link (`[label](https://…)`) or a bare URL is still refused inside the description, and
+inside every other prose field with it. Links live in the structured url fields above, where the
+client knows the target before it paints — in prose, a label can say one thing and go somewhere
+else.
+
+### Where a link goes, and what the reader sees first
+
+A tap on a link button, a linked title or a linked author that points outside Aurival shows the
+reader a leaving notice naming the host before anything opens, so nobody hands their IP to a
+stranger by pressing a pill that looked friendly. The host on the notice is read off the real
+url, so what they are shown is what opens. An `aurival.com` link skips the notice and opens in
+the app, because it never left.
+
+### Caps
+
+The SDK checks every cap locally before the frame goes out, so a bad bot fails fast with a plain
+error naming which cap it hit.
+
+| cap                                                    | limit                                        |
+| ------------------------------------------------------ | -------------------------------------------- |
+| embeds per message                                      | 3                                            |
+| fields per message                                      | 6, summed across every embed                 |
+| buttons per message                                     | 5                                            |
+| button label                                            | 24 characters, emoji not counted             |
+| button emoji                                            | exactly one unicode emoji                    |
+| button style                                            | `primary`, `secondary`, `danger` or `link`   |
+| embed description                                       | 1024 characters of raw markdown              |
+| link url (button, title, author)                        | 2048 characters, `https://` only             |
+| image url (thumbnail, image, author icon, footer icon)  | `https://` only, no length cap               |
+
+One convention, which is ours and not a rule: when one button is the one you want pressed, put
+it last. The server and the client never reorder a row — your order is the order the reader
+sees — so this is a habit the docs suggest, not something enforced anywhere.
 
 A press comes back as a `button.pressed` event, handled the same way any other event is:
 
@@ -344,6 +483,84 @@ code reading other `Message` fields is unaffected.
 `bot.on('button.pressed', ...)` is a new event a bot can opt into; a bot that never registers a
 handler for it simply never receives one.
 
+### Upgrading from 0.4.x
+
+Everything 0.5.0 adds to a card is optional: `url` on the `Embed` init object and as the third
+argument to `setAuthor`, the second argument to `setFooter`, `emoji` and `url` on `Button`, and
+the `Button.link` constructor. A card that uses none of them serialises exactly as it did on
+0.4.0 — same keys, same bytes, no `url: null` where there was nothing before — so a bot you
+wrote against 0.4.0 needs no edit at all.
+
+`'link'` is a real button style now, where 0.4.0 refused it with `link buttons are not supported
+in v1`. Build one with `Button.link({ label, url })`; that static is the sanctioned constructor, and it sets the
+style for you.
+
+A link button is not an action button wearing a url. It never produces a `button.pressed` event,
+it never flips `used`, and it is not disabled by a sibling being pending or used — so a row can
+go cold around a link and the link still works. If you were counting on every button in a row
+answering back, count only the ones you did not build with `Button.link`.
+
+### Upgrading from 0.5.x
+
+0.6.0 adds optional fields in two places and takes nothing away. `ctx.edit()` takes an init
+object next to the message, and `ctx.ack()` takes one too, so a press can answer by replacing the
+card it was pressed on instead of stacking a second message under it. A bot written against
+0.5.0 needs no edit at all: `await ctx.edit(sent, 'done!')` still takes a plain string, and a
+bare `await ctx.ack()` sends exactly the bytes it sent before.
+
+Three states, one rule, on both doors:
+
+- leave a field out and that part of the card is kept as it was
+- pass a value and that part is replaced
+- pass `[]` or `null` and that part is cleared — both go on the wire as `"embeds": null`
+
+`text` is not clearable, because a card always carries text and `''` already means empty. An edit
+with all three left out throws `an edit needs text, embeds or buttons` before anything is sent,
+and the server answers the same sentence as `NothingToEdit`.
+
+A trivia round is the whole feature in one pair of handlers. Both cards earn their plate: the
+question card carries buttons, the result card carries a field.
+
+```ts
+import { Button, Embed } from 'aurival';
+
+bot.command('trivia', async (ctx) => {
+  await ctx.reply({
+    embeds: [new Embed({ title: 'Which planet is largest?' })],
+    buttons: [
+      new Button({ label: 'Mars', style: 'secondary' }),
+      new Button({ label: 'Jupiter', style: 'secondary' }),
+    ],
+  });
+});
+
+bot.on('button.pressed', async (ctx) => {
+  const correct = ctx.button === 'jupiter';
+  const result = new Embed({
+    title: correct ? 'Jupiter' : 'Not quite',
+    description: 'Jupiter is about eleven Earths across.',
+  }).addField('Answered by', ctx.user.handle, true);
+  await ctx.ack({
+    embeds: [result],
+    buttons: [new Button({ id: 'again', label: 'Play again' })],
+  });
+});
+```
+
+The ack and the replacement are one request. The question card becomes the result card in place,
+the `Play again` row starts unused, and the message is not marked edited — an interaction
+response is the bot answering the presser, not the author correcting themselves. Reusing button
+ids across replacements is allowed and safe: the server keys the refusal on the interaction, not
+on the id.
+
+`edit()` is the other door and it does mark the message edited, so a card can redraw itself
+outside a press:
+
+```ts
+await ctx.edit(sent, { embeds: [new Embed({ title: 'Starting in 3…' })] });
+await ctx.edit(sent, { buttons: [] });   // the row is gone, the plate stays
+```
+
 ## Shadowed commands
 
 A bot can declare up to 50 commands, the SDK refuses to connect past that.

package/dist/caps.d.ts

@@ -14,7 +14,9 @@ export declare const MAX_LABEL_RUNES = 24;
 export declare const MAX_BUTTON_ID_LENGTH = 32;
 export declare const MAX_TITLE_LENGTH = 256;
 export declare const MAX_DESCRIPTION_LENGTH = 1024;
-export declare const BUTTON_STYLES: readonly ['primary', 'secondary', 'danger'];
+export declare const MAX_BUTTON_EMOJI_RUNES = 16;
+export declare const MAX_LINK_URL_RUNES = 2048;
+export declare const BUTTON_STYLES: readonly ['primary', 'secondary', 'danger', 'link'];
 export type ButtonStyle = (typeof BUTTON_STYLES)[number];
 export declare const CAP_TOO_MANY_EMBEDS = "a message carries at most 3 embeds";
 export declare const CAP_TOO_MANY_FIELDS = "a message carries at most 6 embed fields";
@@ -22,15 +24,49 @@ export declare const CAP_TOO_MANY_BUTTONS = "a message carries at most 5 buttons
 export declare const CAP_LABEL_TOO_LONG = "a button label is at most 24 characters";
 export declare const CAP_BUTTON_ID_TOO_LONG = "a button id is at most 32 characters";
 export declare const CAP_DUPLICATE_BUTTON_ID = "a button id must be unique within a message";
-export declare const CAP_BAD_BUTTON_STYLE = "a button style must be one of primary, secondary, danger";
-export declare const CAP_LINK_STYLE_DEFERRED = "link buttons are not supported in v1";
+export declare const CAP_BAD_BUTTON_STYLE = "a button style must be one of primary, secondary, danger, link";
 export declare const CAP_TITLE_TOO_LONG = "an embed title is at most 256 characters";
 export declare const CAP_DESCRIPTION_TOO_LONG = "an embed description is at most 1024 characters";
 export declare const CAP_IMAGE_URL_NOT_HTTPS = "an image url must start with https://";
+/**
+ * AMENDMENT-06 §5. Link targets live in structured fields, never in prose,
+ * and they answer a link mistake with a link sentence: `an image url ...`
+ * would tell a bot author to fix the wrong thing. The one sentence that
+ * names a number renders it from `MAX_LINK_URL_RUNES`, exactly as the
+ * label and title caps above render theirs, because the server's template
+ * refuses a digit literal.
+ */
+export declare const CAP_LINK_URL_NOT_HTTPS = "a link url must start with https://";
+export declare const CAP_LINK_URL_TOO_LONG = "a link url is at most 2048 characters";
+export declare const CAP_LINK_BUTTON_MISSING_URL = "a link button needs a url";
+export declare const CAP_URL_ON_NON_LINK_BUTTON = "only a link button carries a url";
+export declare const CAP_INVALID_BUTTON_EMOJI = "a button emoji is a single unicode emoji";
+export declare const CAP_EMBED_URL_WITHOUT_TITLE = "an embed url needs a title to attach to";
+export declare const CAP_AUTHOR_URL_WITHOUT_NAME = "an author url needs an author name to attach to";
+export declare const CAP_EMBED_FOOTER_TEXT_REQUIRED = "an embed footer needs text";
+/**
+ * The server's `button_missing_field` sentence, rendered for the one field
+ * an SDK caller can actually leave empty. AMENDMENT-06 §3 keeps the label
+ * required so an emoji-only pill cannot ship: a pill with no words is
+ * unreadable to a screen reader and unguessable to everyone else.
+ */
+export declare const CAP_BUTTON_MISSING_LABEL = "Every button needs `label`. A button without one cannot be rendered or pressed.";
 /**
  * The SDK's own precondition, not one of the server's cap sentences: a send
  * with no text, no embeds and no buttons has nothing to deliver, so it is
  * refused here rather than sent for the server to refuse as empty text.
  */
 export declare 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 declare const NOTHING_TO_EDIT = "an edit needs text, embeds or buttons";
 //# sourceMappingURL=caps.d.ts.map

package/dist/caps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"caps.d.ts","sourceRoot":"","sources":["../src/caps.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,UAAU,IAAI,CAAC;AAC5B,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAClC,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,eAAe,KAAK,CAAC;AAClC,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,eAAO,MAAM,gBAAgB,MAAM,CAAC;AACpC,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAC3C,eAAO,MAAM,aAAa,YAAI,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAU,CAAC;AAEzE,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,eAAO,MAAM,mBAAmB,uCAAuC,CAAC;AACxE,eAAO,MAAM,mBAAmB,6CAA6C,CAAC;AAC9E,eAAO,MAAM,oBAAoB,wCAAwC,CAAC;AAC1E,eAAO,MAAM,kBAAkB,4CAA4C,CAAC;AAC5E,eAAO,MAAM,sBAAsB,yCAAyC,CAAC;AAC7E,eAAO,MAAM,uBAAuB,gDAAgD,CAAC;AACrF,eAAO,MAAM,oBAAoB,6DAA6D,CAAC;AAC/F,eAAO,MAAM,uBAAuB,yCAAyC,CAAC;AAC9E,eAAO,MAAM,kBAAkB,6CAA6C,CAAC;AAC7E,eAAO,MAAM,wBAAwB,oDAAoD,CAAC;AAC1F,eAAO,MAAM,uBAAuB,0CAA0C,CAAC;AAE/E;;;;GAIG;AACH,eAAO,MAAM,aAAa,4CAA4C,CAAC"}
+{"version":3,"file":"caps.d.ts","sourceRoot":"","sources":["../src/caps.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,UAAU,IAAI,CAAC;AAC5B,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAClC,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,eAAe,KAAK,CAAC;AAClC,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,eAAO,MAAM,gBAAgB,MAAM,CAAC;AACpC,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAC3C,eAAO,MAAM,sBAAsB,KAAK,CAAC;AACzC,eAAO,MAAM,kBAAkB,OAAO,CAAC;AACvC,eAAO,MAAM,aAAa,YAAI,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,CAAU,CAAC;AAEjF,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,eAAO,MAAM,mBAAmB,uCAAuC,CAAC;AACxE,eAAO,MAAM,mBAAmB,6CAA6C,CAAC;AAC9E,eAAO,MAAM,oBAAoB,wCAAwC,CAAC;AAC1E,eAAO,MAAM,kBAAkB,4CAA4C,CAAC;AAC5E,eAAO,MAAM,sBAAsB,yCAAyC,CAAC;AAC7E,eAAO,MAAM,uBAAuB,gDAAgD,CAAC;AACrF,eAAO,MAAM,oBAAoB,mEACiC,CAAC;AACnE,eAAO,MAAM,kBAAkB,6CAA6C,CAAC;AAC7E,eAAO,MAAM,wBAAwB,oDAAoD,CAAC;AAC1F,eAAO,MAAM,uBAAuB,0CAA0C,CAAC;AAE/E;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,wCAAwC,CAAC;AAC5E,eAAO,MAAM,qBAAqB,0CAA2D,CAAC;AAC9F,eAAO,MAAM,2BAA2B,8BAA8B,CAAC;AACvE,eAAO,MAAM,0BAA0B,qCAAqC,CAAC;AAC7E,eAAO,MAAM,wBAAwB,6CAA6C,CAAC;AACnF,eAAO,MAAM,2BAA2B,4CAA4C,CAAC;AACrF,eAAO,MAAM,2BAA2B,oDAAoD,CAAC;AAC7F,eAAO,MAAM,8BAA8B,+BAA+B,CAAC;AAE3E;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,oFAC8C,CAAC;AAEpF;;;;GAIG;AACH,eAAO,MAAM,aAAa,4CAA4C,CAAC;AAEvE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,0CAA0C,CAAC"}

package/dist/caps.js

@@ -14,22 +14,58 @@ export const MAX_LABEL_RUNES = 24;
 export const MAX_BUTTON_ID_LENGTH = 32;
 export const MAX_TITLE_LENGTH = 256;
 export const MAX_DESCRIPTION_LENGTH = 1024;
-export const BUTTON_STYLES = ['primary', 'secondary', 'danger'];
+export const MAX_BUTTON_EMOJI_RUNES = 16;
+export const MAX_LINK_URL_RUNES = 2048;
+export const BUTTON_STYLES = ['primary', 'secondary', 'danger', 'link'];
 export const CAP_TOO_MANY_EMBEDS = 'a message carries at most 3 embeds';
 export const CAP_TOO_MANY_FIELDS = 'a message carries at most 6 embed fields';
 export const CAP_TOO_MANY_BUTTONS = 'a message carries at most 5 buttons';
 export const CAP_LABEL_TOO_LONG = 'a button label is at most 24 characters';
 export const CAP_BUTTON_ID_TOO_LONG = 'a button id is at most 32 characters';
 export const CAP_DUPLICATE_BUTTON_ID = 'a button id must be unique within a message';
-export const CAP_BAD_BUTTON_STYLE = 'a button style must be one of primary, secondary, danger';
-export const CAP_LINK_STYLE_DEFERRED = 'link buttons are not supported in v1';
+export const CAP_BAD_BUTTON_STYLE = 'a button style must be one of primary, secondary, danger, link';
 export const CAP_TITLE_TOO_LONG = 'an embed title is at most 256 characters';
 export const CAP_DESCRIPTION_TOO_LONG = 'an embed description is at most 1024 characters';
 export const CAP_IMAGE_URL_NOT_HTTPS = 'an image url must start with https://';
+/**
+ * AMENDMENT-06 §5. Link targets live in structured fields, never in prose,
+ * and they answer a link mistake with a link sentence: `an image url ...`
+ * would tell a bot author to fix the wrong thing. The one sentence that
+ * names a number renders it from `MAX_LINK_URL_RUNES`, exactly as the
+ * label and title caps above render theirs, because the server's template
+ * refuses a digit literal.
+ */
+export const CAP_LINK_URL_NOT_HTTPS = 'a link url must start with https://';
+export const CAP_LINK_URL_TOO_LONG = `a link url is at most ${MAX_LINK_URL_RUNES} characters`;
+export const CAP_LINK_BUTTON_MISSING_URL = 'a link button needs a url';
+export const CAP_URL_ON_NON_LINK_BUTTON = 'only a link button carries a url';
+export const CAP_INVALID_BUTTON_EMOJI = 'a button emoji is a single unicode emoji';
+export const CAP_EMBED_URL_WITHOUT_TITLE = 'an embed url needs a title to attach to';
+export const CAP_AUTHOR_URL_WITHOUT_NAME = 'an author url needs an author name to attach to';
+export const CAP_EMBED_FOOTER_TEXT_REQUIRED = 'an embed footer needs text';
+/**
+ * The server's `button_missing_field` sentence, rendered for the one field
+ * an SDK caller can actually leave empty. AMENDMENT-06 §3 keeps the label
+ * required so an emoji-only pill cannot ship: a pill with no words is
+ * unreadable to a screen reader and unguessable to everyone else.
+ */
+export const CAP_BUTTON_MISSING_LABEL = 'Every button needs `label`. A button without one cannot be rendered or pressed.';
 /**
  * The SDK's own precondition, not one of the server's cap sentences: a send
  * with no text, no embeds and no buttons has nothing to deliver, so it is
  * 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';
 //# 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,aAAa,GAAG,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAU,CAAC;AAIzE,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,GAAG,0DAA0D,CAAC;AAC/F,MAAM,CAAC,MAAM,uBAAuB,GAAG,sCAAsC,CAAC;AAC9E,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;;;;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"}

package/dist/embeds.d.ts

@@ -1,5 +1,7 @@
 /**
- * Discord-shaped `Embed` and `Button` builders (AMENDMENT-05). Mirrors
+ * Discord-shaped `Embed` and `Button` builders (AMENDMENT-05, extended by
+ * AMENDMENT-06 with a footer icon, a button emoji and the three structured
+ * link targets). Mirrors
  * python's builders field for field; the wire shape and every cap sentence
  * are contractual (`caps.ts`) and must not drift between the two SDKs.
  *
@@ -23,6 +25,7 @@ export interface EmbedFieldValue {
 export interface EmbedAuthorValue {
     name: string;
     icon?: string;
+    url?: string;
 }
 export interface EmbedThumbnailValue {
     url: string;
@@ -32,11 +35,13 @@ export interface EmbedImageValue {
 }
 export interface EmbedFooterValue {
     text: string;
+    icon?: string;
 }
 export interface EmbedInit {
     title?: string;
     description?: string;
     color?: string;
+    url?: string;
 }
 /**
  * `Embed().addField(...)` builder. Every mutation is validated immediately
@@ -48,6 +53,7 @@ export declare class Embed {
     title?: string;
     description?: string;
     color?: string;
+    url?: string;
     author?: EmbedAuthorValue;
     thumbnail?: EmbedThumbnailValue;
     image?: EmbedImageValue;
@@ -57,10 +63,10 @@ export declare class Embed {
     constructor(init?: EmbedInit);
     /** Refuses the 7th field on ONE embed — the whole-message cap (summed across embeds) is enforced by `serialiseEmbeds`. */
     addField(name: string, value: string, inline?: boolean): this;
-    setAuthor(name: string, icon?: string): this;
+    setAuthor(name: string, icon?: string, url?: string): this;
     setThumbnail(url: string): this;
     setImage(url: string): this;
-    setFooter(text: string): this;
+    setFooter(text: string, icon?: string): this;
     /** A `Date` becomes UTC RFC3339 (`Z`); a string is assumed already in that form. */
     setTimestamp(value: Date | string): this;
     toJSON(): Record<string, unknown>;
@@ -76,13 +82,30 @@ export interface ButtonInit {
     label: string;
     id?: string;
     style?: string;
+    emoji?: string;
+    url?: string;
 }
 /** `new Button({ label: 'Pacific' })` — `id` defaults to a slug of `label`, `style` defaults to `'primary'`. */
 export declare class Button {
     label: string;
     id: string;
     style: string;
+    emoji?: string;
+    url?: string;
     constructor(init: ButtonInit);
+    /**
+     * The sanctioned way to build a link pill (AMENDMENT-06 §11): a url is not
+     * optional here, so the shape that raises `a link button needs a url` is
+     * one a caller has to go out of their way to write. A tap opens the url on
+     * the device and stops — a link button never round-trips as `button.pressed`
+     * and never flips the row.
+     */
+    static link(init: {
+        label: string;
+        url: string;
+        id?: string;
+        emoji?: string;
+    }): Button;
     toJSON(): Record<string, unknown>;
     /** Tolerant decode — never throws. See `Embed.fromJSON` for why. */
     static fromJSON(data: unknown): Button;

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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"}