flarecord 0.0.1

package/src/core/heartbeat.ts

@@ -0,0 +1,65 @@
+import { GatewayOpcode } from "../types/constants";
+import { GatewayPayload, GatewayState } from "../types";
+import type { DurableObjectState } from "@cloudflare/workers-types";
+
+export class HeartbeatManager {
+  private heartbeatInterval: number | null = null;
+  private sequence: { value: number | null };
+
+  constructor(
+    private ctx: DurableObjectState,
+    private storageKey: string,
+    sequence: { value: number | null },
+    private sendFn: (payload: GatewayPayload) => void
+  ) {
+    this.sequence = sequence;
+  }
+
+  setInterval(interval: number): void {
+    this.heartbeatInterval = interval;
+  }
+
+  async send(): Promise<void> {
+    if (!this.heartbeatInterval) {
+      return;
+    }
+
+    const heartbeat: GatewayPayload = {
+      op: GatewayOpcode.HEARTBEAT,
+      d: this.sequence.value,
+    };
+    this.sendFn(heartbeat);
+
+    const nextHeartbeat = Date.now() + this.heartbeatInterval;
+    await this.ctx.storage.setAlarm(nextHeartbeat);
+  }
+
+  async cancel(): Promise<void> {
+    await this.ctx.storage.deleteAlarm().catch(() => {});
+  }
+
+  async updateAck(): Promise<void> {
+    const state = await this.getState();
+    if (state) {
+      await this.ctx.storage.put(this.storageKey, {
+        ...state,
+        lastHeartbeatAck: Date.now(),
+      } satisfies GatewayState);
+    }
+  }
+
+  private async getState(): Promise<GatewayState | null> {
+    const state = await this.ctx.storage.get(this.storageKey);
+    return this.validateState(state);
+  }
+
+  private validateState(state: unknown): GatewayState | null {
+    if (state === null || state === undefined) {
+      return null;
+    }
+    if (typeof state === "object" && "heartbeatInterval" in state) {
+      return state as GatewayState;
+    }
+    return null;
+  }
+}

package/src/core/message-handler.ts

@@ -0,0 +1,96 @@
+import {
+  GatewayOpcode,
+  RESUMEABLE_CLOSE_CODES,
+  WebSocketCloseCode,
+} from "../types/constants";
+import { GatewayPayload, HelloData, GatewayState } from "../types";
+import { GatewayHandlers } from "./handlers";
+import { SessionManager } from "../utils/session";
+import { HeartbeatManager } from "./heartbeat";
+import type { DurableObjectState } from "@cloudflare/workers-types";
+import type { Logger } from "../utils/logger";
+
+export class MessageHandler {
+  constructor(
+    private handlers: GatewayHandlers,
+    private sessionManager: SessionManager,
+    private heartbeatManager: HeartbeatManager,
+    private reconnectFn: (shouldResume: boolean) => Promise<void>,
+    private ctx: DurableObjectState,
+    private storageKey: string,
+    private intents: number,
+    private logger: Logger
+  ) {}
+
+  async handle(payload: GatewayPayload): Promise<void> {
+    const opcode = payload.op;
+    
+    if (opcode === GatewayOpcode.HELLO) {
+        await this.handleHello(payload.d as HelloData);
+    } else if (opcode === GatewayOpcode.HEARTBEAT_ACK) {
+        await this.heartbeatManager.updateAck();
+    } else if (opcode === GatewayOpcode.DISPATCH) {
+        this.handlers.handleDispatch(payload);
+    } else if (opcode === GatewayOpcode.RECONNECT) {
+      this.logger.warn("Received RECONNECT opcode");
+        await this.reconnectFn(true);
+    } else if (opcode === GatewayOpcode.INVALID_SESSION) {
+        await this.handleInvalidSession(payload.d as boolean);
+    } else {
+      this.logger.warn("Unknown opcode received", { opcode });
+    }
+  }
+
+  private async handleHello(data: HelloData): Promise<void> {
+    this.logger.debug("Handling HELLO", { heartbeatInterval: data.heartbeat_interval });
+    this.heartbeatManager.setInterval(data.heartbeat_interval);
+    await this.handlers.handleHello(data);
+
+    const resumeData = await this.sessionManager.getResumeData();
+    const state = await this.getState();
+
+    if (resumeData && state?.shouldResume) {
+      this.logger.debug("Resuming session", { sessionId: resumeData.sessionId });
+      this.sessionManager.sendResume(resumeData.sessionId, resumeData.sequence);
+    } else {
+      this.logger.debug("Identifying with new session");
+      this.sessionManager.sendIdentify(this.intents);
+    }
+
+    await this.heartbeatManager.send();
+  }
+
+  private async handleInvalidSession(resumable: boolean): Promise<void> {
+    this.logger.warn("Invalid session", { resumable });
+    if (resumable) {
+      await this.reconnectFn(true);
+    } else {
+      const state = await this.getState();
+      if (state) {
+        await this.ctx.storage.put(this.storageKey, {
+          ...state,
+          shouldResume: false,
+          sessionId: null,
+        } satisfies GatewayState);
+      }
+      await this.reconnectFn(false);
+    }
+  }
+
+  shouldResume(code: number): boolean {
+    const isResumable = RESUMEABLE_CLOSE_CODES.includes(code as WebSocketCloseCode);
+    this.logger.debug("Checking if should resume", { code, isResumable });
+    return isResumable;
+  }
+
+  private async getState(): Promise<GatewayState | null> {
+    const state = await this.ctx.storage.get(this.storageKey);
+    if (state === null || state === undefined) {
+      return null;
+    }
+    if (typeof state === "object" && "heartbeatInterval" in state) {
+      return state as GatewayState;
+    }
+    return null;
+  }
+}

