@erinjs/core 1.0.0

package/core/packages/types/src/api/role.ts

@@ -0,0 +1,41 @@
+import { Snowflake } from '../common/snowflake.js';
+
+/**
+ * Role from GET /guilds/{id}/roles
+ * permissions is bitfield as string (e.g. "8933636165185")
+ */
+export interface APIRole {
+  id: Snowflake;
+  name: string;
+  color: number;
+  position: number;
+  hoist_position?: number | null;
+  permissions: string;
+  hoist: boolean;
+  mentionable: boolean;
+  unicode_emoji?: string | null;
+}
+
+/** Body for POST /guilds/{id}/roles (create role). All fields optional. */
+export interface RESTCreateRoleBody {
+  name?: string;
+  permissions?: string;
+  color?: number;
+  hoist?: boolean;
+  mentionable?: boolean;
+  unicode_emoji?: string | null;
+  position?: number;
+  hoist_position?: number | null;
+}
+
+/** Body for PATCH /guilds/{id}/roles/{roleId} (update role). All fields optional. */
+export interface RESTUpdateRoleBody {
+  name?: string;
+  permissions?: string;
+  color?: number;
+  hoist?: boolean;
+  mentionable?: boolean;
+  unicode_emoji?: string | null;
+  position?: number;
+  hoist_position?: number | null;
+}

package/core/packages/types/src/api/sticker.ts

@@ -0,0 +1,14 @@
+import { Snowflake } from '../common/snowflake.js';
+import { APIUser } from './user.js';
+
+export interface APISticker {
+  id: Snowflake;
+  name: string;
+  description: string;
+  tags: string[];
+  animated: boolean;
+}
+
+export interface APIStickerWithUser extends APISticker {
+  user?: APIUser;
+}

package/core/packages/types/src/api/user.ts

@@ -0,0 +1,79 @@
+import { Snowflake } from '../common/snowflake.js';
+
+/**
+ * Partial user object returned by the API (messages, members, webhooks, etc.).
+ * @see GET /users/{id} - Returns id, username, discriminator, global_name, avatar, avatar_color, flags
+ * @see GET /users/@me - Returns full user with bot, email, premium fields, etc.
+ */
+export interface APIUserPartial {
+  id: Snowflake;
+  username: string;
+  discriminator: string;
+  global_name?: string | null;
+  avatar?: string | null;
+  /** RGB color as number (e.g. 7577782) */
+  avatar_color?: number | null;
+  /** Public/user flags bitfield */
+  flags?: number | null;
+  /** @deprecated Use flags. Discord compat. */
+  public_flags?: number | null;
+  /** Present when author is a bot */
+  bot?: boolean;
+  /** Whether this is an official system user */
+  system?: boolean;
+  /** User banner hash (from profile, member, or invite context) */
+  banner?: string | null;
+}
+
+export type APIUser = APIUserPartial;
+
+/**
+ * User profile sub-object from GET /users/{id}/profile.
+ * @see https://docs.fluxer.app/api-reference
+ */
+export interface APIUserProfile {
+  pronouns?: string | null;
+  bio?: string | null;
+  banner?: string | null;
+  accent_color?: number | null;
+  banner_color?: number | null;
+  theme?: string | null;
+}
+
+/**
+ * Connected account from profile response.
+ */
+export interface APIConnectedAccount {
+  name?: string | null;
+  type?: string | null;
+}
+
+/**
+ * Full profile response from GET /users/{id}/profile.
+ * Optionally use ?guild_id=GUILD_ID for server-specific profile.
+ */
+export interface APIProfileResponse {
+  user_profile?: APIUserProfile | null;
+  mutual_guilds?: Array<{ id: Snowflake }> | null;
+  mutual_guild_ids?: Snowflake[] | null;
+  connected_accounts?: APIConnectedAccount[] | null;
+}
+
+/**
+ * Guild member from GET /guilds/{guild_id}/members or GET /guilds/{guild_id}/members/{user_id}
+ */
+export interface APIGuildMember {
+  user: APIUserPartial;
+  nick?: string | null;
+  avatar?: string | null;
+  banner?: string | null;
+  accent_color?: number | null;
+  roles: Snowflake[];
+  joined_at: string;
+  mute?: boolean;
+  deaf?: boolean;
+  communication_disabled_until?: string | null;
+  profile_flags?: number | null;
+  /** When the user started boosting this guild. */
+  premium_since?: string | null;
+}

package/core/packages/types/src/api/webhook.ts

