@wolpertingerlabs/drawlatch 1.0.0-alpha.1

package/dist/remote/ingestors/ring-buffer.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Generic bounded ring buffer for event storage.
+ *
+ * When the buffer is full, the oldest item is evicted to make room.
+ * Each pushed item receives a monotonically increasing ID that persists
+ * across evictions and clears — enabling cursor-based polling.
+ */
+export declare class RingBuffer<T> {
+    private readonly capacity;
+    private buffer;
+    private head;
+    private count;
+    constructor(capacity: number);
+    /**
+     * Push an item into the buffer.
+     * If the buffer is full, the oldest item is evicted.
+     */
+    push(item: T): void;
+    /**
+     * Return all buffered items in chronological order (oldest first).
+     */
+    toArray(): T[];
+    /**
+     * Return items where the `id` field is greater than `afterId`.
+     * Assumes items have a numeric `id` field (enforced at the call site).
+     */
+    since(afterId: number): T[];
+    /** Current number of items in the buffer. */
+    get size(): number;
+    /** Remove all items. Does NOT reset any external ID counters. */
+    clear(): void;
+}
+//# sourceMappingURL=ring-buffer.d.ts.map

package/dist/remote/ingestors/ring-buffer.js

@@ -0,0 +1,62 @@
+/**
+ * Generic bounded ring buffer for event storage.
+ *
+ * When the buffer is full, the oldest item is evicted to make room.
+ * Each pushed item receives a monotonically increasing ID that persists
+ * across evictions and clears — enabling cursor-based polling.
+ */
+export class RingBuffer {
+    capacity;
+    buffer;
+    head = 0; // next write position
+    count = 0; // number of items currently stored
+    constructor(capacity) {
+        this.capacity = capacity;
+        this.buffer = new Array(capacity);
+    }
+    /**
+     * Push an item into the buffer.
+     * If the buffer is full, the oldest item is evicted.
+     */
+    push(item) {
+        this.buffer[this.head] = item;
+        this.head = (this.head + 1) % this.capacity;
+        if (this.count < this.capacity) {
+            this.count++;
+        }
+    }
+    /**
+     * Return all buffered items in chronological order (oldest first).
+     */
+    toArray() {
+        if (this.count === 0)
+            return [];
+        const start = (this.head - this.count + this.capacity) % this.capacity;
+        const result = [];
+        for (let i = 0; i < this.count; i++) {
+            result.push(this.buffer[(start + i) % this.capacity]);
+        }
+        return result;
+    }
+    /**
+     * Return items where the `id` field is greater than `afterId`.
+     * Assumes items have a numeric `id` field (enforced at the call site).
+     */
+    since(afterId) {
+        return this.toArray().filter((item) => {
+            const id = item.id;
+            return typeof id === 'number' && id > afterId;
+        });
+    }
+    /** Current number of items in the buffer. */
+    get size() {
+        return this.count;
+    }
+    /** Remove all items. Does NOT reset any external ID counters. */
+    clear() {
+        this.buffer = new Array(this.capacity);
+        this.head = 0;
+        this.count = 0;
+    }
+}
+//# sourceMappingURL=ring-buffer.js.map

package/dist/remote/ingestors/slack/index.d.ts

