yuzuha 0.2.0 → 0.2.1

package/src/infrastructure/fluxer/resources/instance.ts

@@ -0,0 +1,105 @@
+import type { Client } from '@fluxerjs/core';
+import type { APIApplicationMe, APIInstance, APIInstanceEndpoints, APIOAuthApplication } from '@fluxerjs/types';
+import type {
+  ApplicationInfo,
+  InstanceInfo,
+  InstanceResources,
+} from '../../../ports/resources/instance.js';
+
+function instanceInfo(endpoints: APIInstanceEndpoints, discovery: APIInstance | null): InstanceInfo {
+  return {
+    apiCodeVersion: discovery?.api_code_version ?? null,
+    codename: discovery?.codename ?? null,
+    endpoints: {
+      api: endpoints.api,
+      apiClient: endpoints.api_client,
+      apiPublic: endpoints.api_public,
+      gateway: endpoints.gateway,
+      media: endpoints.media,
+      staticCDN: endpoints.static_cdn,
+      marketing: endpoints.marketing,
+      admin: endpoints.admin,
+      invite: endpoints.invite,
+      gift: endpoints.gift,
+      webapp: endpoints.webapp,
+    },
+    features: discovery?.features ? {
+      voiceEnabled: discovery.features.voice_enabled,
+      stripeEnabled: discovery.features.stripe_enabled,
+      selfHosted: discovery.features.self_hosted,
+      presignedAttachmentUploads: discovery.features.presigned_attachment_uploads,
+      emailsEnabled: discovery.features.emails_enabled,
+    } : null,
+    registrationMode: discovery?.registration?.mode ?? null,
+    ssoEnabled: discovery?.sso?.enabled ?? null,
+    ssoEnforced: discovery?.sso?.enforced ?? null,
+    singleCommunity: discovery?.community?.single_community ?? null,
+    singleCommunityGuildID: discovery?.community?.single_community_guild_id ?? null,
+    directMessagesDisabled: discovery?.community?.direct_messages_disabled ?? null,
+    services: discovery?.services ? {
+      gif: discovery.services.gif_enabled,
+      youtube: discovery.services.youtube_enabled,
+      bluesky: discovery.services.bluesky_enabled,
+    } : null,
+  };
+}
+
+function applicationInfo(application: APIApplicationMe | APIOAuthApplication): ApplicationInfo {
+  return {
+    id: application.id,
+    name: application.name,
+    icon: application.icon ?? null,
+    description: application.description ?? null,
+    botPublic: application.bot_public ?? null,
+    botRequireCodeGrant: application.bot_require_code_grant ?? null,
+    verifyKey: 'verify_key' in application ? application.verify_key ?? null : null,
+    flags: 'flags' in application ? application.flags ?? null : null,
+    ownerID: 'owner' in application ? application.owner?.id ?? null : null,
+    botID: 'bot' in application ? application.bot?.id ?? null : null,
+    redirectURIs: 'redirect_uris' in application ? [...application.redirect_uris ?? []] : [],
+    clientSecret: 'client_secret' in application ? application.client_secret ?? null : null,
+  };
+}
+
+export function createInstanceResources(client: Client): InstanceResources {
+  return {
+    async describe() {
+      const resolved = client.instance;
+      const fetched = await client.fetchInstance();
+      return instanceInfo(fetched?.endpoints ?? resolved.endpoints, fetched ?? resolved.discovery);
+    },
+    async gatewayInfo() {
+      const info = await client.fetchGatewayInfo();
+      const limit = info.session_start_limit;
+      return {
+        url: info.url,
+        shards: info.shards,
+        sessionStartLimit: limit ? {
+          total: limit.total,
+          remaining: limit.remaining,
+          resetAfter: limit.reset_after,
+          maxConcurrency: limit.max_concurrency,
+        } : null,
+      };
+    },
+    async application() {
+      return applicationInfo(await client.fetchApplication());
+    },
+    async oauthApplications() {
+      return (await client.fetchOAuthApplications()).map(applicationInfo);
+    },
+    async emojiMetadata(emojiID) {
+      const metadata = await client.fetchEmojiMetadata(emojiID);
+      return { id: metadata.id, guildID: metadata.guild_id, name: metadata.name,
+        animated: metadata.animated, allowCloning: metadata.allow_cloning };
+    },
+    async stickerMetadata(stickerID) {
+      const metadata = await client.fetchStickerMetadata(stickerID);
+      return { id: metadata.id, guildID: metadata.guild_id, name: metadata.name,
+        animated: metadata.animated, allowCloning: metadata.allow_cloning };
+    },
+    resolveEmoji(emoji, guildID) {
+      return client.resolveEmoji(emoji, guildID);
+    },
+  };
+}

