@zhin.js/adapter-discord 1.1.20 → 1.1.21

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @zhin.js/adapter-discord
 
+## 1.1.21
+
+### Patch Changes
+
+- b88e988: Preserve account-profile write acknowledgements already observed before cancellation, distinguish native Discord REST rejection from unknown outcomes, and retain the last valid profile when a newer concurrent read fails. Keep scene-scoped SOUL presence consistent with the actual prompt and allow discovered URLs to pass through the existing network authorization policy.
+- af8f803: Use the current Endpoint's platform profile for Agent account identity, with per-field configured fallbacks and scoped, identity-approved profile tools. Keep SOUL first-person and independent of account names. Profile ports preserve the source Client, cancellation, truthful update outcomes and private image authority.
+
+  Adapter Feature API 2.1 and Tool Feature API 1.1 describe the additive profile requirements; new Core, official adapters and generated plugins declare the corresponding floors. Existing compatible API-2.0/API-1.0 plugins remain accepted by the newer providers. npm releases remain patch.
+
+  Private IM assets now bind to the full canonical conversation and principal. Existing IM asset records that contain only the earlier lossy hash remain on disk until their original expiry, but cannot be safely rebound; recapture them. No automatic file deletion, platform profile mutation or workspace SOUL rewrite occurs during upgrade.
+
+- Updated dependencies [b88e988]
+- Updated dependencies [f78eb84]
+- Updated dependencies [c15cef9]
+- Updated dependencies [b0c02a2]
+- Updated dependencies [af8f803]
+- Updated dependencies [26fda97]
+- Updated dependencies [976886c]
+- Updated dependencies [032dc96]
+  - @zhin.js/adapter@1.1.27
+  - @zhin.js/client@1.1.23
+  - @zhin.js/im-contract@1.1.10
+  - @zhin.js/core@1.1.55
+  - @zhin.js/tool@1.1.14
+  - @zhin.js/page@1.1.13
+  - @zhin.js/host-http@1.1.13
+  - @zhin.js/agent-feature@1.1.12
+  - @zhin.js/feature-kit@1.1.11
+  - @zhin.js/permission@1.1.11
+  - @zhin.js/skill@1.1.12
+
 ## 1.1.20
 
 ### Patch Changes

package/README.md

@@ -9,7 +9,7 @@ Zhin.js Discord 适配器（Plugin Runtime），默认通过 **Gateway WebSocket
 - 支持私聊、群组与服务器频道
 - 出站 `send({ conversation, payload })` → Discord channel message（Markdown content / media / embed / keyboard）
 - 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
-- Interactions HTTP webhook 延期（需 `httpHostToken`）；配置 `connection: interactions` 会明确报错
+- Interactions HTTP webhook（需 `httpHostToken`），支持验签、PING 与 slash command
 
 ## 安装
 
