@artflo-ai/artflo-openclaw-plugin 0.0.1

package/README.md

@@ -0,0 +1,102 @@
+# Artflo OpenClaw Plugin
+
+OpenClaw plugin for Artflo canvas operations over direct WebSocket.
+
+## Quick Start
+
+### Install
+
+```bash
+openclaw plugins install @artflo-ai/artflo-openclaw-plugin
+openclaw plugins enable artflo-openclaw-plugin
+openclaw gateway restart
+```
+
+### Configure
+
+Only one required parameter: `apiKey`.
+
+The easiest way: just start chatting. The plugin will detect missing API Key
+and guide you through setup in the conversation.
+
+Or manually edit `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "artflo-openclaw-plugin": {
+    "enabled": true,
+    "config": {
+      "apiKey": "YOUR_API_KEY"
+    }
+  }
+}
+```
+
+Get your API Key from [artflo.ai](https://artflo.ai) settings page.
+
+### Switch Environment
+
+Default is `release` (production). For test environment:
+
+```json
+{
+  "config": {
+    "env": "test",
+    "apiKey": "YOUR_API_KEY"
+  }
+}
+```
+
+## Configuration
+
+| Parameter | Required | Default | Description |
+|---|---|---|---|
+| `apiKey` | Yes | — | Artflo API Key |
+| `env` | No | `release` | `release` (production) or `test` |
+| `operSystem` | No | `7` | Client OS identifier |
+
+Other parameters (`appKey`, `deviceId`, `timeZone`, `countryCode`, etc.)
+are auto-detected or fetched from the Artflo API at startup.
+
+## Tools
+
+- `artflo_canvas_connect` — Connect to canvas WebSocket
+- `artflo_canvas_connection_status` — Check connection status
+- `artflo_canvas_get_state` — Get canvas state
+- `artflo_canvas_get_config` — Get available models and config
+- `artflo_canvas_get_node` — Read a single node
+- `artflo_canvas_find_nodes` — Search nodes
+- `artflo_canvas_change_elements` — Modify nodes
+- `artflo_canvas_delete_elements` — Delete nodes
+- `artflo_canvas_run_nodes` — Execute nodes
+- `artflo_canvas_wait_for_completion` — Wait for node completion
+- `artflo_canvas_execute_plan` — Execute a structured workflow plan
+- `artflo_canvas_create` — Create a new canvas
+- `artflo_canvas_list_models` — List available models with pricing
+- `artflo_upload_file` — Upload files to Artflo storage
+- `artflo_set_api_key` — Save API Key to config (used in chat onboarding)
+
+## Local Development
+
+```bash
+git clone <repo-url>
+cd artflo-openclaw-ws-plugin
+pnpm install
+pnpm check          # type check only
+pnpm build          # compile to dist/
+```
+
+### Link for local testing
+
+```bash
+openclaw plugins install -l .
+openclaw plugins enable artflo-openclaw-plugin
+openclaw gateway restart
+```
+
+## Publish
+
+```bash
+pnpm build
+npm publish
+```

package/dist/index.js

@@ -0,0 +1,73 @@
+import { createPluginConfig } from './src/config.js';
+import { createSessionRegistryService } from './src/services/canvas-session-registry.js';
+import { registerArtfloTools } from './src/tools/register-tools.js';
+import { fetchClientParams } from './src/core/config/fetch-client-params.js';
+import { PLUGIN_DESCRIPTION, PLUGIN_ID, PLUGIN_NAME } from './src/constants.js';
+const pluginConfigSchema = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        env: {
+            type: 'string',
+            enum: ['release', 'test'],
+            default: 'release',
+            description: 'Environment: release (production) or test.',
+        },
+        apiKey: {
+            type: 'string',
+            description: 'Artflo API Key for authentication. Get it from https://artflo.ai/settings.',
+        },
+        operSystem: {
+            type: 'string',
+            default: '7',
+            description: 'Client oper_system identifier for WebSocket connections.',
+        },
+    },
+};
+const plugin = {
+    id: PLUGIN_ID,
+    name: PLUGIN_NAME,
+    description: PLUGIN_DESCRIPTION,
+    configSchema: pluginConfigSchema,
+    async register(api) {
+        const config = createPluginConfig(api);
+        // ── 没有 apiKey 时跳过所有初始化，只注册 tool（tool 内部会检查 apiKey）──
+        if (!config.apiKey) {
+            console.log(`[artflo] API Key not configured. Skipping initialization.`);
+            const sessions = createSessionRegistryService(config);
+            api.registerService(sessions.service);
+            registerArtfloTools(api, { config, sessions: sessions.registry });
+            return;
+        }
+        // ── 自动获取 appKey / vipAppId / vipGroup ─────────────────────────
+        if (!config.appKey || !config.vipAppId || !config.vipGroup) {
+            try {
+                const params = await fetchClientParams(config.webApiBaseUrl);
+                if (!config.appKey)
+                    config.appKey = params.appKey;
+                if (!config.vipAppId)
+                    config.vipAppId = params.vipAppId;
+                if (!config.vipGroup)
+                    config.vipGroup = params.vipGroup;
+                console.log(`[artflo] client params fetched: appKey=${config.appKey}, env=${config.env}`);
+            }
+            catch (err) {
+                console.warn(`[artflo] Failed to fetch client params, using defaults:`, err instanceof Error ? err.message : String(err));
+                if (!config.appKey)
+                    config.appKey = 'A40CB4D42E28F808';
+                if (!config.vipAppId)
+                    config.vipAppId = '7029803307044000000';
+                if (!config.vipGroup)
+                    config.vipGroup = 'group_artflo';
+            }
+        }
+        console.log(`[artflo] env=${config.env}, api=${config.apiBaseUrl}`);
+        const sessions = createSessionRegistryService(config);
+        api.registerService(sessions.service);
+        registerArtfloTools(api, {
+            config,
+            sessions: sessions.registry,
+        });
+    },
+};
+export default plugin;

