lunibee 0.1.5 → 0.1.7

package/README.md

@@ -2,26 +2,12 @@
 
 [![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.
 
-## Production-readiness status
-
-Lunibee's production-readiness work is being developed on `feat/production-readiness`. **Do not use `master` for active development.**
-
-The roadmap covers:
-
-- strict package dependency boundaries and installability
-- Discord Gateway lifecycle, heartbeat ACK handling, resume/reconnect, and zombie detection
-- canonical resource caching and shared REST/Gateway hydration
-- bucket-aware REST rate limits, retries, timeouts, and `AbortSignal` cancellation
-- typed permissions and ergonomic interaction APIs
-- compile-time-safe component and embed builders
-- graceful client and shard shutdown
-- public API documentation
-
 ## Requirements
 
 - [Bun](https://bun.sh/) for the supported runtime and package manager
@@ -42,6 +28,10 @@ For application usage, install the published `lunibee` package when a release is
 bun add lunibee
 ```
 
+## Documentation
+
+Full documentation, practical guides, and API references are available at **[lunibee.js.org](https://lunibee.js.org)**.
+
 ## Getting started
 
 ```ts
@@ -142,10 +132,10 @@ REST-created and Gateway-updated resources are routed through manager cache muta
 
 ## Permissions
 
-`PermissionsBitField` provides named and raw permission checks:
+`PermissionSet` provides named and raw permission checks:
 
 ```ts
-if (member.permissions.has("ManageMessages")) {
+if (member.permissions.has(Permission.manageMessages)) {
     // permitted
 }
 ```
@@ -168,13 +158,12 @@ Available lifecycle methods include `reply()`, `deferReply()`, `editReply()`, `d
 
 ## Builders
 
-Lunibee provides strict builders for Discord payloads, including:
+Lunibee provides strict builders for Discord payloads (Discord.js V2 compatible), including:
 
-- `EmbedBuilder`
-- `ButtonBuilder`
 - `ActionRowBuilder`
+- `ButtonBuilder`
 - `StringSelectBuilder`
-- `EntitySelectBuilder`
+- `EmbedBuilder`
 - `ModalBuilder`
 - `TextInputBuilder`
 
@@ -223,11 +212,11 @@ bun install
 bunx tsc --noEmit
 ```
 
-Keep production-readiness work on the active feature branch and commit each completed phase separately. Changes must not be made directly on `master`.
+## Documentation & API Reference
 
-## API reference
+The full, official API reference and practical guides are available at **[lunibee.js.org](https://lunibee.js.org)**. 
 
-The source is the authoritative API surface while Lunibee remains 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.
+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
 

package/dist/builders/commands.d.ts

@@ -116,3 +116,40 @@ 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 {
+    protected readonly data: Record<string, unknown>;
+    constructor(type: 2 | 3);
+    /** 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
+     * validation is applied here — only Discord's 1-32 length limit and a non-empty
+     * (non-whitespace) requirement are enforced.
+     * @param name Display name; 1-32 characters, mixed case and spaces allowed.
+     * @throws {RangeError} If the name is empty/whitespace-only or exceeds 32 characters.
+     */
+    setName(name: string): this;
+    /** Sets default member permissions required to see this command. */
+    setDefaultMemberPermissions(permissions: bigint | number | string | null): this;
+    /** Sets whether the command is available in direct messages. */
+    setDMPermission(enabled: boolean): this;
+    /** Sets command integration types. */
+    setIntegrationTypes(...types: number[]): this;
+    /** Serializes the command payload for the Discord API. */
+    toJSON(): Record<string, unknown>;
+}
+/** Builds a User context menu command (appears when right-clicking a user, type 2).
+ * @example
+ * new UserCommandBuilder().setName("View Profile").toJSON()
+ */
+export declare class UserCommandBuilder extends ContextMenuCommandBuilder {
+    constructor();
+}
+/** Builds a Message context menu command (appears when right-clicking a message, type 3).
+ * @example
+ * new MessageCommandBuilder().setName("Translate Message").toJSON()
+ */
+export declare class MessageCommandBuilder extends ContextMenuCommandBuilder {
+    constructor();
+}
+export {};

package/dist/builders/components.d.ts

@@ -1,3 +1,5 @@
+import { ButtonStyle } from "@lunibee/types";
+export { ButtonStyle };
 /** Component type constants exposed by Lunibee. */
 export declare const ComponentType: {
     readonly ActionRow: 1;
@@ -8,13 +10,14 @@ export declare const ComponentType: {
     readonly RoleSelect: 6;
     readonly MentionableSelect: 7;
     readonly ChannelSelect: 8;
-};
-export declare const ButtonStyle: {
-    readonly Primary: 1;
-    readonly Secondary: 2;
-    readonly Success: 3;
-    readonly Danger: 4;
-    readonly Link: 5;
+    readonly Section: 9;
+    readonly TextDisplay: 10;
+    readonly Thumbnail: 11;
+    readonly MediaGallery: 12;
+    readonly File: 13;
+    readonly Separator: 14;
+    readonly ContentInventoryEntry: 16;
+    readonly Container: 17;
 };
 export declare const TextInputStyle: {
     readonly Short: 1;
@@ -27,7 +30,7 @@ export interface APIComponentEmoji {
 }
 export interface APIButtonComponent {
     type: typeof ComponentType.Button;
-    style: 1 | 2 | 3 | 4 | 5;
+    style: 1 | 2 | 3 | 4 | 5 | 6;
     custom_id?: string;
     label?: string;
     emoji?: APIComponentEmoji;
@@ -59,6 +62,7 @@ export interface APIEntitySelectComponent {
     max_values?: number;
     required?: boolean;
     disabled?: boolean;
+    default_values?: APISelectDefaultValue[];
 }
 export interface APITextInputComponent {
     type: typeof ComponentType.TextInput;
@@ -82,6 +86,61 @@ export interface APIActionRowComponent {
     type: typeof ComponentType.ActionRow;
     components: APIActionRowChild[];
 }
+export interface APISectionComponent {
+    type: typeof ComponentType.Section;
+    components?: APIComponent[];
+    accessory?: APIComponent;
+}
+export interface APITextDisplayComponent {
+    type: typeof ComponentType.TextDisplay;
+    content: string;
+}
+export interface APIMediaGalleryComponent {
+    type: typeof ComponentType.MediaGallery;
+    items: {
+        media: {
+            url: string;
+            description?: string;
+        };
+    }[];
+}
+/** Default values accepted by an auto-populated entity select. */
+export interface APISelectDefaultValue {
+    id: string;
+    type: "user" | "role" | "channel";
+}
+export interface APIFileComponent {
+    type: typeof ComponentType.File;
+    file: {
+        url: string;
+    };
+    spoiler?: boolean;
+}
+export interface APISeparatorComponent {
+    type: typeof ComponentType.Separator;
+    spacing?: 1 | 2;
+    divider?: boolean;
+}
+export interface APIThumbnailComponent {
+    type: typeof ComponentType.Thumbnail;
+    url: string;
+    proxy_url?: string;
+    width?: number;
+    height?: number;
+    description?: string;
+    spoiler?: boolean;
+}
+export interface APIContentInventoryEntryComponent {
+    type: typeof ComponentType.ContentInventoryEntry;
+    id: string;
+}
+export interface APIContainerComponent {
+    type: typeof ComponentType.Container;
+    components: APIComponent[];
+    accent_color?: number;
+    spoiler?: boolean;
+}
+export type APIComponent = APIActionRowComponent | APIButtonComponent | APIStringSelectComponent | APIEntitySelectComponent | APITextInputComponent | APISectionComponent | APITextDisplayComponent | APIThumbnailComponent | APIMediaGalleryComponent | APIFileComponent | APISeparatorComponent | APIContentInventoryEntryComponent | APIContainerComponent;
 export declare class ActionRowBuilder<T extends {
     toJSON(): APIActionRowChild;
 } = {
@@ -122,10 +181,7 @@ export declare class EntitySelectBuilder {
     setMaxValues(value: number): this;
     setRequired(value?: boolean): this;
     setDisabled(value?: boolean): this;
-    setDefaultValues(...values: {
-        id: string;
-        type: "user" | "role" | "channel";
-    }[]): this;
+    setDefaultValues(...values: APISelectDefaultValue[]): this;
     toJSON(): APIEntitySelectComponent;
 }
 export declare class ModalBuilder {
@@ -149,3 +205,62 @@ export declare class TextInputBuilder {
     setValue(value: string): this;
     toJSON(): APITextInputComponent;
 }
+export declare class ContainerBuilder {
+    #private;
+    addComponents(...components: {
+        toJSON(): APIComponent;
+    }[]): this;
+    setAccentColor(color: number): this;
+    /** Marks the whole container as a spoiler (blurred until clicked). */
+    setSpoiler(spoiler?: boolean): this;
+    toJSON(): APIContainerComponent;
+}
+export declare class SectionBuilder {
+    #private;
+    addComponents(...components: {
+        toJSON(): APIComponent;
+    }[]): this;
+    setAccessory(accessory: {
+        toJSON(): APIComponent;
+    }): this;
+    toJSON(): APISectionComponent;
+}
+export declare class TextDisplayBuilder {
+    #private;
+    setContent(content: string): this;
+    toJSON(): APITextDisplayComponent;
+}
+export declare class MediaGalleryBuilder {
+    #private;
+    addItems(...items: {
+        url: string;
+        description?: string;
+    }[]): this;
+    toJSON(): APIMediaGalleryComponent;
+}
+export declare class FileComponentBuilder {
+    #private;
+    setUrl(url: string): this;
+    setSpoiler(spoiler?: boolean): this;
+    toJSON(): APIFileComponent;
+}
+export declare class SeparatorBuilder {
+    #private;
+    setSpacing(spacing: 1 | 2): this;
+    setDivider(divider?: boolean): this;
+    toJSON(): APISeparatorComponent;
+}
+export declare class ThumbnailBuilder {
+    #private;
+    setUrl(url: string): this;
+    /** Sets the thumbnail's alt-text description. */
+    setDescription(description: string): this;
+    /** Marks the thumbnail as a spoiler (blurred until clicked). */
+    setSpoiler(spoiler?: boolean): this;
+    toJSON(): APIThumbnailComponent;
+}
+export declare class ContentInventoryEntryBuilder {
+    #private;
+    setId(id: string): this;
+    toJSON(): APIContentInventoryEntryComponent;
+}

package/dist/builders/embed.d.ts

@@ -48,7 +48,9 @@ export declare class EmbedBuilder {
     /** Sets the image URL. @param value Image URL or payload. @returns This builder. @throws {TypeError} If URL is invalid. */ setImage(value: {
         url: string;
     } | string): this;
-    /** Adds embed fields. @param fields Field payloads. @returns This builder. @throws {RangeError} If the 25-field limit is exceeded. */ addFields(...fields: EmbedField[]): this;
+    /** Adds embed fields. Accepts both the spread form `addFields(a, b)` and the
+     * single-array form `addFields([a, b])` for discord.js `RestOrArray` parity.
+     * @param fields Field payloads, spread or as a single array. @returns This builder. @throws {RangeError} If the 25-field limit is exceeded. */ addFields(...fields: EmbedField[] | [EmbedField[]]): this;
     setFields(fields: EmbedField[]): this;
     /** Replaces fields starting at an index. @param index Start index. @param deleteCount Number of fields to remove. @param fields Replacement fields. @returns This builder. @throws {RangeError} If arguments are invalid or the 25-field limit is exceeded. */ spliceFields(index: number, deleteCount: number, ...fields: EmbedField[]): this;
     /** Removes all embed fields. @returns This builder. */ clearFields(): this;

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, } from "./components.js";
-export { SlashCommandBuilder, StringOptionBuilder, IntegerOptionBuilder, NumberOptionBuilder, BooleanOptionBuilder, UserOptionBuilder, ChannelOptionBuilder, RoleOptionBuilder, MentionableOptionBuilder, AttachmentOptionBuilder, SubcommandBuilder, SubcommandGroupBuilder, ApplicationCommandOptionType, } from "./commands.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 { AttachmentBuilder, type AttachmentData } from "./attachment.js";