dsh-qqbot 1.0.0

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-qqbot`.
+* @module @deepseek-ai/dsh-qqbot/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-qqbot";
+/** Cordis companion plugin name. */
+const name = "qqbot-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this transport bridge owns no durable package-local
+* event stream; protocol and bridge lifecycle tests cover its mapping.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/client/QqbotSettingsSection.d.ts

@@ -0,0 +1,12 @@
+import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { QqbotSettingsInjected } from './index.ts';
+/** Full settings.section component props: runtime share + injected share + the locale seat. */
+export type QqbotSettingsSectionProps = PropsRuntime<'settings.section'> & InjectFace<QqbotSettingsInjected> & PropsLocale<'qqbot'>;
+/**
+ * The QQ Bot settings page: AppID, AppSecret, and sandbox fields over the
+ * Host's redacted namespace view. The AppSecret is write-only on the wire, so
+ * the field renders blank and "keep unchanged" is the empty-value meaning;
+ * the clear button removes a stored secret. Saving applies every changed
+ * field in one ordered write, and the Host restarts a live gateway in place.
+ */
+export declare function QqbotSettingsSection({ useQqbotSettings, useQqbotBound, save, t }: QqbotSettingsSectionProps): import("react").JSX.Element;

package/lib/types/client/QqbotToggle.d.ts

@@ -0,0 +1,10 @@
+import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { QqbotToggleInjected } from './index.ts';
+/** Full input-left seat component props: runtime share & injected share & the locale seat. */
+export type QqbotToggleProps = PropsRuntime<'conversation.input.left'> & InjectFace<QqbotToggleInjected> & PropsLocale<'qqbot'>;
+/**
+ * Per-session QQ connection toggle over the shared bound-session observable.
+ * It reports the host's last admitted bind: `active` is the single bound
+ * session, not optimistic click state, so switching sessions shows the truth.
+ */
+export declare function QqbotToggle({ sessionId, useQqbotBound, toggle, t }: QqbotToggleProps): import("react").JSX.Element;

package/lib/types/client/index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * QQ bot plugin, browser half: occupies the composer tool row's always-visible
+ * `conversation.input.left` seat with a per-session connection toggle, and
+ * registers the QQ Bot page into the settings panel's `settings.section`
+ * navigation. The bound-session id and the settings namespace view are shared
+ * bare observables held in the inject faces' `hooks` compartments (the
+ * renderer binds them to `useQqbotBound`/`useQqbotSettings`); toggling
+ * executes /qqbot on | off against the addressed session through
+ * `remote.commands`, and settings edits write through the Host's settings
+ * wire face.
+ */
+import { type SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client';
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+import { type QqbotSettingsPatch, type QqbotSettingsState } from './settings-controller.ts';
+import { type QqbotKey } from './locales.ts';
+export type { QqbotSettingsPatch, QqbotSettingsState } from './settings-controller.ts';
+export type { QqbotKey } from './locales.ts';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** The connection toggle's and settings page's copy. */
+        qqbot: QqbotKey;
+    }
+}
+/** Shared bound-session state: the id of the session currently bridged to QQ. */
+export interface QqbotBoundState {
+    readonly sessionId: string | null;
+}
+/** Injected business face of the input-left seat. */
+export interface QqbotToggleInjected {
+    /** Reserved observable compartment; binds to `useQqbotBound` on the component. */
+    hooks: {
+        qqbotBound: SnapshotStore<QqbotBoundState>;
+    };
+    /**
+     * Connect (if idle) or disconnect (if this session is bound) via /qqbot.
+     * @returns null on admitted execution; a user-visible failure line otherwise.
+     */
+    toggle: () => Promise<string | null>;
+}
+/** Injected business face of the settings section seat. */
+export interface QqbotSettingsInjected {
+    /** Reserved observable compartments; bind to `useQqbotSettings`/`useQqbotBound`. */
+    hooks: {
+        qqbotSettings: SnapshotStore<QqbotSettingsState>;
+        qqbotBound: SnapshotStore<QqbotBoundState>;
+    };
+    /**
+     * Apply one user edit to the qqbot settings namespace.
+     * @returns null on success; the Host's failure text otherwise.
+     */
+    save: (patch: QqbotSettingsPatch) => Promise<string | null>;
+}
+/** Required services: the seats' slot registry, connection and commands remotes, and locale. */
+export declare const inject: string[];
+/**
+ * Client plugin body: register the connection toggle over the command channel
+ * and the QQ Bot settings page over the settings wire face.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: ClientContext): void;

package/lib/types/client/locales.d.ts

@@ -0,0 +1,63 @@
+/** `qqbot` namespace dictionaries (the composer toggle's and settings page's copy). */
+/** Simplified Chinese dictionary (the key-set source of truth). */
+export declare const zh: {
+    'toggle.on.aria': string;
+    'toggle.on.title': string;
+    'toggle.on.label': string;
+    'toggle.off.aria': string;
+    'toggle.off.title': string;
+    'toggle.off.label': string;
+    'settings.nav': string;
+    'settings.title': string;
+    'settings.desc': string;
+    'appId.label': string;
+    'appId.placeholder': string;
+    'appId.hint': string;
+    'appSecret.label': string;
+    'appSecret.placeholder': string;
+    'appSecret.placeholder.set': string;
+    'appSecret.hint': string;
+    'appSecret.hint.set': string;
+    'clear.label': string;
+    'sandbox.label': string;
+    'sandbox.hint': string;
+    'save.label': string;
+    'save.busy': string;
+    'save.ok': string;
+    'bound.prefix': string;
+    'status.loading': string;
+    'status.error': string;
+    'status.readonly': string;
+};
+/** The qqbot namespace key union. */
+export type QqbotKey = keyof typeof zh;
+/** English dictionary, checked complete against the zh key set. */
+export declare const en: {
+    'toggle.on.aria': string;
+    'toggle.on.title': string;
+    'toggle.on.label': string;
+    'toggle.off.aria': string;
+    'toggle.off.title': string;
+    'toggle.off.label': string;
+    'settings.nav': string;
+    'settings.title': string;
+    'settings.desc': string;
+    'appId.label': string;
+    'appId.placeholder': string;
+    'appId.hint': string;
+    'appSecret.label': string;
+    'appSecret.placeholder': string;
+    'appSecret.placeholder.set': string;
+    'appSecret.hint': string;
+    'appSecret.hint.set': string;
+    'clear.label': string;
+    'sandbox.label': string;
+    'sandbox.hint': string;
+    'save.label': string;
+    'save.busy': string;
+    'save.ok': string;
+    'bound.prefix': string;
+    'status.loading': string;
+    'status.error': string;
+    'status.readonly': string;
+};

package/lib/types/client/settings-controller.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Settings-page transport for the qqbot namespace: reads the Host's redacted
+ * settings view and writes user edits as path ops, mirroring the result in a
+ * snapshot store the section renders through. The Host is the single fact
+ * source — every mutation writes through the wire and the page re-renders
+ * from the response view (or a reload after a refusal).
+ */
+import type { IApiClient } from '@deepseek-ai/dsh-api-remotes/client';
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client';
+/** The settings namespace the Host plugin registers its identity under. */
+export declare const QQBOT_SETTINGS_NAMESPACE = "qqbot";
+/** One user edit the section sends: absent fields stay untouched. */
+export interface QqbotSettingsPatch {
+    /** New AppID; an empty string clears the field (re-inherits the base layer). */
+    appId?: string;
+    /** New AppSecret; omitted or empty keeps the stored value. */
+    appSecret?: string;
+    /** New sandbox flag. */
+    sandbox?: boolean;
+    /** Remove the stored AppSecret. */
+    clearSecret?: boolean;
+}
+/** Snapshot state mirrored from the Host's redacted namespace view. */
+export interface QqbotSettingsState {
+    /** `loading` until the first accepted view; `error` after a failed load. */
+    status: 'idle' | 'loading' | 'ready' | 'error';
+    /** Resolved AppID (base layer overridden by the user section); '' when unset. */
+    appId: string;
+    /** Resolved sandbox flag. */
+    sandbox: boolean;
+    /** Whether the user section stores an AppSecret (the value never rides the wire). */
+    secretSet: boolean;
+    /** Whether the Host settings document accepts writes. */
+    writable: boolean;
+    /** Namespace revision the next write fences against. */
+    revision: number | undefined;
+    /** Human failure text of the latest load or save; null while healthy. */
+    error: string | null;
+}
+/**
+ * Serializes the qqbot namespace's Host reads and writes behind one snapshot
+ * store. Latest load wins; a refused save reloads the namespace so the form
+ * re-renders from the fresh view and the user can re-apply the edit.
+ */
+export declare class QqbotSettingsController {
+    private readonly api;
+    /** uSES-safe state source the section renders through its hooks compartment. */
+    readonly store: SnapshotStore<QqbotSettingsState>;
+    private generation;
+    /**
+     * @param api - the settings wire face.
+     */
+    constructor(api: Pick<IApiClient, 'settings'>);
+    /**
+     * Refresh the snapshot from `settings.describe`; a failure keeps the last
+     * good state and surfaces the error.
+     * @returns settlement after the read.
+     */
+    load(): Promise<void>;
+    /**
+     * Apply one user edit as ordered path ops; a refusal reloads the namespace
+     * and returns its message.
+     * @param patch - the fields the user changed.
+     * @returns null on success; the Host's failure text otherwise.
+     */
+    save(patch: QqbotSettingsPatch): Promise<string | null>;
+    /** Fold one redacted wire view into the snapshot. */
+    private accept;
+}
+/**
+ * Refresh only after the section left idle, so an unopened page never fetches
+ * on background invalidations.
+ * @param controller - the page controller whose current status gates the reload.
+ */
+export declare function refreshIfLoaded(controller: QqbotSettingsController): void;

package/lib/types/gateway.d.ts

@@ -0,0 +1,96 @@
+/**
+ * QQ official bot gateway client: token refresh, WebSocket connection,
+ * heartbeat, reconnect, inbound dispatch, and outbound message sending.
+ * The socket and fetch implementations are injectable so tests can drive the
+ * state machine without a live platform.
+ * @module @deepseek-ai/dsh-qqbot/gateway
+ */
+import type { FetchLike, QqCredentials, QqMessage } from './types.ts';
+/** Minimal logger surface the gateway uses; `ctx.logger` satisfies it. */
+export interface QqGatewayLogger {
+    warn(message: string): void;
+    info?(message: string): void;
+    debug?(message: string): void;
+}
+/** The WebSocket handle surface the gateway drives. */
+export interface QqSocketLike {
+    onopen: (() => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onclose: ((event: {
+        code?: number;
+    }) => void) | null;
+    onerror: ((error: unknown) => void) | null;
+    send(data: string): void;
+    close(code?: number): void;
+}
+/** Construction options; every field beyond creds has a production default. */
+export interface QqGatewayOptions {
+    readonly creds: QqCredentials;
+    readonly sandbox: boolean;
+    readonly onMessage: (message: QqMessage) => void;
+    readonly logger?: QqGatewayLogger;
+    readonly fetchImpl?: FetchLike;
+    readonly socketFactory?: (url: string) => QqSocketLike;
+    /** Minimum refresh margin before a token is considered expired (ms). */
+    readonly tokenMarginMs?: number;
+    /** Maximum reconnect backoff (ms). */
+    readonly maxReconnectDelayMs?: number;
+    /** Epoch-ms clock, for token-expiry and backoff tests. */
+    readonly now?: () => number;
+}
+/**
+ * Long-lived connection to the QQ gateway. `start()` connects once; a drop
+ * after READY schedules an exponential-backoff reconnect. The client owns the
+ * access token and exposes {@link sendText} for reply delivery.
+ */
+export declare class QqGatewayClient {
+    private readonly creds;
+    private readonly sandbox;
+    private readonly onMessage;
+    private readonly logger;
+    private readonly fetchImpl;
+    private readonly socketFactory;
+    private readonly tokenMarginMs;
+    private readonly maxReconnectDelayMs;
+    private readonly now;
+    private accessToken;
+    private tokenExpiresAt;
+    private socket;
+    private heartbeatTimer;
+    private reconnectTimer;
+    private seq;
+    private reconnectAttempts;
+    private closed;
+    constructor(options: QqGatewayOptions);
+    /**
+     * Return a usable access token, refreshing it when absent or near expiry.
+     * @returns the current access token.
+     */
+    ensureToken(): Promise<string>;
+    /** Connect (and, on a later drop, reconnect) to the gateway. */
+    start(): Promise<void>;
+    /**
+     * Permanently close the client: stop timers, cancel reconnects, and close
+     * the live socket. Idempotent.
+     */
+    close(): void;
+    /**
+     * Deliver one reply to a chat. Chunks the text to the platform limit and
+     * posts each chunk with the triggering message id threaded as a reply.
+     * @param path - the REST path from {@link groupMessagesPath} or {@link c2cMessagesPath}.
+     * @param text - the reply text.
+     * @param msgId - the inbound message id being answered.
+     */
+    sendText(path: string, text: string, msgId: string): Promise<void>;
+    /** Mint a token, resolve the gateway URL, and complete one socket session. */
+    private connectOnce;
+    /** Open the socket and resolve once READY (or RESUME) arrives. */
+    private openSocket;
+    /** Start the heartbeat interval, replacing any previous one. */
+    private startHeartbeat;
+    private stopHeartbeat;
+    /** Schedule one reconnect attempt with exponential backoff. */
+    private scheduleReconnect;
+}

package/lib/types/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * QQ official bot bridge for DeepSeek Harness.
+ *
+ * Answers @-mentions in group chat and private C2C messages by routing them
+ * into one harness session the user selects from the conversation window. The
+ * `/qqbot on` command binds the dispatching agent (its context and cwd) to the
+ * QQ gateway; `/qqbot off` disconnects. Nothing connects until a session opts
+ * in, and QQ messages then arrive as ordinary user messages on that agent.
+ *
+ * The robot identity (AppID/AppSecret) lives in the `qqbot` settings section —
+ * the Settings → QQ Bot page of the web GUI — with the composition entry as
+ * the base layer and `QQBOT_APP_ID`/`QQBOT_APP_SECRET` as an environment
+ * fallback. Committed settings changes restart a live gateway in place.
+ *
+ * The bridge is also an approval answerer for its bound agent: a tool call that
+ * asks for confirmation is forwarded to the originating QQ chat as a prompt,
+ * and the user's "允许" / "拒绝" reply settles the request.
+ *
+ * @module dsh-qqbot
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import Schema from '@deepseek-ai/schemastery';
+import type { ApprovalOutcome } from '@deepseek-ai/dsh-user-approval';
+import type { QqbotConfig } from './types.ts';
+export type { QqbotConfig } from './types.ts';
+export declare const name = "qqbot";
+/** The bridge binds the session's existing agent; commands and session events drive it. */
+export declare const inject: string[];
+/** Plugin config: robot identity plus the API environment selection. */
+export declare const Config: Schema<QqbotConfig>;
+/** Environment variable fallback for the robot application id. */
+export declare const QQBOT_APP_ID_ENV = "QQBOT_APP_ID";
+/** Environment variable fallback for the robot application secret. */
+export declare const QQBOT_APP_SECRET_ENV = "QQBOT_APP_SECRET";
+/** Settings namespace carrying the robot identity (Settings → QQ Bot). */
+export declare const QQBOT_SETTINGS_NAMESPACE: import("@deepseek-ai/dsh-settings").SettingsNamespace;
+/** Prompt section name registered on the bound agent's scope. */
+export declare const QQBOT_CHANNEL_SECTION = "qqbot:channel";
+/** Prompt section order: after the persona, before tool guidance. */
+export declare const QQBOT_CHANNEL_ORDER = 10;
+/**
+ * The QQ-channel instructions, registered verbatim on the bound agent while a
+ * session is connected. Kept as a literal export so the README and tests quote
+ * the exact text.
+ */
+export declare const QQBOT_CHANNEL_PROMPT: string;
+/**
+ * Parse an inbound QQ reply into an approval decision, or leave it undefined
+ * when it is not an answer. Matches the whole normalized text, then its first
+ * whitespace/punctuation-delimited token ("允许。" → allow, "同意 执行" → allow).
+ * @param text - the raw inbound message content.
+ * @returns the decision, or undefined when the text is not an answer.
+ */
+export declare function parseAnswer(text: string): ApprovalOutcome | undefined;
+/**
+ * Mount the QQ bot bridge. It registers the `/qqbot` command and connects the
+ * gateway only when a session runs `/qqbot on`; the bound agent's own scope,
+ * history, and cwd are reused unchanged. While bound, it also answers that
+ * agent's approval requests through the originating QQ chat.
+ * @param ctx - Cordis context carrying the agent registry, commands, and session events.
+ * @param config - composition entry; the user layer of the `qqbot` settings
+ *   namespace resolves over it once a settings provider is mounted.
+ */
+export declare function apply(ctx: Context, config: QqbotConfig): void;

package/lib/types/invariant.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-qqbot`.
+ * @module @deepseek-ai/dsh-qqbot/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "qqbot-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;