@@ -41,7 +41,7 @@ pnpm add @zhin.js/adapter-discord discord.js
 | **Bot Token** | [Discord Developer Portal](https://discord.com/developers/applications) 创建应用并获取 Token |
 | **MESSAGE CONTENT INTENT** | 需开启才能读取消息正文 |
 | **Gateway（默认）** | 本地/生产均可；discord.js 连接 Gateway，无需公网 HTTPS |
-| **host-http** | Gateway **不需要**；Interactions webhook 延期至下一棒 |
+| **host-http** | Gateway **不需要**；Interactions webhook 需要 |
 
 必填字段（`endpoints[i]`）：`id`、`token`。
 
@@ -111,7 +111,7 @@ Discord 的 token / publicKey 更新通过只读 GET `/applications/@me` 核验
 | Gateway 反复断线 | 检查 Token、网络代理、Gateway Intents 与应用后台配置 |
 | 能上线但收不到正文 | 启用 Message Content Intent，并给 Bot 频道读取权限 |
 | 能收不能发 | 检查 Send Messages、Embed Links 与附件权限 |
-| `connection: interactions` 启动失败 | 当前生产路径使用 Gateway；改回 `gateway` |
+| `connection: interactions` 启动失败 | 检查 HTTP Host、`applicationId`、`publicKey` 与交互回调地址 |
 
 ## 许可证
 
@@ -143,3 +143,11 @@ DISCORD_REST_API_PROXY_PORT=18570 pnpm --filter platform-acceptance-bot dev:disc
 forwarding 下以新sample确认真实消息基线；control `POST /cut` 后另发新sample，出站结果须失败/unknown且无自动POST重发；`POST /recover` 后先确认旧sample未补发，再新sample确认恢复。检查平台可见消息与报告回执，不重发未知sample。此模式仅Gateway REST、JSON消息能力；Interactions Endpoint 与其他CDN目的地不适用，配置Interactions会明确拒绝。本地真实SDK TLS fixture覆盖服务收到POST后切断、可信CA但SAN不匹配拒绝、默认直连与手动恢复，不能当成实机结果。停止/连接失败会销毁专用Dispatcher，并取消尚未完成TLS握手。
 
 公开扩展点参考：[Discord RESTOptions.agent](https://discord.js.org/docs/packages/rest/main/RESTOptions:Interface)、[Undici 6.28 Agent](https://github.com/nodejs/undici/blob/v6.28.0/docs/docs/api/Agent.md)。
+
+## 当前账号资料
+
+Gateway 和 Interactions 模式均通过资料端口暴露当前认证账号的用户名（`nickname`）及头像。Gateway 使用原生 `ClientUser`；Interactions 使用 `GET/PATCH /users/@me`。修改沿用 Agent 身份类审批及当前账号生命周期，与服务器内的成员昵称分开处理。
+
+支持修改昵称和头像；其他资料字段没有对应适配器操作时不声明可写。平台响应提供有效头像资料时返回其 CDN URL；若仅确认修改成功，则不返回未确认的资料。图片字节只在请求内部使用，不返回模型；Agent 解析图片沿用现有本地图片和网络权限。
+
+`nickname` / `profile` 配置仅补足平台缺失字段，Endpoint 配置优先于适配器默认值。接口依据 [discord.js ClientUser](https://discord.js.org/docs/packages/discord.js/main/ClientUser:Class)。

package/lib/endpoint.js

@@ -1,3 +1,5 @@
+import { createDiscordSelfProfile, createDiscordRestSelfProfile } from './self-profile.js';
+import { DiscordRestRequestError } from './rest-request-error.js';
 /**
  * DiscordEndpoint — lifecycle, outbound, admit, gateway / interactions modes, agent tool surface.
  */
@@ -40,7 +42,7 @@ export class DiscordGatewayEndpoint extends Client {
             start: signal => this.#startFramework(signal), open: () => this.#openFramework(), close: () => this.#closeFramework(),
             stop: () => this.#stopFramework(), send: request => this.#sendFramework(request),
             get name() { return options.config.id; }, get transportState() { return endpoint.#transportState; },
-            management: this.#management, control: this.#control, content: this.#content,
+            management: this.#management, control: this.#control, content: this.#content, profile: createDiscordSelfProfile(this),
         });
     }
     get #transportState() {
@@ -93,6 +95,8 @@ export class DiscordGatewayEndpoint extends Client {
                 }, AbortSignal.any([abort.signal, executionSignal]));
                 if (abort.signal.aborted || this.#connection !== abort)
                     return;
+                if (this.user?.id)
+                    this[endpointSpec].reportSelfUserId(this.user.id);
                 this.#logger.info(formatCompact({
                     op: 'connect',
                     endpoint: this.#options.config.id,
@@ -290,16 +294,26 @@ export class DiscordRestClient {
         const operationSignal = signal ? AbortSignal.any([signal, deadline]) : deadline;
         const operation = createEndpointOperation({ signal: operationSignal });
         const execute = async () => {
-            const response = await this.fetch(`${DISCORD_API}${path}`, {
-                method,
-                headers: { Authorization: `Bot ${this.token}`, ...(body === undefined ? {} : { 'Content-Type': 'application/json' }) },
-                ...(body === undefined ? {} : { body: JSON.stringify(body) }),
-                signal: operationSignal,
-            });
-            const text = await response.text();
-            if (!response.ok)
-                throw new Error(`Discord API ${method} ${path} failed (${response.status}): ${text.slice(0, 200)}`);
-            return (text ? JSON.parse(text) : undefined);
+            const encodedBody = body === undefined ? undefined : JSON.stringify(body);
+            let response;
+            let text;
+            try {
+                response = await this.fetch(`${DISCORD_API}${path}`, {
+                    method,
+                    headers: { Authorization: `Bot ${this.token}`, ...(body === undefined ? {} : { 'Content-Type': 'application/json' }) },
+                    ...(encodedBody === undefined ? {} : { body: encodedBody }),
+                    signal: operationSignal,
+                });
+                text = await response.text();
+                if (!response.ok)
+                    throw new DiscordRestRequestError({ status: response.status, body: text });
+                return (text ? JSON.parse(text) : undefined);
+            }
+            catch (cause) {
+                if (cause instanceof DiscordRestRequestError)
+                    throw cause;
+                throw new DiscordRestRequestError({ status: response?.status, body: text, cause });
+            }
         };
         return operation.run(execute);
     }
@@ -333,6 +347,7 @@ export class DiscordInteractionsEndpoint extends DiscordRestClient {
             start: () => this.#startFramework(), open: () => this.#openFramework(), close: () => this.#closeFramework(),
             stop: () => this.#stopFramework(), send: request => this.#sendFramework(request), name: options.config.id,
             control: this.#control, content: this.#content,
+            profile: createDiscordRestSelfProfile(this, id => this[endpointSpec].reportSelfUserId(id)),
         });
     }
     get isOpen() {

package/lib/protocol.d.ts

@@ -1,3 +1,4 @@
+import type { EndpointProfileConfiguration } from 'zhin.js/adapter';
 import { type ConversationRef } from '@zhin.js/im-contract';
 import type { Segment } from '@zhin.js/core/runtime';
 export interface DiscordActivity {
@@ -6,7 +7,7 @@ export interface DiscordActivity {
     readonly url?: string;
 }
 /** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
-export interface DiscordEndpointConfig {
+export interface DiscordEndpointConfig extends EndpointProfileConfiguration {
     readonly id: string;
     readonly token: string;
     /** Default `gateway`. `interactions` uses httpHostToken POST + Ed25519 verify. */

package/lib/rest-request-error.d.ts

@@ -0,0 +1,13 @@
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+/** Discord response evidence; request URLs, authorization headers and submitted bodies are excluded. */
+export declare class DiscordRestRequestError extends EndpointDeliveryError {
+    readonly status?: number;
+    readonly body?: string;
+    constructor({ status, body, cause }: Readonly<{
+        status?: number;
+        body?: string;
+        cause?: unknown;
+    }>);
+    /** HTTP success survives an unreadable response body; it does not prove any profile field. */
+    get acknowledged(): boolean;
+}

package/lib/rest-request-error.js

@@ -0,0 +1,39 @@
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+/** Discord response evidence; request URLs, authorization headers and submitted bodies are excluded. */
+export class DiscordRestRequestError extends EndpointDeliveryError {
+    status;
+    body;
+    constructor({ status, body, cause }) {
+        const rejection = nativeRejection(status, body);
+        const rejected = rejection !== undefined;
+        super(rejected ? 'platform_rejected' : 'delivery_unconfirmed', status === undefined ? 'Discord REST request failed before a response was available'
+            : `Discord REST request ${rejected ? 'rejected' : 'unconfirmed'} (${status})${rejected ? `: ${rejection}` : ''}`, rejected ? 'rejected' : 'unknown', { cause });
+        this.name = 'DiscordRestRequestError';
+        this.status = status;
+        this.body = body;
+    }
+    /** HTTP success survives an unreadable response body; it does not prove any profile field. */
+    get acknowledged() { return this.status !== undefined && this.status >= 200 && this.status < 300; }
+}
+/** Official rejection statuses plus a native JSON error, never a proxy timeout/body alone.
+ * @see https://docs.discord.com/developers/topics/opcodes-and-status-codes#http
+ * @see https://docs.discord.com/developers/topics/rate-limits#rate-limit-response-structure
+ */
+function nativeRejection(status, body) {
+    if (status === undefined || ![400, 401, 403, 404, 405, 429].includes(status) || !body)
+        return undefined;
+    try {
+        const value = JSON.parse(body);
+        if (typeof value?.message !== 'string')
+            return undefined;
+        if (typeof value.code === 'number' && Number.isSafeInteger(value.code))
+            return `code ${value.code}`;
+        if (status === 429 && typeof value.retry_after === 'number' && Number.isFinite(value.retry_after)
+            && value.retry_after >= 0 && typeof value.global === 'boolean')
+            return 'rate limited';
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/lib/self-profile.d.ts

@@ -0,0 +1,11 @@
+import { type EndpointProfile } from 'zhin.js/adapter';
+import type { Client } from 'discord.js';
+import type { DiscordRestRequest } from './endpoint.js';
+/** The Gateway's native ClientUser owns its current username/avatar and updates its own cache. */
+export declare function createDiscordSelfProfile(client: Pick<Client, 'user' | 'users'>): EndpointProfile;
+interface DiscordProfileRestClient {
+    request<T>(request: DiscordRestRequest): Promise<T>;
+}
+/** Interactions-only accounts use the same public identity fields through authenticated REST. */
+export declare function createDiscordRestSelfProfile(client: DiscordProfileRestClient, reportAccount: (id: string) => void): EndpointProfile;
+export {};

package/lib/self-profile.js

@@ -0,0 +1,82 @@
+import { createEndpointOperation } from 'zhin.js/adapter';
+import { DiscordRestRequestError } from './rest-request-error.js';
+function profileOf(user) {
+    return { nickname: user.username, avatar: user.avatarURL() };
+}
+/** The Gateway's native ClientUser owns its current username/avatar and updates its own cache. */
+export function createDiscordSelfProfile(client) {
+    const user = () => {
+        if (!client.user)
+            throw new Error('Discord self account is unavailable');
+        return client.user;
+    };
+    return Object.freeze({
+        writableFields: Object.freeze(['nickname', 'avatar']),
+        get current() { return client.user ? profileOf(client.user) : {}; },
+        async read({ signal }) {
+            return profileOf(await createEndpointOperation({ signal }).prepare(() => client.users.fetch(user().id, { force: true, cache: false })));
+        },
+        async write({ change, signal }) {
+            const operation = createEndpointOperation({ signal });
+            if (change.field === 'nickname') {
+                const updated = await operation.run(() => user().setUsername(change.value));
+                return { status: 'updated', profile: profileOf(updated) };
+            }
+            if (change.field === 'avatar') {
+                if (change.value.kind === 'file') {
+                    return { status: 'rejected', message: 'Discord avatar requires resolved image bytes, URL or local path' };
+                }
+                const image = change.value.kind === 'base64' ? Buffer.from(change.value.value, 'base64') : change.value.value;
+                const updated = await operation.run(() => user().setAvatar(image));
+                return { status: 'updated', profile: profileOf(updated) };
+            }
+            return { status: 'rejected', message: `Discord does not expose ${change.field} through this port` };
+        },
+    });
+}
+/** Interactions-only accounts use the same public identity fields through authenticated REST. */
+export function createDiscordRestSelfProfile(client, reportAccount) {
+    const observed = (user) => {
+        if (!user?.id || typeof user.username !== 'string' || (user.avatar !== null && typeof user.avatar !== 'string')) {
+            return undefined;
+        }
+        reportAccount(user.id);
+        return { nickname: user.username, avatar: user.avatar === null ? null
+                : `https://cdn.discordapp.com/avatars/${user.id}/${user.avatar}.${user.avatar.startsWith('a_') ? 'gif' : 'png'}` };
+    };
+    return Object.freeze({
+        writableFields: Object.freeze(['nickname', 'avatar']),
+        async read({ signal }) {
+            const profile = observed(await client.request({ method: 'GET', path: '/users/@me', signal }));
+            if (!profile)
+                throw new Error('Discord returned an incomplete self profile');
+            return profile;
+        },
+        async write({ change, signal }) {
+            let body;
+            if (change.field === 'nickname')
+                body = { username: change.value };
+            else if (change.field === 'avatar') {
+                if (change.value.kind !== 'base64' || !change.value.mime_type) {
+                    return { status: 'rejected', message: 'Discord REST avatar requires resolved image bytes and MIME type' };
+                }
+                body = { avatar: `data:${change.value.mime_type};base64,${change.value.value}` };
+            }
+            else
+                return { status: 'rejected', message: `Discord does not expose ${change.field} through this port` };
+            let updated;
+            try {
+                updated = await client.request({ method: 'PATCH', path: '/users/@me', body, signal });
+            }
+            catch (error) {
+                if (!(error instanceof DiscordRestRequestError))
+                    throw error;
+                if (error.acknowledged)
+                    return { status: 'updated' };
+                return { status: error.disposition === 'rejected' ? 'rejected' : 'unknown', message: error.message };
+            }
+            const profile = observed(updated);
+            return { status: 'updated', ...(profile ? { profile } : {}) };
+        },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-discord",
-  "version": "1.1.20",
+  "version": "1.1.21",
   "description": "Zhin.js Discord adapter for Plugin Runtime (Gateway WebSocket)",
   "type": "module",
   "main": "./lib/index.js",
@@ -35,26 +35,26 @@
     "@discordjs/ws": "1.2.3",
     "discord.js": "^14.27.0",
     "undici": "6.29.1",
-    "@zhin.js/adapter": "1.1.26",
-    "@zhin.js/agent-feature": "1.1.11",
-    "@zhin.js/client": "1.1.22",
+    "@zhin.js/adapter": "1.1.27",
+    "@zhin.js/agent-feature": "1.1.12",
+    "@zhin.js/client": "1.1.23",
     "@zhin.js/console-contract": "1.1.3",
-    "@zhin.js/core": "1.1.54",
-    "@zhin.js/feature-kit": "1.1.10",
-    "@zhin.js/host-http": "1.1.12",
-    "@zhin.js/im-contract": "1.1.9",
+    "@zhin.js/core": "1.1.55",
+    "@zhin.js/feature-kit": "1.1.11",
+    "@zhin.js/host-http": "1.1.13",
+    "@zhin.js/im-contract": "1.1.10",
     "@zhin.js/logger": "1.1.2",
-    "@zhin.js/page": "1.1.12",
-    "@zhin.js/permission": "1.1.10",
-    "@zhin.js/skill": "1.1.11",
-    "@zhin.js/tool": "1.1.13"
+    "@zhin.js/page": "1.1.13",
+    "@zhin.js/permission": "1.1.11",
+    "@zhin.js/skill": "1.1.12",
+    "@zhin.js/tool": "1.1.14"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.26",
-    "@zhin.js/command": "^1.1.12",
-    "@zhin.js/core": "^1.1.54",
-    "zhin.js": "^1.1.19"
+    "@zhin.js/adapter": "^1.1.27",
+    "@zhin.js/command": "^1.1.13",
+    "@zhin.js/core": "^1.1.55",
+    "zhin.js": "^1.1.20"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
@@ -72,8 +72,8 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/host-http": "1.1.12",
-    "zhin.js": "1.1.19"
+    "@zhin.js/host-http": "1.1.13",
+    "zhin.js": "1.1.20"
   },
   "files": [
     "adapters",
@@ -104,7 +104,7 @@
     "features": [
       {
         "package": "@zhin.js/adapter",
-        "api": "^2.0.0"
+        "api": "^2.1.0"
       },
       {
         "package": "@zhin.js/command",
@@ -112,7 +112,7 @@
       },
       {
         "package": "@zhin.js/tool",
-        "api": "^1.0.0"
+        "api": "^1.1.0"
       },
       {
         "package": "@zhin.js/skill",

package/schema.json

@@ -230,6 +230,27 @@
                 "description": "REST-only fault proxy for Gateway tests: pin discord.com:443 TCP to loopback while preserving SNI and certificate validation, independently of the Gateway proxy."
               }
             }
+          },
+          "nickname": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "账号昵称兜底",
+            "x-i18n": {
+              "en": {
+                "description": "Fallback account nickname"
+              }
+            }
+          },
+          "profile": {
+            "$ref": "#/$defs/selfProfileFallback",
+            "description": "账号资料兜底",
+            "x-i18n": {
+              "en": {
+                "description": "Fallback account profile"
+              }
+            }
           }
         },
         "required": [
@@ -257,9 +278,93 @@
       "type": "string",
       "pattern": "^(?:ws://127\\.0\\.0\\.1:[0-9]+/?|\\$\\{[A-Za-z_][A-Za-z0-9_]*\\})$",
       "description": "Isolated acceptance only: loopback Gateway fault proxy; REST unchanged."
+    },
+    "nickname": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "账号昵称兜底",
+      "x-i18n": {
+        "en": {
+          "description": "Fallback account nickname"
+        }
+      }
+    },
+    "profile": {
+      "$ref": "#/$defs/selfProfileFallback",
+      "description": "账号资料兜底",
+      "x-i18n": {
+        "en": {
+          "description": "Fallback account profile"
+        }
+      }
     }
   },
   "required": [
     "endpoints"
-  ]
+  ],
+  "$defs": {
+    "selfProfileFallback": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "gender": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "enum": [
+            "male",
+            "female",
+            "other",
+            "unknown",
+            null
+          ]
+        },
+        "age": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 0
+        },
+        "birthday": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$"
+        },
+        "signature": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "avatar": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^(https?://[^\\s/?#]+(?:[/?#].*)?|)$"
+        },
+        "interests": {
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "type": "string"
+          }
+        },
+        "bio": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    }
+  }
 }

