privage.js 0.21.0

package/dist/components.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Message components (buttons + select menus) + fluent builders. Bot-only,
+ * like embeds — but the server REJECTS invalid components (400) instead of
+ * dropping them, and these builders throw the same complaints at build time.
+ *
+ * Row grammar (interactions v2): a row holds EITHER ≤5 buttons OR exactly
+ * one select. Wire shape:
+ *   components: [
+ *     { type: 'row', components: [
+ *       { type: 'button', style: 'primary', label: 'Claim', custom_id: 'ticket:claim:42' },
+ *       { type: 'button', style: 'link',    label: 'Logs',  url: 'https://...' },
+ *     ]},
+ *     { type: 'row', components: [
+ *       { type: 'select', custom_id: 'ticket:severity', placeholder: 'Severity',
+ *         options: [{ label: 'Low', value: 'low' }] },
+ *     ]},
+ *   ]
+ */
+export type ButtonStyle = 'primary' | 'secondary' | 'success' | 'danger' | 'link';
+/** discord.js-style constants for {@link ButtonStyle} — `setStyle(ButtonStyle.Primary)` ports verbatim. */
+export declare const ButtonStyle: {
+    readonly Primary: "primary";
+    readonly Secondary: "secondary";
+    readonly Success: "success";
+    readonly Danger: "danger";
+    readonly Link: "link";
+};
+/** Server-enforced component limits (mirrored client-side). */
+export declare const ComponentLimits: {
+    readonly RowsPerMessage: 5;
+    readonly ButtonsPerRow: 5;
+    /** Interactive components per message (a select counts as 1). */
+    readonly ButtonsPerMessage: 25;
+    readonly Label: 80;
+    readonly CustomId: 100;
+    readonly Emoji: 32;
+    readonly SelectPlaceholder: 150;
+    /** Options per select menu. */
+    readonly SelectOptions: 25;
+    /** Ceiling for `min_values`/`max_values`. */
+    readonly SelectValues: 25;
+    readonly OptionLabel: 100;
+    readonly OptionValue: 100;
+    readonly OptionDescription: 100;
+    readonly OptionEmoji: 8;
+};
+export interface Button {
+    type: 'button';
+    style: ButtonStyle;
+    /** ≤80 chars. Optional only for emoji-only buttons. */
+    label?: string;
+    /** Unicode emoji shown before the label (≤32 chars). */
+    emoji?: string;
+    /** Required for non-link styles (≤100 chars, unique per message). Round-trips in the interaction event. */
+    custom_id?: string;
+    /** Required for (and exclusive to) link-style buttons. */
+    url?: string;
+    disabled?: boolean;
+}
+/** One option in a select menu. */
+export interface SelectOption {
+    /** ≤100 chars. */
+    label: string;
+    /** ≤100 chars, unique within the select. Round-trips in `interaction.values`. */
+    value: string;
+    /** Muted second line under the label (≤100 chars). */
+    description?: string;
+    /** Unicode emoji shown before the label (≤8 chars). */
+    emoji?: string;
+    /** Pre-selected when the menu renders. */
+    default?: boolean;
+}
+export interface SelectMenu {
+    type: 'select';
+    /** ≤100 chars, unique per message across ALL components. */
+    custom_id: string;
+    /** ≤150 chars. */
+    placeholder?: string;
+    /** 0–25 (server default 1). */
+    min_values?: number;
+    /** 1–25, ≥ min_values (server default 1). */
+    max_values?: number;
+    disabled?: boolean;
+    /** 1–25 options. */
+    options: SelectOption[];
+}
+export interface ActionRow {
+    type: 'row';
+    /** Either ≤5 buttons or exactly one select — never both. */
+    components: (Button | SelectMenu)[];
+}
+export declare class ButtonBuilder {
+    private readonly data;
+    setStyle(style: ButtonStyle): this;
+    /** ≤80 chars. */
+    setLabel(label: string): this;
+    /** Unicode emoji (≤32 chars) — allows emoji-only buttons with no label. */
+    setEmoji(emoji: string): this;
+    /** Your opaque click identifier (≤100 chars) — comes back on the `interaction` event. Non-link styles only. */
+    setCustomId(customId: string): this;
+    /** Link-style buttons only — opens the URL, no interaction event. */
+    setURL(url: string): this;
+    setDisabled(disabled?: boolean): this;
+    toJSON(): Button;
+}
+/**
+ * Fluent select-menu builder. Mirrors the server's select grammar — throws
+ * at build time where the server would 400.
+ */
+export declare class SelectMenuBuilder {
+    private readonly data;
+    private readonly options;
+    /** Your opaque identifier (≤100 chars, unique per message) — comes back on the `interaction` event. */
+    setCustomId(customId: string): this;
+    /** Hint text shown while nothing is selected (≤150 chars). */
+    setPlaceholder(placeholder: string): this;
+    /** Minimum selections (0–25; server default 1). */
+    setMinValues(min: number): this;
+    /** Maximum selections (1–25, ≥ min_values; server default 1). */
+    setMaxValues(max: number): this;
+    setDisabled(disabled?: boolean): this;
+    /** Append options (≤25 total; label/value ≤100, values unique). */
+    addOptions(...options: SelectOption[]): this;
+    toJSON(): SelectMenu;
+}
+/**
+ * A row holds EITHER up to 5 buttons OR exactly one select — the builder
+ * enforces the same exclusivity the server does.
+ */
+export declare class ActionRowBuilder {
+    private readonly buttons;
+    private select;
+    addButtons(...buttons: (Button | ButtonBuilder)[]): this;
+    /** Put a select menu in the row — it must be the row's only component. */
+    addSelect(select: SelectMenu | SelectMenuBuilder): this;
+    toJSON(): ActionRow;
+}

