@artflo-ai/artflo-openclaw-plugin 0.0.1

package/dist/src/core/canvas/canvas-session-manager.js

@@ -0,0 +1,189 @@
+import { EventEmitter } from 'node:events';
+import { CanvasWebSocketClient } from './canvas-websocket-client.js';
+export class CanvasSessionManager extends EventEmitter {
+    sessionKey;
+    config;
+    client = null;
+    elements = new Map();
+    connectionParams = null;
+    isConnected = false;
+    isConnecting = false;
+    intentionalClose = false;
+    reconnectAttempts = 0;
+    constructor(sessionKey, config) {
+        super();
+        this.sessionKey = sessionKey;
+        this.config = config;
+    }
+    async connect(params) {
+        if (this.isConnected || this.isConnecting) {
+            return this.getElements();
+        }
+        this.isConnecting = true;
+        this.intentionalClose = false;
+        this.connectionParams = params;
+        try {
+            this.client = new CanvasWebSocketClient(this.config);
+            this.setupEventListeners();
+            const canvasDoc = await this.client.connect(params);
+            this.elements.clear();
+            Object.values(canvasDoc.elements).forEach((element) => {
+                this.elements.set(element.id, element);
+            });
+            this.isConnected = true;
+            this.isConnecting = false;
+            this.reconnectAttempts = 0;
+            return this.getElements();
+        }
+        catch (error) {
+            this.isConnecting = false;
+            throw error;
+        }
+    }
+    getConnectionState() {
+        return {
+            sessionKey: this.sessionKey,
+            canvasId: this.connectionParams?.canvasId ?? null,
+            isConnected: this.isConnected,
+            isConnecting: this.isConnecting,
+            elementCount: this.elements.size,
+            reconnectAttempts: this.reconnectAttempts,
+            clientState: this.client?.getConnectionState() ?? null,
+        };
+    }
+    getElements() {
+        return Array.from(this.elements.values());
+    }
+    getElement(id) {
+        return this.elements.get(id);
+    }
+    getCanvasConfig() {
+        return this.client?.getCanvasConfig() ?? null;
+    }
+    async addElements(elements) {
+        this.ensureConnected();
+        await this.client.addElements(elements);
+        elements.forEach((element) => this.elements.set(element.id, element));
+    }
+    async changeElements(changes) {
+        this.ensureConnected();
+        await this.client.changeElements(changes);
+        changes.forEach((change) => {
+            if (!change.id)
+                return;
+            const existing = this.elements.get(change.id);
+            if (!existing)
+                return;
+            const updated = { ...existing, ...change };
+            if (existing.data && change.data) {
+                updated.data = { ...existing.data, ...change.data };
+            }
+            this.elements.set(change.id, updated);
+        });
+    }
+    async deleteElements(ids) {
+        this.ensureConnected();
+        await this.client.removeElements(ids);
+        ids.forEach((id) => this.elements.delete(id));
+    }
+    async executeNodes(nodeIds) {
+        this.ensureConnected();
+        await this.client.executeNodes(nodeIds);
+    }
+    async waitForCompletion(nodeIds, timeout = 300_000) {
+        this.ensureConnected();
+        try {
+            await Promise.all(nodeIds.map((id) => this.client.waitForStatus(id, 3, timeout)));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async waitForStatus(nodeId, status, timeout = 300_000) {
+        this.ensureConnected();
+        try {
+            await this.client.waitForStatus(nodeId, status, timeout);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    disconnect() {
+        this.intentionalClose = true;
+        this.isConnected = false;
+        this.isConnecting = false;
+        if (this.client) {
+            this.client.disconnect();
+            this.client.removeAllListeners();
+            this.client = null;
+        }
+        this.elements.clear();
+    }
+    ensureConnected() {
+        if (!this.client || !this.isConnected) {
+            throw new Error('Not connected');
+        }
+    }
+    setupEventListeners() {
+        if (!this.client)
+            return;
+        this.client.on('element:add', (element) => {
+            this.elements.set(element.id, element);
+        });
+        this.client.on('element:change', (element) => {
+            this.elements.set(element.id, element);
+        });
+        this.client.on('element:delete', (id) => {
+            this.elements.delete(id);
+        });
+        this.client.on('close', () => {
+            this.isConnected = false;
+            if (!this.intentionalClose) {
+                void this.attemptReconnect();
+            }
+        });
+        this.client.on('error', () => {
+            // error is usually followed by close, but guard against edge cases
+            // where close doesn't fire.
+            this.isConnected = false;
+        });
+    }
+    async attemptReconnect() {
+        if (this.intentionalClose || !this.connectionParams) {
+            return;
+        }
+        if (this.reconnectAttempts >= this.config.maxReconnectAttempts) {
+            this.emit('reconnect:failed');
+            return;
+        }
+        this.reconnectAttempts += 1;
+        const delay = Math.min(1_000 * Math.pow(2, this.reconnectAttempts - 1), 30_000);
+        void this.trace(`reconnect attempt ${this.reconnectAttempts}/${this.config.maxReconnectAttempts} in ${delay}ms`);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        if (this.intentionalClose)
+            return;
+        try {
+            // Tear down the old client so connect() doesn't bail on the isConnecting guard.
+            if (this.client) {
+                this.client.removeAllListeners();
+                this.client = null;
+            }
+            this.isConnected = false;
+            this.isConnecting = false;
+            await this.connect(this.connectionParams);
+            void this.trace('reconnect:success');
+            this.emit('reconnect:success');
+        }
+        catch {
+            void this.trace('reconnect:attempt_failed');
+            await this.attemptReconnect();
+        }
+    }
+    trace(event) {
+        // Lightweight internal trace — goes to stderr so it doesn't pollute tool output.
+        const ts = new Date().toISOString();
+        process.stderr.write(`[CanvasSession:${this.sessionKey}] ${ts} ${event}\n`);
+    }
+}

package/dist/src/core/canvas/canvas-websocket-client.js

@@ -0,0 +1,453 @@
+import { EventEmitter } from 'node:events';
+import WebSocket from 'ws';
+import { getCanvasWsUrl } from '../api/api-base.js';
+import { writeWsTrace } from './ws-trace.js';
+import { WS_ERROR, isJoinErrorMessage, isJoinSuccessMessage, isPushErrorMessage, isPushSuccessMessage, isSyncPushMessage, } from './types.js';
+export class CanvasWebSocketClient extends EventEmitter {
+    config;
+    ws = null;
+    clientId = 0;
+    clock = 0;
+    connected = false;
+    connecting = false;
+    currentApiKey = '';
+    currentCanvasId = '';
+    elements = new Map();
+    canvasConfig = null;
+    /** Heartbeat interval handle — sends ping every 30s to keep the connection alive. */
+    heartbeatTimer = null;
+    /** Fires if we don't receive a pong within 10s of a ping. */
+    pongTimeout = null;
+    static HEARTBEAT_INTERVAL_MS = 30_000;
+    static PONG_TIMEOUT_MS = 10_000;
+    constructor(config) {
+        super();
+        this.config = config;
+    }
+    buildWebSocketUrl(params) {
+        const queryParams = new URLSearchParams();
+        queryParams.set('app_key', params.appKey || this.config.appKey);
+        queryParams.set('device_id', params.deviceId || this.config.deviceId);
+        queryParams.set('time_zone', params.timeZone || this.config.timeZone);
+        queryParams.set('oper_system', params.operSystem || this.config.operSystem);
+        queryParams.set('country_code', params.countryCode || this.config.countryCode);
+        queryParams.set('api_key', params.apiKey || this.config.apiKey);
+        queryParams.set('canvas_id', params.canvasId);
+        return `${getCanvasWsUrl(this.config)}?${queryParams.toString()}`;
+    }
+    async connect(params) {
+        if (this.connected) {
+            this.disconnect();
+        }
+        this.connecting = true;
+        this.currentCanvasId = params.canvasId;
+        this.currentApiKey = params.apiKey || this.config.apiKey;
+        const wsUrl = this.buildWebSocketUrl(params);
+        void this.trace('lifecycle', 'connect:start', {
+            canvasId: params.canvasId,
+            wsUrl,
+        });
+        return new Promise((resolve, reject) => {
+            try {
+                this.ws = new WebSocket(wsUrl);
+                this.ws.on('open', () => {
+                    void this.trace('lifecycle', 'socket:open', {
+                        canvasId: params.canvasId,
+                    });
+                    this.send({
+                        type: 'join',
+                        join_canvas_id: params.canvasId,
+                    });
+                });
+                this.ws.on('message', (data) => {
+                    try {
+                        void this.trace('inbound', 'socket:message_raw', {
+                            raw: data.toString(),
+                        });
+                        const message = JSON.parse(data.toString());
+                        this.handleMessage(message, resolve, reject);
+                    }
+                    catch (error) {
+                        void this.trace('lifecycle', 'socket:message_parse_error', {
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                        reject(error instanceof Error
+                            ? error
+                            : new Error(String(error)));
+                    }
+                });
+                // Reset pong timeout on every pong frame — connection is alive.
+                this.ws.on('pong', () => {
+                    this.clearPongTimeout();
+                });
+                this.ws.on('close', () => {
+                    this.stopHeartbeat();
+                    this.connected = false;
+                    this.connecting = false;
+                    void this.trace('lifecycle', 'socket:close', {
+                        canvasId: this.currentCanvasId,
+                    });
+                    this.emit('close');
+                });
+                this.ws.on('error', (error) => {
+                    this.stopHeartbeat();
+                    this.connected = false;
+                    this.connecting = false;
+                    void this.trace('lifecycle', 'socket:error', {
+                        canvasId: this.currentCanvasId,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                    reject(error instanceof Error ? error : new Error(String(error)));
+                });
+            }
+            catch (error) {
+                this.connected = false;
+                this.connecting = false;
+                void this.trace('lifecycle', 'connect:exception', {
+                    canvasId: params.canvasId,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+    }
+    disconnect() {
+        this.stopHeartbeat();
+        if (this.ws) {
+            this.send({ type: 'leave' });
+            this.ws.close();
+            this.ws = null;
+        }
+        void this.trace('lifecycle', 'disconnect', {
+            canvasId: this.currentCanvasId,
+        });
+        this.connected = false;
+        this.connecting = false;
+        this.clientId = 0;
+        this.clock = 0;
+        this.currentCanvasId = '';
+        this.elements.clear();
+    }
+    async addElements(elements) {
+        await this.push([{ type: 'element:add', elements }]);
+        elements.forEach((element) => this.elements.set(element.id, element));
+    }
+    async changeElements(changes) {
+        await this.push([{ type: 'element:change', elements: changes }]);
+        changes.forEach((change) => {
+            if (!change.id)
+                return;
+            const existing = this.elements.get(change.id);
+            if (!existing)
+                return;
+            const updated = { ...existing, ...change };
+            if (existing.data && change.data) {
+                updated.data = { ...existing.data, ...change.data };
+            }
+            this.elements.set(change.id, updated);
+        });
+    }
+    async removeElements(elementIds) {
+        await this.push([{ type: 'element:delete', delete_elements: elementIds }]);
+        elementIds.forEach((id) => this.elements.delete(id));
+    }
+    async executeNodes(targetIds, position) {
+        if (!this.connected || !this.ws) {
+            throw new Error('Not connected to canvas');
+        }
+        const message = {
+            type: 'push',
+            order_op_data: {
+                batch_targets: targetIds,
+                position,
+            },
+            api_key: this.currentApiKey || this.config.apiKey,
+        };
+        this.send(message);
+    }
+    getElement(id) {
+        return this.elements.get(id);
+    }
+    getAllElements() {
+        return this.elements;
+    }
+    getCanvasConfig() {
+        return this.canvasConfig;
+    }
+    getConnectionState() {
+        return {
+            connected: this.connected,
+            connecting: this.connecting,
+            clock: this.clock,
+            clientId: this.clientId,
+        };
+    }
+    waitForStatus(elementId, targetStatus, timeout = 300_000) {
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const cleanup = () => {
+                this.removeListener('element:change', onElementChange);
+                clearTimeout(timer);
+            };
+            const onElementChange = (element) => {
+                if (settled || element.id !== elementId)
+                    return;
+                checkStatus();
+            };
+            const checkStatus = () => {
+                const element = this.elements.get(elementId);
+                if (!element)
+                    return;
+                const currentStatus = element.data.status;
+                if (currentStatus === targetStatus) {
+                    settled = true;
+                    cleanup();
+                    resolve(element);
+                }
+                else if (currentStatus === 400) {
+                    settled = true;
+                    cleanup();
+                    reject(new Error(`Element ${elementId} execution failed (status 400)`));
+                }
+            };
+            // Check synchronously first — element may already be in the target state.
+            checkStatus();
+            if (settled)
+                return;
+            this.on('element:change', onElementChange);
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                reject(new Error(`Timeout waiting for element ${elementId} status ${targetStatus}`));
+            }, timeout);
+        });
+    }
+    send(message) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            void this.trace('lifecycle', 'send:skipped_not_open', {
+                canvasId: this.currentCanvasId,
+                message,
+            });
+            return;
+        }
+        void this.trace('outbound', `send:${message.type}`, {
+            canvasId: this.currentCanvasId,
+            message,
+        });
+        this.ws.send(JSON.stringify(message));
+    }
+    async push(operations, retries = 3) {
+        if (!this.connected || !this.ws) {
+            throw new Error('Not connected to canvas');
+        }
+        this.clock += 1;
+        const message = {
+            type: 'push',
+            push_op_data: {
+                clock: this.clock,
+                op_infos: operations,
+            },
+        };
+        void this.trace('outbound', 'push:operations', {
+            canvasId: this.currentCanvasId,
+            operations,
+            clock: this.clock,
+            retries,
+        });
+        const attempt = (attemptsLeft) => new Promise((resolve, reject) => {
+            const onMessage = (msg) => {
+                if (isPushSuccessMessage(msg)) {
+                    void this.trace('inbound', 'push:success', {
+                        canvasId: this.currentCanvasId,
+                        message: msg,
+                    });
+                    this.clock = msg.clock;
+                    this.removeListener('message', onMessage);
+                    clearTimeout(timer);
+                    resolve();
+                    return;
+                }
+                if (isPushErrorMessage(msg)) {
+                    void this.trace('inbound', 'push:error', {
+                        canvasId: this.currentCanvasId,
+                        message: msg,
+                        attemptsLeft,
+                    });
+                    this.removeListener('message', onMessage);
+                    clearTimeout(timer);
+                    const error = new Error(msg.err_message || 'Push error');
+                    if (attemptsLeft > 1) {
+                        setTimeout(() => attempt(attemptsLeft - 1).then(resolve, reject), (4 - attemptsLeft) * 2_000);
+                    }
+                    else {
+                        reject(error);
+                    }
+                }
+            };
+            this.on('message', onMessage);
+            this.send(message);
+            const timer = setTimeout(() => {
+                this.removeListener('message', onMessage);
+                void this.trace('lifecycle', 'push:timeout', {
+                    canvasId: this.currentCanvasId,
+                    attemptsLeft,
+                    clock: this.clock,
+                });
+                if (attemptsLeft > 1) {
+                    setTimeout(() => attempt(attemptsLeft - 1).then(resolve, reject), (4 - attemptsLeft) * 2_000);
+                }
+                else {
+                    reject(new Error('Push timeout'));
+                }
+            }, this.config.requestTimeoutMs);
+        });
+        return attempt(retries);
+    }
+    handleMessage(message, joinResolve, joinReject) {
+        void this.trace('inbound', `message:${message.type}`, {
+            canvasId: this.currentCanvasId,
+            message,
+        });
+        this.emit('message', message);
+        if (isJoinSuccessMessage(message)) {
+            this.connected = true;
+            this.connecting = false;
+            this.clientId = message.client_id;
+            this.clock = message.canvas_doc.clock;
+            this.elements.clear();
+            Object.entries(message.canvas_doc.elements).forEach(([id, element]) => {
+                this.elements.set(id, element);
+            });
+            if (message.canvas_config) {
+                this.canvasConfig = message.canvas_config;
+            }
+            else if (message.canvas_config) {
+                this.canvasConfig = message.canvas_config;
+            }
+            void this.trace('lifecycle', 'join:success', {
+                canvasId: this.currentCanvasId,
+                clientId: this.clientId,
+                clock: this.clock,
+                elementCount: this.elements.size,
+                hasCanvasConfig: this.canvasConfig !== null,
+            });
+            this.startHeartbeat();
+            joinResolve?.(message.canvas_doc);
+            return;
+        }
+        if (isJoinErrorMessage(message)) {
+            this.connecting = false;
+            void this.trace('lifecycle', 'join:error', {
+                canvasId: this.currentCanvasId,
+                message,
+            });
+            joinReject?.(new Error(this.getErrorMessage(message.err_code)));
+            return;
+        }
+        if (isSyncPushMessage(message)) {
+            this.handleSyncPush(message.ops_data);
+        }
+    }
+    handleSyncPush(opsData) {
+        void this.trace('inbound', 'sync_push:ops', {
+            canvasId: this.currentCanvasId,
+            opsData,
+        });
+        for (const ops of opsData) {
+            if (ops.client_id === this.clientId)
+                continue;
+            for (const op of ops.op_infos) {
+                if (op.type === 'element:add') {
+                    op.elements.forEach((element) => {
+                        this.elements.set(element.id, element);
+                        this.emit('element:add', element);
+                    });
+                }
+                if (op.type === 'element:change') {
+                    op.elements.forEach((change) => {
+                        if (!change.id)
+                            return;
+                        const existing = this.elements.get(change.id);
+                        if (!existing)
+                            return;
+                        const updated = { ...existing, ...change };
+                        if (existing.data && change.data) {
+                            updated.data = { ...existing.data, ...change.data };
+                        }
+                        this.elements.set(change.id, updated);
+                        this.emit('element:change', updated);
+                    });
+                }
+                if (op.type === 'element:delete') {
+                    op.delete_elements.forEach((id) => {
+                        this.elements.delete(id);
+                        this.emit('element:delete', id);
+                    });
+                }
+            }
+            if (ops.clock > this.clock) {
+                this.clock = ops.clock;
+            }
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Heartbeat — keeps the WebSocket alive by sending periodic pings.
+    // If the server doesn't respond with a pong within PONG_TIMEOUT_MS we
+    // consider the connection dead and force-close so the reconnect logic kicks in.
+    // ---------------------------------------------------------------------------
+    startHeartbeat() {
+        this.stopHeartbeat();
+        this.heartbeatTimer = setInterval(() => {
+            if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
+                return;
+            this.ws.ping();
+            void this.trace('lifecycle', 'heartbeat:ping', {
+                canvasId: this.currentCanvasId,
+            });
+            // If no pong comes back in time, terminate the socket so 'close' fires.
+            this.pongTimeout = setTimeout(() => {
+                void this.trace('lifecycle', 'heartbeat:pong_timeout', {
+                    canvasId: this.currentCanvasId,
+                });
+                this.ws?.terminate();
+            }, CanvasWebSocketClient.PONG_TIMEOUT_MS);
+        }, CanvasWebSocketClient.HEARTBEAT_INTERVAL_MS);
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        this.clearPongTimeout();
+    }
+    clearPongTimeout() {
+        if (this.pongTimeout) {
+            clearTimeout(this.pongTimeout);
+            this.pongTimeout = null;
+        }
+    }
+    async trace(direction, event, payload) {
+        await writeWsTrace({
+            canvasId: this.currentCanvasId || undefined,
+            direction,
+            event,
+            payload,
+        });
+    }
+    getErrorMessage(code) {
+        switch (code) {
+            case WS_ERROR.DOCUMENT_NOT_EXISTS:
+                return 'Canvas not found';
+            case WS_ERROR.DOCUMENT_NOT_AUTHORIZED:
+                return 'Not authorized to access canvas';
+            case WS_ERROR.DOCUMENT_IS_DELETED:
+                return 'Canvas has been deleted';
+            case WS_ERROR.AUTHENTICATION_FAILED:
+                return 'Authentication failed';
+            default:
+                return `Unknown error: ${code}`;
+        }
+    }
+}

package/dist/src/core/canvas/create-canvas.js

@@ -0,0 +1,37 @@
+/**
+ * Create a new Artflo canvas via the REST API.
+ *
+ * Derives the HTTP API base URL from the configured WebSocket URL:
+ *   wss://prewebapi.artflo.ai/canvas/ws → https://prewebapi.artflo.ai
+ *   wss://webapi.artflo.ai/canvas/ws    → https://webapi.artflo.ai
+ */
+import { getApiBaseUrl } from '../api/api-base.js';
+export async function createCanvas(config, name = 'Untitled') {
+    const baseUrl = getApiBaseUrl(config);
+    const response = await fetch(`${baseUrl}/canvas`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'X-API-Key': config.apiKey,
+        },
+        body: JSON.stringify({ name, belong_type: 0 }),
+    });
+    if (!response.ok) {
+        throw new Error(`Create canvas failed: HTTP ${response.status}`);
+    }
+    const body = (await response.json());
+    if (body.code !== 0 || !body.data?.id) {
+        throw new Error(`Create canvas failed: code=${body.code}`);
+    }
+    const canvasId = body.data.id;
+    // Derive project URL from API host: prewebapi → pre.artflo.ai, webapi → artflo.ai
+    const hostname = new URL(baseUrl).hostname;
+    const projectHost = hostname.startsWith('prewebapi')
+        ? 'pre.artflo.ai'
+        : 'artflo.ai';
+    return {
+        id: canvasId,
+        name: body.data.name ?? name,
+        url: `https://${projectHost}/project/${canvasId}`,
+    };
+}

package/dist/src/core/canvas/types.js

@@ -0,0 +1,23 @@
+export function isJoinSuccessMessage(msg) {
+    return msg.type === 'join:success';
+}
+export function isJoinErrorMessage(msg) {
+    return msg.type === 'join:error';
+}
+export function isPushSuccessMessage(msg) {
+    return msg.type === 'push:success';
+}
+export function isPushErrorMessage(msg) {
+    return msg.type === 'push:error';
+}
+export function isSyncPushMessage(msg) {
+    return msg.type === 'sync_push:success';
+}
+export const WS_ERROR = {
+    DOCUMENT_NOT_EXISTS: 12001,
+    CLIENT_NOT_EXISTS: 12002,
+    DOCUMENT_NOT_AUTHORIZED: 12004,
+    DOCUMENT_IS_DELETED: 12005,
+    SYSTEM_ERROR: 11002,
+    AUTHENTICATION_FAILED: 20000,
+};