@lchavezpozo/firefly-plugin-openclaw 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luis Chavez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# 🔥 Firefly III Plugin for OpenClaw
+
+A native OpenClaw plugin for [Firefly III](https://www.firefly-iii.org/) - the self-hosted personal finance manager.
+
+## Features
+
+- 💰 **Check balances** - View all your asset accounts
+- 📝 **Record transactions** - Log expenses, income, and transfers
+- 📊 **View recent transactions** - See your latest activity
+- 🗑️ **Delete transactions** - Remove incorrect entries
+- 📈 **Monthly summary** - Get spending overview
+- 🏷️ **List categories** - View all your categories
+
+## Installation
+
+```bash
+openclaw plugins install @lchavezpozo/firefly-plugin-openclaw
+```
+
+Or clone manually:
+
+```bash
+git clone https://github.com/lchavezpozo/firefly-plugin-openclaw.git ~/.openclaw/plugins/firefly-iii
+```
+
+## Configuration
+
+### 1. Get your Firefly III API Token
+
+1. Go to your Firefly III instance
+2. Navigate to **Options** → **Profile** → **OAuth**
+3. Create a new Personal Access Token
+4. Copy the token
+
+### 2. Configure the plugin
+
+Add to your `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "load": {
+      "paths": ["~/.openclaw/plugins/firefly-iii"]
+    },
+    "entries": {
+      "firefly-iii": {
+        "enabled": true,
+        "config": {
+          "url": "http://your-firefly-instance:8080",
+          "token": "your-api-token-here"
+        }
+      }
+    }
+  }
+}
+```
+
+Or use a credentials file:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "firefly-iii": {
+        "enabled": true,
+        "config": {
+          "credentialsPath": "/path/to/firefly-credentials.json"
+        }
+      }
+    }
+  }
+}
+```
+
+Credentials file format:
+```json
+{
+  "url": "http://your-firefly-instance:8080",
+  "token": "your-api-token-here"
+}
+```
+
+### 3. Restart OpenClaw
+
+```bash
+openclaw gateway restart
+```
+
+## Usage
+
+Once configured, the AI will automatically use these tools when you ask about finances:
+
+- "How much money do I have?" → `firefly_accounts`
+- "I spent $50 on groceries" → `firefly_transaction`
+- "Show my recent expenses" → `firefly_recent`
+- "Monthly spending summary" → `firefly_summary`
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `firefly_accounts` | Get all asset account balances |
+| `firefly_transaction` | Record expense/income/transfer |
+| `firefly_recent` | List recent transactions |
+| `firefly_delete` | Delete a transaction by ID |
+| `firefly_summary` | Get current month summary |
+| `firefly_categories` | List all categories |
+
+## Requirements
+
+- OpenClaw 2026.2.0 or later
+- Firefly III instance with API access
+- Personal Access Token from Firefly III
+
+## License
+
+MIT © Luis Chavez
+
+## Contributing
+
+PRs welcome! Feel free to open issues for bugs or feature requests.

package/index.ts

@@ -0,0 +1,347 @@
+/**
+ * Firefly III Plugin for OpenClaw
+ * 
+ * Personal finance management - check balances, record transactions, view spending.
+ * https://github.com/lchavezpozo/firefly-plugin-openclaw
+ */
+
+import { readFileSync } from "fs";
+import { resolve } from "path";
+import { homedir } from "os";
+
+interface FireflyConfig {
+  url?: string;
+  token?: string;
+  credentialsPath?: string;
+}
+
+interface Credentials {
+  url: string;
+  token: string;
+}
+
+function expandPath(p: string): string {
+  if (p.startsWith("~/")) {
+    return resolve(homedir(), p.slice(2));
+  }
+  return resolve(p);
+}
+
+function getCredentials(config: FireflyConfig): Credentials {
+  // Direct config takes precedence
+  if (config.url && config.token) {
+    return { url: config.url, token: config.token };
+  }
+  
+  // Try credentials file
+  if (config.credentialsPath) {
+    const credPath = expandPath(config.credentialsPath);
+    const creds = JSON.parse(readFileSync(credPath, "utf-8"));
+    return { url: creds.url, token: creds.token };
+  }
+  
+  throw new Error(
+    "Firefly III plugin not configured. Set url+token in config or provide credentialsPath."
+  );
+}
+
+async function fireflyFetch(creds: Credentials, endpoint: string, options: RequestInit = {}) {
+  const url = creds.url.replace(/\/$/, ""); // Remove trailing slash
+  const response = await fetch(`${url}${endpoint}`, {
+    ...options,
+    headers: {
+      "Authorization": `Bearer ${creds.token}`,
+      "Content-Type": "application/json",
+      "Accept": "application/json",
+      ...options.headers,
+    },
+  });
+  
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Firefly API error: ${response.status} ${response.statusText} - ${text}`);
+  }
+  
+  if (response.status === 204) return null;
+  return response.json();
+}
+
+export default function (api: any) {
+  const config: FireflyConfig = api.config?.plugins?.entries?.["firefly-iii"]?.config || {};
+
+  // ============================================
+  // Tool: Get account balances
+  // ============================================
+  api.registerTool({
+    name: "firefly_accounts",
+    description: "Get all asset account balances from Firefly III. Use when user asks about their money, balances, or 'cuánto tengo'.",
+    parameters: {
+      type: "object",
+      properties: {},
+      required: [],
+    },
+    async execute() {
+      const creds = getCredentials(config);
+      const data = await fireflyFetch(creds, "/api/v1/accounts?type=asset");
+      
+      const accounts = data.data.map((acc: any) => ({
+        name: acc.attributes.name,
+        balance: parseFloat(acc.attributes.current_balance),
+        currency: acc.attributes.currency_symbol,
+      }));
+      
+      const total = accounts.reduce((sum: number, acc: any) => sum + acc.balance, 0);
+      
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({ accounts, total, currency: accounts[0]?.currency || "$" }, null, 2)
+        }]
+      };
+    },
+  });
+
+  // ============================================
+  // Tool: Record a transaction
+  // ============================================
+  api.registerTool({
+    name: "firefly_transaction",
+    description: "Record a new transaction (expense, income, or transfer) in Firefly III. Use for 'gasté', 'pagué', 'compré', 'recibí', 'transferí'.",
+    parameters: {
+      type: "object",
+      properties: {
+        type: {
+          type: "string",
+          enum: ["withdrawal", "deposit", "transfer"],
+          description: "Transaction type: withdrawal (expense), deposit (income), transfer"
+        },
+        amount: {
+          type: "number",
+          description: "Transaction amount (positive number)"
+        },
+        description: {
+          type: "string",
+          description: "What was this transaction for"
+        },
+        account: {
+          type: "string",
+          description: "Source account name (e.g., 'Checking', 'Savings')"
+        },
+        category: {
+          type: "string",
+          description: "Optional category (e.g., 'Food', 'Transport')"
+        },
+        destination_account: {
+          type: "string",
+          description: "Destination account (required for transfers)"
+        },
+      },
+      required: ["type", "amount", "description", "account"],
+    },
+    async execute(_id: string, params: any) {
+      const creds = getCredentials(config);
+      
+      // Get source account ID
+      const accountsData = await fireflyFetch(creds, "/api/v1/accounts?type=asset");
+      const sourceAccount = accountsData.data.find((acc: any) => 
+        acc.attributes.name.toLowerCase() === params.account.toLowerCase()
+      );
+      
+      if (!sourceAccount) {
+        const available = accountsData.data.map((a: any) => a.attributes.name).join(", ");
+        return {
+          content: [{
+            type: "text",
+            text: `Error: Account '${params.account}' not found. Available accounts: ${available}`
+          }]
+        };
+      }
+
+      const transaction: any = {
+        type: params.type,
+        date: new Date().toISOString().split("T")[0],
+        amount: params.amount.toString(),
+        description: params.description,
+        source_id: sourceAccount.id,
+      };
+
+      if (params.category) {
+        transaction.category_name = params.category;
+      }
+
+      if (params.type === "transfer" && params.destination_account) {
+        const destAccount = accountsData.data.find((acc: any) =>
+          acc.attributes.name.toLowerCase() === params.destination_account.toLowerCase()
+        );
+        if (destAccount) {
+          transaction.destination_id = destAccount.id;
+        } else {
+          return {
+            content: [{
+              type: "text",
+              text: `Error: Destination account '${params.destination_account}' not found.`
+            }]
+          };
+        }
+      }
+
+      const result = await fireflyFetch(creds, "/api/v1/transactions", {
+        method: "POST",
+        body: JSON.stringify({ transactions: [transaction] }),
+      });
+
+      const tx = result.data.attributes.transactions[0];
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            success: true,
+            id: result.data.id,
+            type: tx.type,
+            amount: tx.amount,
+            currency: tx.currency_symbol,
+            description: tx.description,
+            date: tx.date,
+            category: tx.category_name || null,
+          }, null, 2)
+        }]
+      };
+    },
+  });
+
+  // ============================================
+  // Tool: Get recent transactions
+  // ============================================
+  api.registerTool({
+    name: "firefly_recent",
+    description: "Get recent transactions from Firefly III. Use for 'últimos gastos', 'transacciones recientes', 'en qué gasté'.",
+    parameters: {
+      type: "object",
+      properties: {
+        limit: {
+          type: "number",
+          description: "Number of transactions to return (default 10)"
+        },
+      },
+      required: [],
+    },
+    async execute(_id: string, params: any) {
+      const creds = getCredentials(config);
+      const limit = params.limit || 10;
+      const data = await fireflyFetch(creds, `/api/v1/transactions?limit=${limit}`);
+      
+      const transactions = data.data.map((tx: any) => {
+        const t = tx.attributes.transactions[0];
+        return {
+          id: tx.id,
+          date: t.date?.split("T")[0],
+          type: t.type,
+          amount: `${t.currency_symbol}${t.amount}`,
+          description: t.description,
+          category: t.category_name || null,
+          source: t.source_name,
+          destination: t.destination_name,
+        };
+      });
+
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify(transactions, null, 2)
+        }]
+      };
+    },
+  });
+
+  // ============================================
+  // Tool: Delete a transaction
+  // ============================================
+  api.registerTool({
+    name: "firefly_delete",
+    description: "Delete a transaction from Firefly III by its ID.",
+    parameters: {
+      type: "object",
+      properties: {
+        transaction_id: {
+          type: "string",
+          description: "The transaction ID to delete"
+        },
+      },
+      required: ["transaction_id"],
+    },
+    async execute(_id: string, params: any) {
+      const creds = getCredentials(config);
+      
+      await fireflyFetch(creds, `/api/v1/transactions/${params.transaction_id}`, {
+        method: "DELETE",
+      });
+
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({ success: true, deleted: params.transaction_id })
+        }]
+      };
+    },
+  });
+
+  // ============================================
+  // Tool: Get monthly summary
+  // ============================================
+  api.registerTool({
+    name: "firefly_summary",
+    description: "Get a financial summary for the current month from Firefly III. Use for 'resumen del mes', 'cuánto gasté este mes'.",
+    parameters: {
+      type: "object",
+      properties: {},
+      required: [],
+    },
+    async execute() {
+      const creds = getCredentials(config);
+      
+      const now = new Date();
+      const start = new Date(now.getFullYear(), now.getMonth(), 1).toISOString().split("T")[0];
+      const end = now.toISOString().split("T")[0];
+      
+      const data = await fireflyFetch(creds, `/api/v1/summary/basic?start=${start}&end=${end}`);
+
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify(data, null, 2)
+        }]
+      };
+    },
+  });
+
+  // ============================================
+  // Tool: Get categories
+  // ============================================
+  api.registerTool({
+    name: "firefly_categories",
+    description: "List all spending categories from Firefly III.",
+    parameters: {
+      type: "object",
+      properties: {},
+      required: [],
+    },
+    async execute() {
+      const creds = getCredentials(config);
+      const data = await fireflyFetch(creds, "/api/v1/categories");
+      
+      const categories = data.data.map((cat: any) => ({
+        id: cat.id,
+        name: cat.attributes.name,
+        spent: cat.attributes.spent || null,
+        earned: cat.attributes.earned || null,
+      }));
+
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify(categories, null, 2)
+        }]
+      };
+    },
+  });
+}