package/dist/logs/ws-traffic-traces/2026-03-27T20-30-00-216Z+08-lifecycle-heartbeat_ping-2b637466-6c6f-6172-470c-151459021b0a.json

@@ -0,0 +1,9 @@
+{
+  "createdAt": "2026-03-27T12:30:00.217Z",
+  "direction": "lifecycle",
+  "event": "heartbeat:ping",
+  "canvasId": "2b637466-6c6f-6172-470c-151459021b0a",
+  "payload": {
+    "canvasId": "2b637466-6c6f-6172-470c-151459021b0a"
+  }
+}

package/dist/logs/ws-traffic-traces/2026-03-27T20-30-00-217Z+08-lifecycle-heartbeat_ping-2d637466-6c6f-6172-410c-15145f021b0a.json

@@ -0,0 +1,9 @@
+{
+  "createdAt": "2026-03-27T12:30:00.217Z",
+  "direction": "lifecycle",
+  "event": "heartbeat:ping",
+  "canvasId": "2d637466-6c6f-6172-410c-15145f021b0a",
+  "payload": {
+    "canvasId": "2d637466-6c6f-6172-410c-15145f021b0a"
+  }
+}

package/dist/logs/ws-traffic-traces/2026-03-27T20-30-05-727Z+08-lifecycle-heartbeat_ping-2c637466-6c6f-6172-400c-15145e021b0a.json

@@ -0,0 +1,9 @@
+{
+  "createdAt": "2026-03-27T12:30:05.728Z",
+  "direction": "lifecycle",
+  "event": "heartbeat:ping",
+  "canvasId": "2c637466-6c6f-6172-400c-15145e021b0a",
+  "payload": {
+    "canvasId": "2c637466-6c6f-6172-400c-15145e021b0a"
+  }
+}

package/dist/logs/ws-traffic-traces/2026-03-27T20-30-30-218Z+08-lifecycle-heartbeat_ping-2b637466-6c6f-6172-470c-151459021b0a.json

@@ -0,0 +1,9 @@
+{
+  "createdAt": "2026-03-27T12:30:30.218Z",
+  "direction": "lifecycle",
+  "event": "heartbeat:ping",
+  "canvasId": "2b637466-6c6f-6172-470c-151459021b0a",
+  "payload": {
+    "canvasId": "2b637466-6c6f-6172-470c-151459021b0a"
+  }
+}