package/dist/components.js

@@ -0,0 +1,226 @@
+"use strict";
+/**
+ * Message components (buttons + select menus) + fluent builders. Bot-only,
+ * like embeds — but the server REJECTS invalid components (400) instead of
+ * dropping them, and these builders throw the same complaints at build time.
+ *
+ * Row grammar (interactions v2): a row holds EITHER ≤5 buttons OR exactly
+ * one select. Wire shape:
+ *   components: [
+ *     { type: 'row', components: [
+ *       { type: 'button', style: 'primary', label: 'Claim', custom_id: 'ticket:claim:42' },
+ *       { type: 'button', style: 'link',    label: 'Logs',  url: 'https://...' },
+ *     ]},
+ *     { type: 'row', components: [
+ *       { type: 'select', custom_id: 'ticket:severity', placeholder: 'Severity',
+ *         options: [{ label: 'Low', value: 'low' }] },
+ *     ]},
+ *   ]
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActionRowBuilder = exports.SelectMenuBuilder = exports.ButtonBuilder = exports.ComponentLimits = exports.ButtonStyle = void 0;
+/** discord.js-style constants for {@link ButtonStyle} — `setStyle(ButtonStyle.Primary)` ports verbatim. */
+exports.ButtonStyle = {
+    Primary: 'primary',
+    Secondary: 'secondary',
+    Success: 'success',
+    Danger: 'danger',
+    Link: 'link',
+};
+/** Server-enforced component limits (mirrored client-side). */
+exports.ComponentLimits = {
+    RowsPerMessage: 5,
+    ButtonsPerRow: 5,
+    /** Interactive components per message (a select counts as 1). */
+    ButtonsPerMessage: 25,
+    Label: 80,
+    CustomId: 100,
+    Emoji: 32,
+    SelectPlaceholder: 150,
+    /** Options per select menu. */
+    SelectOptions: 25,
+    /** Ceiling for `min_values`/`max_values`. */
+    SelectValues: 25,
+    OptionLabel: 100,
+    OptionValue: 100,
+    OptionDescription: 100,
+    OptionEmoji: 8,
+};
+function assertLength(what, value, max, kind = 'Button') {
+    if (value.length === 0 || value.length > max) {
+        throw new RangeError(`${kind} ${what} must be 1–${max} characters (got ${value.length}).`);
+    }
+    return value;
+}
+class ButtonBuilder {
+    constructor() {
+        this.data = { type: 'button' };
+    }
+    setStyle(style) {
+        this.data.style = style;
+        return this;
+    }
+    /** ≤80 chars. */
+    setLabel(label) {
+        this.data.label = assertLength('label', label, exports.ComponentLimits.Label);
+        return this;
+    }
+    /** Unicode emoji (≤32 chars) — allows emoji-only buttons with no label. */
+    setEmoji(emoji) {
+        this.data.emoji = assertLength('emoji', emoji, exports.ComponentLimits.Emoji);
+        return this;
+    }
+    /** Your opaque click identifier (≤100 chars) — comes back on the `interaction` event. Non-link styles only. */
+    setCustomId(customId) {
+        this.data.custom_id = assertLength('custom_id', customId, exports.ComponentLimits.CustomId);
+        return this;
+    }
+    /** Link-style buttons only — opens the URL, no interaction event. */
+    setURL(url) {
+        this.data.url = url;
+        return this;
+    }
+    setDisabled(disabled = true) {
+        this.data.disabled = disabled;
+        return this;
+    }
+    toJSON() {
+        const d = this.data;
+        if (!d.style)
+            throw new RangeError('Button style is required — call setStyle().');
+        if (d.label === undefined && d.emoji === undefined) {
+            throw new RangeError('Buttons need a label (or an emoji for emoji-only buttons).');
+        }
+        if (d.style === 'link') {
+            if (d.custom_id !== undefined)
+                throw new RangeError('Link buttons must not carry a custom_id.');
+            if (!d.url)
+                throw new RangeError('Link buttons require a URL — call setURL().');
+        }
+        else {
+            if (d.url !== undefined)
+                throw new RangeError('Only link buttons may carry a URL.');
+            if (!d.custom_id)
+                throw new RangeError('Non-link buttons require a custom_id — call setCustomId().');
+        }
+        return { ...d };
+    }
+}
+exports.ButtonBuilder = ButtonBuilder;
+/**
+ * Fluent select-menu builder. Mirrors the server's select grammar — throws
+ * at build time where the server would 400.
+ */
+class SelectMenuBuilder {
+    constructor() {
+        this.data = { type: 'select' };
+        this.options = [];
+    }
+    /** Your opaque identifier (≤100 chars, unique per message) — comes back on the `interaction` event. */
+    setCustomId(customId) {
+        this.data.custom_id = assertLength('custom_id', customId, exports.ComponentLimits.CustomId, 'Select');
+        return this;
+    }
+    /** Hint text shown while nothing is selected (≤150 chars). */
+    setPlaceholder(placeholder) {
+        this.data.placeholder = assertLength('placeholder', placeholder, exports.ComponentLimits.SelectPlaceholder, 'Select');
+        return this;
+    }
+    /** Minimum selections (0–25; server default 1). */
+    setMinValues(min) {
+        if (!Number.isInteger(min) || min < 0 || min > exports.ComponentLimits.SelectValues) {
+            throw new RangeError(`Select min_values must be an integer between 0 and ${exports.ComponentLimits.SelectValues} (got ${min}).`);
+        }
+        this.data.min_values = min;
+        return this;
+    }
+    /** Maximum selections (1–25, ≥ min_values; server default 1). */
+    setMaxValues(max) {
+        if (!Number.isInteger(max) || max < 1 || max > exports.ComponentLimits.SelectValues) {
+            throw new RangeError(`Select max_values must be an integer between 1 and ${exports.ComponentLimits.SelectValues} (got ${max}).`);
+        }
+        this.data.max_values = max;
+        return this;
+    }
+    setDisabled(disabled = true) {
+        this.data.disabled = disabled;
+        return this;
+    }
+    /** Append options (≤25 total; label/value ≤100, values unique). */
+    addOptions(...options) {
+        for (const option of options) {
+            if (this.options.length >= exports.ComponentLimits.SelectOptions) {
+                throw new RangeError(`Selects hold at most ${exports.ComponentLimits.SelectOptions} options.`);
+            }
+            assertLength('option label', option.label, exports.ComponentLimits.OptionLabel, 'Select');
+            assertLength('option value', option.value, exports.ComponentLimits.OptionValue, 'Select');
+            if (option.description !== undefined)
+                assertLength('option description', option.description, exports.ComponentLimits.OptionDescription, 'Select');
+            if (option.emoji !== undefined)
+                assertLength('option emoji', option.emoji, exports.ComponentLimits.OptionEmoji, 'Select');
+            if (this.options.some((o) => o.value === option.value)) {
+                throw new RangeError(`Select option value "${option.value}" is duplicated — values must be unique within the select.`);
+            }
+            this.options.push({ ...option });
+        }
+        return this;
+    }
+    toJSON() {
+        const d = this.data;
+        if (!d.custom_id)
+            throw new RangeError('Selects require a custom_id — call setCustomId().');
+        if (this.options.length === 0)
+            throw new RangeError('Select has no options — add at least one with addOptions().');
+        const min = d.min_values ?? 1;
+        const max = d.max_values ?? 1;
+        if (max < min) {
+            throw new RangeError(`Select max_values (${max}) must be greater than or equal to min_values (${min}).`);
+        }
+        return { ...d, options: this.options.map((o) => ({ ...o })) };
+    }
+}
+exports.SelectMenuBuilder = SelectMenuBuilder;
+/**
+ * A row holds EITHER up to 5 buttons OR exactly one select — the builder
+ * enforces the same exclusivity the server does.
+ */
+class ActionRowBuilder {
+    constructor() {
+        this.buttons = [];
+        this.select = null;
+    }
+    addButtons(...buttons) {
+        if (this.select) {
+            throw new RangeError('A row holds either buttons or a single select — this row already has a select.');
+        }
+        for (const button of buttons) {
+            const resolved = button instanceof ButtonBuilder ? button.toJSON() : button;
+            if (this.buttons.length >= exports.ComponentLimits.ButtonsPerRow) {
+                throw new RangeError(`Action rows hold at most ${exports.ComponentLimits.ButtonsPerRow} buttons.`);
+            }
+            this.buttons.push(resolved);
+        }
+        return this;
+    }
+    /** Put a select menu in the row — it must be the row's only component. */
+    addSelect(select) {
+        if (this.buttons.length > 0) {
+            throw new RangeError('A row holds either buttons or a single select — this row already has buttons.');
+        }
+        if (this.select) {
+            throw new RangeError('A row holds exactly one select.');
+        }
+        this.select = select instanceof SelectMenuBuilder ? select.toJSON() : select;
+        return this;
+    }
+    toJSON() {
+        if (this.select) {
+            return { type: 'row', components: [{ ...this.select, options: this.select.options.map((o) => ({ ...o })) }] };
+        }
+        if (this.buttons.length === 0) {
+            throw new RangeError('Action row is empty — add at least one button or a select.');
+        }
+        return { type: 'row', components: this.buttons.map((b) => ({ ...b })) };
+    }
+}
+exports.ActionRowBuilder = ActionRowBuilder;

