@pellux/goodvibes-sdk 0.18.3 → 0.18.11

package/dist/platform/integrations/discord.d.ts

@@ -0,0 +1,171 @@
+/** Discord interaction types (subset used here) */
+export declare const DiscordInteractionType: {
+    readonly Ping: 1;
+    readonly ApplicationCommand: 2;
+    readonly MessageComponent: 3;
+    readonly ApplicationCommandAutocomplete: 4;
+    readonly ModalSubmit: 5;
+};
+/** Discord interaction response types */
+export declare const DiscordInteractionResponseType: {
+    readonly Pong: 1;
+    readonly ChannelMessageWithSource: 4;
+    readonly DeferredChannelMessageWithSource: 5;
+    readonly DeferredUpdateMessage: 6;
+};
+export interface DiscordInteraction {
+    id: string;
+    type: number;
+    applicationId: string;
+    token: string;
+    guildId?: string;
+    channelId?: string;
+    userId: string;
+    commandName?: string;
+    commandOptions?: Array<{
+        name: string;
+        value: unknown;
+    }>;
+    raw: Record<string, unknown>;
+}
+export interface DiscordOAuthAuthorizeOptions {
+    readonly clientId: string;
+    readonly redirectUri?: string;
+    readonly scopes?: readonly string[];
+    readonly permissions?: string;
+    readonly guildId?: string;
+    readonly disableGuildSelect?: boolean;
+    readonly state?: string;
+}
+export interface DiscordApplicationCommandOption {
+    readonly type: number;
+    readonly name: string;
+    readonly description: string;
+    readonly required?: boolean;
+}
+export interface DiscordApplicationCommand {
+    readonly id?: string;
+    readonly application_id?: string;
+    readonly guild_id?: string;
+    readonly name: string;
+    readonly description: string;
+    readonly type?: number;
+    readonly options?: readonly DiscordApplicationCommandOption[];
+    readonly default_member_permissions?: string | null;
+    readonly dm_permission?: boolean;
+}
+export interface DiscordGatewayBotResponse {
+    readonly url: string;
+    readonly shards: number;
+    readonly session_start_limit?: Record<string, unknown>;
+}
+export interface DiscordGatewayDispatch {
+    readonly op: number;
+    readonly t?: string;
+    readonly s?: number;
+    readonly d?: Record<string, unknown> | null;
+}
+export interface DiscordGatewayClientOptions {
+    readonly token: string;
+    readonly integration: DiscordIntegration;
+    readonly intents?: number;
+    readonly gatewayUrl?: string;
+    readonly onDispatch: (dispatch: DiscordGatewayDispatch, client: DiscordGatewayClient) => void | Promise<void>;
+    readonly WebSocketImpl?: typeof WebSocket;
+}
+export declare const DiscordGatewayOpcode: {
+    readonly Dispatch: 0;
+    readonly Heartbeat: 1;
+    readonly Identify: 2;
+    readonly Hello: 10;
+    readonly HeartbeatAck: 11;
+};
+export declare const DiscordGatewayIntent: {
+    readonly Guilds: number;
+    readonly GuildMessages: number;
+    readonly DirectMessages: number;
+    readonly MessageContent: number;
+};
+/**
+ * DiscordIntegration — handles inbound interaction verification/parsing and
+ * outbound message posting for Discord slash commands and webhooks.
+ *
+ * Env vars:
+ *   DISCORD_WEBHOOK_URL   — webhook URL for outbound posting
+ *   DISCORD_BOT_TOKEN     — bot token for Discord API calls
+ *   DISCORD_PUBLIC_KEY    — Ed25519 public key for interaction verification
+ */
+export declare class DiscordIntegration {
+    private webhookUrl?;
+    private botToken?;
+    constructor(webhookUrl?: string | undefined, botToken?: string | undefined);
+    static buildOAuthAuthorizeUrl(options: DiscordOAuthAuthorizeOptions): string;
+    static buildGoodVibesCommand(): DiscordApplicationCommand;
+    getGatewayBot(token?: string | undefined): Promise<DiscordGatewayBotResponse>;
+    getCurrentBotUser(token?: string | undefined): Promise<Record<string, unknown>>;
+    listGuildChannels(guildId: string, token?: string | undefined): Promise<Array<Record<string, unknown>>>;
+    listGuildMembers(guildId: string, options?: {
+        readonly token?: string;
+        readonly limit?: number;
+        readonly after?: string;
+    }): Promise<Array<Record<string, unknown>>>;
+    registerGlobalCommand(applicationId: string, command: DiscordApplicationCommand, token?: string | undefined): Promise<DiscordApplicationCommand>;
+    registerGuildCommand(applicationId: string, guildId: string, command: DiscordApplicationCommand, token?: string | undefined): Promise<DiscordApplicationCommand>;
+    bulkOverwriteGuildCommands(applicationId: string, guildId: string, commands: readonly DiscordApplicationCommand[], token?: string | undefined): Promise<DiscordApplicationCommand[]>;
+    /**
+     * Verify an inbound Discord interaction using Ed25519.
+     * Discord signs: timestamp + body with the application's public key.
+     */
+    verifySignature(body: string, signature: string, timestamp: string, publicKey: string): Promise<boolean>;
+    /**
+     * Parse an inbound Discord interaction payload into a typed DiscordInteraction.
+     */
+    parseInteraction(body: Record<string, unknown>): DiscordInteraction;
+    /**
+     * Post a message via Discord webhook URL.
+     */
+    postWebhook(content: string, embeds?: unknown[], url?: string): Promise<void>;
+    /**
+     * Post a message to a channel via the Discord Bot API.
+     * Requires DISCORD_BOT_TOKEN.
+     */
+    postMessage(channelId: string, content: string, embeds?: unknown[]): Promise<void>;
+    /**
+     * Respond to an interaction via the Discord interactions endpoint.
+     * Use this to send the deferred acknowledgment or a follow-up.
+     */
+    respondToInteraction(interactionId: string, interactionToken: string, type: number, data?: Record<string, unknown>): Promise<void>;
+    /**
+     * Edit the original deferred interaction response (follow-up).
+     */
+    editOriginalResponse(applicationId: string, interactionToken: string, content: string, embeds?: unknown[]): Promise<void>;
+    private apiFetch;
+    /**
+     * Format an agent result as a Discord embed object.
+     */
+    formatAgentResult(agentId: string, task: string, result: string): unknown;
+    /**
+     * Format a session summary as a Discord embed object.
+     */
+    formatSessionSummary(sessionId: string, messageCount: number, tokensUsed: number): unknown;
+    private hexToBytes;
+    private validateSnowflake;
+}
+export declare class DiscordGatewayClient {
+    private readonly options;
+    private socket;
+    private heartbeat;
+    private sequence;
+    private started;
+    private readonly WebSocketImpl;
+    constructor(options: DiscordGatewayClientOptions);
+    start(): Promise<DiscordGatewayBotResponse>;
+    stop(): void;
+    send(op: number, d: unknown): void;
+    get isStarted(): boolean;
+    private handleMessage;
+    private identify;
+    private startHeartbeat;
+    private cleanup;
+}
+//# sourceMappingURL=discord.d.ts.map

