@erinjs/core 1.0.0

package/core/packages/types/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@erinjs/types",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "1.2.4",
+  "description": "TypeScript types for the Fluxer API",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/blstmo-abandoned-us-for-the-milk/core.git",
+    "directory": "packages/types"
+  },
+  "bugs": "https://github.com/blstmo-abandoned-us-for-the-milk/core/issues",
+  "homepage": "https://github.com/blstmo-abandoned-us-for-the-milk/core#readme",
+  "keywords": [
+    "fluxer",
+    "types",
+    "api"
+  ],
+  "license": "Apache-2.0",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "lint": "eslint src --max-warnings 0 --config ../../eslint.config.js",
+    "lint:fix": "eslint src --fix --config ../../eslint.config.js",
+    "test": "vitest run --passWithNoTests",
+    "test:coverage": "vitest run --coverage --passWithNoTests"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0"
+  }
+}

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

@@ -0,0 +1,8 @@
+import { APIUser } from './user.js';
+
+export interface APIBan {
+  user: APIUser;
+  reason: string | null;
+  /** ISO timestamp when a temporary ban expires. Null for permanent bans. */
+  expires_at?: string | null;
+}

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

@@ -0,0 +1,65 @@
+import { Snowflake } from '../common/snowflake.js';
+import { APIUser } from './user.js';
+
+/**
+ * Channel type enum (Fluxer/Discord compatible).
+ * API may return additional types (e.g. 998 for link channels with url).
+ */
+export enum ChannelType {
+  GuildText = 0,
+  DM = 1,
+  GuildVoice = 2,
+  GroupDM = 3,
+  GuildCategory = 4,
+  GuildLink = 5,
+  /** Fluxer link channel (GET /guilds/{id}/channels returns type 998 for url channels) */
+  GuildLinkExtended = 998,
+}
+
+/** Permission overwrite type */
+export enum OverwriteType {
+  Role = 0,
+  Member = 1,
+}
+
+/** Permission overwrite from GET /channels/{id} or GET /guilds/{id}/channels */
+export interface APIChannelOverwrite {
+  id: Snowflake;
+  type: OverwriteType;
+  allow: string;
+  deny: string;
+}
+
+/** Minimal channel (id, type required) */
+export interface APIChannelPartial {
+  id: Snowflake;
+  name?: string | null;
+  type: ChannelType | number;
+  icon?: string | null;
+  parent_id?: Snowflake | null;
+}
+
+/**
+ * Channel from GET /channels/{id} or GET /guilds/{id}/channels
+ */
+export interface APIChannel extends APIChannelPartial {
+  guild_id?: Snowflake | null;
+  name: string | null;
+  topic?: string | null;
+  /** External URL (link channels, type 998) */
+  url?: string | null;
+  icon?: string | null;
+  owner_id?: Snowflake | null;
+  position?: number;
+  parent_id: Snowflake | null;
+  bitrate?: number | null;
+  user_limit?: number | null;
+  rtc_region?: string | null;
+  last_message_id?: Snowflake | null;
+  last_pin_timestamp?: string | null;
+  permission_overwrites?: APIChannelOverwrite[];
+  recipients?: APIUser[];
+  nsfw?: boolean;
+  rate_limit_per_user?: number;
+  nicks?: Record<string, string>;
+}

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