package/src/index.ts

@@ -0,0 +1,96 @@
+export { DiscordGateway } from "./core/gateway";
+export { DiscordClient, type DiscordClientOptions } from "./core/client";
+export { MessageHelper } from "./utils/message-helper";
+export { GatewayConnection } from "./core/connection";
+export { GatewayHandlers } from "./core/handlers";
+export { WebSocketManager } from "./utils/websocket";
+export { ReconnectManager } from "./utils/reconnect";
+export { SessionManager } from "./utils/session";
+export { Logger, LogLevel, createLogger } from "./utils/logger";
+
+export type {
+  GatewayPayload,
+  HelloData,
+  IdentifyData,
+  ResumeData,
+  ReadyData,
+  GatewayState,
+  GatewayConfig,
+  MessageData,
+} from "./types";
+export {
+  GatewayOpcode,
+  GatewayEvent,
+  GatewayIntents,
+  WebSocketCloseCode,
+  RESUMEABLE_CLOSE_CODES,
+  GATEWAY_BASE_URL,
+  GATEWAY_VERSION,
+  GATEWAY_ENCODING,
+  DEFAULT_RECONNECT_DELAYS,
+  WEBSOCKET_READY_STATE_OPEN,
+  DEFAULT_STORAGE_KEY,
+  DEFAULT_MAX_RECONNECT_ATTEMPTS,
+} from "./types/constants";
+export { DEFAULT_IDENTIFY_PROPERTIES } from "./types";
+
+export {
+  EmbedBuilder,
+  ActionRowBuilder,
+  ButtonBuilder,
+  StringSelectMenuBuilder,
+  UserSelectMenuBuilder,
+  RoleSelectMenuBuilder,
+  ChannelSelectMenuBuilder,
+  MentionableSelectMenuBuilder,
+  ModalBuilder,
+  TextInputBuilder,
+  AttachmentBuilder,
+  SlashCommandBuilder,
+  ContextMenuCommandBuilder,
+  SlashCommandSubcommandBuilder,
+  SlashCommandSubcommandGroupBuilder,
+  SlashCommandOptionsOnlyBuilder,
+  SlashCommandBooleanOption,
+  SlashCommandChannelOption,
+  SlashCommandIntegerOption,
+  SlashCommandMentionableOption,
+  SlashCommandNumberOption,
+  SlashCommandRoleOption,
+  SlashCommandStringOption,
+  SlashCommandUserOption,
+  REST,
+  Routes,
+  Colors,
+  PermissionFlagsBits,
+  GatewayIntentBits,
+  Events,
+  ActivityType,
+  ChannelType,
+  MessageType,
+  InteractionType,
+  ApplicationCommandType,
+  ButtonStyle,
+  TextInputStyle,
+  ComponentType,
+  Locale,
+  type APIEmbed,
+  type APIEmbedField,
+  type APIButtonComponent,
+  type APIActionRowComponent,
+  type APIMessageComponent,
+  type RESTPostAPIChannelMessageJSONBody,
+  type RESTPostAPIChannelMessageResult,
+  type APIInteractionResponse,
+  type APIMessage,
+  type APIUser,
+  type APIGuild,
+  type APIChannel,
+  type APIInteraction,
+  type APIChatInputApplicationCommandInteraction,
+  type APIMessageApplicationCommandInteraction,
+  type APIUserApplicationCommandInteraction,
+  type APIMessageComponentInteraction,
+  type APIModalSubmitInteraction,
+} from "discord.js";
+