@@ -0,0 +1,41 @@
+import { Snowflake } from '../common/snowflake.js';
+import { APIUser } from './user.js';
+
+export enum WebhookType {
+  Incoming = 1,
+  ChannelFollower = 2,
+}
+
+/**
+ * Webhook from GET /channels/{id}/webhooks (includes token) or GET /webhooks/{id} (no token)
+ */
+export interface APIWebhook {
+  id: Snowflake;
+  guild_id: Snowflake;
+  channel_id: Snowflake;
+  name: string;
+  avatar: string | null;
+  /** Present when listing channel webhooks; not returned when fetching by ID without token */
+  token?: string;
+  user: APIUser;
+}
+
+/** Request body for PATCH /webhooks/{id} (bot auth). All fields optional. */
+export interface APIWebhookUpdateRequest {
+  name?: string;
+  avatar?: string | null;
+  channel_id?: Snowflake;
+}
+
+/** Request body for PATCH /webhooks/{id}/{token} (token auth). All fields optional. */
+export interface APIWebhookTokenUpdateRequest {
+  name?: string;
+  avatar?: string | null;
+}
+
+/** Request body for PATCH /webhooks/{id}/{token}/messages/{message_id}. All fields optional. */
+export interface APIWebhookEditMessageRequest {
+  content?: string;
+  embeds?: unknown[];
+  attachments?: unknown[];
+}

package/core/packages/types/src/common/index.ts

@@ -0,0 +1 @@
+export * from './snowflake.js';

package/core/packages/types/src/common/snowflake.test.ts

@@ -0,0 +1,9 @@
+import { describe, it, expect } from 'vitest';
+import { FLUXER_EPOCH } from './snowflake.js';
+
+describe('snowflake common', () => {
+  it('FLUXER_EPOCH is 2015-01-01', () => {
+    expect(FLUXER_EPOCH).toBe(1420070400000);
+    expect(new Date(FLUXER_EPOCH).toISOString()).toBe('2015-01-01T00:00:00.000Z');
+  });
+});

package/core/packages/types/src/common/snowflake.ts

@@ -0,0 +1,8 @@
+/**
+ * Snowflake ID type - 64-bit unsigned integer as string.
+ * Fluxer uses Twitter Snowflakes with epoch 1420070400000 (first second of 2015).
+ */
+export type Snowflake = string;
+
+/** Fluxer epoch in milliseconds (2015-01-01 00:00:00 UTC) */
+export const FLUXER_EPOCH = 1420070400000;

package/core/packages/types/src/gateway/events.ts

