profclaw 0.0.1-beta.1

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

@@ -0,0 +1,243 @@
+/**
+ * Tlon Provider - Urbit/Tlon messaging via ship HTTP API
+ * Connects to an Urbit ship for decentralized messaging.
+ * API: ship HTTP interface (Eyre)
+ */
+import { z } from 'zod';
+import { logger } from '../../../utils/logger.js';
+// --- Schema ---
+export const TlonAccountConfigSchema = z.object({
+    id: z.string(),
+    name: z.string().optional(),
+    enabled: z.boolean().default(true),
+    isDefault: z.boolean().optional(),
+    provider: z.literal('tlon'),
+    shipUrl: z.string().optional(),
+    shipCode: z.string().optional(),
+    shipName: z.string().optional(),
+    channelPath: z.string().optional(),
+});
+// --- State ---
+let currentConfig = null;
+let sessionCookie = null;
+// --- HTTP helper ---
+async function authenticateShip(config) {
+    if (!config.shipUrl || !config.shipCode)
+        return null;
+    try {
+        const res = await fetch(`${config.shipUrl}/~/login`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: `password=${encodeURIComponent(config.shipCode)}`,
+            redirect: 'manual',
+        });
+        const setCookie = res.headers.get('set-cookie');
+        if (setCookie) {
+            const match = setCookie.match(/urbauth-[^=]+=([^;]+)/);
+            if (match)
+                return match[0];
+        }
+        return null;
+    }
+    catch (error) {
+        logger.error('[Tlon] Authentication failed:', error instanceof Error ? error : undefined);
+        return null;
+    }
+}
+async function callShipApi(endpoint, method = 'GET', body) {
+    const config = currentConfig;
+    if (!config?.shipUrl)
+        return { ok: false, error: 'Ship URL not configured' };
+    if (!sessionCookie) {
+        sessionCookie = await authenticateShip(config);
+        if (!sessionCookie)
+            return { ok: false, error: 'Authentication failed' };
+    }
+    const makeRequest = async (cookie) => fetch(`${config.shipUrl}${endpoint}`, {
+        method,
+        headers: {
+            'Content-Type': 'application/json',
+            'Cookie': cookie,
+        },
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    try {
+        let res = await makeRequest(sessionCookie);
+        if (res.status === 401 || res.status === 403) {
+            sessionCookie = await authenticateShip(config);
+            if (!sessionCookie)
+                return { ok: false, error: 'Re-authentication failed' };
+            res = await makeRequest(sessionCookie);
+        }
+        if (!res.ok)
+            return { ok: false, error: `HTTP ${res.status}` };
+        const data = await res.json();
+        return { ok: true, data };
+    }
+    catch (error) {
+        logger.error('[Tlon] API call failed:', error instanceof Error ? error : undefined);
+        return { ok: false, error: error instanceof Error ? error.message : 'Unknown error' };
+    }
+}
+// --- Adapters ---
+const authAdapter = {
+    getAuthUrl(_state, _scopes) {
+        throw new Error('Tlon uses ship +code authentication. Get your code with +code in Dojo.');
+    },
+    async exchangeCode(_code) {
+        throw new Error('Tlon does not use OAuth. Configure shipUrl and shipCode.');
+    },
+    verifyWebhook(_signature, _timestamp, _body) {
+        // Urbit uses session cookies, not webhook signatures
+        return true;
+    },
+};
+const outboundAdapter = {
+    async send(message) {
+        if (!currentConfig?.shipUrl)
+            return { success: false, error: 'Ship URL not configured' };
+        const channelPath = message.to || currentConfig.channelPath;
+        if (!channelPath)
+            return { success: false, error: 'Channel path required (to or channelPath config)' };
+        const result = await callShipApi('/~/channels/profclaw', 'PUT', [
+            {
+                id: Date.now(),
+                action: 'poke',
+                ship: currentConfig.shipName?.replace('~', '') ?? '',
+                mark: 'graph-update-3',
+                json: {
+                    'add-post': {
+                        resource: { ship: currentConfig.shipName ?? '', name: channelPath },
+                        body: {
+                            contents: [{ text: message.text ?? '' }],
+                        },
+                    },
+                },
+            },
+        ]);
+        return result.ok
+            ? { success: true, messageId: `tlon-${Date.now()}` }
+            : { success: false, error: result.error ?? 'Failed to send' };
+    },
+};
+const inboundAdapter = {
+    parseMessage(payload) {
+        const event = payload;
+        if (!event?.json?.['graph-update']?.['add-nodes'])
+            return null;
+        const addNodes = event.json['graph-update']['add-nodes'];
+        if (!addNodes)
+            return null;
+        const nodes = Object.values(addNodes.nodes);
+        if (nodes.length === 0)
+            return null;
+        const node = nodes[0];
+        const post = node.post;
+        const text = post.contents
+            .filter((c) => typeof c.text === 'string')
+            .map((c) => c.text)
+            .join('');
+        if (!text)
+            return null;
+        return {
+            id: post.index || `tlon-${Date.now()}`,
+            provider: 'tlon',
+            accountId: currentConfig?.id ?? 'default',
+            senderId: post.author,
+            senderName: post.author,
+            senderUsername: post.author,
+            chatType: 'group',
+            chatId: `${addNodes.resource.ship}/${addNodes.resource.name}`,
+            chatName: addNodes.resource.name,
+            threadId: undefined,
+            replyToId: undefined,
+            text,
+            rawContent: event,
+            timestamp: new Date(post['time-sent']),
+            attachments: undefined,
+        };
+    },
+    parseCommand(_payload) { return null; },
+    parseAction(_payload) { return null; },
+    buildCommandResponse(response) { return { text: response.text ?? '' }; },
+    buildActionResponse(response) { return { text: response.text ?? '' }; },
+};
+const statusAdapter = {
+    isConfigured(config) {
+        return !!(config.shipUrl && config.shipCode);
+    },
+    async checkHealth(config) {
+        if (!config.shipUrl)
+            return { connected: false, error: 'shipUrl is required' };
+        if (!config.shipCode)
+            return { connected: false, error: 'shipCode is required' };
+        const start = Date.now();
+        try {
+            const res = await fetch(`${config.shipUrl}/~/login`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+                body: `password=${encodeURIComponent(config.shipCode)}`,
+                redirect: 'manual',
+                signal: AbortSignal.timeout(10000),
+            });
+            const latencyMs = Date.now() - start;
+            const hasCookie = res.headers.get('set-cookie')?.includes('urbauth') ?? false;
+            return {
+                connected: hasCookie,
+                latencyMs,
+                details: { shipName: config.shipName, status: res.status },
+            };
+        }
+        catch (error) {
+            return {
+                connected: false,
+                latencyMs: Date.now() - start,
+                error: error instanceof Error ? error.message : 'Unknown error',
+            };
+        }
+    },
+};
+// --- Config ---
+export function setTlonConfig(config) {
+    currentConfig = config;
+    sessionCookie = null;
+}
+export function clearTlonConfig() {
+    currentConfig = null;
+    sessionCookie = null;
+}
+// --- Provider export ---
+export const tlonProvider = {
+    meta: {
+        id: 'tlon',
+        name: 'Tlon',
+        description: 'Urbit/Tlon decentralized messaging via ship HTTP API',
+        icon: 'Tlon icon',
+        docsUrl: 'https://docs.urbit.org/',
+        order: 23,
+        color: '#000000',
+    },
+    capabilities: {
+        chatTypes: ['group'],
+        send: true,
+        receive: true,
+        slashCommands: false,
+        interactiveComponents: false,
+        reactions: false,
+        edit: false,
+        delete: false,
+        threads: false,
+        media: false,
+        richBlocks: false,
+        oauth: false,
+        webhooks: false,
+        realtime: true,
+    },
+    defaultConfig: { provider: 'tlon', enabled: true },
+    configSchema: TlonAccountConfigSchema,
+    auth: authAdapter,
+    outbound: outboundAdapter,
+    inbound: inboundAdapter,
+    status: statusAdapter,
+};
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,79 @@
+/**
+ * Twitch Provider - Full Implementation
+ *
+ * Twitch chat integration using:
+ * - Helix API for outbound messages (POST /helix/chat/messages)
+ * - IRC (irc.chat.twitch.tv:6697 TLS) or EventSub webhook for inbound
+ * - HMAC-SHA256 signature verification (Twitch-Eventsub-Message-Signature)
+ * - Health check via GET /helix/users with Bearer token
+ *
+ * API base: https://api.twitch.tv/helix
+ * Docs: https://dev.twitch.tv/docs/api/reference/
+ */
+import { z } from 'zod';
+import type { ChatProvider, TwitchAccountConfig } from '../types.js';
+/** Parsed IRC PRIVMSG from Twitch chat */
+interface TwitchIrcMessage {
+    nick: string;
+    channel: string;
+    text: string;
+    tags?: Record<string, string>;
+}
+/** EventSub channel.chat.message event */
+interface TwitchEventSubPayload {
+    subscription: {
+        type: string;
+        id?: string;
+    };
+    event: {
+        broadcaster_user_id: string;
+        broadcaster_user_login?: string;
+        chatter_user_id: string;
+        chatter_user_name: string;
+        message_id?: string;
+        message: {
+            text: string;
+            fragments?: Array<{
+                type: string;
+                text: string;
+            }>;
+        };
+    };
+}
+export declare const TwitchAccountConfigSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    isDefault: z.ZodOptional<z.ZodBoolean>;
+    provider: z.ZodLiteral<"twitch">;
+    oauthToken: z.ZodOptional<z.ZodString>;
+    clientId: z.ZodOptional<z.ZodString>;
+    nick: z.ZodOptional<z.ZodString>;
+    channels: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    provider: "twitch";
+    enabled: boolean;
+    name?: string | undefined;
+    isDefault?: boolean | undefined;
+    clientId?: string | undefined;
+    channels?: string[] | undefined;
+    nick?: string | undefined;
+    oauthToken?: string | undefined;
+}, {
+    id: string;
+    provider: "twitch";
+    name?: string | undefined;
+    isDefault?: boolean | undefined;
+    enabled?: boolean | undefined;
+    clientId?: string | undefined;
+    channels?: string[] | undefined;
+    nick?: string | undefined;
+    oauthToken?: string | undefined;
+}>;
+type TwitchConfig = z.infer<typeof TwitchAccountConfigSchema>;
+export declare function setTwitchConfig(config: TwitchConfig): void;
+export declare function clearTwitchConfig(): void;
+export declare const twitchProvider: ChatProvider<TwitchAccountConfig>;
+export type { TwitchConfig, TwitchIrcMessage, TwitchEventSubPayload };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,349 @@
+/**
+ * Twitch Provider - Full Implementation
+ *
+ * Twitch chat integration using:
+ * - Helix API for outbound messages (POST /helix/chat/messages)
+ * - IRC (irc.chat.twitch.tv:6697 TLS) or EventSub webhook for inbound
+ * - HMAC-SHA256 signature verification (Twitch-Eventsub-Message-Signature)
+ * - Health check via GET /helix/users with Bearer token
+ *
+ * API base: https://api.twitch.tv/helix
+ * Docs: https://dev.twitch.tv/docs/api/reference/
+ */
+import { createHmac } from 'node:crypto';
+import { z } from 'zod';
+import { logger } from '../../../utils/logger.js';
+// CONFIGURATION
+export const TwitchAccountConfigSchema = z.object({
+    id: z.string(),
+    name: z.string().optional(),
+    enabled: z.boolean().default(true),
+    isDefault: z.boolean().optional(),
+    provider: z.literal('twitch'),
+    oauthToken: z.string().optional(),
+    clientId: z.string().optional(),
+    nick: z.string().optional(),
+    channels: z.array(z.string()).optional(),
+});
+// METADATA
+const meta = {
+    id: 'twitch',
+    name: 'Twitch',
+    description: 'Twitch chat integration via Helix API and EventSub webhooks',
+    icon: 'Twitch icon',
+    docsUrl: 'https://dev.twitch.tv/docs/api/reference/',
+    order: 18,
+    color: '#9146FF',
+};
+// CAPABILITIES
+const capabilities = {
+    chatTypes: ['group'],
+    send: true,
+    receive: true,
+    slashCommands: false,
+    interactiveComponents: false,
+    reactions: false,
+    edit: false,
+    delete: false,
+    threads: false,
+    media: false,
+    richBlocks: false,
+    oauth: false,
+    webhooks: true,
+    realtime: false,
+};
+// STATE
+let currentConfig = null;
+const TWITCH_API_BASE = 'https://api.twitch.tv/helix';
+// HELPER FUNCTIONS
+function getHelixHeaders(config) {
+    const cfg = config ?? currentConfig;
+    return {
+        'Authorization': cfg?.oauthToken ? `Bearer ${cfg.oauthToken}` : '',
+        'Client-Id': cfg?.clientId ?? '',
+        'Content-Type': 'application/json',
+    };
+}
+async function callHelixApi(endpoint, method = 'GET', body, config) {
+    const headers = getHelixHeaders(config);
+    if (!headers['Authorization'] || headers['Authorization'] === 'Bearer ') {
+        return { ok: false, error: 'OAuth token not configured' };
+    }
+    const url = `${TWITCH_API_BASE}${endpoint}`;
+    try {
+        const response = await fetch(url, {
+            method,
+            headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        const data = await response.json();
+        if (!response.ok) {
+            const errData = data;
+            return {
+                ok: false,
+                status: response.status,
+                error: errData.message ?? errData.error ?? `HTTP ${response.status}`,
+            };
+        }
+        return { ok: true, data, status: response.status };
+    }
+    catch (error) {
+        logger.error('[Twitch] API call failed:', error instanceof Error ? error : undefined);
+        return {
+            ok: false,
+            error: error instanceof Error ? error.message : 'Unknown error',
+        };
+    }
+}
+/**
+ * Parse a raw Twitch IRC PRIVMSG line.
+ * Format: [@tags] :nick!nick@nick.tmi.twitch.tv PRIVMSG #channel :message
+ */
+function parseIrcLine(line) {
+    // Strip optional leading tags (@key=val;...)
+    let rest = line;
+    const tags = {};
+    if (rest.startsWith('@')) {
+        const spaceIdx = rest.indexOf(' ');
+        if (spaceIdx === -1)
+            return null;
+        const tagString = rest.slice(1, spaceIdx);
+        for (const part of tagString.split(';')) {
+            const eqIdx = part.indexOf('=');
+            if (eqIdx !== -1) {
+                tags[part.slice(0, eqIdx)] = part.slice(eqIdx + 1);
+            }
+        }
+        rest = rest.slice(spaceIdx + 1).trimStart();
+    }
+    // Match: :nick!nick@nick.tmi.twitch.tv PRIVMSG #channel :text
+    const match = /^:(\w+)!\w+@\w+\.tmi\.twitch\.tv PRIVMSG (#\S+) :(.*)$/.exec(rest);
+    if (!match)
+        return null;
+    return {
+        nick: match[1],
+        channel: match[2],
+        text: match[3],
+        tags: Object.keys(tags).length > 0 ? tags : undefined,
+    };
+}
+/**
+ * Resolve the broadcaster's user ID from a channel name.
+ * Channel name should be provided without the leading '#'.
+ * Used to populate broadcaster_id for Helix send.
+ */
+function channelToBroadcasterId(channel) {
+    // Without a Helix lookup we cannot reliably map name -> ID at parse time.
+    // Callers that need to send messages should store the broadcaster_id
+    // obtained during channel join or from the EventSub event payload.
+    return channel.replace(/^#/, '');
+}
+// AUTH ADAPTER
+const authAdapter = {
+    getAuthUrl(_state, _scopes) {
+        // Twitch provider does not implement a full OAuth flow here.
+        // Tokens are obtained externally via the Twitch OAuth2 authorization flow
+        // and supplied via oauthToken in the configuration.
+        throw new Error('Twitch OAuth flow is not handled by this provider. ' +
+            'Obtain an OAuth token via the Twitch Developer Console and supply it in configuration.');
+    },
+    async exchangeCode(_code) {
+        throw new Error('Twitch does not use authorization code exchange in this provider. ' +
+            'Supply an oauthToken directly in configuration.');
+    },
+    verifyWebhook(signature, _timestamp, body) {
+        // Twitch EventSub signs messages with HMAC-SHA256.
+        // The header Twitch-Eventsub-Message-Signature has format: sha256=<hex>
+        // The HMAC input is: messageId + timestamp + rawBody
+        // Since messageId and timestamp are separate headers not passed here,
+        // we verify the bare body hash as a fallback.
+        // Full verification requires messageId + messageTimestamp headers from the caller.
+        const secret = currentConfig?.oauthToken;
+        if (!secret) {
+            logger.warn('[Twitch] verifyWebhook: oauthToken not configured, skipping verification');
+            return false;
+        }
+        try {
+            const expected = 'sha256=' + createHmac('sha256', secret)
+                .update(body, 'utf8')
+                .digest('hex');
+            return signature === expected;
+        }
+        catch (error) {
+            logger.error('[Twitch] verifyWebhook: HMAC computation failed:', error instanceof Error ? error : undefined);
+            return false;
+        }
+    },
+};
+// OUTBOUND ADAPTER
+const outboundAdapter = {
+    async send(message) {
+        if (!currentConfig?.oauthToken || !currentConfig?.clientId) {
+            return { success: false, error: 'oauthToken and clientId are required' };
+        }
+        if (!message.to) {
+            return { success: false, error: 'broadcaster_id (to) is required' };
+        }
+        // nick is used as sender_id - caller must supply the bot account's user ID
+        const senderId = currentConfig.nick ?? message.to;
+        const sendBody = {
+            broadcaster_id: message.to,
+            sender_id: senderId,
+            message: message.text ?? '',
+        };
+        const result = await callHelixApi('/chat/messages', 'POST', sendBody);
+        if (result.ok && result.data) {
+            const sent = result.data.data?.[0];
+            if (sent?.is_sent === false) {
+                return {
+                    success: false,
+                    error: sent.drop_reason?.message ?? 'Message was not sent',
+                };
+            }
+            return { success: true, messageId: sent?.message_id };
+        }
+        return {
+            success: false,
+            error: result.error ?? 'Failed to send Twitch chat message',
+        };
+    },
+};
+// INBOUND ADAPTER
+const inboundAdapter = {
+    parseMessage(payload) {
+        if (payload === null || typeof payload !== 'object')
+            return null;
+        const obj = payload;
+        // --- EventSub payload ---
+        if ('subscription' in obj && 'event' in obj) {
+            const eventsub = payload;
+            if (eventsub.subscription.type !== 'channel.chat.message') {
+                logger.debug(`[Twitch] parseMessage: unsupported EventSub type '${eventsub.subscription.type}'`);
+                return null;
+            }
+            const ev = eventsub.event;
+            return {
+                id: ev.message_id ?? `${ev.chatter_user_id}-${Date.now()}`,
+                provider: 'twitch',
+                accountId: currentConfig?.id ?? 'default',
+                senderId: ev.chatter_user_id,
+                senderName: ev.chatter_user_name,
+                senderUsername: ev.chatter_user_name,
+                chatType: 'group',
+                chatId: ev.broadcaster_user_id,
+                chatName: ev.broadcaster_user_login,
+                threadId: undefined,
+                replyToId: undefined,
+                text: ev.message.text,
+                rawContent: eventsub,
+                timestamp: new Date(),
+                attachments: undefined,
+            };
+        }
+        // --- Raw IRC line string wrapped in an object ---
+        if ('raw' in obj && typeof obj['raw'] === 'string') {
+            const parsed = parseIrcLine(obj['raw']);
+            if (!parsed)
+                return null;
+            return {
+                id: parsed.tags?.['id'] ?? `${parsed.nick}-${Date.now()}`,
+                provider: 'twitch',
+                accountId: currentConfig?.id ?? 'default',
+                senderId: parsed.tags?.['user-id'] ?? parsed.nick,
+                senderName: parsed.tags?.['display-name'] ?? parsed.nick,
+                senderUsername: parsed.nick,
+                chatType: 'group',
+                chatId: channelToBroadcasterId(parsed.channel),
+                chatName: parsed.channel,
+                threadId: undefined,
+                replyToId: undefined,
+                text: parsed.text,
+                rawContent: parsed,
+                timestamp: new Date(),
+                attachments: undefined,
+            };
+        }
+        logger.debug('[Twitch] parseMessage: unrecognized payload shape');
+        return null;
+    },
+    parseCommand(_payload) {
+        // Twitch does not have native slash commands for bots.
+        return null;
+    },
+    parseAction(_payload) {
+        // Twitch channel point redemptions and predictions are not normalized here.
+        return null;
+    },
+    buildCommandResponse(response) {
+        return { text: response.text ?? '' };
+    },
+    buildActionResponse(response) {
+        return { text: response.text ?? '' };
+    },
+};
+// STATUS ADAPTER
+const statusAdapter = {
+    isConfigured(config) {
+        return !!(config.oauthToken && config.clientId);
+    },
+    async checkHealth(config) {
+        if (!config.oauthToken || !config.clientId) {
+            return { connected: false, error: 'oauthToken and clientId are required' };
+        }
+        const twitchConfig = {
+            id: config.id,
+            name: config.name,
+            enabled: config.enabled ?? true,
+            isDefault: config.isDefault,
+            provider: 'twitch',
+            oauthToken: config.oauthToken,
+            clientId: config.clientId,
+            nick: config.nick,
+            channels: config.channels,
+        };
+        const start = Date.now();
+        const result = await callHelixApi('/users', 'GET', undefined, twitchConfig);
+        const latencyMs = Date.now() - start;
+        if (result.ok && result.data) {
+            const user = result.data.data?.[0];
+            return {
+                connected: true,
+                latencyMs,
+                details: {
+                    userId: user?.id,
+                    login: user?.login,
+                    displayName: user?.display_name,
+                    broadcasterType: user?.broadcaster_type,
+                    channelsConfigured: config.channels?.length ?? 0,
+                },
+            };
+        }
+        return {
+            connected: false,
+            latencyMs,
+            error: result.error ?? 'Failed to connect to Twitch Helix API',
+        };
+    },
+};
+// CONFIG MANAGEMENT
+export function setTwitchConfig(config) {
+    currentConfig = config;
+}
+export function clearTwitchConfig() {
+    currentConfig = null;
+}
+// PROVIDER EXPORT
+export const twitchProvider = {
+    meta,
+    capabilities,
+    defaultConfig: {
+        provider: 'twitch',
+        enabled: true,
+    },
+    configSchema: TwitchAccountConfigSchema,
+    auth: authAdapter,
+    outbound: outboundAdapter,
+    inbound: inboundAdapter,
+    status: statusAdapter,
+};
+//# sourceMappingURL=index.js.map