package/src/types/constants.ts

@@ -0,0 +1,103 @@
+export enum GatewayOpcode {
+  DISPATCH = 0,
+  HEARTBEAT = 1,
+  IDENTIFY = 2,
+  PRESENCE_UPDATE = 3,
+  VOICE_STATE_UPDATE = 4,
+  RESUME = 6,
+  RECONNECT = 7,
+  REQUEST_GUILD_MEMBERS = 8,
+  INVALID_SESSION = 9,
+  HELLO = 10,
+  HEARTBEAT_ACK = 11,
+}
+
+export enum GatewayEvent {
+  READY = "READY",
+  RESUMED = "RESUMED",
+  MESSAGE_CREATE = "MESSAGE_CREATE",
+  MESSAGE_UPDATE = "MESSAGE_UPDATE",
+  MESSAGE_DELETE = "MESSAGE_DELETE",
+  INTERACTION_CREATE = "INTERACTION_CREATE",
+  GUILD_CREATE = "GUILD_CREATE",
+  GUILD_UPDATE = "GUILD_UPDATE",
+  GUILD_DELETE = "GUILD_DELETE",
+}
+
+/**
+ * Discord Gateway Intents
+ * @see https://discord.com/developers/docs/topics/gateway#gateway-intents
+ */
+export enum GatewayIntents {
+  GUILDS = 1 << 0,
+  GUILD_MEMBERS = 1 << 1,
+  GUILD_MODERATION = 1 << 2,
+  GUILD_EMOJIS_AND_STICKERS = 1 << 3,
+  GUILD_INTEGRATIONS = 1 << 4,
+  GUILD_WEBHOOKS = 1 << 5,
+  GUILD_INVITES = 1 << 6,
+  GUILD_VOICE_STATES = 1 << 7,
+  GUILD_PRESENCES = 1 << 8,
+  GUILD_MESSAGES = 1 << 9,
+  GUILD_MESSAGE_REACTIONS = 1 << 10,
+  GUILD_MESSAGE_TYPING = 1 << 11,
+  DIRECT_MESSAGES = 1 << 12,
+  DIRECT_MESSAGE_REACTIONS = 1 << 13,
+  DIRECT_MESSAGE_TYPING = 1 << 14,
+  MESSAGE_CONTENT = 1 << 15,
+  GUILD_SCHEDULED_EVENTS = 1 << 16,
+  AUTO_MODERATION_CONFIGURATION = 1 << 20,
+  AUTO_MODERATION_EXECUTION = 1 << 21,
+  GUILD_MESSAGE_POLLS = 1 << 24,
+  DIRECT_MESSAGE_POLLS = 1 << 25,
+}
+
+export enum WebSocketCloseCode {
+  NORMAL_CLOSURE = 1000,
+  GOING_AWAY = 1001,
+  PROTOCOL_ERROR = 1002,
+  UNSUPPORTED_DATA = 1003,
+  NO_STATUS_RECEIVED = 1005,
+  ABNORMAL_CLOSURE = 1006,
+  INVALID_FRAME_PAYLOAD = 1007,
+  POLICY_VIOLATION = 1008,
+  MESSAGE_TOO_BIG = 1009,
+  MISSING_EXTENSION = 1010,
+  INTERNAL_ERROR = 1011,
+  SERVICE_RESTART = 1012,
+  TRY_AGAIN_LATER = 1013,
+  BAD_GATEWAY = 1014,
+  TLS_HANDSHAKE = 1015,
+  UNAUTHENTICATED = 4000,
+  INVALID_API_VERSION = 4001,
+  INVALID_INTENTS = 4002,
+  DISALLOWED_INTENTS = 4003,
+}
+
+export const RESUMEABLE_CLOSE_CODES = [
+  WebSocketCloseCode.NORMAL_CLOSURE,
+  WebSocketCloseCode.GOING_AWAY,
+  WebSocketCloseCode.ABNORMAL_CLOSURE,
+  WebSocketCloseCode.NO_STATUS_RECEIVED,
+];
+
+export const GATEWAY_BASE_URL = "https://discord.com/api/v10/gateway/bot";
+export const GATEWAY_VERSION = 10;
+export const GATEWAY_ENCODING = "json";
+
+export const WEBSOCKET_READY_STATE_OPEN = 1;
+export const DEFAULT_STORAGE_KEY = "gatewayState";
+export const DEFAULT_MAX_RECONNECT_ATTEMPTS = 5;
+
+export const DEFAULT_RECONNECT_DELAYS = {
+  initial: 1000,
+  max: 60000,
+  backoffMultiplier: 2,
+};
+
+export const DEFAULT_IDENTIFY_PROPERTIES = {
+  os: "cloudflare-workers",
+  browser: "discord-gateway",
+  device: "discord-gateway",
+};
+

