@fibukiapp/openclaw-plugin 0.1.0 → 0.1.1

package/README.md

@@ -1,92 +1,82 @@
 # FiBuKI OpenClaw Plugin
 
-Manage your FiBuKI tax accounting data through AI assistants.
+Manage your FiBuKI tax accounting data through AI assistants. 25 tools for bank transactions, receipts, partners, and tax categorization.
 
-## What Claude Can Do
+## Installation
 
-| 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` |
+### From ClawHub (recommended)
 
-## Installation
+```bash
+clawhub install fibuki
+```
+
+### From npm
 
 ```bash
-# From npm (when published)
-openclaw plugins install @fibuki/openclaw-plugin
+openclaw plugins install @fibukiapp/openclaw-plugin
+```
 
-# Or link locally for development
+### Local development
+
+```bash
 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_`)
+### 1. Get an API Key
+
+**Option A — CLI (zero friction):**
+```bash
+npx @fibukiapp/cli auth
+```
+Opens your browser, you approve, key is saved automatically.
+
+**Option B — Manual:**
+1. Go to **fibuki.com > Settings > Integrations > AI Agents**
+2. Click "Create API Key"
+3. Copy the key (starts with `fk_`)
+
+### 2. Configure OpenClaw
 
-2. **Add to OpenClaw config:**
+**Option A — Environment variable** (works with ClawHub skills):
+```bash
+export FIBUKI_API_KEY="fk_your_key_here"
+```
 
+**Option B — Plugin config** in `~/.openclaw/openclaw.json`:
 ```json5
 {
-  plugins: {
-    entries: {
+  "skills": {
+    "entries": {
       "fibuki": {
-        enabled: true,
-        config: {
-          apiKey: "fk_your_api_key_here"
-        }
+        "enabled": true,
+        "env": { "FIBUKI_API_KEY": "fk_your_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
+## What Claude Can Do
 
-**User:** "Show me incomplete transactions from last month"
-```
-Claude uses: list_transactions with isComplete=false, dateFrom, dateTo
-```
+| 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` |
+| **Manage partners** | `list_partners`, `create_partner`, `assign_partner_to_transaction` |
+| **Import data** | `import_transactions`, `upload_file` |
 
-**User:** "Match all my unconnected receipts"
-```
-Claude uses: auto_connect_file_suggestions
-```
+## Resources
 
-**User:** "The bank fee doesn't need a receipt"
-```
-Claude uses: list_no_receipt_categories, then assign_no_receipt_category
-```
+- **llm.txt** — Machine-readable API overview: https://fibuki.com/llm.txt
+- **OpenAPI spec** — Full tool schema: https://fibuki.com/api/openapi.json
+- **MCP endpoint** — For Claude Desktop: https://fibuki.com/api/mcp/sse
+- **CLI** — `npx @fibukiapp/cli auth` for zero-friction setup
 
 ## API Key Security
 
@@ -98,8 +88,4 @@ Claude uses: list_no_receipt_categories, then assign_no_receipt_category
 
 ## 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
+The plugin includes a skill file (`skills/fibuki-guide/SKILL.md`) that gives the agent context about FiBuKI's data model, transaction completion logic, amount handling (cents, not euros!), and common workflows.

package/openclaw.plugin.json

@@ -1,18 +1,18 @@
 {
   "id": "fibuki",
   "name": "FiBuKI Tax Studio",
-  "description": "Manage bank transactions, receipts, files, and tax categorization through FiBuKI. 15+ tools for transactions, files, and categories.",
+  "description": "Manage bank transactions, receipts, and tax bookkeeping for Austrian/German small businesses. 25 tools for transactions, files, partners, and categories.",
   "skills": ["skills/fibuki-guide"],
   "channel": {
     "docsPath": "/integrations/fibuki",
-    "blurb": "German tax accounting automation"
+    "blurb": "AI-powered tax bookkeeping for Austrian & German freelancers and small businesses"
   },
   "configSchema": {
     "type": "object",
     "properties": {
       "apiKey": {
         "type": "string",
-        "description": "Your FiBuKI API key (generate at Settings > Integrations > AI Agents)"
+        "description": "Your FiBuKI API key. Generate at fibuki.com > Settings > Integrations > AI Agents, or run: npx @fibukiapp/cli auth"
       }
     },
     "required": ["apiKey"]

package/package.json

@@ -1,17 +1,26 @@
 {
   "name": "@fibukiapp/openclaw-plugin",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "FiBuKI Tax Studio plugin for OpenClaw - manage transactions, receipts, and tax categorization",
   "type": "module",
   "main": "src/index.ts",
   "openclaw": {
-    "extensions": ["./src/index.ts"]
+    "extensions": [
+      "./src/index.ts"
+    ]
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/fibuki/openclaw-plugin"
   },
-  "keywords": ["openclaw", "fibuki", "tax", "accounting", "receipts", "invoices"],
+  "keywords": [
+    "openclaw",
+    "fibuki",
+    "tax",
+    "accounting",
+    "receipts",
+    "invoices"
+  ],
   "author": "FiBuKI",
   "license": "MIT",
   "scripts": {

package/skills/fibuki-guide/SKILL.md

@@ -1,14 +1,37 @@
-# FiBuKI Tax Accounting Guide
+---
+name: fibuki
+description: "Manage bank transactions, receipts, and tax bookkeeping in FiBuKI. Match receipts to transactions, categorize expenses, and track completion status for Austrian/German small businesses."
+homepage: https://fibuki.com
+user-invocable: true
+metadata: {"openclaw":{"emoji":"receipt","primaryEnv":"FIBUKI_API_KEY","requires":{"env":["FIBUKI_API_KEY"],"bins":["curl"]}}}
+---
 
-You are helping manage a FiBuKI tax accounting account. This guide explains the domain.
+# FiBuKI Tax Bookkeeping
 
-## What is FiBuKI?
+You are helping manage a FiBuKI tax accounting account. FiBuKI is a bookkeeping tool for Austrian and German small businesses and freelancers.
 
-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
+## What You Can Do
+
+- **View bank accounts and transactions** — browse, search, filter by date/amount/completion
+- **Match receipts to transactions** — connect uploaded files (invoices, receipts) to the right bank transactions
+- **Categorize transactions** — assign no-receipt categories to transactions that don't need receipts (bank fees, payroll, internal transfers)
+- **Track completion** — find incomplete transactions and help get them to 100%
+- **Manage partners** — create and assign business partners/vendors to transactions
+
+## Authentication
+
+All API calls use the user's `FIBUKI_API_KEY` environment variable (starts with `fk_`).
+
+Generate a key at: fibuki.com > Settings > Integrations > AI Agents
+Or run: `npx @fibukiapp/cli auth`
+
+Machine-readable API docs: https://fibuki.com/llm.txt
+
+## API Endpoint
+
+POST https://fibuki.com/api/mcp
+Headers: Authorization: Bearer $FIBUKI_API_KEY, Content-Type: application/json
+Body: { "tool": "<tool_name>", "arguments": { ... } }
 
 ## Core Data Model
 
@@ -16,37 +39,65 @@ FiBuKI is a German tax accounting tool for small businesses and freelancers. It
 - 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
+- **Complete** when they have a file attached OR a no-receipt category assigned
 
 ### Files (Receipts/Invoices)
 - Uploaded PDFs or images
-- AI extracts: amount, date, VAT, partner
-- System suggests matching transactions (transactionSuggestions)
+- AI extracts: amount, date, VAT, partner name
+- System suggests matching transactions with confidence scores (0-100)
 - Many-to-many relationship with transactions
 
 ### Partners
-- Companies or people the user transacts with
-- Examples: "Amazon", "REWE", "Deutsche Telekom"
+- Companies or people the user transacts with (e.g., "Amazon", "REWE")
 - 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
+- For transactions that legally don't need receipts: bank fees, interest, internal transfers, payroll, taxes
 - Assigning a category marks the transaction complete
 
-## Transaction Completion Logic
+## Available Tools
+
+### Bank Accounts
+- `list_sources` — List all connected bank accounts
+- `get_source(sourceId)` — Get details of a specific account
+- `create_source(name, accountKind?, iban?, currency?)` — Create a new bank account
+- `delete_source(sourceId, confirm)` — Delete account and all its data (requires confirm: true)
+
+### Transactions
+- `list_transactions(sourceId?, dateFrom?, dateTo?, search?, isComplete?, limit?)` — Search/filter transactions
+- `get_transaction(transactionId)` — Get full transaction details
+- `update_transaction(transactionId, description?, isComplete?)` — Update description or status
+- `list_transactions_needing_files(minAmount?, limit?)` — Find transactions without receipts or categories
+- `import_transactions(sourceId, transactions[])` — Import transactions into a source
+
+### Files (Receipts/Invoices)
+- `list_files(hasConnections?, hasSuggestions?, limit?)` — List uploaded files
+- `get_file(fileId)` — Get file details including AI-extracted data and suggestions
+- `connect_file_to_transaction(fileId, transactionId)` — Link file to transaction (marks it complete)
+- `disconnect_file_from_transaction(fileId, transactionId)` — Unlink file from transaction
+- `auto_connect_file_suggestions(fileId?, minConfidence?)` — Bulk-connect high-confidence matches (default 89%)
+- `upload_file(fileName, mimeType, url?, base64?)` — Upload a file from URL or base64
+- `score_file_transaction_match(fileId, transactionId)` — Score how well a file matches a transaction
+
+### Partners
+- `list_partners(search?, limit?)` — List user partners
+- `get_partner(partnerId)` — Get partner details
+- `create_partner(name, aliases?, vatId?, ibans?, website?, country?)` — Create a new partner
+- `assign_partner_to_transaction(transactionId, partnerId)` — Assign partner to transaction
+- `remove_partner_from_transaction(transactionId)` — Remove partner assignment
 
-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)
+### Categories
+- `list_no_receipt_categories` — List available no-receipt categories
+- `assign_no_receipt_category(transactionId, categoryId)` — Assign category (marks complete)
+- `remove_no_receipt_category(transactionId)` — Remove category
 
-Your goal: Help the user get all transactions to complete status.
+### Status
+- `get_automation_status` — Get user's automation mode, AI budget, and plan info
 
 ## Common Workflows
 
@@ -73,25 +124,13 @@ list_transactions with isComplete=false
 ```
 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
+1. **Never delete individual transactions** — they must be deleted with their entire source
+2. **Amounts are in cents** — always divide by 100 for display (1050 = 10.50 EUR)
+3. **Negative amounts = expenses** — positive = income
+4. **Files can connect to multiple transactions** — many-to-many relationship
+5. **Trust transactionSuggestions** — server-side AI matching is accurate
+6. **High confidence = 85+** — safe to auto-connect suggestions above this threshold
+7. **Dates are ISO 8601** — `2024-01-15` for dates, `2024-01-15T10:30:00Z` for timestamps

package/src/index.ts

@@ -5,7 +5,7 @@
  * Users authenticate with an API key generated in FiBuKI Settings.
  */
 
-const API_BASE_URL = "https://europe-west1-taxstudio-f12fb.cloudfunctions.net";
+const API_BASE_URL = "https://fibuki.com";
 
 // OpenClaw plugin API types
 interface OpenClawApi {
@@ -228,7 +228,7 @@ async function callApi(
   tool: string,
   args: Record<string, unknown>
 ): Promise<string> {
-  const response = await fetch(`${API_BASE_URL}/mcpApi`, {
+  const response = await fetch(`${API_BASE_URL}/api/mcp`, {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
@@ -252,13 +252,12 @@ async function callApi(
 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");
+  // Validate required config — check plugin config first, then env var
+  const apiKey = config.apiKey || process.env.FIBUKI_API_KEY;
+  if (!apiKey) {
+    logger.error("FiBuKI plugin requires an API key. Set FIBUKI_API_KEY env var, or add apiKey to plugin config. Generate one at fibuki.com > Settings > Integrations, or run: npx @fibukiapp/cli auth");
     return;
   }
-
-  const apiKey = config.apiKey;
   logger.info("FiBuKI plugin initializing...");
 
   // Register all tools