package/dist/platform/integrations/discord.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discord.d.ts","sourceRoot":"","sources":["../../../src/platform/integrations/discord.ts"],"names":[],"mappings":"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"}

package/dist/platform/integrations/discord.js

@@ -0,0 +1,445 @@
+import { logger } from '../utils/logger.js';
+import { summarizeError } from '../utils/error-display.js';
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+/** Discord interaction types (subset used here) */
+export const DiscordInteractionType = {
+    Ping: 1,
+    ApplicationCommand: 2,
+    MessageComponent: 3,
+    ApplicationCommandAutocomplete: 4,
+    ModalSubmit: 5,
+};
+/** Discord interaction response types */
+export const DiscordInteractionResponseType = {
+    Pong: 1,
+    ChannelMessageWithSource: 4,
+    DeferredChannelMessageWithSource: 5,
+    DeferredUpdateMessage: 6,
+};
+export const DiscordGatewayOpcode = {
+    Dispatch: 0,
+    Heartbeat: 1,
+    Identify: 2,
+    Hello: 10,
+    HeartbeatAck: 11,
+};
+export const DiscordGatewayIntent = {
+    Guilds: 1 << 0,
+    GuildMessages: 1 << 9,
+    DirectMessages: 1 << 12,
+    MessageContent: 1 << 15,
+};
+// ---------------------------------------------------------------------------
+// DiscordIntegration
+// ---------------------------------------------------------------------------
+/**
+ * DiscordIntegration — handles inbound interaction verification/parsing and
+ * outbound message posting for Discord slash commands and webhooks.
+ *
+ * Env vars:
+ *   DISCORD_WEBHOOK_URL   — webhook URL for outbound posting
+ *   DISCORD_BOT_TOKEN     — bot token for Discord API calls
+ *   DISCORD_PUBLIC_KEY    — Ed25519 public key for interaction verification
+ */
+export class DiscordIntegration {
+    webhookUrl;
+    botToken;
+    constructor(webhookUrl, botToken) {
+        this.webhookUrl = webhookUrl;
+        this.botToken = botToken;
+    }
+    static buildOAuthAuthorizeUrl(options) {
+        const url = new URL('https://discord.com/oauth2/authorize');
+        url.searchParams.set('client_id', options.clientId);
+        url.searchParams.set('scope', (options.scopes?.length ? options.scopes : ['bot', 'applications.commands']).join(' '));
+        if (options.redirectUri)
+            url.searchParams.set('redirect_uri', options.redirectUri);
+        if (options.permissions)
+            url.searchParams.set('permissions', options.permissions);
+        if (options.guildId)
+            url.searchParams.set('guild_id', options.guildId);
+        if (options.disableGuildSelect !== undefined)
+            url.searchParams.set('disable_guild_select', options.disableGuildSelect ? 'true' : 'false');
+        if (options.state)
+            url.searchParams.set('state', options.state);
+        return url.toString();
+    }
+    static buildGoodVibesCommand() {
+        return {
+            name: 'goodvibes',
+            description: 'Send a prompt to GoodVibes.',
+            type: 1,
+            options: [
+                {
+                    type: 3,
+                    name: 'prompt',
+                    description: 'Prompt or control command to run.',
+                    required: true,
+                },
+            ],
+        };
+    }
+    async getGatewayBot(token = this.botToken) {
+        return this.apiFetch('/gateway/bot', { token });
+    }
+    async getCurrentBotUser(token = this.botToken) {
+        return this.apiFetch('/users/@me', { token });
+    }
+    async listGuildChannels(guildId, token = this.botToken) {
+        this.validateSnowflake(guildId, 'guildId');
+        return this.apiFetch(`/guilds/${guildId}/channels`, { token });
+    }
+    async listGuildMembers(guildId, options = {}) {
+        this.validateSnowflake(guildId, 'guildId');
+        const params = new URLSearchParams({
+            limit: String(Math.max(1, Math.min(1000, options.limit ?? 100))),
+        });
+        if (options.after)
+            params.set('after', options.after);
+        return this.apiFetch(`/guilds/${guildId}/members?${params.toString()}`, {
+            token: options.token ?? this.botToken,
+        });
+    }
+    async registerGlobalCommand(applicationId, command, token = this.botToken) {
+        this.validateSnowflake(applicationId, 'applicationId');
+        return this.apiFetch(`/applications/${applicationId}/commands`, {
+            method: 'POST',
+            token,
+            body: command,
+        });
+    }
+    async registerGuildCommand(applicationId, guildId, command, token = this.botToken) {
+        this.validateSnowflake(applicationId, 'applicationId');
+        this.validateSnowflake(guildId, 'guildId');
+        return this.apiFetch(`/applications/${applicationId}/guilds/${guildId}/commands`, {
+            method: 'POST',
+            token,
+            body: command,
+        });
+    }
+    async bulkOverwriteGuildCommands(applicationId, guildId, commands, token = this.botToken) {
+        this.validateSnowflake(applicationId, 'applicationId');
+        this.validateSnowflake(guildId, 'guildId');
+        return this.apiFetch(`/applications/${applicationId}/guilds/${guildId}/commands`, {
+            method: 'PUT',
+            token,
+            body: commands,
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Inbound: verification
+    // -------------------------------------------------------------------------
+    /**
+     * Verify an inbound Discord interaction using Ed25519.
+     * Discord signs: timestamp + body with the application's public key.
+     */
+    async verifySignature(body, signature, timestamp, publicKey) {
+        try {
+            const keyBytes = this.hexToBytes(publicKey);
+            const sigBytes = this.hexToBytes(signature);
+            const message = new TextEncoder().encode(timestamp + body);
+            const cryptoKey = await crypto.subtle.importKey('raw', keyBytes, { name: 'Ed25519' }, false, ['verify']);
+            return await crypto.subtle.verify('Ed25519', cryptoKey, sigBytes, message);
+        }
+        catch (err) {
+            logger.warn('DiscordIntegration.verifySignature: verification error', {
+                error: summarizeError(err),
+            });
+            return false;
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Inbound: parsing
+    // -------------------------------------------------------------------------
+    /**
+     * Parse an inbound Discord interaction payload into a typed DiscordInteraction.
+     */
+    parseInteraction(body) {
+        const member = (body.member ?? {});
+        const memberUser = (member.user ?? {});
+        const directUser = (body.user ?? {});
+        // Guild interactions put the user under member.user; DMs put it under user
+        const userObj = Object.keys(memberUser).length > 0 ? memberUser : directUser;
+        const data = (body.data ?? {});
+        const options = Array.isArray(data.options)
+            ? data.options.map((o) => ({
+                name: typeof o.name === 'string' ? o.name : '',
+                value: o.value,
+            }))
+            : undefined;
+        return {
+            id: typeof body.id === 'string' ? body.id : '',
+            type: typeof body.type === 'number' ? body.type : 0,
+            applicationId: typeof body.application_id === 'string' ? body.application_id : '',
+            token: typeof body.token === 'string' ? body.token : '',
+            guildId: typeof body.guild_id === 'string' ? body.guild_id : undefined,
+            channelId: typeof body.channel_id === 'string' ? body.channel_id : undefined,
+            userId: typeof userObj.id === 'string' ? userObj.id : '',
+            commandName: typeof data.name === 'string' ? data.name : undefined,
+            commandOptions: options,
+            raw: body,
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Outbound: posting
+    // -------------------------------------------------------------------------
+    /**
+     * Post a message via Discord webhook URL.
+     */
+    async postWebhook(content, embeds, url) {
+        const target = url ?? this.webhookUrl;
+        if (!target) {
+            throw new Error('DiscordIntegration: webhookUrl is required for postWebhook');
+        }
+        const payload = {};
+        if (content)
+            payload.content = content;
+        if (embeds && embeds.length > 0)
+            payload.embeds = embeds;
+        const res = await fetch(target, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(payload),
+        });
+        if (!res.ok) {
+            const err = await res.text();
+            throw new Error(`DiscordIntegration.postWebhook failed (${res.status}): ${err}`);
+        }
+    }
+    /**
+     * Post a message to a channel via the Discord Bot API.
+     * Requires DISCORD_BOT_TOKEN.
+     */
+    async postMessage(channelId, content, embeds) {
+        if (!this.botToken) {
+            throw new Error('DiscordIntegration: botToken is required for postMessage');
+        }
+        this.validateSnowflake(channelId, 'channelId');
+        const payload = {};
+        if (content)
+            payload.content = content;
+        if (embeds && embeds.length > 0)
+            payload.embeds = embeds;
+        const res = await fetch(`https://discord.com/api/v10/channels/${channelId}/messages`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bot ${this.botToken}`,
+            },
+            body: JSON.stringify(payload),
+        });
+        if (!res.ok) {
+            const err = await res.text();
+            throw new Error(`DiscordIntegration.postMessage failed (${res.status}): ${err}`);
+        }
+    }
+    /**
+     * Respond to an interaction via the Discord interactions endpoint.
+     * Use this to send the deferred acknowledgment or a follow-up.
+     */
+    async respondToInteraction(interactionId, interactionToken, type, data) {
+        this.validateSnowflake(interactionId, 'interactionId');
+        const payload = { type };
+        if (data)
+            payload.data = data;
+        const res = await fetch(`https://discord.com/api/v10/interactions/${interactionId}/${interactionToken}/callback`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(payload),
+        });
+        // 204 No Content is the normal success code
+        if (!res.ok && res.status !== 204) {
+            const err = await res.text();
+            throw new Error(`DiscordIntegration.respondToInteraction failed (${res.status}): ${err}`);
+        }
+    }
+    /**
+     * Edit the original deferred interaction response (follow-up).
+     */
+    async editOriginalResponse(applicationId, interactionToken, content, embeds) {
+        this.validateSnowflake(applicationId, 'applicationId');
+        const payload = { content };
+        if (embeds && embeds.length > 0)
+            payload.embeds = embeds;
+        const res = await fetch(`https://discord.com/api/v10/webhooks/${applicationId}/${interactionToken}/messages/@original`, {
+            method: 'PATCH',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(payload),
+        });
+        if (!res.ok) {
+            const err = await res.text();
+            throw new Error(`DiscordIntegration.editOriginalResponse failed (${res.status}): ${err}`);
+        }
+    }
+    async apiFetch(path, options = {}) {
+        const token = options.token ?? this.botToken;
+        if (!token) {
+            throw new Error(`DiscordIntegration: botToken is required for ${path}`);
+        }
+        const res = await fetch(`https://discord.com/api/v10${path}`, {
+            method: options.method ?? 'GET',
+            headers: {
+                Authorization: `Bot ${token}`,
+                ...(options.body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+            },
+            ...(options.body !== undefined ? { body: JSON.stringify(options.body) } : {}),
+        });
+        if (!res.ok) {
+            const err = await res.text();
+            throw new Error(`DiscordIntegration.apiFetch ${path} failed (${res.status}): ${err}`);
+        }
+        return await res.json();
+    }
+    // -------------------------------------------------------------------------
+    // Formatting helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Format an agent result as a Discord embed object.
+     */
+    formatAgentResult(agentId, task, result) {
+        const truncated = result.length > 4000 ? `${result.slice(0, 4000)}\n\n*…truncated*` : result;
+        return {
+            title: 'Agent Complete',
+            color: 0x57f287, // green
+            fields: [
+                { name: 'Task', value: task.slice(0, 1024), inline: false },
+                { name: 'Agent ID', value: `\`${agentId}\``, inline: true },
+            ],
+            description: truncated,
+            timestamp: new Date().toISOString(),
+        };
+    }
+    /**
+     * Format a session summary as a Discord embed object.
+     */
+    formatSessionSummary(sessionId, messageCount, tokensUsed) {
+        return {
+            title: 'Session Summary',
+            color: 0x5865f2, // blurple
+            fields: [
+                { name: 'Session ID', value: `\`${sessionId}\``, inline: false },
+                { name: 'Messages', value: String(messageCount), inline: true },
+                { name: 'Tokens Used', value: tokensUsed.toLocaleString(), inline: true },
+            ],
+            timestamp: new Date().toISOString(),
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    hexToBytes(hex) {
+        if (hex.length % 2 !== 0 || !/^[0-9a-fA-F]+$/.test(hex)) {
+            throw new Error('DiscordIntegration: invalid hex string');
+        }
+        const buf = new ArrayBuffer(hex.length / 2);
+        const bytes = new Uint8Array(buf);
+        for (let i = 0; i < bytes.length; i++) {
+            bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+        }
+        return bytes;
+    }
+    validateSnowflake(id, name) {
+        if (!/^\d{17,20}$/.test(id)) {
+            throw new Error(`DiscordIntegration: invalid ${name}: ${id}`);
+        }
+    }
+}
+export class DiscordGatewayClient {
+    options;
+    socket = null;
+    heartbeat = null;
+    sequence = null;
+    started = false;
+    WebSocketImpl;
+    constructor(options) {
+        this.options = options;
+        this.WebSocketImpl = options.WebSocketImpl ?? WebSocket;
+    }
+    async start() {
+        if (this.started && this.socket) {
+            return {
+                url: this.options.gatewayUrl ?? '',
+                shards: 1,
+            };
+        }
+        const gateway = this.options.gatewayUrl
+            ? { url: this.options.gatewayUrl, shards: 1 }
+            : await this.options.integration.getGatewayBot(this.options.token);
+        const url = `${gateway.url.replace(/\/+$/, '')}/?v=10&encoding=json`;
+        const socket = new this.WebSocketImpl(url);
+        this.socket = socket;
+        this.started = true;
+        socket.addEventListener('message', (event) => {
+            void this.handleMessage(event.data);
+        });
+        socket.addEventListener('close', () => this.cleanup());
+        return gateway;
+    }
+    stop() {
+        this.cleanup();
+        this.socket?.close();
+        this.socket = null;
+    }
+    send(op, d) {
+        if (!this.socket || this.socket.readyState !== this.WebSocketImpl.OPEN)
+            return;
+        this.socket.send(JSON.stringify({ op, d }));
+    }
+    get isStarted() {
+        return this.started;
+    }
+    async handleMessage(data) {
+        const raw = typeof data === 'string' ? data : data instanceof Buffer ? data.toString('utf-8') : String(data);
+        let dispatch;
+        try {
+            dispatch = JSON.parse(raw);
+        }
+        catch (error) {
+            logger.warn('DiscordGatewayClient: invalid gateway payload', {
+                error: summarizeError(error),
+            });
+            return;
+        }
+        if (typeof dispatch.s === 'number')
+            this.sequence = dispatch.s;
+        if (dispatch.op === DiscordGatewayOpcode.Hello) {
+            const hello = dispatch.d ?? {};
+            const interval = typeof hello.heartbeat_interval === 'number' ? hello.heartbeat_interval : 45_000;
+            this.startHeartbeat(interval);
+            this.identify();
+            return;
+        }
+        if (dispatch.op === DiscordGatewayOpcode.Dispatch) {
+            await this.options.onDispatch(dispatch, this);
+        }
+    }
+    identify() {
+        this.send(DiscordGatewayOpcode.Identify, {
+            token: this.options.token,
+            intents: this.options.intents
+                ?? (DiscordGatewayIntent.Guilds | DiscordGatewayIntent.GuildMessages | DiscordGatewayIntent.DirectMessages | DiscordGatewayIntent.MessageContent),
+            properties: {
+                os: process.platform,
+                browser: 'goodvibes-sdk',
+                device: 'goodvibes-sdk',
+            },
+        });
+    }
+    startHeartbeat(intervalMs) {
+        if (this.heartbeat)
+            clearInterval(this.heartbeat);
+        this.heartbeat = setInterval(() => {
+            this.send(DiscordGatewayOpcode.Heartbeat, this.sequence);
+        }, intervalMs);
+        this.send(DiscordGatewayOpcode.Heartbeat, this.sequence);
+    }
+    cleanup() {
+        this.started = false;
+        if (this.heartbeat) {
+            clearInterval(this.heartbeat);
+            this.heartbeat = null;
+        }
+    }
+}

package/dist/platform/integrations/github.d.ts

@@ -0,0 +1,43 @@
+export interface GitHubWebhookEvent {
+    /** GitHub event type from X-GitHub-Event header (e.g. 'pull_request', 'issues') */
+    type: string;
+    /** Action field from the payload (e.g. 'opened', 'synchronize') */
+    action: string;
+    /** Raw webhook payload */
+    payload: Record<string, unknown>;
+}
+/**
+ * GitHubIntegration — HMAC verification, event parsing, prompt generation,
+ * and outbound GitHub API calls (comments, reviews).
+ */
+export declare class GitHubIntegration {
+    /**
+     * Verify an HMAC-SHA256 webhook signature.
+     * GitHub sends: X-Hub-Signature-256: sha256=<hex>
+     */
+    static verifySignature(payload: string, signature: string, secret: string): boolean;
+    /**
+     * Parse a GitHub webhook payload into a structured event.
+     * The event type comes from the X-GitHub-Event header.
+     */
+    static parseEvent(headers: Headers, body: Record<string, unknown>): GitHubWebhookEvent;
+    /**
+     * Convert a GitHub webhook event into an agent prompt.
+     * Returns null if the event does not warrant agent action.
+     */
+    static eventToPrompt(event: GitHubWebhookEvent): string | null;
+    /**
+     * Post a comment on a pull request.
+     */
+    postPRComment(owner: string, repo: string, prNumber: number, body: string, token: string): Promise<void>;
+    /**
+     * Post a review on a pull request.
+     */
+    postPRReview(owner: string, repo: string, prNumber: number, body: string, event: 'APPROVE' | 'REQUEST_CHANGES' | 'COMMENT', token: string): Promise<void>;
+    /**
+     * Post a comment on an issue.
+     */
+    postIssueComment(owner: string, repo: string, issueNumber: number, body: string, token: string): Promise<void>;
+    private githubPost;
+}
+//# sourceMappingURL=github.d.ts.map

package/dist/platform/integrations/github.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github.d.ts","sourceRoot":"","sources":["../../../src/platform/integrations/github.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,kBAAkB;IACjC,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAMD;;;GAGG;AACH,qBAAa,iBAAiB;IAC5B;;;OAGG;IACH,MAAM,CAAC,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO;IAQnF;;;OAGG;IACH,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,kBAAkB;IAMtF;;;OAGG;IACH,MAAM,CAAC,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM,GAAG,IAAI;IAqK9D;;OAEG;IACG,aAAa,CACjB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC;IAQhB;;OAEG;IACG,YAAY,CAChB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,SAAS,GAAG,iBAAiB,GAAG,SAAS,EAChD,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC;IAQhB;;OAEG;IACG,gBAAgB,CACpB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC;YAYF,UAAU;CA0BzB"}