package/src/types/index.ts

@@ -0,0 +1,65 @@
+import type {
+  GatewayHelloData,
+  GatewayIdentifyData,
+  GatewayResumeData,
+  GatewayReadyDispatchData,
+} from "discord-api-types/v10";
+import type { Logger } from "../utils/logger";
+
+export interface GatewayPayload {
+  op: number;
+  d?: unknown;
+  s?: number | null;
+  t?: string | null;
+}
+
+export type HelloData = GatewayHelloData;
+export type IdentifyData = GatewayIdentifyData;
+export type ResumeData = GatewayResumeData;
+export type ReadyData = GatewayReadyDispatchData;
+
+export interface MessageData extends Record<string, unknown> {
+  _gatewayMetadata?: {
+    opcode: number;
+    opcodeName: string;
+    event: string;
+    sequence: number | null;
+  };
+}
+
+export interface GatewayState {
+  heartbeatInterval: number;
+  sequence: number | null;
+  sessionId: string | null;
+  lastHeartbeat?: number;
+  lastHeartbeatAck?: number;
+  reconnectAttempts: number;
+  shouldResume: boolean;
+}
+
+export interface GatewayConfig {
+  token: string;
+  intents: number;
+  storageKey?: string;
+  identifyProperties?: {
+    os: string;
+    browser: string;
+    device: string;
+  };
+  maxReconnectAttempts?: number;
+  reconnectDelays?: {
+    initial: number;
+    max: number;
+    backoffMultiplier: number;
+  };
+  onDispatch?: (event: string, data: unknown) => void;
+  logger?: Logger;
+  debug?: boolean;
+}
+
+export const DEFAULT_IDENTIFY_PROPERTIES = {
+  os: "cloudflare-workers",
+  browser: "discord-gateway",
+  device: "discord-gateway",
+} as const;
+