@@ -0,0 +1,189 @@
+/**
+ * Gateway dispatch event names sent by the Fluxer gateway.
+ * Sourced from fluxer_gateway constants.erl. Use for type-safe event handling.
+ *
+ * @example
+ * ```ts
+ * if (payload.t === GatewayDispatchEvents.MessageCreate) {
+ *   // handle message
+ * }
+ * ```
+ */
+export const GatewayDispatchEvents = {
+  // ─── Connection & Session ─────────────────────────────────────────────────
+  /** Initial connection established; contains user, guilds, and session state. */
+  Ready: 'READY',
+  /** Connection resumed after disconnect; sequence restored. */
+  Resumed: 'RESUMED',
+  /** User's active sessions list replaced (e.g. new login). */
+  SessionsReplace: 'SESSIONS_REPLACE',
+
+  // ─── User ──────────────────────────────────────────────────────────────────
+  /** Current user's profile was updated. */
+  UserUpdate: 'USER_UPDATE',
+  /** User settings changed (theme, locale, etc.). */
+  UserSettingsUpdate: 'USER_SETTINGS_UPDATE',
+  /** Per-guild user settings changed (notifications, etc.). */
+  UserGuildSettingsUpdate: 'USER_GUILD_SETTINGS_UPDATE',
+  /** Pinned DM order changed. */
+  UserPinnedDmsUpdate: 'USER_PINNED_DMS_UPDATE',
+  /** Note on another user changed. */
+  UserNoteUpdate: 'USER_NOTE_UPDATE',
+  /** Recent mention was cleared. */
+  RecentMentionDelete: 'RECENT_MENTION_DELETE',
+
+  // ─── Saved Messages & Auth ─────────────────────────────────────────────────
+  /** Message was saved (bookmarked). */
+  SavedMessageCreate: 'SAVED_MESSAGE_CREATE',
+  /** Saved message was unsaved. */
+  SavedMessageDelete: 'SAVED_MESSAGE_DELETE',
+  /** Auth session changed (login/logout on another client). */
+  AuthSessionChange: 'AUTH_SESSION_CHANGE',
+
+  // ─── Presence ───────────────────────────────────────────────────────────────
+  /** User's presence (status, activity) updated. */
+  PresenceUpdate: 'PRESENCE_UPDATE',
+
+  // ─── Guild ─────────────────────────────────────────────────────────────────
+  /** Bot joined a guild or guild data became available. */
+  GuildCreate: 'GUILD_CREATE',
+  /** Guild was updated. */
+  GuildUpdate: 'GUILD_UPDATE',
+  /** Bot left or was removed from a guild. */
+  GuildDelete: 'GUILD_DELETE',
+  /** Member joined a guild. */
+  GuildMemberAdd: 'GUILD_MEMBER_ADD',
+  /** Member was updated (roles, nickname, etc.). */
+  GuildMemberUpdate: 'GUILD_MEMBER_UPDATE',
+  /** Member left or was removed from a guild. */
+  GuildMemberRemove: 'GUILD_MEMBER_REMOVE',
+  /** Chunk of guild members (from request_guild_members). */
+  GuildMembersChunk: 'GUILD_MEMBERS_CHUNK',
+  /** Member list view updated (lazy loading). */
+  GuildMemberListUpdate: 'GUILD_MEMBER_LIST_UPDATE',
+  /** Guild sync state (passive/lazy loading). */
+  GuildSync: 'GUILD_SYNC',
+
+  // ─── Roles ──────────────────────────────────────────────────────────────────
+  /** Role was created. */
+  GuildRoleCreate: 'GUILD_ROLE_CREATE',
+  /** Role was updated. */
+  GuildRoleUpdate: 'GUILD_ROLE_UPDATE',
+  /** Multiple roles updated at once. */
+  GuildRoleUpdateBulk: 'GUILD_ROLE_UPDATE_BULK',
+  /** Role was deleted. */
+  GuildRoleDelete: 'GUILD_ROLE_DELETE',
+
+  // ─── Guild Assets ───────────────────────────────────────────────────────────
+  /** Guild emojis changed. */
+  GuildEmojisUpdate: 'GUILD_EMOJIS_UPDATE',
+  /** Guild stickers changed. */
+  GuildStickersUpdate: 'GUILD_STICKERS_UPDATE',
+
+  // ─── Moderation ─────────────────────────────────────────────────────────────
+  /** User was banned from a guild. */
+  GuildBanAdd: 'GUILD_BAN_ADD',
+  /** User was unbanned from a guild. */
+  GuildBanRemove: 'GUILD_BAN_REMOVE',
+
+  // ─── Channels ──────────────────────────────────────────────────────────────
+  /** Channel was created. */
+  ChannelCreate: 'CHANNEL_CREATE',
+  /** Channel was updated. */
+  ChannelUpdate: 'CHANNEL_UPDATE',
+  /** Multiple channels updated at once. */
+  ChannelUpdateBulk: 'CHANNEL_UPDATE_BULK',
+  /** Channel was deleted. */
+  ChannelDelete: 'CHANNEL_DELETE',
+  /** Recipient added to group DM. */
+  ChannelRecipientAdd: 'CHANNEL_RECIPIENT_ADD',
+  /** Recipient removed from group DM. */
+  ChannelRecipientRemove: 'CHANNEL_RECIPIENT_REMOVE',
+  /** Pinned messages in a channel changed. */
+  ChannelPinsUpdate: 'CHANNEL_PINS_UPDATE',
+  /** User acknowledged viewing pinned messages. */
+  ChannelPinsAck: 'CHANNEL_PINS_ACK',
+
+  // ─── Internal / Passive ────────────────────────────────────────────────────
+  /** Passive/lazy-loaded entity updates. */
+  PassiveUpdates: 'PASSIVE_UPDATES',
+
+  // ─── Invites ───────────────────────────────────────────────────────────────
+  /** Invite was created. */
+  InviteCreate: 'INVITE_CREATE',
+  /** Invite was deleted or expired. */
+  InviteDelete: 'INVITE_DELETE',
+
+  // ─── Messages ──────────────────────────────────────────────────────────────
+  /** New message was sent. */
+  MessageCreate: 'MESSAGE_CREATE',
+  /** Message was edited. */
+  MessageUpdate: 'MESSAGE_UPDATE',
+  /** Message was deleted. */
+  MessageDelete: 'MESSAGE_DELETE',
+  /** Multiple messages were deleted. */
+  MessageDeleteBulk: 'MESSAGE_DELETE_BULK',
+  /** Reaction was added to a message. */
+  MessageReactionAdd: 'MESSAGE_REACTION_ADD',
+  /** Reaction was removed from a message. */
+  MessageReactionRemove: 'MESSAGE_REACTION_REMOVE',
+  /** All reactions were removed from a message. */
+  MessageReactionRemoveAll: 'MESSAGE_REACTION_REMOVE_ALL',
+  /** All reactions of an emoji were removed from a message. */
+  MessageReactionRemoveEmoji: 'MESSAGE_REACTION_REMOVE_EMOJI',
+  /** Message was acknowledged (read receipt). */
+  MessageAck: 'MESSAGE_ACK',
+
+  // ─── Typing ─────────────────────────────────────────────────────────────────
+  /** User started typing in a channel. */
+  TypingStart: 'TYPING_START',
+
+  // ─── Webhooks ───────────────────────────────────────────────────────────────
+  /** Webhooks for a channel were updated. */
+  WebhooksUpdate: 'WEBHOOKS_UPDATE',
+
+  // ─── Relationships ──────────────────────────────────────────────────────────
+  /** Relationship (friend, block) was added. */
+  RelationshipAdd: 'RELATIONSHIP_ADD',
+  /** Relationship was updated. */
+  RelationshipUpdate: 'RELATIONSHIP_UPDATE',
+  /** Relationship was removed. */
+  RelationshipRemove: 'RELATIONSHIP_REMOVE',
+
+  // ─── Voice ───────────────────────────────────────────────────────────────────
+  /** Voice state changed (join, leave, mute, etc.). */
+  VoiceStateUpdate: 'VOICE_STATE_UPDATE',
+  /** Voice server allocation info (for connecting to voice). */
+  VoiceServerUpdate: 'VOICE_SERVER_UPDATE',
+
+  // ─── Calls ──────────────────────────────────────────────────────────────────
+  /** Call was created. */
+  CallCreate: 'CALL_CREATE',
+  /** Call was updated. */
+  CallUpdate: 'CALL_UPDATE',
+  /** Call was ended. */
+  CallDelete: 'CALL_DELETE',
+
+  // ─── Favorites ──────────────────────────────────────────────────────────────
+  /** Favorite meme/media was added. */
+  FavoriteMemeCreate: 'FAVORITE_MEME_CREATE',
+  /** Favorite meme/media was updated. */
+  FavoriteMemeUpdate: 'FAVORITE_MEME_UPDATE',
+  /** Favorite meme/media was removed. */
+  FavoriteMemeDelete: 'FAVORITE_MEME_DELETE',
+
+  // ─── SDK / Compatibility (may come from API layer) ──────────────────────────
+  /** Slash command or component interaction. */
+  InteractionCreate: 'INTERACTION_CREATE',
+  /** Guild integrations changed. */
+  GuildIntegrationsUpdate: 'GUILD_INTEGRATIONS_UPDATE',
+  /** Guild scheduled event was created. */
+  GuildScheduledEventCreate: 'GUILD_SCHEDULED_EVENT_CREATE',
+  /** Guild scheduled event was updated. */
+  GuildScheduledEventUpdate: 'GUILD_SCHEDULED_EVENT_UPDATE',
+  /** Guild scheduled event was cancelled. */
+  GuildScheduledEventDelete: 'GUILD_SCHEDULED_EVENT_DELETE',
+} as const;
+
+export type GatewayDispatchEventName =
+  (typeof GatewayDispatchEvents)[keyof typeof GatewayDispatchEvents];

package/core/packages/types/src/gateway/index.ts

@@ -0,0 +1,3 @@
+export * from './opcodes.js';
+export * from './events.js';
+export * from './payloads.js';

package/core/packages/types/src/gateway/opcodes.ts

@@ -0,0 +1,17 @@
+/**
+ * Gateway opcodes (Discord-compatible).
+ * @see https://discord.com/developers/docs/topics/opcodes-and-status-codes#gateway-gateway-opcodes
+ */
+export enum GatewayOpcodes {
+  Dispatch = 0,
+  Heartbeat = 1,
+  Identify = 2,
+  PresenceUpdate = 3,
+  VoiceStateUpdate = 4,
+  Resume = 6,
+  Reconnect = 7,
+  RequestGuildMembers = 8,
+  InvalidSession = 9,
+  Hello = 10,
+  HeartbeatAck = 11,
+}