package/src/infrastructure/fluxer/resources/messages.ts

@@ -4,7 +4,7 @@ import type { ReceivedEmbed, ReceivedEmbedMedia } from '../../../domain/messages
 import { limitOf } from '../../../ports/resources/common.js';
 import type { AttachmentSpec, BinaryAttachmentSpec } from '../../../ports/resources/common.js';
 import { YuzuhaError } from '../../../errors.js';
-import type { MessageInfo, MessagesResources } from '../../../ports/resources/messages.js';
+import type { BulkFetchRawChannel, MessageInfo, MessageSearchInput, MessageSearchPage, MessagesResources } from '../../../ports/resources/messages.js';
 import { preloadChannels } from '../../../domain/resource-batches.js';
 import { messageSearchInput, pinnedMessagesInput, reactionUsersInput } from '../../../domain/message-query.js';
 
@@ -27,7 +27,7 @@ function receivedEmbed(embed: MessageEmbed): ReceivedEmbed {
   };
 }
 
-function info(message: Message): MessageInfo {
+export function toMessageInfo(message: Message): MessageInfo {
   return {
     id: message.id, channelID: message.channelId, authorID: message.author.id,
     authorName: message.author.username, content: message.content,
@@ -59,14 +59,43 @@ export function createMessagesResources(client: Client): MessagesResources {
       allowedMentions: { parse: [], repliedUser: false },
     })).id;
   };