package/dist/logs/ws-traffic-traces/2026-03-27T20-30-30-218Z+08-lifecycle-heartbeat_ping-2d637466-6c6f-6172-410c-15145f021b0a.json

@@ -0,0 +1,9 @@
+{
+  "createdAt": "2026-03-27T12:30:30.218Z",
+  "direction": "lifecycle",
+  "event": "heartbeat:ping",
+  "canvasId": "2d637466-6c6f-6172-410c-15145f021b0a",
+  "payload": {
+    "canvasId": "2d637466-6c6f-6172-410c-15145f021b0a"
+  }
+}

package/dist/logs/ws-traffic-traces/2026-03-27T20-30-35-728Z+08-lifecycle-heartbeat_ping-2c637466-6c6f-6172-400c-15145e021b0a.json

@@ -0,0 +1,9 @@
+{
+  "createdAt": "2026-03-27T12:30:35.728Z",
+  "direction": "lifecycle",
+  "event": "heartbeat:ping",
+  "canvasId": "2c637466-6c6f-6172-400c-15145e021b0a",
+  "payload": {
+    "canvasId": "2c637466-6c6f-6172-400c-15145e021b0a"
+  }
+}

package/dist/logs/ws-traffic-traces/2026-03-27T20-31-00-218Z+08-lifecycle-heartbeat_ping-2b637466-6c6f-6172-470c-151459021b0a.json

@@ -0,0 +1,9 @@
+{
+  "createdAt": "2026-03-27T12:31:00.219Z",
+  "direction": "lifecycle",
+  "event": "heartbeat:ping",
+  "canvasId": "2b637466-6c6f-6172-470c-151459021b0a",
+  "payload": {
+    "canvasId": "2b637466-6c6f-6172-470c-151459021b0a"
+  }
+}

package/dist/logs/ws-traffic-traces/2026-03-27T20-31-00-219Z+08-lifecycle-heartbeat_ping-2d637466-6c6f-6172-410c-15145f021b0a.json

@@ -0,0 +1,9 @@
+{
+  "createdAt": "2026-03-27T12:31:00.219Z",
+  "direction": "lifecycle",
+  "event": "heartbeat:ping",
+  "canvasId": "2d637466-6c6f-6172-410c-15145f021b0a",
+  "payload": {
+    "canvasId": "2d637466-6c6f-6172-410c-15145f021b0a"
+  }
+}

package/dist/logs/ws-traffic-traces/2026-03-27T20-31-05-729Z+08-lifecycle-heartbeat_ping-2c637466-6c6f-6172-400c-15145e021b0a.json

@@ -0,0 +1,9 @@
+{
+  "createdAt": "2026-03-27T12:31:05.729Z",
+  "direction": "lifecycle",
+  "event": "heartbeat:ping",
+  "canvasId": "2c637466-6c6f-6172-400c-15145e021b0a",
+  "payload": {
+    "canvasId": "2c637466-6c6f-6172-400c-15145e021b0a"
+  }
+}

package/dist/logs/ws-traffic-traces/2026-03-27T20-31-30-220Z+08-lifecycle-heartbeat_ping-2b637466-6c6f-6172-470c-151459021b0a.json

@@ -0,0 +1,9 @@
+{
+  "createdAt": "2026-03-27T12:31:30.220Z",
+  "direction": "lifecycle",
+  "event": "heartbeat:ping",
+  "canvasId": "2b637466-6c6f-6172-470c-151459021b0a",
+  "payload": {
+    "canvasId": "2b637466-6c6f-6172-470c-151459021b0a"
+  }
+}

package/dist/logs/ws-traffic-traces/2026-03-27T20-31-30-220Z+08-lifecycle-heartbeat_ping-2d637466-6c6f-6172-410c-15145f021b0a.json

@@ -0,0 +1,9 @@
+{
+  "createdAt": "2026-03-27T12:31:30.220Z",
+  "direction": "lifecycle",
+  "event": "heartbeat:ping",
+  "canvasId": "2d637466-6c6f-6172-410c-15145f021b0a",
+  "payload": {
+    "canvasId": "2d637466-6c6f-6172-410c-15145f021b0a"
+  }
+}