@@ -0,0 +1,3 @@
+export { SlackSocketModeIngestor } from './socket-mode.js';
+export { type SlackMessageType, type SlackDisconnectReason, type SlackEnvelope, type SlackHello, type SlackDisconnect, type SlackConnectionsOpenResponse, extractSlackEventType, extractSlackChannelId, extractSlackUserId, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/remote/ingestors/slack/index.js

@@ -0,0 +1,3 @@
+export { SlackSocketModeIngestor } from './socket-mode.js';
+export { extractSlackEventType, extractSlackChannelId, extractSlackUserId, } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/remote/ingestors/slack/socket-mode.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Slack Socket Mode ingestor.
+ *
+ * Connects to Slack via Socket Mode WebSocket and streams real-time events
+ * (messages, slash commands, interactions, etc.) into the ring buffer.
+ *
+ * Implements the Socket Mode lifecycle:
+ *   1. POST apps.connections.open (app-level token) → get WebSocket URL
+ *   2. Connect to WebSocket → receive `hello`
+ *   3. Receive envelopes → acknowledge → buffer events
+ *   4. Handle `disconnect` messages → reconnect
+ *
+ * Uses the native WebSocket API (Node 22+) and native fetch.
+ *
+ * @see https://docs.slack.dev/apis/events-api/using-socket-mode
+ */
+import { BaseIngestor } from '../base-ingestor.js';
+import type { WebSocketIngestorConfig } from '../types.js';
+export declare class SlackSocketModeIngestor extends BaseIngestor {
+    private readonly wsConfig;
+    private ws;
+    private reconnectAttempts;
+    private readonly maxReconnectAttempts;
+    private reconnectTimer;
+    /** The URL for the apps.connections.open endpoint. */
+    private readonly connectUrl;
+    private readonly eventFilter;
+    private readonly channelIds;
+    private readonly userIds;
+    constructor(connectionAlias: string, secrets: Record<string, string>, wsConfig: WebSocketIngestorConfig, bufferSize?: number);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * Call apps.connections.open to get a dynamic WebSocket URL, then connect.
+     */
+    private openConnection;
+    private connectWebSocket;
+    private handleEnvelope;
+    private handleHello;
+    private handleDisconnect;
+    private handleEvent;
+    private acknowledge;
+    private initiateReconnect;
+    private scheduleReconnect;
+    private send;
+    private clearReconnectTimer;
+}
+//# sourceMappingURL=socket-mode.d.ts.map

package/dist/remote/ingestors/slack/socket-mode.js

@@ -0,0 +1,267 @@
+/**
+ * Slack Socket Mode ingestor.
+ *
+ * Connects to Slack via Socket Mode WebSocket and streams real-time events
+ * (messages, slash commands, interactions, etc.) into the ring buffer.
+ *
+ * Implements the Socket Mode lifecycle:
+ *   1. POST apps.connections.open (app-level token) → get WebSocket URL
+ *   2. Connect to WebSocket → receive `hello`
+ *   3. Receive envelopes → acknowledge → buffer events
+ *   4. Handle `disconnect` messages → reconnect
+ *
+ * Uses the native WebSocket API (Node 22+) and native fetch.
+ *
+ * @see https://docs.slack.dev/apis/events-api/using-socket-mode
+ */
+import { BaseIngestor } from '../base-ingestor.js';
+import { registerIngestorFactory } from '../registry.js';
+import { extractSlackEventType, extractSlackChannelId, extractSlackUserId, } from './types.js';
+import { createLogger } from '../../../shared/logger.js';
+const log = createLogger('slack-sm');
+// ── Slack Socket Mode ingestor ──────────────────────────────────────────
+export class SlackSocketModeIngestor extends BaseIngestor {
+    wsConfig;
+    ws = null;
+    reconnectAttempts = 0;
+    maxReconnectAttempts = 10;
+    reconnectTimer = null;
+    /** The URL for the apps.connections.open endpoint. */
+    connectUrl;
+    eventFilter;
+    channelIds;
+    userIds;
+    constructor(connectionAlias, secrets, wsConfig, bufferSize) {
+        super(connectionAlias, 'websocket', secrets, bufferSize);
+        this.wsConfig = wsConfig;
+        this.connectUrl = wsConfig.gatewayUrl;
+        this.eventFilter = wsConfig.eventFilter ?? [];
+        this.channelIds = new Set(wsConfig.channelIds ?? []);
+        this.userIds = new Set(wsConfig.userIds ?? []);
+    }
+    async start() {
+        this.state = 'starting';
+        await this.openConnection();
+    }
+    stop() {
+        this.state = 'stopped';
+        this.clearReconnectTimer();
+        if (this.ws) {
+            this.ws.close(1000, 'Shutting down');
+            this.ws = null;
+        }
+        return Promise.resolve();
+    }
+    // ── Connection establishment ────────────────────────────────────────
+    /**
+     * Call apps.connections.open to get a dynamic WebSocket URL, then connect.
+     */
+    async openConnection() {
+        const appToken = this.secrets.SLACK_APP_TOKEN;
+        if (!appToken) {
+            this.state = 'error';
+            this.errorMessage = 'SLACK_APP_TOKEN not found in resolved secrets';
+            log.error(`${this.errorMessage} (${this.connectionAlias})`);
+            return;
+        }
+        let wsUrl;
+        try {
+            const response = await fetch(this.connectUrl, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${appToken}`,
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                },
+            });
+            const body = (await response.json());
+            if (!body.ok || !body.url) {
+                this.state = 'error';
+                this.errorMessage = `apps.connections.open failed: ${body.error ?? 'no URL returned'}`;
+                log.error(`${this.errorMessage} (${this.connectionAlias})`);
+                return;
+            }
+            wsUrl = body.url;
+        }
+        catch (err) {
+            this.state = 'error';
+            this.errorMessage = `Failed to call apps.connections.open: ${err instanceof Error ? err.message : String(err)}`;
+            log.error(`${this.errorMessage} (${this.connectionAlias})`);
+            return;
+        }
+        this.connectWebSocket(wsUrl);
+    }
+    // ── WebSocket connection ────────────────────────────────────────────
+    connectWebSocket(url) {
+        try {
+            this.ws = new WebSocket(url);
+        }
+        catch (err) {
+            this.state = 'error';
+            this.errorMessage = `Failed to create WebSocket: ${err instanceof Error ? err.message : String(err)}`;
+            log.error(`${this.errorMessage} (${this.connectionAlias})`);
+            return;
+        }
+        this.ws.addEventListener('open', () => {
+            log.info(`WebSocket connected for ${this.connectionAlias}`);
+        });
+        this.ws.addEventListener('message', (event) => {
+            try {
+                const data = typeof event.data === 'string' ? event.data : String(event.data);
+                const envelope = JSON.parse(data);
+                this.handleEnvelope(envelope);
+            }
+            catch (err) {
+                log.error(`Failed to parse Socket Mode message:`, err);
+            }
+        });
+        this.ws.addEventListener('close', (event) => {
+            log.info(`Connection closed for ${this.connectionAlias}: ${event.code} ${event.reason}`);
+            if (this.state !== 'stopped') {
+                this.scheduleReconnect();
+            }
+        });
+        this.ws.addEventListener('error', () => {
+            // The 'close' event always follows 'error', so we handle reconnection there.
+            log.error(`WebSocket error for ${this.connectionAlias}`);
+        });
+    }
+    // ── Envelope dispatch ──────────────────────────────────────────────
+    handleEnvelope(envelope) {
+        switch (envelope.type) {
+            case 'hello':
+                this.handleHello(envelope);
+                break;
+            case 'disconnect':
+                this.handleDisconnect(envelope);
+                break;
+            case 'events_api':
+            case 'slash_commands':
+            case 'interactive':
+                this.handleEvent(envelope);
+                break;
+            default:
+                log.warn(`Unknown message type "${String(envelope.type)}" for ${this.connectionAlias}`);
+                // Still acknowledge if there's an envelope_id
+                if (envelope.envelope_id) {
+                    this.acknowledge(envelope.envelope_id);
+                }
+                break;
+        }
+    }
+    // ── Hello ─────────────────────────────────────────────────────────
+    handleHello(hello) {
+        this.state = 'connected';
+        this.reconnectAttempts = 0;
+        log.info(`Connected for ${this.connectionAlias} ` +
+            `(app: ${hello.connection_info.app_id}, connections: ${hello.num_connections}, ` +
+            `refresh in ~${hello.debug_info.approximate_connection_time}s)`);
+    }
+    // ── Disconnect ────────────────────────────────────────────────────
+    handleDisconnect(disconnect) {
+        log.info(`Disconnect for ${this.connectionAlias}: ${disconnect.reason} ` +
+            `(host: ${disconnect.debug_info.host})`);
+        switch (disconnect.reason) {
+            case 'refresh_requested':
+            case 'warning':
+                // Normal refresh — reconnect immediately
+                this.initiateReconnect();
+                break;
+            case 'link_disabled':
+                // Socket Mode was disabled for the app — stop permanently
+                this.state = 'error';
+                this.errorMessage = 'Socket Mode was disabled for this app (link_disabled)';
+                log.error(`${this.errorMessage} (${this.connectionAlias})`);
+                if (this.ws) {
+                    this.ws.close(1000, 'Link disabled');
+                    this.ws = null;
+                }
+                break;
+        }
+    }
+    // ── Event handling ────────────────────────────────────────────────
+    handleEvent(envelope) {
+        // Always acknowledge first — Slack expects prompt acks
+        if (envelope.envelope_id) {
+            this.acknowledge(envelope.envelope_id);
+        }
+        // Determine the specific event type for filtering and buffering
+        const eventType = extractSlackEventType(envelope);
+        // Apply event type filter (empty filter = capture all)
+        if (this.eventFilter.length > 0 && !this.eventFilter.includes(eventType)) {
+            log.debug(`${this.connectionAlias} event filtered out by eventFilter: ${eventType}`);
+            return;
+        }
+        // Apply payload-level filters.
+        // Events without the filtered field pass through (same convention as Discord).
+        if (this.channelIds.size > 0) {
+            const channelId = extractSlackChannelId(envelope);
+            if (channelId && !this.channelIds.has(channelId))
+                return;
+        }
+        if (this.userIds.size > 0) {
+            const userId = extractSlackUserId(envelope);
+            if (userId && !this.userIds.has(userId))
+                return;
+        }
+        // Buffer the event (use envelope_id as idempotency key for retry dedup)
+        const idempotencyKey = envelope.envelope_id ? `slack:${envelope.envelope_id}` : undefined;
+        log.debug(`${this.connectionAlias} dispatching event: ${eventType} (envelope: ${envelope.type})`);
+        this.pushEvent(eventType, envelope.payload, idempotencyKey);
+    }
+    // ── Acknowledgment ────────────────────────────────────────────────
+    acknowledge(envelopeId) {
+        this.send({ envelope_id: envelopeId });
+    }
+    // ── Reconnection ──────────────────────────────────────────────────
+    initiateReconnect() {
+        this.clearReconnectTimer();
+        if (this.ws) {
+            this.ws.close(1000, 'Reconnecting');
+            this.ws = null;
+        }
+        // Reset attempts for intentional refreshes (Slack-initiated)
+        this.reconnectAttempts = 0;
+        this.scheduleReconnect();
+    }
+    scheduleReconnect() {
+        if (this.state === 'stopped')
+            return;
+        if (this.reconnectAttempts >= this.maxReconnectAttempts) {
+            this.state = 'error';
+            this.errorMessage = `Max reconnect attempts (${this.maxReconnectAttempts}) exceeded`;
+            log.error(`${this.errorMessage} (${this.connectionAlias})`);
+            return;
+        }
+        this.state = 'reconnecting';
+        this.reconnectAttempts++;
+        const backoff = Math.min(1000 * Math.pow(2, this.reconnectAttempts), 30_000);
+        log.info(`Reconnecting ${this.connectionAlias} in ${backoff}ms ` +
+            `(attempt ${this.reconnectAttempts}/${this.maxReconnectAttempts})`);
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            // Must re-fetch a new WebSocket URL each time — Slack URLs are single-use
+            void this.openConnection();
+        }, backoff);
+    }
+    // ── Helpers ───────────────────────────────────────────────────────
+    send(data) {
+        if (this.ws?.readyState === WebSocket.OPEN) {
+            this.ws.send(JSON.stringify(data));
+        }
+    }
+    clearReconnectTimer() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+    }
+}
+// ── Self-registration ────────────────────────────────────────────────────
+registerIngestorFactory('websocket:slack', (connectionAlias, config, secrets, bufferSize) => {
+    if (!config.websocket) {
+        log.error(`Missing websocket config for ${connectionAlias}`);
+        return null;
+    }
+    return new SlackSocketModeIngestor(connectionAlias, secrets, config.websocket, bufferSize);
+});
+//# sourceMappingURL=socket-mode.js.map

package/dist/remote/ingestors/slack/types.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Slack-specific types and constants for the Socket Mode ingestor.
+ *
+ * @see https://docs.slack.dev/apis/events-api/using-socket-mode
+ */
+/** Top-level message types received over the Socket Mode WebSocket. */
+export type SlackMessageType = 'hello' | 'events_api' | 'slash_commands' | 'interactive' | 'disconnect';
+/** Reasons a Socket Mode disconnect message may be sent. */
+export type SlackDisconnectReason = 'link_disabled' | 'warning' | 'refresh_requested';
+/**
+ * Envelope wrapper for all Socket Mode messages.
+ * Every non-hello/disconnect message has an `envelope_id` that must be acknowledged.
+ */
+export interface SlackEnvelope {
+    /** Message type — determines how to process the payload. */
+    type: SlackMessageType;
+    /** Unique ID for this envelope. Send it back to acknowledge receipt. */
+    envelope_id?: string;
+    /** The actual event/command/interaction payload. */
+    payload?: unknown;
+    /** Whether Slack accepts a response payload in the acknowledgment. */
+    accepts_response_payload?: boolean;
+}
+/** Hello message received immediately after WebSocket connection. */
+export interface SlackHello {
+    type: 'hello';
+    connection_info: {
+        app_id: string;
+    };
+    num_connections: number;
+    debug_info: {
+        host: string;
+        started: string;
+        build_number: number;
+        /** Approximate seconds until this connection will be refreshed. */
+        approximate_connection_time: number;
+    };
+}
+/** Disconnect message sent by Slack before closing the connection. */
+export interface SlackDisconnect {
+    type: 'disconnect';
+    reason: SlackDisconnectReason;
+    debug_info: {
+        host: string;
+    };
+}
+/** Shape of the `apps.connections.open` API response. */
+export interface SlackConnectionsOpenResponse {
+    ok: boolean;
+    url?: string;
+    error?: string;
+}
+/**
+ * Extract the Slack event type from an envelope payload.
+ * For `events_api` envelopes, the event type is at `payload.event.type`.
+ * For `slash_commands`, we use the command name.
+ * For `interactive`, we use the interaction type.
+ */
+export declare function extractSlackEventType(envelope: SlackEnvelope): string;
+/**
+ * Extract a channel ID from a Slack envelope payload.
+ * Checks `payload.event.channel`, `payload.channel_id`, and `payload.channel.id`.
+ */
+export declare function extractSlackChannelId(envelope: SlackEnvelope): string | undefined;
+/**
+ * Extract a user ID from a Slack envelope payload.
+ * Checks `payload.event.user`, `payload.user_id`, and `payload.user.id`.
+ */
+export declare function extractSlackUserId(envelope: SlackEnvelope): string | undefined;
+//# sourceMappingURL=types.d.ts.map

package/dist/remote/ingestors/slack/types.js

@@ -0,0 +1,72 @@
+/**
+ * Slack-specific types and constants for the Socket Mode ingestor.
+ *
+ * @see https://docs.slack.dev/apis/events-api/using-socket-mode
+ */
+// ── Payload helpers ─────────────────────────────────────────────────────
+/**
+ * Extract the Slack event type from an envelope payload.
+ * For `events_api` envelopes, the event type is at `payload.event.type`.
+ * For `slash_commands`, we use the command name.
+ * For `interactive`, we use the interaction type.
+ */
+export function extractSlackEventType(envelope) {
+    const payload = envelope.payload;
+    if (!payload)
+        return envelope.type;
+    switch (envelope.type) {
+        case 'events_api': {
+            const event = payload.event;
+            return typeof event?.type === 'string' ? event.type : 'events_api';
+        }
+        case 'slash_commands':
+            return typeof payload.command === 'string' ? payload.command : 'slash_command';
+        case 'interactive':
+            return typeof payload.type === 'string' ? payload.type : 'interactive';
+        default:
+            return envelope.type;
+    }
+}
+/**
+ * Extract a channel ID from a Slack envelope payload.
+ * Checks `payload.event.channel`, `payload.channel_id`, and `payload.channel.id`.
+ */
+export function extractSlackChannelId(envelope) {
+    const payload = envelope.payload;
+    if (!payload)
+        return undefined;
+    // events_api: event.channel
+    const event = payload.event;
+    if (typeof event?.channel === 'string')
+        return event.channel;
+    // slash_commands / interactive: channel_id
+    if (typeof payload.channel_id === 'string')
+        return payload.channel_id;
+    // interactive: channel.id
+    const channel = payload.channel;
+    if (typeof channel?.id === 'string')
+        return channel.id;
+    return undefined;
+}
+/**
+ * Extract a user ID from a Slack envelope payload.
+ * Checks `payload.event.user`, `payload.user_id`, and `payload.user.id`.
+ */
+export function extractSlackUserId(envelope) {
+    const payload = envelope.payload;
+    if (!payload)
+        return undefined;
+    // events_api: event.user
+    const event = payload.event;
+    if (typeof event?.user === 'string')
+        return event.user;
+    // slash_commands / interactive: user_id
+    if (typeof payload.user_id === 'string')
+        return payload.user_id;
+    // interactive: user.id
+    const user = payload.user;
+    if (typeof user?.id === 'string')
+        return user.id;
+    return undefined;
+}
+//# sourceMappingURL=types.js.map