@@ -0,0 +1,82 @@
+export interface APIEmbedAuthor {
+  name?: string;
+  url?: string;
+  icon_url?: string;
+  proxy_icon_url?: string;
+}
+
+export interface APIEmbedFooter {
+  text: string;
+  icon_url?: string;
+  proxy_icon_url?: string;
+}
+
+/** Bitwise flags for embed media. */
+export const EmbedMediaFlags = {
+  /** Embed media contains explicit content */
+  CONTAINS_EXPLICIT_MEDIA: 16,
+  /** Embed media is animated */
+  IS_ANIMATED: 32,
+} as const;
+
+export interface APIEmbedMedia {
+  url: string;
+  proxy_url?: string | null;
+  content_type?: string | null;
+  content_hash?: string | null;
+  width?: number | null;
+  height?: number | null;
+  description?: string | null;
+  /** Base64 placeholder for lazy loading */
+  placeholder?: string | null;
+  duration?: number | null;
+  /** EmbedMediaFlags bitfield (e.g. EmbedMediaFlags.CONTAINS_EXPLICIT_MEDIA) */
+  flags?: number | null;
+}
+
+export interface APIEmbedField {
+  name: string;
+  value: string;
+  inline?: boolean;
+}
+
+export type EmbedType = 'rich' | 'image' | 'video' | 'gifv' | 'article' | 'link';
+
+/** Nested embed from unfurlers (subset of APIEmbed) */
+export interface APIEmbedChild {
+  type?: EmbedType;
+  url?: string | null;
+  title?: string | null;
+  color?: number | null;
+  timestamp?: string | null;
+  description?: string | null;
+  author?: APIEmbedAuthor | null;
+  image?: APIEmbedMedia | null;
+  thumbnail?: APIEmbedMedia | null;
+  footer?: APIEmbedFooter | null;
+  fields?: APIEmbedField[] | null;
+  provider?: APIEmbedAuthor | null;
+  video?: APIEmbedMedia | null;
+  audio?: APIEmbedMedia | null;
+  nsfw?: boolean | null;
+}
+
+export interface APIEmbed {
+  type?: EmbedType;
+  url?: string | null;
+  title?: string | null;
+  color?: number | null;
+  timestamp?: string | null;
+  description?: string | null;
+  author?: APIEmbedAuthor | null;
+  image?: APIEmbedMedia | null;
+  thumbnail?: APIEmbedMedia | null;
+  footer?: APIEmbedFooter | null;
+  fields?: APIEmbedField[] | null;
+  provider?: APIEmbedAuthor | null;
+  video?: APIEmbedMedia | null;
+  audio?: APIEmbedMedia | null;
+  nsfw?: boolean | null;
+  /** Nested embeds from unfurlers */
+  children?: APIEmbedChild[] | null;
+}

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

@@ -0,0 +1,12 @@
+import { Snowflake } from '../common/snowflake.js';
+import { APIUser } from './user.js';
+
+export interface APIEmoji {
+  id: Snowflake;
+  name: string;
+  animated: boolean;
+}
+
+export interface APIEmojiWithUser extends APIEmoji {
+  user?: APIUser;
+}

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

@@ -0,0 +1,68 @@
+/**
+ * API error codes returned by the Fluxer API.
+ * Subset of commonly used codes for bot development.
+ */
+export enum APIErrorCode {
+  // Auth
+  Unauthorized = 'UNAUTHORIZED',
+  Forbidden = 'FORBIDDEN',
+  MissingAuthorization = 'MISSING_AUTHORIZATION',
+  InvalidAuthToken = 'INVALID_AUTH_TOKEN',
+  InvalidToken = 'INVALID_TOKEN',
+  TwoFactorRequired = 'TWO_FACTOR_REQUIRED',
+  SudoModeRequired = 'SUDO_MODE_REQUIRED',
+
+  // Not found
+  NotFound = 'NOT_FOUND',
+  UnknownUser = 'UNKNOWN_USER',
+  UnknownGuild = 'UNKNOWN_GUILD',
+  UnknownChannel = 'UNKNOWN_CHANNEL',
+  UnknownMessage = 'UNKNOWN_MESSAGE',
+  UnknownRole = 'UNKNOWN_ROLE',
+  UnknownEmoji = 'UNKNOWN_EMOJI',
+  UnknownSticker = 'UNKNOWN_STICKER',
+  UnknownWebhook = 'UNKNOWN_WEBHOOK',
+  UnknownInvite = 'UNKNOWN_INVITE',
+
+  // Validation
+  BadRequest = 'BAD_REQUEST',
+  ValidationError = 'VALIDATION_ERROR',
+  InvalidRequest = 'INVALID_REQUEST',
+  InvalidFormBody = 'INVALID_FORM_BODY',
+
+  // Rate limit
+  RateLimited = 'RATE_LIMITED',
+  SlowmodeRateLimited = 'SLOWMODE_RATE_LIMITED',
+
+  // Server
+  InternalServerError = 'INTERNAL_SERVER_ERROR',
+  BadGateway = 'BAD_GATEWAY',
+  GatewayTimeout = 'GATEWAY_TIMEOUT',
+  ServiceUnavailable = 'SERVICE_UNAVAILABLE',
+
+  // Bot-specific
+  BotsCannotSendFriendRequests = 'BOTS_CANNOT_SEND_FRIEND_REQUESTS',
+  BotAlreadyInGuild = 'BOT_ALREADY_IN_GUILD',
+  BotApplicationNotFound = 'BOT_APPLICATION_NOT_FOUND',
+  BotIsPrivate = 'BOT_IS_PRIVATE',
+  NotABotApplication = 'NOT_A_BOT_APPLICATION',
+
+  // Content
+  CannotSendEmptyMessage = 'CANNOT_SEND_EMPTY_MESSAGE',
+  FileSizeTooLarge = 'FILE_SIZE_TOO_LARGE',
+  MaxEmojis = 'MAX_EMOJIS',
+  MaxStickers = 'MAX_STICKERS',
+  MaxWebhooks = 'MAX_WEBHOOKS',
+}
+
+export interface APIErrorBody {
+  code: APIErrorCode | string;
+  message: string;
+  errors?: Array<{ path: string; message: string; code?: string }>;
+}
+
+export interface RateLimitErrorBody extends APIErrorBody {
+  code: 'RATE_LIMITED';
+  retry_after: number;
+  global?: boolean;
+}

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

