qaut.js 1.0.0

package/README.md

@@ -0,0 +1,82 @@
+# qaut.js
+
+Official QauT bot framework for Node.js.
+
+## Install
+
+```bash
+npm i qaut.js
+```
+
+Local development from this repository:
+
+```bash
+npm i ../QauT.js
+```
+
+## Quick Start
+
+```js
+const { Client, Events, GatewayIntentBits, EmbedBuilder, Status } = require('qaut.js');
+
+const client = new Client({
+  token: process.env.QAUT_TOKEN,
+  intents: [
+    GatewayIntentBits.Guilds,
+    GatewayIntentBits.GuildMessages,
+    GatewayIntentBits.MessageContent
+  ]
+});
+
+client.on(Events.ClientReady, async bot => {
+  console.log(`Ready as ${bot.username}`);
+  await client.setPresence({
+    status: Status.Online,
+    activity: { name: 'QauT servers', type: 3 }
+  });
+});
+
+client.on(Events.MessageCreate, async message => {
+  if (message.content === '!ping') {
+    await message.reply({
+      embeds: [
+        new EmbedBuilder()
+          .setTitle('Pong')
+          .setDescription('QauT.js is running.')
+          .setColor('#22d3ee')
+          .setTimestamp()
+      ]
+    });
+  }
+});
+
+client.login();
+```
+
+## Builders
+
+- `EmbedBuilder`
+- `ButtonBuilder`
+- `ActionRowBuilder`
+- `SlashCommandBuilder`
+- `PermissionBitField`
+- `IntentBitField`
+
+## REST
+
+```js
+const { REST } = require('qaut.js');
+
+const rest = new REST({ token: process.env.QAUT_TOKEN });
+await rest.post('/bot/channels/123/messages', {
+  content: 'Hello from QauT.js'
+});
+```
+
+## Developer Portal
+
+Create and manage bot applications from:
+
+```text
+https://qaut.gg/developers/applications
+```

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "qaut.js",
+  "version": "1.0.0",
+  "description": "Official QauT bot framework for building bots and integrations.",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "license": "MIT",
+  "author": "QauT",
+  "keywords": [
+    "qaut",
+    "qaut.js",
+    "bot",
+    "gateway",
+    "embed",
+    "oauth2"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node test/smoke.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ]
+}

package/src/index.d.ts

