@nubemclaw/channel-qq-bot 2.0.0

package/LICENSE.md

@@ -0,0 +1,59 @@
+# LICENSE — NubemClaw v3
+
+**Copyright © 2026 Nubemsystems S.L.** All rights reserved.
+
+NubemClaw v3 (this monorepo and every `@nubemclaw/*` package published
+under it on the npm registry) is **proprietary software** distributed
+publicly under the SPDX identifier **`UNLICENSED`**. Public
+distribution via npm does NOT make this an open-source project. The
+absence of a permissive license is intentional — the source is
+visible for transparency and operator use, but the rights below apply.
+
+## Permitted
+
+- Installing and running the published `@nubemclaw/*` packages from
+  npm for personal, internal-business, or research use.
+- Reading the source code on the public repository.
+- Submitting issues, pull requests, and feedback to the upstream
+  repository (`nubemsystemsdev/NubemClaw-v3`). Contributions are
+  accepted under the Contributor License Agreement (CLA) gated at PR
+  time; by submitting a contribution you grant Nubemsystems a
+  perpetual, worldwide, non-exclusive license to use the contribution
+  under this proprietary license.
+
+## NOT permitted (without prior written authorisation from Nubemsystems S.L.)
+
+- Redistribution of the source or binaries outside the official npm
+  registry / GitHub release artifacts.
+- Forking and republishing under a different name or scope.
+- Removing or modifying the copyright notice in this file or in the
+  package manifests.
+- Selling, sublicensing, or offering as a hosted SaaS that competes
+  with Nubemsystems' commercial offerings.
+- Reverse-engineering the cloud control plane (when one exists) or
+  any non-source components shipped alongside.
+
+## Trademarks
+
+"NubemClaw", "Nubemsystems", and associated logos are trademarks of
+Nubemsystems S.L. They are not licensed by this document — using them
+to identify your fork, derivative, or service requires explicit
+written permission.
+
+## Warranty disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## Contact
+
+Licensing inquiries: `licensing@nubemsystems.es`.
+
+Operator (single point of contact for v3): José Luis Manzanares
+Fernández, Nubemsystems S.L. (`joseluis.manzanares@nubemsystems.es`).

package/dist/channel.d.ts

@@ -0,0 +1,30 @@
+import { type Channel, type ChannelTarget, type RestFetch } from "@nubemclaw/channel-sdk";
+/**
+ * F31.b — QQ Bot channel adapter (F31-fix.1: real provider body shape).
+ *
+ * QQ Bot OpenAPI group messages.
+ *
+ * Endpoint:
+ *   POST https://api.sgroup.qq.com/v2/groups/{target}/messages
+ *   Header: Authorization: Bot <token>
+ *   Body: ({ content: text, msg_type: 0 })
+ *
+ * The package OWNS its lifecycle: it does NOT inherit from a unified
+ * factory across the 21 F31.b adapters. `createRestChannelBase`
+ * (channel-sdk) is a code-reuse helper for the HTTP send path; each
+ * package wires its own auth + body + (future) inbound parser.
+ */
+export interface QqBotChannelConfig {
+    readonly token: string;
+    readonly endpoint?: string;
+    readonly fetch?: RestFetch;
+    readonly capabilities?: import("@nubemclaw/channel-sdk").ChannelCapabilities;
+}
+export declare const DEFAULT_QQBOT_ENDPOINT = "https://api.sgroup.qq.com/v2/groups/{target}/messages";
+export declare const buildSendBody: (_target: ChannelTarget, text: string) => Record<string, unknown>;
+export declare const buildSendRequest: (endpoint: string, token: string, target: ChannelTarget, text: string) => {
+    url: string;
+    init: RequestInit;
+};
+export declare const createQqBotChannel: (config: QqBotChannelConfig) => Channel;
+//# sourceMappingURL=channel.d.ts.map

package/dist/channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,OAAO,EACZ,KAAK,aAAa,EAClB,KAAK,SAAS,EAGf,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,wBAAwB,EAAE,mBAAmB,CAAC;CAC9E;AAED,eAAO,MAAM,sBAAsB,0DAA0D,CAAC;AAK9F,eAAO,MAAM,aAAa,GAAI,SAAS,aAAa,EAAE,MAAM,MAAM,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAGzF,CAAC;AAEH,eAAO,MAAM,gBAAgB,GAC3B,UAAU,MAAM,EAChB,OAAO,MAAM,EACb,QAAQ,aAAa,EACrB,MAAM,MAAM,KACX;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAalC,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,QAAQ,kBAAkB,KAAG,OAqB/D,CAAC"}

