@zhin.js/adapter-satori 5.0.0 → 5.0.2

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @zhin.js/adapter-satori
 
+## 5.0.2
+
+### Patch Changes
+
+- Updated dependencies [afc0e66]
+- Updated dependencies [2e41ad5]
+- Updated dependencies [9f57124]
+  - @zhin.js/core@1.5.2
+  - @zhin.js/adapter@1.1.5
+  - @zhin.js/im-contract@1.0.1
+  - @zhin.js/plugin-runtime@1.1.3
+  - @zhin.js/command@1.0.7
+  - @zhin.js/host-http@1.0.6
+  - zhin.js@6.0.2
+
+## 5.0.1
+
+### Patch Changes
+
+- Updated dependencies [c8f4d45]
+  - @zhin.js/plugin-runtime@1.1.2
+  - @zhin.js/host-http@1.0.5
+  - @zhin.js/adapter@1.1.4
+  - @zhin.js/command@1.0.6
+  - @zhin.js/core@1.5.1
+  - zhin.js@6.0.1
+
 ## 5.0.0
 
 ### Patch Changes

package/README.md

@@ -27,8 +27,8 @@ pnpm add @zhin.js/adapter-satori
 - `@zhin.js/host-http` — Webhook 模式需 `httpHostToken` 注册 POST 路由
 - 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`（`baseUrl` / `token` / …）
 
-入站：`gateway.receive({ adapter, target: channelId, content: text, sender, id, metadata })`  
-出站：`send({ target: channelId, payload })` → Satori `message.create`（payload 已由 gateway/core 渲染；无 segment-mapper）
+入站：`gateway.receive({ conversation, message, content, sender, metadata })`（`conversation` 为 ConversationRef：DIRECT 频道 → kind `private`，其余 → kind `group`、所属 guild 进 `parent`）  
+出站：`send({ conversation, payload })` → Satori `message.create`（`channel_id = conversation.id`；payload 已由 gateway/core 渲染；无 segment-mapper）
 
 入站 `metadata.mentioned`：消息 content 中 `<at id="…"/>` 元素的 id 等于登录 selfId（READY/事件 `login.user.id`）时置 `true`。
 

package/lib/endpoint.d.ts

@@ -1,7 +1,7 @@
 /**
  * SatoriEndpoint — WebSocket and webhook lifecycle, outbound, admit.
  */
-import { type EndpointInstance, type EndpointManagement } from '@zhin.js/adapter';
+import { type EndpointInstance, type EndpointManagement, type EndpointSendRequest } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
@@ -23,10 +23,7 @@ export declare class SatoriWsEndpoint implements EndpointInstance {
     open(): void;
     close(): void;
     stop(): Promise<void>;
-    send({ target, payload }: {
-        readonly target: string;
-        readonly payload: unknown;
-    }): Promise<string>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     /** Test / internal: admit a gateway event when the endpoint is open. */
     admit(body: SatoriEventBody): void;
     recall(id: string): Promise<void>;
@@ -51,10 +48,7 @@ export declare class SatoriWebhookEndpoint implements EndpointInstance {
     open(): void;
     close(): void;
     stop(): Promise<void>;
-    send({ target, payload }: {
-        readonly target: string;
-        readonly payload: unknown;
-    }): Promise<string>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     admit(body: SatoriEventBody): void;
     recall(id: string): Promise<void>;
     /** Test helper: inject login without a live webhook push. */

package/lib/endpoint.js

@@ -3,7 +3,7 @@
  */
 import { createEndpointLifecycle, } from '@zhin.js/adapter';
 import { formatCompact, getLogger } from '@zhin.js/logger';
-import { SatoriOpcode, buildWsUrl, callSatoriApi, extractCreatedMessageId, formatInboundContent, formatMessageId, formatSatoriOutbound, isMessageEvent, isSelfMentioned, parseMessageRef, resolveInboundSender, resolveInboundTarget, } from './protocol.js';
+import { SatoriOpcode, buildWsUrl, callSatoriApi, extractCreatedMessageId, formatInboundContent, formatMessageId, formatSatoriOutbound, isMessageEvent, isSelfMentioned, parseMessageRef, resolveInboundSender, satoriInboundConversation, } from './protocol.js';
 import { registerSatoriWebhookRoutes } from './webhook.js';
 import { WS_OPEN, defaultCreateWebSocket, } from './ws.js';
 const logger = getLogger('satori');
@@ -64,20 +64,20 @@ export class SatoriWsEndpoint {
         await this.#lifecycle.stop();
         this.#ws = null;
     }
-    async send({ target, payload }) {
+    async send({ conversation, payload }) {
         const content = formatSatoriOutbound(payload);
         const result = await this.#api('message', 'create', {
-            channel_id: target,
+            channel_id: conversation.id,
             content,
         });
         const msgId = extractCreatedMessageId(result);
         logger.debug(formatCompact({
             op: 'satori_send',
             endpoint: this.#options.config.name,
-            target,
+            channel: conversation.id,
             messageId: msgId || undefined,
         }));
-        return msgId ? formatMessageId(target, msgId) : '';
+        return msgId ? formatMessageId(conversation.id, msgId) : '';
     }
     /** Test / internal: admit a gateway event when the endpoint is open. */
     admit(body) {
@@ -87,18 +87,16 @@ export class SatoriWsEndpoint {
             this.#login = body.login;
         if (!isMessageEvent(body))
             return;
-        const target = resolveInboundTarget(body);
+        const conversation = satoriInboundConversation(String(this.#options.id), body);
         const content = formatInboundContent(body);
         const sender = resolveInboundSender(body);
-        const messageId = formatMessageId(target, body.message.id);
         const selfId = this.#login?.user?.id ?? body.login?.user?.id;
         const mentioned = isSelfMentioned(body, selfId);
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target,
+            conversation,
+            message: { conversation, id: body.message.id },
             content,
             sender,
-            id: messageId,
             metadata: Object.freeze({
                 type: body.type,
                 channelType: isPrivateChannelType(body) ? 'private' : 'group',
@@ -110,7 +108,7 @@ export class SatoriWsEndpoint {
         }).catch((err) => {
             logger.warn(formatCompact({
                 op: 'satori_gateway_receive_failed',
-                target,
+                channel: conversation.id,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });
@@ -295,20 +293,20 @@ export class SatoriWebhookEndpoint {
             endpoint: this.#options.config.name,
         }));
     }
-    async send({ target, payload }) {
+    async send({ conversation, payload }) {
         const content = formatSatoriOutbound(payload);
         const result = await this.#api('message', 'create', {
-            channel_id: target,
+            channel_id: conversation.id,
             content,
         });
         const msgId = extractCreatedMessageId(result);
         logger.debug(formatCompact({
             op: 'satori_send',
             endpoint: this.#options.config.name,
-            target,
+            channel: conversation.id,
             messageId: msgId || undefined,
         }));
-        return msgId ? formatMessageId(target, msgId) : '';
+        return msgId ? formatMessageId(conversation.id, msgId) : '';
     }
     admit(body) {
         if (!this.#open)
@@ -317,18 +315,16 @@ export class SatoriWebhookEndpoint {
             this.#login = body.login;
         if (!isMessageEvent(body))
             return;
-        const target = resolveInboundTarget(body);
+        const conversation = satoriInboundConversation(String(this.#options.id), body);
         const content = formatInboundContent(body);
         const sender = resolveInboundSender(body);
-        const messageId = formatMessageId(target, body.message.id);
         const selfId = this.#login?.user?.id ?? body.login?.user?.id;
         const mentioned = isSelfMentioned(body, selfId);
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target,
+            conversation,
+            message: { conversation, id: body.message.id },
             content,
             sender,
-            id: messageId,
             metadata: Object.freeze({
                 type: body.type,
                 channelType: isPrivateChannelType(body) ? 'private' : 'group',
@@ -340,7 +336,7 @@ export class SatoriWebhookEndpoint {
         }).catch((err) => {
             logger.warn(formatCompact({
                 op: 'satori_gateway_receive_failed',
-                target,
+                channel: conversation.id,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-export { SatoriOpcode, buildWsUrl, callSatoriApi, extractCreatedMessageId, formatInboundContent, formatMessageId, formatSatoriOutbound, isMessageEvent, isPrivateChannel, parseMessageRef, resolveInboundSender, resolveInboundTarget, resolveSatoriConfig, type ResolvedSatoriWebhookConfig, type ResolvedSatoriWsConfig, type SatoriAdapterConfig, type SatoriApiOptions, type SatoriChannel, type SatoriEventBody, type SatoriLogin, type SatoriMessage, type SatoriSignal, type SatoriUser, type SatoriWireSegment, } from './protocol.js';
+export { SatoriOpcode, buildWsUrl, callSatoriApi, extractCreatedMessageId, formatInboundContent, formatSatoriOutbound, isMessageEvent, isPrivateChannel, resolveInboundSender, resolveSatoriConfig, satoriInboundConversation, type ResolvedSatoriWebhookConfig, type ResolvedSatoriWsConfig, type SatoriAdapterConfig, type SatoriApiOptions, type SatoriChannel, type SatoriEventBody, type SatoriLogin, type SatoriMessage, type SatoriSignal, type SatoriUser, type SatoriWireSegment, } from './protocol.js';
 export { SatoriWebhookEndpoint, SatoriWsEndpoint, type CreateSatoriWebSocket, type SatoriApiCaller, type SatoriWebhookEndpointOptions, type SatoriWsEndpointOptions, type SatoriWsSocket, } from './endpoint.js';
 export { handleSatoriWebhookRequest, readRequestBody, registerSatoriWebhookRoutes, resolveSatoriOpcode, verifySatoriToken, type SatoriWebhookHandler, } from './webhook.js';
 export { WS_OPEN, defaultCreateWebSocket, } from './ws.js';

package/lib/index.js

@@ -1,4 +1,4 @@
-export { SatoriOpcode, buildWsUrl, callSatoriApi, extractCreatedMessageId, formatInboundContent, formatMessageId, formatSatoriOutbound, isMessageEvent, isPrivateChannel, parseMessageRef, resolveInboundSender, resolveInboundTarget, resolveSatoriConfig, } from './protocol.js';
+export { SatoriOpcode, buildWsUrl, callSatoriApi, extractCreatedMessageId, formatInboundContent, formatSatoriOutbound, isMessageEvent, isPrivateChannel, resolveInboundSender, resolveSatoriConfig, satoriInboundConversation, } from './protocol.js';
 export { SatoriWebhookEndpoint, SatoriWsEndpoint, } from './endpoint.js';
 export { handleSatoriWebhookRequest, readRequestBody, registerSatoriWebhookRoutes, resolveSatoriOpcode, verifySatoriToken, } from './webhook.js';
 export { WS_OPEN, defaultCreateWebSocket, } from './ws.js';

package/lib/protocol.d.ts

@@ -3,6 +3,7 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  * Spec: https://satori.chat/zh-CN/protocol/overview.html
  */
+import type { ConversationRef } from '@zhin.js/im-contract';
 /** Opcode：EVENT=0, PING=1, PONG=2, IDENTIFY=3, READY=4, META=5 */
 export declare const SatoriOpcode: {
     readonly EVENT: 0;
@@ -124,9 +125,13 @@ export declare function callSatoriApi<T = unknown>(options: SatoriApiOptions, re
 export declare function formatInboundContent(body: SatoriEventBody & {
     message: SatoriMessage;
 }): string;
-export declare function resolveInboundTarget(body: SatoriEventBody & {
+/**
+ * 入站归一化 → ConversationRef：Channel.type 1 (DIRECT) → kind 'private'；
+ * 其余频道消息 → kind 'group'，所属 guild 容器进 `parent`（kind 'channel'）。
+ */
+export declare function satoriInboundConversation(endpointId: string, body: SatoriEventBody & {
     message: SatoriMessage;
-}): string;
+}): ConversationRef;
 export declare function resolveInboundSender(body: SatoriEventBody & {
     message: SatoriMessage;
 }): string;

package/lib/protocol.js

@@ -113,9 +113,21 @@ export function formatInboundContent(body) {
     const content = body.message.content ?? '';
     return typeof content === 'string' ? content : String(content);
 }
-export function resolveInboundTarget(body) {
+/**
+ * 入站归一化 → ConversationRef：Channel.type 1 (DIRECT) → kind 'private'；
+ * 其余频道消息 → kind 'group'，所属 guild 容器进 `parent`（kind 'channel'）。
+ */
+export function satoriInboundConversation(endpointId, body) {
     const channel = body.channel ?? body.message.channel;
-    return channel?.id ?? '';
+    const kind = isPrivateChannel(channel) ? 'private' : 'group';
+    return {
+        endpoint: { id: endpointId, adapter: endpointId.split('\0')[0] ?? endpointId },
+        kind,
+        id: channel?.id ?? '',
+        ...(kind === 'group' && body.guild?.id
+            ? { parent: { kind: 'channel', id: body.guild.id } }
+            : {}),
+    };
 }
 export function resolveInboundSender(body) {
     const user = body.user ?? body.message.user ?? body.message.member?.user;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-satori",
-  "version": "5.0.0",
+  "version": "5.0.2",
   "description": "Zhin.js Satori adapter for Plugin Runtime (WebSocket client)",
   "type": "module",
   "main": "./lib/index.js",
@@ -39,25 +39,26 @@
   },
   "dependencies": {
     "ws": "^8.21.1",
-    "@zhin.js/adapter": "1.1.3",
-    "@zhin.js/command": "1.0.5",
-    "@zhin.js/core": "1.5.0",
-    "@zhin.js/host-http": "1.0.4",
+    "@zhin.js/adapter": "1.1.5",
+    "@zhin.js/command": "1.0.7",
+    "@zhin.js/core": "1.5.2",
+    "@zhin.js/host-http": "1.0.6",
+    "@zhin.js/im-contract": "1.0.1",
     "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.1.1"
+    "@zhin.js/plugin-runtime": "1.1.3"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
     "@types/ws": "^8.18.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "@zhin.js/host-http": "1.0.4"
+    "@zhin.js/host-http": "1.0.6"
   },
   "peerDependencies": {
-    "@zhin.js/adapter": "1.1.3",
-    "@zhin.js/core": "1.5.0",
-    "@zhin.js/plugin-runtime": "1.1.1",
-    "zhin.js": "6.0.0"
+    "@zhin.js/adapter": "1.1.5",
+    "@zhin.js/core": "1.5.2",
+    "@zhin.js/plugin-runtime": "1.1.3",
+    "zhin.js": "6.0.2"
   },
   "peerDependenciesMeta": {
     "zhin.js": {

package/src/endpoint.ts

@@ -9,6 +9,7 @@ import {
   type EndpointInstance,
   type EndpointLifecycle,
   type EndpointManagement,
+  type EndpointSendRequest,
 } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
@@ -26,7 +27,7 @@ import {
   isSelfMentioned,
   parseMessageRef,
   resolveInboundSender,
-  resolveInboundTarget,
+  satoriInboundConversation,
   type ResolvedSatoriWebhookConfig,
   type ResolvedSatoriWsConfig,
   type SatoriApiOptions,
@@ -117,20 +118,20 @@ export class SatoriWsEndpoint implements EndpointInstance {
     this.#ws = null;
   }
 
-  async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
+  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     const content = formatSatoriOutbound(payload);
     const result = await this.#api('message', 'create', {
-      channel_id: target,
+      channel_id: conversation.id,
       content,
     });
     const msgId = extractCreatedMessageId(result);
     logger.debug(formatCompact({
       op: 'satori_send',
       endpoint: this.#options.config.name,
-      target,
+      channel: conversation.id,
       messageId: msgId || undefined,
     }));
-    return msgId ? formatMessageId(target, msgId) : '';
+    return msgId ? formatMessageId(conversation.id, msgId) : '';
   }
 
   /** Test / internal: admit a gateway event when the endpoint is open. */
@@ -138,18 +139,16 @@ export class SatoriWsEndpoint implements EndpointInstance {
     if (!this.#open) return;
     if (body.login && !this.#login) this.#login = body.login;
     if (!isMessageEvent(body)) return;
-    const target = resolveInboundTarget(body);
+    const conversation = satoriInboundConversation(String(this.#options.id), body);
     const content = formatInboundContent(body);
     const sender = resolveInboundSender(body);
-    const messageId = formatMessageId(target, body.message.id);
     const selfId = this.#login?.user?.id ?? body.login?.user?.id;
     const mentioned = isSelfMentioned(body, selfId);
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target,
+      conversation,
+      message: { conversation, id: body.message.id },
       content,
       sender,
-      id: messageId,
       metadata: Object.freeze({
         type: body.type,
         channelType: isPrivateChannelType(body) ? 'private' : 'group',
@@ -161,7 +160,7 @@ export class SatoriWsEndpoint implements EndpointInstance {
     }).catch((err) => {
       logger.warn(formatCompact({
         op: 'satori_gateway_receive_failed',
-        target,
+        channel: conversation.id,
         error: err instanceof Error ? err.message : String(err),
       }));
     });
@@ -374,38 +373,36 @@ export class SatoriWebhookEndpoint implements EndpointInstance {
     }));
   }
 
-  async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
+  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     const content = formatSatoriOutbound(payload);
     const result = await this.#api('message', 'create', {
-      channel_id: target,
+      channel_id: conversation.id,
       content,
     });
     const msgId = extractCreatedMessageId(result);
     logger.debug(formatCompact({
       op: 'satori_send',
       endpoint: this.#options.config.name,
-      target,
+      channel: conversation.id,
       messageId: msgId || undefined,
     }));
-    return msgId ? formatMessageId(target, msgId) : '';
+    return msgId ? formatMessageId(conversation.id, msgId) : '';
   }
 
   admit(body: SatoriEventBody): void {
     if (!this.#open) return;
     if (body.login && !this.#login) this.#login = body.login;
     if (!isMessageEvent(body)) return;
-    const target = resolveInboundTarget(body);
+    const conversation = satoriInboundConversation(String(this.#options.id), body);
     const content = formatInboundContent(body);
     const sender = resolveInboundSender(body);
-    const messageId = formatMessageId(target, body.message.id);
     const selfId = this.#login?.user?.id ?? body.login?.user?.id;
     const mentioned = isSelfMentioned(body, selfId);
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target,
+      conversation,
+      message: { conversation, id: body.message.id },
       content,
       sender,
-      id: messageId,
       metadata: Object.freeze({
         type: body.type,
         channelType: isPrivateChannelType(body) ? 'private' : 'group',
@@ -417,7 +414,7 @@ export class SatoriWebhookEndpoint implements EndpointInstance {
     }).catch((err) => {
       logger.warn(formatCompact({
         op: 'satori_gateway_receive_failed',
-        target,
+        channel: conversation.id,
         error: err instanceof Error ? err.message : String(err),
       }));
     });

package/src/index.ts

@@ -4,14 +4,12 @@ export {
   callSatoriApi,
   extractCreatedMessageId,
   formatInboundContent,
-  formatMessageId,
   formatSatoriOutbound,
   isMessageEvent,
   isPrivateChannel,
-  parseMessageRef,
   resolveInboundSender,
-  resolveInboundTarget,
   resolveSatoriConfig,
+  satoriInboundConversation,
   type ResolvedSatoriWebhookConfig,
   type ResolvedSatoriWsConfig,
   type SatoriAdapterConfig,

package/src/protocol.ts

@@ -6,6 +6,7 @@
 
 import { pickCredential } from '@zhin.js/adapter';
 import { isMediaRef } from '@zhin.js/core';
+import type { ConversationKind, ConversationRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 
 const logger = getLogger('satori');
@@ -227,9 +228,25 @@ export function formatInboundContent(body: SatoriEventBody & { message: SatoriMe
   return typeof content === 'string' ? content : String(content);
 }
 
-export function resolveInboundTarget(body: SatoriEventBody & { message: SatoriMessage }): string {
+
+/**
+ * 入站归一化 → ConversationRef：Channel.type 1 (DIRECT) → kind 'private'；
+ * 其余频道消息 → kind 'group'，所属 guild 容器进 `parent`（kind 'channel'）。
+ */
+export function satoriInboundConversation(
+  endpointId: string,
+  body: SatoriEventBody & { message: SatoriMessage },
+): ConversationRef {
   const channel = body.channel ?? body.message.channel;
-  return channel?.id ?? '';
+  const kind: ConversationKind = isPrivateChannel(channel) ? 'private' : 'group';
+  return {
+    endpoint: { id: endpointId, adapter: endpointId.split('\0')[0] ?? endpointId },
+    kind,
+    id: channel?.id ?? '',
+    ...(kind === 'group' && body.guild?.id
+      ? { parent: { kind: 'channel' as const, id: body.guild.id } }
+      : {}),
+  };
 }
 
 export function resolveInboundSender(body: SatoriEventBody & { message: SatoriMessage }): string {