@@ -0,0 +1,14 @@
+/**
+ * Response from GET /gateway/bot
+ * url: WebSocket URL, session_start_limit: rate limit info in ms
+ */
+export interface APIGatewayBotResponse {
+  url: string;
+  shards: number;
+  session_start_limit: {
+    total: number;
+    remaining: number;
+    reset_after: number;
+    max_concurrency: number;
+  };
+}

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

@@ -0,0 +1,123 @@
+import { Snowflake } from '../common/snowflake.js';
+
+export enum GuildVerificationLevel {
+  None = 0,
+  Low = 1,
+  Medium = 2,
+  High = 3,
+  VeryHigh = 4,
+}
+
+export enum GuildMFALevel {
+  None = 0,
+  Elevated = 1,
+}
+
+export enum GuildExplicitContentFilter {
+  Disabled = 0,
+  MembersWithoutRoles = 1,
+  AllMembers = 2,
+}
+
+export enum DefaultMessageNotifications {
+  AllMessages = 0,
+  OnlyMentions = 1,
+}
+
+export type GuildFeature =
+  | 'ANIMATED_ICON'
+  | 'ANIMATED_BANNER'
+  | 'BANNER'
+  | 'DETACHED_BANNER'
+  | 'INVITE_SPLASH'
+  | 'INVITES_DISABLED'
+  | 'TEXT_CHANNEL_FLEXIBLE_NAMES'
+  | 'MORE_EMOJI'
+  | 'MORE_STICKERS'
+  | 'UNLIMITED_EMOJI'
+  | 'UNLIMITED_STICKERS'
+  | 'EXPRESSION_PURGE_ALLOWED'
+  | 'VANITY_URL'
+  | 'VERIFIED'
+  | 'VIP_VOICE'
+  | 'UNAVAILABLE_FOR_EVERYONE'
+  | 'UNAVAILABLE_FOR_EVERYONE_BUT_STAFF'
+  | 'VISIONARY'
+  | 'OPERATOR'
+  | 'LARGE_GUILD_OVERRIDE'
+  | 'VERY_LARGE_GUILD'
+  | 'MT_MESSAGE_SCHEDULING'
+  | 'MT_EXPRESSION_PACKS';
+
+/**
+ * Guild from GET /guilds/{id} or gateway GUILD_CREATE
+ */
+export interface APIGuild {
+  id: Snowflake;
+  name: string;
+  icon: string | null;
+  banner: string | null;
+  banner_width?: number | null;
+  banner_height?: number | null;
+  splash?: string | null;
+  splash_width?: number | null;
+  splash_height?: number | null;
+  splash_card_alignment?: number;
+  embed_splash?: string | null;
+  embed_splash_width?: number | null;
+  embed_splash_height?: number | null;
+  vanity_url_code?: string | null;
+  owner_id: Snowflake;
+  system_channel_id?: Snowflake | null;
+  system_channel_flags?: number;
+  rules_channel_id?: Snowflake | null;
+  afk_channel_id?: Snowflake | null;
+  afk_timeout: number;
+  features: GuildFeature[];
+  verification_level: GuildVerificationLevel;
+  mfa_level: GuildMFALevel;
+  nsfw_level: number;
+  explicit_content_filter: GuildExplicitContentFilter;
+  default_message_notifications: DefaultMessageNotifications;
+  disabled_operations?: number;
+  message_history_cutoff?: string | null;
+  permissions?: string | null;
+}
+
+/** Audit log entry from GET /guilds/{id}/audit-logs */
+export interface APIGuildAuditLogEntry {
+  id: string;
+  action_type: number;
+  user_id?: Snowflake | null;
+  target_id?: Snowflake | null;
+  reason?: string | null;
+  /** Changed fields. Value types vary by action_type (e.g. string for name, number for permissions). */
+  changes?: Array<{
+    key: string;
+    old_value?: string | number | boolean | null;
+    new_value?: string | number | boolean | null;
+  }>;
+}
+
+/** Response from GET /guilds/{id}/vanity-url */
+export interface APIVanityURL {
+  code: string | null;
+  uses: number;
+}
+
+/** Request body for guild feature toggles (text-channel-flexible-names, etc.) */
+export interface APIGuildFeatureToggle {
+  enabled: boolean;
+}
+
+/** Response from GET /guilds/{id}/audit-logs */
+export interface APIGuildAuditLog {
+  audit_log_entries: APIGuildAuditLogEntry[];
+  users: Array<{
+    id: Snowflake;
+    username?: string;
+    discriminator?: string;
+    avatar?: string | null;
+  }>;
+  webhooks: Array<{ id: Snowflake; name?: string; avatar?: string | null }>;
+}

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

