@kanvas/openclaw-plugin 0.1.3 → 0.1.4

package/dist/domains/crm/index.js

@@ -1,4 +1,26 @@
+import { readFile } from "node:fs/promises";
 import { postGraphQLMultipart } from "../../client/multipart.js";
+const CONTENT_TYPES = {
+    ".pdf": "application/pdf",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+    ".doc": "application/msword",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ".xls": "application/vnd.ms-excel",
+    ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ".csv": "text/csv",
+    ".txt": "text/plain",
+    ".zip": "application/zip",
+    ".html": "text/html",
+};
+function guessContentType(fileName) {
+    const ext = fileName.slice(fileName.lastIndexOf(".")).toLowerCase();
+    return CONTENT_TYPES[ext] ?? "application/octet-stream";
+}
 export class CrmService {
     client;
     constructor(client) {
@@ -162,6 +184,17 @@ export class CrmService {
         return this.client.query(mutation, { input });
     }
     async updateLead(id, input) {
+        // Auto-fetch branch_id and people_id if not provided (the API requires them)
+        if (!input.branch_id || !input.people_id) {
+            const current = await this.getLeadCore(id);
+            const lead = current.data?.leads?.data?.[0];
+            if (lead) {
+                if (!input.branch_id)
+                    input.branch_id = lead.branch?.id;
+                if (!input.people_id)
+                    input.people_id = lead.people?.id;
+            }
+        }
         const mutation = `
       mutation UpdateLead($id: ID!, $input: LeadUpdateInput!) {
         updateLead(id: $id, input: $input) {
@@ -180,6 +213,24 @@ export class CrmService {
     `;
         return this.client.query(mutation, { id, input });
     }
+    /** Lightweight lead fetch for getting required fields (branch_id, people_id). */
+    async getLeadCore(id) {
+        const query = `
+      query GetLeadCore($first: Int!, $where: QueryLeadsWhereWhereConditions) {
+        leads(first: $first, where: $where) {
+          data {
+            id
+            branch { id }
+            people { id }
+          }
+        }
+      }
+    `;
+        return this.client.query(query, {
+            first: 1,
+            where: [{ column: "ID", operator: "EQ", value: id }],
+        });
+    }
     async changeLeadOwner(input) {
         return this.updateLead(String(input.leadId), {
             branch_id: input.branch_id,
@@ -587,4 +638,263 @@ export class CrmService {
     `;
         return this.client.query(query, { first });
     }
+    async attachFileToLeadByUrl(leadId, fileUrl, fileName) {
+        const mutation = `
+      mutation CreateFilesystem($input: FilesystemInputUrl!) {
+        createFileSystem(input: $input) {
+          id
+          uuid
+          name
+          url
+          type
+        }
+      }
+    `;
+        const fileResult = await this.client.query(mutation, {
+            input: { url: fileUrl, name: fileName },
+        });
+        const fileUuid = fileResult.data?.createFileSystem?.uuid;
+        if (!fileUuid) {
+            return fileResult; // return the error
+        }
+        // Now attach via updateLead with files
+        return this.updateLead(leadId, {
+            files: [{ url: fileUrl, name: fileName }],
+        });
+    }
+    /**
+     * Resolve file content from base64, file path, or URL.
+     */
+    async resolveFileContent(source) {
+        if (source.base64) {
+            return Buffer.from(source.base64, "base64");
+        }
+        if (source.filePath) {
+            return readFile(source.filePath);
+        }
+        if (source.url) {
+            const response = await fetch(source.url);
+            if (!response.ok) {
+                throw new Error(`Failed to download file from ${source.url}: ${response.status}`);
+            }
+            return Buffer.from(await response.arrayBuffer());
+        }
+        throw new Error("One of base64, filePath, or url must be provided");
+    }
+    async uploadFileToLead(leadId, fileName, source, contentType) {
+        const buffer = await this.resolveFileContent(source);
+        return postGraphQLMultipart({
+            config: this.client.getConfig(),
+            query: `
+        mutation AttachFileToLead($id: ID!, $file: Upload!) {
+          attachFileToLead(id: $id, file: $file) {
+            id
+            uuid
+            title
+            files {
+              data {
+                id
+                uuid
+                name
+                url
+                type
+              }
+            }
+          }
+        }
+      `,
+            variables: { id: leadId, file: null },
+            files: [{
+                    key: "variables.file",
+                    fileName,
+                    contentType: contentType ?? guessContentType(fileName),
+                    content: buffer,
+                }],
+        });
+    }
+    async uploadFileToMessage(messageId, fileName, source, contentType) {
+        const buffer = await this.resolveFileContent(source);
+        return postGraphQLMultipart({
+            config: this.client.getConfig(),
+            query: `
+        mutation AttachFileToMessage($message_id: ID!, $file: Upload!) {
+          attachFileToMessage(message_id: $message_id, file: $file) {
+            id
+            uuid
+            message
+            files {
+              data {
+                id
+                uuid
+                name
+                url
+                type
+              }
+            }
+          }
+        }
+      `,
+            variables: { message_id: messageId, file: null },
+            files: [{
+                    key: "variables.file",
+                    fileName,
+                    contentType: contentType ?? guessContentType(fileName),
+                    content: buffer,
+                }],
+        });
+    }
+    async updatePeople(id, input) {
+        const mutation = `
+      mutation UpdatePeople($id: ID!, $input: PeopleInput!) {
+        updatePeople(id: $id, input: $input) {
+          id
+          uuid
+          firstname
+          middlename
+          lastname
+          dob
+          contacts {
+            id
+            value
+            type { id name }
+          }
+          address {
+            id
+            address
+            city
+            state
+            zip
+            country
+          }
+          organizations { name }
+          custom_fields { name value }
+          tags { id name }
+          updated_at
+        }
+      }
+    `;
+        return this.client.query(mutation, { id, input });
+    }
+    async searchPeople(search, first = 10) {
+        const query = `
+      query SearchPeople($first: Int, $search: String) {
+        peoples(first: $first, search: $search) {
+          data {
+            id
+            uuid
+            firstname
+            lastname
+            contacts {
+              id
+              value
+              type { id name }
+            }
+            organizations { name }
+            created_at
+          }
+        }
+      }
+    `;
+        return this.client.query(query, { first, search });
+    }
+    async listPeopleRelationships(first = 50) {
+        const query = `
+      query PeopleRelationships($first: Int) {
+        peopleRelationships(first: $first) {
+          data {
+            id
+            name
+            description
+          }
+        }
+      }
+    `;
+        return this.client.query(query, { first });
+    }
+    async listContactTypes(first = 50) {
+        const query = `
+      query ContactTypes($first: Int) {
+        contactTypes(first: $first) {
+          data {
+            id
+            name
+          }
+        }
+      }
+    `;
+        return this.client.query(query, { first });
+    }
+    async createFollowUpEvent(input) {
+        const mutation = `
+      mutation CreateEvent($input: EventInput!) {
+        createEvent(input: $input) {
+          id
+          uuid
+          name
+          description
+          created_at
+          versions {
+            data {
+              id
+              start_at
+              end_at
+              dates {
+                id
+                date
+                start_time
+                end_time
+              }
+            }
+          }
+        }
+      }
+    `;
+        const eventInput = {
+            name: input.name,
+            description: input.description,
+            dates: [{
+                    date: input.date,
+                    start_time: input.start_time,
+                    end_time: input.end_time,
+                }],
+        };
+        if (input.lead_id) {
+            eventInput.resources = [{
+                    resources_id: String(input.lead_id),
+                    resources_type: "lead",
+                }];
+        }
+        return this.client.query(mutation, { input: eventInput });
+    }
+    async listEvents(first = 25, where) {
+        const query = `
+      query Events($first: Int, $where: QueryEventsWhereWhereConditions) {
+        events(first: $first, where: $where, orderBy: [{ column: CREATED_AT, order: DESC }]) {
+          data {
+            id
+            uuid
+            name
+            description
+            created_at
+            type { name }
+            eventStatus { name }
+            versions {
+              data {
+                id
+                start_at
+                end_at
+                dates {
+                  id
+                  date
+                  start_time
+                  end_time
+                }
+              }
+            }
+          }
+        }
+      }
+    `;
+        return this.client.query(query, { first, where });
+    }
 }

package/dist/index.js

@@ -1,4 +1,3 @@
-import { definePluginEntry } from "openclaw/plugin-sdk/core";
 import { Type } from "@sinclair/typebox";
 import { KanvasClient } from "./client/kanvas-client.js";
 import { CrmService } from "./domains/crm/index.js";
@@ -62,10 +61,11 @@ function createAuthGuard(client, config, logger) {
         return authPromise;
     };
 }
-export default definePluginEntry({
+export default {
     id: "kanvas",
     name: "Kanvas CRM",
     description: "Connects agents to Kanvas — your company's nervous system for CRM, inventory, orders, and messaging.",
+    configSchema: { type: "object" },
     register(api) {
         const config = resolveConfig(api.pluginConfig);
         const client = new KanvasClient(config);
@@ -103,9 +103,9 @@ export default definePluginEntry({
                 await runSetup();
             });
         }, { commands: ["setup"] });
-        api.logger.info("Kanvas plugin registered — 41 tools loaded");
+        api.logger.info("Kanvas plugin registered — 50 tools loaded");
     },
-});
+};
 const KANVAS_SYSTEM_CONTEXT = `
 ## Kanvas Plugin
 
@@ -124,6 +124,16 @@ Use when the user asks about leads, prospects, sales pipeline, contacts, or foll
 - \`kanvas_add_lead_participant\` / \`kanvas_remove_lead_participant\` → manage related people
 - \`kanvas_follow_lead\` / \`kanvas_unfollow_lead\` → subscribe to lead updates
 - \`kanvas_delete_lead\` / \`kanvas_restore_lead\` → soft-delete and restore
+- \`kanvas_attach_file_to_lead_by_url\` → attach a file to a lead from a public URL
+- \`kanvas_upload_file_to_lead\` → upload a file directly to a lead (base64-encoded content — for PDFs, images, generated docs)
+- \`kanvas_upload_file_to_message\` → upload a file to a message (base64-encoded)
+
+**People / Contacts**
+Use when the user asks about updating contact info, adding phone numbers or emails.
+- \`kanvas_search_people\` → search contacts by name, email, or phone
+- \`kanvas_update_people\` → update a person's name, phone, email, address, tags (call kanvas_list_contact_types first for contact type IDs)
+- \`kanvas_list_contact_types\` → get valid contact type IDs (email, phone, etc.)
+- \`kanvas_list_people_relationships\` → list relationship types for lead participants
 
 **CRM Support Data** — call these first when creating/updating leads to get valid IDs:
 - \`kanvas_list_pipelines\` → pipelines and their stages (needed for pipeline_stage_id)
@@ -167,6 +177,12 @@ Use when the user asks about orders, purchases, or sales.
 - \`kanvas_search_orders\` → find orders by number or keyword
 - \`kanvas_get_order\` → full order detail with items, customer, status
 
+**Follow-ups & Reminders**
+ALWAYS schedule follow-ups in Kanvas so the human team can see them — NEVER store them only in local memory.
+- \`kanvas_create_follow_up\` → create a calendar event for a future action (e.g. "Call Jane re: proposal"). Optionally link to a lead. Requires: name, date, start_time, end_time.
+- \`kanvas_list_events\` → list scheduled events/follow-ups
+- For structured follow-up data (tracking status, priority, custom fields), use \`kanvas_create_message\` with verb "follow_up" and a JSON payload containing { due_date, lead_id, action, status, priority }.
+
 **Diagnostics**
 - \`kanvas_test_connection\` → verify the API is reachable
 
@@ -176,4 +192,7 @@ Use when the user asks about orders, purchases, or sales.
 - Messages use \`message_verb\` to define their type (e.g. "comment", "note", "sms"). New verbs are auto-created.
 - The \`message\` field in social messages accepts arbitrary JSON — use it to store any structured data.
 - Filtering uses \`where: [{ column, operator, value }]\` format. Common operators: "EQ", "LIKE", "IN".
+- **Follow-ups and reminders MUST go in Kanvas** (events or messages), not local memory. The human team needs to see them in the dashboard.
+- When updating a lead, you don't need to provide branch_id or people_id — they are auto-fetched.
+- To add contacts to a person, call \`kanvas_list_contact_types\` first, then pass the contacts array to \`kanvas_update_people\`.
 `.trim();

package/dist/tools/crm.js

@@ -61,12 +61,12 @@ export function registerCrmTools(api, service, ensureAuth) {
     api.registerTool({
         name: "kanvas_update_lead",
         label: "Update Lead",
-        description: "Update an existing lead's fields.",
+        description: "Update an existing lead's fields. branch_id and people_id are auto-fetched if not provided.",
         parameters: Type.Object({
             id: Type.String({ description: "Lead ID" }),
             input: Type.Object({
-                branch_id: Type.Union([Type.String(), Type.Number()]),
-                people_id: Type.Union([Type.String(), Type.Number()]),
+                branch_id: Type.Optional(Type.Union([Type.String(), Type.Number()], { description: "Auto-fetched if omitted" })),
+                people_id: Type.Optional(Type.Union([Type.String(), Type.Number()], { description: "Auto-fetched if omitted" })),
                 title: Type.Optional(Type.String()),
                 leads_owner_id: Type.Optional(Type.Union([Type.String(), Type.Number()])),
                 organization_id: Type.Optional(Type.Union([Type.String(), Type.Number()])),
@@ -340,4 +340,159 @@ export function registerCrmTools(api, service, ensureAuth) {
             return toolResult(await service.listLeadTypes(params.first));
         },
     });
+    api.registerTool({
+        name: "kanvas_attach_file_to_lead_by_url",
+        label: "Attach File to Lead by URL",
+        description: "Attach a file (PDF, image, document) to a lead using a public URL. " +
+            "The file is downloaded by the server and attached to the lead.",
+        parameters: Type.Object({
+            leadId: Type.String({ description: "Lead ID" }),
+            fileUrl: Type.String({ description: "Public URL of the file to attach" }),
+            fileName: Type.String({ description: "File name (e.g. proposal.pdf, photo.jpg)" }),
+        }),
+        async execute(_id, params) {
+            await ensureAuth();
+            return toolResult(await service.attachFileToLeadByUrl(params.leadId, params.fileUrl, params.fileName));
+        },
+    });
+    api.registerTool({
+        name: "kanvas_upload_file_to_lead",
+        label: "Upload File to Lead",
+        description: "Upload a file to a lead. Provide the content as base64, a local file path, or a URL to download from. " +
+            "Exactly one of base64, filePath, or url must be provided.",
+        parameters: Type.Object({
+            leadId: Type.String({ description: "Lead ID" }),
+            fileName: Type.String({ description: "File name with extension (e.g. proposal.pdf, photo.jpg)" }),
+            base64: Type.Optional(Type.String({ description: "Base64-encoded file content" })),
+            filePath: Type.Optional(Type.String({ description: "Absolute path to a local file" })),
+            url: Type.Optional(Type.String({ description: "URL to download the file from" })),
+            contentType: Type.Optional(Type.String({ description: "MIME type (auto-detected from extension if omitted)" })),
+        }),
+        async execute(_id, params) {
+            await ensureAuth();
+            const { leadId, fileName, contentType, ...source } = params;
+            return toolResult(await service.uploadFileToLead(leadId, fileName, source, contentType));
+        },
+    });
+    api.registerTool({
+        name: "kanvas_upload_file_to_message",
+        label: "Upload File to Message",
+        description: "Upload a file to a message. Provide the content as base64, a local file path, or a URL to download from.",
+        parameters: Type.Object({
+            messageId: Type.String({ description: "Message ID" }),
+            fileName: Type.String({ description: "File name with extension" }),
+            base64: Type.Optional(Type.String({ description: "Base64-encoded file content" })),
+            filePath: Type.Optional(Type.String({ description: "Absolute path to a local file" })),
+            url: Type.Optional(Type.String({ description: "URL to download the file from" })),
+            contentType: Type.Optional(Type.String({ description: "MIME type (auto-detected if omitted)" })),
+        }),
+        async execute(_id, params) {
+            await ensureAuth();
+            const { messageId, fileName, contentType, ...source } = params;
+            return toolResult(await service.uploadFileToMessage(messageId, fileName, source, contentType));
+        },
+    });
+    // --- People / Contacts ---
+    api.registerTool({
+        name: "kanvas_search_people",
+        label: "Search People",
+        description: "Search contacts/people by name, email, or phone.",
+        parameters: Type.Object({
+            search: Type.String({ description: "Search keyword" }),
+            first: Type.Optional(Type.Number({ description: "Max results (default 10)" })),
+        }),
+        async execute(_id, params) {
+            await ensureAuth();
+            return toolResult(await service.searchPeople(params.search, params.first));
+        },
+    });
+    api.registerTool({
+        name: "kanvas_update_people",
+        label: "Update People/Contact",
+        description: "Update a person's profile — name, phone, email, address, tags, custom fields. " +
+            "To add contacts (phone/email), pass contacts array with value and contacts_types_id. " +
+            "Call kanvas_list_contact_types first to get valid contact type IDs.",
+        parameters: Type.Object({
+            id: Type.String({ description: "People ID" }),
+            input: Type.Object({
+                firstname: Type.Optional(Type.String()),
+                middlename: Type.Optional(Type.String()),
+                lastname: Type.Optional(Type.String()),
+                dob: Type.Optional(Type.String({ description: "Date of birth (YYYY-MM-DD)" })),
+                organization: Type.Optional(Type.String()),
+                contacts: Type.Optional(Type.Array(Type.Object({
+                    value: Type.String({ description: "Phone number, email, etc." }),
+                    contacts_types_id: Type.Union([Type.String(), Type.Number()], { description: "Contact type ID (call kanvas_list_contact_types)" }),
+                    weight: Type.Optional(Type.Number()),
+                    is_opt_out: Type.Optional(Type.Boolean()),
+                }))),
+                tags: Type.Optional(Type.Array(Type.Object({ name: Type.String() }))),
+                custom_fields: Type.Optional(Type.Array(Type.Record(Type.String(), Type.Unknown()))),
+            }),
+        }),
+        async execute(_id, params) {
+            await ensureAuth();
+            return toolResult(await service.updatePeople(params.id, params.input));
+        },
+    });
+    api.registerTool({
+        name: "kanvas_list_people_relationships",
+        label: "List People Relationships",
+        description: "List available relationship types for lead participants (e.g. Architect, Client, Consultant).",
+        parameters: Type.Object({
+            first: Type.Optional(Type.Number({ description: "Max results (default 50)" })),
+        }),
+        async execute(_id, params) {
+            await ensureAuth();
+            return toolResult(await service.listPeopleRelationships(params.first));
+        },
+    });
+    api.registerTool({
+        name: "kanvas_list_contact_types",
+        label: "List Contact Types",
+        description: "List available contact types (email, phone, etc.) needed for adding contacts to people.",
+        parameters: Type.Object({
+            first: Type.Optional(Type.Number({ description: "Max results (default 50)" })),
+        }),
+        async execute(_id, params) {
+            await ensureAuth();
+            return toolResult(await service.listContactTypes(params.first));
+        },
+    });
+    // --- Events / Follow-ups ---
+    api.registerTool({
+        name: "kanvas_create_follow_up",
+        label: "Create Follow-up",
+        description: "Schedule a follow-up reminder as a calendar event. Optionally link to a lead. " +
+            "Use this for any action that needs to happen on a future date — the team can see it in the Kanvas dashboard.",
+        parameters: Type.Object({
+            name: Type.String({ description: 'Follow-up name (e.g. "Call Jane Doe re: proposal")' }),
+            description: Type.Optional(Type.String({ description: "Details/notes about the follow-up" })),
+            date: Type.String({ description: "Date (YYYY-MM-DD)" }),
+            start_time: Type.String({ description: "Start time (HH:MM, 24h format)" }),
+            end_time: Type.String({ description: "End time (HH:MM, 24h format)" }),
+            lead_id: Type.Union([Type.String(), Type.Number()], { description: "Lead ID to link this follow-up to" }),
+        }),
+        async execute(_id, params) {
+            await ensureAuth();
+            return toolResult(await service.createFollowUpEvent(params));
+        },
+    });
+    api.registerTool({
+        name: "kanvas_list_events",
+        label: "List Events",
+        description: "List scheduled events/follow-ups with optional filtering.",
+        parameters: Type.Object({
+            first: Type.Optional(Type.Number({ description: "Max results (default 25)" })),
+            where: Type.Optional(Type.Array(Type.Object({
+                column: Type.String({ description: 'e.g. "ID", "NAME"' }),
+                operator: Type.String({ description: 'e.g. "EQ", "LIKE"' }),
+                value: Type.Unknown(),
+            }))),
+        }),
+        async execute(_id, params) {
+            await ensureAuth();
+            return toolResult(await service.listEvents(params.first, params.where));
+        },
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kanvas/openclaw-plugin",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Connects agents to Kanvas — your company's nervous system for CRM, inventory, orders, and messaging.",
   "license": "MIT",
   "repository": {
@@ -10,6 +10,7 @@
   "keywords": ["openclaw", "kanvas", "crm", "plugin", "ai-agent"],
   "type": "module",
   "openclaw": {
+    "id": "kanvas",
     "extensions": [
       "./dist/index.js"
     ]