@metagames/channel-bot-sdk 1.0.0

package/dist/src/types.d.ts

@@ -0,0 +1,119 @@
+export type ChannelBotEmbedField = {
+    name: string;
+    value: string;
+    inline?: boolean;
+};
+export type ChannelBotEmbed = {
+    title?: string;
+    description?: string;
+    url?: string;
+    color?: string;
+    footer?: string;
+    fields?: ChannelBotEmbedField[];
+};
+export type ChannelBotMessage = {
+    id: string;
+    content: string;
+    embeds?: ChannelBotEmbed[] | null;
+    isPinned?: boolean;
+    createdAt: string;
+    updatedAt: string;
+    edited?: boolean;
+    reactions?: Array<{
+        emoji: string;
+        count: number;
+        reactedByMe: boolean;
+    }>;
+    sender: {
+        id: string;
+        username: string;
+    };
+};
+export type GuildBotInteraction = {
+    commandName: string;
+    rawInput: string;
+    arguments: string[];
+    user: {
+        id: string;
+        username: string;
+    };
+};
+export type GuildBotSocketEvent = {
+    type: "guildBot.ready";
+    bot: {
+        id: string;
+        username: string;
+        description: string | null;
+    };
+} | {
+    type: "guildBot.error";
+    message: string;
+    requestId?: string;
+} | {
+    type: "guildBot.messageCreate";
+    guildId: string;
+    channelId: string;
+    message: ChannelBotMessage;
+} | {
+    type: "guildBot.messageUpdate";
+    guildId: string;
+    channelId: string;
+    message: ChannelBotMessage;
+} | {
+    type: "guildBot.messageDelete";
+    guildId: string;
+    channelId: string;
+    messageId: string;
+} | {
+    type: "guildBot.reactionUpdate";
+    guildId: string;
+    channelId: string;
+    messageId: string;
+    reactions: Array<{
+        emoji: string;
+        count: number;
+        reactedByMe: boolean;
+    }>;
+} | {
+    type: "guildBot.interactionCreate";
+    guildId: string;
+    channelId: string;
+    interaction: GuildBotInteraction;
+};
+export type GuildBotMeResponse = {
+    success: boolean;
+    bot: {
+        id: string;
+        username: string;
+        description: string | null;
+        logoId: string | null;
+        creatorId: string;
+        creatorType: string;
+    };
+    installations: Array<{
+        guildId: string;
+        guildName: string;
+    }>;
+    commands: Array<{
+        id: string;
+        name: string;
+        description: string;
+        options?: unknown;
+    }>;
+};
+export type ChannelBotClientOptions = {
+    token: string;
+    apiBaseUrl: string;
+    websocketUrl?: string;
+    fetchImpl?: typeof fetch;
+    WebSocketImpl?: typeof WebSocket;
+    autoReconnect?: boolean;
+    reconnectDelayMs?: number;
+};
+export type ChannelBotMessageInput = {
+    guildId: string;
+    channelId: string;
+    content?: string;
+    embeds?: ChannelBotEmbed[];
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/src/types.d.ts.map

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

package/dist/src/types.js

@@ -0,0 +1,2 @@
+// (c) 2026 Meta Games LLC. All rights reserved.
+export {};

package/dist/types.d.ts

@@ -0,0 +1,119 @@
+export type ChannelBotEmbedField = {
+    name: string;
+    value: string;
+    inline?: boolean;
+};
+export type ChannelBotEmbed = {
+    title?: string;
+    description?: string;
+    url?: string;
+    color?: string;
+    footer?: string;
+    fields?: ChannelBotEmbedField[];
+};
+export type ChannelBotMessage = {
+    id: string;
+    content: string;
+    embeds?: ChannelBotEmbed[] | null;
+    isPinned?: boolean;
+    createdAt: string;
+    updatedAt: string;
+    edited?: boolean;
+    reactions?: Array<{
+        emoji: string;
+        count: number;
+        reactedByMe: boolean;
+    }>;
+    sender: {
+        id: string;
+        username: string;
+    };
+};
+export type GuildBotInteraction = {
+    commandName: string;
+    rawInput: string;
+    arguments: string[];
+    user: {
+        id: string;
+        username: string;
+    };
+};
+export type GuildBotSocketEvent = {
+    type: "guildBot.ready";
+    bot: {
+        id: string;
+        username: string;
+        description: string | null;
+    };
+} | {
+    type: "guildBot.error";
+    message: string;
+    requestId?: string;
+} | {
+    type: "guildBot.messageCreate";
+    guildId: string;
+    channelId: string;
+    message: ChannelBotMessage;
+} | {
+    type: "guildBot.messageUpdate";
+    guildId: string;
+    channelId: string;
+    message: ChannelBotMessage;
+} | {
+    type: "guildBot.messageDelete";
+    guildId: string;
+    channelId: string;
+    messageId: string;
+} | {
+    type: "guildBot.reactionUpdate";
+    guildId: string;
+    channelId: string;
+    messageId: string;
+    reactions: Array<{
+        emoji: string;
+        count: number;
+        reactedByMe: boolean;
+    }>;
+} | {
+    type: "guildBot.interactionCreate";
+    guildId: string;
+    channelId: string;
+    interaction: GuildBotInteraction;
+};
+export type GuildBotMeResponse = {
+    success: boolean;
+    bot: {
+        id: string;
+        username: string;
+        description: string | null;
+        logoId: string | null;
+        creatorId: string;
+        creatorType: string;
+    };
+    installations: Array<{
+        guildId: string;
+        guildName: string;
+    }>;
+    commands: Array<{
+        id: string;
+        name: string;
+        description: string;
+        options?: unknown;
+    }>;
+};
+export type ChannelBotClientOptions = {
+    token: string;
+    apiBaseUrl: string;
+    websocketUrl?: string;
+    fetchImpl?: typeof fetch;
+    WebSocketImpl?: typeof WebSocket;
+    autoReconnect?: boolean;
+    reconnectDelayMs?: number;
+};
+export type ChannelBotMessageInput = {
+    guildId: string;
+    channelId: string;
+    content?: string;
+    embeds?: ChannelBotEmbed[];
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,2 @@
+// (c) 2026 Meta Games LLC. All rights reserved.
+export {};

package/docs/command-handling.md

@@ -0,0 +1,44 @@
+# Command Handling
+
+Use `CommandRouter` for slash-command-like interaction dispatch.
+
+## Register commands
+
+```ts
+import { CommandRouter } from "@metagames/channel-bot-sdk";
+
+const router = new CommandRouter()
+	.command("ping", async (ctx) => {
+		await ctx.replyMention("pong");
+	})
+	.command("help", async (ctx) => {
+		await ctx.replyEmbed({
+			title: "Commands",
+			description: "Available commands for this bot",
+			fields: [
+				{ name: "ping", value: "Health check" },
+				{ name: "help", value: "Show this help" },
+			],
+		});
+	});
+```
+
+## Attach router
+
+```ts
+client.useCommandRouter(router);
+await client.connect();
+```
+
+## Context
+
+Each handler receives a `CommandContext` with:
+
+- `ctx.guildId`
+- `ctx.channelId`
+- `ctx.commandName`
+- `ctx.args`
+- `ctx.user`
+- `ctx.reply(...)`
+- `ctx.replyMention(...)`
+- `ctx.replyEmbed(...)`

package/docs/events.md

@@ -0,0 +1,27 @@
+# Events
+
+All events are available through `client.on(eventName, listener)`.
+
+## Gateway events
+
+- `guildBot.ready`
+- `guildBot.error`
+- `guildBot.messageCreate`
+- `guildBot.messageUpdate`
+- `guildBot.messageDelete`
+- `guildBot.reactionUpdate`
+- `guildBot.interactionCreate`
+
+## Utility events
+
+- `raw` (all parsed gateway payloads)
+- `disconnected`
+- `guildBot.commandError` (when command router handler throws)
+
+## Example
+
+```ts
+client.on("guildBot.interactionCreate", async (event) => {
+	console.log(event.interaction.commandName);
+});
+```

package/docs/quick-start.md

@@ -0,0 +1,44 @@
+# Quick Start
+
+## 1. Create a bot in Brickverse
+
+Create a guild bot in the Brickverse dashboard and copy its token.
+
+## 2. Initialize the client
+
+```ts
+import { ChannelBotClient } from "@metagames/channel-bot-sdk";
+
+const client = new ChannelBotClient({
+	token: process.env.BOT_TOKEN!,
+	apiBaseUrl: "https://api.brickverse.gg",
+});
+```
+
+## 3. Listen to events
+
+```ts
+client.on("guildBot.ready", (event) => {
+	console.log("ready", event.bot.id);
+});
+
+client.on("guildBot.messageCreate", (event) => {
+	console.log(event.message.content);
+});
+```
+
+## 4. Connect
+
+```ts
+await client.connect();
+```
+
+## 5. Send messages manually
+
+```ts
+await client.sendMessage({
+	guildId: "123",
+	channelId: "456",
+	content: "Hello from SDK",
+});
+```

package/package.json

@@ -0,0 +1,46 @@
+{
+	"name": "@metagames/channel-bot-sdk",
+	"version": "1.0.0",
+	"description": "Brickverse guild channel bot SDK",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"sideEffects": false,
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/BrickVerse-co/channel-bot-sdk.git"
+	},
+	"files": [
+		"dist",
+		"README.md",
+		"docs"
+	],
+	"scripts": {
+		"build": "tsc -p tsconfig.json",
+		"type-check": "tsc -p tsconfig.json --noEmit"
+	},
+	"keywords": [
+		"brickverse",
+		"bot",
+		"guild",
+		"sdk"
+	],
+	"license": "Apache-2.0",
+	"author": "Meta Games LLC",
+	"devDependencies": {
+		"typescript": "^5.9.3"
+	},
+	"bugs": {
+		"url": "https://github.com/BrickVerse-co/channel-bot-sdk/issues"
+	},
+	"homepage": "https://github.com/BrickVerse-co/channel-bot-sdk#readme"
+}