package/src/endpoint.ts

@@ -1,4 +1,6 @@
 import { createDiscordRestApiAgent } from './rest-api-proxy.js';
+import { createDiscordSelfProfile, createDiscordRestSelfProfile } from './self-profile.js';
+import { DiscordRestRequestError } from './rest-request-error.js';
 /**
  * DiscordEndpoint — lifecycle, outbound, admit, gateway / interactions modes, agent tool surface.
  */
@@ -104,7 +106,7 @@ export class DiscordGatewayEndpoint extends Client implements Endpoint {
       start: signal => this.#startFramework(signal), open: () => this.#openFramework(), close: () => this.#closeFramework(),
       stop: () => this.#stopFramework(), send: request => this.#sendFramework(request),
       get name() { return options.config.id; }, get transportState() { return endpoint.#transportState; },
-      management: this.#management, control: this.#control, content: this.#content,
+      management: this.#management, control: this.#control, content: this.#content, profile: createDiscordSelfProfile(this),
     });
   }
 
@@ -160,6 +162,7 @@ export class DiscordGatewayEndpoint extends Client implements Endpoint {
         },
       }, AbortSignal.any([abort.signal, executionSignal]));
       if (abort.signal.aborted || this.#connection !== abort) return;
+      if (this.user?.id) this[endpointSpec].reportSelfUserId(this.user.id);
       this.#logger.info(formatCompact({
         op: 'connect',
         endpoint: this.#options.config.id,
@@ -373,15 +376,23 @@ export class DiscordRestClient {
     const operationSignal = signal ? AbortSignal.any([signal, deadline]) : deadline;
     const operation = createEndpointOperation({ signal: operationSignal });
     const execute = async () => {
-      const response = await this.fetch(`${DISCORD_API}${path}`, {
-        method,
-        headers: { Authorization: `Bot ${this.token}`, ...(body === undefined ? {} : { 'Content-Type': 'application/json' }) },
-        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
-        signal: operationSignal,
-      });
-      const text = await response.text();
-      if (!response.ok) throw new Error(`Discord API ${method} ${path} failed (${response.status}): ${text.slice(0, 200)}`);
-      return (text ? JSON.parse(text) : undefined) as T;
+      const encodedBody = body === undefined ? undefined : JSON.stringify(body);
+      let response: Response | undefined;
+      let text: string | undefined;
+      try {
+        response = await this.fetch(`${DISCORD_API}${path}`, {
+          method,
+          headers: { Authorization: `Bot ${this.token}`, ...(body === undefined ? {} : { 'Content-Type': 'application/json' }) },
+          ...(encodedBody === undefined ? {} : { body: encodedBody }),
+          signal: operationSignal,
+        });
+        text = await response.text();
+        if (!response.ok) throw new DiscordRestRequestError({ status: response.status, body: text });
+        return (text ? JSON.parse(text) : undefined) as T;
+      } catch (cause) {
+        if (cause instanceof DiscordRestRequestError) throw cause;
+        throw new DiscordRestRequestError({ status: response?.status, body: text, cause });
+      }
     };
     return operation.run(execute);
   }
@@ -419,6 +430,7 @@ export class DiscordInteractionsEndpoint extends DiscordRestClient implements En
       start: () => this.#startFramework(), open: () => this.#openFramework(), close: () => this.#closeFramework(),
       stop: () => this.#stopFramework(), send: request => this.#sendFramework(request), name: options.config.id,
       control: this.#control, content: this.#content,
+      profile: createDiscordRestSelfProfile(this, id => this[endpointSpec].reportSelfUserId(id)),
     });
   }
 

