@erinjs/core 1.0.0

package/core/apps/docs/src/data/apiEndpoints.ts

@@ -0,0 +1,1073 @@
+/**
+ * Bot and Webhook API reference data.
+ * Source: fluxer_api (Hono routes under /v1).
+ */
+
+export interface ApiQueryParam {
+  name: string;
+  type: string;
+  required?: boolean;
+  description?: string;
+}
+
+export interface ApiSchemaField {
+  name: string;
+  type: string;
+  required?: boolean;
+  description?: string;
+  items?: ApiSchemaField[];
+  nested?: ApiSchemaField[];
+}
+
+export interface ApiEndpoint {
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  path: string;
+  summary: string;
+  description?: string;
+  auth: 'bot' | 'webhook-token' | 'none';
+  category: string;
+  queryParams?: ApiQueryParam[];
+  requestBody?: ApiSchemaField[];
+  responseBody?: ApiSchemaField[];
+  responseCode?: number;
+  responseRef?: string;
+}
+
+/** Shared schema definitions referenced by multiple endpoints */
+export const sharedSchemas = {
+  messageRequest: [
+    {
+      name: 'content',
+      type: 'string | null',
+      required: false,
+      description: 'Message text content',
+    },
+    { name: 'embeds', type: 'RichEmbed[]', required: false, description: 'Rich embeds (max 10)' },
+    {
+      name: 'attachments',
+      type: 'AttachmentRequest[]',
+      required: false,
+      description: 'Attachment refs (max 10)',
+    },
+    {
+      name: 'message_reference',
+      type: '{ message_id, channel_id?, guild_id?, type? }',
+      required: false,
+    },
+    {
+      name: 'allowed_mentions',
+      type: '{ parse?, users?, roles?, replied_user? }',
+      required: false,
+    },
+    { name: 'flags', type: 'number', required: false, description: 'Message flags (default 0)' },
+    { name: 'nonce', type: 'string', required: false, description: '1-32 chars, for idempotency' },
+    { name: 'favorite_meme_id', type: 'string (snowflake)', required: false },
+    { name: 'sticker_ids', type: 'string[]', required: false, description: 'Max 3 sticker IDs' },
+    { name: 'tts', type: 'boolean', required: false },
+  ] as ApiSchemaField[],
+  messageUpdate: [
+    { name: 'content', type: 'string | null', required: false },
+    { name: 'embeds', type: 'RichEmbed[]', required: false },
+    {
+      name: 'allowed_mentions',
+      type: '{ parse?, users?, roles?, replied_user? }',
+      required: false,
+    },
+    { name: 'flags', type: 'number', required: false },
+    { name: 'attachments', type: 'AttachmentReference[]', required: false },
+  ] as ApiSchemaField[],
+  richEmbed: [
+    { name: 'url', type: 'string', required: false },
+    { name: 'title', type: 'string', required: false },
+    { name: 'color', type: 'number', required: false },
+    { name: 'timestamp', type: 'ISO datetime', required: false },
+    { name: 'description', type: 'string (1-4096)', required: false },
+    { name: 'author', type: '{ name, url?, icon_url? }', required: false },
+    { name: 'image', type: '{ url, description? }', required: false },
+    { name: 'thumbnail', type: '{ url, description? }', required: false },
+    { name: 'footer', type: '{ text, icon_url? }', required: false },
+    { name: 'fields', type: '{ name, value, inline? }[]', required: false, description: 'Max 25' },
+  ] as ApiSchemaField[],
+  channelOverwrite: [
+    { name: 'id', type: 'string (snowflake)', required: true },
+    { name: 'type', type: '0 | 1', required: true, description: '0=role, 1=member' },
+    { name: 'allow', type: 'string (permission bitfield)', required: false },
+    { name: 'deny', type: 'string (permission bitfield)', required: false },
+  ] as ApiSchemaField[],
+};
+
+export const API_CATEGORIES = [
+  'gateway',
+  'instance',
+  'channels',
+  'messages',
+  'pins-reactions',
+  'guilds',
+  'invites',
+  'webhooks',
+] as const;
+
+export const API_CATEGORY_LABELS: Record<(typeof API_CATEGORIES)[number], string> = {
+  gateway: 'Gateway',
+  instance: 'Instance',
+  channels: 'Channels',
+  messages: 'Messages',
+  'pins-reactions': 'Pins & Reactions',
+  guilds: 'Guilds',
+  invites: 'Invites',
+  webhooks: 'Webhooks',
+};
+
+export const apiEndpoints: ApiEndpoint[] = [
+  // --- Gateway ---
+  {
+    method: 'GET',
+    path: '/gateway/bot',
+    summary: 'Get gateway connection URL for bot',
+    auth: 'bot',
+    category: 'gateway',
+    responseBody: [
+      { name: 'url', type: 'string', description: 'WebSocket URL' },
+      { name: 'shards', type: 'number', description: 'Recommended shard count (1)' },
+      {
+        name: 'session_start_limit',
+        type: 'object',
+        nested: [
+          { name: 'total', type: 'number' },
+          { name: 'remaining', type: 'number' },
+          { name: 'reset_after', type: 'number', description: 'ms' },
+          { name: 'max_concurrency', type: 'number' },
+        ],
+      },
+    ],
+  },
+
+  // --- Instance ---
+  {
+    method: 'GET',
+    path: '/instance',
+    summary: 'Get instance info and endpoints',
+    auth: 'none',
+    category: 'instance',
+    responseBody: [
+      { name: 'api_code_version', type: 'string' },
+      {
+        name: 'endpoints',
+        type: 'object',
+        nested: [
+          { name: 'api', type: 'string' },
+          { name: 'gateway', type: 'string' },
+        ],
+      },
+      { name: 'captcha', type: 'object' },
+      { name: 'features', type: 'object', nested: [{ name: 'voice_enabled', type: 'boolean' }] },
+      { name: 'push', type: 'object' },
+    ],
+  },
+
+  // --- Channels ---
+  {
+    method: 'GET',
+    path: '/channels/:channel_id',
+    summary: 'Get channel',
+    auth: 'bot',
+    category: 'channels',
+    responseRef: 'ChannelResponse',
+  },
+  {
+    method: 'PATCH',
+    path: '/channels/:channel_id',
+    summary: 'Update channel',
+    auth: 'bot',
+    category: 'channels',
+    requestBody: [
+      { name: 'type', type: 'number', required: true, description: 'Channel type (required)' },
+      { name: 'name', type: 'string', required: false },
+      { name: 'topic', type: 'string (1-1024)', required: false },
+      { name: 'url', type: 'string', required: false },
+      { name: 'parent_id', type: 'string (snowflake)', required: false },
+      { name: 'bitrate', type: 'number (8000-320000)', required: false },
+      { name: 'user_limit', type: 'number (0-99)', required: false },
+      { name: 'nsfw', type: 'boolean', required: false },
+      { name: 'rate_limit_per_user', type: 'number (0-21600)', required: false },
+      { name: 'icon', type: 'base64 string', required: false },
+      { name: 'owner_id', type: 'string (snowflake)', required: false },
+      { name: 'permission_overwrites', type: 'ChannelOverwrite[]', required: false },
+      { name: 'nicks', type: 'Record<string, string>', required: false },
+      { name: 'rtc_region', type: 'string (1-64)', required: false },
+    ],
+    responseRef: 'ChannelResponse',
+  },
+  {
+    method: 'DELETE',
+    path: '/channels/:channel_id',
+    summary: 'Delete channel',
+    auth: 'bot',
+    category: 'channels',
+    queryParams: [{ name: 'silent', type: 'boolean', required: false }],
+    responseCode: 204,
+  },
+  {
+    method: 'PUT',
+    path: '/channels/:channel_id/recipients/:user_id',
+    summary: 'Add recipient to group DM',
+    auth: 'bot',
+    category: 'channels',
+    responseCode: 204,
+  },
+  {
+    method: 'DELETE',
+    path: '/channels/:channel_id/recipients/:user_id',
+    summary: 'Remove recipient from group DM',
+    auth: 'bot',
+    category: 'channels',
+    queryParams: [{ name: 'silent', type: 'boolean', required: false }],
+    responseCode: 204,
+  },
+  {
+    method: 'PUT',
+    path: '/channels/:channel_id/permissions/:overwrite_id',
+    summary: 'Set permission overwrite',
+    auth: 'bot',
+    category: 'channels',
+    requestBody: [
+      { name: 'type', type: '0 | 1', required: true, description: '0=role, 1=member' },
+      { name: 'allow', type: 'string (snowflake)', required: false },
+      { name: 'deny', type: 'string (snowflake)', required: false },
+    ],
+    responseCode: 204,
+  },
+  {
+    method: 'DELETE',
+    path: '/channels/:channel_id/permissions/:overwrite_id',
+    summary: 'Delete permission overwrite',
+    auth: 'bot',
+    category: 'channels',
+    responseCode: 204,
+  },
+
+  // --- Messages ---
+  {
+    method: 'GET',
+    path: '/channels/:channel_id/messages',
+    summary: 'List channel messages',
+    auth: 'bot',
+    category: 'messages',
+    queryParams: [
+      { name: 'limit', type: 'number (1-100)', required: false, description: 'Default 50' },
+      { name: 'before', type: 'string (snowflake)', required: false },
+      { name: 'after', type: 'string (snowflake)', required: false },
+      { name: 'around', type: 'string (snowflake)', required: false },
+    ],
+    responseRef: 'MessageResponse[]',
+  },
+  {
+    method: 'GET',
+    path: '/channels/:channel_id/messages/:message_id',
+    summary: 'Get message',
+    auth: 'bot',
+    category: 'messages',
+    responseRef: 'MessageResponse',
+  },
+  {
+    method: 'POST',
+    path: '/channels/:channel_id/messages',
+    summary: 'Send message',
+    auth: 'bot',
+    category: 'messages',
+    description: 'Accepts JSON or multipart/form-data',
+    requestBody: sharedSchemas.messageRequest,
+    responseRef: 'MessageResponse',
+  },
+  {
+    method: 'PATCH',
+    path: '/channels/:channel_id/messages/:message_id',
+    summary: 'Edit message',
+    auth: 'bot',
+    category: 'messages',
+    requestBody: sharedSchemas.messageUpdate,
+    responseRef: 'MessageResponse',
+  },
+  {
+    method: 'DELETE',
+    path: '/channels/:channel_id/messages/:message_id',
+    summary: 'Delete message',
+    auth: 'bot',
+    category: 'messages',
+    responseCode: 204,
+  },
+  {
+    method: 'DELETE',
+    path: '/channels/:channel_id/messages/:message_id/attachments/:attachment_id',
+    summary: 'Delete message attachment',
+    auth: 'bot',
+    category: 'messages',
+    responseCode: 204,
+  },
+  {
+    method: 'POST',
+    path: '/channels/:channel_id/messages/bulk-delete',
+    summary: 'Bulk delete messages',
+    auth: 'bot',
+    category: 'messages',
+    requestBody: [{ name: 'message_ids', type: 'string[] (snowflakes)', required: true }],
+    responseCode: 204,
+  },
+  {
+    method: 'POST',
+    path: '/channels/:channel_id/typing',
+    summary: 'Trigger typing indicator',
+    auth: 'bot',
+    category: 'messages',
+    responseCode: 204,
+  },
+
+  // --- Pins & Reactions ---
+  {
+    method: 'GET',
+    path: '/channels/:channel_id/messages/pins',
+    summary: 'List pinned messages',
+    auth: 'bot',
+    category: 'pins-reactions',
+    queryParams: [
+      { name: 'limit', type: 'number (1-50)', required: false },
+      { name: 'before', type: 'ISO datetime', required: false },
+    ],
+    responseRef: 'ChannelPinResponse[]',
+  },
+  {
+    method: 'PUT',
+    path: '/channels/:channel_id/pins/:message_id',
+    summary: 'Pin message',
+    auth: 'bot',
+    category: 'pins-reactions',
+    responseCode: 204,
+  },
+  {
+    method: 'DELETE',
+    path: '/channels/:channel_id/pins/:message_id',
+    summary: 'Unpin message',
+    auth: 'bot',
+    category: 'pins-reactions',
+    responseCode: 204,
+  },
+  {
+    method: 'GET',
+    path: '/channels/:channel_id/messages/:message_id/reactions/:emoji',
+    summary: 'Get users who reacted',
+    auth: 'bot',
+    category: 'pins-reactions',
+    queryParams: [
+      { name: 'limit', type: 'number', required: false },
+      { name: 'after', type: 'string (snowflake)', required: false },
+    ],
+    responseRef: 'UserPartialResponse[]',
+  },
+  {
+    method: 'PUT',
+    path: '/channels/:channel_id/messages/:message_id/reactions/:emoji/@me',
+    summary: 'Add own reaction',
+    auth: 'bot',
+    category: 'pins-reactions',
+    responseCode: 204,
+  },
+  {
+    method: 'DELETE',
+    path: '/channels/:channel_id/messages/:message_id/reactions/:emoji/@me',
+    summary: 'Remove own reaction',
+    auth: 'bot',
+    category: 'pins-reactions',
+    responseCode: 204,
+  },
+  {
+    method: 'DELETE',
+    path: '/channels/:channel_id/messages/:message_id/reactions/:emoji/:target_id',
+    summary: 'Remove user reaction',
+    auth: 'bot',
+    category: 'pins-reactions',
+    responseCode: 204,
+  },
+  {
+    method: 'DELETE',
+    path: '/channels/:channel_id/messages/:message_id/reactions/:emoji',
+    summary: 'Remove all reactions for emoji',
+    auth: 'bot',
+    category: 'pins-reactions',
+    responseCode: 204,
+  },
+  {
+    method: 'DELETE',
+    path: '/channels/:channel_id/messages/:message_id/reactions',
+    summary: 'Remove all reactions',
+    auth: 'bot',
+    category: 'pins-reactions',
+    responseCode: 204,
+  },
+
+  // --- Guilds ---
+  {
+    method: 'POST',
+    path: '/guilds',
+    summary: 'Create guild',
+    auth: 'bot',
+    category: 'guilds',
+    requestBody: [
+      { name: 'name', type: 'string (1-100)', required: true },
+      { name: 'icon', type: 'base64 string', required: false },
+      { name: 'empty_features', type: 'boolean', required: false },
+    ],
+    responseRef: 'GuildResponse',
+  },
+  {
+    method: 'GET',
+    path: '/guilds/:guild_id',
+    summary: 'Get guild',
+    auth: 'bot',
+    category: 'guilds',
+    responseRef: 'GuildResponse',
+  },
+  {
+    method: 'PATCH',
+    path: '/guilds/:guild_id',
+    summary: 'Update guild',
+    auth: 'bot',
+    category: 'guilds',
+    requestBody: [
+      { name: 'name', type: 'string (1-100)', required: false },
+      { name: 'icon', type: 'base64', required: false },
+      { name: 'system_channel_id', type: 'string | null', required: false },
+      { name: 'system_channel_flags', type: 'number', required: false },
+      { name: 'afk_channel_id', type: 'string | null', required: false },
+      { name: 'afk_timeout', type: 'number (60-3600)', required: false },
+      { name: 'default_message_notifications', type: 'number (0-1)', required: false },
+      { name: 'verification_level', type: 'number', required: false },
+      { name: 'mfa_level', type: 'number', required: false },
+      { name: 'explicit_content_filter', type: 'number', required: false },
+      { name: 'banner', type: 'base64', required: false },
+      { name: 'splash', type: 'base64', required: false },
+      { name: 'embed_splash', type: 'base64', required: false },
+      { name: 'splash_card_alignment', type: 'string', required: false },
+      { name: 'features', type: 'string[]', required: false },
+    ],
+    responseRef: 'GuildResponse',
+  },
+  {
+    method: 'POST',
+    path: '/guilds/:guild_id/delete',
+    summary: 'Delete guild',
+    auth: 'bot',
+    category: 'guilds',
+    responseCode: 204,
+  },
+  {
+    method: 'GET',
+    path: '/guilds/:guild_id/vanity-url',
+    summary: 'Get vanity URL',
+    auth: 'bot',
+    category: 'guilds',
+    responseBody: [
+      { name: 'code', type: 'string | null' },
+      { name: 'uses', type: 'number' },
+    ],
+  },
+  {
+    method: 'PATCH',
+    path: '/guilds/:guild_id/text-channel-flexible-names',
+    summary: 'Update text channel flexible names',
+    auth: 'bot',
+    category: 'guilds',
+    requestBody: [{ name: 'enabled', type: 'boolean', required: true }],
+    responseRef: 'GuildResponse',
+  },
+  {
+    method: 'PATCH',
+    path: '/guilds/:guild_id/detached-banner',
+    summary: 'Update detached banner feature',
+    auth: 'bot',
+    category: 'guilds',
+    requestBody: [{ name: 'enabled', type: 'boolean', required: true }],
+    responseRef: 'GuildResponse',
+  },
+  {
+    method: 'PATCH',
+    path: '/guilds/:guild_id/disallow-unclaimed-accounts',
+    summary: 'Update disallow unclaimed accounts',
+    auth: 'bot',
+    category: 'guilds',
+    requestBody: [{ name: 'enabled', type: 'boolean', required: true }],
+    responseRef: 'GuildResponse',
+  },
+  {
+    method: 'GET',
+    path: '/guilds/:guild_id/channels',
+    summary: 'List guild channels',
+    auth: 'bot',
+    category: 'guilds',
+    responseRef: 'ChannelResponse[]',
+  },
+  {
+    method: 'POST',
+    path: '/guilds/:guild_id/channels',
+    summary: 'Create channel',
+    auth: 'bot',
+    category: 'guilds',
+    requestBody: [
+      {
+        name: 'type',
+        type: 'number',
+        required: true,
+        description: '0=text, 2=voice, 4=category, 5=link',
+      },
+      { name: 'name', type: 'string', required: true },
+      { name: 'topic', type: 'string (1-1024)', required: false },
+      { name: 'url', type: 'string', required: false },
+      { name: 'parent_id', type: 'string (snowflake)', required: false },
+      { name: 'bitrate', type: 'number (8000-320000)', required: false },
+      { name: 'user_limit', type: 'number (0-99)', required: false },
+      { name: 'nsfw', type: 'boolean', required: false },
+      { name: 'permission_overwrites', type: 'ChannelOverwrite[]', required: false },
+    ],
+    responseRef: 'ChannelResponse',
+  },
+  {
+    method: 'PATCH',
+    path: '/guilds/:guild_id/channels',
+    summary: 'Reorder channels',
+    auth: 'bot',
+    category: 'guilds',
+    description: 'Request body is array of channel update objects',
+    requestBody: [
+      { name: 'id', type: 'string (snowflake)', required: true, description: 'Per item in array' },
+      { name: 'position', type: 'number', required: false },
+      { name: 'parent_id', type: 'string | null', required: false },
+      { name: 'lock_permissions', type: 'boolean', required: false },
+    ],
+    responseCode: 204,
+  },
+  {
+    method: 'GET',
+    path: '/guilds/:guild_id/members',
+    summary: 'List guild members',
+    auth: 'bot',
+    category: 'guilds',
+    queryParams: [
+      { name: 'limit', type: 'number', required: false },
+      { name: 'after', type: 'string (snowflake)', required: false },
+    ],
+    responseRef: 'GuildMemberResponse[]',
+  },
+  {
+    method: 'GET',
+    path: '/guilds/:guild_id/members/@me',
+    summary: 'Get current member',
+    auth: 'bot',
+    category: 'guilds',
+    responseRef: 'GuildMemberResponse',
+  },
+  {
+    method: 'GET',
+    path: '/guilds/:guild_id/members/:user_id',
+    summary: 'Get guild member',
+    auth: 'bot',
+    category: 'guilds',
+    responseRef: 'GuildMemberResponse',
+  },
+  {
+    method: 'PATCH',
+    path: '/guilds/:guild_id/members/@me',
+    summary: 'Update current member',
+    auth: 'bot',
+    category: 'guilds',
+    requestBody: [
+      { name: 'nick', type: 'string (1-32)', required: false },
+      { name: 'avatar', type: 'base64', required: false },
+      { name: 'banner', type: 'base64', required: false },
+      { name: 'bio', type: 'string (1-320)', required: false },
+      { name: 'pronouns', type: 'string (1-40)', required: false },
+      { name: 'accent_color', type: 'number', required: false },
+      { name: 'profile_flags', type: 'number', required: false },
+      { name: 'mute', type: 'boolean', required: false },
+      { name: 'deaf', type: 'boolean', required: false },
+      { name: 'communication_disabled_until', type: 'ISO datetime', required: false },
+      { name: 'timeout_reason', type: 'string (1-512)', required: false },
+      { name: 'channel_id', type: 'string (snowflake)', required: false },
+      { name: 'connection_id', type: 'string (1-32)', required: false },
+    ],
+    responseRef: 'GuildMemberResponse',
+  },
+  {
+    method: 'PATCH',
+    path: '/guilds/:guild_id/members/:user_id',
+    summary: 'Update guild member',
+    auth: 'bot',
+    category: 'guilds',
+    requestBody: [
+      { name: 'nick', type: 'string (1-32)', required: false },
+      { name: 'roles', type: 'string[] (snowflakes, max 100)', required: false },
+      { name: 'avatar', type: 'base64', required: false },
+      { name: 'banner', type: 'base64', required: false },
+      { name: 'bio', type: 'string (1-320)', required: false },
+      { name: 'pronouns', type: 'string (1-40)', required: false },
+      { name: 'accent_color', type: 'number', required: false },
+      { name: 'profile_flags', type: 'number', required: false },
+      { name: 'mute', type: 'boolean', required: false },
+      { name: 'deaf', type: 'boolean', required: false },
+      { name: 'communication_disabled_until', type: 'ISO datetime', required: false },
+      { name: 'timeout_reason', type: 'string (1-512)', required: false },
+      { name: 'channel_id', type: 'string (snowflake)', required: false },
+      { name: 'connection_id', type: 'string (1-32)', required: false },
+    ],
+    responseRef: 'GuildMemberResponse',
+  },
+  {
+    method: 'DELETE',
+    path: '/guilds/:guild_id/members/:user_id',
+    summary: 'Remove guild member',
+    auth: 'bot',
+    category: 'guilds',
+    responseCode: 204,
+  },
+  {
+    method: 'POST',
+    path: '/guilds/:guild_id/transfer-ownership',
+    summary: 'Transfer guild ownership',
+    auth: 'bot',
+    category: 'guilds',
+    requestBody: [
+      { name: 'new_owner_id', type: 'string (snowflake)', required: true },
+      { name: 'password', type: 'string', required: false },
+    ],
+    responseRef: 'GuildResponse',
+  },
+  {
+    method: 'GET',
+    path: '/guilds/:guild_id/bans',
+    summary: 'List guild bans',
+    auth: 'bot',
+    category: 'guilds',
+    queryParams: [
+      { name: 'limit', type: 'number', required: false },
+      { name: 'after', type: 'string (snowflake)', required: false },
+    ],
+    responseRef: 'GuildBanResponse[]',
+  },
+  {
+    method: 'PUT',
+    path: '/guilds/:guild_id/bans/:user_id',
+    summary: 'Ban user',
+    auth: 'bot',
+    category: 'guilds',
+    requestBody: [
+      {
+        name: 'delete_message_days',
+        type: 'number (0-7)',
+        required: false,
+        description: 'Default 0',
+      },
+      { name: 'reason', type: 'string (0-512)', required: false },
+      {
+        name: 'ban_duration_seconds',
+        type: 'number',
+        required: false,
+        description: '0=permanent, or valid temp duration',
+      },
+    ],
+    responseRef: 'GuildBanResponse',
+  },
+  {
+    method: 'DELETE',
+    path: '/guilds/:guild_id/bans/:user_id',
+    summary: 'Unban user',
+    auth: 'bot',
+    category: 'guilds',
+    responseCode: 204,
+  },
+  {
+    method: 'PUT',
+    path: '/guilds/:guild_id/members/:user_id/roles/:role_id',
+    summary: 'Add role to member',
+    auth: 'bot',
+    category: 'guilds',
+    responseCode: 204,
+  },
+  {
+    method: 'DELETE',
+    path: '/guilds/:guild_id/members/:user_id/roles/:role_id',
+    summary: 'Remove role from member',
+    auth: 'bot',
+    category: 'guilds',
+    responseCode: 204,
+  },
+  {
+    method: 'GET',
+    path: '/guilds/:guild_id/roles',
+    summary: 'List guild roles',
+    auth: 'bot',
+    category: 'guilds',
+    responseRef: 'GuildRoleResponse[]',
+  },
+  {
+    method: 'POST',
+    path: '/guilds/:guild_id/roles',
+    summary: 'Create role',
+    auth: 'bot',
+    category: 'guilds',
+    requestBody: [
+      { name: 'name', type: 'string (1-100)', required: true },
+      { name: 'color', type: 'number', required: false, description: 'Default 0' },
+      { name: 'permissions', type: 'string (snowflake)', required: false },
+    ],
+    responseRef: 'GuildRoleResponse',
+  },
+  {
+    method: 'PATCH',
+    path: '/guilds/:guild_id/roles',
+    summary: 'Reorder roles',
+    auth: 'bot',
+    category: 'guilds',
+    requestBody: [
+      { name: 'id', type: 'string (snowflake)', required: true },
+      { name: 'position', type: 'number', required: false },
+    ],
+    responseRef: 'GuildRoleResponse[]',
+  },
+  {
+    method: 'PATCH',
+    path: '/guilds/:guild_id/roles/hoist-positions',
+    summary: 'Update role hoist positions',
+    auth: 'bot',
+    category: 'guilds',
+    requestBody: [
+      { name: 'id', type: 'string (snowflake)', required: true },
+      { name: 'hoist_position', type: 'number', required: false },
+    ],
+    responseRef: 'GuildRoleResponse[]',
+  },
+  {
+    method: 'DELETE',
+    path: '/guilds/:guild_id/roles/hoist-positions',
+    summary: 'Reset role hoist positions',
+    auth: 'bot',
+    category: 'guilds',
+    responseRef: 'GuildRoleResponse[]',
+  },
+  {
+    method: 'PATCH',
+    path: '/guilds/:guild_id/roles/:role_id',
+    summary: 'Update role',
+    auth: 'bot',
+    category: 'guilds',
+    requestBody: [
+      { name: 'name', type: 'string (1-100)', required: false },
+      { name: 'color', type: 'number', required: false },
+      { name: 'permissions', type: 'string (snowflake)', required: false },
+      { name: 'hoist', type: 'boolean', required: false },
+      { name: 'hoist_position', type: 'number', required: false },
+      { name: 'mentionable', type: 'boolean', required: false },
+    ],
+    responseRef: 'GuildRoleResponse',
+  },
+  {
+    method: 'DELETE',
+    path: '/guilds/:guild_id/roles/:role_id',
+    summary: 'Delete role',
+    auth: 'bot',
+    category: 'guilds',
+    responseCode: 204,
+  },
+  {
+    method: 'GET',
+    path: '/guilds/:guild_id/emojis',
+    summary: 'List guild emojis',
+    auth: 'bot',
+    category: 'guilds',
+    responseRef: 'GuildEmojiResponse[]',
+  },
+  {
+    method: 'POST',
+    path: '/guilds/:guild_id/emojis',
+    summary: 'Create emoji',
+    auth: 'bot',
+    category: 'guilds',
+    requestBody: [
+      { name: 'name', type: 'string (2-32, letters/numbers/underscore)', required: true },
+      { name: 'image', type: 'base64 string', required: true },
+    ],
+    responseRef: 'GuildEmojiWithUserResponse',
+  },
+  {
+    method: 'POST',
+    path: '/guilds/:guild_id/emojis/bulk',
+    summary: 'Bulk create emojis',
+    auth: 'bot',
+    category: 'guilds',
+    requestBody: [
+      {
+        name: 'emojis',
+        type: 'GuildEmojiCreateRequest[]',
+        required: true,
+        description: '1-50 emojis',
+      },
+    ],
+    responseRef: 'GuildEmojiWithUserResponse[]',
+  },
+  {
+    method: 'PATCH',
+    path: '/guilds/:guild_id/emojis/:emoji_id',
+    summary: 'Update emoji',
+    auth: 'bot',
+    category: 'guilds',
+    requestBody: [{ name: 'name', type: 'string (2-32)', required: true }],
+    responseRef: 'GuildEmojiWithUserResponse',
+  },
+  {
+    method: 'DELETE',
+    path: '/guilds/:guild_id/emojis/:emoji_id',
+    summary: 'Delete emoji',
+    auth: 'bot',
+    category: 'guilds',
+    responseCode: 204,
+  },
+  {
+    method: 'GET',
+    path: '/guilds/:guild_id/stickers',
+    summary: 'List guild stickers',
+    auth: 'bot',
+    category: 'guilds',
+    responseRef: 'GuildStickerResponse[]',
+  },
+  {
+    method: 'POST',
+    path: '/guilds/:guild_id/stickers',
+    summary: 'Create sticker',
+    auth: 'bot',
+    category: 'guilds',
+    requestBody: [
+      { name: 'name', type: 'string (2-30)', required: true },
+      { name: 'description', type: 'string (1-100)', required: false },
+      { name: 'tags', type: 'string[]', required: false, description: 'Max 10, each 1-30 chars' },
+      { name: 'image', type: 'base64 string', required: true },
+    ],
+    responseRef: 'GuildStickerWithUserResponse',
+  },
+  {
+    method: 'POST',
+    path: '/guilds/:guild_id/stickers/bulk',
+    summary: 'Bulk create stickers',
+    auth: 'bot',
+    category: 'guilds',
+    requestBody: [
+      {
+        name: 'stickers',
+        type: 'GuildStickerCreateRequest[]',
+        required: true,
+        description: '1-50 stickers',
+      },
+    ],
+    responseRef: 'GuildStickerWithUserResponse[]',
+  },
+  {
+    method: 'PATCH',
+    path: '/guilds/:guild_id/stickers/:sticker_id',
+    summary: 'Update sticker',
+    auth: 'bot',
+    category: 'guilds',
+    requestBody: [
+      { name: 'name', type: 'string (2-30)', required: false },
+      { name: 'description', type: 'string (1-100)', required: false },
+      { name: 'tags', type: 'string[]', required: false },
+    ],
+    responseRef: 'GuildStickerWithUserResponse',
+  },
+  {
+    method: 'DELETE',
+    path: '/guilds/:guild_id/stickers/:sticker_id',
+    summary: 'Delete sticker',
+    auth: 'bot',
+    category: 'guilds',
+    responseCode: 204,
+  },
+
+  // --- Invites ---
+  {
+    method: 'GET',
+    path: '/invites/:invite_code',
+    summary: 'Get invite',
+    auth: 'bot',
+    category: 'invites',
+    responseRef: 'GuildInviteResponse | GroupDmInviteResponse | PackInviteResponse',
+  },
+  {
+    method: 'DELETE',
+    path: '/invites/:invite_code',
+    summary: 'Delete invite',
+    auth: 'bot',
+    category: 'invites',
+    responseCode: 204,
+  },
+  {
+    method: 'POST',
+    path: '/channels/:channel_id/invites',
+    summary: 'Create channel invite',
+    auth: 'bot',
+    category: 'invites',
+    requestBody: [
+      { name: 'max_uses', type: 'number (0-100)', required: false, description: 'Default 0' },
+      {
+        name: 'max_age',
+        type: 'number (0-604800)',
+        required: false,
+        description: 'Seconds, default 0',
+      },
+      { name: 'unique', type: 'boolean', required: false, description: 'Default false' },
+      { name: 'temporary', type: 'boolean', required: false, description: 'Default false' },
+    ],
+    responseRef: 'GuildInviteMetadataResponse',
+  },
+  {
+    method: 'GET',
+    path: '/channels/:channel_id/invites',
+    summary: 'List channel invites',
+    auth: 'bot',
+    category: 'invites',
+    responseRef: 'InviteMetadata[]',
+  },
+  {
+    method: 'GET',
+    path: '/guilds/:guild_id/invites',
+    summary: 'List guild invites',
+    auth: 'bot',
+    category: 'invites',
+    responseRef: 'InviteMetadata[]',
+  },
+
+  // --- Webhooks ---
+  {
+    method: 'GET',
+    path: '/guilds/:guild_id/webhooks',
+    summary: 'List guild webhooks',
+    auth: 'bot',
+    category: 'webhooks',
+    responseRef: 'WebhookResponse[]',
+  },
+  {
+    method: 'GET',
+    path: '/channels/:channel_id/webhooks',
+    summary: 'List channel webhooks',
+    auth: 'bot',
+    category: 'webhooks',
+    responseRef: 'WebhookResponse[]',
+  },
+  {
+    method: 'POST',
+    path: '/channels/:channel_id/webhooks',
+    summary: 'Create webhook',
+    auth: 'bot',
+    category: 'webhooks',
+    requestBody: [
+      { name: 'name', type: 'string', required: true },
+      { name: 'avatar', type: 'base64 string', required: false },
+    ],
+    responseRef: 'WebhookResponse',
+  },
+  {
+    method: 'GET',
+    path: '/webhooks/:webhook_id',
+    summary: 'Get webhook (bot token)',
+    auth: 'bot',
+    category: 'webhooks',
+    responseRef: 'WebhookResponse',
+  },
+  {
+    method: 'GET',
+    path: '/webhooks/:webhook_id/:token',
+    summary: 'Get webhook (token auth)',
+    auth: 'webhook-token',
+    category: 'webhooks',
+    responseRef: 'WebhookResponse',
+  },
+  {
+    method: 'PATCH',
+    path: '/webhooks/:webhook_id',
+    summary: 'Update webhook (bot token)',
+    auth: 'bot',
+    category: 'webhooks',
+    requestBody: [
+      { name: 'name', type: 'string', required: false },
+      { name: 'avatar', type: 'base64', required: false },
+      { name: 'channel_id', type: 'string (snowflake)', required: false },
+    ],
+    responseRef: 'WebhookResponse',
+  },
+  {
+    method: 'PATCH',
+    path: '/webhooks/:webhook_id/:token',
+    summary: 'Update webhook (token auth)',
+    auth: 'webhook-token',
+    category: 'webhooks',
+    requestBody: [
+      { name: 'name', type: 'string', required: false },
+      { name: 'avatar', type: 'base64', required: false },
+      { name: 'channel_id', type: 'string (snowflake)', required: false },
+    ],
+    responseRef: 'WebhookResponse',
+  },
+  {
+    method: 'DELETE',
+    path: '/webhooks/:webhook_id',
+    summary: 'Delete webhook (bot token)',
+    auth: 'bot',
+    category: 'webhooks',
+    responseCode: 204,
+  },
+  {
+    method: 'DELETE',
+    path: '/webhooks/:webhook_id/:token',
+    summary: 'Delete webhook (token auth)',
+    auth: 'webhook-token',
+    category: 'webhooks',
+    responseCode: 204,
+  },
+  {
+    method: 'POST',
+    path: '/webhooks/:webhook_id/:token',
+    summary: 'Execute webhook',
+    auth: 'webhook-token',
+    category: 'webhooks',
+    description: 'Token in URL. Use ?wait=true to receive MessageResponse instead of 204.',
+    queryParams: [
+      { name: 'wait', type: 'boolean', required: false, description: 'Return message if true' },
+    ],
+    requestBody: [
+      ...sharedSchemas.messageRequest,
+      {
+        name: 'username',
+        type: 'string',
+        required: false,
+        description: 'Override webhook username',
+      },
+      {
+        name: 'avatar_url',
+        type: 'string (URL)',
+        required: false,
+        description: 'Override webhook avatar',
+      },
+    ],
+    responseBody: [
+      {
+        name: '204 or MessageResponse',
+        type: 'see MessageResponse',
+        description: 'If wait=true returns message',
+      },
+    ],
+    responseCode: 204,
+  },
+];
+
+export function getEndpointsByCategory() {
+  const byCategory: Record<string, ApiEndpoint[]> = {};
+  for (const cat of API_CATEGORIES) {
+    byCategory[cat] = apiEndpoints.filter((e) => e.category === cat);
+  }
+  return byCategory;
+}