@@ -0,0 +1,122 @@
+/// <reference types="node" />
+import { EventEmitter } from 'events';
+
+export declare const Events: {
+  readonly ClientReady: 'clientReady';
+  readonly Debug: 'debug';
+  readonly Error: 'error';
+  readonly MessageCreate: 'messageCreate';
+  readonly MessageUpdate: 'messageUpdate';
+  readonly MessageDelete: 'messageDelete';
+  readonly InteractionCreate: 'interactionCreate';
+  readonly GuildCreate: 'guildCreate';
+  readonly GuildUpdate: 'guildUpdate';
+  readonly GuildDelete: 'guildDelete';
+  readonly GuildMemberAdd: 'guildMemberAdd';
+  readonly GuildMemberRemove: 'guildMemberRemove';
+  readonly PresenceUpdate: 'presenceUpdate';
+  readonly WebhookEvent: 'webhookEvent';
+};
+
+export declare const GatewayIntentBits: Record<string, number>;
+export declare const Status: Record<string, string>;
+export declare const ActivityType: Record<string, number>;
+export declare const PermissionFlagsBits: Record<string, bigint>;
+export declare const DefaultRestBase = "https://qaut.gg/api";
+
+export declare class QauTError extends Error {
+  details?: unknown;
+}
+
+export declare class BitField {
+  bitfield: bigint;
+  constructor(bits?: bigint | number | string | Array<bigint | number | string>);
+  has(bit: bigint | number | string): boolean;
+  add(...bits: Array<bigint | number | string | Array<bigint | number | string>>): this;
+  remove(...bits: Array<bigint | number | string | Array<bigint | number | string>>): this;
+  toString(): string;
+  valueOf(): bigint;
+}
+
+export declare class PermissionBitField extends BitField {}
+export declare class IntentBitField extends BitField {}
+
+export declare class EmbedBuilder {
+  constructor(data?: Record<string, unknown>);
+  setTitle(title: string): this;
+  setDescription(description: string): this;
+  setColor(color: string | number): this;
+  setURL(url: string): this;
+  setTimestamp(timestamp?: Date | string | number): this;
+  setAuthor(author: string | Record<string, unknown>): this;
+  setFooter(footer: string | Record<string, unknown>): this;
+  setImage(url: string): this;
+  setThumbnail(url: string): this;
+  addFields(...fields: Array<{ name: string; value: string; inline?: boolean } | Array<{ name: string; value: string; inline?: boolean }>>): this;
+  toJSON(): Record<string, unknown>;
+}
+
+export declare class ButtonBuilder {
+  constructor(data?: Record<string, unknown>);
+  setCustomId(customId: string): this;
+  setLabel(label: string): this;
+  setStyle(style: string): this;
+  setURL(url: string): this;
+  setDisabled(disabled?: boolean): this;
+  toJSON(): Record<string, unknown>;
+}
+
+export declare class ActionRowBuilder {
+  constructor(data?: { components?: unknown[] });
+  addComponents(...components: unknown[]): this;
+  toJSON(): Record<string, unknown>;
+}
+
+export declare class SlashCommandBuilder {
+  constructor(data?: Record<string, unknown>);
+  setName(name: string): this;
+  setDescription(description: string): this;
+  addStringOption(option: Record<string, unknown>): this;
+  addIntegerOption(option: Record<string, unknown>): this;
+  addBooleanOption(option: Record<string, unknown>): this;
+  toJSON(): Record<string, unknown>;
+}
+
+export declare class REST {
+  constructor(options?: { token?: string; baseUrl?: string; authPrefix?: string });
+  setToken(token: string): this;
+  request(method: string, route: string, body?: unknown): Promise<unknown>;
+  get(route: string): Promise<unknown>;
+  post(route: string, body?: unknown): Promise<unknown>;
+  patch(route: string, body?: unknown): Promise<unknown>;
+  delete(route: string, body?: unknown): Promise<unknown>;
+}
+
+export declare class TextChannel {
+  id: string;
+  constructor(client: Client, data?: Record<string, unknown>);
+  send(payload: string | Record<string, unknown>): Promise<unknown>;
+}
+
+export declare class Message {
+  client: Client;
+  channel: TextChannel | null;
+  content?: string;
+  constructor(client: Client, data?: Record<string, unknown>);
+  reply(payload: string | Record<string, unknown>): Promise<unknown>;
+}
+
+export declare class Client extends EventEmitter {
+  token: string;
+  rest: REST;
+  user: unknown;
+  intents: IntentBitField;
+  constructor(options?: { token?: string; intents?: Array<number | bigint | string> | number | bigint | string; restBaseUrl?: string });
+  login(token?: string): Promise<string>;
+  setPresence(presence?: Record<string, unknown>): Promise<unknown>;
+  setStatus(status: string): Promise<unknown>;
+  channel(id: string): TextChannel;
+  emitGatewayEvent(eventName: string, payload: unknown): boolean;
+}
+
+export declare function CreateEmbed(data?: Record<string, unknown>): EmbedBuilder;

package/src/index.js