package/src/protocol.ts

@@ -1,3 +1,4 @@
+import type { EndpointProfileConfiguration } from 'zhin.js/adapter';
 import { validateDiscordGatewayFaultProxy } from './gateway-fault-proxy.js';
 /** Discord Gateway protocol helpers. Canonicalization is owned by Core. */
 
@@ -15,7 +16,7 @@ export interface DiscordActivity {
 }
 
 /** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
-export interface DiscordEndpointConfig {
+export interface DiscordEndpointConfig extends EndpointProfileConfiguration {
   readonly id: string;
   readonly token: string;
   /** Default `gateway`. `interactions` uses httpHostToken POST + Ed25519 verify. */

package/src/rest-request-error.ts

@@ -0,0 +1,38 @@
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+
+/** Discord response evidence; request URLs, authorization headers and submitted bodies are excluded. */
+export class DiscordRestRequestError extends EndpointDeliveryError {
+  readonly status?: number;
+  readonly body?: string;
+
+  constructor({ status, body, cause }: Readonly<{ status?: number; body?: string; cause?: unknown }>) {
+    const rejection = nativeRejection(status, body);
+    const rejected = rejection !== undefined;
+    super(rejected ? 'platform_rejected' : 'delivery_unconfirmed',
+      status === undefined ? 'Discord REST request failed before a response was available'
+        : `Discord REST request ${rejected ? 'rejected' : 'unconfirmed'} (${status})${rejected ? `: ${rejection}` : ''}`,
+      rejected ? 'rejected' : 'unknown', { cause });
+    this.name = 'DiscordRestRequestError';
+    this.status = status;
+    this.body = body;
+  }
+
+  /** HTTP success survives an unreadable response body; it does not prove any profile field. */
+  get acknowledged(): boolean { return this.status !== undefined && this.status >= 200 && this.status < 300; }
+}
+
+/** Official rejection statuses plus a native JSON error, never a proxy timeout/body alone.
+ * @see https://docs.discord.com/developers/topics/opcodes-and-status-codes#http
+ * @see https://docs.discord.com/developers/topics/rate-limits#rate-limit-response-structure
+ */
+function nativeRejection(status: number | undefined, body: string | undefined): string | undefined {
+  if (status === undefined || ![400, 401, 403, 404, 405, 429].includes(status) || !body) return undefined;
+  try {
+    const value = JSON.parse(body) as { code?: unknown; message?: unknown; retry_after?: unknown; global?: unknown } | null;
+    if (typeof value?.message !== 'string') return undefined;
+    if (typeof value.code === 'number' && Number.isSafeInteger(value.code)) return `code ${value.code}`;
+    if (status === 429 && typeof value.retry_after === 'number' && Number.isFinite(value.retry_after)
+      && value.retry_after >= 0 && typeof value.global === 'boolean') return 'rate limited';
+    return undefined;
+  } catch { return undefined; }
+}