package/lib/types/protocol.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Pure QQ official bot protocol helpers: gateway opcodes, event intents,
+ * REST endpoints, access-token and gateway URL fetches, inbound dispatch
+ * parsing, and outbound text chunking. Everything here is I/O- and timer-free
+ * except the two `fetch` wrappers, so the rest is unit-testable directly.
+ * @module @deepseek-ai/dsh-qqbot/protocol
+ */
+import type { FetchLike, QqAccessToken, QqCredentials, QqMessage } from './types.ts';
+/** Gateway opcodes from the QQ official bot WebSocket protocol. */
+export declare const QQ_OP: {
+    readonly DISPATCH: 0;
+    readonly HEARTBEAT: 1;
+    readonly IDENTIFY: 2;
+    readonly RESUME: 6;
+    readonly RECONNECT: 7;
+    readonly INVALID_SESSION: 9;
+    readonly HELLO: 10;
+    readonly HEARTBEAT_ACK: 11;
+};
+/**
+ * Intent bit for group @-mention and C2C private-message events. The single
+ * `1 << 25` (`GROUP_AND_C2C_EVENT`) intent delivers both, so the bridge
+ * subscribes to it and nothing else.
+ */
+export declare const QQ_INTENT_GROUP_AND_C2C: number;
+/** Access-token mint endpoint; independent of the sandbox selection. */
+export declare const QQ_TOKEN_URL = "https://bots.qq.com/app/getAppAccessToken";
+/** Default outbound chunk length in UTF-16 code units. */
+export declare const QQ_MAX_MESSAGE_LENGTH = 2000;
+/**
+ * Resolve the REST API base for the selected environment.
+ * @param sandbox - whether the sandbox host is in use.
+ * @returns the `https://api.sgroup.qq.com` or sandbox equivalent origin.
+ */
+export declare function apiBase(sandbox: boolean): string;
+/**
+ * REST path for sending a message to a group.
+ * @param groupOpenid - the target group's openid.
+ * @returns the `/v2/groups/{groupOpenid}/messages` path.
+ */
+export declare function groupMessagesPath(groupOpenid: string): string;
+/**
+ * REST path for sending a private message to a user.
+ * @param userOpenid - the target user's openid.
+ * @returns the `/v2/users/{userOpenid}/messages` path.
+ */
+export declare function c2cMessagesPath(userOpenid: string): string;
+/**
+ * Mint an access token from the robot app id and secret.
+ * @param creds - the robot credentials.
+ * @param fetchImpl - injectable fetch (defaults to the global).
+ * @param now - injectable epoch-ms clock (defaults to `Date.now`).
+ * @returns the token with its absolute expiry.
+ */
+export declare function fetchAccessToken(creds: QqCredentials, fetchImpl?: FetchLike, now?: () => number): Promise<QqAccessToken>;
+/**
+ * Resolve the WebSocket gateway URL for the selected environment.
+ * @param accessToken - the current access token.
+ * @param sandbox - whether the sandbox host is in use.
+ * @param fetchImpl - injectable fetch (defaults to the global).
+ * @returns the gateway WebSocket URL.
+ */
+export declare function fetchGatewayUrl(accessToken: string, sandbox: boolean, fetchImpl?: FetchLike): Promise<string>;
+/** Raw shape extracted from one WebSocket text frame. */
+export interface RawGatewayMessage {
+    readonly op: number;
+    readonly type?: string;
+    readonly seq?: number;
+    readonly data?: unknown;
+    readonly heartbeatInterval?: number;
+}
+/**
+ * Parse one gateway text frame into its opcode and the fields that op carries.
+ * @param raw - the frame payload (expected to be a JSON string).
+ * @returns the parsed message, or `undefined` for non-text or malformed frames.
+ */
+export declare function parseRawGatewayMessage(raw: unknown): RawGatewayMessage | undefined;
+/**
+ * Narrow a dispatch event to an answerable {@link QqMessage}. Group events
+ * require a `group_openid`; C2C events require an `author.user_openid`. Other
+ * event types (READY, RESUMED, and every non-message event) return `undefined`.
+ * @param type - the dispatch event type (`t`).
+ * @param data - the dispatch payload (`d`).
+ * @returns the normalized message, or `undefined` when the event is not answerable.
+ */
+export declare function parseMessageEvent(type: string, data: unknown): QqMessage | undefined;
+/**
+ * Strip QQ mention tags from group message text. The platform may deliver
+ * `<@!12345>` or `<@OPENID>`; both are removed so only the user's words remain.
+ * @param text - the raw group message content.
+ * @returns the text with mentions removed and surrounding whitespace trimmed.
+ */
+export declare function stripMentions(text: string): string;
+/**
+ * Split outbound text into chunks no longer than `max` UTF-16 code units.
+ * An empty input yields no chunks (nothing to send).
+ * @param text - the reply text.
+ * @param max - the per-chunk ceiling.
+ * @returns zero or more bounded chunks.
+ */
+export declare function splitMessage(text: string, max?: number): string[];
+/**
+ * Build the ordered request bodies for one reply. The first chunk carries the
+ * triggering `msg_id` so the platform renders it as a reply; subsequent chunks
+ * share it with an increasing `msg_seq`, streaming the multi-chunk reply.
+ * @param text - the reply text.
+ * @param msgId - the inbound message id being answered, when known.
+ * @returns the ordered request bodies, or an empty array for empty text.
+ */
+export declare function buildSendPayloads(text: string, msgId: string | undefined): Array<Record<string, unknown>>;

