@zhin.js/adapter-satori 3.0.2 → 4.0.0

package/lib/endpoint.js

@@ -0,0 +1,379 @@
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { SatoriOpcode, buildWsUrl, callSatoriApi, extractCreatedMessageId, formatInboundContent, formatMessageId, formatSatoriOutbound, isMessageEvent, isSelfMentioned, parseMessageRef, resolveInboundSender, resolveInboundTarget, } from './protocol.js';
+import { registerSatoriWebhookRoutes } from './webhook.js';
+import { WS_OPEN, defaultCreateWebSocket, } from './ws.js';
+const logger = getLogger('satori');
+export class SatoriWsEndpoint {
+    #options;
+    #ws = null;
+    #login;
+    #lastSn;
+    #reconnectTimer = null;
+    #heartbeatTimer = null;
+    #open = false;
+    #started = false;
+    #stopping = false;
+    constructor(options) {
+        this.#options = options;
+    }
+    async start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        this.#stopping = false;
+        await this.#connect();
+    }
+    open() {
+        this.#open = true;
+    }
+    close() {
+        this.#open = false;
+    }
+    async stop() {
+        this.#open = false;
+        this.#stopping = true;
+        this.#clearReconnect();
+        this.#clearHeartbeat();
+        if (this.#ws) {
+            try {
+                this.#ws.close();
+            }
+            catch {
+                /* ignore */
+            }
+            this.#ws = null;
+        }
+        this.#started = false;
+        logger.debug(formatCompact({
+            op: 'disconnect',
+            endpoint: this.#options.config.name,
+        }));
+    }
+    async send({ target, payload }) {
+        const content = formatSatoriOutbound(payload);
+        const result = await this.#api('message', 'create', {
+            channel_id: target,
+            content,
+        });
+        const msgId = extractCreatedMessageId(result);
+        logger.debug(formatCompact({
+            op: 'satori_send',
+            endpoint: this.#options.config.name,
+            target,
+            messageId: msgId || undefined,
+        }));
+        return msgId ? formatMessageId(target, msgId) : '';
+    }
+    /** Test / internal: admit a gateway event when the endpoint is open. */
+    admit(body) {
+        if (!this.#open)
+            return;
+        if (body.login && !this.#login)
+            this.#login = body.login;
+        if (!isMessageEvent(body))
+            return;
+        const target = resolveInboundTarget(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,
+            content,
+            sender,
+            id: messageId,
+            metadata: Object.freeze({
+                type: body.type,
+                channelType: isPrivateChannelType(body) ? 'private' : 'group',
+                sn: body.sn,
+                platform: this.#login?.platform,
+                endpoint: this.#options.config.name,
+                ...(mentioned ? { mentioned: true } : {}),
+            }),
+        }).catch((err) => {
+            logger.warn(formatCompact({
+                op: 'satori_gateway_receive_failed',
+                target,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    async recall(id) {
+        const { channelId, messageId } = parseMessageRef(id);
+        await this.#api('message', 'delete', {
+            channel_id: channelId,
+            message_id: messageId,
+        });
+    }
+    /** Test helper: inject a READY login without a live socket. */
+    setLogin(login) {
+        this.#login = login;
+    }
+    async #connect() {
+        const { config } = this.#options;
+        const createWs = this.#options.createWebSocket ?? defaultCreateWebSocket;
+        const headers = {};
+        if (config.token)
+            headers.Authorization = `Bearer ${config.token}`;
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const ws = createWs(buildWsUrl(config.baseUrl, config.token), { headers });
+            this.#ws = ws;
+            ws.on('open', () => {
+                logger.debug(formatCompact({ endpoint: config.name, mode: 'ws' }));
+                this.#sendSignal(SatoriOpcode.IDENTIFY, {
+                    token: config.token,
+                    sn: this.#lastSn,
+                });
+                this.#startHeartbeat();
+                if (!settled) {
+                    settled = true;
+                    resolve();
+                }
+            });
+            ws.on('message', (data) => {
+                try {
+                    const raw = typeof data === 'string'
+                        ? data
+                        : Buffer.isBuffer(data)
+                            ? data.toString('utf8')
+                            : String(data ?? '');
+                    const signal = JSON.parse(raw);
+                    this.#handleSignal(signal);
+                }
+                catch (error) {
+                    logger.warn(formatCompact({
+                        op: 'ws_parse_error',
+                        endpoint: config.name,
+                        error: error instanceof Error ? error.message : String(error),
+                    }));
+                }
+            });
+            ws.on('close', (code, reason) => {
+                this.#clearHeartbeat();
+                const reasonStr = typeof reason === 'string'
+                    ? reason
+                    : Buffer.isBuffer(reason)
+                        ? reason.toString('utf8')
+                        : String(reason ?? '');
+                const numericCode = typeof code === 'number' ? code : 0;
+                logger.warn(formatCompact({
+                    op: 'disconnect',
+                    endpoint: config.name,
+                    code: numericCode,
+                    error: reasonStr || 'closed',
+                    reconnect_ms: this.#stopping ? undefined : 5000,
+                }));
+                if (!settled) {
+                    settled = true;
+                    reject(new Error(`Satori WS closed: ${numericCode} ${reasonStr}`));
+                    return;
+                }
+                if (!this.#stopping)
+                    this.#scheduleReconnect();
+            });
+            ws.on('error', (error) => {
+                logger.warn(formatCompact({
+                    op: 'ws_error',
+                    endpoint: config.name,
+                    ok: false,
+                    error: error instanceof Error ? error.message : String(error),
+                }));
+                if (!settled) {
+                    settled = true;
+                    reject(error instanceof Error ? error : new Error(String(error)));
+                }
+            });
+        });
+    }
+    #handleSignal(signal) {
+        if (signal.op === SatoriOpcode.READY && signal.body?.logins) {
+            const logins = signal.body.logins;
+            this.#login = logins[0];
+            if (!this.#login?.platform || !this.#login?.user?.id) {
+                logger.warn(formatCompact({ op: 'ready', ok: false, error: 'missing platform/user' }));
+            }
+            return;
+        }
+        if (signal.op === SatoriOpcode.EVENT && signal.body) {
+            if (typeof signal.body.sn === 'number')
+                this.#lastSn = signal.body.sn;
+            this.admit(signal.body);
+        }
+    }
+    #sendSignal(op, body) {
+        if (!this.#ws || this.#ws.readyState !== WS_OPEN)
+            return;
+        this.#ws.send(JSON.stringify({ op, body: body ?? {} }));
+    }
+    #startHeartbeat() {
+        this.#clearHeartbeat();
+        const interval = this.#options.config.heartbeat_interval;
+        this.#heartbeatTimer = setInterval(() => {
+            this.#sendSignal(SatoriOpcode.PING);
+        }, interval);
+    }
+    #scheduleReconnect() {
+        if (this.#reconnectTimer || this.#stopping)
+            return;
+        this.#reconnectTimer = setTimeout(() => {
+            this.#reconnectTimer = null;
+            void this.#connect().catch((err) => {
+                logger.warn(formatCompact({
+                    op: 'reconnect',
+                    endpoint: this.#options.config.name,
+                    ok: false,
+                    error: err instanceof Error ? err.message : String(err),
+                }));
+            });
+        }, 5000);
+    }
+    #clearReconnect() {
+        if (this.#reconnectTimer) {
+            clearTimeout(this.#reconnectTimer);
+            this.#reconnectTimer = null;
+        }
+    }
+    #clearHeartbeat() {
+        if (this.#heartbeatTimer) {
+            clearInterval(this.#heartbeatTimer);
+            this.#heartbeatTimer = null;
+        }
+    }
+    #apiOptions() {
+        return {
+            baseUrl: this.#options.config.baseUrl,
+            platform: this.#login?.platform ?? '',
+            userId: this.#login?.user?.id ?? '',
+            token: this.#options.config.token,
+        };
+    }
+    #api(resource, method, params) {
+        const call = this.#options.callApi ?? callSatoriApi;
+        return call(this.#apiOptions(), resource, method, params);
+    }
+}
+export class SatoriWebhookEndpoint {
+    #options;
+    #login;
+    #routeReleases = [];
+    #open = false;
+    #started = false;
+    constructor(options) {
+        this.#options = options;
+    }
+    /** Used by webhook handler. */
+    get isOpen() {
+        return this.#open;
+    }
+    get config() {
+        return this.#options.config;
+    }
+    async start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        this.#routeReleases.push(...registerSatoriWebhookRoutes(this.#options.http, this));
+        logger.info(formatCompact({
+            op: 'listen',
+            endpoint: this.#options.config.name,
+            mode: 'webhook',
+            path: this.#options.config.path,
+        }));
+    }
+    open() {
+        this.#open = true;
+    }
+    close() {
+        this.#open = false;
+    }
+    async stop() {
+        this.#open = false;
+        for (const release of this.#routeReleases.splice(0))
+            release();
+        this.#started = false;
+        logger.debug(formatCompact({
+            op: 'disconnect',
+            endpoint: this.#options.config.name,
+        }));
+    }
+    async send({ target, payload }) {
+        const content = formatSatoriOutbound(payload);
+        const result = await this.#api('message', 'create', {
+            channel_id: target,
+            content,
+        });
+        const msgId = extractCreatedMessageId(result);
+        logger.debug(formatCompact({
+            op: 'satori_send',
+            endpoint: this.#options.config.name,
+            target,
+            messageId: msgId || undefined,
+        }));
+        return msgId ? formatMessageId(target, msgId) : '';
+    }
+    admit(body) {
+        if (!this.#open)
+            return;
+        if (body.login && !this.#login)
+            this.#login = body.login;
+        if (!isMessageEvent(body))
+            return;
+        const target = resolveInboundTarget(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,
+            content,
+            sender,
+            id: messageId,
+            metadata: Object.freeze({
+                type: body.type,
+                channelType: isPrivateChannelType(body) ? 'private' : 'group',
+                sn: body.sn,
+                platform: this.#login?.platform,
+                endpoint: this.#options.config.name,
+                ...(mentioned ? { mentioned: true } : {}),
+            }),
+        }).catch((err) => {
+            logger.warn(formatCompact({
+                op: 'satori_gateway_receive_failed',
+                target,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    async recall(id) {
+        const { channelId, messageId } = parseMessageRef(id);
+        await this.#api('message', 'delete', {
+            channel_id: channelId,
+            message_id: messageId,
+        });
+    }
+    /** Test helper: inject login without a live webhook push. */
+    setLogin(login) {
+        this.#login = login;
+    }
+    #apiOptions() {
+        return {
+            baseUrl: this.#options.config.baseUrl,
+            platform: this.#login?.platform ?? '',
+            userId: this.#login?.user?.id ?? '',
+            token: this.#options.config.token,
+        };
+    }
+    #api(resource, method, params) {
+        const call = this.#options.callApi ?? callSatoriApi;
+        return call(this.#apiOptions(), resource, method, params);
+    }
+}
+function isPrivateChannelType(body) {
+    const channel = body.channel ?? body.message?.channel;
+    return channel?.type === 1;
+}

package/lib/index.d.ts

@@ -1,18 +1,4 @@
-import { SatoriAdapter } from './adapter.js';
-export * from './types.js';
-export { callSatoriApi } from './api.js';
-export * from './utils.js';
-export { SatoriWsClient } from './endpoint-ws.js';
-export { SatoriWebhookEndpoint } from './endpoint-webhook.js';
-export { SatoriAdapter, type SatoriBot } from './adapter.js';
-declare module 'zhin.js' {
-    namespace Plugin {
-        interface Contexts {
-            router: import('@zhin.js/host-router').Router;
-        }
-    }
-    interface Adapters {
-        satori: SatoriAdapter;
-    }
-}
-//# sourceMappingURL=index.d.ts.map
+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 { 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,25 +1,4 @@
-/**
- * Satori 适配器入口：单一适配器，支持 WS / Webhook，协议文档 https://satori.chat/zh-CN/introduction.html
- */
-import { usePlugin } from 'zhin.js';
-import { SatoriAdapter } from './adapter.js';
-export * from './types.js';
-export { callSatoriApi } from './api.js';
-export * from './utils.js';
-export { SatoriWsClient } from './endpoint-ws.js';
-export { SatoriWebhookEndpoint } from './endpoint-webhook.js';
-export { SatoriAdapter } from './adapter.js';
-const { provide } = usePlugin();
-provide({
-    name: 'satori',
-    description: 'Satori 协议适配器（WS 正向 / Webhook）',
-    mounted: async (p) => {
-        const adapter = new SatoriAdapter(p);
-        await adapter.start();
-        return adapter;
-    },
-    dispose: async (adapter) => {
-        await adapter.stop();
-    },
-});
-//# sourceMappingURL=index.js.map
+export { SatoriOpcode, buildWsUrl, callSatoriApi, extractCreatedMessageId, formatInboundContent, formatMessageId, formatSatoriOutbound, isMessageEvent, isPrivateChannel, parseMessageRef, resolveInboundSender, resolveInboundTarget, resolveSatoriConfig, } 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

@@ -0,0 +1,150 @@
+/**
+ * Satori protocol helpers (no legacy Adapter/Endpoint / segment-mapper).
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ * Spec: https://satori.chat/zh-CN/protocol/overview.html
+ */
+/** Opcode：EVENT=0, PING=1, PONG=2, IDENTIFY=3, READY=4, META=5 */
+export declare const SatoriOpcode: {
+    readonly EVENT: 0;
+    readonly PING: 1;
+    readonly PONG: 2;
+    readonly IDENTIFY: 3;
+    readonly READY: 4;
+    readonly META: 5;
+};
+export interface SatoriSignal {
+    readonly op: number;
+    readonly body?: Record<string, unknown>;
+}
+export interface SatoriUser {
+    readonly id: string;
+    readonly name?: string;
+    readonly avatar?: string;
+}
+export interface SatoriChannel {
+    readonly id: string;
+    /** 0=TEXT, 1=DIRECT, 2=CATEGORY, 3=VOICE */
+    readonly type?: number;
+    readonly name?: string;
+    readonly parent_id?: string;
+}
+export interface SatoriMessage {
+    readonly id: string;
+    readonly content?: string;
+    readonly channel?: SatoriChannel;
+    readonly user?: SatoriUser;
+    readonly member?: {
+        readonly user?: SatoriUser;
+        readonly nick?: string;
+    };
+    readonly created_at?: number;
+    readonly updated_at?: number;
+}
+export interface SatoriLogin {
+    readonly platform?: string;
+    readonly user?: SatoriUser;
+    readonly status?: number;
+    readonly sn?: number;
+}
+export interface SatoriEventBody {
+    readonly type?: string;
+    readonly sn?: number;
+    readonly timestamp?: number;
+    readonly login?: SatoriLogin;
+    readonly message?: SatoriMessage;
+    readonly channel?: SatoriChannel;
+    readonly user?: SatoriUser;
+    readonly guild?: {
+        readonly id: string;
+        readonly name?: string;
+    };
+    readonly member?: {
+        readonly user?: SatoriUser;
+        readonly nick?: string;
+        readonly roles?: string[];
+    };
+    readonly [key: string]: unknown;
+}
+export interface SatoriApiOptions {
+    readonly baseUrl: string;
+    readonly platform: string;
+    readonly userId: string;
+    readonly token?: string;
+}
+export interface SatoriWireSegment {
+    readonly type: string;
+    readonly data?: Record<string, unknown>;
+}
+/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
+export interface SatoriAdapterConfig {
+    readonly name?: string;
+    readonly connection?: 'ws' | 'webhook';
+    readonly baseUrl?: string;
+    readonly token?: string;
+    readonly heartbeat_interval?: number;
+    /** Webhook POST path (connection: webhook). */
+    readonly path?: string;
+    /** Transitional: legacy root `endpoints[]` with `context: satori`. */
+    readonly endpoints?: ReadonlyArray<Partial<ResolvedSatoriWsConfig> & {
+        readonly context?: string;
+        readonly connection?: 'ws' | 'webhook';
+        readonly path?: string;
+    }>;
+}
+export interface ResolvedSatoriWsConfig {
+    readonly context: 'satori';
+    readonly connection: 'ws';
+    readonly name: string;
+    readonly baseUrl: string;
+    readonly token?: string;
+    readonly heartbeat_interval: number;
+}
+export interface ResolvedSatoriWebhookConfig {
+    readonly context: 'satori';
+    readonly connection: 'webhook';
+    readonly name: string;
+    readonly baseUrl: string;
+    readonly token?: string;
+    readonly path: string;
+}
+export type ResolvedSatoriConfig = ResolvedSatoriWsConfig | ResolvedSatoriWebhookConfig;
+export declare function resolveSatoriConfig(config?: SatoriAdapterConfig): ResolvedSatoriConfig;
+/** Channel.type 1 = DIRECT (private). */
+export declare function isPrivateChannel(channel?: SatoriChannel): boolean;
+export declare function isMessageEvent(body: SatoriEventBody): body is SatoriEventBody & {
+    message: SatoriMessage;
+};
+export declare function buildWsUrl(baseUrl: string, token?: string): string;
+/**
+ * Call Satori HTTP API: POST {baseUrl}/v1/{resource}.{method}
+ * @see https://satori.chat/en-US/protocol/api.html
+ */
+export declare function callSatoriApi<T = unknown>(options: SatoriApiOptions, resource: string, method: string, params?: Record<string, unknown>): Promise<T>;
+/** Build inbound text for MessageGateway.receive. */
+export declare function formatInboundContent(body: SatoriEventBody & {
+    message: SatoriMessage;
+}): string;
+export declare function resolveInboundTarget(body: SatoriEventBody & {
+    message: SatoriMessage;
+}): string;
+export declare function resolveInboundSender(body: SatoriEventBody & {
+    message: SatoriMessage;
+}): string;
+/**
+ * Detect `<at id="…"/>` elements in message content targeting the bot selfId.
+ * selfId 来源：READY/事件携带的 `login.user.id`。
+ */
+export declare function isSelfMentioned(body: SatoriEventBody & {
+    message: SatoriMessage;
+}, selfId?: string): boolean;
+export declare function formatMessageId(channelId: string, messageId: string): string;
+export declare function parseMessageRef(id: string): {
+    channelId: string;
+    messageId: string;
+};
+/**
+ * Wire-encode an already-rendered outbound payload into Satori message content.
+ * Segment canonicalization is intentionally not done here.
+ */
+export declare function formatSatoriOutbound(payload: unknown): string;
+export declare function extractCreatedMessageId(result: unknown): string;