@@ -0,0 +1,15 @@
+export * from './channel.js';
+export * from './user.js';
+export * from './guild.js';
+export * from './embed.js';
+export * from './message.js';
+export * from './role.js';
+export * from './emoji.js';
+export * from './sticker.js';
+export * from './webhook.js';
+export * from './invite.js';
+export * from './ban.js';
+export * from './errors.js';
+export * from './gateway.js';
+export * from './instance.js';
+export * from './interaction.js';

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

@@ -0,0 +1,32 @@
+/**
+ * Response from GET /instance (unauthenticated).
+ * Instance info and API/gateway endpoints.
+ */
+export interface APIInstance {
+  api_code_version: string | number;
+  endpoints: {
+    api: string;
+    gateway: string;
+    api_client?: string;
+    api_public?: string;
+    media?: string;
+    static_cdn?: string;
+    marketing?: string;
+    admin?: string;
+    invite?: string;
+    gift?: string;
+    webapp?: string;
+    [key: string]: unknown;
+  };
+  captcha?: Record<string, unknown>;
+  features?: {
+    voice_enabled?: boolean;
+    self_hosted?: boolean;
+    stripe_enabled?: boolean;
+    sms_mfa_enabled?: boolean;
+    manual_review_enabled?: boolean;
+    [key: string]: unknown;
+  };
+  push?: Record<string, unknown>;
+  [key: string]: unknown;
+}

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

@@ -0,0 +1,26 @@
+import { APIUser } from './user.js';
+import { APIGuildMember } from './user.js';
+import { Snowflake } from '../common/snowflake.js';
+
+/** Application command option value (string, number, or boolean). */
+export type APIApplicationCommandOptionValue = string | number | boolean;
+
+/** Minimal application command interaction (slash command) payload from the gateway. */
+export interface APIApplicationCommandInteraction {
+  id: string;
+  application_id: string;
+  type: number;
+  token: string;
+  data?: {
+    id?: string;
+    name: string;
+    type?: number;
+    options?: Array<{ name: string; type: number; value?: APIApplicationCommandOptionValue }>;
+  };
+  guild_id?: string;
+  channel_id?: string;
+  /** Guild member (when interaction is in a guild). Includes user. */
+  member?: APIGuildMember & { guild_id?: Snowflake };
+  /** User who ran the command (DM context or fallback). */
+  user?: APIUser;
+}

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

@@ -0,0 +1,28 @@
+import { Snowflake } from '../common/snowflake.js';
+import { APIUser } from './user.js';
+import { APIChannelPartial } from './channel.js';
+
+export interface APIGuildPartial {
+  id: Snowflake;
+  name: string;
+  icon?: string | null;
+  banner?: string | null;
+  splash?: string | null;
+  features?: string[];
+}
+
+export interface APIInvite {
+  code: string;
+  type: number;
+  guild: APIGuildPartial;
+  channel: APIChannelPartial;
+  inviter?: APIUser | null;
+  member_count?: number;
+  presence_count?: number;
+  expires_at?: string | null;
+  temporary?: boolean;
+  created_at?: string;
+  uses?: number;
+  max_uses?: number;
+  max_age?: number;
+}

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

