@lambdot/protocol-qq 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.1.0](https://github.com/Embers-of-the-Fire/lambdot/compare/protocol-qq-v0.0.1...protocol-qq-v0.1.0) (2026-08-29)
+
+
+### Features
+
+* **protocol-qq:** qq protocol with gateway and webhook infras ([d41936b](https://github.com/Embers-of-the-Fire/lambdot/commit/d41936be964e620c6da5641aecfe5f370c2e541c))

package/package.json

@@ -0,0 +1,16 @@
+{
+    "name": "@lambdot/protocol-qq",
+    "version": "0.1.0",
+    "type": "module",
+    "exports": {
+        ".": "./src/index.ts"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "dependencies": {
+        "@lambdot/core": "workspace:*",
+        "@lambdot/websocket": "workspace:*",
+        "tweetnacl": "^1.0.3"
+    }
+}

package/src/api.ts

@@ -0,0 +1,165 @@
+import type { Disposer, FeaturePlugin } from "@lambdot/core";
+
+import { readQqCredentials, type QqCredentialKeys, type QqEnvNeeds } from "./credentials.ts";
+import type { QqAddress } from "./events.ts";
+
+/**
+ * The REST half of the qq protocol, provided as a typed capability. Both
+ * receiving transports (gateway, webhook) deliver events only; sending a
+ * message is always an HTTPS call against the open platform. Owns the
+ * access-token lifecycle: tokens are cached and refreshed ahead of expiry
+ * (the platform hands out ~7200s tokens and keeps the old one valid for a
+ * 60s overlap).
+ */
+export interface QqApi {
+    readonly appId: string;
+    /** A valid access token; refreshed automatically ahead of expiry. */
+    accessToken(): Promise<string>;
+    /** The websocket gateway URL (`GET /gateway`). */
+    gatewayUrl(): Promise<string>;
+    /**
+     * Send a plain-text message (`msg_type` 0). Passive reply when the
+     * address carries a `msgId`: `msg_seq` is taken from the address, or
+     * auto-incremented per `msgId` when omitted (the platform rejects a
+     * repeated `msg_id` + `msg_seq` pair).
+     */
+    sendMessage(to: QqAddress, content: string): Promise<void>;
+}
+
+export type QqCapability<TCap extends string> = { readonly [K in TCap]: QqApi };
+
+export interface QqApiConfig {
+    /** Open-platform base URL; override to point at a mock in tests. */
+    readonly apiBase?: string;
+    /** Which env variables carry the credentials. */
+    readonly keys?: QqCredentialKeys;
+}
+
+const DEFAULT_API_BASE = "https://api.bot.qq.com";
+/** Refresh a token once it is within this margin of its expiry. */
+const EXPIRY_MARGIN_MS = 60_000;
+
+/**
+ * Provide the qq REST client as a typed capability, reading credentials from
+ * the env capability (see `@lambdot/env`). Register the env provider first:
+ *
+ * ```ts
+ * createKernel()
+ *     .use(envVars("qq-env", ["QQ_BOT_APP_ID", "QQ_BOT_APP_SECRET"]))
+ *     .use(qqApi("qq-api", "qq-env"));
+ * // ctx["qq-api"]: QqApi
+ * ```
+ */
+export function qqApi<TCap extends string, TEnvCap extends string>(
+    capability: TCap,
+    env: TEnvCap,
+): FeaturePlugin<
+    {},
+    {},
+    undefined,
+    QqApiConfig,
+    `qq-api:${TCap}`,
+    QqCapability<TCap>,
+    QqEnvNeeds<TEnvCap>
+> {
+    return {
+        name: `qq-api:${capability}`,
+        inject: [env],
+        apply(ctx, config) {
+            const credentials = readQqCredentials(ctx[env], config.keys);
+            const apiBase = config.apiBase ?? DEFAULT_API_BASE;
+
+            let cached: { token: string; expiresAt: number } | undefined;
+            let pending: Promise<string> | undefined;
+            const accessToken = (): Promise<string> => {
+                if (cached && Date.now() < cached.expiresAt) return Promise.resolve(cached.token);
+                pending ??= fetch(`${apiBase}/app/getAppAccessToken`, {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify({
+                        appId: credentials.appId,
+                        clientSecret: credentials.clientSecret,
+                    }),
+                })
+                    .then(async (res) => {
+                        if (!res.ok)
+                            throw new Error(
+                                `qq access token request failed: ${res.status} ${await res.text()}`,
+                            );
+                        const body = (await res.json()) as {
+                            access_token?: unknown;
+                            expires_in?: unknown;
+                        };
+                        if (typeof body.access_token !== "string")
+                            throw new Error("qq access token response is missing access_token");
+                        return {
+                            token: body.access_token,
+                            expiresAt:
+                                Date.now() +
+                                // The docs' examples show expires_in as a string.
+                                Number(body.expires_in ?? 7200) * 1000 -
+                                EXPIRY_MARGIN_MS,
+                        };
+                    })
+                    .then(
+                        (next) => {
+                            cached = next;
+                            pending = undefined;
+                            return next.token;
+                        },
+                        (error: unknown) => {
+                            pending = undefined;
+                            throw error;
+                        },
+                    );
+                return pending;
+            };
+
+            const authed = async (path: string, init?: RequestInit): Promise<Response> => {
+                const headers = new Headers(init?.headers);
+                headers.set("content-type", "application/json");
+                headers.set("authorization", `QQBot ${await accessToken()}`);
+                const res = await fetch(`${apiBase}${path}`, { ...init, headers });
+                if (!res.ok)
+                    throw new Error(`qq api ${path} failed: ${res.status} ${await res.text()}`);
+                return res;
+            };
+
+            // Passive replies to one msg_id must increment msg_seq.
+            const msgSeqs = new Map<string, number>();
+
+            const api: QqApi = {
+                appId: credentials.appId,
+                accessToken,
+                async gatewayUrl() {
+                    const res = await authed("/gateway");
+                    const body = (await res.json()) as { url?: unknown };
+                    if (typeof body.url !== "string")
+                        throw new Error("qq gateway response is missing url");
+                    return body.url;
+                },
+                async sendMessage(to, content) {
+                    const path =
+                        to.scope === "group"
+                            ? `/v2/groups/${to.openid}/messages`
+                            : `/v2/users/${to.openid}/messages`;
+                    const body: Record<string, unknown> = { msg_type: 0, content };
+                    if (to.msgId !== undefined) {
+                        body.msg_id = to.msgId;
+                        const seq = (msgSeqs.get(to.msgId) ?? 0) + 1;
+                        msgSeqs.set(to.msgId, seq);
+                        body.msg_seq = to.msgSeq ?? seq;
+                    }
+                    await authed(path, { method: "POST", body: JSON.stringify(body) });
+                },
+            };
+
+            // See `wsTransport` in @lambdot/websocket for why `provide` is pinned here.
+            return (ctx.provide as (name: TCap, value: QqApi) => Disposer).call(
+                ctx,
+                capability,
+                api,
+            );
+        },
+    };
+}

package/src/credentials.ts

@@ -0,0 +1,40 @@
+/**
+ * The env-capability view the qq plugins declare as `TInjects`: any
+ * string-keyed snapshot of variables. `@lambdot/env`'s
+ * `EnvCapability<TCap, TKey>` narrows the keys but stays assignable to this,
+ * so the fold's capability-type check accepts it.
+ */
+export type QqEnvNeeds<TEnvCap extends string> = {
+    readonly [K in TEnvCap]: Readonly<Record<string, string>>;
+};
+
+/** The bot credentials issued by the QQ open platform. */
+export interface QqCredentials {
+    readonly appId: string;
+    readonly clientSecret: string;
+}
+
+/** Which env variables carry the credentials (overridable per plugin config). */
+export interface QqCredentialKeys {
+    readonly appId: string;
+    readonly clientSecret: string;
+}
+
+export const DEFAULT_QQ_CREDENTIAL_KEYS: QqCredentialKeys = {
+    appId: "QQ_BOT_APP_ID",
+    clientSecret: "QQ_BOT_APP_SECRET",
+};
+
+/** Read the credentials out of an env snapshot, failing loudly when absent. */
+export function readQqCredentials(
+    env: Readonly<Record<string, string>>,
+    keys: QqCredentialKeys = DEFAULT_QQ_CREDENTIAL_KEYS,
+): QqCredentials {
+    const appId = env[keys.appId];
+    const clientSecret = env[keys.clientSecret];
+    if (!appId || !clientSecret)
+        throw new Error(
+            `qq credentials missing: "${keys.appId}" and "${keys.clientSecret}" must both be set`,
+        );
+    return { appId, clientSecret };
+}

package/src/events.ts

@@ -0,0 +1,125 @@
+import type { Address, EventDef, OutputContract } from "@lambdot/core";
+
+/**
+ * Where a qq message goes. Owned by the output half of the qq platform —
+ * outputs consume addresses, inputs produce them. `msgId`/`msgSeq` carry the
+ * passive-reply reference (`msg_id`/`msg_seq`) from the triggering message;
+ * omit both for an active (proactive) message.
+ */
+export interface QqAddress extends Address<"qq"> {
+    /** Which conversation the message belongs to. */
+    readonly scope: "group" | "c2c";
+    /** `group_openid` for groups, the user's openid for C2C. */
+    readonly openid: string;
+    /** Passive-reply reference, from the triggering event's `d.id`. */
+    readonly msgId?: string;
+    /** Passive-reply sequence; the output auto-increments it per reply. */
+    readonly msgSeq?: number;
+}
+
+/** The payload produced by qq message events: plain-text content only. */
+export interface QqMessage {
+    /** Message id (`msg_id`), reused as the passive-reply reference. */
+    readonly id: string;
+    readonly content: string;
+    readonly authorOpenid: string;
+    readonly timestamp: string;
+}
+
+/**
+ * Events produced by qq inputs (gateway and webhook alike): one kind per
+ * conversation scope. A type alias (not an interface extending `EventMap`)
+ * so `keyof` stays exactly these kinds.
+ */
+export type QqEvents = {
+    "qq.group-message": EventDef<QqMessage, QqAddress>;
+    "qq.c2c-message": EventDef<QqMessage, QqAddress>;
+};
+
+/** The qq platform's output contract: plain text (msg_type 0). */
+export type QqOutputs = {
+    qq: OutputContract<QqAddress, string>;
+};
+
+/** The wire shape of a `GROUP_AT_MESSAGE_CREATE` dispatch body. */
+interface QqRawGroupMessage {
+    id?: unknown;
+    content?: unknown;
+    group_openid?: unknown;
+    timestamp?: unknown;
+    author?: { member_openid?: unknown };
+}
+
+/** The wire shape of a `C2C_MESSAGE_CREATE` dispatch body. */
+interface QqRawC2cMessage {
+    id?: unknown;
+    content?: unknown;
+    timestamp?: unknown;
+    author?: { user_openid?: unknown };
+}
+
+/**
+ * Decode a dispatch (`t`, `d`) pair into an ingestible event, or null to
+ * ignore it. Shared by the gateway and webhook inputs — both transports
+ * deliver the same `{op, t, d}` envelope.
+ */
+export function decodeMessageEvent(
+    t: string,
+    d: unknown,
+): { kind: keyof QqEvents; payload: QqMessage; address: QqAddress } | null {
+    if (typeof d !== "object" || d === null) return null;
+
+    if (t === "GROUP_AT_MESSAGE_CREATE") {
+        const raw = d as QqRawGroupMessage;
+        if (
+            typeof raw.id !== "string" ||
+            typeof raw.content !== "string" ||
+            typeof raw.group_openid !== "string" ||
+            typeof raw.author?.member_openid !== "string"
+        )
+            return null;
+        return {
+            kind: "qq.group-message",
+            payload: {
+                id: raw.id,
+                // The platform strips the @bot prefix but leaves padding.
+                content: raw.content.trim(),
+                authorOpenid: raw.author.member_openid,
+                timestamp: typeof raw.timestamp === "string" ? raw.timestamp : "",
+            },
+            address: {
+                platform: "qq",
+                scope: "group",
+                openid: raw.group_openid,
+                msgId: raw.id,
+            },
+        };
+    }
+
+    if (t === "C2C_MESSAGE_CREATE") {
+        const raw = d as QqRawC2cMessage;
+        if (
+            typeof raw.id !== "string" ||
+            typeof raw.content !== "string" ||
+            typeof raw.author?.user_openid !== "string"
+        )
+            return null;
+        return {
+            kind: "qq.c2c-message",
+            payload: {
+                id: raw.id,
+                content: raw.content.trim(),
+                authorOpenid: raw.author.user_openid,
+                timestamp: typeof raw.timestamp === "string" ? raw.timestamp : "",
+            },
+            address: {
+                platform: "qq",
+                scope: "c2c",
+                openid: raw.author.user_openid,
+                msgId: raw.id,
+            },
+        };
+    }
+
+    return null;
+}

package/src/gateway.ts

@@ -0,0 +1,165 @@
+import type { Disposer, FeaturePlugin, InputPlugin } from "@lambdot/core";
+import type { WsCapability, WsConnection } from "@lambdot/websocket";
+
+import type { QqCapability } from "./api.ts";
+import { decodeMessageEvent, type QqEvents } from "./events.ts";
+
+/** `GROUP_AND_C2C_EVENT` (1 << 25): group at-messages and C2C messages. */
+export const QQ_INTENT_GROUP_AND_C2C = 1 << 25;
+
+/**
+ * The qq-specific half of the transport: unlike the generic `wsTransport`,
+ * the gateway URL is not static configuration — it is discovered through the
+ * REST client (`GET /gateway` with the access token). Resolves the URL at
+ * activation, owns the socket, and provides the connection as a typed
+ * `WsCapability` so the input can ride it. Register after the api:
+ *
+ * ```ts
+ * .use(qqApi("qq-api", "qq-env"))
+ * .use(qqGatewayTransport("qq-ws", "qq-api"))
+ * ```
+ */
+export function qqGatewayTransport<TWsCap extends string, TApiCap extends string>(
+    capability: TWsCap,
+    api: TApiCap,
+): FeaturePlugin<
+    {},
+    {},
+    undefined,
+    void,
+    `qq-gateway-transport:${TWsCap}`,
+    WsCapability<TWsCap>,
+    QqCapability<TApiCap>
+> {
+    return {
+        name: `qq-gateway-transport:${capability}`,
+        inject: [api],
+        async apply(ctx) {
+            const url = await ctx[api].gatewayUrl();
+            const socket = new WebSocket(url);
+            await new Promise<void>((resolve, reject) => {
+                socket.addEventListener("open", () => resolve(), { once: true });
+                socket.addEventListener(
+                    "error",
+                    () => reject(new Error("qq gateway failed to connect")),
+                    { once: true },
+                );
+            });
+
+            const listeners = new Set<(data: string) => void>();
+            socket.addEventListener("message", (event) => {
+                if (typeof event.data !== "string") return;
+                for (const listener of listeners) listener(event.data);
+            });
+
+            const connection: WsConnection = {
+                url,
+                send: (data) => socket.send(data),
+                onMessage(listener) {
+                    listeners.add(listener);
+                    return () => {
+                        listeners.delete(listener);
+                    };
+                },
+            };
+
+            // See `wsTransport` in @lambdot/websocket for why `provide` is pinned here.
+            const unprovide = (ctx.provide as (name: TWsCap, value: WsConnection) => Disposer).call(
+                ctx,
+                capability,
+                connection,
+            );
+            return () => {
+                socket.close();
+                void unprovide();
+            };
+        },
+    };
+}
+
+export interface QqGatewayInputConfig {
+    /** Event intents bitmask; defaults to `QQ_INTENT_GROUP_AND_C2C`. */
+    readonly intents?: number;
+}
+
+/**
+ * The receiving half of the gateway infra: consumes the connection provided
+ * by {@link qqGatewayTransport} and runs the basic gateway algorithm —
+ * identify on hello (op 10), heartbeat on the advertised interval (op 1),
+ * decode dispatches (op 0) into message events. Resume (op 6) is deliberately
+ * not implemented: a dropped connection is a fresh identify.
+ */
+export function qqGatewayInput<TWsCap extends string, TApiCap extends string>(
+    ws: TWsCap,
+    api: TApiCap,
+): InputPlugin<
+    QqEvents,
+    QqGatewayInputConfig,
+    "qq-gateway-input",
+    {},
+    WsCapability<TWsCap> & QqCapability<TApiCap>
+> {
+    return {
+        role: "input",
+        name: "qq-gateway-input",
+        inject: [ws, api],
+        apply(ctx, config) {
+            const connection = ctx[ws];
+            const intents = config.intents ?? QQ_INTENT_GROUP_AND_C2C;
+            let lastSeq: number | null = null;
+            let heartbeat: ReturnType<typeof setInterval> | undefined;
+
+            const unsubscribe = connection.onMessage((data) => {
+                let frame: { op?: unknown; d?: unknown; s?: unknown; t?: unknown };
+                try {
+                    frame = JSON.parse(data) as typeof frame;
+                } catch {
+                    return; // not JSON: not ours
+                }
+                if (typeof frame.s === "number") lastSeq = frame.s;
+
+                switch (frame.op) {
+                    case 10: {
+                        // Hello: identify, then heartbeat on the advertised interval.
+                        const d = frame.d as { heartbeat_interval?: unknown } | null | undefined;
+                        const interval =
+                            typeof d?.heartbeat_interval === "number"
+                                ? d.heartbeat_interval
+                                : 45_000;
+                        void ctx[api].accessToken().then((token) => {
+                            connection.send(
+                                JSON.stringify({
+                                    op: 2,
+                                    d: {
+                                        token: `QQBot ${token}`,
+                                        intents,
+                                        shard: [0, 1],
+                                        properties: {},
+                                    },
+                                }),
+                            );
+                        });
+                        heartbeat = setInterval(() => {
+                            connection.send(JSON.stringify({ op: 1, d: lastSeq }));
+                        }, interval);
+                        break;
+                    }
+                    case 0: {
+                        // Dispatch: message events become lambdot events.
+                        if (typeof frame.t !== "string") break;
+                        const decoded = decodeMessageEvent(frame.t, frame.d);
+                        if (decoded)
+                            void ctx.ingest(decoded.kind, decoded.payload, decoded.address);
+                        break;
+                    }
+                    // 11 is a heartbeat ack; every other opcode needs no handling.
+                }
+            });
+
+            return () => {
+                if (heartbeat !== undefined) clearInterval(heartbeat);
+                void unsubscribe();
+            };
+        },
+    };
+}

package/src/index.ts

@@ -0,0 +1,179 @@
+import type { FeaturePlugin, InputPlugin, OutputPlugin } from "@lambdot/core";
+import type { WsCapability } from "@lambdot/websocket";
+
+import { qqApi, type QqApiConfig, type QqCapability } from "./api.ts";
+import type { QqEnvNeeds } from "./credentials.ts";
+import type { QqAddress, QqEvents } from "./events.ts";
+import { qqGatewayInput, qqGatewayTransport, type QqGatewayInputConfig } from "./gateway.ts";
+import { qqOutput } from "./output.ts";
+import { qqWebhookInput, type QqWebhookCapability, type QqWebhookConfig } from "./webhook.ts";
+
+export { qqApi, type QqApi, type QqApiConfig, type QqCapability } from "./api.ts";
+export {
+    DEFAULT_QQ_CREDENTIAL_KEYS,
+    readQqCredentials,
+    type QqCredentialKeys,
+    type QqCredentials,
+    type QqEnvNeeds,
+} from "./credentials.ts";
+export {
+    decodeMessageEvent,
+    type QqAddress,
+    type QqEvents,
+    type QqMessage,
+    type QqOutputs,
+} from "./events.ts";
+export {
+    QQ_INTENT_GROUP_AND_C2C,
+    qqGatewayInput,
+    qqGatewayTransport,
+    type QqGatewayInputConfig,
+} from "./gateway.ts";
+export { qqOutput } from "./output.ts";
+export {
+    qqWebhookInput,
+    type QqWebhook,
+    type QqWebhookCapability,
+    type QqWebhookConfig,
+} from "./webhook.ts";
+
+/**
+ * One qq platform over the websocket gateway, bundled: the REST client, the
+ * gateway transport that discovers the socket URL through it, the receiving
+ * input, and the shared output. The pieces stay separate (rather than one
+ * fused plugin) so the type fold can keep enforcing registration order:
+ * env provider → api → transport → input → output → features.
+ *
+ * ```ts
+ * const qq = qqGatewayPlatform({ ws: "qq-ws", api: "qq-api", env: "qq-env" });
+ * createKernel()
+ *     .use(envVars("qq-env", ["QQ_BOT_APP_ID", "QQ_BOT_APP_SECRET"]))
+ *     .use(qq.api, {})
+ *     .use(qq.transport)
+ *     .use(qq.input, {})
+ *     .use(qq.output);
+ * ```
+ */
+export interface QqGatewayPlatform<
+    TWsCap extends string,
+    TApiCap extends string,
+    TEnvCap extends string,
+> {
+    readonly api: FeaturePlugin<
+        {},
+        {},
+        undefined,
+        QqApiConfig,
+        `qq-api:${TApiCap}`,
+        QqCapability<TApiCap>,
+        QqEnvNeeds<TEnvCap>
+    >;
+    readonly transport: FeaturePlugin<
+        {},
+        {},
+        undefined,
+        void,
+        `qq-gateway-transport:${TWsCap}`,
+        WsCapability<TWsCap>,
+        QqCapability<TApiCap>
+    >;
+    readonly input: InputPlugin<
+        QqEvents,
+        QqGatewayInputConfig,
+        "qq-gateway-input",
+        {},
+        WsCapability<TWsCap> & QqCapability<TApiCap>
+    >;
+    readonly output: OutputPlugin<
+        "qq",
+        QqAddress,
+        string,
+        void,
+        "qq-output",
+        {},
+        QqCapability<TApiCap>
+    >;
+}
+
+/** Build a whole gateway-backed qq platform from its capability names. */
+export function qqGatewayPlatform<
+    TWsCap extends string,
+    TApiCap extends string,
+    TEnvCap extends string,
+>(capabilities: {
+    readonly ws: TWsCap;
+    readonly api: TApiCap;
+    readonly env: TEnvCap;
+}): QqGatewayPlatform<TWsCap, TApiCap, TEnvCap> {
+    return {
+        api: qqApi(capabilities.api, capabilities.env),
+        transport: qqGatewayTransport(capabilities.ws, capabilities.api),
+        input: qqGatewayInput(capabilities.ws, capabilities.api),
+        output: qqOutput(capabilities.api),
+    };
+}
+
+/**
+ * One qq platform over the webhook (reversed-post) infra, bundled: the
+ * webhook input that provides the callback-handler capability, the REST
+ * client, and the output. Registration order: env provider → webhook → api →
+ * output → features.
+ *
+ * ```ts
+ * const qq = qqWebhookPlatform({ webhook: "qq-webhook", api: "qq-api", env: "qq-env" });
+ * createKernel()
+ *     .use(envVars("qq-env", ["QQ_BOT_APP_ID", "QQ_BOT_APP_SECRET"]))
+ *     .use(qq.webhook, {})
+ *     .use(qq.api, {})
+ *     .use(qq.output);
+ * // in the hono route: return kernel.ctx["qq-webhook"].handle(c.req.raw);
+ * ```
+ */
+export interface QqWebhookPlatform<
+    TCap extends string,
+    TApiCap extends string,
+    TEnvCap extends string,
+> {
+    readonly webhook: InputPlugin<
+        QqEvents,
+        QqWebhookConfig,
+        `qq-webhook:${TCap}`,
+        QqWebhookCapability<TCap>,
+        QqEnvNeeds<TEnvCap>
+    >;
+    readonly api: FeaturePlugin<
+        {},
+        {},
+        undefined,
+        QqApiConfig,
+        `qq-api:${TApiCap}`,
+        QqCapability<TApiCap>,
+        QqEnvNeeds<TEnvCap>
+    >;
+    readonly output: OutputPlugin<
+        "qq",
+        QqAddress,
+        string,
+        void,
+        "qq-output",
+        {},
+        QqCapability<TApiCap>
+    >;
+}
+
+/** Build a whole webhook-backed qq platform from its capability names. */
+export function qqWebhookPlatform<
+    TCap extends string,
+    TApiCap extends string,
+    TEnvCap extends string,
+>(capabilities: {
+    readonly webhook: TCap;
+    readonly api: TApiCap;
+    readonly env: TEnvCap;
+}): QqWebhookPlatform<TCap, TApiCap, TEnvCap> {
+    return {
+        webhook: qqWebhookInput(capabilities.webhook, capabilities.env),
+        api: qqApi(capabilities.api, capabilities.env),
+        output: qqOutput(capabilities.api),
+    };
+}

package/src/output.ts

@@ -0,0 +1,31 @@
+import type { OutputPlugin } from "@lambdot/core";
+
+import type { QqApi, QqCapability } from "./api.ts";
+import type { QqAddress } from "./events.ts";
+
+/**
+ * The output half of the qq platform: plain text (msg_type 0) through the
+ * REST client provided by `qqApi`. Sending is transport-independent — the
+ * gateway and webhook infras share this output.
+ */
+export function qqOutput<TApiCap extends string>(
+    api: TApiCap,
+): OutputPlugin<"qq", QqAddress, string, void, "qq-output", {}, QqCapability<TApiCap>> {
+    let client: QqApi | undefined;
+    return {
+        role: "output",
+        name: "qq-output",
+        platform: "qq",
+        inject: [api],
+        async send(to, content) {
+            if (!client) throw new Error('output "qq" is not active');
+            await client.sendMessage(to, content);
+        },
+        apply(ctx) {
+            client = ctx[api];
+            return () => {
+                client = undefined;
+            };
+        },
+    };
+}

package/src/webhook.ts

@@ -0,0 +1,137 @@
+import type { Disposer, InputPlugin } from "@lambdot/core";
+import nacl from "tweetnacl";
+
+import { readQqCredentials, type QqCredentialKeys, type QqEnvNeeds } from "./credentials.ts";
+import { decodeMessageEvent, type QqEvents } from "./events.ts";
+
+/**
+ * The request bridge, provided as a typed capability: the HTTP route lives
+ * outside the event pipeline (a hono handler, a worker's fetch), so it hands
+ * each callback request to `handle` and sends back the returned response —
+ * the same bridge pattern as the cloudflare example's `PingService`.
+ */
+export interface QqWebhook {
+    handle(request: Request): Promise<Response>;
+}
+
+export type QqWebhookCapability<TCap extends string> = { readonly [K in TCap]: QqWebhook };
+
+export interface QqWebhookConfig {
+    /** Which env variables carry the credentials. */
+    readonly keys?: QqCredentialKeys;
+}
+
+/**
+ * The webhook (reversed-post) input: QQ pushes events to an HTTPS callback
+ * address. Registers the message event kinds and provides a {@link QqWebhook}
+ * capability that implements the callback algorithm — op 13 address
+ * validation (sign `event_ts + plain_token`), ed25519 verification of
+ * `X-Signature-Ed25519` over `timestamp + body` for everything else — then
+ * ingests message dispatches. The bot secret seeds the ed25519 keypair
+ * (repeated to 32 bytes).
+ *
+ * ```ts
+ * .use(qqWebhookInput("qq-webhook", "qq-env"), {});
+ * // in the hono route: return kernel.ctx["qq-webhook"].handle(c.req.raw);
+ * ```
+ */
+export function qqWebhookInput<TCap extends string, TEnvCap extends string>(
+    capability: TCap,
+    env: TEnvCap,
+): InputPlugin<
+    QqEvents,
+    QqWebhookConfig,
+    `qq-webhook:${TCap}`,
+    QqWebhookCapability<TCap>,
+    QqEnvNeeds<TEnvCap>
+> {
+    return {
+        role: "input",
+        name: `qq-webhook:${capability}`,
+        inject: [env],
+        apply(ctx, config) {
+            const credentials = readQqCredentials(ctx[env], config.keys);
+            // The bot secret seeds the ed25519 keypair: repeat to 32 bytes.
+            let seed = credentials.clientSecret;
+            while (seed.length < 32) seed += seed;
+            const keyPair = nacl.sign.keyPair.fromSeed(new TextEncoder().encode(seed.slice(0, 32)));
+
+            const webhook: QqWebhook = {
+                async handle(request) {
+                    if (request.method !== "POST")
+                        return new Response("method not allowed", { status: 405 });
+                    const body = await request.text();
+                    let frame: { op?: unknown; d?: unknown; t?: unknown };
+                    try {
+                        frame = JSON.parse(body) as typeof frame;
+                    } catch {
+                        return new Response("bad request", { status: 400 });
+                    }
+
+                    // op 13: callback-address validation. Sign, no verify.
+                    if (frame.op === 13) {
+                        const d = frame.d as
+                            | { plain_token?: unknown; event_ts?: unknown }
+                            | null
+                            | undefined;
+                        if (typeof d?.plain_token !== "string" || typeof d.event_ts !== "string")
+                            return new Response("bad request", { status: 400 });
+                        const signature = toHex(
+                            nacl.sign.detached(
+                                new TextEncoder().encode(d.event_ts + d.plain_token),
+                                keyPair.secretKey,
+                            ),
+                        );
+                        return Response.json({ plain_token: d.plain_token, signature });
+                    }
+
+                    // Everything else: verify the ed25519 signature over
+                    // timestamp + body before trusting the payload.
+                    const signature = request.headers.get("x-signature-ed25519");
+                    const timestamp = request.headers.get("x-signature-timestamp");
+                    if (
+                        signature === null ||
+                        timestamp === null ||
+                        !verify(keyPair.publicKey, timestamp + body, signature)
+                    )
+                        return new Response("unauthorized", { status: 401 });
+
+                    if (frame.op === 0 && typeof frame.t === "string") {
+                        const decoded = decodeMessageEvent(frame.t, frame.d);
+                        if (decoded)
+                            await ctx.ingest(decoded.kind, decoded.payload, decoded.address);
+                    }
+                    return Response.json({});
+                },
+            };
+
+            // See `wsTransport` in @lambdot/websocket for why `provide` is pinned here.
+            return (ctx.provide as (name: TCap, value: QqWebhook) => Disposer).call(
+                ctx,
+                capability,
+                webhook,
+            );
+        },
+    };
+}
+
+function verify(publicKey: Uint8Array, message: string, signatureHex: string): boolean {
+    const signature = fromHex(signatureHex);
+    return (
+        signature !== null &&
+        signature.length === nacl.sign.signatureLength &&
+        nacl.sign.detached.verify(new TextEncoder().encode(message), signature, publicKey)
+    );
+}
+
+function toHex(bytes: Uint8Array): string {
+    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+function fromHex(hex: string): Uint8Array | null {
+    if (hex.length % 2 !== 0 || !/^[0-9a-fA-F]+$/.test(hex)) return null;
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < bytes.length; i++)
+        bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    return bytes;
+}

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+    "extends": "../../../tsconfig.base.json",
+    "include": ["src"]
+}