@kanvas/openclaw-plugin 0.1.0

package/README.md

@@ -0,0 +1,193 @@
+# Kanvas OpenClaw Plugin
+
+OpenClaw plugin that connects AI agents to [Kanvas](https://kanvas.dev) — your company's nervous system. Kanvas is the operational engine that connects all your data, tools, and workflows. For AI agents, it's what lets them actually run your business — not just talk about it.
+
+This plugin gives agents direct access to CRM, inventory, orders, and messaging so they can search leads, create contacts, check stock, track orders, store structured data, and send emails — all through 41 tools with auto-login and built-in system prompt context.
+
+## Quick Start
+
+### 1. Install the plugin
+
+```bash
+# From local directory (development)
+openclaw plugins install /path/to/kanvas-openclaw-plugin --link
+
+# From npm (once published)
+openclaw plugins install kanvas-openclaw-plugin
+```
+
+### 2. Configure credentials
+
+In your OpenClaw config file:
+
+```json5
+{
+  plugins: {
+    entries: {
+      "kanvas": {
+        enabled: true,
+        config: {
+          xKanvasApp: "your-app-id",
+          email: "agent@yourcompany.com",
+          password: "agent-password",
+          // Optional:
+          // xKanvasKey: "your-app-key"  // needed for kanvas_send_anonymous_email
+          // xKanvasLocation: "branch-uuid"
+        }
+      }
+    }
+  }
+}
+```
+
+The API URL defaults to `https://graphapi.kanvas.dev/graphql`. The plugin authenticates automatically on the first tool call using the Kanvas login mutation.
+
+### 3. Set up the agent's system prompt
+
+The plugin injects tool documentation into the agent's context automatically. But the agent's **base system prompt** (configured in OpenClaw) should tell it to use Kanvas. Here's a sample:
+
+```
+You are a sales and operations agent for [Company Name]. You manage leads,
+inventory, and orders using Kanvas.
+
+Your responsibilities:
+- Register and manage leads in the CRM pipeline
+- Look up products, stock levels, and pricing
+- Check and track orders
+- Add notes and messages to leads
+- Send emails to customers and prospects
+
+When users ask you to do any of these things, use the kanvas_* tools to act
+on it directly. Don't just describe what you would do — actually do it.
+
+Before creating a lead, always check kanvas_list_pipelines to get valid
+pipeline stage IDs, and kanvas_list_lead_sources for source IDs.
+
+When you don't have enough information to complete an action (e.g. missing
+a required field), ask the user for the missing details before proceeding.
+```
+
+Customize this for your business — add your company name, specific workflows, and any domain-specific instructions.
+
+## Tools Reference
+
+### CRM (22 tools)
+
+| Tool | Description |
+|------|-------------|
+| `kanvas_search_leads` | Search leads by keyword |
+| `kanvas_get_lead` | Full lead detail (pipeline, owner, participants, files, events) |
+| `kanvas_create_lead` | Create a new lead |
+| `kanvas_update_lead` | Update lead fields |
+| `kanvas_change_lead_owner` | Reassign lead owner |
+| `kanvas_change_lead_receiver` | Reassign lead receiver |
+| `kanvas_add_lead_participant` | Add a person to a lead |
+| `kanvas_remove_lead_participant` | Remove a person from a lead |
+| `kanvas_follow_lead` | Subscribe to lead updates |
+| `kanvas_unfollow_lead` | Unsubscribe from lead updates |
+| `kanvas_delete_lead` | Soft-delete a lead |
+| `kanvas_restore_lead` | Restore a deleted lead |
+| `kanvas_mark_lead_outcome` | Mark as Won, Lost, or Close |
+| `kanvas_create_lead_appointment` | Create a calendar event for a lead |
+| `kanvas_add_lead_message` | Add note to a lead channel |
+| `kanvas_add_lead_note_by_lead_id` | Add note by lead ID (auto-resolves channel) |
+| `kanvas_list_lead_messages` | List messages in a lead channel |
+| `kanvas_get_lead_primary_channel_slug` | Get the main channel slug for a lead |
+| `kanvas_list_pipelines` | List pipelines and stages |
+| `kanvas_list_lead_statuses` | List lead statuses |
+| `kanvas_list_lead_sources` | List lead sources |
+| `kanvas_list_lead_types` | List lead types |
+
+### Social / Messages (9 tools)
+
+Messages act as NoSQL-like document storage — the `message` field accepts any JSON structure.
+
+| Tool | Description |
+|------|-------------|
+| `kanvas_create_message` | Create a message with arbitrary JSON payload |
+| `kanvas_get_message` | Get message with metadata, files, children |
+| `kanvas_update_message` | Update message content or metadata |
+| `kanvas_delete_message` | Soft-delete a message |
+| `kanvas_list_channel_messages` | List messages by channel slug |
+| `kanvas_search_messages` | Search/filter by type, channel, or entity |
+| `kanvas_list_message_types` | List available message verbs |
+| `kanvas_create_message_type` | Create a new verb with optional template |
+| `kanvas_send_anonymous_email` | Send email via template (requires `xKanvasKey`) |
+
+### Inventory (7 tools)
+
+| Tool | Description |
+|------|-------------|
+| `kanvas_search_products` | Search products by keyword |
+| `kanvas_get_product` | Full product detail with variants and warehouses |
+| `kanvas_list_variants` | List variants with pricing and stock |
+| `kanvas_list_warehouses` | List stock locations |
+| `kanvas_list_channels` | List sales channels |
+| `kanvas_list_categories` | List product categories |
+| `kanvas_list_inventory_statuses` | List product statuses |
+
+### Orders (2 tools)
+
+| Tool | Description |
+|------|-------------|
+| `kanvas_search_orders` | Search orders by number or keyword |
+| `kanvas_get_order` | Full order detail with items, customer, status |
+
+### Diagnostics (1 tool)
+
+| Tool | Description |
+|------|-------------|
+| `kanvas_test_connection` | Verify API connectivity |
+
+## Authentication
+
+The plugin supports three auth modes:
+
+| Mode | Config fields | When to use |
+|------|--------------|-------------|
+| **Email/password** (recommended) | `email`, `password` | Agent logs in like a user. Token cached for the session. |
+| **Bearer token** | `bearerToken` | Pre-authenticated service account. |
+| **App key** | `authMode: "app-key"`, `xKanvasKey` | App-scoped access. Required for `kanvas_send_anonymous_email`. |
+
+With email/password, the plugin calls the Kanvas `login` mutation on the first tool invocation and caches the bearer token — no hardcoded tokens needed.
+
+## Configuration Reference
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `xKanvasApp` | Yes | — | App/tenant identifier |
+| `email` | Yes* | — | Agent user email |
+| `password` | Yes* | — | Agent user password |
+| `apiUrl` | No | `https://graphapi.kanvas.dev/graphql` | GraphQL endpoint |
+| `xKanvasLocation` | No | — | Branch/location UUID |
+| `xKanvasKey` | No | — | App key (for anonymous email) |
+| `bearerToken` | No | — | Pre-existing token (skips login) |
+| `authMode` | No | `bearer` | `bearer` or `app-key` |
+| `timeoutMs` | No | `15000` | Request timeout in ms |
+
+*Required when using email/password auth (recommended). Not needed if using `bearerToken` or `app-key` mode.
+
+All fields also fall back to `KANVAS_*` environment variables.
+
+## Development
+
+```bash
+npm run build     # Compile TypeScript to dist/
+npm run check     # Type-check without emitting
+npm run dev       # Watch mode
+```
+
+### Smoke Test
+
+Test against the real API:
+
+```bash
+KANVAS_X_APP=your-app-id \
+KANVAS_EMAIL=your@email.com \
+KANVAS_PASSWORD=yourpassword \
+  npx ts-node --esm scripts/smoke-test.ts
+```
+
+## License
+
+Private — see package.json.

package/dist/cli/setup.js

@@ -0,0 +1,75 @@
+import * as readline from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { KanvasClient } from "../client/kanvas-client.js";
+const DEFAULT_API_URL = "https://graphapi.kanvas.dev/graphql";
+async function prompt(rl, question, defaultValue) {
+    const suffix = defaultValue ? ` (${defaultValue})` : "";
+    const answer = await rl.question(`  ${question}${suffix}: `);
+    return answer.trim() || defaultValue || "";
+}
+export async function runSetup() {
+    const rl = readline.createInterface({ input: stdin, output: stdout });
+    try {
+        console.log("\n  Kanvas Plugin Setup\n  ───────────────────\n");
+        const apiUrl = await prompt(rl, "API URL", DEFAULT_API_URL);
+        const xKanvasApp = await prompt(rl, "App ID (X-Kanvas-App)");
+        if (!xKanvasApp) {
+            throw new Error("App ID is required");
+        }
+        const email = await prompt(rl, "Agent email");
+        if (!email) {
+            throw new Error("Email is required");
+        }
+        const password = await prompt(rl, "Agent password");
+        if (!password) {
+            throw new Error("Password is required");
+        }
+        const xKanvasLocation = await prompt(rl, "Branch/Location UUID (optional)");
+        const xKanvasKey = await prompt(rl, "App Key (optional, for anonymous email)");
+        // Test the credentials
+        console.log("\n  Testing connection...");
+        const client = new KanvasClient({
+            apiUrl,
+            xKanvasApp,
+            authMode: "bearer",
+        });
+        const session = await client.login(email, password);
+        console.log(`  Authenticated as ${session.uuid}`);
+        const conn = await client.testConnection();
+        if (!conn.ok) {
+            console.error(`  Connection test failed: ${conn.errors.join(", ")}`);
+        }
+        else {
+            console.log("  Connection OK\n");
+        }
+        const result = { apiUrl, xKanvasApp, email, password };
+        if (xKanvasLocation)
+            result.xKanvasLocation = xKanvasLocation;
+        if (xKanvasKey)
+            result.xKanvasKey = xKanvasKey;
+        // Print the config for the user to copy
+        console.log("  Add this to your OpenClaw config:\n");
+        console.log("  plugins:");
+        console.log("    entries:");
+        console.log("      kanvas:");
+        console.log("        enabled: true");
+        console.log("        config:");
+        if (apiUrl !== DEFAULT_API_URL) {
+            console.log(`          apiUrl: "${apiUrl}"`);
+        }
+        console.log(`          xKanvasApp: "${xKanvasApp}"`);
+        console.log(`          email: "${email}"`);
+        console.log(`          password: "${password}"`);
+        if (xKanvasLocation) {
+            console.log(`          xKanvasLocation: "${xKanvasLocation}"`);
+        }
+        if (xKanvasKey) {
+            console.log(`          xKanvasKey: "${xKanvasKey}"`);
+        }
+        console.log("");
+        return result;
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/client/headers.js

@@ -0,0 +1,25 @@
+export function buildKanvasHeaders(config, override = {}) {
+    const headers = {
+        "Content-Type": "application/json",
+        "X-Kanvas-App": config.xKanvasApp,
+    };
+    const location = override.xKanvasLocation ?? config.xKanvasLocation;
+    if (location) {
+        headers["X-Kanvas-Location"] = location;
+    }
+    if (config.authMode === "bearer") {
+        const token = override.bearerToken ?? config.bearerToken;
+        if (!token) {
+            throw new Error("Bearer auth mode selected but no bearer token is configured");
+        }
+        headers.Authorization = `Bearer ${token}`;
+    }
+    if (config.authMode === "app-key") {
+        const appKey = override.xKanvasKey ?? config.xKanvasKey;
+        if (!appKey) {
+            throw new Error("App-key auth mode selected but no X-Kanvas-Key is configured");
+        }
+        headers["X-Kanvas-Key"] = appKey;
+    }
+    return headers;
+}

package/dist/client/kanvas-client.js

@@ -0,0 +1,137 @@
+import { buildKanvasHeaders } from "./headers.js";
+export class KanvasClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    getConfig() {
+        return this.config;
+    }
+    /**
+     * Authenticate with email/password and store the bearer token.
+     * The login mutation is public (no @guard), only needs X-Kanvas-App.
+     */
+    async login(email, password) {
+        const mutation = `
+      mutation Login($data: LoginInput!) {
+        login(data: $data) {
+          id
+          uuid
+          token
+          refresh_token
+          token_expires
+          refresh_token_expires
+          time
+          timezone
+          sessionId
+        }
+      }
+    `;
+        const response = await fetch(this.config.apiUrl, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "X-Kanvas-App": this.config.xKanvasApp,
+            },
+            body: JSON.stringify({
+                query: mutation,
+                variables: { data: { email, password } },
+            }),
+        });
+        const payload = (await response.json());
+        if (payload.errors?.length) {
+            throw new Error(`Kanvas login failed: ${payload.errors.map((e) => e.message).join(", ")}`);
+        }
+        if (!payload.data?.login?.token) {
+            throw new Error("Kanvas login failed: no token returned");
+        }
+        this.config = {
+            ...this.config,
+            authMode: "bearer",
+            bearerToken: payload.data.login.token,
+        };
+        return payload.data.login;
+    }
+    /**
+     * Execute a query using X-Kanvas-Key auth (for @guardByAppKey mutations).
+     * Requires xKanvasKey to be configured.
+     */
+    async queryWithAppKey(query, variables = {}) {
+        const appKey = this.config.xKanvasKey;
+        if (!appKey) {
+            throw new Error("xKanvasKey is required for this operation (app-key authenticated mutation)");
+        }
+        const headers = {
+            "Content-Type": "application/json",
+            "X-Kanvas-App": this.config.xKanvasApp,
+            "X-Kanvas-Key": appKey,
+        };
+        const location = this.config.xKanvasLocation;
+        if (location) {
+            headers["X-Kanvas-Location"] = location;
+        }
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs ?? 15000);
+        try {
+            const response = await fetch(this.config.apiUrl, {
+                method: "POST",
+                headers,
+                body: JSON.stringify({ query, variables }),
+                signal: controller.signal,
+            });
+            return (await response.json());
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async query(query, variables = {}, override = {}) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs ?? 15000);
+        try {
+            const response = await fetch(this.config.apiUrl, {
+                method: "POST",
+                headers: buildKanvasHeaders(this.config, override),
+                body: JSON.stringify({ query, variables }),
+                signal: controller.signal,
+            });
+            return (await response.json());
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async testConnection(override = {}) {
+        const query = `query PluginConnectionTest { __typename }`;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs ?? 15000);
+        try {
+            const response = await fetch(this.config.apiUrl, {
+                method: "POST",
+                headers: buildKanvasHeaders(this.config, override),
+                body: JSON.stringify({ query, variables: {} }),
+                signal: controller.signal,
+            });
+            const payload = (await response.json());
+            return {
+                ok: response.ok && !payload.errors?.length,
+                status: response.status,
+                endpoint: this.config.apiUrl,
+                hasData: Boolean(payload.data),
+                errors: payload.errors?.map((error) => error.message) ?? [],
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                status: 0,
+                endpoint: this.config.apiUrl,
+                hasData: false,
+                errors: [error instanceof Error ? error.message : "Unknown connection error"],
+            };
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+}

package/dist/client/multipart.js

@@ -0,0 +1,37 @@
+import { buildKanvasHeaders } from "./headers.js";
+export async function postGraphQLMultipart(options) {
+    const form = new FormData();
+    form.append("operations", JSON.stringify({
+        query: options.query,
+        variables: options.variables,
+    }));
+    const map = {};
+    options.files.forEach((file, index) => {
+        map[String(index)] = [file.key];
+    });
+    form.append("map", JSON.stringify(map));
+    options.files.forEach((file, index) => {
+        let blob;
+        if (file.content instanceof Blob) {
+            blob = file.content;
+        }
+        else if (typeof file.content === "string") {
+            blob = new Blob([file.content], { type: file.contentType ?? "text/plain" });
+        }
+        else {
+            const uint8 = file.content instanceof Uint8Array ? file.content : new Uint8Array(file.content);
+            blob = new Blob([uint8], {
+                type: file.contentType ?? "application/octet-stream",
+            });
+        }
+        form.append(String(index), blob, file.fileName);
+    });
+    const headers = buildKanvasHeaders(options.config, options.override);
+    delete headers["Content-Type"];
+    const response = await fetch(options.config.apiUrl, {
+        method: "POST",
+        headers,
+        body: form,
+    });
+    return (await response.json());
+}

package/dist/client/types.js

@@ -0,0 +1 @@
+export {};

package/dist/config/env.js

@@ -0,0 +1,18 @@
+function required(name, value) {
+    if (!value) {
+        throw new Error(`Missing required environment variable: ${name}`);
+    }
+    return value;
+}
+export function loadConfigFromEnv(env = process.env) {
+    const authMode = (env.KANVAS_AUTH_MODE ?? "bearer");
+    return {
+        apiUrl: required("KANVAS_API_URL", env.KANVAS_API_URL),
+        xKanvasApp: required("KANVAS_X_APP", env.KANVAS_X_APP),
+        xKanvasLocation: env.KANVAS_X_LOCATION,
+        authMode,
+        bearerToken: env.KANVAS_BEARER_TOKEN,
+        xKanvasKey: env.KANVAS_X_KEY,
+        timeoutMs: env.KANVAS_TIMEOUT_MS ? Number(env.KANVAS_TIMEOUT_MS) : 15000,
+    };
+}

package/dist/config/types.js

@@ -0,0 +1 @@
+export {};