package/dist/embeds.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Typed embeds + a fluent EmbedBuilder (discord.js-style). Embeds are
+ * bot-only. The wire shape below is exactly what the backend's embed
+ * validator accepts; limits mirror the server's, but the builder throws at
+ * build time where the server would silently truncate or drop.
+ */
+/** Server-enforced embed limits (mirrored client-side; see embedValidator). */
+export declare const EmbedLimits: {
+    /** Max embeds per message. */
+    readonly EmbedsPerMessage: 10;
+    readonly Title: 256;
+    readonly Description: 4096;
+    readonly AuthorName: 256;
+    readonly FieldName: 256;
+    readonly FieldValue: 1024;
+    readonly Fields: 25;
+    readonly FooterText: 2048;
+};
+export interface EmbedField {
+    name: string;
+    value: string;
+    inline?: boolean;
+}
+export interface EmbedAuthor {
+    name: string;
+    /** Small icon next to the author name. */
+    icon_url?: string;
+    url?: string;
+}
+export interface EmbedFooter {
+    text: string;
+    icon_url?: string;
+}
+/** The wire embed shape the backend accepts. */
+export interface Embed {
+    title?: string;
+    description?: string;
+    url?: string;
+    /** `0xRRGGBB` number or a hex string like `'#35b9e8'` — both accepted. */
+    color?: number | string;
+    author?: EmbedAuthor;
+    footer?: EmbedFooter;
+    fields?: EmbedField[];
+    image?: {
+        url: string;
+    };
+    thumbnail?: {
+        url: string;
+    };
+    /** ISO timestamp shown in the footer area. */
+    timestamp?: string;
+}
+/**
+ * Fluent embed builder. `JSON.stringify` picks up `toJSON()` automatically,
+ * so builders can be passed straight into `embeds: [...]` without unwrapping.
+ *
+ * Note: the client renders a single image slot — if both are set,
+ * `thumbnail` wins over `image`.
+ */
+export declare class EmbedBuilder {
+    private readonly data;
+    /** ≤256 chars. */
+    setTitle(title: string): this;
+    /** ≤4096 chars. */
+    setDescription(description: string): this;
+    /** Makes the title a link. */
+    setURL(url: string): this;
+    /** `0xRRGGBB` number (e.g. `0x35b9e8`), hex string (`'#35b9e8'`), or `[r, g, b]` tuple (discord.js-style). */
+    setColor(color: number | string | [number, number, number]): this;
+    /** Author line above the title. `name` ≤256 chars. (`iconURL` accepted as a discord.js-style alias.) */
+    setAuthor(author: {
+        name: string;
+        iconUrl?: string;
+        iconURL?: string;
+        url?: string;
+    }): this;
+    /** Footer line. `text` ≤2048 chars. (`iconURL` accepted as a discord.js-style alias.) */
+    setFooter(footer: {
+        text: string;
+        iconUrl?: string;
+        iconURL?: string;
+    }): this;
+    /** Append fields (≤25 total; name ≤256, value ≤1024 each). Accepts spread or a single array (discord.js-style). */
+    addFields(...fields: (EmbedField | EmbedField[])[]): this;
+    /** Replace all fields. Accepts spread or a single array. */
+    setFields(...fields: (EmbedField | EmbedField[])[]): this;
+    setImage(url: string): this;
+    /** Renders in the same single image slot; wins over `setImage`. */
+    setThumbnail(url: string): this;
+    /** Defaults to now. */
+    setTimestamp(timestamp?: Date | number | string): this;
+    /**
+     * The plain wire object. Throws if the embed is empty (the server would
+     * silently drop it — fail loud instead).
+     */
+    toJSON(): Embed;
+}

