@fibukiapp/openclaw-plugin 0.1.0

package/README.md

@@ -0,0 +1,105 @@
+# FiBuKI OpenClaw Plugin
+
+Manage your FiBuKI tax accounting data through AI assistants.
+
+## What Claude Can Do
+
+| Task | Tools Used |
+|------|------------|
+| **View bank accounts** | `list_sources`, `get_source` |
+| **Browse transactions** | `list_transactions`, `get_transaction` |
+| **Find incomplete work** | `list_transactions` (isComplete=false), `list_transactions_needing_files` |
+| **Match receipts** | `list_files`, `connect_file_to_transaction`, `auto_connect_file_suggestions` |
+| **Categorize transactions** | `list_no_receipt_categories`, `assign_no_receipt_category` |
+
+## Installation
+
+```bash
+# From npm (when published)
+openclaw plugins install @fibuki/openclaw-plugin
+
+# Or link locally for development
+cd integrations/openclaw-plugin
+openclaw plugins install -l .
+```
+
+## Configuration
+
+1. **Generate an API Key** in FiBuKI:
+   - Go to **Settings > Integrations > AI Agents**
+   - Click "Create API Key"
+   - Copy the key (starts with `fk_`)
+
+2. **Add to OpenClaw config:**
+
+```json5
+{
+  plugins: {
+    entries: {
+      "fibuki": {
+        enabled: true,
+        config: {
+          apiKey: "fk_your_api_key_here"
+        }
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### Bank Accounts
+- `list_sources` - List all connected bank accounts
+- `get_source` - Get details of a specific account
+
+### Transactions
+- `list_transactions` - Search/filter transactions (use `isComplete: false` for incomplete)
+- `get_transaction` - Get full transaction details
+- `update_transaction` - Update description, mark complete
+
+### Files (Receipts/Invoices)
+- `list_files` - List uploaded files with match suggestions
+- `get_file` - Get file details including extracted data
+- `connect_file_to_transaction` - Link file to transaction
+- `disconnect_file_from_transaction` - Unlink file
+- `list_transactions_needing_files` - Find transactions without receipts
+- `auto_connect_file_suggestions` - Bulk-connect high-confidence matches
+
+### No-Receipt Categories
+- `list_no_receipt_categories` - List categories (bank fees, payroll, etc.)
+- `assign_no_receipt_category` - Mark transaction as not needing receipt
+- `remove_no_receipt_category` - Remove category from transaction
+
+## Example Conversations
+
+**User:** "Show me incomplete transactions from last month"
+```
+Claude uses: list_transactions with isComplete=false, dateFrom, dateTo
+```
+
+**User:** "Match all my unconnected receipts"
+```
+Claude uses: auto_connect_file_suggestions
+```
+
+**User:** "The bank fee doesn't need a receipt"
+```
+Claude uses: list_no_receipt_categories, then assign_no_receipt_category
+```
+
+## API Key Security
+
+- API keys are hashed before storage (we never store the raw key)
+- Keys can be revoked anytime in Settings
+- Each key tracks last used time and usage count
+- Maximum 5 active keys per user
+- Optional expiry dates supported
+
+## Domain Context
+
+The plugin includes a skills file (`skills/fibuki-guide/SKILL.md`) that gives Claude context about:
+- FiBuKI's data model (sources, transactions, files, partners)
+- Transaction completion logic
+- Amount handling (cents, not euros!)
+- Common workflows

package/openclaw.plugin.json

@@ -0,0 +1,27 @@
+{
+  "id": "fibuki",
+  "name": "FiBuKI Tax Studio",
+  "description": "Manage bank transactions, receipts, files, and tax categorization through FiBuKI. 15+ tools for transactions, files, and categories.",
+  "skills": ["skills/fibuki-guide"],
+  "channel": {
+    "docsPath": "/integrations/fibuki",
+    "blurb": "German tax accounting automation"
+  },
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "apiKey": {
+        "type": "string",
+        "description": "Your FiBuKI API key (generate at Settings > Integrations > AI Agents)"
+      }
+    },
+    "required": ["apiKey"]
+  },
+  "uiHints": {
+    "apiKey": {
+      "label": "API Key",
+      "placeholder": "fk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+      "sensitive": true
+    }
+  }
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@fibukiapp/openclaw-plugin",
+  "version": "0.1.0",
+  "description": "FiBuKI Tax Studio plugin for OpenClaw - manage transactions, receipts, and tax categorization",
+  "type": "module",
+  "main": "src/index.ts",
+  "openclaw": {
+    "extensions": ["./src/index.ts"]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fibuki/openclaw-plugin"
+  },
+  "keywords": ["openclaw", "fibuki", "tax", "accounting", "receipts", "invoices"],
+  "author": "FiBuKI",
+  "license": "MIT",
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.9.0"
+  }
+}

package/skills/fibuki-guide/SKILL.md

@@ -0,0 +1,97 @@
+# FiBuKI Tax Accounting Guide
+
+You are helping manage a FiBuKI tax accounting account. This guide explains the domain.
+
+## What is FiBuKI?
+
+FiBuKI is a German tax accounting tool for small businesses and freelancers. It helps users:
+- Import bank transactions (via CSV or Open Banking)
+- Upload and match receipts/invoices to transactions
+- Categorize transactions for tax purposes
+- Track completion status for bookkeeping
+
+## Core Data Model
+
+### Sources (Bank Accounts)
+- Represent bank accounts or credit cards
+- Transactions are imported from sources
+- Types: `bank_account`, `credit_card`
+- Can be connected via CSV upload or Open Banking (GoCardless)
+
+### Transactions
+- Individual bank movements (debits/credits)
+- Have: date, amount (in cents!), name, partner
+- **Cannot be individually deleted** (accounting integrity)
+- Complete when they have a file OR a no-receipt category
+
+### Files (Receipts/Invoices)
+- Uploaded PDFs or images
+- AI extracts: amount, date, VAT, partner
+- System suggests matching transactions (transactionSuggestions)
+- Many-to-many relationship with transactions
+
+### Partners
+- Companies or people the user transacts with
+- Examples: "Amazon", "REWE", "Deutsche Telekom"
+- System auto-detects partners from transaction names
+
+### No-Receipt Categories
+- For transactions that don't need receipts
+- Examples: Bank fees, Interest, Internal transfers, Payroll, Taxes
+- Assigning a category marks the transaction complete
+
+## Transaction Completion Logic
+
+A transaction is **complete** (isComplete=true) when:
+1. It has at least one connected file (fileIds.length > 0), OR
+2. It has a no-receipt category assigned (noReceiptCategoryId is set)
+
+Your goal: Help the user get all transactions to complete status.
+
+## Common Workflows
+
+### 1. Review Incomplete Transactions
+```
+list_transactions with isComplete=false
+```
+
+### 2. Match Files to Transactions
+```
+1. list_files with hasConnections=false (unmatched files)
+2. Look at transactionSuggestions on each file
+3. connect_file_to_transaction for good matches
+4. Or use auto_connect_file_suggestions for bulk matching
+```
+
+### 3. Categorize No-Receipt Transactions
+```
+1. list_no_receipt_categories (get available categories)
+2. assign_no_receipt_category for bank fees, transfers, etc.
+```
+
+### 4. Find Transactions Needing Receipts
+```
+list_transactions_needing_files
+```
+Returns transactions without files AND without no-receipt categories.
+
+## Amount Handling
+
+**All amounts are in CENTS (integer)**
+- 10.50 EUR = 1050
+- -25.00 EUR = -2500 (negative = expense)
+- When displaying to user, divide by 100
+
+## Date Handling
+
+All dates are ISO 8601 format:
+- `2024-01-15` for date-only
+- `2024-01-15T10:30:00Z` for timestamps
+
+## Important Rules
+
+1. **Never delete individual transactions** - They must be deleted with their source
+2. **Amounts are in cents** - Always divide by 100 for display
+3. **Files can connect to multiple transactions** - Many-to-many relationship
+4. **Trust transactionSuggestions** - Server-side matching is accurate
+5. **High confidence = 85+** - Auto-connect suggestions above this threshold

package/src/index.ts

@@ -0,0 +1,287 @@
+/**
+ * FiBuKI OpenClaw Plugin
+ *
+ * Exposes FiBuKI tools as OpenClaw agent tools via the FiBuKI HTTP API.
+ * Users authenticate with an API key generated in FiBuKI Settings.
+ */
+
+const API_BASE_URL = "https://europe-west1-taxstudio-f12fb.cloudfunctions.net";
+
+// OpenClaw plugin API types
+interface OpenClawApi {
+  config: PluginConfig;
+  logger: {
+    info: (msg: string) => void;
+    error: (msg: string) => void;
+    debug: (msg: string) => void;
+  };
+  registerAgentTool: (tool: AgentTool) => void;
+  registerService: (service: Service) => void;
+}
+
+interface PluginConfig {
+  apiKey?: string;
+}
+
+interface AgentTool {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  handler: (args: Record<string, unknown>) => Promise<string>;
+}
+
+interface Service {
+  id: string;
+  start: () => void;
+  stop: () => void;
+}
+
+// Tool definitions with full documentation for Claude
+const TOOL_DEFINITIONS: AgentTool[] = [
+  // ========== SOURCES ==========
+  {
+    name: "list_sources",
+    description: "List all bank accounts/sources for the user. Returns account names, IBANs, types (bank_account/credit_card), and currency.",
+    inputSchema: { type: "object", properties: {} },
+    handler: async () => "", // Placeholder, replaced at registration
+  },
+  {
+    name: "get_source",
+    description: "Get details of a specific bank account/source by ID.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        sourceId: { type: "string", description: "The bank account/source ID" },
+      },
+      required: ["sourceId"],
+    },
+    handler: async () => "",
+  },
+
+  // ========== TRANSACTIONS ==========
+  {
+    name: "list_transactions",
+    description:
+      "List transactions with optional filters. Returns date, amount (in cents!), partner, description, completion status. Use isComplete=false to find incomplete transactions.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        sourceId: { type: "string", description: "Filter by bank account ID" },
+        dateFrom: { type: "string", description: "Start date (ISO format: 2024-01-01)" },
+        dateTo: { type: "string", description: "End date (ISO format)" },
+        search: { type: "string", description: "Search in name, description, partner" },
+        isComplete: { type: "boolean", description: "Filter by completion status" },
+        limit: { type: "number", description: "Max results (default 50, max 100)" },
+      },
+    },
+    handler: async () => "",
+  },
+  {
+    name: "get_transaction",
+    description: "Get full details of a specific transaction including partner suggestions and file attachments.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        transactionId: { type: "string", description: "The transaction ID" },
+      },
+      required: ["transactionId"],
+    },
+    handler: async () => "",
+  },
+  {
+    name: "update_transaction",
+    description: "Update a transaction's description or completion status. Use for adding tax-relevant notes.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        transactionId: { type: "string", description: "The transaction ID" },
+        description: { type: "string", description: "Description for tax purposes" },
+        isComplete: { type: "boolean", description: "Mark as complete/incomplete" },
+      },
+      required: ["transactionId"],
+    },
+    handler: async () => "",
+  },
+
+  // ========== FILES ==========
+  {
+    name: "list_files",
+    description:
+      "List uploaded files (receipts/invoices) with match suggestions. Files have transactionSuggestions with confidence scores. Use hasConnections=false to find unmatched files.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        hasConnections: { type: "boolean", description: "true = matched files, false = unmatched" },
+        hasSuggestions: { type: "boolean", description: "Filter by whether file has transaction suggestions" },
+        limit: { type: "number", description: "Max results (default 50)" },
+      },
+    },
+    handler: async () => "",
+  },
+  {
+    name: "get_file",
+    description: "Get full details of a file including extracted data (amount, date, partner) and transaction suggestions.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        fileId: { type: "string", description: "The file ID" },
+      },
+      required: ["fileId"],
+    },
+    handler: async () => "",
+  },
+  {
+    name: "connect_file_to_transaction",
+    description:
+      "Connect a file (receipt) to a transaction. This marks the transaction as complete. Use when you've confirmed a file matches a transaction.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        fileId: { type: "string", description: "The file ID to connect" },
+        transactionId: { type: "string", description: "The transaction ID to connect to" },
+      },
+      required: ["fileId", "transactionId"],
+    },
+    handler: async () => "",
+  },
+  {
+    name: "disconnect_file_from_transaction",
+    description: "Disconnect a file from a transaction. Use when a match was incorrect.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        fileId: { type: "string", description: "The file ID" },
+        transactionId: { type: "string", description: "The transaction ID" },
+      },
+      required: ["fileId", "transactionId"],
+    },
+    handler: async () => "",
+  },
+  {
+    name: "list_transactions_needing_files",
+    description:
+      "Find transactions without receipts (no files connected AND no no-receipt category). These need action.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        minAmount: { type: "number", description: "Minimum amount in cents (absolute value)" },
+        limit: { type: "number", description: "Max results (default 50)" },
+      },
+    },
+    handler: async () => "",
+  },
+  {
+    name: "auto_connect_file_suggestions",
+    description:
+      "Automatically connect files to transactions where suggestion confidence is above threshold. Great for bulk matching. Default threshold is 89%.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        fileId: { type: "string", description: "Specific file ID, or omit for all unmatched files" },
+        minConfidence: { type: "number", description: "Minimum confidence 0-100 (default 89)" },
+      },
+    },
+    handler: async () => "",
+  },
+
+  // ========== CATEGORIES ==========
+  {
+    name: "list_no_receipt_categories",
+    description:
+      "List categories for transactions that don't need receipts: Bank fees, Interest, Internal transfers, Payroll, Taxes, etc.",
+    inputSchema: { type: "object", properties: {} },
+    handler: async () => "",
+  },
+  {
+    name: "assign_no_receipt_category",
+    description:
+      "Assign a no-receipt category to a transaction. This marks it complete without needing a file. Use for bank fees, interest, internal transfers, etc.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        transactionId: { type: "string", description: "The transaction ID" },
+        categoryId: { type: "string", description: "The category ID to assign" },
+      },
+      required: ["transactionId", "categoryId"],
+    },
+    handler: async () => "",
+  },
+  {
+    name: "remove_no_receipt_category",
+    description: "Remove a no-receipt category from a transaction.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        transactionId: { type: "string", description: "The transaction ID" },
+      },
+      required: ["transactionId"],
+    },
+    handler: async () => "",
+  },
+];
+
+/**
+ * Call the FiBuKI MCP API
+ */
+async function callApi(
+  apiKey: string,
+  tool: string,
+  args: Record<string, unknown>
+): Promise<string> {
+  const response = await fetch(`${API_BASE_URL}/mcpApi`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify({ tool, arguments: args }),
+  });
+
+  const data = await response.json();
+
+  if (!response.ok || !data.success) {
+    throw new Error(data.error || `API error: ${response.status}`);
+  }
+
+  return JSON.stringify(data.result, null, 2);
+}
+
+/**
+ * Main plugin registration function
+ */
+export default function register(api: OpenClawApi) {
+  const { config, logger } = api;
+
+  // Validate required config
+  if (!config.apiKey) {
+    logger.error("FiBuKI plugin requires apiKey in config. Generate one at Settings > Integrations > AI Agents");
+    return;
+  }
+
+  const apiKey = config.apiKey;
+  logger.info("FiBuKI plugin initializing...");
+
+  // Register all tools
+  for (const toolDef of TOOL_DEFINITIONS) {
+    api.registerAgentTool({
+      name: toolDef.name,
+      description: toolDef.description,
+      inputSchema: toolDef.inputSchema,
+      handler: async (args) => {
+        try {
+          return await callApi(apiKey, toolDef.name, args);
+        } catch (error) {
+          const msg = error instanceof Error ? error.message : "Unknown error";
+          return `Error: ${msg}`;
+        }
+      },
+    });
+    logger.debug(`Registered tool: ${toolDef.name}`);
+  }
+
+  logger.info(`FiBuKI plugin loaded with ${TOOL_DEFINITIONS.length} tools`);
+}
+
+// Export plugin metadata
+export const id = "fibuki";
+export const name = "FiBuKI Tax Studio";

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "declaration": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"]
+}