package/openclaw.plugin.json

@@ -0,0 +1,39 @@
+{
+  "id": "firefly-iii",
+  "name": "Firefly III",
+  "description": "Personal finance management - check balances, record transactions, view spending",
+  "version": "1.0.0",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "url": {
+        "type": "string",
+        "description": "Firefly III server URL (e.g., http://localhost:8080)"
+      },
+      "token": {
+        "type": "string",
+        "description": "Firefly III Personal Access Token"
+      },
+      "credentialsPath": {
+        "type": "string",
+        "description": "Path to JSON file with url and token (alternative to inline config)"
+      }
+    }
+  },
+  "uiHints": {
+    "token": {
+      "sensitive": true,
+      "label": "API Token",
+      "placeholder": "eyJ0eXAiOiJKV1QiLCJhbGciOi..."
+    },
+    "url": {
+      "label": "Firefly III URL",
+      "placeholder": "http://localhost:8080"
+    },
+    "credentialsPath": {
+      "label": "Credentials File Path",
+      "placeholder": "~/.openclaw/credentials/firefly.json"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@lchavezpozo/firefly-plugin-openclaw",
+  "version": "1.0.0",
+  "description": "OpenClaw plugin for Firefly III personal finance management",
+  "main": "index.ts",
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "firefly-iii",
+    "finance",
+    "personal-finance",
+    "budgeting"
+  ],
+  "author": "Luis Chavez <lchavezpozo@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lchavezpozo/firefly-plugin-openclaw.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lchavezpozo/firefly-plugin-openclaw/issues"
+  },
+  "homepage": "https://github.com/lchavezpozo/firefly-plugin-openclaw#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "index.ts",
+    "openclaw.plugin.json",
+    "README.md",
+    "LICENSE"
+  ]
+}