package/dist/embeds.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * Typed embeds + a fluent EmbedBuilder (discord.js-style). Embeds are
+ * bot-only. The wire shape below is exactly what the backend's embed
+ * validator accepts; limits mirror the server's, but the builder throws at
+ * build time where the server would silently truncate or drop.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmbedBuilder = exports.EmbedLimits = void 0;
+/** Server-enforced embed limits (mirrored client-side; see embedValidator). */
+exports.EmbedLimits = {
+    /** Max embeds per message. */
+    EmbedsPerMessage: 10,
+    Title: 256,
+    Description: 4096,
+    AuthorName: 256,
+    FieldName: 256,
+    FieldValue: 1024,
+    Fields: 25,
+    FooterText: 2048,
+};
+function assertLength(what, value, max) {
+    if (value.length > max) {
+        throw new RangeError(`Embed ${what} exceeds ${max} characters (got ${value.length}).`);
+    }
+    return value;
+}
+/**
+ * Fluent embed builder. `JSON.stringify` picks up `toJSON()` automatically,
+ * so builders can be passed straight into `embeds: [...]` without unwrapping.
+ *
+ * Note: the client renders a single image slot — if both are set,
+ * `thumbnail` wins over `image`.
+ */
+class EmbedBuilder {
+    constructor() {
+        this.data = {};
+    }
+    /** ≤256 chars. */
+    setTitle(title) {
+        this.data.title = assertLength('title', title, exports.EmbedLimits.Title);
+        return this;
+    }
+    /** ≤4096 chars. */
+    setDescription(description) {
+        this.data.description = assertLength('description', description, exports.EmbedLimits.Description);
+        return this;
+    }
+    /** Makes the title a link. */
+    setURL(url) {
+        this.data.url = url;
+        return this;
+    }
+    /** `0xRRGGBB` number (e.g. `0x35b9e8`), hex string (`'#35b9e8'`), or `[r, g, b]` tuple (discord.js-style). */
+    setColor(color) {
+        this.data.color = Array.isArray(color)
+            ? ((color[0] & 0xff) << 16) | ((color[1] & 0xff) << 8) | (color[2] & 0xff)
+            : color;
+        return this;
+    }
+    /** Author line above the title. `name` ≤256 chars. (`iconURL` accepted as a discord.js-style alias.) */
+    setAuthor(author) {
+        const icon = author.iconUrl ?? author.iconURL;
+        this.data.author = {
+            name: assertLength('author name', author.name, exports.EmbedLimits.AuthorName),
+            ...(icon ? { icon_url: icon } : {}),
+            ...(author.url ? { url: author.url } : {}),
+        };
+        return this;
+    }
+    /** Footer line. `text` ≤2048 chars. (`iconURL` accepted as a discord.js-style alias.) */
+    setFooter(footer) {
+        const icon = footer.iconUrl ?? footer.iconURL;
+        this.data.footer = {
+            text: assertLength('footer text', footer.text, exports.EmbedLimits.FooterText),
+            ...(icon ? { icon_url: icon } : {}),
+        };
+        return this;
+    }
+    /** Append fields (≤25 total; name ≤256, value ≤1024 each). Accepts spread or a single array (discord.js-style). */
+    addFields(...fields) {
+        const flat = fields.flat();
+        const next = [...(this.data.fields ?? []), ...flat];
+        if (next.length > exports.EmbedLimits.Fields) {
+            throw new RangeError(`Embeds support at most ${exports.EmbedLimits.Fields} fields (got ${next.length}).`);
+        }
+        this.data.fields = next.map((f) => ({
+            name: assertLength('field name', f.name, exports.EmbedLimits.FieldName),
+            value: assertLength('field value', f.value, exports.EmbedLimits.FieldValue),
+            inline: !!f.inline,
+        }));
+        return this;
+    }
+    /** Replace all fields. Accepts spread or a single array. */
+    setFields(...fields) {
+        this.data.fields = undefined;
+        return fields.length ? this.addFields(...fields) : this;
+    }
+    setImage(url) {
+        this.data.image = { url };
+        return this;
+    }
+    /** Renders in the same single image slot; wins over `setImage`. */
+    setThumbnail(url) {
+        this.data.thumbnail = { url };
+        return this;
+    }
+    /** Defaults to now. */
+    setTimestamp(timestamp = new Date()) {
+        this.data.timestamp = new Date(timestamp).toISOString();
+        return this;
+    }
+    /**
+     * The plain wire object. Throws if the embed is empty (the server would
+     * silently drop it — fail loud instead).
+     */
+    toJSON() {
+        const d = this.data;
+        if (!d.title && !d.description && !d.fields?.length && !d.image?.url && !d.thumbnail?.url) {
+            throw new RangeError('Embed is empty — set at least a title, description, field, or image before sending.');
+        }
+        return { ...d, ...(d.fields ? { fields: d.fields.map((f) => ({ ...f })) } : {}) };
+    }
+}
+exports.EmbedBuilder = EmbedBuilder;