package/lib/types/types.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Vocabulary for the QQ official bot bridge: gateway credentials, token state,
+ * inbound message events, and plugin config. Pure types only — no runtime code.
+ * @module @deepseek-ai/dsh-qqbot/types
+ */
+/** QQ official bot credentials used to mint the gateway access token. */
+export interface QqCredentials {
+    /** The robot application id from the QQ open platform. */
+    readonly appId: string;
+    /** The robot application secret; kept out of logs and prompts. */
+    readonly appSecret: string;
+}
+/** A minted access token plus its absolute expiry timestamp (epoch ms). */
+export interface QqAccessToken {
+    readonly accessToken: string;
+    /** Epoch milliseconds at which the token must be refreshed. */
+    readonly expiresAt: number;
+}
+/**
+ * Narrow fetch surface the bridge needs: a URL string plus optional init.
+ * The global `fetch` satisfies it, and tests can supply a plain function
+ * without a lossy `typeof fetch` cast.
+ */
+export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+/** The `author` block shared by group and C2C message events. */
+export interface QqAuthor {
+    /** Sender's platform-scoped numeric id; absent on C2C events. */
+    readonly id?: string;
+    /** Sender openid for C2C events. */
+    readonly userOpenid?: string;
+    /** Member openid within a group; present only on group events. */
+    readonly memberOpenid?: string;
+    /** Display name, when the platform supplies one. */
+    readonly username?: string;
+}
+/**
+ * One inbound message the bridge can answer. The two kinds carry the same
+ * content fields and differ only in who the reply is addressed to: the
+ * sender's `userOpenid` for C2C, or the group `groupOpenid` for group chat.
+ */
+export type QqMessage = {
+    readonly kind: 'c2c';
+    readonly id: string;
+    readonly content: string;
+    readonly author: QqAuthor;
+    readonly userOpenid: string;
+} | {
+    readonly kind: 'group';
+    readonly id: string;
+    readonly content: string;
+    readonly author: QqAuthor;
+    readonly groupOpenid: string;
+};
+/** Plugin config: QQ bot identity plus the API environment selection. */
+export interface QqbotConfig {
+    /** Robot application id; falls back to `QQBOT_APP_ID`. */
+    readonly appId?: string;
+    /** Robot application secret; falls back to `QQBOT_APP_SECRET`. */
+    readonly appSecret?: string;
+    /** Route token, gateway, and sends through the sandbox host. Default false. */
+    readonly sandbox?: boolean;
+}