profclaw 0.0.1-beta.1

package/dist/chat/providers/qq/index.js

@@ -0,0 +1,260 @@
+// QQ Bot Provider
+// API base (prod):    https://api.sgroup.qq.com
+// API base (sandbox): https://sandbox.api.sgroup.qq.com
+// Auth: POST /app/getAppAccessToken -> Bearer token | Health: GET /users/@me
+import { z } from 'zod';
+import { logger } from '../../../utils/logger.js';
+// -- CONFIGURATION --
+export const QQAccountConfigSchema = z.object({
+    id: z.string(),
+    name: z.string().optional(),
+    enabled: z.boolean().default(true),
+    isDefault: z.boolean().optional(),
+    provider: z.literal('qq'),
+    appId: z.string().optional(),
+    token: z.string().optional(),
+    secret: z.string().optional(),
+    sandboxMode: z.boolean().optional(),
+});
+// -- METADATA + CAPABILITIES --
+const meta = {
+    id: 'qq',
+    name: 'QQ',
+    description: 'QQ Bot API with channel, group, and DM message support',
+    icon: 'QQ icon',
+    docsUrl: 'https://bot.q.qq.com/wiki/develop/api/',
+    order: 16,
+    color: '#12B7F5',
+};
+const capabilities = {
+    chatTypes: ['direct', 'group', 'channel'],
+    send: true,
+    receive: true,
+    slashCommands: false,
+    interactiveComponents: false,
+    reactions: false,
+    edit: false,
+    delete: false,
+    threads: false,
+    media: true,
+    richBlocks: false,
+    oauth: false,
+    webhooks: true,
+    realtime: false,
+};
+// -- STATE + HELPERS --
+let currentConfig = null;
+let cachedToken = null;
+let tokenExpiresAt = 0;
+function apiBase(config) {
+    return (config ?? currentConfig)?.sandboxMode
+        ? 'https://sandbox.api.sgroup.qq.com'
+        : 'https://api.sgroup.qq.com';
+}
+async function fetchToken(config) {
+    if (!config.appId || !config.secret)
+        return null;
+    try {
+        const res = await fetch(`${apiBase(config)}/app/getAppAccessToken`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ appId: config.appId, clientSecret: config.secret }),
+        });
+        if (!res.ok) {
+            logger.error(`[QQ] fetchToken: HTTP ${res.status}`);
+            return null;
+        }
+        const data = await res.json();
+        cachedToken = data.access_token;
+        tokenExpiresAt = Date.now() + (data.expires_in - 60) * 1000;
+        return cachedToken;
+    }
+    catch (error) {
+        logger.error('[QQ] fetchToken failed:', error instanceof Error ? error : undefined);
+        return null;
+    }
+}
+async function getToken(config) {
+    const cfg = config ?? currentConfig;
+    if (!cfg)
+        return null;
+    if (cachedToken && Date.now() < tokenExpiresAt)
+        return cachedToken;
+    return fetchToken(cfg);
+}
+async function callApi(endpoint, method = 'GET', body, config) {
+    const cfg = config ?? currentConfig;
+    const token = await getToken(cfg);
+    if (!token)
+        return { ok: false, error: 'Could not obtain access token' };
+    const url = `${apiBase(cfg)}${endpoint}`;
+    try {
+        const res = await fetch(url, {
+            method,
+            headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        const text = await res.text();
+        if (!text)
+            return { ok: res.ok, status: res.status };
+        let data;
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            return { ok: res.ok, status: res.status };
+        }
+        if (!res.ok)
+            return { ok: false, status: res.status, error: data.message ?? `HTTP ${res.status}` };
+        return { ok: true, data, status: res.status };
+    }
+    catch (error) {
+        logger.error('[QQ] API call failed:', error instanceof Error ? error : undefined);
+        return { ok: false, error: error instanceof Error ? error.message : 'Unknown error' };
+    }
+}
+// -- AUTH ADAPTER --
+const authAdapter = {
+    getAuthUrl(_state, _scopes) {
+        throw new Error('QQ Bot uses app access tokens, not OAuth. Supply appId and secret in config.');
+    },
+    async exchangeCode(_code) {
+        throw new Error('QQ Bot does not use OAuth authorization codes.');
+    },
+    verifyWebhook(_signature, _timestamp, _body) {
+        // QQ uses Ed25519 signatures. Accept pre-verified payloads for simplicity.
+        return true;
+    },
+};
+// -- OUTBOUND ADAPTER --
+const outboundAdapter = {
+    async send(message) {
+        if (!currentConfig?.appId)
+            return { success: false, error: 'QQ appId not configured' };
+        if (!message.to)
+            return { success: false, error: 'Target ID (to) is required' };
+        const text = message.text ?? '';
+        const chatType = message.chatType;
+        const replyTo = message.replyToId;
+        let endpoint;
+        let body;
+        if (chatType === 'group') {
+            endpoint = `/v2/groups/${message.to}/messages`;
+            body = { content: text, msg_type: 0 };
+        }
+        else if (chatType === 'direct') {
+            endpoint = `/dms/${message.to}/messages`;
+            body = { content: text };
+        }
+        else {
+            endpoint = `/channels/${message.to}/messages`;
+            body = replyTo ? { content: text, msg_id: replyTo } : { content: text };
+        }
+        const result = await callApi(endpoint, 'POST', body);
+        return result.ok
+            ? { success: true, messageId: result.data?.id }
+            : { success: false, error: result.error ?? 'Failed to send message' };
+    },
+};
+// -- INBOUND ADAPTER --
+const inboundAdapter = {
+    parseMessage(payload) {
+        if (!payload || typeof payload !== 'object')
+            return null;
+        const event = payload;
+        if (event.op !== 0 || !event.t || !event.d)
+            return null;
+        const { t, d } = event;
+        const isGroup = t === 'GROUP_AT_MESSAGE_CREATE';
+        const isDirect = t === 'DIRECT_MESSAGE_CREATE' || t === 'C2C_MESSAGE_CREATE';
+        const isChannel = t === 'AT_MESSAGE_CREATE' || t === 'MESSAGE_CREATE';
+        if (!isGroup && !isDirect && !isChannel) {
+            logger.debug(`[QQ] parseMessage: unhandled event type '${t}', skipping`);
+            return null;
+        }
+        const chatType = isDirect ? 'direct' : isGroup ? 'group' : 'channel';
+        const chatId = isGroup
+            ? (d.group_id ?? d.group_openid ?? '')
+            : isDirect
+                ? (d.guild_id ?? d.channel_id ?? '')
+                : (d.channel_id ?? '');
+        return {
+            id: d.id,
+            provider: 'qq',
+            accountId: currentConfig?.id ?? 'default',
+            senderId: d.author.id,
+            senderName: d.author.username,
+            senderUsername: d.author.username,
+            chatType,
+            chatId,
+            chatName: undefined,
+            threadId: undefined,
+            replyToId: undefined,
+            text: d.content ?? '',
+            rawContent: event,
+            timestamp: new Date(),
+            attachments: undefined,
+        };
+    },
+    parseCommand(_payload) { return null; },
+    parseAction(_payload) { return null; },
+    buildCommandResponse(response) {
+        return { content: response.text ?? '', msg_type: 0 };
+    },
+    buildActionResponse(response) {
+        return { content: response.text ?? '', msg_type: 0 };
+    },
+};
+// -- STATUS ADAPTER --
+const statusAdapter = {
+    isConfigured(config) {
+        return !!(config.appId && config.secret);
+    },
+    async checkHealth(config) {
+        if (!config.appId || !config.secret)
+            return { connected: false, error: 'appId and secret are required' };
+        const qqConfig = {
+            id: config.id,
+            name: config.name,
+            enabled: config.enabled ?? true,
+            isDefault: config.isDefault,
+            provider: 'qq',
+            appId: config.appId,
+            token: config.token,
+            secret: config.secret,
+            sandboxMode: config.sandboxMode,
+        };
+        const start = Date.now();
+        const result = await callApi('/users/@me', 'GET', undefined, qqConfig);
+        const latencyMs = Date.now() - start;
+        if (result.ok && result.data) {
+            return {
+                connected: true, latencyMs,
+                details: { id: result.data.id, username: result.data.username, bot: result.data.bot, sandboxMode: config.sandboxMode ?? false },
+            };
+        }
+        return { connected: false, latencyMs, error: result.error ?? 'Failed to connect to QQ Bot API' };
+    },
+};
+// -- CONFIG MANAGEMENT + EXPORT --
+export function setQQConfig(config) {
+    currentConfig = config;
+    cachedToken = null;
+    tokenExpiresAt = 0;
+}
+export function clearQQConfig() {
+    currentConfig = null;
+    cachedToken = null;
+    tokenExpiresAt = 0;
+}
+export const qqProvider = {
+    meta,
+    capabilities,
+    defaultConfig: { provider: 'qq', enabled: true },
+    configSchema: QQAccountConfigSchema,
+    auth: authAdapter,
+    outbound: outboundAdapter,
+    inbound: inboundAdapter,
+    status: statusAdapter,
+};
+//# sourceMappingURL=index.js.map

package/dist/chat/providers/registry.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Chat Provider Registry
+ *
+ * Central registry for all chat providers.
+ * Handles provider registration, lookup, and capability queries.
+ */
+import type { ChatProvider, ChatProviderId, ChatProviderCapabilities, ProviderRegistry, ChatAccountConfig, ChatEvent, ChatEventHandler } from './types.js';
+declare class ChatProviderRegistry implements ProviderRegistry {
+    private providers;
+    private accounts;
+    private eventHandlers;
+    /**
+     * Register a chat provider
+     */
+    register(provider: ChatProvider): void;
+    /**
+     * Unregister a provider
+     */
+    unregister(id: ChatProviderId): boolean;
+    /**
+     * Get provider by ID
+     */
+    get(id: ChatProviderId): ChatProvider | undefined;
+    /**
+     * List all registered providers
+     */
+    list(): ChatProvider[];
+    /**
+     * Get providers with specific capability
+     */
+    withCapability(capability: keyof ChatProviderCapabilities): ChatProvider[];
+    /**
+     * Check if a provider is registered
+     */
+    has(id: ChatProviderId): boolean;
+    /**
+     * Register an account configuration
+     */
+    registerAccount(config: ChatAccountConfig): void;
+    /**
+     * Get account configuration
+     */
+    getAccount(providerId: ChatProviderId, accountId: string): ChatAccountConfig | undefined;
+    /**
+     * Get default account for a provider
+     */
+    getDefaultAccount(providerId: ChatProviderId): ChatAccountConfig | undefined;
+    /**
+     * List accounts for a provider
+     */
+    listAccounts(providerId?: ChatProviderId): ChatAccountConfig[];
+    /**
+     * Remove an account
+     */
+    removeAccount(providerId: ChatProviderId, accountId: string): boolean;
+    /**
+     * Subscribe to events
+     */
+    on(eventType: string, handler: ChatEventHandler): () => void;
+    /**
+     * Emit an event
+     */
+    emit(event: ChatEvent): Promise<void>;
+    /**
+     * Get status summary of all providers and accounts
+     */
+    getStatus(): Promise<{
+        providers: Array<{
+            id: ChatProviderId;
+            name: string;
+            registered: boolean;
+            accounts: Array<{
+                id: string;
+                name?: string;
+                enabled: boolean;
+                configured: boolean;
+                connected: boolean;
+                error?: string;
+            }>;
+        }>;
+    }>;
+}
+export declare function getChatRegistry(): ChatProviderRegistry;
+/**
+ * Reset registry (for testing)
+ */
+export declare function resetChatRegistry(): void;
+export { ChatProviderRegistry };
+//# sourceMappingURL=registry.d.ts.map

package/dist/chat/providers/registry.js

@@ -0,0 +1,213 @@
+/**
+ * Chat Provider Registry
+ *
+ * Central registry for all chat providers.
+ * Handles provider registration, lookup, and capability queries.
+ */
+import { logger } from '../../utils/logger.js';
+// REGISTRY IMPLEMENTATION
+class ChatProviderRegistry {
+    providers = new Map();
+    accounts = new Map();
+    eventHandlers = new Map();
+    /**
+     * Register a chat provider
+     */
+    register(provider) {
+        if (this.providers.has(provider.meta.id)) {
+            logger.warn(`[ChatRegistry] Provider ${provider.meta.id} already registered, overwriting`);
+        }
+        this.providers.set(provider.meta.id, provider);
+        logger.info(`[ChatRegistry] Registered provider: ${provider.meta.name}`, {
+            id: provider.meta.id,
+            capabilities: Object.entries(provider.capabilities)
+                .filter(([, v]) => v === true || (Array.isArray(v) && v.length > 0))
+                .map(([k]) => k),
+        });
+    }
+    /**
+     * Unregister a provider
+     */
+    unregister(id) {
+        const removed = this.providers.delete(id);
+        if (removed) {
+            logger.info(`[ChatRegistry] Unregistered provider: ${id}`);
+        }
+        return removed;
+    }
+    /**
+     * Get provider by ID
+     */
+    get(id) {
+        return this.providers.get(id);
+    }
+    /**
+     * List all registered providers
+     */
+    list() {
+        return Array.from(this.providers.values()).sort((a, b) => a.meta.order - b.meta.order);
+    }
+    /**
+     * Get providers with specific capability
+     */
+    withCapability(capability) {
+        return this.list().filter((p) => {
+            const value = p.capabilities[capability];
+            return value === true || (Array.isArray(value) && value.length > 0);
+        });
+    }
+    /**
+     * Check if a provider is registered
+     */
+    has(id) {
+        return this.providers.has(id);
+    }
+    // ACCOUNT MANAGEMENT
+    /**
+     * Register an account configuration
+     */
+    registerAccount(config) {
+        const key = `${config.provider}:${config.id}`;
+        this.accounts.set(key, config);
+        logger.debug(`[ChatRegistry] Registered account: ${key}`, { name: config.name });
+    }
+    /**
+     * Get account configuration
+     */
+    getAccount(providerId, accountId) {
+        return this.accounts.get(`${providerId}:${accountId}`);
+    }
+    /**
+     * Get default account for a provider
+     */
+    getDefaultAccount(providerId) {
+        for (const [key, config] of this.accounts) {
+            if (key.startsWith(`${providerId}:`) && config.isDefault) {
+                return config;
+            }
+        }
+        // Return first account if no default set
+        for (const [key, config] of this.accounts) {
+            if (key.startsWith(`${providerId}:`)) {
+                return config;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * List accounts for a provider
+     */
+    listAccounts(providerId) {
+        const result = [];
+        for (const [key, config] of this.accounts) {
+            if (!providerId || key.startsWith(`${providerId}:`)) {
+                result.push(config);
+            }
+        }
+        return result;
+    }
+    /**
+     * Remove an account
+     */
+    removeAccount(providerId, accountId) {
+        return this.accounts.delete(`${providerId}:${accountId}`);
+    }
+    // EVENT HANDLING
+    /**
+     * Subscribe to events
+     */
+    on(eventType, handler) {
+        if (!this.eventHandlers.has(eventType)) {
+            this.eventHandlers.set(eventType, new Set());
+        }
+        this.eventHandlers.get(eventType).add(handler);
+        // Return unsubscribe function
+        return () => {
+            this.eventHandlers.get(eventType)?.delete(handler);
+        };
+    }
+    /**
+     * Emit an event
+     */
+    async emit(event) {
+        const handlers = this.eventHandlers.get(event.type);
+        if (!handlers || handlers.size === 0) {
+            return;
+        }
+        const account = this.getAccount(event.provider, event.accountId);
+        const context = {
+            provider: event.provider,
+            accountId: event.accountId,
+            config: account,
+        };
+        const promises = [];
+        for (const handler of handlers) {
+            promises.push(handler(event, context).catch((error) => {
+                logger.error(`[ChatRegistry] Event handler error`, {
+                    eventType: event.type,
+                    provider: event.provider,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }));
+        }
+        await Promise.all(promises);
+    }
+    // UTILITY METHODS
+    /**
+     * Get status summary of all providers and accounts
+     */
+    async getStatus() {
+        const result = { providers: [] };
+        for (const provider of this.list()) {
+            const providerStatus = {
+                id: provider.meta.id,
+                name: provider.meta.name,
+                registered: true,
+                accounts: [],
+            };
+            const accounts = this.listAccounts(provider.meta.id);
+            for (const account of accounts) {
+                const configured = provider.status.isConfigured(account);
+                let connected = false;
+                let error;
+                if (configured && account.enabled) {
+                    try {
+                        const health = await provider.status.checkHealth(account);
+                        connected = health.connected;
+                        error = health.error;
+                    }
+                    catch (e) {
+                        error = e instanceof Error ? e.message : String(e);
+                    }
+                }
+                providerStatus.accounts.push({
+                    id: account.id,
+                    name: account.name,
+                    enabled: account.enabled ?? true,
+                    configured,
+                    connected,
+                    error,
+                });
+            }
+            result.providers.push(providerStatus);
+        }
+        return result;
+    }
+}
+// SINGLETON INSTANCE
+let _registry = null;
+export function getChatRegistry() {
+    if (!_registry) {
+        _registry = new ChatProviderRegistry();
+    }
+    return _registry;
+}
+/**
+ * Reset registry (for testing)
+ */
+export function resetChatRegistry() {
+    _registry = null;
+}
+// EXPORTS
+export { ChatProviderRegistry };
+//# sourceMappingURL=registry.js.map

package/dist/chat/providers/signal/index.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Signal Provider - Full Implementation
+ *
+ * Signal integration via signald bridge:
+ * - signald exposes an HTTP API at localhost:15432 (configurable)
+ * - No OAuth; authentication is phone-number based
+ * - Supports direct messages and group chats
+ * - Supports media attachments
+ * - Does NOT support: threads, message editing, rich blocks, reactions,
+ *   slash commands, or interactive components
+ *
+ * Signald HTTP API base: http://localhost:15432
+ * Signald docs: https://signald.org/articles/
+ *
+ * Security level: moderate (phone number based allowlist)
+ */
+import { z } from 'zod';
+import type { ChatProvider, SignalAccountConfig } from '../types.js';
+/** Signald message data shape as received in webhook payloads */
+interface SignaldDataMessage {
+    timestamp?: number;
+    message?: string;
+    groupInfo?: {
+        groupId?: string;
+        name?: string;
+        type?: string;
+    };
+    attachments?: SignaldAttachment[];
+}
+interface SignaldAttachment {
+    contentType?: string;
+    id?: string;
+    size?: number;
+    filename?: string;
+    storedFilename?: string;
+    width?: number;
+    height?: number;
+}
+/** Top-level signald inbound envelope shape */
+interface SignaldEnvelope {
+    type?: string;
+    source?: string;
+    sourceDevice?: number;
+    timestamp?: number;
+    serverTimestamp?: number;
+    dataMessage?: SignaldDataMessage;
+    syncMessage?: unknown;
+    callMessage?: unknown;
+}
+/** Signald webhook payload (wraps envelope) */
+interface SignaldWebhookPayload {
+    account?: string;
+    envelope?: SignaldEnvelope;
+}
+export declare const SignalAccountConfigSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    isDefault: z.ZodOptional<z.ZodBoolean>;
+    provider: z.ZodLiteral<"signal">;
+    signaldSocketPath: z.ZodOptional<z.ZodString>;
+    phoneNumber: z.ZodOptional<z.ZodString>;
+    allowedNumbers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    provider: "signal";
+    enabled: boolean;
+    name?: string | undefined;
+    isDefault?: boolean | undefined;
+    phoneNumber?: string | undefined;
+    signaldSocketPath?: string | undefined;
+    allowedNumbers?: string[] | undefined;
+}, {
+    id: string;
+    provider: "signal";
+    name?: string | undefined;
+    isDefault?: boolean | undefined;
+    enabled?: boolean | undefined;
+    phoneNumber?: string | undefined;
+    signaldSocketPath?: string | undefined;
+    allowedNumbers?: string[] | undefined;
+}>;
+type SignalConfig = z.infer<typeof SignalAccountConfigSchema>;
+export declare function setSignalConfig(config: SignalConfig): void;
+export declare function clearSignalConfig(): void;
+export declare const signalProvider: ChatProvider<SignalAccountConfig>;
+export type { SignalConfig, SignaldEnvelope, SignaldDataMessage, SignaldWebhookPayload };
+//# sourceMappingURL=index.d.ts.map