@@ -0,0 +1,140 @@
+import { Snowflake } from '../common/snowflake.js';
+import { APIUser } from './user.js';
+import { APIGuildMember } from './user.js';
+import { APIEmbed } from './embed.js';
+
+export enum MessageType {
+  Default = 0,
+  RecipientAdd = 1,
+  RecipientRemove = 2,
+  Call = 3,
+  ChannelNameChange = 4,
+  ChannelIconChange = 5,
+  ChannelPinnedMessage = 6,
+  UserJoin = 7,
+  Reply = 19,
+}
+
+export enum MessageFlags {
+  SuppressEmbeds = 4,
+  SuppressNotifications = 4096,
+  VoiceMessage = 8192,
+  CompactAttachments = 131072,
+}
+
+export interface APIReactionEmoji {
+  id: Snowflake | null;
+  name: string;
+  animated?: boolean | null;
+}
+
+export interface APIMessageReaction {
+  emoji: APIReactionEmoji;
+  count: number;
+  me?: boolean | null;
+}
+
+/** Reply/forward reference from GET /channels/{id}/messages (type 0 = reply) */
+export interface APIMessageReference {
+  channel_id: Snowflake;
+  message_id: Snowflake;
+  guild_id?: Snowflake | null;
+  /** 0 = reply, 1 = forward */
+  type?: number;
+}
+
+/** Call metadata for call-type messages */
+export interface APIMessageCall {
+  participants: string[];
+  ended_timestamp?: string | null;
+}
+
+/** Snapshot of a forwarded message */
+export interface APIMessageSnapshot {
+  content?: string | null;
+  timestamp: string;
+  edited_timestamp?: string | null;
+  mentions?: string[] | null;
+  mention_roles?: Snowflake[] | null;
+  embeds?: APIEmbed[] | null;
+  attachments?: APIMessageAttachment[] | null;
+  stickers?: APIMessageSticker[] | null;
+  type?: number;
+}
+
+/** Bitwise flags for message attachments (when sending, use in attachments metadata). */
+export const MessageAttachmentFlags = {
+  /** Renders attachment as spoiler (blurred until clicked) */
+  IS_SPOILER: 8,
+  /** Attachment contains explicit content */
+  CONTAINS_EXPLICIT_MEDIA: 16,
+  /** Animated image (e.g. GIF, animated WebP). Renders with EmbedGif / looping behavior. */
+  IS_ANIMATED: 32,
+} as const;
+
+export interface APIMessageAttachment {
+  id: Snowflake;
+  filename: string;
+  title?: string | null;
+  description?: string | null;
+  content_type?: string | null;
+  /** Hash of attachment content for integrity */
+  content_hash?: string | null;
+  size: number;
+  url?: string | null;
+  proxy_url?: string | null;
+  width?: number | null;
+  height?: number | null;
+  /** Base64 placeholder for lazy loading */
+  placeholder?: string | null;
+  /** MessageAttachmentFlags bitfield */
+  flags?: number | null;
+  nsfw?: boolean | null;
+  duration?: number | null;
+  /** Base64 audio waveform for voice messages */
+  waveform?: string | null;
+  expires_at?: string | null;
+  expired?: boolean | null;
+}
+
+export interface APIMessageSticker {
+  id: Snowflake;
+  name: string;
+  description?: string;
+  tags?: string[];
+  animated?: boolean;
+}
+
+/**
+ * Message from GET /channels/{id}/messages, POST /channels/{id}/messages, PATCH, or gateway MESSAGE_CREATE
+ */
+export interface APIMessage {
+  id: Snowflake;
+  channel_id: Snowflake;
+  guild_id?: Snowflake | null;
+  author: APIUser;
+  webhook_id?: Snowflake | null;
+  type: MessageType;
+  flags: number;
+  content: string;
+  timestamp: string;
+  edited_timestamp: string | null;
+  pinned: boolean;
+  mention_everyone?: boolean;
+  tts?: boolean;
+  mentions?: APIUser[] | null;
+  mention_roles?: Snowflake[] | null;
+  embeds?: APIEmbed[] | null;
+  attachments?: APIMessageAttachment[] | null;
+  stickers?: APIMessageSticker[] | null;
+  reactions?: APIMessageReaction[] | null;
+  message_reference?: APIMessageReference | null;
+  /** Snapshots of forwarded messages */
+  message_snapshots?: APIMessageSnapshot[] | null;
+  nonce?: string | null;
+  /** Call info when type is Call */
+  call?: APIMessageCall | null;
+  referenced_message?: APIMessage | null;
+  /** Author's guild member (gateway MESSAGE_CREATE only, when guild message) */
+  member?: APIGuildMember | null;
+}