package/dist/channel.js

@@ -0,0 +1,44 @@
+import { TEXT_ONLY_REST_CAPABILITIES, createRestChannelBase, extractMessageText, } from "@nubemclaw/channel-sdk";
+export const DEFAULT_QQBOT_ENDPOINT = "https://api.sgroup.qq.com/v2/groups/{target}/messages";
+const replaceTargetPlaceholder = (endpoint, target) => endpoint.replace(/\{target\}/g, encodeURIComponent(target.id));
+export const buildSendBody = (_target, text) => ({
+    content: text,
+    msg_type: 0,
+});
+export const buildSendRequest = (endpoint, token, target, text) => {
+    const url = replaceTargetPlaceholder(endpoint, target);
+    const headers = { "content-type": "application/json" };
+    headers["Authorization"] = `Bot ${token}`;
+    return {
+        url,
+        init: {
+            method: "POST",
+            headers,
+            body: JSON.stringify(buildSendBody(target, text)),
+        },
+    };
+};
+export const createQqBotChannel = (config) => {
+    const endpoint = config.endpoint ?? DEFAULT_QQBOT_ENDPOINT;
+    const sendImpl = async (args) => {
+        const text = extractMessageText(args.message);
+        const { url, init } = buildSendRequest(endpoint, config.token, args.target, text);
+        const res = await args.fetch(url, init);
+        let messageId;
+        try {
+            const body = (await res.json());
+            messageId = body.id ?? body.messageId ?? body.ts;
+        }
+        catch {
+            // Some channels return text/204 — that's fine.
+        }
+        return messageId !== undefined ? { status: res.status, messageId } : { status: res.status };
+    };
+    return createRestChannelBase({
+        id: "qq-bot",
+        capabilities: config.capabilities ?? TEXT_ONLY_REST_CAPABILITIES,
+        send: sendImpl,
+        ...(config.fetch !== undefined ? { fetch: config.fetch } : {}),
+    });
+};
+//# sourceMappingURL=channel.js.map

package/dist/channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.js","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,2BAA2B,EAC3B,qBAAqB,EACrB,kBAAkB,GAMnB,MAAM,wBAAwB,CAAC;AAyBhC,MAAM,CAAC,MAAM,sBAAsB,GAAG,uDAAuD,CAAC;AAE9F,MAAM,wBAAwB,GAAG,CAAC,QAAgB,EAAE,MAAqB,EAAU,EAAE,CACnF,QAAQ,CAAC,OAAO,CAAC,aAAa,EAAE,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;AAEjE,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,OAAsB,EAAE,IAAY,EAA2B,EAAE,CAAC,CAAC;IAC/F,OAAO,EAAE,IAAI;IACb,QAAQ,EAAE,CAAC;CACZ,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,QAAgB,EAChB,KAAa,EACb,MAAqB,EACrB,IAAY,EACwB,EAAE;IACtC,MAAM,GAAG,GAAG,wBAAwB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACvD,MAAM,OAAO,GAA2B,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC;IAC/E,OAAO,CAAC,eAAe,CAAC,GAAG,OAAO,KAAK,EAAE,CAAC;IAE1C,OAAO;QACL,GAAG;QACH,IAAI,EAAE;YACJ,MAAM,EAAE,MAAM;YACd,OAAO;YACP,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;SAClD;KACF,CAAC;AACJ,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,MAA0B,EAAW,EAAE;IACxE,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAI,sBAAsB,CAAC;IAC3D,MAAM,QAAQ,GAAG,KAAK,EAAE,IAAkB,EAA2B,EAAE;QACrE,MAAM,IAAI,GAAG,kBAAkB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC9C,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,gBAAgB,CAAC,QAAQ,EAAE,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAClF,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACxC,IAAI,SAA6B,CAAC;QAClC,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAqD,CAAC;YACpF,SAAS,GAAG,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,EAAE,CAAC;QACnD,CAAC;QAAC,MAAM,CAAC;YACP,+CAA+C;QACjD,CAAC;QACD,OAAO,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;IAC9F,CAAC,CAAC;IACF,OAAO,qBAAqB,CAAC;QAC3B,EAAE,EAAE,QAAQ;QACZ,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,2BAA2B;QAChE,IAAI,EAAE,QAAQ;QACd,GAAG,CAAC,MAAM,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC/D,CAAC,CAAC;AACL,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./channel.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from "./channel.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC"}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@nubemclaw/channel-qq-bot",
+  "version": "2.0.0",
+  "description": "NubemClaw v3 — QQ Bot channel (F31.b). QQ Bot OpenAPI.",
+  "license": "UNLICENSED",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "zod": "^3.23.8",
+    "@nubemclaw/channel-sdk": "2.0.0",
+    "@nubemclaw/core": "2.0.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean && rm -rf dist .cache"
+  }
+}