package/dist/errors.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Typed errors surfaced by the SDK. Bot authors branch on these instead of
+ * inspecting HTTP status codes. See the protocol spec §12 "Error taxonomy".
+ */
+export declare class PrivageError extends Error {
+    constructor(message: string);
+}
+/** 401/403 auth — bad or rotated token, or a non-bot account. Terminal: `login()` rejects and does not retry. */
+export declare class PrivageAuthError extends PrivageError {
+}
+/** 403 on an action — missing channel permission, not a member, or the bot was kicked. Thrown from `reply()`/`send()`. */
+export declare class PrivagePermissionError extends PrivageError {
+}
+/**
+ * Network-level failure. Two paths: emitted as `connectionError` for WS
+ * transport failures/heartbeat timeouts (recoverable — the SDK
+ * auto-reconnects), AND thrown from any REST-backed call whose fetch fails
+ * or times out (not retried — the caller decides).
+ */
+export declare class PrivageConnectionError extends PrivageError {
+}
+/** 429 + slowmode + mention limits. `retryAfter` is milliseconds. */
+export declare class PrivageRateLimitError extends PrivageError {
+    readonly retryAfter: number;
+    constructor(message: string, retryAfter: number);
+}
+/** Any other non-2xx REST response. */
+export declare class PrivageHTTPError extends PrivageError {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}