package/src/utils/logger.ts

@@ -0,0 +1,56 @@
+export enum LogLevel {
+  DEBUG = 0,
+  INFO = 1,
+  WARN = 2,
+  ERROR = 3,
+  NONE = 4,
+}
+
+export interface LoggerConfig {
+  level: LogLevel;
+  prefix?: string;
+}
+
+export class Logger {
+  private level: LogLevel;
+  private prefix: string;
+
+  constructor(config: LoggerConfig = { level: LogLevel.INFO }) {
+    this.level = config.level;
+    this.prefix = config.prefix || "[flarecord]";
+  }
+
+  debug(message: string, ...args: unknown[]): void {
+    if (this.level <= LogLevel.DEBUG) {
+      console.log(`${this.prefix} [DEBUG] ${message}`, ...args);
+    }
+  }
+
+  info(message: string, ...args: unknown[]): void {
+    if (this.level <= LogLevel.INFO) {
+      console.log(`${this.prefix} [INFO] ${message}`, ...args);
+    }
+  }
+
+  warn(message: string, ...args: unknown[]): void {
+    if (this.level <= LogLevel.WARN) {
+      console.warn(`${this.prefix} [WARN] ${message}`, ...args);
+    }
+  }
+
+  error(message: string, error?: Error | unknown, ...args: unknown[]): void {
+    if (this.level <= LogLevel.ERROR) {
+      const errorDetails = error instanceof Error ? error.stack : error;
+      console.error(`${this.prefix} [ERROR] ${message}`, errorDetails, ...args);
+    }
+  }
+
+  setLevel(level: LogLevel): void {
+    this.level = level;
+  }
+}
+
+export const createLogger = (config?: LoggerConfig): Logger => {
+  return new Logger(config);
+};
+

package/src/utils/message-helper.ts

@@ -0,0 +1,100 @@
+import {
+  REST,
+  Routes,
+  EmbedBuilder,
+  ActionRowBuilder,
+  type RESTPostAPIChannelMessageJSONBody,
+  type APIEmbed,
+} from "discord.js";
+
+type MessageContent =
+  | string
+  | EmbedBuilder
+  | ActionRowBuilder<never>
+  | RESTPostAPIChannelMessageJSONBody
+  | (EmbedBuilder | ActionRowBuilder<never>)[];
+
+interface NormalizedMessageBody {
+  content?: string;
+  embeds?: APIEmbed[];
+  components?: unknown[];
+  message_reference?: {
+    message_id: string;
+    channel_id: string;
+    guild_id?: string;
+  };
+}
+
+export class MessageHelper {
+  private rest: REST;
+
+  constructor(token: string) {
+    this.rest = new REST().setToken(token);
+  }
+
+  async send(channelId: string, content: MessageContent): Promise<unknown> {
+    const body = this.normalizeContent(content);
+    return this.rest.post(Routes.channelMessages(channelId), { body });
+  }
+
+  async reply(
+    channelId: string,
+    messageId: string,
+    guildId: string | undefined,
+    content: MessageContent
+  ): Promise<unknown> {
+    const body = this.normalizeContent(content);
+    const replyBody: RESTPostAPIChannelMessageJSONBody = {
+      ...body,
+      message_reference: {
+        message_id: messageId,
+        channel_id: channelId,
+        ...(guildId && { guild_id: guildId }),
+      },
+    };
+    return this.rest.post(Routes.channelMessages(channelId), {
+      body: replyBody,
+    });
+  }
+
+  private normalizeContent(content: MessageContent): RESTPostAPIChannelMessageJSONBody {
+    if (typeof content === "string") {
+      return { content };
+    }
+
+    if (content instanceof EmbedBuilder) {
+      return { embeds: [content.toJSON()] };
+    }
+
+    if (content instanceof ActionRowBuilder) {
+      const json = content.toJSON();
+      return {
+        components: [json],
+      } as RESTPostAPIChannelMessageJSONBody;
+    }
+
+    if (Array.isArray(content)) {
+      const embeds: APIEmbed[] = [];
+      const components: unknown[] = [];
+
+      for (const item of content) {
+        if (item instanceof EmbedBuilder) {
+          embeds.push(item.toJSON());
+        } else if (item instanceof ActionRowBuilder) {
+          components.push(item.toJSON());
+        }
+      }
+
+      const result: NormalizedMessageBody = {};
+      if (embeds.length > 0) {
+        result.embeds = embeds;
+      }
+      if (components.length > 0) {
+        result.components = components;
+      }
+      return result as RESTPostAPIChannelMessageJSONBody;
+    }
+
+    return content;
+  }
+}