package/src/channel.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  createQqBotChannel,
+  buildSendBody,
+  buildSendRequest,
+  DEFAULT_QQBOT_ENDPOINT,
+} from "./channel.js";
+import type { ChannelDeps } from "@nubemclaw/channel-sdk";
+
+const fakeDeps = (): ChannelDeps => ({
+  logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() },
+  state: { get: async () => undefined, set: async () => {}, delete: async () => {} },
+  allowlist: { allows: () => true, size: 0 },
+  onInbound: async () => {},
+});
+
+describe("createQqBotChannel", () => {
+  it("exposes a working Channel with id qq-bot", () => {
+    const ch = createQqBotChannel({ token: "t" });
+    expect(ch.id).toBe("qq-bot");
+    expect(ch.capabilities.mediaTypes).toContain("text");
+  });
+
+  it("DEFAULT endpoint constant is the canonical provider URL", () => {
+    expect(DEFAULT_QQBOT_ENDPOINT).toContain("api.sgroup.qq.com");
+  });
+
+  it("buildSendBody returns the provider-real body shape (audit-1 finding 1)", () => {
+    const body = buildSendBody({ kind: "chat", id: "target-1" }, "hello") as Record<
+      string,
+      unknown
+    > & {
+      chatId?: unknown;
+      content?: unknown;
+      channel?: unknown;
+      text?: unknown;
+      to?: unknown;
+      messages?: unknown;
+      msgtype?: unknown;
+      body?: unknown;
+      message?: unknown;
+      messaging_product?: unknown;
+      receive_id?: unknown;
+      msg_type?: unknown;
+      msgType?: unknown;
+      ship?: unknown;
+      app?: unknown;
+      recipient?: unknown;
+      conversation_id?: unknown;
+      payload?: unknown;
+      touser?: unknown;
+      number?: unknown;
+      recipients?: unknown;
+      type?: unknown;
+      broadcaster_id?: unknown;
+      sender_id?: unknown;
+      json?: unknown;
+      content_type?: unknown;
+      agentid?: unknown;
+      chatGuid?: unknown;
+      method?: unknown;
+    };
+    expect(body.content).toBe("hello");
+    expect(body.msg_type).toBe(0);
+  });
+
+  it("send() POSTs to the channel endpoint with token-bound auth", async () => {
+    const fetchSpy = vi.fn(
+      async () =>
+        new Response("{}", { status: 200, headers: { "content-type": "application/json" } }),
+    );
+    const ch = createQqBotChannel({ token: "tok-1", fetch: fetchSpy as unknown as typeof fetch });
+    await ch.init(fakeDeps());
+    await ch.send({ kind: "chat", id: "target-1" }, { type: "text", text: "hello" });
+    expect(fetchSpy).toHaveBeenCalledOnce();
+    const call = fetchSpy.mock.calls.at(0);
+    const init = call?.[1] as RequestInit | undefined;
+    expect(init?.method).toBe("POST");
+    const body = JSON.parse((init?.body ?? "{}") as string) as Record<string, unknown> & {
+      chatId?: unknown;
+      content?: unknown;
+      channel?: unknown;
+      text?: unknown;
+      to?: unknown;
+      messages?: unknown;
+      msgtype?: unknown;
+      body?: unknown;
+      message?: unknown;
+      messaging_product?: unknown;
+      receive_id?: unknown;
+      msg_type?: unknown;
+      msgType?: unknown;
+      ship?: unknown;
+      app?: unknown;
+      recipient?: unknown;
+      conversation_id?: unknown;
+      payload?: unknown;
+      touser?: unknown;
+      number?: unknown;
+      recipients?: unknown;
+      type?: unknown;
+      broadcaster_id?: unknown;
+      sender_id?: unknown;
+      json?: unknown;
+      content_type?: unknown;
+      agentid?: unknown;
+      chatGuid?: unknown;
+      method?: unknown;
+    };
+    expect(body.content).toBe("hello");
+    expect(body.msg_type).toBe(0);
+  });
+
+  it("send() throws on non-2xx response", async () => {
+    const fetchSpy = vi.fn(async () => new Response("server error", { status: 500 }));
+    const ch = createQqBotChannel({ token: "tok", fetch: fetchSpy as unknown as typeof fetch });
+    await ch.init(fakeDeps());
+    await expect(ch.send({ kind: "chat", id: "x" }, { type: "text", text: "msg" })).rejects.toThrow(
+      /qq-bot send failed with status 500/,
+    );
+  });
+
+  it("buildSendRequest substitutes {target} placeholders when present", () => {
+    const out = buildSendRequest(
+      "https://api.example/{target}/send",
+      "tok",
+      { kind: "chat", id: "abc123" },
+      "hi",
+    );
+    if (DEFAULT_QQBOT_ENDPOINT.includes("{target}")) {
+      expect(out.url).toContain("abc123");
+    }
+    expect(out.init.method).toBe("POST");
+  });
+});