package/dist/errors.js

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * Typed errors surfaced by the SDK. Bot authors branch on these instead of
+ * inspecting HTTP status codes. See the protocol spec §12 "Error taxonomy".
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PrivageHTTPError = exports.PrivageRateLimitError = exports.PrivageConnectionError = exports.PrivagePermissionError = exports.PrivageAuthError = exports.PrivageError = void 0;
+class PrivageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+exports.PrivageError = PrivageError;
+/** 401/403 auth — bad or rotated token, or a non-bot account. Terminal: `login()` rejects and does not retry. */
+class PrivageAuthError extends PrivageError {
+}
+exports.PrivageAuthError = PrivageAuthError;
+/** 403 on an action — missing channel permission, not a member, or the bot was kicked. Thrown from `reply()`/`send()`. */
+class PrivagePermissionError extends PrivageError {
+}
+exports.PrivagePermissionError = PrivagePermissionError;
+/**
+ * Network-level failure. Two paths: emitted as `connectionError` for WS
+ * transport failures/heartbeat timeouts (recoverable — the SDK
+ * auto-reconnects), AND thrown from any REST-backed call whose fetch fails
+ * or times out (not retried — the caller decides).
+ */
+class PrivageConnectionError extends PrivageError {
+}
+exports.PrivageConnectionError = PrivageConnectionError;
+/** 429 + slowmode + mention limits. `retryAfter` is milliseconds. */
+class PrivageRateLimitError extends PrivageError {
+    constructor(message, retryAfter) {
+        super(message);
+        this.retryAfter = retryAfter;
+    }
+}
+exports.PrivageRateLimitError = PrivageRateLimitError;
+/** Any other non-2xx REST response. */
+class PrivageHTTPError extends PrivageError {
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+    }
+}
+exports.PrivageHTTPError = PrivageHTTPError;

package/dist/formatters.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Message formatting helpers. Mention syntax matches the wire format the
+ * backend parses and the client renders: `<@userId>`, `<@&roleId>`,
+ * `<#channelId>`, plus the `@everyone` / `@here` broadcasts (rate-limited
+ * server-side). The rest is standard markdown.
+ */
+export declare function userMention(userId: string): string;
+export declare function roleMention(roleId: string): string;
+export declare function channelMention(channelId: string): string;
+export declare const everyone = "@everyone";
+export declare const here = "@here";
+export declare function bold(text: string): string;
+export declare function italic(text: string): string;
+export declare function strikethrough(text: string): string;
+export declare function inlineCode(text: string): string;
+export declare function codeBlock(content: string, language?: string): string;