package/dist/logs/ws-traffic-traces/2026-03-27T20-31-35-729Z+08-lifecycle-heartbeat_ping-2c637466-6c6f-6172-400c-15145e021b0a.json

@@ -0,0 +1,9 @@
+{
+  "createdAt": "2026-03-27T12:31:35.730Z",
+  "direction": "lifecycle",
+  "event": "heartbeat:ping",
+  "canvasId": "2c637466-6c6f-6172-400c-15145e021b0a",
+  "payload": {
+    "canvasId": "2c637466-6c6f-6172-400c-15145e021b0a"
+  }
+}

package/dist/logs/ws-traffic-traces/2026-03-27T20-32-00-221Z+08-lifecycle-heartbeat_ping-2b637466-6c6f-6172-470c-151459021b0a.json

@@ -0,0 +1,9 @@
+{
+  "createdAt": "2026-03-27T12:32:00.222Z",
+  "direction": "lifecycle",
+  "event": "heartbeat:ping",
+  "canvasId": "2b637466-6c6f-6172-470c-151459021b0a",
+  "payload": {
+    "canvasId": "2b637466-6c6f-6172-470c-151459021b0a"
+  }
+}

package/dist/logs/ws-traffic-traces/2026-03-27T20-32-00-221Z+08-lifecycle-heartbeat_ping-2d637466-6c6f-6172-410c-15145f021b0a.json

@@ -0,0 +1,9 @@
+{
+  "createdAt": "2026-03-27T12:32:00.221Z",
+  "direction": "lifecycle",
+  "event": "heartbeat:ping",
+  "canvasId": "2d637466-6c6f-6172-410c-15145f021b0a",
+  "payload": {
+    "canvasId": "2d637466-6c6f-6172-410c-15145f021b0a"
+  }
+}

package/dist/logs/ws-traffic-traces/2026-03-27T20-32-05-730Z+08-lifecycle-heartbeat_ping-2c637466-6c6f-6172-400c-15145e021b0a.json

@@ -0,0 +1,9 @@
+{
+  "createdAt": "2026-03-27T12:32:05.730Z",
+  "direction": "lifecycle",
+  "event": "heartbeat:ping",
+  "canvasId": "2c637466-6c6f-6172-400c-15145e021b0a",
+  "payload": {
+    "canvasId": "2c637466-6c6f-6172-400c-15145e021b0a"
+  }
+}

package/dist/logs/ws-traffic-traces/2026-03-27T20-32-30-222Z+08-lifecycle-heartbeat_ping-2b637466-6c6f-6172-470c-151459021b0a.json

@@ -0,0 +1,9 @@
+{
+  "createdAt": "2026-03-27T12:32:30.222Z",
+  "direction": "lifecycle",
+  "event": "heartbeat:ping",
+  "canvasId": "2b637466-6c6f-6172-470c-151459021b0a",
+  "payload": {
+    "canvasId": "2b637466-6c6f-6172-470c-151459021b0a"
+  }
+}

package/dist/logs/ws-traffic-traces/2026-03-27T20-32-30-222Z+08-lifecycle-heartbeat_ping-2d637466-6c6f-6172-410c-15145f021b0a.json

@@ -0,0 +1,9 @@
+{
+  "createdAt": "2026-03-27T12:32:30.222Z",
+  "direction": "lifecycle",
+  "event": "heartbeat:ping",
+  "canvasId": "2d637466-6c6f-6172-410c-15145f021b0a",
+  "payload": {
+    "canvasId": "2d637466-6c6f-6172-410c-15145f021b0a"
+  }
+}

package/dist/logs/ws-traffic-traces/2026-03-27T20-32-35-731Z+08-lifecycle-heartbeat_ping-2c637466-6c6f-6172-400c-15145e021b0a.json

@@ -0,0 +1,9 @@
+{
+  "createdAt": "2026-03-27T12:32:35.731Z",
+  "direction": "lifecycle",
+  "event": "heartbeat:ping",
+  "canvasId": "2c637466-6c6f-6172-400c-15145e021b0a",
+  "payload": {
+    "canvasId": "2c637466-6c6f-6172-400c-15145e021b0a"
+  }
+}