@@ -0,0 +1,322 @@
+'use strict';
+
+const { EventEmitter } = require('events');
+
+const DefaultRestBase = 'https://qaut.gg/api';
+
+const Events = Object.freeze({
+  ClientReady: 'clientReady',
+  Debug: 'debug',
+  Error: 'error',
+  MessageCreate: 'messageCreate',
+  MessageUpdate: 'messageUpdate',
+  MessageDelete: 'messageDelete',
+  InteractionCreate: 'interactionCreate',
+  GuildCreate: 'guildCreate',
+  GuildUpdate: 'guildUpdate',
+  GuildDelete: 'guildDelete',
+  GuildMemberAdd: 'guildMemberAdd',
+  GuildMemberRemove: 'guildMemberRemove',
+  PresenceUpdate: 'presenceUpdate',
+  WebhookEvent: 'webhookEvent'
+});
+
+const GatewayIntentBits = Object.freeze({
+  Guilds: 1 << 0,
+  GuildMembers: 1 << 1,
+  GuildMessages: 1 << 2,
+  MessageContent: 1 << 3,
+  GuildPresences: 1 << 4,
+  DirectMessages: 1 << 5,
+  Webhooks: 1 << 6
+});
+
+const Status = Object.freeze({
+  Online: 'online',
+  Idle: 'idle',
+  DoNotDisturb: 'dnd',
+  Invisible: 'invisible',
+  Offline: 'offline'
+});
+
+const ActivityType = Object.freeze({
+  Playing: 0,
+  Streaming: 1,
+  Listening: 2,
+  Watching: 3,
+  Custom: 4,
+  Competing: 5
+});
+
+const PermissionFlagsBits = Object.freeze({
+  Administrator: 1n << 0n,
+  ViewAuditLog: 1n << 1n,
+  ManageServer: 1n << 2n,
+  ManageRoles: 1n << 3n,
+  ManageChannels: 1n << 4n,
+  KickMembers: 1n << 5n,
+  BanMembers: 1n << 6n,
+  CreateInstantInvite: 1n << 7n,
+  ManageWebhooks: 1n << 11n,
+  ViewChannels: 1n << 12n,
+  SendMessages: 1n << 20n,
+  ManageMessages: 1n << 24n,
+  EmbedLinks: 1n << 25n,
+  AttachFiles: 1n << 26n,
+  ReadMessageHistory: 1n << 27n,
+  MentionEveryone: 1n << 28n,
+  UseSlashCommands: 1n << 31n,
+  Connect: 1n << 40n,
+  Speak: 1n << 41n,
+  Video: 1n << 42n,
+  MuteMembers: 1n << 43n,
+  DeafenMembers: 1n << 44n,
+  MoveMembers: 1n << 45n,
+  UseVoiceActivity: 1n << 46n
+});
+
+class QauTError extends Error {
+  constructor(message, details) {
+    super(message);
+    this.name = 'QauTError';
+    this.details = details;
+  }
+}
+
+class BitField {
+  constructor(bits = 0n) {
+    this.bitfield = Array.isArray(bits) ? bits.reduce((total, bit) => total | BigInt(bit), 0n) : BigInt(bits);
+  }
+
+  has(bit) {
+    return (this.bitfield & BigInt(bit)) === BigInt(bit);
+  }
+
+  add(...bits) {
+    bits.flat().forEach(bit => { this.bitfield |= BigInt(bit); });
+    return this;
+  }
+
+  remove(...bits) {
+    bits.flat().forEach(bit => { this.bitfield &= ~BigInt(bit); });
+    return this;
+  }
+
+  toString() {
+    return this.bitfield.toString();
+  }
+
+  valueOf() {
+    return this.bitfield;
+  }
+}
+
+class PermissionBitField extends BitField {
+  static Flags = PermissionFlagsBits;
+}
+
+class IntentBitField extends BitField {
+  static Flags = GatewayIntentBits;
+}
+
+class EmbedBuilder {
+  constructor(data = {}) {
+    this.data = { ...data };
+  }
+
+  setTitle(title) { this.data.title = String(title).slice(0, 256); return this; }
+  setDescription(description) { this.data.description = String(description).slice(0, 4096); return this; }
+  setColor(color) { this.data.color = normalizeColor(color); return this; }
+  setURL(url) { this.data.url = String(url); return this; }
+  setTimestamp(timestamp = new Date()) { this.data.timestamp = new Date(timestamp).toISOString(); return this; }
+  setAuthor(author) { this.data.author = typeof author === 'string' ? { name: author } : { ...author }; return this; }
+  setFooter(footer) { this.data.footer = typeof footer === 'string' ? { text: footer } : { ...footer }; return this; }
+  setImage(url) { this.data.image = { url: String(url) }; return this; }
+  setThumbnail(url) { this.data.thumbnail = { url: String(url) }; return this; }
+
+  addFields(...fields) {
+    this.data.fields ||= [];
+    this.data.fields.push(...fields.flat().map(field => ({
+      name: String(field.name).slice(0, 256),
+      value: String(field.value).slice(0, 1024),
+      inline: Boolean(field.inline)
+    })));
+    this.data.fields = this.data.fields.slice(0, 25);
+    return this;
+  }
+
+  toJSON() {
+    return { ...this.data };
+  }
+}
+
+class ButtonBuilder {
+  constructor(data = {}) { this.data = { type: 'button', style: 'primary', ...data }; }
+  setCustomId(customId) { this.data.custom_id = String(customId); return this; }
+  setLabel(label) { this.data.label = String(label).slice(0, 80); return this; }
+  setStyle(style) { this.data.style = style; return this; }
+  setURL(url) { this.data.url = String(url); this.data.style = 'link'; return this; }
+  setDisabled(disabled = true) { this.data.disabled = Boolean(disabled); return this; }
+  toJSON() { return { ...this.data }; }
+}
+
+class ActionRowBuilder {
+  constructor(data = {}) { this.components = data.components || []; }
+  addComponents(...components) { this.components.push(...components.flat()); return this; }
+  toJSON() { return { type: 'action_row', components: this.components.map(component => toJSON(component)) }; }
+}
+
+class SlashCommandBuilder {
+  constructor(data = {}) {
+    this.data = { type: 'chat_input', options: [], ...data };
+  }
+
+  setName(name) { this.data.name = String(name).toLowerCase().replace(/\s+/g, '-').slice(0, 32); return this; }
+  setDescription(description) { this.data.description = String(description).slice(0, 100); return this; }
+  addStringOption(option) { this.data.options.push({ type: 'string', ...option }); return this; }
+  addIntegerOption(option) { this.data.options.push({ type: 'integer', ...option }); return this; }
+  addBooleanOption(option) { this.data.options.push({ type: 'boolean', ...option }); return this; }
+  toJSON() { return { ...this.data, options: [...this.data.options] }; }
+}
+
+class REST {
+  constructor(options = {}) {
+    this.baseUrl = String(options.baseUrl || DefaultRestBase).replace(/\/+$/, '');
+    this.token = options.token || '';
+    this.authPrefix = options.authPrefix || 'Bot';
+  }
+
+  setToken(token) {
+    this.token = token;
+    return this;
+  }
+
+  async request(method, route, body) {
+    const response = await fetch(`${this.baseUrl}${route}`, {
+      method,
+      headers: {
+        Authorization: `${this.authPrefix} ${this.token}`,
+        'Content-Type': 'application/json'
+      },
+      body: body === undefined ? undefined : JSON.stringify(serialize(body))
+    });
+    const data = await response.json().catch(() => null);
+    if (!response.ok) throw new QauTError(data?.error || response.statusText, { status: response.status, data });
+    return data;
+  }
+
+  get(route) { return this.request('GET', route); }
+  post(route, body) { return this.request('POST', route, body); }
+  patch(route, body) { return this.request('PATCH', route, body); }
+  delete(route, body) { return this.request('DELETE', route, body); }
+}
+
+class TextChannel {
+  constructor(client, data = {}) {
+    this.client = client;
+    Object.assign(this, data);
+  }
+
+  send(payload) {
+    return this.client.rest.post(`/bot/channels/${this.id}/messages`, normalizeMessagePayload(payload));
+  }
+}
+
+class Message {
+  constructor(client, data = {}) {
+    this.client = client;
+    Object.assign(this, data);
+    this.channel = data.channel || (data.channelId ? new TextChannel(client, { id: data.channelId }) : null);
+  }
+
+  reply(payload) {
+    if (!this.channel) throw new QauTError('Cannot reply without channel information');
+    return this.channel.send(payload);
+  }
+}
+
+class Client extends EventEmitter {
+  constructor(options = {}) {
+    super();
+    this.options = options;
+    this.token = options.token || '';
+    this.intents = new IntentBitField(options.intents || 0);
+    this.rest = new REST({ token: this.token, baseUrl: options.restBaseUrl || DefaultRestBase });
+    this.user = null;
+  }
+
+  async login(token = this.token) {
+    if (!token) throw new QauTError('Bot token is required');
+    this.token = token;
+    this.rest.setToken(token);
+    const me = await this.rest.get('/bot/me');
+    this.user = me;
+    this.emit(Events.ClientReady, me);
+    return token;
+  }
+
+  async setPresence(presence = {}) {
+    return this.rest.patch('/bot/presence', presence);
+  }
+
+  async setStatus(status) {
+    return this.setPresence({ status });
+  }
+
+  channel(id) {
+    return new TextChannel(this, { id });
+  }
+
+  emitGatewayEvent(eventName, payload) {
+    if (eventName === Events.MessageCreate) return this.emit(eventName, new Message(this, payload));
+    return this.emit(eventName, payload);
+  }
+}
+
+function CreateEmbed(data) {
+  return new EmbedBuilder(data);
+}
+
+function normalizeMessagePayload(payload) {
+  if (typeof payload === 'string') return { content: payload };
+  const output = { ...payload };
+  if (output.embeds) output.embeds = output.embeds.map(toJSON);
+  if (output.components) output.components = output.components.map(toJSON);
+  return output;
+}
+
+function normalizeColor(color) {
+  if (typeof color === 'number') return color;
+  const value = String(color).replace('#', '');
+  return Number.parseInt(value, 16);
+}
+
+function toJSON(value) {
+  return value && typeof value.toJSON === 'function' ? value.toJSON() : value;
+}
+
+function serialize(value) {
+  return JSON.parse(JSON.stringify(value, (_key, item) => typeof item === 'bigint' ? item.toString() : toJSON(item)));
+}
+
+module.exports = {
+  ActionRowBuilder,
+  ActivityType,
+  BitField,
+  ButtonBuilder,
+  Client,
+  CreateEmbed,
+  DefaultRestBase,
+  EmbedBuilder,
+  Events,
+  GatewayIntentBits,
+  IntentBitField,
+  Message,
+  PermissionBitField,
+  PermissionFlagsBits,
+  QauTError,
+  REST,
+  SlashCommandBuilder,
+  Status,
+  TextChannel
+};