package/src/channel.ts

@@ -0,0 +1,86 @@
+import {
+  TEXT_ONLY_REST_CAPABILITIES,
+  createRestChannelBase,
+  extractMessageText,
+  type Channel,
+  type ChannelTarget,
+  type RestFetch,
+  type RestSendArgs,
+  type RestSendResult,
+} from "@nubemclaw/channel-sdk";
+
+/**
+ * F31.b — QQ Bot channel adapter (F31-fix.1: real provider body shape).
+ *
+ * QQ Bot OpenAPI group messages.
+ *
+ * Endpoint:
+ *   POST https://api.sgroup.qq.com/v2/groups/{target}/messages
+ *   Header: Authorization: Bot <token>
+ *   Body: ({ content: text, msg_type: 0 })
+ *
+ * The package OWNS its lifecycle: it does NOT inherit from a unified
+ * factory across the 21 F31.b adapters. `createRestChannelBase`
+ * (channel-sdk) is a code-reuse helper for the HTTP send path; each
+ * package wires its own auth + body + (future) inbound parser.
+ */
+
+export interface QqBotChannelConfig {
+  readonly token: string;
+  readonly endpoint?: string;
+  readonly fetch?: RestFetch;
+  readonly capabilities?: import("@nubemclaw/channel-sdk").ChannelCapabilities;
+}
+
+export const DEFAULT_QQBOT_ENDPOINT = "https://api.sgroup.qq.com/v2/groups/{target}/messages";
+
+const replaceTargetPlaceholder = (endpoint: string, target: ChannelTarget): string =>
+  endpoint.replace(/\{target\}/g, encodeURIComponent(target.id));
+
+export const buildSendBody = (_target: ChannelTarget, text: string): Record<string, unknown> => ({
+  content: text,
+  msg_type: 0,
+});
+
+export const buildSendRequest = (
+  endpoint: string,
+  token: string,
+  target: ChannelTarget,
+  text: string,
+): { url: string; init: RequestInit } => {
+  const url = replaceTargetPlaceholder(endpoint, target);
+  const headers: Record<string, string> = { "content-type": "application/json" };
+  headers["Authorization"] = `Bot ${token}`;
+
+  return {
+    url,
+    init: {
+      method: "POST",
+      headers,
+      body: JSON.stringify(buildSendBody(target, text)),
+    },
+  };
+};
+
+export const createQqBotChannel = (config: QqBotChannelConfig): Channel => {
+  const endpoint = config.endpoint ?? DEFAULT_QQBOT_ENDPOINT;
+  const sendImpl = async (args: RestSendArgs): Promise<RestSendResult> => {
+    const text = extractMessageText(args.message);
+    const { url, init } = buildSendRequest(endpoint, config.token, args.target, text);
+    const res = await args.fetch(url, init);
+    let messageId: string | undefined;
+    try {
+      const body = (await res.json()) as { id?: string; messageId?: string; ts?: string };
+      messageId = body.id ?? body.messageId ?? body.ts;
+    } catch {
+      // Some channels return text/204 — that's fine.
+    }
+    return messageId !== undefined ? { status: res.status, messageId } : { status: res.status };
+  };
+  return createRestChannelBase({
+    id: "qq-bot",
+    capabilities: config.capabilities ?? TEXT_ONLY_REST_CAPABILITIES,
+    send: sendImpl,
+    ...(config.fetch !== undefined ? { fetch: config.fetch } : {}),
+  });
+};

package/src/index.ts

@@ -0,0 +1 @@
+export * from "./channel.js";