package/dist/logs/ws-traffic-traces/2026-03-27T20-33-00-223Z+08-lifecycle-heartbeat_ping-2b637466-6c6f-6172-470c-151459021b0a.json

@@ -0,0 +1,9 @@
+{
+  "createdAt": "2026-03-27T12:33:00.223Z",
+  "direction": "lifecycle",
+  "event": "heartbeat:ping",
+  "canvasId": "2b637466-6c6f-6172-470c-151459021b0a",
+  "payload": {
+    "canvasId": "2b637466-6c6f-6172-470c-151459021b0a"
+  }
+}

package/dist/logs/ws-traffic-traces/2026-03-27T20-33-00-223Z+08-lifecycle-heartbeat_ping-2d637466-6c6f-6172-410c-15145f021b0a.json

@@ -0,0 +1,9 @@
+{
+  "createdAt": "2026-03-27T12:33:00.223Z",
+  "direction": "lifecycle",
+  "event": "heartbeat:ping",
+  "canvasId": "2d637466-6c6f-6172-410c-15145f021b0a",
+  "payload": {
+    "canvasId": "2d637466-6c6f-6172-410c-15145f021b0a"
+  }
+}

package/dist/logs/ws-traffic-traces/2026-03-27T20-33-05-732Z+08-lifecycle-heartbeat_ping-2c637466-6c6f-6172-400c-15145e021b0a.json

@@ -0,0 +1,9 @@
+{
+  "createdAt": "2026-03-27T12:33:05.732Z",
+  "direction": "lifecycle",
+  "event": "heartbeat:ping",
+  "canvasId": "2c637466-6c6f-6172-400c-15145e021b0a",
+  "payload": {
+    "canvasId": "2c637466-6c6f-6172-400c-15145e021b0a"
+  }
+}

package/dist/logs/ws-traffic-traces/2026-03-27T20-33-30-223Z+08-lifecycle-heartbeat_ping-2b637466-6c6f-6172-470c-151459021b0a.json

@@ -0,0 +1,9 @@
+{
+  "createdAt": "2026-03-27T12:33:30.223Z",
+  "direction": "lifecycle",
+  "event": "heartbeat:ping",
+  "canvasId": "2b637466-6c6f-6172-470c-151459021b0a",
+  "payload": {
+    "canvasId": "2b637466-6c6f-6172-470c-151459021b0a"
+  }
+}

package/dist/logs/ws-traffic-traces/2026-03-27T20-33-30-223Z+08-lifecycle-heartbeat_ping-2d637466-6c6f-6172-410c-15145f021b0a.json

@@ -0,0 +1,9 @@
+{
+  "createdAt": "2026-03-27T12:33:30.223Z",
+  "direction": "lifecycle",
+  "event": "heartbeat:ping",
+  "canvasId": "2d637466-6c6f-6172-410c-15145f021b0a",
+  "payload": {
+    "canvasId": "2d637466-6c6f-6172-410c-15145f021b0a"
+  }
+}

package/dist/logs/ws-traffic-traces/2026-03-27T20-33-35-734Z+08-lifecycle-heartbeat_ping-2c637466-6c6f-6172-400c-15145e021b0a.json

@@ -0,0 +1,9 @@
+{
+  "createdAt": "2026-03-27T12:33:35.734Z",
+  "direction": "lifecycle",
+  "event": "heartbeat:ping",
+  "canvasId": "2c637466-6c6f-6172-400c-15145e021b0a",
+  "payload": {
+    "canvasId": "2c637466-6c6f-6172-400c-15145e021b0a"
+  }
+}

package/dist/logs/ws-traffic-traces/2026-03-27T20-34-00-228Z+08-lifecycle-heartbeat_ping-2b637466-6c6f-6172-470c-151459021b0a.json

@@ -0,0 +1,9 @@
+{
+  "createdAt": "2026-03-27T12:34:00.229Z",
+  "direction": "lifecycle",
+  "event": "heartbeat:ping",
+  "canvasId": "2b637466-6c6f-6172-470c-151459021b0a",
+  "payload": {
+    "canvasId": "2b637466-6c6f-6172-470c-151459021b0a"
+  }
+}