package/src/self-profile.ts

@@ -0,0 +1,83 @@
+import { createEndpointOperation, type EndpointProfile } from 'zhin.js/adapter';
+import type { Client, ClientUser, User } from 'discord.js';
+import type { SelfProfile } from '@zhin.js/im-contract';
+import type { DiscordRestRequest } from './endpoint.js';
+import { DiscordRestRequestError } from './rest-request-error.js';
+
+function profileOf(user: Pick<User, 'username' | 'avatarURL'>): SelfProfile {
+  return { nickname: user.username, avatar: user.avatarURL() };
+}
+
+/** The Gateway's native ClientUser owns its current username/avatar and updates its own cache. */
+export function createDiscordSelfProfile(client: Pick<Client, 'user' | 'users'>): EndpointProfile {
+  const user = (): ClientUser => {
+    if (!client.user) throw new Error('Discord self account is unavailable');
+    return client.user;
+  };
+  return Object.freeze<EndpointProfile>({
+    writableFields: Object.freeze(['nickname', 'avatar']),
+    get current() { return client.user ? profileOf(client.user) : {}; },
+    async read({ signal }) {
+      return profileOf(await createEndpointOperation({ signal }).prepare(() =>
+        client.users.fetch(user().id, { force: true, cache: false })));
+    },
+    async write({ change, signal }) {
+      const operation = createEndpointOperation({ signal });
+      if (change.field === 'nickname') {
+        const updated = await operation.run(() => user().setUsername(change.value));
+        return { status: 'updated', profile: profileOf(updated) };
+      }
+      if (change.field === 'avatar') {
+        if (change.value.kind === 'file') {
+          return { status: 'rejected', message: 'Discord avatar requires resolved image bytes, URL or local path' };
+        }
+        const image = change.value.kind === 'base64' ? Buffer.from(change.value.value, 'base64') : change.value.value;
+        const updated = await operation.run(() => user().setAvatar(image));
+        return { status: 'updated', profile: profileOf(updated) };
+      }
+      return { status: 'rejected', message: `Discord does not expose ${change.field} through this port` };
+    },
+  });
+}
+
+interface DiscordOwnUser { readonly id: string; readonly username: string; readonly avatar: string | null; }
+interface DiscordProfileRestClient { request<T>(request: DiscordRestRequest): Promise<T>; }
+
+/** Interactions-only accounts use the same public identity fields through authenticated REST. */
+export function createDiscordRestSelfProfile(client: DiscordProfileRestClient, reportAccount: (id: string) => void): EndpointProfile {
+  const observed = (user: DiscordOwnUser): SelfProfile | undefined => {
+    if (!user?.id || typeof user.username !== 'string' || (user.avatar !== null && typeof user.avatar !== 'string')) {
+      return undefined;
+    }
+    reportAccount(user.id);
+    return { nickname: user.username, avatar: user.avatar === null ? null
+      : `https://cdn.discordapp.com/avatars/${user.id}/${user.avatar}.${user.avatar.startsWith('a_') ? 'gif' : 'png'}` };
+  };
+  return Object.freeze<EndpointProfile>({
+    writableFields: Object.freeze(['nickname', 'avatar']),
+    async read({ signal }) {
+      const profile = observed(await client.request<DiscordOwnUser>({ method: 'GET', path: '/users/@me', signal }));
+      if (!profile) throw new Error('Discord returned an incomplete self profile');
+      return profile;
+    },
+    async write({ change, signal }) {
+      let body: { username: string } | { avatar: string };
+      if (change.field === 'nickname') body = { username: change.value };
+      else if (change.field === 'avatar') {
+        if (change.value.kind !== 'base64' || !change.value.mime_type) {
+          return { status: 'rejected', message: 'Discord REST avatar requires resolved image bytes and MIME type' };
+        }
+        body = { avatar: `data:${change.value.mime_type};base64,${change.value.value}` };
+      } else return { status: 'rejected', message: `Discord does not expose ${change.field} through this port` };
+      let updated: DiscordOwnUser;
+      try { updated = await client.request<DiscordOwnUser>({ method: 'PATCH', path: '/users/@me', body, signal }); }
+      catch (error) {
+        if (!(error instanceof DiscordRestRequestError)) throw error;
+        if (error.acknowledged) return { status: 'updated' };
+        return { status: error.disposition === 'rejected' ? 'rejected' : 'unknown', message: error.message };
+      }
+      const profile = observed(updated);
+      return { status: 'updated', ...(profile ? { profile } : {}) };
+    },
+  });
+}