+  const search = async (rawInput: MessageSearchInput): Promise<MessageSearchPage> => {
+    const input = messageSearchInput(rawInput);
+    const result = await client.searchMessages({ content: input.content,
+      contextGuildId: input.guildID, contextChannelId: input.channelID,
+      channelIds: input.channelIDs ?? (input.channelID ? [input.channelID] : undefined),
+      authorIds: input.authorIDs ?? (input.authorID ? [input.authorID] : undefined),
+      hitsPerPage: limitOf(input.limit, 25, 100), cursor: input.cursor,
+      ...(input.contents === undefined ? {} : { contents: input.contents }),
+      ...(input.exactPhrases === undefined ? {} : { exactPhrases: input.exactPhrases }),
+      ...(input.excludeChannelIDs === undefined ? {} : { excludeChannelIds: input.excludeChannelIDs }),
+      ...(input.excludeAuthorIDs === undefined ? {} : { excludeAuthorIds: input.excludeAuthorIDs }),
+      ...(input.authorType === undefined ? {} : { authorType: input.authorType }),
+      ...(input.excludeAuthorType === undefined ? {} : { excludeAuthorType: input.excludeAuthorType }),
+      ...(input.mentions === undefined ? {} : { mentions: input.mentions }),
+      ...(input.excludeMentions === undefined ? {} : { excludeMentions: input.excludeMentions }),
+      ...(input.mentionEveryone === undefined ? {} : { mentionEveryone: input.mentionEveryone }),
+      ...(input.pinned === undefined ? {} : { pinned: input.pinned }),
+      ...(input.includeNsfw === undefined ? {} : { includeNsfw: input.includeNsfw }),
+      ...(input.has === undefined ? {} : { has: input.has }),
+      ...(input.excludeHas === undefined ? {} : { excludeHas: input.excludeHas }),
+      ...(input.minID === undefined ? {} : { minId: input.minID }),
+      ...(input.maxID === undefined ? {} : { maxId: input.maxID }),
+      ...(input.sortBy === undefined ? {} : { sortBy: input.sortBy }),
+      ...(input.sortOrder === undefined ? {} : { sortOrder: input.sortOrder }),
+      ...(input.page === undefined ? {} : { page: input.page }) });
+    if ('indexing' in result) return { indexing: true, messages: [], total: 0, cursor: null };
+    return { indexing: false, messages: result.messages.map(data => toMessageInfo(new Message(client, data))),
+      total: result.total, cursor: result.cursor ?? null };
+  };
   return {
     async preload(channelIDs) {
       const ids = preloadChannels(channelIDs);
       const result = await client.preloadMessages(ids);
-      return Object.fromEntries(ids.map(id => [id, result[id] ? info(new Message(client, result[id])) : null]));
+      return Object.fromEntries(ids.map(id => [id, result[id] ? toMessageInfo(new Message(client, result[id])) : null]));
     },
     async fetch(channelID: string, messageID: string): Promise<MessageInfo> {
-      return info(await client.channels.fetchMessage(channelID, messageID));
+      return toMessageInfo(await client.channels.fetchMessage(channelID, messageID));
     },
     async list(channelID, limit, cursor = {}): Promise<MessageInfo[]> {
       if (Object.values(cursor).filter(value => value !== undefined).length > 1) {
@@ -75,7 +104,7 @@ export function createMessagesResources(client: Client): MessagesResources {
       const channel = await client.channels.fetch(channelID, { force: true });
       if (!channel.isTextBased()) throw new YuzuhaError('CHANNEL_TEXT', 'Canal sem suporte a mensagens.');
       const messages = await channel.messages.fetch({ limit: limitOf(limit, 20, 100), ...cursor });
-      return order([...messages.values()].map(info));
+      return order([...messages.values()].map(toMessageInfo));
     },
     async pin(channelID: string, messageID: string): Promise<void> {
       await (await client.channels.fetchMessage(channelID, messageID)).pin();
@@ -90,14 +119,14 @@ export function createMessagesResources(client: Client): MessagesResources {
       const messages = limit === undefined
         ? await channel.fetchPinnedMessages()
         : await channel.fetchPinnedMessagesPage({ limit }).then(page => page.messages);
-      return order(messages.map(info));
+      return order(messages.map(toMessageInfo));
     },
     async pinnedPage(channelID, input) {
       const options = pinnedMessagesInput(input);
       const channel = await client.channels.fetch(channelID, { force: true });
       if (!channel.isTextBased()) throw new YuzuhaError('CHANNEL_TEXT', 'Canal sem suporte a mensagens.');
       const page = await channel.fetchPinnedMessagesPage(options);
-      return { messages: page.messages.map(info), pinnedAt: [...page.pinnedAt], hasMore: page.hasMore,
+      return { messages: page.messages.map(toMessageInfo), pinnedAt: [...page.pinnedAt], hasMore: page.hasMore,
         nextBefore: page.hasMore ? page.pinnedAt.at(-1) ?? null : null };
     },
     sendFiles: send,
@@ -111,34 +140,19 @@ export function createMessagesResources(client: Client): MessagesResources {
         allowedMentions: { parse: [], repliedUser: false },
       })).id;
     },
-    async search(rawInput) {
-      const input = messageSearchInput(rawInput);
-      const result = await client.searchMessages({ content: input.content,
-        contextGuildId: input.guildID, contextChannelId: input.channelID,
-        channelIds: input.channelIDs ?? (input.channelID ? [input.channelID] : undefined),
-        authorIds: input.authorIDs ?? (input.authorID ? [input.authorID] : undefined),
-        hitsPerPage: limitOf(input.limit, 25, 100), cursor: input.cursor,
-        ...(input.contents === undefined ? {} : { contents: input.contents }),
-        ...(input.exactPhrases === undefined ? {} : { exactPhrases: input.exactPhrases }),
-        ...(input.excludeChannelIDs === undefined ? {} : { excludeChannelIds: input.excludeChannelIDs }),
-        ...(input.excludeAuthorIDs === undefined ? {} : { excludeAuthorIds: input.excludeAuthorIDs }),
-        ...(input.authorType === undefined ? {} : { authorType: input.authorType }),
-        ...(input.excludeAuthorType === undefined ? {} : { excludeAuthorType: input.excludeAuthorType }),
-        ...(input.mentions === undefined ? {} : { mentions: input.mentions }),
-        ...(input.excludeMentions === undefined ? {} : { excludeMentions: input.excludeMentions }),
-        ...(input.mentionEveryone === undefined ? {} : { mentionEveryone: input.mentionEveryone }),
-        ...(input.pinned === undefined ? {} : { pinned: input.pinned }),
-        ...(input.includeNsfw === undefined ? {} : { includeNsfw: input.includeNsfw }),
-        ...(input.has === undefined ? {} : { has: input.has }),
-        ...(input.excludeHas === undefined ? {} : { excludeHas: input.excludeHas }),
-        ...(input.minID === undefined ? {} : { minId: input.minID }),
-        ...(input.maxID === undefined ? {} : { maxId: input.maxID }),
-        ...(input.sortBy === undefined ? {} : { sortBy: input.sortBy }),
-        ...(input.sortOrder === undefined ? {} : { sortOrder: input.sortOrder }),
-        ...(input.page === undefined ? {} : { page: input.page }) });
-      if ('indexing' in result) return { indexing: true, messages: [], total: 0, cursor: null };
-      return { indexing: false, messages: result.messages.map(data => info(new Message(client, data))),
-        total: result.total, cursor: result.cursor ?? null };
+    search,
+    searchAll: search,
+    async bulkFetch(requests, input): Promise<MessageInfo[] | BulkFetchRawChannel[]> {
+      const options = requests.map(request => ({ channelId: request.channelID, limit: request.limit,
+        ...(request.before === undefined ? {} : { before: request.before }),
+        ...(request.after === undefined ? {} : { after: request.after }),
+        ...(request.around === undefined ? {} : { around: request.around }) }));
+      if (input?.hydrate === false) {
+        const raw = await client.bulkFetchMessages(options, { hydrate: false });
+        return raw.channels.map(channel => ({ channelID: channel.channel_id, messages: channel.messages }));
+      }
+      const result = await client.bulkFetchMessages(options);
+      return result.channels.flatMap(channel => [...channel.messages.values()].map(toMessageInfo));
     },
     sendBytes: send,
     sendAttachments: send,

package/src/infrastructure/fluxer/resources/self.ts

@@ -0,0 +1,39 @@
+import type { Client, ClientUser } from '@fluxerjs/core';
+import { YuzuhaError } from '../../../errors.js';
+import type { SelfResources } from '../../../ports/resources/self.js';
+import { toUserInfo } from './users.js';
+
+function selfUser(client: Client): ClientUser {
+  const user = client.user;
+  if (!user) {
+    throw new YuzuhaError('NOT_READY', 'O cliente ainda não está pronto; o usuário autenticado não está disponível.');
+  }
+  return user;
+}
+
+export function createSelfResources(client: Client): SelfResources {
+  return {
+    async fetch() {
+      return toUserInfo(await selfUser(client).fetch());
+    },
+    async guilds(input) {
+      const guilds = await selfUser(client).fetchGuilds({ withCounts: input?.withCounts ?? false });
+      return guilds.map(guild => ({
+        id: guild.id,
+        name: guild.name,
+        icon: guild.icon,
+        owner: guild.owner ?? false,
+        permissions: guild.permissions ?? null,
+        features: guild.features ?? [],
+        memberCount: guild.approximateMemberCount ?? null,
+        onlineCount: guild.approximatePresenceCount ?? null,
+      }));
+    },
+    async leaveGuild(guildID, verification) {
+      await selfUser(client).leaveGuild(guildID, verification);
+    },
+    async deleteMyMessages(guildID, verification) {
+      await selfUser(client).bulkDeleteMyMessagesInGuild(guildID, verification);
+    },
+  };
+}

package/src/infrastructure/fluxer/resources/users.ts

@@ -65,7 +65,7 @@ function snowflakeTimestamp(id: string): number {
   return Number((BigInt(id) >> 22n) + FLUXER_EPOCH);
 }
 
-function toUserInfo(user: User): UserInfo {
+export function toUserInfo(user: User): UserInfo {
   return {
     id: user.id,
     username: user.username,
@@ -77,7 +77,7 @@ function toUserInfo(user: User): UserInfo {
   };
 }
 
-function toMemberInfo(member: GuildMember): MemberInfo {
+export function toMemberInfo(member: GuildMember): MemberInfo {
   const user = member.user;
   return {
     id: member.id,

package/src/infrastructure/fluxer/resources.ts

@@ -1,11 +1,15 @@
 import type { Client } from '@fluxerjs/core';
 import type { Resources } from '../../ports/resources.js';
+import { createCacheResources } from './resources/cache.js';
 import { createChannelsResources } from './resources/channels.js';
 import { createCollectorsResources } from './resources/collectors.js';
 import { createExpressionsResources } from './resources/expressions.js';
+import { createGatewayResources } from './resources/gateway.js';
+import { createInstanceResources } from './resources/instance.js';
 import { createInvitesResources } from './resources/invites.js';
 import { createMessagesResources } from './resources/messages.js';
 import { createRolesResources } from './resources/roles.js';
+import { createSelfResources } from './resources/self.js';
 import { createThreadsResources } from './resources/threads.js';
 import { createUsersResources } from './resources/users.js';
 import { createWebhooksResources } from './resources/webhooks.js';
@@ -21,6 +25,10 @@ export class FluxerResources implements Resources {
   readonly expressions;
   readonly threads;
   readonly invites;
+  readonly gateway;
+  readonly instance;
+  readonly self;
+  readonly cache;
 
   constructor(client: Client) {
     this.users = createUsersResources(client);
@@ -32,5 +40,9 @@ export class FluxerResources implements Resources {
     this.expressions = createExpressionsResources(client);
     this.threads = createThreadsResources(client);
     this.invites = createInvitesResources(client);
+    this.gateway = createGatewayResources(client);
+    this.instance = createInstanceResources(client);
+    this.self = createSelfResources(client);
+    this.cache = createCacheResources(client);
   }
 }

package/src/ports/resources/cache.ts

@@ -0,0 +1,56 @@
+import type { MessageInfo } from './messages.js';
+import type { MemberInfo } from './users.js';
+
+/** Limites resolvidos do cache; `null` indica ilimitado. */
+export interface CacheLimitsInfo {
+  guilds: number | null;
+  channels: number | null;
+  users: number | null;
+  members: number | null;
+  /** `false` quando o cache de mensagens está desabilitado. */
+  messages: number | false | null;
+  roles: number | null;
+  emojis: number | null;
+  stickers: number | null;
+}
+
+/** Tamanhos atuais dos buckets de cache com os limites aplicados. */
+export interface CacheStatsInfo {
+  guilds: number;
+  channels: number;
+  users: number;
+  members: number;
+  messages: number;
+  messageChannels: number;
+  roles: number;
+  emojis: number;
+  stickers: number;
+  limits: CacheLimitsInfo;
+}
+
+/**
+ * Filtro de limpeza do cache de mensagens. Sem `maxAgeMs` nem `keep`,
+ * todas as mensagens do escopo são removidas. `keep` retorna verdadeiro
+ * para manter a mensagem no cache.
+ */
+export interface MessageSweepInput {
+  channelID?: string;
+  maxAgeMs?: number;
+  keep?: (message: MessageInfo, channelID: string) => boolean;
+}
+
+/**
+ * Filtro de limpeza do cache de membros. Sem `keep`, todos os membros
+ * do escopo são removidos. `keep` retorna verdadeiro para manter o membro.
+ */
+export interface MemberSweepInput {
+  guildID?: string;
+  keep?: (member: MemberInfo, guildID: string) => boolean;
+}
+
+/** Inspeção e limpeza dos caches locais do client. */
+export interface CacheResources {
+  stats(): Promise<CacheStatsInfo>;
+  sweepMessages(input?: MessageSweepInput): Promise<number>;
+  sweepMembers(input?: MemberSweepInput): Promise<number>;
+}

package/src/ports/resources/collectors.ts

@@ -5,6 +5,23 @@ export interface AwaitMessageInput {
   signal?: AbortSignal;
 }
 
+export interface CollectMessagesInput {
+  userID?: string;
+  contains?: string;
+  timeMs?: number;
+  max?: number;
+  signal?: AbortSignal;
+}
+
+export interface CollectReactionsInput {
+  messageID: string;
+  emojis?: string | string[];
+  userID?: string;
+  timeMs?: number;
+  max?: number;
+  signal?: AbortSignal;
+}
+
 export interface CollectedMessageInfo {
   id: string;
   channelID: string;
@@ -15,10 +32,13 @@ export interface CollectedMessageInfo {
 export interface ReactionVote {
   userID: string;
   emoji: string;
+  messageID?: string;
 }
 
 export interface CollectorsResources {
   awaitMessage(channelID: string, input: AwaitMessageInput): Promise<CollectedMessageInfo | null>;
   awaitReaction(channelID: string, messageID: string, emojis: string | string[],
     timeMs: number, userID?: string, signal?: AbortSignal): Promise<ReactionVote | null>;
+  collectMessages(channelID: string, input: CollectMessagesInput): AsyncIterable<CollectedMessageInfo>;
+  collectReactions(channelID: string, input: CollectReactionsInput): AsyncIterable<ReactionVote>;
 }

package/src/ports/resources/gateway.ts

@@ -0,0 +1,49 @@
+import type { GatewaySendPayload } from '@fluxerjs/types';
+
+/** Pedido de membros de servidor pelo gateway (opcode 8). */
+export interface GatewayMembersRequest {
+  guildID?: string;
+  guildIDs?: string[];
+  query?: string;
+  limit?: number;
+  userIDs?: string[];
+  presences?: boolean;
+  nonce?: string;
+}
+
+/** Pedido de contagens de membros por canal dentro de um servidor (opcode 16). */
+export interface ChannelCountsRequest {
+  guildID: string;
+  channelID?: string;
+  channelIDs?: string[];
+  nonce?: string;
+}
+
+/** Pedido de não lidos de posts em um canal de fórum ou mídia (opcode 28). */
+export interface ForumUnreadsRequest {
+  guildID: string;
+  channelID: string;
+  threads: { threadID: string; ackMessageID?: string }[];
+}
+
+/** Assinatura de tráfego de threads em um servidor (opcode 14). */
+export interface ThreadSubscriptionInput {
+  guildID: string;
+  threads?: boolean;
+  threadIDs?: string[];
+}
+
+/**
+ * Pedidos brutos ao gateway. São fire-and-forget: os resultados chegam por
+ * eventos do client (ex.: `guildCountsUpdate`, `channelMemberCountsUpdate`,
+ * `forumUnreads`, `threadMemberListUpdate`). Para aguardar a resposta use
+ * `users.guildCounts` e `users.channelCounts`, que encapsulam pedido e espera.
+ */
+export interface GatewayResources {
+  requestMembers(input: GatewayMembersRequest): void;
+  requestGuildCounts(guildIDs: string[], nonce?: string): void;
+  requestChannelCounts(input: ChannelCountsRequest): void;
+  requestForumUnreads(input: ForumUnreadsRequest): void;
+  subscribeThreads(input: ThreadSubscriptionInput): void;
+  send(shardID: number, payload: GatewaySendPayload): void;
+}

package/src/ports/resources/instance.ts

@@ -0,0 +1,109 @@
+/** URLs de endpoint resolvidas da instância Fluxer. */
+export interface InstanceEndpointsInfo {
+  api: string;
+  apiClient: string;
+  apiPublic: string;
+  gateway: string;
+  media: string;
+  staticCDN: string;
+  marketing: string;
+  admin: string;
+  invite: string;
+  gift: string;
+  webapp: string;
+}
+
+/** Flags de recursos do documento de descoberta da instância. */
+export interface InstanceFeaturesInfo {
+  voiceEnabled: boolean;
+  stripeEnabled: boolean;
+  selfHosted: boolean;
+  presignedAttachmentUploads: boolean;
+  emailsEnabled: boolean;
+}
+
+/** Integrações opcionais de terceiros habilitadas na instância. */
+export interface InstanceServicesInfo {
+  gif: boolean;
+  youtube: boolean;
+  bluesky: boolean;
+}
+
+/** Descrição normalizada da instância: endpoints resolvidos e descoberta. */
+export interface InstanceInfo {
+  apiCodeVersion: number | null;
+  codename: string | null;
+  endpoints: InstanceEndpointsInfo;
+  features: InstanceFeaturesInfo | null;
+  registrationMode: 'open' | 'approval' | 'closed' | null;
+  ssoEnabled: boolean | null;
+  ssoEnforced: boolean | null;
+  singleCommunity: boolean | null;
+  singleCommunityGuildID: string | null;
+  directMessagesDisabled: boolean | null;
+  services: InstanceServicesInfo | null;
+}
+
+/** Informações de conexão do gateway (`GET /gateway/bot`). */
+export interface GatewayInfo {
+  url: string;
+  shards: number;
+  sessionStartLimit: {
+    total: number;
+    remaining: number;
+    resetAfter: number;
+    maxConcurrency: number;
+  } | null;
+}
+
+/** Aplicação normalizada de `applications/@me` e `oauth2/applications/@me`. */
+export interface ApplicationInfo {
+  id: string;
+  name: string;
+  icon: string | null;
+  description: string | null;
+  botPublic: boolean | null;
+  botRequireCodeGrant: boolean | null;
+  verifyKey: string | null;
+  flags: number | null;
+  ownerID: string | null;
+  botID: string | null;
+  redirectURIs: string[];
+  clientSecret: string | null;
+}
+
+/** Metadados de emoji (`GET /emojis/{id}/metadata`). */
+export interface EmojiMetadataInfo {
+  id: string;
+  guildID: string;
+  name: string;
+  animated: boolean;
+  allowCloning: boolean;
+}
+
+/** Metadados de sticker (`GET /stickers/{id}/metadata`). */
+export interface StickerMetadataInfo {
+  id: string;
+  guildID: string;
+  name: string;
+  animated: boolean;
+  allowCloning: boolean;
+}
+
+/** Referência de emoji aceita por `resolveEmoji` além do texto. */
+export interface EmojiReference {
+  name: string;
+  id?: string;
+  animated?: boolean;
+}
+
+/** Introspecção da instância, do gateway e da aplicação do client. */
+export interface InstanceResources {
+  describe(): Promise<InstanceInfo>;
+  gatewayInfo(): Promise<GatewayInfo>;
+  application(): Promise<ApplicationInfo>;
+  oauthApplications(): Promise<ApplicationInfo[]>;
+  emojiMetadata(emojiID: string): Promise<EmojiMetadataInfo>;
+  stickerMetadata(stickerID: string): Promise<StickerMetadataInfo>;
+  resolveEmoji(emoji: string | EmojiReference, guildID?: string): Promise<string>;
+}

package/src/ports/resources/messages.ts

@@ -1,4 +1,5 @@
 import type { AttachmentSpec, BinaryAttachmentSpec } from './common.js';
+import type { APIMessage } from '@fluxerjs/types';
 import type { MessageSearchInput, PinnedMessagesInput } from '../../domain/message-query.js';
 import type { ReceivedEmbed } from '../../domain/messages.js';
 export type { MessageSearchInput, PinnedMessagesInput } from '../../domain/message-query.js';
@@ -40,6 +41,8 @@ export interface MessagesResources {
   dm(userID: string, content: string): Promise<string>;
   forward(channelID: string, sourceChannelID: string, messageID: string): Promise<string>;
   search(input: MessageSearchInput): Promise<MessageSearchPage>;
+  searchAll(input: MessageSearchInput): Promise<MessageSearchPage>;
+  bulkFetch(requests: BulkFetchRequest[], input?: BulkFetchInput): Promise<MessageInfo[] | BulkFetchRawChannel[]>;
   sendBytes(channelID: string, files: BinaryAttachmentSpec[], content?: string): Promise<string>;
   sendAttachments(channelID: string, files: (AttachmentSpec | BinaryAttachmentSpec)[], content?: string): Promise<string>;
 }
@@ -62,3 +65,23 @@ export interface MessageSearchPage {
   total: number;
   cursor: string[] | null;
 }
+
+/** Janela de mensagens de um canal dentro de um `bulkFetch`. */
+export interface BulkFetchRequest {
+  channelID: string;
+  limit: number;
+  before?: string;
+  after?: string;
+  around?: string;
+}
+
+export interface BulkFetchInput {
+  /** `false` retorna o payload bruto da API; o padrão hidrata e normaliza. */
+  hydrate?: boolean;
+}
+
+/** Canal do retorno bruto de `bulkFetch` quando `hydrate` é `false`. */
+export interface BulkFetchRawChannel {
+  channelID: string;
+  messages: APIMessage[];
+}

package/src/ports/resources/self.ts

@@ -0,0 +1,30 @@
+import type { UserInfo } from './users.js';
+
+/** Credenciais para verificação sudo (ações elevadas): senha e/ou MFA. */
+export interface SudoVerification {
+  password?: string;
+  mfaMethod?: 'totp' | 'webauthn';
+  mfaCode?: string;
+  webauthnResponse?: Record<string, unknown>;
+  webauthnChallenge?: string;
+}
+
+/** Servidor parcial retornado por `GET /users/@me/guilds`. */
+export interface SelfGuildInfo {
+  id: string;
+  name: string;
+  icon: string | null;
+  owner: boolean;
+  permissions: string | null;
+  features: string[];
+  memberCount: number | null;
+  onlineCount: number | null;
+}
+
+/** Operações sobre o usuário autenticado (`client.user`). */
+export interface SelfResources {
+  fetch(): Promise<UserInfo>;
+  guilds(input?: { withCounts?: boolean }): Promise<SelfGuildInfo[]>;
+  leaveGuild(guildID: string, verification?: SudoVerification): Promise<void>;
+  deleteMyMessages(guildID: string, verification?: SudoVerification): Promise<void>;
+}