package/dist/logs/ws-traffic-traces/2026-03-27T20-34-00-229Z+08-lifecycle-heartbeat_ping-2d637466-6c6f-6172-410c-15145f021b0a.json

@@ -0,0 +1,9 @@
+{
+  "createdAt": "2026-03-27T12:34:00.229Z",
+  "direction": "lifecycle",
+  "event": "heartbeat:ping",
+  "canvasId": "2d637466-6c6f-6172-410c-15145f021b0a",
+  "payload": {
+    "canvasId": "2d637466-6c6f-6172-410c-15145f021b0a"
+  }
+}

package/dist/src/config.js

@@ -0,0 +1,57 @@
+import { createHash } from 'node:crypto';
+import os from 'node:os';
+import { ENV_CONFIG, DEFAULT_MAX_RECONNECT_ATTEMPTS, DEFAULT_OPER_SYSTEM, DEFAULT_REQUEST_TIMEOUT_MS, } from './constants.js';
+function readString(value, fallback) {
+    return typeof value === 'string' && value.length > 0 ? value : fallback;
+}
+function readNumber(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+function buildStableDefaultDeviceId() {
+    const fingerprint = createHash('sha1')
+        .update(`${os.hostname()}:${os.userInfo().username}`)
+        .digest('hex')
+        .slice(0, 8);
+    return `artflo-openclaw-${fingerprint}`;
+}
+function detectTimeZone() {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone || 'Asia/Shanghai';
+    }
+    catch {
+        return 'Asia/Shanghai';
+    }
+}
+function detectCountryCode() {
+    try {
+        const locale = Intl.DateTimeFormat().resolvedOptions().locale || '';
+        const parts = locale.split('-');
+        return parts.length >= 2 ? parts[parts.length - 1].toUpperCase() : 'CN';
+    }
+    catch {
+        return 'CN';
+    }
+}
+export function createPluginConfig(api) {
+    const pluginConfig = api.pluginConfig ?? {};
+    const env = (typeof pluginConfig.env === 'string' && (pluginConfig.env === 'release' || pluginConfig.env === 'test')
+        ? pluginConfig.env
+        : 'release');
+    const urls = ENV_CONFIG[env];
+    return {
+        env,
+        apiBaseUrl: urls.apiBaseUrl,
+        vipApiBaseUrl: urls.vipApiBaseUrl,
+        webApiBaseUrl: urls.webApiBaseUrl,
+        apiKey: readString(pluginConfig.apiKey, ''),
+        appKey: readString(pluginConfig.appKey, ''),
+        vipAppId: readString(pluginConfig.vipAppId, ''),
+        vipGroup: readString(pluginConfig.vipGroup, ''),
+        deviceId: readString(pluginConfig.deviceId, buildStableDefaultDeviceId()),
+        timeZone: readString(pluginConfig.timeZone, detectTimeZone()),
+        countryCode: readString(pluginConfig.countryCode, detectCountryCode()),
+        operSystem: readString(pluginConfig.operSystem, DEFAULT_OPER_SYSTEM),
+        requestTimeoutMs: readNumber(pluginConfig.requestTimeoutMs, DEFAULT_REQUEST_TIMEOUT_MS),
+        maxReconnectAttempts: readNumber(pluginConfig.maxReconnectAttempts, DEFAULT_MAX_RECONNECT_ATTEMPTS),
+    };
+}

package/dist/src/constants.js

