lunibee 0.1.7 → 0.2.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Ekretos
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Ekretos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,223 +1,225 @@
-# Lunibee 🐝
-
-[![npm version](https://badge.fury.io/js/lunibee.svg)](https://www.npmjs.com/package/lunibee)
-[![NPM Downloads](https://img.shields.io/npm/dt/lunibee.svg?style=flat-square)](https://www.npmjs.com/package/lunibee)
-[![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/SSADgyBpgw)
-
-[![NPM Graph](https://nodei.co/npm/lunibee.png?downloads=true&downloadRank=true&stars=true)](https://www.npmjs.com/package/lunibee)
-
-A lightweight, Bun-first Discord API library for TypeScript.
-
-## Requirements
-
-- [Bun](https://bun.sh/) for the supported runtime and package manager
-- TypeScript for typed application development
-- A Discord bot token for connecting to Discord
-
-## Installation
-
-For repository development:
-
-```bash
-bun install
-```
-
-For application usage, install the published `lunibee` package when a release is available:
-
-```bash
-bun add lunibee
-```
-
-## Documentation
-
-Full documentation, practical guides, and API references are available at **[lunibee.js.org](https://lunibee.js.org)**.
-
-## Getting started
-
-```ts
-import { Client, GatewayIntentBits } from "lunibee";
-
-const client = new Client({
-    token: process.env.DISCORD_TOKEN!,
-    intents: GatewayIntentBits.Guilds | GatewayIntentBits.GuildMessages
-});
-
-client.on("ready", user => {
-    console.log(`Ready as ${user.username}`);
-});
-
-client.on("messageCreate", message => {
-    console.log(message.content);
-});
-
-await client.login();
-```
-
-Destroy the client when the application is shutting down:
-
-```ts
-client.destroy();
-```
-
-## Client
-
-`Client` is the main application entry point. It coordinates the REST transport, resource managers, Gateway, event dispatch, interactions, and lifecycle state.
-
-### Lifecycle
-
-```text
-idle → connecting → ready
-  ↑                 ↓
-  └──── reconnect ──┘
-
-ready → destroyed
-```
-
-Useful APIs include:
-
-- `client.login()` — authenticate and connect to Discord.
-- `client.isReady()` — type guard for a ready client.
-- `client.destroy()` — close the Gateway and clear client-managed resources.
-- `client.rest` — access the REST transport.
-- `client.users`, `client.guilds`, `client.channels` — resource managers.
-
-## Gateway
-
-The Gateway package implements the Discord WebSocket lifecycle:
-
-```text
-CONNECT → HELLO → IDENTIFY/RESUME → READY → DISPATCH
-                              ↘ HEARTBEAT / ACK
-                                      ↓
-                                  RECONNECT
-```
-
-The Gateway tracks sequence numbers and sessions, handles Discord resume URLs, heartbeat acknowledgement timeouts, invalid sessions, server reconnect requests, and stale/zombie connections.
-
-```ts
-import { Gateway } from "@lunibee/ws";
-
-const gateway = new Gateway({
-    token: process.env.DISCORD_TOKEN!,
-    intents: 513
-});
-
-await gateway.connect();
-```
-
-## REST
-
-The REST client supports Discord bucket-aware rate limiting and retries. It consumes Discord's rate-limit headers including bucket identifiers, remaining requests, reset information, and `Retry-After`.
-
-Requests accept an `AbortSignal`:
-
-```ts
-const controller = new AbortController();
-
-const request = client.rest.get("/users/@me", {
-    signal: controller.signal
-});
-
-controller.abort();
-await request;
-```
-
-`RESTError` includes HTTP status, Discord error code, method, path, and the raw error payload when available.
-
-## Structures and caching
-
-Resource managers maintain canonical instances by Discord resource ID. Re-resolving an already cached resource returns the same structure instance, allowing identity-sensitive application code to remain consistent.
-
-REST-created and Gateway-updated resources are routed through manager cache mutation APIs so the same resource is not represented by unrelated structure instances.
-
-## Permissions
-
-`PermissionSet` provides named and raw permission checks:
-
-```ts
-if (member.permissions.has(Permission.manageMessages)) {
-    // permitted
-}
-```
-
-Multiple permissions can be checked together, and immutable `add()` / `remove()` operations return a new bitfield.
-
-## Interactions
-
-Interactions expose an ergonomic acknowledgement lifecycle:
-
-```ts
-if (interaction.isChatInputCommand()) {
-    await interaction.deferReply();
-    await interaction.editReply({ content: "Done!" });
-    await interaction.followUp({ content: "Follow-up" });
-}
-```
-
-Available lifecycle methods include `reply()`, `deferReply()`, `editReply()`, `deleteReply()`, and `followUp()`.
-
-## Builders
-
-Lunibee provides strict builders for Discord payloads (Discord.js V2 compatible), including:
-
-- `ActionRowBuilder`
-- `ButtonBuilder`
-- `StringSelectBuilder`
-- `EmbedBuilder`
-- `ModalBuilder`
-- `TextInputBuilder`
-
-Builders validate Discord limits before serialization and expose typed `toJSON()` payloads.
-
-## Sharding
-
-`@lunibee/sharding` manages multiple Gateway connections and supports explicit shard counts or Discord's recommended shard count.
-
-```ts
-import { ShardManager } from "@lunibee/sharding";
-
-const shards = new ShardManager({
-    token: process.env.DISCORD_TOKEN!,
-    intents: 513,
-    shardCount: "auto"
-});
-
-await shards.connect();
-```
-
-Call `destroy()` during shutdown. The manager releases its Gateway instances and can initialize a fresh shard set on a later `connect()`.
-
-## Package layout
-
-The monorepo is organized into focused packages:
-
-| Package | Responsibility |
-| --- | --- |
-| `@lunibee/types` | Discord API and shared TypeScript types |
-| `@lunibee/structures` | Discord resource and interaction structures |
-| `@lunibee/managers` | Resource caches and REST-backed managers |
-| `@lunibee/rest` | HTTP transport, routes, rate limits, retries |
-| `@lunibee/ws` | Discord Gateway connection |
-| `@lunibee/core` | Main client and high-level orchestration |
-| `@lunibee/builders` | Typed Discord payload builders |
-| `@lunibee/sharding` | Multi-Gateway shard management |
-| `lunibee` | End-user package entry point |
-
-## Development
-
-Run the repository's checks before submitting changes:
-
-```bash
-bun install
-bunx tsc --noEmit
-```
-
-## Documentation & API Reference
-
-The full, official API reference and practical guides are available at **[lunibee.js.org](https://lunibee.js.org)**. 
-
-The source remains the authoritative API surface while Lunibee is pre-1.0. Public exports are intentionally split by responsibility so applications can import either the high-level `lunibee` package or individual packages when appropriate.
-
-## Status
-
-Lunibee is in active development and the API may change before the first stable release.
+# Lunibee 🐝
+
+[![npm version](https://badge.fury.io/js/lunibee.svg)](https://www.npmjs.com/package/lunibee)
+[![NPM Downloads](https://img.shields.io/npm/dt/lunibee.svg?style=flat-square)](https://www.npmjs.com/package/lunibee)
+[![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/SSADgyBpgw)
+
+[![NPM Graph](https://nodei.co/npm/lunibee.png?downloads=true&downloadRank=true&stars=true)](https://www.npmjs.com/package/lunibee)
+
+A lightweight, Bun-first Discord API library for TypeScript.
+
+## Requirements
+
+- [Bun](https://bun.sh/) for the supported runtime and package manager
+- TypeScript for typed application development
+- A Discord bot token for connecting to Discord
+
+## Installation
+
+For repository development:
+
+```bash
+bun install
+```
+
+For application usage, install the published `lunibee` package when a release is available:
+
+```bash
+bun add lunibee
+```
+
+## Documentation
+
+Full documentation, practical guides, and API references are available at **[lunibee.js.org](https://lunibee.js.org)**.
+
+## Getting started
+
+```ts
+import { Client, GatewayIntentBits } from "lunibee";
+
+const client = new Client({
+    token: process.env.DISCORD_TOKEN!,
+    intents: GatewayIntentBits.Guilds | GatewayIntentBits.GuildMessages
+});
+
+client.on("ready", user => {
+    console.log(`Ready as ${user.username}`);
+});
+
+client.on("messageCreate", message => {
+    console.log(message.content);
+});
+
+await client.login();
+```
+
+Destroy the client when the application is shutting down:
+
+```ts
+client.destroy();
+```
+
+## Client
+
+`Client` is the main application entry point. It coordinates the REST transport, resource managers, Gateway, event dispatch, interactions, and lifecycle state.
+
+### Lifecycle
+
+```text
+idle → connecting → ready
+  ↑                 ↓
+  └──── reconnect ──┘
+
+ready → destroyed
+```
+
+Useful APIs include:
+
+- `client.login()` — authenticate and connect to Discord.
+- `client.isReady()` — type guard for a ready client.
+- `client.destroy()` — close the Gateway and clear client-managed resources.
+- `client.rest` — access the REST transport.
+- `client.users`, `client.guilds`, `client.channels` — resource managers.
+
+## Gateway
+
+The Gateway package implements the Discord WebSocket lifecycle:
+
+```text
+CONNECT → HELLO → IDENTIFY/RESUME → READY → DISPATCH
+                              ↘ HEARTBEAT / ACK
+                                      ↓
+                                  RECONNECT
+```
+
+The Gateway tracks sequence numbers and sessions, handles Discord resume URLs, heartbeat acknowledgement timeouts, invalid sessions, server reconnect requests, and stale/zombie connections.
+
+```ts
+import { Gateway } from "@lunibee/ws";
+
+const gateway = new Gateway({
+    token: process.env.DISCORD_TOKEN!,
+    intents: 513
+});
+
+await gateway.connect();
+```
+
+## REST
+
+The REST client supports Discord bucket-aware rate limiting and retries. It consumes Discord's rate-limit headers including bucket identifiers, remaining requests, reset information, and `Retry-After`.
+
+Requests accept an `AbortSignal`:
+
+```ts
+const controller = new AbortController();
+
+const request = client.rest.get("/users/@me", {
+    signal: controller.signal
+});
+
+controller.abort();
+await request;
+```
+
+`RESTError` includes HTTP status, Discord error code, method, path, and the raw error payload when available.
+
+## Structures and caching
+
+Resource managers maintain canonical instances by Discord resource ID. Re-resolving an already cached resource returns the same structure instance, allowing identity-sensitive application code to remain consistent.
+
+REST-created and Gateway-updated resources are routed through manager cache mutation APIs so the same resource is not represented by unrelated structure instances.
+
+Discord resources are stored with `Collection.setWithoutTTL()` and leave the cache only through Gateway delete events or an explicit `delete()`, never through expiry. Messages are cached only with the `messageCache: { maxSize?, ttl? }` client option, and `cache: { users, members, roles, emojis }` turns off per-resource caching on large bots. For your own data, `new Collection(null, { ttl, maxSize, onEvict })` is a TTL/LRU cache. See the [0.2.0 upgrade guide](https://lunibee.js.org/getting-started/upgrading/).
+
+## Permissions
+
+`PermissionSet` provides named and raw permission checks:
+
+```ts
+if (member.permissions.has(Permission.manageMessages)) {
+    // permitted
+}
+```
+
+Multiple permissions can be checked together, and immutable `add()` / `remove()` operations return a new bitfield.
+
+## Interactions
+
+Interactions expose an ergonomic acknowledgement lifecycle:
+
+```ts
+if (interaction.isChatInputCommand()) {
+    await interaction.deferReply();
+    await interaction.editReply({ content: "Done!" });
+    await interaction.followUp({ content: "Follow-up" });
+}
+```
+
+Available lifecycle methods include `reply()`, `deferReply()`, `editReply()`, `deleteReply()`, and `followUp()`.
+
+## Builders
+
+Lunibee provides strict builders for Discord payloads (Discord.js V2 compatible), including:
+
+- `ActionRowBuilder`
+- `ButtonBuilder`
+- `StringSelectBuilder`
+- `EmbedBuilder`
+- `ModalBuilder`
+- `TextInputBuilder`
+
+Builders validate Discord limits before serialization and expose typed `toJSON()` payloads.
+
+## Sharding
+
+`@lunibee/sharding` manages multiple Gateway connections and supports explicit shard counts or Discord's recommended shard count.
+
+```ts
+import { ShardManager } from "@lunibee/sharding";
+
+const shards = new ShardManager({
+    token: process.env.DISCORD_TOKEN!,
+    intents: 513,
+    shardCount: "auto"
+});
+
+await shards.connect();
+```
+
+Call `destroy()` during shutdown. The manager releases its Gateway instances and can initialize a fresh shard set on a later `connect()`.
+
+## Package layout
+
+The monorepo is organized into focused packages:
+
+| Package | Responsibility |
+| --- | --- |
+| `@lunibee/types` | Discord API and shared TypeScript types |
+| `@lunibee/structures` | Discord resource and interaction structures |
+| `@lunibee/managers` | Resource caches and REST-backed managers |
+| `@lunibee/rest` | HTTP transport, routes, rate limits, retries |
+| `@lunibee/ws` | Discord Gateway connection |
+| `@lunibee/core` | Main client and high-level orchestration |
+| `@lunibee/builders` | Typed Discord payload builders |
+| `@lunibee/sharding` | Multi-Gateway shard management |
+| `lunibee` | End-user package entry point |
+
+## Development
+
+Run the repository's checks before submitting changes:
+
+```bash
+bun install
+bunx tsc --noEmit
+```
+
+## Documentation & API Reference
+
+The full, official API reference and practical guides are available at **[lunibee.js.org](https://lunibee.js.org)**. 
+
+The source remains the authoritative API surface while Lunibee is pre-1.0. Public exports are intentionally split by responsibility so applications can import either the high-level `lunibee` package or individual packages when appropriate.
+
+## Status
+
+Lunibee is in active development and the API may change before the first stable release.

package/dist/builders/commands.d.ts

@@ -116,10 +116,13 @@ export declare class NumberOptionBuilder extends CommandOptionBuilder {
     /** Creates a subcommand group. */ constructor();
     /** Adds a subcommand to this group. */ addSubcommand(configure: (option: SubcommandBuilder) => SubcommandBuilder): this;
 }
-/** Base builder for application commands that appear in right-click context menus. */
-declare class ContextMenuCommandBuilder {
+/** Builder for application commands that appear in right-click context menus.
+ * Discord.js-familiar: `new ContextMenuCommandBuilder().setName("x").setType(2)`. */
+export declare class ContextMenuCommandBuilder {
     protected readonly data: Record<string, unknown>;
-    constructor(type: 2 | 3);
+    constructor(type?: 2 | 3);
+    /** Sets the command type: 2 = USER, 3 = MESSAGE. @throws {RangeError} For any other type. */
+    setType(type: 2 | 3): this;
     /** Sets the command name (shown in the right-click menu).
      * Unlike CHAT_INPUT commands, USER (type 2) and MESSAGE (type 3) context-menu
      * command names may contain uppercase letters and spaces, so no lowercase/charset
@@ -152,4 +155,3 @@ export declare class UserCommandBuilder extends ContextMenuCommandBuilder {
 export declare class MessageCommandBuilder extends ContextMenuCommandBuilder {
     constructor();
 }
-export {};

package/dist/builders/components.d.ts

@@ -35,6 +35,8 @@ export interface APIButtonComponent {
     label?: string;
     emoji?: APIComponentEmoji;
     url?: string;
+    /** SKU for premium (style 6) buttons. */
+    sku_id?: string;
     disabled?: boolean;
 }
 export interface APISelectOption {
@@ -164,10 +166,13 @@ export declare class StringSelectBuilder {
 }
 export declare class ButtonBuilder {
     #private;
+    /** Sets the style and drops fields that style cannot carry. */
     setStyle(style: APIButtonComponent["style"]): this;
     setCustomId(value: string): this;
     setLabel(value: string): this;
     setURL(value: string): this;
+    /** Makes this a premium (purchase) button for a SKU. Premium buttons carry no label, emoji, custom ID or URL. */
+    setSKUId(skuId: string): this;
     setEmoji(emoji: APIComponentEmoji | string): this;
     setDisabled(value?: boolean): this;
     toJSON(): APIButtonComponent;
@@ -264,3 +269,21 @@ export declare class ContentInventoryEntryBuilder {
     setId(id: string): this;
     toJSON(): APIContentInventoryEntryComponent;
 }
+/** Discord.js-familiar alias for {@link StringSelectBuilder}. */
+export { StringSelectBuilder as StringSelectMenuBuilder };
+/** User select menu builder (Discord.js-familiar). */
+export declare class UserSelectMenuBuilder extends EntitySelectBuilder {
+    constructor();
+}
+/** Role select menu builder (Discord.js-familiar). */
+export declare class RoleSelectMenuBuilder extends EntitySelectBuilder {
+    constructor();
+}
+/** Mentionable select menu builder (Discord.js-familiar). */
+export declare class MentionableSelectMenuBuilder extends EntitySelectBuilder {
+    constructor();
+}
+/** Channel select menu builder (Discord.js-familiar). */
+export declare class ChannelSelectMenuBuilder extends EntitySelectBuilder {
+    constructor();
+}

package/dist/builders/index.d.ts

@@ -1,5 +1,5 @@
 export { EmbedBuilder } from "./embed.js";
 export type { EmbedField } from "./embed.js";
-export { ButtonBuilder, ButtonStyle, ComponentType, ActionRowBuilder, StringSelectBuilder, EntitySelectBuilder, ModalBuilder, TextInputBuilder, TextInputStyle, ContainerBuilder, SectionBuilder, TextDisplayBuilder, MediaGalleryBuilder, FileComponentBuilder, SeparatorBuilder, ThumbnailBuilder, ContentInventoryEntryBuilder, } from "./components.js";
-export { SlashCommandBuilder, StringOptionBuilder, IntegerOptionBuilder, NumberOptionBuilder, BooleanOptionBuilder, UserOptionBuilder, ChannelOptionBuilder, RoleOptionBuilder, MentionableOptionBuilder, AttachmentOptionBuilder, SubcommandBuilder, SubcommandGroupBuilder, ApplicationCommandOptionType, UserCommandBuilder, MessageCommandBuilder, } from "./commands.js";
+export { ButtonBuilder, ButtonStyle, ComponentType, ActionRowBuilder, StringSelectBuilder, StringSelectMenuBuilder, EntitySelectBuilder, UserSelectMenuBuilder, RoleSelectMenuBuilder, MentionableSelectMenuBuilder, ChannelSelectMenuBuilder, ModalBuilder, TextInputBuilder, TextInputStyle, ContainerBuilder, SectionBuilder, TextDisplayBuilder, MediaGalleryBuilder, FileComponentBuilder, SeparatorBuilder, ThumbnailBuilder, ContentInventoryEntryBuilder, } from "./components.js";
+export { SlashCommandBuilder, StringOptionBuilder, IntegerOptionBuilder, NumberOptionBuilder, BooleanOptionBuilder, UserOptionBuilder, ChannelOptionBuilder, RoleOptionBuilder, MentionableOptionBuilder, AttachmentOptionBuilder, SubcommandBuilder, SubcommandGroupBuilder, ApplicationCommandOptionType, UserCommandBuilder, MessageCommandBuilder, ContextMenuCommandBuilder, } from "./commands.js";
 export { AttachmentBuilder, type AttachmentData } from "./attachment.js";