package/src/utils/reconnect.ts

@@ -0,0 +1,108 @@
+import { DEFAULT_RECONNECT_DELAYS } from "../types/constants";
+import { GatewayState } from "../types";
+import type { DurableObjectState } from "@cloudflare/workers-types";
+
+export class ReconnectManager {
+  private reconnectAttempts = 0;
+  private maxReconnectAttempts: number;
+  private isReconnecting = false;
+  private reconnectDelays: {
+    initial: number;
+    max: number;
+    backoffMultiplier: number;
+  };
+
+  constructor(
+    maxReconnectAttempts: number = 5,
+    reconnectDelays = DEFAULT_RECONNECT_DELAYS
+  ) {
+    this.maxReconnectAttempts = maxReconnectAttempts;
+    this.reconnectDelays = reconnectDelays;
+  }
+
+  async scheduleReconnect(connectFn: () => Promise<void>): Promise<void> {
+    if (
+      this.isReconnecting ||
+      this.reconnectAttempts >= this.maxReconnectAttempts
+    ) {
+      return;
+    }
+
+    this.isReconnecting = true;
+    const delay = this.calculateDelay();
+    await new Promise((resolve) => setTimeout(resolve, delay));
+
+    this.reconnectAttempts++;
+    this.isReconnecting = false;
+    await connectFn();
+  }
+
+  async reconnect(
+    shouldResume: boolean,
+    ctx: DurableObjectState,
+    storageKey: string,
+    connectFn: () => Promise<void>,
+    closeFn: () => void
+  ): Promise<void> {
+    if (this.isReconnecting) {
+      return;
+    }
+    if (this.reconnectAttempts >= this.maxReconnectAttempts) {
+      throw new Error("Max reconnect attempts reached");
+    }
+
+    this.isReconnecting = true;
+    await ctx.storage.deleteAlarm().catch(() => {});
+    closeFn();
+
+    const state = await this.getState(ctx, storageKey);
+    if (state) {
+      await ctx.storage.put(storageKey, {
+        ...state,
+        shouldResume: shouldResume && state.sessionId !== null,
+        reconnectAttempts: this.reconnectAttempts + 1,
+      } satisfies GatewayState);
+    }
+
+    const delay = this.calculateDelay();
+    await new Promise((resolve) => setTimeout(resolve, delay));
+
+    this.reconnectAttempts++;
+    this.isReconnecting = false;
+    await connectFn();
+  }
+
+  reset(): void {
+    this.reconnectAttempts = 0;
+    this.isReconnecting = false;
+  }
+
+  private calculateDelay(): number {
+    return Math.min(
+      this.reconnectDelays.initial *
+        Math.pow(
+          this.reconnectDelays.backoffMultiplier,
+          this.reconnectAttempts
+        ),
+      this.reconnectDelays.max
+    );
+  }
+
+  private async getState(
+    ctx: DurableObjectState,
+    storageKey: string
+  ): Promise<GatewayState | null> {
+    const state = await ctx.storage.get(storageKey);
+    return this.validateState(state);
+  }
+
+  private validateState(state: unknown): GatewayState | null {
+    if (state === null || state === undefined) {
+      return null;
+    }
+    if (typeof state === "object" && "heartbeatInterval" in state) {
+      return state as GatewayState;
+    }
+    return null;
+  }
+}