@@ -0,0 +1,35 @@
+export const PLUGIN_ID = 'artflo-openclaw-plugin';
+export const PLUGIN_NAME = 'Artflo OpenClaw Plugin';
+export const PLUGIN_DESCRIPTION = 'Expose deterministic Artflo canvas tools over direct WebSocket execution.';
+export const ENV_CONFIG = {
+    release: {
+        apiBaseUrl: 'https://webapi.artflo.ai',
+        vipApiBaseUrl: 'https://api-h5-sub.starii.com',
+        webApiBaseUrl: 'https://artflo.ai',
+    },
+    test: {
+        apiBaseUrl: 'https://testwebapi.artflo.ai',
+        vipApiBaseUrl: 'https://pre-api-h5-sub.starii.com',
+        webApiBaseUrl: 'https://test.artflo.ai',
+    },
+};
+export const DEFAULT_OPER_SYSTEM = '7';
+export const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
+export const DEFAULT_MAX_RECONNECT_ATTEMPTS = 5;
+export const ARTFLO_TOOL_NAMES = {
+    connect: 'artflo_canvas_connect',
+    connectionStatus: 'artflo_canvas_connection_status',
+    getState: 'artflo_canvas_get_state',
+    getConfig: 'artflo_canvas_get_config',
+    findNodes: 'artflo_canvas_find_nodes',
+    getNode: 'artflo_canvas_get_node',
+    changeElements: 'artflo_canvas_change_elements',
+    deleteElements: 'artflo_canvas_delete_elements',
+    runNodes: 'artflo_canvas_run_nodes',
+    waitForCompletion: 'artflo_canvas_wait_for_completion',
+    executePlan: 'artflo_canvas_execute_plan',
+    createCanvas: 'artflo_canvas_create',
+    listModels: 'artflo_canvas_list_models',
+    uploadFile: 'artflo_upload_file',
+    setApiKey: 'artflo_set_api_key',
+};

package/dist/src/core/api/api-base.js

@@ -0,0 +1,12 @@
+/** HTTP API base URL (trailing slash stripped). */
+export function getApiBaseUrl(config) {
+    return config.apiBaseUrl.replace(/\/+$/, '');
+}
+/**
+ * Derive the WebSocket URL from apiBaseUrl.
+ *   https://webapi.artflo.ai → wss://webapi.artflo.ai/canvas/ws
+ */
+export function getCanvasWsUrl(config) {
+    const hostname = new URL(config.apiBaseUrl).hostname;
+    return `wss://${hostname}/canvas/ws`;
+}

package/dist/src/core/api/upload-file.js

@@ -0,0 +1,59 @@
+/**
+ * Upload a file to Artflo OBS storage.
+ *
+ * POST /storage/obs/starii  (multipart/form-data, field "file")
+ * Auth: X-API-Key header.
+ * Max 100 MiB; common image/video extensions.
+ */
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { getApiBaseUrl } from './api-base.js';
+/**
+ * Upload a local file or a remote URL to Artflo OBS.
+ *
+ * @param source - Local file path or remote https URL.
+ * @param config - Plugin config (provides access token and WS URL for API base).
+ * @param filename - Optional override for the uploaded filename.
+ */
+export async function uploadFile(config, source, filename) {
+    let fileBlob;
+    let resolvedFilename;
+    if (source.startsWith('http://') || source.startsWith('https://')) {
+        // Remote URL — download first
+        const resp = await fetch(source);
+        if (!resp.ok) {
+            throw new Error(`Failed to download ${source}: HTTP ${resp.status}`);
+        }
+        const buffer = await resp.arrayBuffer();
+        const contentType = resp.headers.get('content-type') || 'application/octet-stream';
+        fileBlob = new Blob([buffer], { type: contentType });
+        resolvedFilename = filename || basename(new URL(source).pathname) || 'upload';
+    }
+    else {
+        // Local file path
+        const buffer = await readFile(source);
+        fileBlob = new Blob([buffer]);
+        resolvedFilename = filename || basename(source);
+    }
+    const formData = new FormData();
+    formData.append('file', fileBlob, resolvedFilename);
+    const baseUrl = getApiBaseUrl(config);
+    const response = await fetch(`${baseUrl}/storage/obs/starii`, {
+        method: 'POST',
+        headers: {
+            'X-API-Key': config.apiKey,
+        },
+        body: formData,
+    });
+    if (!response.ok) {
+        throw new Error(`Upload failed: HTTP ${response.status}`);
+    }
+    const body = (await response.json());
+    if (body.code !== 0 || !body.data?.url) {
+        throw new Error(`Upload failed: code=${body.code}`);
+    }
+    return {
+        url: body.data.url,
+        key: body.data.key ?? '',
+    };
+}