{"id":"7f9ac7fa-14fc-4c6f-a1a7-06a51b31e19f","entityType":"agent","slug":"clawhub-armysarge-quickbooks-direct","name":"QuickBooks Direct","canonicalUrl":"https://www.xpersona.co/agent/clawhub-armysarge-quickbooks-direct","canonicalPath":"/agent/clawhub-armysarge-quickbooks-direct","generatedAt":"2026-10-12T15:12:19.167Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T23:59:04.750Z","emptyReason":null},"description":"Comprehensive QuickBooks Online API integration for accounting, invoicing, payments, and financial reporting","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 972 downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s17855p89x5k6s0nagwqb2s8y9885ddh:quickbooks-direct","sourceUrl":"https://clawhub.ai/armysarge/quickbooks-direct","homepage":"https://clawhub.ai/armysarge/skills/quickbooks-direct","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/armysarge/quickbooks-direct","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/armysarge/skills/quickbooks-direct","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"QuickBooks Direct technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T23:59:04.750Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T23:59:04.750Z","emptyReason":null},"stars":null,"forks":null,"downloads":972,"likes":null,"task":null,"library":null,"packageName":null,"latestVersion":"1.0.1","tractionLabel":"972 downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T23:59:04.635Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T23:59:04.750Z","lastCrawledAt":"2026-10-11T23:59:04.635Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T23:59:04.635Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.1","createdAt":"2026-02-21T09:16:16.207Z","changelog":"- Added documentation files: API_REFERENCE.md, CHANGELOG.md, EXAMPLES.md, README.md, SECURITY.md, and TROUBLESHOOTING.md. - Updated OAuth redirect URI to http://localhost:3001/callback in documentation and config template. - Added api_environment configuration option in config.json. - Updated skill description to mention \"direct API integration\". - Removed dependency on '@modelcontextprotocol/sdk' from installation instructions.","fileCount":10,"zipByteSize":35305},{"version":"1.0.0","createdAt":"2026-02-21T09:03:54.362Z","changelog":"- Initial release of quickbooks-openclaw v1.0.0: comprehensive QuickBooks Online API integration for OpenClaw. - Supports full accounting, invoicing, customer/vendor management, inventory, payments, and core financial reports. - Includes OAuth2 authentication flow with automated token management. - Provides detailed tools for customer, invoice, payment, item management, as well as financial and aging reports. - Clear installation and setup instructions for seamless integration with OpenClaw. - Designed for extensibility in business and finance use cases.","fileCount":4,"zipByteSize":9043}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17855p89x5k6s0nagwqb2s8y9885ddh:quickbooks-direct","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s17855p89x5k6s0nagwqb2s8y9885ddh:quickbooks-direct` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/armysarge/quickbooks-direct before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-armysarge-quickbooks-direct/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-armysarge-quickbooks-direct/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-armysarge-quickbooks-direct/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-armysarge-quickbooks-direct/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-armysarge-quickbooks-direct/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-armysarge-quickbooks-direct/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-12T15:12:19.163Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-armysarge-quickbooks-direct/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-armysarge-quickbooks-direct/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-armysarge-quickbooks-direct/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-armysarge-quickbooks-direct/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T23:59:04.750Z","emptyReason":null},"readme":"Skill: QuickBooks Direct\n\nOwner: armysarge\n\nSummary: Comprehensive QuickBooks Online API integration for accounting, invoicing, payments, and financial reporting\n\nTags: latest:1.0.1\n\nVersion history:\n\nv1.0.1 | 2026-02-21T09:16:16.207Z | user\n\n- Added documentation files: API_REFERENCE.md, CHANGELOG.md, EXAMPLES.md, README.md, SECURITY.md, and TROUBLESHOOTING.md.\n- Updated OAuth redirect URI to http://localhost:3001/callback in documentation and config template.\n- Added api_environment configuration option in config.json.\n- Updated skill description to mention \"direct API integration\".\n- Removed dependency on '@modelcontextprotocol/sdk' from installation instructions.\n\nv1.0.0 | 2026-02-21T09:03:54.362Z | user\n\n- Initial release of quickbooks-openclaw v1.0.0: comprehensive QuickBooks Online API integration for OpenClaw.\n- Supports full accounting, invoicing, customer/vendor management, inventory, payments, and core financial reports.\n- Includes OAuth2 authentication flow with automated token management.\n- Provides detailed tools for customer, invoice, payment, item management, as well as financial and aging reports.\n- Clear installation and setup instructions for seamless integration with OpenClaw.\n- Designed for extensibility in business and finance use cases.\n\nArchive index:\n\nArchive v1.0.1: 10 files, 35305 bytes\n\nFiles: API_REFERENCE.md (16681b), CHANGELOG.md (6623b), config.json (277b), EXAMPLES.md (14741b), README.md (13343b), run.js (14170b), SECURITY.md (7761b), SKILL.md (16180b), TROUBLESHOOTING.md (14588b), _meta.json (136b)\n\nFile v1.0.1:SKILL.md\n\n---\r\nname: quickbooks-openclaw\r\nversion: 1.0.1\r\ndescription: Comprehensive QuickBooks Online API integration for accounting, invoicing, payments, and financial reporting\r\nauthor: Armysarge\r\nlicense: MIT\r\ntags:\r\n  - accounting\r\n  - quickbooks\r\n  - invoicing\r\n  - payments\r\n  - financial\r\n  - erp\r\n  - bookkeeping\r\ncategory: Business & Finance\r\n---\r\n\r\n# QuickBooks API Skill for OpenClaw\r\n\r\nA complete QuickBooks Online direct API integration skill for OpenClaw providing full access to accounting, invoicing, customer management, inventory, payments, and financial reporting through the Intuit QuickBooks API.\r\n\r\n## Overview\r\n\r\nThis skill enables OpenClaw to interact with QuickBooks Online for:\r\n- **Customer & Vendor Management**: Create and manage business relationships\r\n- **Invoicing**: Generate, send, and track invoices\r\n- **Payments**: Record and reconcile payments\r\n- **Inventory**: Manage products, services, and stock levels\r\n- **Financial Reports**: Generate P&L, Balance Sheets, Cash Flow, and aging reports\r\n- **Estimates**: Create quotes and proposals\r\n- **Bills**: Track accounts payable\r\n- **Purchase Orders**: Manage procurement\r\n\r\n## Prerequisites\r\n\r\n1. **QuickBooks Developer Account**\r\n   - Sign up at [https://developer.intuit.com](https://developer.intuit.com)\r\n   - Create a new app in the Developer Portal\r\n   - Enable \"QuickBooks Online API\" scope\r\n\r\n2. **App Credentials**\r\n   - Client ID from your QuickBooks app\r\n   - Client Secret from your QuickBooks app\r\n   - Redirect URI: `http://localhost:3001/callback`\r\n\r\n3. **Node.js**\r\n   - Version 18.0.0 or higher\r\n   - npm or yarn package manager\r\n\r\n## Installation\r\n\r\n### 1. Install Dependencies\r\n\r\n```bash\r\ncd \"c:\\Users\\Shaun\\Desktop\\Quickbooks skill\"\r\nnpm install\r\n```\r\n\r\nRequired packages:\r\n- `axios` - HTTP client for API requests\r\n- `express` - OAuth callback server\r\n- `open` - Browser automation for OAuth\r\n\r\n### 2. Configure Credentials\r\n\r\nCreate `config.json` from template:\r\n\r\n```bash\r\ncp config.json.template config.json\r\n```\r\n\r\nEdit `config.json` with your QuickBooks app credentials:\r\n\r\n```json\r\n{\r\n  \"client_id\": \"YOUR_CLIENT_ID_HERE\",\r\n  \"client_secret\": \"YOUR_CLIENT_SECRET_HERE\",\r\n  \"redirect_uri\": \"http://localhost:3001/callback\",\r\n  \"api_environment\": \"sandbox\",\r\n  \"access_token\": \"\",\r\n  \"refresh_token\": \"\",\r\n  \"realm_id\": \"\",\r\n  \"token_expiry\": 0\r\n}\r\n```\r\n\r\n### 3. Add to Configuration\r\n\r\n**For OpenClaw:**\r\n\r\nAdd to your OpenClaw configuration:\r\n```json\r\n{\r\n  \"skills\": {\r\n    \"quickbooks\": {\r\n      \"path\": \"~/.openclaw/workspace/skills/Quickbooks-openclaw\",\r\n      \"enabled\": true,\r\n      \"autoStart\": true\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n## Authentication\r\n\r\n### First-Time Setup\r\n\r\n1. Use the `qb_authenticate` tool with your credentials:\r\n```\r\nUse qb_authenticate with client_id and client_secret\r\n```\r\n\r\n2. A browser window will open automatically\r\n3. Log in to your QuickBooks account\r\n4. Authorize the application\r\n5. You'll be redirected to localhost (handled automatically)\r\n6. Tokens are saved to `config.json`\r\n\r\n### Token Management\r\n\r\n- **Access tokens** expire after 1 hour (refreshed automatically)\r\n- **Refresh tokens** last 100 days (renewed on refresh)\r\n- The skill automatically refreshes tokens before they expire\r\n- Re-authenticate if you see \"Not authenticated\" errors\r\n\r\n## Available Tools\r\n\r\n### 🔐 Authentication\r\n\r\n#### `qb_authenticate`\r\nInitiate OAuth2 authentication flow.\r\n\r\n**Parameters:**\r\n- `client_id` (required): Your QuickBooks app Client ID\r\n- `client_secret` (required): Your QuickBooks app Client Secret\r\n- `redirect_uri` (optional): OAuth redirect URI (default: http://localhost:3001/callback)\r\n\r\n**Example:**\r\n```json\r\n{\r\n  \"client_id\": \"ABxxxxxxxxxxxxxxxxxxxx\",\r\n  \"client_secret\": \"xxxxxxxxxxxxxxxxxx\"\r\n}\r\n```\r\n\r\n---\r\n\r\n### 👥 Customer Management\r\n\r\n#### `qb_create_customer`\r\nCreate a new customer.\r\n\r\n**Parameters:**\r\n- `DisplayName` (required): Customer display name\r\n- `CompanyName`: Company name\r\n- `GivenName`: First name\r\n- `FamilyName`: Last name\r\n- `PrimaryEmailAddr`: Email address object\r\n- `PrimaryPhone`: Phone number object\r\n- `BillAddr`: Billing address object\r\n- `ShipAddr`: Shipping address object\r\n\r\n**Example:**\r\n```json\r\n{\r\n  \"DisplayName\": \"Acme Corporation\",\r\n  \"PrimaryEmailAddr\": {\r\n    \"Address\": \"billing@acme.com\"\r\n  }\r\n}\r\n```\r\n\r\n#### `qb_get_customer`\r\nGet customer details by ID.\r\n\r\n**Parameters:**\r\n- `customer_id` (required): Customer ID\r\n\r\n#### `qb_query_customers`\r\nQuery customers using SQL syntax.\r\n\r\n**Parameters:**\r\n- `query`: SQL query string (default: \"SELECT * FROM Customer\")\r\n\r\n**Example:**\r\n```json\r\n{\r\n  \"query\": \"SELECT * FROM Customer WHERE Active = true\"\r\n}\r\n```\r\n\r\n---\r\n\r\n### 🧾 Invoice Management\r\n\r\n#### `qb_create_invoice`\r\nCreate a new invoice.\r\n\r\n**Parameters:**\r\n- `CustomerRef` (required): Customer reference object\r\n- `Line` (required): Array of line items\r\n- `TxnDate`: Transaction date (YYYY-MM-DD)\r\n- `DueDate`: Due date (YYYY-MM-DD)\r\n- `CustomerMemo`: Message to customer\r\n- `BillEmail`: Email address for invoice\r\n\r\n**Example:**\r\n```json\r\n{\r\n  \"CustomerRef\": { \"value\": \"123\" },\r\n  \"Line\": [{\r\n    \"Amount\": 500.00,\r\n    \"DetailType\": \"SalesItemLineDetail\",\r\n    \"SalesItemLineDetail\": {\r\n      \"ItemRef\": { \"value\": \"1\" },\r\n      \"Qty\": 10,\r\n      \"UnitPrice\": 50.00\r\n    }\r\n  }],\r\n  \"DueDate\": \"2026-03-15\"\r\n}\r\n```\r\n\r\n#### `qb_get_invoice`\r\nGet invoice by ID.\r\n\r\n**Parameters:**\r\n- `invoice_id` (required): Invoice ID\r\n\r\n#### `qb_send_invoice`\r\nSend invoice via email.\r\n\r\n**Parameters:**\r\n- `invoice_id` (required): Invoice ID\r\n- `email` (required): Recipient email address\r\n\r\n#### `qb_query_invoices`\r\nQuery invoices using SQL syntax.\r\n\r\n**Parameters:**\r\n- `query`: SQL query string\r\n\r\n**Example:**\r\n```json\r\n{\r\n  \"query\": \"SELECT * FROM Invoice WHERE Balance > 0\"\r\n}\r\n```\r\n\r\n---\r\n\r\n### 📦 Item/Product Management\r\n\r\n#### `qb_create_item`\r\nCreate a new product or service item.\r\n\r\n**Parameters:**\r\n- `Name` (required): Item name\r\n- `Type` (required): Item type (Service, Inventory, NonInventory)\r\n- `Description`: Item description\r\n- `UnitPrice`: Sales price\r\n- `IncomeAccountRef`: Income account reference\r\n- `ExpenseAccountRef`: Expense account reference (for inventory)\r\n- `QtyOnHand`: Quantity on hand (for inventory)\r\n\r\n**Example:**\r\n```json\r\n{\r\n  \"Name\": \"Consulting Services\",\r\n  \"Type\": \"Service\",\r\n  \"UnitPrice\": 150.00,\r\n  \"IncomeAccountRef\": { \"value\": \"79\" }\r\n}\r\n```\r\n\r\n#### `qb_get_item`\r\nGet item by ID.\r\n\r\n**Parameters:**\r\n- `item_id` (required): Item ID\r\n\r\n#### `qb_query_items`\r\nQuery items using SQL syntax.\r\n\r\n**Parameters:**\r\n- `query`: SQL query string\r\n\r\n---\r\n\r\n### 💰 Payment Processing\r\n\r\n#### `qb_create_payment`\r\nRecord a payment received.\r\n\r\n**Parameters:**\r\n- `CustomerRef` (required): Customer reference\r\n- `TotalAmt` (required): Total payment amount\r\n- `TxnDate`: Transaction date\r\n- `Line`: Array of payment line items linking to invoices\r\n- `PaymentMethodRef`: Payment method reference\r\n\r\n**Example:**\r\n```json\r\n{\r\n  \"CustomerRef\": { \"value\": \"123\" },\r\n  \"TotalAmt\": 500.00,\r\n  \"Line\": [{\r\n    \"Amount\": 500.00,\r\n    \"LinkedTxn\": [{\r\n      \"TxnId\": \"456\",\r\n      \"TxnType\": \"Invoice\"\r\n    }]\r\n  }]\r\n}\r\n```\r\n\r\n#### `qb_query_payments`\r\nQuery payments using SQL syntax.\r\n\r\n---\r\n\r\n### 📊 Financial Reports\r\n\r\n#### `qb_get_profit_loss`\r\nGenerate Profit & Loss report.\r\n\r\n**Parameters:**\r\n- `start_date` (required): Start date (YYYY-MM-DD)\r\n- `end_date` (required): End date (YYYY-MM-DD)\r\n\r\n**Example:**\r\n```json\r\n{\r\n  \"start_date\": \"2026-01-01\",\r\n  \"end_date\": \"2026-01-31\"\r\n}\r\n```\r\n\r\n#### `qb_get_balance_sheet`\r\nGenerate Balance Sheet report.\r\n\r\n**Parameters:**\r\n- `date` (required): Report date (YYYY-MM-DD)\r\n\r\n#### `qb_get_cash_flow`\r\nGenerate Cash Flow report.\r\n\r\n**Parameters:**\r\n- `start_date` (required): Start date\r\n- `end_date` (required): End date\r\n\r\n#### `qb_get_aged_receivables`\r\nGenerate Aged Receivables (A/R Aging) report.\r\n\r\n**Parameters:** None\r\n\r\n#### `qb_get_aged_payables`\r\nGenerate Aged Payables (A/P Aging) report.\r\n\r\n**Parameters:** None\r\n\r\n---\r\n\r\n### 💼 Vendor & Bill Management\r\n\r\n#### `qb_create_vendor`\r\nCreate a new vendor.\r\n\r\n**Parameters:**\r\n- `DisplayName` (required): Vendor display name\r\n- `CompanyName`: Company name\r\n- `PrimaryEmailAddr`: Email address object\r\n- `PrimaryPhone`: Phone number object\r\n\r\n#### `qb_create_bill`\r\nCreate a bill for a vendor.\r\n\r\n**Parameters:**\r\n- `VendorRef` (required): Vendor reference\r\n- `Line` (required): Array of bill line items\r\n- `TxnDate`: Transaction date\r\n- `DueDate`: Due date\r\n\r\n#### `qb_query_vendors`\r\nQuery vendors using SQL syntax.\r\n\r\n---\r\n\r\n### 📝 Estimates & Quotes\r\n\r\n#### `qb_create_estimate`\r\nCreate a new estimate/quote.\r\n\r\n**Parameters:**\r\n- `CustomerRef` (required): Customer reference\r\n- `Line` (required): Array of line items\r\n- `TxnDate`: Transaction date\r\n- `ExpirationDate`: Expiration date\r\n\r\n#### `qb_query_estimates`\r\nQuery estimates using SQL syntax.\r\n\r\n---\r\n\r\n### 🛒 Purchase Orders\r\n\r\n#### `qb_create_purchase_order`\r\nCreate a purchase order.\r\n\r\n**Parameters:**\r\n- `VendorRef` (required): Vendor reference\r\n- `Line` (required): Array of PO line items\r\n\r\n---\r\n\r\n### 💵 Sales Receipts\r\n\r\n#### `qb_create_sales_receipt`\r\nCreate a sales receipt (cash sale).\r\n\r\n**Parameters:**\r\n- `CustomerRef` (required): Customer reference\r\n- `Line` (required): Array of line items\r\n- `TxnDate`: Transaction date\r\n\r\n---\r\n\r\n### 🏦 Chart of Accounts\r\n\r\n#### `qb_query_accounts`\r\nQuery chart of accounts.\r\n\r\n**Parameters:**\r\n- `query`: SQL query string\r\n\r\n**Example:**\r\n```json\r\n{\r\n  \"query\": \"SELECT * FROM Account WHERE AccountType = 'Income'\"\r\n}\r\n```\r\n\r\n---\r\n\r\n### 🏢 Company Information\r\n\r\n#### `qb_get_company_info`\r\nGet company information.\r\n\r\n**Parameters:** None\r\n\r\n---\r\n\r\n### 🔍 Generic Query\r\n\r\n#### `qb_query`\r\nExecute any SQL query against QuickBooks entities.\r\n\r\n**Parameters:**\r\n- `query` (required): SQL query string\r\n\r\n**Example:**\r\n```json\r\n{\r\n  \"query\": \"SELECT * FROM Customer WHERE Balance > 100 ORDER BY DisplayName\"\r\n}\r\n```\r\n\r\n**Supported Entities:**\r\nAccount, Bill, BillPayment, Class, CreditMemo, Customer, Department, Deposit, Employee, Estimate, Invoice, Item, JournalEntry, Payment, PaymentMethod, Purchase, PurchaseOrder, RefundReceipt, SalesReceipt, TaxCode, TaxRate, Term, TimeActivity, Transfer, Vendor, VendorCredit\r\n\r\n---\r\n\r\n### ⚡ Batch Operations\r\n\r\n#### `qb_batch`\r\nExecute multiple operations in a single batch request.\r\n\r\n**Parameters:**\r\n- `operations` (required): Array of batch operations\r\n\r\n**Example:**\r\n```json\r\n{\r\n  \"operations\": [\r\n    {\r\n      \"bId\": \"bid1\",\r\n      \"operation\": \"create\",\r\n      \"entity\": \"Customer\",\r\n      \"data\": { \"DisplayName\": \"Customer 1\" }\r\n    },\r\n    {\r\n      \"bId\": \"bid2\",\r\n      \"operation\": \"query\",\r\n      \"query\": \"SELECT * FROM Invoice WHERE Balance > 0\"\r\n    }\r\n  ]\r\n}\r\n```\r\n\r\n## Usage Examples\r\n\r\n### Create and Send an Invoice Workflow\r\n\r\n```\r\n1. First, create or find a customer:\r\n   \"Find customer with name 'Acme Corp' using qb_query_customers\"\r\n\r\n2. Create an invoice:\r\n   \"Create an invoice for customer ID 123 with consulting services \r\n    for 10 hours at $150/hour, due in 30 days\"\r\n\r\n3. Send the invoice:\r\n   \"Send invoice 456 to billing@acme.com\"\r\n```\r\n\r\n### Financial Reporting Workflow\r\n\r\n```\r\n1. Get month-end reports:\r\n   \"Show me the profit and loss for January 2026\"\r\n\r\n2. Check cash flow:\r\n   \"What's the cash flow for last quarter?\"\r\n\r\n3. Review outstanding receivables:\r\n   \"Show me the aged receivables report\"\r\n```\r\n\r\n### Inventory Management Workflow\r\n\r\n```\r\n1. Check low stock items:\r\n   \"Query items where quantity on hand is less than 10\"\r\n\r\n2. Create reorder purchase order:\r\n   \"Create a purchase order for vendor 789 to reorder low stock items\"\r\n\r\n3. Update item prices:\r\n   \"Update the price of item 'Widget Pro' to $299.99\"\r\n```\r\n\r\n## SQL Query Syntax\r\n\r\nQuickBooks uses a SQL-like query language:\r\n\r\n### Basic Query\r\n```sql\r\nSELECT * FROM Customer WHERE Active = true\r\n```\r\n\r\n### With Conditions\r\n```sql\r\nSELECT * FROM Invoice WHERE Balance > 0 AND DueDate < '2026-03-01'\r\n```\r\n\r\n### Pattern Matching\r\n```sql\r\nSELECT * FROM Customer WHERE DisplayName LIKE '%Corp%'\r\n```\r\n\r\n### Ordering Results\r\n```sql\r\nSELECT * FROM Invoice ORDER BY TxnDate DESC\r\n```\r\n\r\n### Limiting Results\r\n```sql\r\nSELECT *, MAXRESULTS 50 FROM Customer\r\n```\r\n\r\n### Multiple Conditions\r\n```sql\r\nSELECT * FROM Item WHERE Type = 'Inventory' AND QtyOnHand < 10\r\n```\r\n\r\n## Error Handling\r\n\r\nThe skill provides detailed error messages:\r\n\r\n- **Authentication Errors**: \"Not authenticated. Please run qb_authenticate first.\"\r\n- **API Errors**: Full QuickBooks error details with status codes\r\n- **Validation Errors**: Missing required fields or invalid data\r\n- **Rate Limit Errors**: \"Too Many Requests - retry after delay\"\r\n\r\n## Configuration\r\n\r\nAll configuration is stored in `config.json`. This file contains both your app credentials (Client ID and Secret) and the OAuth tokens that are saved after authentication.\r\n\r\n### API Environment\r\n\r\nThe skill supports both Sandbox and Production environments via the `api_environment` setting in `config.json`:\r\n\r\n- **sandbox** (default): QuickBooks Sandbox API for development and testing\r\n- **production**: QuickBooks Production API for live company data (requires app verification)\r\n\r\nTo switch environments, update `config.json`:\r\n```json\r\n{\r\n  \"api_environment\": \"sandbox\"  // or \"production\"\r\n}\r\n```\r\n\r\n**Important**: Production mode requires your app to be verified by Intuit. Start with sandbox for development.\r\n\r\n### Security Considerations\r\n\r\n⚠️ **Credential Storage**: This skill stores OAuth tokens and client secrets in plaintext in `config.json` on your local filesystem. To enhance security:\r\n\r\n- Set restrictive file permissions on `config.json` (read/write for owner only)\r\n- Never commit `config.json` to version control (included in `.gitignore`)\r\n- Store the skill directory in a secure location\r\n- Regularly rotate your client secrets in the QuickBooks Developer Portal\r\n- Consider encrypting your disk or using a secure secret management solution\r\n- Do not enable `autoStart` until you've verified the skill behaves as expected\r\n\r\n## Rate Limits\r\n\r\n- **Sandbox**: 500 requests/minute per app\r\n- **Production**: Varies by subscription (500-1000/minute)\r\n\r\nThe skill automatically handles rate limiting with proper error messages.\r\n\r\n## Security\r\n\r\n- OAuth2 authentication (no password storage)\r\n- Tokens stored in `config.json` (excluded from git)\r\n- Automatic token refresh\r\n- Secure HTTPS API communication\r\n- No credentials in code\r\n\r\n## Troubleshooting\r\n\r\n### \"Not authenticated\" Error\r\nRun `qb_authenticate` with your credentials.\r\n\r\n### \"Token refresh failed\"\r\nDelete `config.json` and re-authenticate.\r\n\r\n### \"Invalid redirect URI\"\r\nEnsure redirect URI in config matches your QuickBooks app settings.\r\n\r\n### Port 3000 Already in Use\r\nChange port in code or kill the process using port 3000.\r\n\r\nFor more troubleshooting, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md).\r\n\r\n## Documentation\r\n\r\n- [README.md](README.md) - Complete setup guide\r\n- [EXAMPLES.md](EXAMPLES.md) - 50+ practical examples\r\n- [API_REFERENCE.md](API_REFERENCE.md) - Full API documentation\r\n- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Common issues and solutions\r\n- [CHANGELOG.md](CHANGELOG.md) - Version history\r\n\r\n## Support\r\n\r\n- [QuickBooks Developer Portal](https://developer.intuit.com)\r\n- [QuickBooks Developer Forum](https://help.developer.intuit.com/s/)\r\n- [API Documentation](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/account)\r\n- [API Status](https://status.developer.intuit.com/)\r\n\r\n## Contributing\r\n\r\nContributions welcome! Please:\r\n1. Fork the repository\r\n2. Create a feature branch\r\n3. Test thoroughly in sandbox\r\n4. Submit a pull request\r\n\r\n## License\r\n\r\nMIT License - See [LICENSE](LICENSE) file for details.\r\n\r\n## Version\r\n\r\n**Current Version**: 1.0.1  \r\n**Last Updated**: February 21, 2026  \r\n**Node.js Required**: 18.0.0+\r\n\r\n## Tags\r\n\r\n`accounting` `quickbooks` `invoicing` `payments` `financial-reporting` `bookkeeping` `erp` `business` `intuit` `api-integration` `mcp-skill` `openclaw`\r\n\r\n---\r\n\r\n**Ready to use!** Run `npm install` and authenticate to get started.\n\nFile v1.0.1:README.md\n\n# QuickBooks API Skill for OpenClaw\r\n\r\nA comprehensive QuickBooks Online API integration skill for OpenClaw, providing full access to QuickBooks accounting features.\r\n\r\n## Features\r\n\r\n### 🔐 Authentication\r\n- OAuth2 authentication flow with automatic token refresh\r\n- Secure credential storage\r\n- Automatic browser-based authorization\r\n\r\n### 📊 Customer Management\r\n- Create, read, and query customers\r\n- Manage customer details and contact information\r\n- Search customers with SQL-like queries\r\n\r\n### 🧾 Invoice Operations\r\n- Create and manage invoices\r\n- Send invoices via email\r\n- Query invoice history\r\n- Track invoice status\r\n\r\n### 📦 Inventory & Items\r\n- Create and manage products/services\r\n- Track inventory items\r\n- Manage pricing and descriptions\r\n- Support for Service, Inventory, and Non-Inventory items\r\n\r\n### 💰 Payment Processing\r\n- Record customer payments\r\n- Link payments to invoices\r\n- Query payment history\r\n\r\n### 📈 Financial Reports\r\n- Profit & Loss statements\r\n- Balance Sheet reports\r\n- Cash Flow reports\r\n- Aged Receivables (A/R Aging)\r\n- Aged Payables (A/P Aging)\r\n\r\n### 🏢 Vendor Management\r\n- Create and manage vendors\r\n- Create bills for vendors\r\n- Track vendor payments\r\n\r\n### 📝 Estimates & Quotes\r\n- Create estimates/quotes\r\n- Convert estimates to invoices\r\n- Track estimate status\r\n\r\n### 🛒 Purchase Orders\r\n- Create purchase orders\r\n- Track PO status\r\n\r\n### 💵 Sales Receipts\r\n- Create cash sale receipts\r\n- Record immediate payments\r\n\r\n### 🔍 Advanced Features\r\n- Generic SQL-like queries for any entity\r\n- Batch operations for multiple requests\r\n- Complete Chart of Accounts access\r\n- Tax code and rate management\r\n- Company information retrieval\r\n\r\n## Prerequisites\r\n\r\n1. **Node.js** (v18 or higher)\r\n2. **QuickBooks Developer Account**\r\n   - Sign up at [https://developer.intuit.com](https://developer.intuit.com)\r\n3. **QuickBooks App**\r\n   - Create an app in the Intuit Developer Portal\r\n   - Enable QuickBooks Online API scope\r\n\r\n## Setup Instructions\r\n\r\n### Step 1: Create QuickBooks Developer App\r\n\r\n1. Go to [Intuit Developer Portal](https://developer.intuit.com)\r\n2. Sign in and navigate to \"My Apps\"\r\n3. Click \"Create an app\" and select \"QuickBooks Online and Payments\"\r\n4. Fill in your app details:\r\n   - **App name**: Choose a name for your app\r\n   - **Redirect URI**: `http://localhost:3001/callback` (must match exactly)\r\n5. After creating the app, note your:\r\n   - **Client ID**\r\n   - **Client Secret**\r\n6. Under \"Keys & credentials\", make sure you're in the right environment:\r\n   - **Sandbox**: For testing (recommended to start)\r\n   - **Production**: For live data\r\n\r\n### Step 2: Install Dependencies\r\n\r\n```bash\r\ncd \"c:\\Users\\Shaun\\Desktop\\Quickbooks skill\"\r\nnpm install\r\n```\r\n\r\n### Step 3: Configure Authentication\r\n\r\nCreate a `config.json` file from the template:\r\n\r\n```bash\r\ncp config.json.template config.json\r\n```\r\n\r\nEdit `config.json` and add your credentials:\r\n\r\n```json\r\n{\r\n  \"client_id\": \"YOUR_CLIENT_ID_HERE\",\r\n  \"client_secret\": \"YOUR_CLIENT_SECRET_HERE\",\r\n  \"redirect_uri\": \"http://localhost:3001/callback\",\r\n  \"api_environment\": \"sandbox\",\r\n  \"access_token\": \"\",\r\n  \"refresh_token\": \"\",\r\n  \"realm_id\": \"\",\r\n  \"token_expiry\": 0\r\n}\r\n```\r\n\r\n### Step 4: Authenticate with QuickBooks\r\n\r\nThe skill uses OAuth2 for authentication. The first time you run any QuickBooks operation, you'll need to authenticate:\r\n\r\n1. The authentication process will:\r\n   - Start a local web server on port 3001\r\n   - Open your default browser\r\n   - Redirect to QuickBooks authorization page\r\n   - Capture the auth code and exchange it for tokens\r\n   - Save tokens to `config.json`\r\n\r\n2. After successful authentication, all subsequent API calls will use the saved tokens\r\n3. Tokens are automatically refreshed when they expire\r\n\r\n## OpenClaw Integration\r\n\r\n### Add to OpenClaw Configuration\r\n\r\nAdd this skill to your OpenClaw configuration file (typically `~/.config/openclaw/config.json` or similar):\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"quickbooks\": {\r\n      \"command\": \"node\",\r\n      \"args\": [\"c:/Users/Shaun/Desktop/Quickbooks skill/run.js\"],\r\n      \"env\": {}\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n## Usage with OpenClaw\r\n\r\nOnce installed and configured, the skill will be automatically available in OpenClaw. All QuickBooks tools will appear in your available skill set.\r\n\r\nRestart OpenClaw after installation to load the skill.\r\n\r\n## Usage Examples\r\n\r\n### Authentication\r\n\r\nFirst, authenticate with QuickBooks:\r\n\r\n```\r\nUse the qb_authenticate tool with your client_id and client_secret\r\n```\r\n\r\nThe tool will open a browser for you to authorize the app. After authorization, tokens are saved automatically.\r\n\r\n### Create a Customer\r\n\r\n```\r\nUse qb_create_customer with:\r\n{\r\n  \"DisplayName\": \"John Doe\",\r\n  \"PrimaryEmailAddr\": {\r\n    \"Address\": \"john@example.com\"\r\n  },\r\n  \"PrimaryPhone\": {\r\n    \"FreeFormNumber\": \"555-1234\"\r\n  }\r\n}\r\n```\r\n\r\n### Create an Invoice\r\n\r\n```\r\nUse qb_create_invoice with:\r\n{\r\n  \"CustomerRef\": {\r\n    \"value\": \"123\"\r\n  },\r\n  \"Line\": [\r\n    {\r\n      \"Amount\": 100.00,\r\n      \"DetailType\": \"SalesItemLineDetail\",\r\n      \"SalesItemLineDetail\": {\r\n        \"ItemRef\": {\r\n          \"value\": \"1\"\r\n        },\r\n        \"Qty\": 2,\r\n        \"UnitPrice\": 50.00\r\n      }\r\n    }\r\n  ],\r\n  \"DueDate\": \"2026-03-15\",\r\n  \"TxnDate\": \"2026-02-21\"\r\n}\r\n```\r\n\r\n### Query Customers\r\n\r\n```\r\nUse qb_query_customers with:\r\n{\r\n  \"query\": \"SELECT * FROM Customer WHERE DisplayName LIKE '%John%'\"\r\n}\r\n```\r\n\r\n### Get Profit & Loss Report\r\n\r\n```\r\nUse qb_get_profit_loss with:\r\n{\r\n  \"start_date\": \"2026-01-01\",\r\n  \"end_date\": \"2026-01-31\"\r\n}\r\n```\r\n\r\n### Send an Invoice\r\n\r\n```\r\nUse qb_send_invoice with:\r\n{\r\n  \"invoice_id\": \"123\",\r\n  \"email\": \"customer@example.com\"\r\n}\r\n```\r\n\r\n## Available Tools\r\n\r\n### Authentication\r\n- `qb_authenticate` - Initiate OAuth2 flow\r\n- `qb_exchange_token` - Exchange auth code for tokens (handled automatically)\r\n\r\n### Customers\r\n- `qb_create_customer` - Create a new customer\r\n- `qb_get_customer` - Get customer by ID\r\n- `qb_query_customers` - Query customers with SQL\r\n\r\n### Invoices\r\n- `qb_create_invoice` - Create a new invoice\r\n- `qb_get_invoice` - Get invoice by ID\r\n- `qb_send_invoice` - Email an invoice\r\n- `qb_query_invoices` - Query invoices with SQL\r\n\r\n### Items\r\n- `qb_create_item` - Create product/service item\r\n- `qb_get_item` - Get item by ID\r\n- `qb_query_items` - Query items with SQL\r\n\r\n### Payments\r\n- `qb_create_payment` - Record a payment\r\n- `qb_query_payments` - Query payments with SQL\r\n\r\n### Estimates\r\n- `qb_create_estimate` - Create an estimate/quote\r\n- `qb_query_estimates` - Query estimates with SQL\r\n\r\n### Vendors & Bills\r\n- `qb_create_vendor` - Create a vendor\r\n- `qb_create_bill` - Create a bill\r\n- `qb_query_vendors` - Query vendors with SQL\r\n\r\n### Reports\r\n- `qb_get_profit_loss` - Profit & Loss report\r\n- `qb_get_balance_sheet` - Balance Sheet report\r\n- `qb_get_cash_flow` - Cash Flow report\r\n- `qb_get_aged_receivables` - A/R Aging report\r\n- `qb_get_aged_payables` - A/P Aging report\r\n\r\n### Accounts\r\n- `qb_query_accounts` - Query chart of accounts\r\n\r\n### Purchase Orders\r\n- `qb_create_purchase_order` - Create a PO\r\n\r\n### Sales Receipts\r\n- `qb_create_sales_receipt` - Create a cash sale receipt\r\n\r\n### Other\r\n- `qb_get_company_info` - Get company information\r\n- `qb_query` - Execute any SQL query\r\n- `qb_batch` - Execute multiple operations in one request\r\n\r\n## SQL Query Syntax\r\n\r\nQuickBooks uses a SQL-like query language. Examples:\r\n\r\n```sql\r\n-- Get all active customers\r\nSELECT * FROM Customer WHERE Active = true\r\n\r\n-- Get invoices for a specific customer\r\nSELECT * FROM Invoice WHERE CustomerRef = '123'\r\n\r\n-- Get items with price greater than 50\r\nSELECT * FROM Item WHERE UnitPrice > 50\r\n\r\n-- Get recent transactions\r\nSELECT * FROM Invoice WHERE TxnDate > '2026-01-01' ORDER BY TxnDate DESC\r\n\r\n-- Get customers with email\r\nSELECT * FROM Customer WHERE PrimaryEmailAddr IS NOT NULL\r\n```\r\n\r\nSupported entities for queries:\r\n- Account\r\n- Bill\r\n- Customer\r\n- Estimate\r\n- Invoice\r\n- Item\r\n- Payment\r\n- Purchase\r\n- PurchaseOrder\r\n- SalesReceipt\r\n- Vendor\r\n- And many more...\r\n\r\n## Error Handling\r\n\r\nThe skill includes comprehensive error handling:\r\n\r\n- **Authentication Errors**: Clear messages when tokens are invalid or expired\r\n- **API Errors**: Detailed QuickBooks API error messages\r\n- **Validation Errors**: Client-side validation of required fields\r\n- **Rate Limiting**: Automatic retry with exponential backoff (if needed)\r\n\r\n## API Environment Configuration\r\n\r\nThe skill supports both Sandbox and Production environments:\r\n\r\n### Sandbox (Default)\r\nFor testing and development. Configured automatically when you authenticate.\r\n\r\n```json\r\n{\r\n  \"api_environment\": \"sandbox\"\r\n}\r\n```\r\n\r\n### Production\r\nFor live company data. Requires Intuit app verification.\r\n\r\n```json\r\n{\r\n  \"api_environment\": \"production\"\r\n}\r\n```\r\n\r\n**Switching Environments:**\r\n1. Update `api_environment` in `config.json`\r\n2. Re-authenticate with `qb_authenticate` using production credentials\r\n3. Verify you're using production Client ID and Secret from QuickBooks Developer Portal\r\n\r\n## Security Best Practices\r\n\r\n⚠️ **Important Security Considerations**\r\n\r\nThis skill stores sensitive credentials in plaintext in `config.json`. Before using in production:\r\n\r\n1. **File Permissions** - Restrict `config.json` to owner read/write only:\r\n   - Windows: Right-click → Properties → Security → Advanced\r\n   - Linux/Mac: `chmod 600 config.json`\r\n\r\n2. **Never Commit Credentials** - Ensure `config.json` is in `.gitignore`\r\n\r\n3. **Secure Storage Location** - Store the skill in a protected directory\r\n\r\n4. **Regular Credential Rotation** - Rotate client secrets monthly in QuickBooks Developer Portal\r\n\r\n5. **Audit Access** - Monitor who has access to the machine and skill directory\r\n\r\n6. **Use Sandbox First** - Always test with sandbox before production\r\n\r\n7. **Disable AutoStart** - Don't enable autoStart in OpenClaw until thoroughly tested\r\n\r\n8. **HTTPS in Production** - Use HTTPS redirect URIs for production deployments\r\n\r\n9. **Monitor Token Usage** - Refresh tokens expire after 100 days of inactivity\r\n\r\n10. **Principle of Least Privilege** - Only grant QuickBooks scopes you actually need\r\n\r\n## Troubleshooting\r\n\r\n### \"Not authenticated\" Error\r\n- Run the authentication flow first using `qb_authenticate`\r\n- Make sure config.json exists and has valid credentials\r\n\r\n### Token Refresh Failures\r\n- Your refresh token may have expired (they last 100 days)\r\n- Re-authenticate using `qb_authenticate`\r\n\r\n### API Permission Errors\r\n- Make sure your app has the correct scopes enabled\r\n- Check that you're using the right environment (sandbox vs production)\r\n\r\n### Browser Doesn't Open\r\n- Manually visit the authorization URL provided in the output\r\n- Make sure port 3001 is available\r\n\r\n### Port 3001 Already in Use\r\n- Kill the process using port 3001\r\n- Or change to a different port in:\r\n  - Your QuickBooks app settings (redirect URI)\r\n  - Your `config.json` (redirect_uri)\r\n  - The `run.js` code (server port)\r\n\r\n### Wrong API Environment\r\n- Check `api_environment` in `config.json` matches your intent (sandbox vs production)\r\n- Production requires verified app - use sandbox for development\r\n- After changing environment, re-authenticate with matching credentials\r\n\r\n## Development\r\n\r\n### Testing\r\n\r\n```bash\r\n# Install dependencies\r\nnpm install\r\n\r\n# Run the skill\r\nnode run.js\r\n```\r\n\r\n### Debugging\r\n\r\nEnable debug logging by setting:\r\n\r\n```bash\r\nexport DEBUG=quickbooks:*\r\nnode run.js\r\n```\r\n\r\n## API Rate Limits\r\n\r\nQuickBooks has API rate limits:\r\n- **Sandbox**: 500 requests per app per minute\r\n- **Production**: Varies by subscription level\r\n\r\nThe skill handles rate limiting gracefully with automatic retries.\r\n\r\n## References\r\n\r\n- [QuickBooks API Documentation](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/account)\r\n- [QuickBooks Workflows](https://developer.intuit.com/app/developer/qbo/docs/workflows)\r\n- [OAuth2 Guide](https://developer.intuit.com/app/developer/qbo/docs/develop/authentication-and-authorization/oauth-2.0)\r\n- [API Explorer](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/account)\r\n\r\n## License\r\n\r\nMIT\r\n\r\n## Support\r\n\r\nFor issues and questions:\r\n1. Check the [QuickBooks Developer Forum](https://help.developer.intuit.com/s/)\r\n2. Review the API documentation\r\n3. Open an issue in this repository\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please:\r\n1. Fork the repository\r\n2. Create a feature branch\r\n3. Commit your changes\r\n4. Push to the branch\r\n5. Create a Pull Request\r\n\r\n## Changelog\r\n\r\n### Version 1.0.1 - 2026-02-21\r\n**Security & Configuration Update**\r\n\r\n- ✅ Fixed port mismatch: Standardized all documentation to port 3001\r\n- ✅ Made API environment configurable: Added `api_environment` setting (sandbox/production)\r\n- ✅ Removed unused dependency: Cleaned up @modelcontextprotocol/sdk reference\r\n- ✅ Enhanced security documentation: Added credential storage warnings and best practices\r\n- ✅ Updated configuration template with api_environment field\r\n- ✅ Fixed run.js to dynamically select API endpoint based on configuration\r\n\r\n### Version 1.0.0 - 2026-02-21\r\n- Initial release\r\n- Full OAuth2 authentication\r\n- Complete CRUD operations for all major entities\r\n- Financial reporting\r\n- Batch operations\r\n- SQL query support\n\nFile v1.0.1:_meta.json\n\n{\n  \"ownerId\": \"kn75r02ytvqq38hkzbx6tqctc981dm3h\",\n  \"slug\": \"quickbooks-direct\",\n  \"version\": \"1.0.1\",\n  \"publishedAt\": 1771665376207\n}\n\nFile v1.0.1:API_REFERENCE.md\n\n# QuickBooks API Skill - Complete API Reference\r\n\r\n## Entity Relationships\r\n\r\n```\r\n┌─────────────┐\r\n│  Customer   │────┐\r\n└─────────────┘    │\r\n                   ├──► Invoice ──► Payment\r\n┌─────────────┐    │      │\r\n│    Item     │────┤      │\r\n└─────────────┘    │      └──► SalesReceipt\r\n                   │\r\n┌─────────────┐    └──► Estimate\r\n│   Account   │\r\n└─────────────┘\r\n\r\n┌─────────────┐\r\n│   Vendor    │────► Bill ──► BillPayment\r\n└─────────────┘    │\r\n                   └──► PurchaseOrder\r\n```\r\n\r\n## Core Entities\r\n\r\n### Customer\r\n\r\n**Fields:**\r\n- `DisplayName` (required) - Customer name\r\n- `Title` - Title (Mr., Mrs., etc.)\r\n- `GivenName` - First name\r\n- `MiddleName` - Middle name\r\n- `FamilyName` - Last name\r\n- `Suffix` - Name suffix (Jr., Sr., etc.)\r\n- `CompanyName` - Company name\r\n- `PrimaryEmailAddr.Address` - Email address\r\n- `PrimaryPhone.FreeFormNumber` - Phone number\r\n- `Mobile.FreeFormNumber` - Mobile number\r\n- `Fax.FreeFormNumber` - Fax number\r\n- `WebAddr.URI` - Website URL\r\n- `BillAddr` - Billing address object\r\n  - `Line1`, `Line2`, `Line3`, `Line4`, `Line5`\r\n  - `City`\r\n  - `CountrySubDivisionCode` (State/Province)\r\n  - `PostalCode`\r\n  - `Country`\r\n- `ShipAddr` - Shipping address (same structure as BillAddr)\r\n- `Notes` - Customer notes\r\n- `Active` - Boolean, customer status\r\n- `Balance` - Current balance (read-only)\r\n- `BalanceWithJobs` - Balance including jobs (read-only)\r\n- `PreferredDeliveryMethod` - Email, Print, or None\r\n- `ResaleNum` - Resale number\r\n- `PaymentMethodRef` - Default payment method\r\n- `TermRef` - Payment terms reference\r\n\r\n**Query Examples:**\r\n```sql\r\nSELECT * FROM Customer WHERE Active = true\r\nSELECT * FROM Customer WHERE Balance > 0\r\nSELECT * FROM Customer WHERE DisplayName LIKE '%ACME%'\r\nSELECT Id, DisplayName, Balance FROM Customer ORDER BY Balance DESC\r\n```\r\n\r\n### Invoice\r\n\r\n**Fields:**\r\n- `CustomerRef.value` (required) - Customer ID\r\n- `Line` (required) - Array of line items\r\n  - `Amount` (required)\r\n  - `DetailType` - Usually \"SalesItemLineDetail\"\r\n  - `Description`\r\n  - `SalesItemLineDetail`\r\n    - `ItemRef.value` (required) - Item ID\r\n    - `Qty` - Quantity\r\n    - `UnitPrice` - Price per unit\r\n    - `TaxCodeRef.value` - Tax code\r\n    - `DiscountAmt` - Discount amount\r\n- `TxnDate` - Transaction date (YYYY-MM-DD)\r\n- `DueDate` - Due date (YYYY-MM-DD)\r\n- `DocNumber` - Invoice number (auto-generated if omitted)\r\n- `PrivateNote` - Internal note\r\n- `CustomerMemo.value` - Message to customer\r\n- `BillEmail.Address` - Email for sending invoice\r\n- `BillEmailCc.Address` - CC email address\r\n- `BillEmailBcc.Address` - BCC email address\r\n- `ShipAddr` - Shipping address\r\n- `BillAddr` - Billing address\r\n- `TxnTaxDetail` - Tax details\r\n- `SalesTermRef` - Payment terms\r\n- `ShipMethodRef` - Shipping method\r\n- `ShipDate` - Ship date\r\n- `TrackingNum` - Tracking number\r\n- `TotalAmt` (read-only) - Total amount\r\n- `Balance` (read-only) - Remaining balance\r\n- `EmailStatus` - Email status (read-only)\r\n- `PrintStatus` - Print status\r\n\r\n**Query Examples:**\r\n```sql\r\nSELECT * FROM Invoice WHERE Balance > 0\r\nSELECT * FROM Invoice WHERE DueDate < '2026-02-21' AND Balance > 0\r\nSELECT * FROM Invoice WHERE CustomerRef = '123'\r\nSELECT Id, DocNumber, TotalAmt, Balance FROM Invoice ORDER BY TxnDate DESC\r\nSELECT * FROM Invoice WHERE TxnDate >= '2026-01-01' AND TxnDate <= '2026-01-31'\r\n```\r\n\r\n### Item\r\n\r\n**Types:** Service, Inventory, NonInventory, Category, Group\r\n\r\n**Common Fields:**\r\n- `Name` (required) - Item name\r\n- `Type` (required) - Item type\r\n- `Description` - Item description\r\n- `Active` - Boolean, item status\r\n- `UnitPrice` - Sales price\r\n- `PurchaseCost` - Purchase cost\r\n- `QtyOnHand` - Quantity (Inventory only)\r\n- `InvStartDate` - Inventory start date (required for Inventory)\r\n- `IncomeAccountRef.value` - Income account\r\n- `ExpenseAccountRef.value` - Expense account (Inventory/NonInventory)\r\n- `AssetAccountRef.value` - Asset account (Inventory only)\r\n- `TrackQtyOnHand` - Boolean, track inventory (Inventory only)\r\n- `Taxable` - Boolean, item is taxable\r\n- `SalesTaxCodeRef.value` - Sales tax code\r\n\r\n**Query Examples:**\r\n```sql\r\nSELECT * FROM Item WHERE Active = true ORDER BY Name\r\nSELECT * FROM Item WHERE Type = 'Inventory'\r\nSELECT * FROM Item WHERE QtyOnHand < 10\r\nSELECT Name, UnitPrice, QtyOnHand FROM Item WHERE Type = 'Inventory'\r\n```\r\n\r\n### Payment\r\n\r\n**Fields:**\r\n- `CustomerRef.value` (required) - Customer ID\r\n- `TotalAmt` (required) - Total payment amount\r\n- `TxnDate` - Transaction date\r\n- `Line` - Array of line items\r\n  - `Amount` - Amount applied\r\n  - `LinkedTxn` - Array of linked transactions\r\n    - `TxnId` - Transaction ID (usually Invoice)\r\n    - `TxnType` - Transaction type (usually \"Invoice\")\r\n- `PaymentMethodRef.value` - Payment method\r\n- `PaymentRefNum` - Check number or reference\r\n- `DepositToAccountRef.value` - Deposit account\r\n- `PrivateNote` - Internal note\r\n- `UnappliedAmt` (read-only) - Unapplied amount\r\n- `ProcessPayment` - Boolean, process payment (for credit cards)\r\n\r\n**Query Examples:**\r\n```sql\r\nSELECT * FROM Payment WHERE TxnDate >= '2026-01-01'\r\nSELECT * FROM Payment WHERE CustomerRef = '123'\r\nSELECT Id, TxnDate, TotalAmt, UnappliedAmt FROM Payment ORDER BY TxnDate DESC\r\n```\r\n\r\n### Estimate\r\n\r\n**Fields:**\r\nSimilar to Invoice, but represents a quote/estimate rather than an actual sale.\r\n\r\n- `CustomerRef.value` (required)\r\n- `Line` (required) - Same structure as Invoice\r\n- `TxnDate` - Estimate date\r\n- `ExpirationDate` - Expiration date\r\n- `AcceptedBy` - Name of person who accepted\r\n- `AcceptedDate` - Date accepted\r\n- `TxnStatus` - Accepted, Closed, Pending, Rejected\r\n- `CustomerMemo.value` - Message to customer\r\n- `EmailStatus` (read-only)\r\n- `TotalAmt` (read-only)\r\n\r\n**Query Examples:**\r\n```sql\r\nSELECT * FROM Estimate WHERE TxnStatus = 'Pending'\r\nSELECT * FROM Estimate WHERE CustomerRef = '123'\r\nSELECT * FROM Estimate WHERE ExpirationDate < '2026-02-21' AND TxnStatus = 'Pending'\r\n```\r\n\r\n### Vendor\r\n\r\n**Fields:**\r\n- `DisplayName` (required) - Vendor name\r\n- `CompanyName` - Company name\r\n- `Title`, `GivenName`, `MiddleName`, `FamilyName`, `Suffix`\r\n- `PrimaryEmailAddr.Address` - Email\r\n- `PrimaryPhone.FreeFormNumber` - Phone\r\n- `Mobile.FreeFormNumber` - Mobile\r\n- `Fax.FreeFormNumber` - Fax\r\n- `WebAddr.URI` - Website\r\n- `BillAddr` - Address object (same structure as Customer)\r\n- `Active` - Boolean, vendor status\r\n- `Balance` - Current balance (read-only)\r\n- `AcctNum` - Account number\r\n- `Vendor1099` - Boolean, if vendor receives 1099\r\n- `TaxIdentifier` - Tax ID/SSN\r\n- `TermRef` - Payment terms\r\n\r\n**Query Examples:**\r\n```sql\r\nSELECT * FROM Vendor WHERE Active = true ORDER BY DisplayName\r\nSELECT * FROM Vendor WHERE Balance > 0\r\nSELECT * FROM Vendor WHERE Vendor1099 = true\r\n```\r\n\r\n### Bill\r\n\r\n**Fields:**\r\n- `VendorRef.value` (required) - Vendor ID\r\n- `Line` (required) - Array of line items\r\n  - `Amount` (required)\r\n  - `DetailType` - Usually \"AccountBasedExpenseLineDetail\" or \"ItemBasedExpenseLineDetail\"\r\n  - `Description`\r\n  - `AccountBasedExpenseLineDetail`\r\n    - `AccountRef.value` - Expense account ID\r\n    - `TaxCodeRef.value` - Tax code\r\n  - `ItemBasedExpenseLineDetail`\r\n    - `ItemRef.value` - Item ID\r\n    - `Qty` - Quantity\r\n    - `UnitPrice` - Price per unit\r\n- `TxnDate` - Transaction date\r\n- `DueDate` - Due date\r\n- `DocNumber` - Bill number\r\n- `PrivateNote` - Internal note\r\n- `APAccountRef.value` - Accounts Payable account\r\n- `TotalAmt` (read-only)\r\n- `Balance` (read-only)\r\n\r\n**Query Examples:**\r\n```sql\r\nSELECT * FROM Bill WHERE Balance > 0\r\nSELECT * FROM Bill WHERE DueDate < '2026-02-21' AND Balance > 0\r\nSELECT * FROM Bill WHERE VendorRef = '789'\r\n```\r\n\r\n### Account\r\n\r\n**Types:** Bank, Accounts Receivable, Other Current Asset, Fixed Asset, Other Asset, Accounts Payable, Credit Card, Other Current Liability, Long Term Liability, Equity, Income, Cost of Goods Sold, Expense, Other Income, Other Expense\r\n\r\n**Fields:**\r\n- `Name` (required) - Account name\r\n- `AccountType` (required) - Account type from list above\r\n- `AccountSubType` - Specific subtype\r\n- `Description` - Account description\r\n- `Active` - Boolean, account status\r\n- `CurrentBalance` (read-only) - Current balance\r\n- `CurrentBalanceWithSubAccounts` (read-only)\r\n- `AcctNum` - Account number\r\n- `SubAccount` - Boolean, is sub-account\r\n- `ParentRef.value` - Parent account ID (if sub-account)\r\n\r\n**Query Examples:**\r\n```sql\r\nSELECT * FROM Account WHERE Active = true ORDER BY Name\r\nSELECT * FROM Account WHERE AccountType = 'Income'\r\nSELECT * FROM Account WHERE AccountType = 'Expense'\r\nSELECT * FROM Account WHERE AccountType = 'Bank'\r\nSELECT Name, AccountType, CurrentBalance FROM Account WHERE CurrentBalance != 0\r\n```\r\n\r\n### SalesReceipt\r\n\r\n**Fields:**\r\nSimilar to Invoice, but represents an immediate cash sale.\r\n\r\n- `CustomerRef.value` (required)\r\n- `Line` (required) - Same structure as Invoice\r\n- `TxnDate` - Transaction date\r\n- `PaymentMethodRef.value` - Payment method\r\n- `PaymentRefNum` - Check/reference number\r\n- `DepositToAccountRef.value` - Deposit account\r\n- `CustomerMemo.value` - Message to customer\r\n- `PrivateNote` - Internal note\r\n- `TotalAmt` (read-only)\r\n\r\n**Query Examples:**\r\n```sql\r\nSELECT * FROM SalesReceipt WHERE TxnDate >= '2026-01-01'\r\nSELECT * FROM SalesReceipt WHERE CustomerRef = '123'\r\nSELECT * FROM SalesReceipt WHERE PaymentMethodRef = '1'\r\n```\r\n\r\n### PurchaseOrder\r\n\r\n**Fields:**\r\n- `VendorRef.value` (required) - Vendor ID\r\n- `Line` (required) - Array of line items\r\n  - `Amount` (required)\r\n  - `DetailType` - Usually \"ItemBasedExpenseLineDetail\"\r\n  - `Description`\r\n  - `ItemBasedExpenseLineDetail`\r\n    - `ItemRef.value` - Item ID\r\n    - `Qty` - Quantity\r\n    - `UnitPrice` - Price per unit\r\n- `TxnDate` - Transaction date\r\n- `DueDate` - Expected delivery date\r\n- `DocNumber` - PO number\r\n- `ShipAddr` - Shipping address\r\n- `ShipMethodRef` - Shipping method\r\n- `POStatus` - Open, Closed\r\n- `POEmail.Address` - Email to send PO\r\n- `TotalAmt` (read-only)\r\n\r\n**Query Examples:**\r\n```sql\r\nSELECT * FROM PurchaseOrder WHERE POStatus = 'Open'\r\nSELECT * FROM PurchaseOrder WHERE VendorRef = '789'\r\nSELECT * FROM PurchaseOrder WHERE TxnDate >= '2026-01-01'\r\n```\r\n\r\n## Report Types\r\n\r\n### ProfitAndLoss\r\n**Parameters:**\r\n- `start_date` (required) - Start date (YYYY-MM-DD)\r\n- `end_date` (required) - End date (YYYY-MM-DD)\r\n- `accounting_method` - Cash or Accrual\r\n- `summarize_column_by` - Total, Month, Quarter, Year\r\n\r\n### BalanceSheet\r\n**Parameters:**\r\n- `date` (required) - Report date (YYYY-MM-DD)\r\n- `accounting_method` - Cash or Accrual\r\n\r\n### CashFlow\r\n**Parameters:**\r\n- `start_date` (required) - Start date\r\n- `end_date` (required) - End date\r\n- `accounting_method` - Cash or Accrual\r\n\r\n### AgedReceivables\r\n**Parameters:**\r\n- `report_date` - As of date\r\n- `aging_method` - Report Basis, Current\r\n- `num_periods` - Number of aging periods (default: 4)\r\n- `aging_period` - Number of days in each period (default: 30)\r\n\r\n### AgedPayables\r\n**Parameters:**\r\nSame as AgedReceivables\r\n\r\n## Query Language (SQL-like)\r\n\r\n### Syntax\r\n```sql\r\nSELECT [fields] FROM [Entity] WHERE [conditions] ORDER BY [field] [ASC|DESC]\r\n```\r\n\r\n### Operators\r\n- `=` Equal\r\n- `>` Greater than\r\n- `<` Less than\r\n- `>=` Greater than or equal\r\n- `<=` Less than or equal\r\n- `<>` or `!=` Not equal\r\n- `LIKE` Pattern matching (use `%` wildcard)\r\n- `IN` Match any value in list\r\n- `AND` Logical AND\r\n- `OR` Logical OR\r\n\r\n### Examples\r\n\r\n**Select specific fields:**\r\n```sql\r\nSELECT Id, DisplayName, Balance FROM Customer\r\n```\r\n\r\n**Where clause:**\r\n```sql\r\nSELECT * FROM Invoice WHERE Balance > 0 AND DueDate < '2026-02-21'\r\n```\r\n\r\n**Pattern matching:**\r\n```sql\r\nSELECT * FROM Customer WHERE DisplayName LIKE '%Corp%'\r\n```\r\n\r\n**In clause:**\r\n```sql\r\nSELECT * FROM Item WHERE Type IN ('Service', 'Inventory')\r\n```\r\n\r\n**Order by:**\r\n```sql\r\nSELECT * FROM Customer ORDER BY Balance DESC\r\n```\r\n\r\n**Complex conditions:**\r\n```sql\r\nSELECT * FROM Invoice \r\nWHERE (Balance > 0 AND DueDate < '2026-02-21') \r\n   OR (TotalAmt > 1000 AND EmailStatus = 'NotSent')\r\nORDER BY DueDate ASC\r\n```\r\n\r\n### Queryable Entities\r\n\r\nFull list of entities you can query:\r\n\r\n- Account\r\n- Bill\r\n- BillPayment\r\n- Class\r\n- CreditMemo\r\n- Customer\r\n- Department\r\n- Deposit\r\n- Employee\r\n- Estimate\r\n- Invoice\r\n- Item\r\n- JournalEntry\r\n- Payment\r\n- PaymentMethod\r\n- Purchase\r\n- PurchaseOrder\r\n- RefundReceipt\r\n- SalesReceipt\r\n- TaxCode\r\n- TaxRate\r\n- Term\r\n- TimeActivity\r\n- Transfer\r\n- Vendor\r\n- VendorCredit\r\n\r\n## Error Codes\r\n\r\n### Common HTTP Status Codes\r\n\r\n- `200` - Success\r\n- `400` - Bad Request (validation error)\r\n- `401` - Unauthorized (invalid/expired token)\r\n- `403` - Forbidden (insufficient permissions)\r\n- `404` - Not Found (entity doesn't exist)\r\n- `429` - Too Many Requests (rate limit exceeded)\r\n- `500` - Internal Server Error\r\n- `503` - Service Unavailable\r\n\r\n### QuickBooks Error Types\r\n\r\n**ValidationFault:**\r\n- Missing required fields\r\n- Invalid field values\r\n- Invalid references\r\n\r\n**AuthenticationFault:**\r\n- Invalid or expired access token\r\n- Invalid company/realm ID\r\n\r\n**AuthorizationFault:**\r\n- Insufficient permissions\r\n- Feature not enabled for account\r\n\r\n**ServiceException:**\r\n- Internal QuickBooks error\r\n- Try again later\r\n\r\n## Rate Limits\r\n\r\n### Sandbox\r\n- 500 requests per minute per app\r\n- 100 requests per minute per user (across all apps)\r\n\r\n### Production\r\nVaries by subscription:\r\n- **QuickBooks Online Plus**: 500 requests/minute\r\n- **QuickBooks Online Advanced**: 1000 requests/minute\r\n\r\n**Rate Limit Headers:**\r\n```\r\nintuit_tid: [transaction ID]\r\nX-RateLimit-Limit: 500\r\nX-RateLimit-Remaining: 499\r\nX-RateLimit-Reset: 1234567890\r\n```\r\n\r\n## Authentication Flow\r\n\r\n### 1. Authorization URL\r\n```\r\nhttps://appcenter.intuit.com/connect/oauth2?\r\n  client_id=[CLIENT_ID]&\r\n  redirect_uri=[REDIRECT_URI]&\r\n  response_type=code&\r\n  scope=com.intuit.quickbooks.accounting&\r\n  state=[RANDOM_STATE]\r\n```\r\n\r\n### 2. Exchange Code for Token\r\n```\r\nPOST https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer\r\nAuthorization: Basic [BASE64(client_id:client_secret)]\r\nContent-Type: application/x-www-form-urlencoded\r\n\r\ngrant_type=authorization_code&\r\ncode=[AUTH_CODE]&\r\nredirect_uri=[REDIRECT_URI]\r\n```\r\n\r\n### 3. Refresh Token\r\n```\r\nPOST https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer\r\nAuthorization: Basic [BASE64(client_id:client_secret)]\r\nContent-Type: application/x-www-form-urlencoded\r\n\r\ngrant_type=refresh_token&\r\nrefresh_token=[REFRESH_TOKEN]\r\n```\r\n\r\n### Token Lifetimes\r\n- **Access Token**: 1 hour\r\n- **Refresh Token**: 100 days (renewable)\r\n\r\n## Best Practices\r\n\r\n### 1. Error Handling\r\nAlways wrap API calls in try-catch and handle specific error types.\r\n\r\n### 2. Token Management\r\n- Refresh tokens proactively (don't wait for expiration)\r\n- Store tokens securely\r\n- Implement token refresh logic\r\n\r\n### 3. Data Validation\r\n- Validate input before sending to API\r\n- Check for required references\r\n- Ensure dates are in correct format\r\n\r\n### 4. Performance\r\n- Use batch operations when possible\r\n- Cache reference data (accounts, items)\r\n- Use specific queries instead of SELECT *\r\n- Implement pagination for large result sets\r\n\r\n### 5. Idempotency\r\n- Store transaction IDs to prevent duplicates\r\n- Use unique DocNumbers for invoices\r\n- Implement retry logic with exponential backoff\r\n\r\n### 6. Testing\r\n- Always test in Sandbox first\r\n- Create test data for different scenarios\r\n- Test error conditions\r\n\r\n### 7. Webhooks\r\nConsider using webhooks for:\r\n- Real-time updates\r\n- Change notifications\r\n- Event-driven architecture\r\n\r\n## Environment Differences\r\n\r\n### Sandbox\r\n- Test environment with sample data\r\n- No real financial impact\r\n- Can create unlimited test companies\r\n- Same API as production\r\n\r\n### Production\r\n- Real customer data\r\n- Real financial transactions\r\n- Requires approval and review\r\n- Company limit based on subscription\r\n\r\n## Additional Resources\r\n\r\n- [API Explorer](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/account)\r\n- [API Reference](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/account)\r\n- [Webhooks Documentation](https://developer.intuit.com/app/developer/qbo/docs/develop/webhooks)\r\n- [Sample Apps](https://developer.intuit.com/app/developer/qbo/docs/get-started/start-developing-your-app)\r\n- [Developer Forum](https://help.developer.intuit.com/s/)\n\nFile v1.0.1:CHANGELOG.md\n\n# Changelog\r\n\r\nAll notable changes to the QuickBooks API Skill will be documented in this file.\r\n\r\nThe format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),\r\nand this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\r\n\r\n## [1.0.1] - 2026-02-21\r\n\r\n### Fixed\r\n- **Port Mismatch**: Standardized redirect URI and callback server to port 3001 across all documentation (was inconsistent between 3000 and 3001)\r\n- **Dependency Cleanup**: Removed unused `@modelcontextprotocol/sdk` reference from SKILL.md (not actually required)\r\n- **API Endpoint**: Changed from hard-coded sandbox URL to configurable environment setting\r\n\r\n### Added\r\n- **Configurable API Environment**: Added `api_environment` field to `config.json` allowing easy switching between sandbox and production\r\n- **Security Documentation**: Comprehensive security warnings about credential storage in plaintext\r\n- **Security Best Practices**: 10-point security checklist for production deployments\r\n- **Environment Troubleshooting**: Added guidance for API environment configuration issues\r\n\r\n### Changed\r\n- Config template now includes `api_environment: \"sandbox\"` by default\r\n- `run.js` now reads `api_environment` from config and selects correct API base URL dynamically\r\n- Enhanced documentation with specific security considerations for credential management\r\n- Updated version numbers across all documentation files\r\n\r\n### Security\r\n- Added explicit warnings about plaintext credential storage in `config.json`\r\n- Documented file permission requirements\r\n- Added recommendations for credential rotation\r\n- Included notes about autoStart risks\r\n\r\n## [1.0.0] - 2026-02-21\r\n\r\n### Added\r\n- Initial release of QuickBooks API Skill\r\n- OAuth2 authentication flow with automatic token refresh\r\n- Customer management (create, read, query)\r\n- Invoice operations (create, read, send, query)\r\n- Item/Product management (create, read, query)\r\n- Payment processing (create, query)\r\n- Estimate/Quote management (create, query)\r\n- Vendor management (create, query)\r\n- Bill management (create, query)\r\n- Purchase Order operations (create, query)\r\n- Sales Receipt operations (create, query)\r\n- Financial reports:\r\n  - Profit & Loss statement\r\n  - Balance Sheet\r\n  - Cash Flow statement\r\n  - Aged Receivables (A/R Aging)\r\n  - Aged Payables (A/P Aging)\r\n- Chart of Accounts querying\r\n- Company information retrieval\r\n- Generic SQL-like query support for all entities\r\n- Batch operations for multiple requests\r\n- Tax code and rate management\r\n- Comprehensive error handling\r\n- Automatic token refresh mechanism\r\n- Configuration file management\r\n- Complete documentation:\r\n  - README.md with setup instructions\r\n  - EXAMPLES.md with practical examples\r\n  - API_REFERENCE.md with complete API documentation\r\n  - TROUBLESHOOTING.md with common issues and solutions\r\n- Support for both Sandbox and Production environments\r\n\r\n### Features\r\n- 40+ tool implementations covering core QuickBooks operations\r\n- Support for complex SQL queries with WHERE, ORDER BY clauses\r\n- Automatic OAuth2 flow with browser integration\r\n- Local callback server for OAuth completion\r\n- Secure credential storage\r\n- Rate limiting awareness\r\n- Cross-platform compatibility (Windows, macOS, Linux)\r\n\r\n### Security\r\n- Secure OAuth2 authentication\r\n- Token encryption and storage\r\n- No hardcoded credentials\r\n- .gitignore included to prevent credential leaks\r\n- Config file safety checks\r\n\r\n### Documentation\r\n- Comprehensive README with setup guide\r\n- 50+ working examples across all entity types\r\n- Complete API reference documentation\r\n- Troubleshooting guide with 10+ common issues\r\n- Inline code comments and JSDoc\r\n\r\n## [Unreleased]\r\n\r\n### Planned Features\r\n- Webhook support for real-time updates\r\n- Advanced batch operation builder\r\n- Transaction history tracking\r\n- Recurring transaction support\r\n- Multi-company management\r\n- Enhanced report customization\r\n- PDF attachment support\r\n- Credit memo operations\r\n- Refund receipt operations\r\n- Time tracking integration\r\n- Project management integration\r\n- Inventory tracking enhancements\r\n- Custom field support\r\n- Audit log retrieval\r\n- Change data capture (CDC) queries\r\n- Advanced filtering and pagination\r\n- GraphQL support (if available)\r\n- Automated testing suite\r\n- Performance monitoring\r\n- Retry logic with exponential backoff\r\n- Rate limit management\r\n\r\n### Potential Improvements\r\n- TypeScript migration for better type safety\r\n- CLI tool for standalone usage\r\n- Web dashboard for credential management\r\n- Interactive authentication flow\r\n- Better error messages with solutions\r\n- Caching layer for frequently accessed data\r\n- Query builder helper functions\r\n- Transaction rollback capabilities\r\n- Bulk import/export functionality\r\n- Migration tools for other accounting systems\r\n- Integration templates for common workflows\r\n\r\n## Version History\r\n\r\n### Version 1.0.0 - Initial Release\r\n**Release Date:** February 21, 2026\r\n\r\n**Focus:** Complete QuickBooks Online API integration with OpenClaw/MCP\r\n\r\n**Goals Achieved:**\r\n✅ Full OAuth2 implementation\r\n✅ All major entity CRUD operations\r\n✅ Comprehensive reporting capabilities\r\n✅ SQL query support\r\n✅ Batch operations\r\n✅ Complete documentation\r\n✅ Cross-platform support\r\n✅ Production-ready error handling\r\n\r\n**Metrics:**\r\n- 40+ tools implemented\r\n- 500+ lines of core functionality\r\n- 100+ example use cases documented\r\n- 50+ troubleshooting scenarios covered\r\n\r\n## Contributing\r\n\r\nWe welcome contributions! Areas we'd love help with:\r\n\r\n1. **Testing**\r\n   - Unit tests for core functions\r\n   - Integration tests with sandbox\r\n   - Edge case testing\r\n\r\n2. **Documentation**\r\n   - More examples and use cases\r\n   - Video tutorials\r\n   - Translation to other languages\r\n\r\n3. **Features**\r\n   - New entity support\r\n   - Enhanced error handling\r\n   - Performance optimizations\r\n\r\n4. **Bug Fixes**\r\n   - Report issues on GitHub\r\n   - Submit pull requests with fixes\r\n\r\n## Support\r\n\r\nFor issues and questions:\r\n- Check [TROUBLESHOOTING.md](TROUBLESHOOTING.md)\r\n- Review [EXAMPLES.md](EXAMPLES.md)\r\n- Visit [QuickBooks Developer Forum](https://help.developer.intuit.com/s/)\r\n- Open an issue on GitHub\r\n\r\n## License\r\n\r\nMIT License - See [LICENSE](LICENSE) file for details\r\n\r\n## Acknowledgments\r\n\r\n- Intuit QuickBooks API team for comprehensive documentation\r\n- Model Context Protocol (MCP) community\r\n- OpenClaw project contributors\r\n- All users providing feedback and bug reports\r\n\r\n---\r\n\r\n*For detailed API changes by QuickBooks, see [QuickBooks Release Notes](https://developer.intuit.com/app/developer/qbo/docs/release-notes)*\n\nFile v1.0.1:EXAMPLES.md\n\n# QuickBooks API Examples\r\n\r\nThis document provides practical examples for common QuickBooks operations using the skill.\r\n\r\n## Table of Contents\r\n- [Setup & Authentication](#setup--authentication)\r\n- [Customer Management](#customer-management)\r\n- [Invoice Workflows](#invoice-workflows)\r\n- [Inventory Management](#inventory-management)\r\n- [Payment Processing](#payment-processing)\r\n- [Financial Reporting](#financial-reporting)\r\n- [Vendor & Bill Management](#vendor--bill-management)\r\n- [Advanced Queries](#advanced-queries)\r\n\r\n## Setup & Authentication\r\n\r\n### Initial Authentication\r\n\r\n```javascript\r\n// Step 1: Authenticate with QuickBooks\r\n{\r\n  \"tool\": \"qb_authenticate\",\r\n  \"arguments\": {\r\n    \"client_id\": \"ABxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\r\n    \"client_secret\": \"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\"\r\n  }\r\n}\r\n```\r\n\r\nThis will:\r\n1. Open a browser window\r\n2. Redirect to QuickBooks authorization\r\n3. Capture the auth code automatically\r\n4. Save tokens to config.json\r\n\r\n## Customer Management\r\n\r\n### Create a Basic Customer\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_create_customer\",\r\n  \"arguments\": {\r\n    \"DisplayName\": \"Acme Corporation\",\r\n    \"CompanyName\": \"Acme Corp\",\r\n    \"PrimaryEmailAddr\": {\r\n      \"Address\": \"billing@acme.com\"\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### Create a Customer with Full Details\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_create_customer\",\r\n  \"arguments\": {\r\n    \"DisplayName\": \"John Smith\",\r\n    \"GivenName\": \"John\",\r\n    \"FamilyName\": \"Smith\",\r\n    \"CompanyName\": \"Smith Consulting\",\r\n    \"PrimaryEmailAddr\": {\r\n      \"Address\": \"john@smithconsulting.com\"\r\n    },\r\n    \"PrimaryPhone\": {\r\n      \"FreeFormNumber\": \"(555) 123-4567\"\r\n    },\r\n    \"Mobile\": {\r\n      \"FreeFormNumber\": \"(555) 987-6543\"\r\n    },\r\n    \"BillAddr\": {\r\n      \"Line1\": \"123 Main Street\",\r\n      \"Line2\": \"Suite 100\",\r\n      \"City\": \"San Francisco\",\r\n      \"CountrySubDivisionCode\": \"CA\",\r\n      \"PostalCode\": \"94102\",\r\n      \"Country\": \"USA\"\r\n    },\r\n    \"ShipAddr\": {\r\n      \"Line1\": \"456 Oak Avenue\",\r\n      \"City\": \"San Francisco\",\r\n      \"CountrySubDivisionCode\": \"CA\",\r\n      \"PostalCode\": \"94103\",\r\n      \"Country\": \"USA\"\r\n    },\r\n    \"Notes\": \"Preferred customer - Net 30 terms\",\r\n    \"WebAddr\": {\r\n      \"URI\": \"https://smithconsulting.com\"\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### Find Customers by Name\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_query_customers\",\r\n  \"arguments\": {\r\n    \"query\": \"SELECT * FROM Customer WHERE DisplayName LIKE '%Smith%'\"\r\n  }\r\n}\r\n```\r\n\r\n### Get All Active Customers\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_query_customers\",\r\n  \"arguments\": {\r\n    \"query\": \"SELECT * FROM Customer WHERE Active = true ORDER BY DisplayName\"\r\n  }\r\n}\r\n```\r\n\r\n### Get Customer by ID\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_get_customer\",\r\n  \"arguments\": {\r\n    \"customer_id\": \"123\"\r\n  }\r\n}\r\n```\r\n\r\n## Invoice Workflows\r\n\r\n### Create a Simple Invoice\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_create_invoice\",\r\n  \"arguments\": {\r\n    \"CustomerRef\": {\r\n      \"value\": \"123\"\r\n    },\r\n    \"Line\": [\r\n      {\r\n        \"Amount\": 500.00,\r\n        \"DetailType\": \"SalesItemLineDetail\",\r\n        \"SalesItemLineDetail\": {\r\n          \"ItemRef\": {\r\n            \"value\": \"1\"\r\n          },\r\n          \"Qty\": 10,\r\n          \"UnitPrice\": 50.00\r\n        }\r\n      }\r\n    ],\r\n    \"TxnDate\": \"2026-02-21\",\r\n    \"DueDate\": \"2026-03-21\"\r\n  }\r\n}\r\n```\r\n\r\n### Create an Invoice with Multiple Line Items\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_create_invoice\",\r\n  \"arguments\": {\r\n    \"CustomerRef\": {\r\n      \"value\": \"123\"\r\n    },\r\n    \"Line\": [\r\n      {\r\n        \"Amount\": 1000.00,\r\n        \"DetailType\": \"SalesItemLineDetail\",\r\n        \"Description\": \"Consulting Services - February 2026\",\r\n        \"SalesItemLineDetail\": {\r\n          \"ItemRef\": {\r\n            \"value\": \"1\"\r\n          },\r\n          \"Qty\": 20,\r\n          \"UnitPrice\": 50.00\r\n        }\r\n      },\r\n      {\r\n        \"Amount\": 150.00,\r\n        \"DetailType\": \"SalesItemLineDetail\",\r\n        \"Description\": \"Travel Expenses\",\r\n        \"SalesItemLineDetail\": {\r\n          \"ItemRef\": {\r\n            \"value\": \"2\"\r\n          },\r\n          \"Qty\": 1,\r\n          \"UnitPrice\": 150.00\r\n        }\r\n      }\r\n    ],\r\n    \"TxnDate\": \"2026-02-21\",\r\n    \"DueDate\": \"2026-03-21\",\r\n    \"CustomerMemo\": {\r\n      \"value\": \"Thank you for your business!\"\r\n    },\r\n    \"BillEmail\": {\r\n      \"Address\": \"billing@customer.com\"\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### Send an Invoice via Email\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_send_invoice\",\r\n  \"arguments\": {\r\n    \"invoice_id\": \"456\",\r\n    \"email\": \"customer@example.com\"\r\n  }\r\n}\r\n```\r\n\r\n### Query Unpaid Invoices\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_query_invoices\",\r\n  \"arguments\": {\r\n    \"query\": \"SELECT * FROM Invoice WHERE Balance > 0 ORDER BY DueDate\"\r\n  }\r\n}\r\n```\r\n\r\n### Query Invoices by Date Range\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_query_invoices\",\r\n  \"arguments\": {\r\n    \"query\": \"SELECT * FROM Invoice WHERE TxnDate >= '2026-01-01' AND TxnDate <= '2026-01-31'\"\r\n  }\r\n}\r\n```\r\n\r\n### Query Overdue Invoices\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_query_invoices\",\r\n  \"arguments\": {\r\n    \"query\": \"SELECT * FROM Invoice WHERE Balance > 0 AND DueDate < '2026-02-21' ORDER BY DueDate\"\r\n  }\r\n}\r\n```\r\n\r\n## Inventory Management\r\n\r\n### Create a Service Item\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_create_item\",\r\n  \"arguments\": {\r\n    \"Name\": \"Consulting Services\",\r\n    \"Type\": \"Service\",\r\n    \"Description\": \"Hourly consulting services\",\r\n    \"UnitPrice\": 150.00,\r\n    \"IncomeAccountRef\": {\r\n      \"value\": \"79\"\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### Create an Inventory Item\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_create_item\",\r\n  \"arguments\": {\r\n    \"Name\": \"Widget Pro 3000\",\r\n    \"Type\": \"Inventory\",\r\n    \"Description\": \"Professional grade widget\",\r\n    \"UnitPrice\": 299.99,\r\n    \"QtyOnHand\": 50,\r\n    \"InvStartDate\": \"2026-01-01\",\r\n    \"IncomeAccountRef\": {\r\n      \"value\": \"79\"\r\n    },\r\n    \"ExpenseAccountRef\": {\r\n      \"value\": \"80\"\r\n    },\r\n    \"AssetAccountRef\": {\r\n      \"value\": \"81\"\r\n    },\r\n    \"TrackQtyOnHand\": true\r\n  }\r\n}\r\n```\r\n\r\n### Create a Non-Inventory Item\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_create_item\",\r\n  \"arguments\": {\r\n    \"Name\": \"Shipping & Handling\",\r\n    \"Type\": \"NonInventory\",\r\n    \"Description\": \"Standard shipping fee\",\r\n    \"UnitPrice\": 15.00,\r\n    \"IncomeAccountRef\": {\r\n      \"value\": \"79\"\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### Query All Items\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_query_items\",\r\n  \"arguments\": {\r\n    \"query\": \"SELECT * FROM Item WHERE Active = true ORDER BY Name\"\r\n  }\r\n}\r\n```\r\n\r\n### Query Low Stock Items\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_query_items\",\r\n  \"arguments\": {\r\n    \"query\": \"SELECT * FROM Item WHERE Type = 'Inventory' AND QtyOnHand < 10\"\r\n  }\r\n}\r\n```\r\n\r\n## Payment Processing\r\n\r\n### Record a Full Payment Against an Invoice\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_create_payment\",\r\n  \"arguments\": {\r\n    \"CustomerRef\": {\r\n      \"value\": \"123\"\r\n    },\r\n    \"TotalAmt\": 500.00,\r\n    \"TxnDate\": \"2026-02-21\",\r\n    \"Line\": [\r\n      {\r\n        \"Amount\": 500.00,\r\n        \"LinkedTxn\": [\r\n          {\r\n            \"TxnId\": \"456\",\r\n            \"TxnType\": \"Invoice\"\r\n          }\r\n        ]\r\n      }\r\n    ],\r\n    \"PaymentMethodRef\": {\r\n      \"value\": \"1\"\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### Record a Partial Payment\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_create_payment\",\r\n  \"arguments\": {\r\n    \"CustomerRef\": {\r\n      \"value\": \"123\"\r\n    },\r\n    \"TotalAmt\": 250.00,\r\n    \"TxnDate\": \"2026-02-21\",\r\n    \"Line\": [\r\n      {\r\n        \"Amount\": 250.00,\r\n        \"LinkedTxn\": [\r\n          {\r\n            \"TxnId\": \"456\",\r\n            \"TxnType\": \"Invoice\"\r\n          }\r\n        ]\r\n      }\r\n    ],\r\n    \"PrivateNote\": \"Partial payment - balance due next month\"\r\n  }\r\n}\r\n```\r\n\r\n### Record a Payment for Multiple Invoices\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_create_payment\",\r\n  \"arguments\": {\r\n    \"CustomerRef\": {\r\n      \"value\": \"123\"\r\n    },\r\n    \"TotalAmt\": 1500.00,\r\n    \"TxnDate\": \"2026-02-21\",\r\n    \"Line\": [\r\n      {\r\n        \"Amount\": 1000.00,\r\n        \"LinkedTxn\": [\r\n          {\r\n            \"TxnId\": \"456\",\r\n            \"TxnType\": \"Invoice\"\r\n          }\r\n        ]\r\n      },\r\n      {\r\n        \"Amount\": 500.00,\r\n        \"LinkedTxn\": [\r\n          {\r\n            \"TxnId\": \"457\",\r\n            \"TxnType\": \"Invoice\"\r\n          }\r\n        ]\r\n      }\r\n    ]\r\n  }\r\n}\r\n```\r\n\r\n### Query Recent Payments\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_query_payments\",\r\n  \"arguments\": {\r\n    \"query\": \"SELECT * FROM Payment WHERE TxnDate >= '2026-02-01' ORDER BY TxnDate DESC\"\r\n  }\r\n}\r\n```\r\n\r\n## Financial Reporting\r\n\r\n### Get Profit & Loss Report for Last Month\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_get_profit_loss\",\r\n  \"arguments\": {\r\n    \"start_date\": \"2026-01-01\",\r\n    \"end_date\": \"2026-01-31\"\r\n  }\r\n}\r\n```\r\n\r\n### Get Year-to-Date Profit & Loss\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_get_profit_loss\",\r\n  \"arguments\": {\r\n    \"start_date\": \"2026-01-01\",\r\n    \"end_date\": \"2026-02-21\"\r\n  }\r\n}\r\n```\r\n\r\n### Get Current Balance Sheet\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_get_balance_sheet\",\r\n  \"arguments\": {\r\n    \"date\": \"2026-02-21\"\r\n  }\r\n}\r\n```\r\n\r\n### Get Cash Flow Report\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_get_cash_flow\",\r\n  \"arguments\": {\r\n    \"start_date\": \"2026-01-01\",\r\n    \"end_date\": \"2026-02-21\"\r\n  }\r\n}\r\n```\r\n\r\n### Get Aged Receivables (Who Owes You Money)\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_get_aged_receivables\",\r\n  \"arguments\": {}\r\n}\r\n```\r\n\r\n### Get Aged Payables (Who You Owe Money)\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_get_aged_payables\",\r\n  \"arguments\": {}\r\n}\r\n```\r\n\r\n## Vendor & Bill Management\r\n\r\n### Create a Vendor\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_create_vendor\",\r\n  \"arguments\": {\r\n    \"DisplayName\": \"Office Supplies Inc\",\r\n    \"CompanyName\": \"Office Supplies Inc\",\r\n    \"PrimaryEmailAddr\": {\r\n      \"Address\": \"billing@officesupplies.com\"\r\n    },\r\n    \"PrimaryPhone\": {\r\n      \"FreeFormNumber\": \"(555) 555-5555\"\r\n    },\r\n    \"BillAddr\": {\r\n      \"Line1\": \"789 Commercial Blvd\",\r\n      \"City\": \"New York\",\r\n      \"CountrySubDivisionCode\": \"NY\",\r\n      \"PostalCode\": \"10001\"\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### Create a Bill\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_create_bill\",\r\n  \"arguments\": {\r\n    \"VendorRef\": {\r\n      \"value\": \"789\"\r\n    },\r\n    \"Line\": [\r\n      {\r\n        \"Amount\": 350.00,\r\n        \"DetailType\": \"AccountBasedExpenseLineDetail\",\r\n        \"AccountBasedExpenseLineDetail\": {\r\n          \"AccountRef\": {\r\n            \"value\": \"7\"\r\n          }\r\n        },\r\n        \"Description\": \"Office supplies - February\"\r\n      }\r\n    ],\r\n    \"TxnDate\": \"2026-02-21\",\r\n    \"DueDate\": \"2026-03-21\"\r\n  }\r\n}\r\n```\r\n\r\n### Query Unpaid Bills\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_query\",\r\n  \"arguments\": {\r\n    \"query\": \"SELECT * FROM Bill WHERE Balance > 0 ORDER BY DueDate\"\r\n  }\r\n}\r\n```\r\n\r\n## Advanced Queries\r\n\r\n### Get Company Information\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_get_company_info\",\r\n  \"arguments\": {}\r\n}\r\n```\r\n\r\n### Query Chart of Accounts\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_query_accounts\",\r\n  \"arguments\": {\r\n    \"query\": \"SELECT * FROM Account WHERE Active = true ORDER BY Name\"\r\n  }\r\n}\r\n```\r\n\r\n### Get Income Accounts\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_query_accounts\",\r\n  \"arguments\": {\r\n    \"query\": \"SELECT * FROM Account WHERE AccountType = 'Income' AND Active = true\"\r\n  }\r\n}\r\n```\r\n\r\n### Get Expense Accounts\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_query_accounts\",\r\n  \"arguments\": {\r\n    \"query\": \"SELECT * FROM Account WHERE AccountType = 'Expense' AND Active = true\"\r\n  }\r\n}\r\n```\r\n\r\n### Complex Join Query (Invoices with Customer Names)\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_query\",\r\n  \"arguments\": {\r\n    \"query\": \"SELECT Invoice.Id, Invoice.TxnDate, Invoice.TotalAmt, Customer.DisplayName FROM Invoice INNER JOIN Customer ON Invoice.CustomerRef = Customer.Id WHERE Invoice.TxnDate >= '2026-01-01'\"\r\n  }\r\n}\r\n```\r\n\r\n### Create a Sales Receipt (Cash Sale)\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_create_sales_receipt\",\r\n  \"arguments\": {\r\n    \"CustomerRef\": {\r\n      \"value\": \"123\"\r\n    },\r\n    \"Line\": [\r\n      {\r\n        \"Amount\": 100.00,\r\n        \"DetailType\": \"SalesItemLineDetail\",\r\n        \"SalesItemLineDetail\": {\r\n          \"ItemRef\": {\r\n            \"value\": \"1\"\r\n          },\r\n          \"Qty\": 2,\r\n          \"UnitPrice\": 50.00\r\n        }\r\n      }\r\n    ],\r\n    \"TxnDate\": \"2026-02-21\",\r\n    \"PaymentMethodRef\": {\r\n      \"value\": \"1\"\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### Create an Estimate/Quote\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_create_estimate\",\r\n  \"arguments\": {\r\n    \"CustomerRef\": {\r\n      \"value\": \"123\"\r\n    },\r\n    \"Line\": [\r\n      {\r\n        \"Amount\": 5000.00,\r\n        \"DetailType\": \"SalesItemLineDetail\",\r\n        \"Description\": \"Website Development Project\",\r\n        \"SalesItemLineDetail\": {\r\n          \"ItemRef\": {\r\n            \"value\": \"1\"\r\n          },\r\n          \"Qty\": 100,\r\n          \"UnitPrice\": 50.00\r\n        }\r\n      }\r\n    ],\r\n    \"TxnDate\": \"2026-02-21\",\r\n    \"ExpirationDate\": \"2026-03-21\",\r\n    \"CustomerMemo\": {\r\n      \"value\": \"Estimate valid for 30 days\"\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### Batch Operations (Multiple Requests in One Call)\r\n\r\n```json\r\n{\r\n  \"tool\": \"qb_batch\",\r\n  \"arguments\": {\r\n    \"operations\": [\r\n      {\r\n        \"bId\": \"bid1\",\r\n        \"operation\": \"create\",\r\n        \"Customer\": {\r\n          \"DisplayName\": \"Batch Customer 1\"\r\n        }\r\n      },\r\n      {\r\n        \"bId\": \"bid2\",\r\n        \"operation\": \"create\",\r\n        \"Customer\": {\r\n          \"DisplayName\": \"Batch Customer 2\"\r\n        }\r\n      },\r\n      {\r\n        \"bId\": \"bid3\",\r\n        \"operation\": \"query\",\r\n        \"Query\": \"SELECT * FROM Invoice WHERE Balance > 0\"\r\n      }\r\n    ]\r\n  }\r\n}\r\n```\r\n\r\n## Tips & Best Practices\r\n\r\n### Date Formats\r\nAlways use ISO 8601 format: `YYYY-MM-DD` (e.g., `2026-02-21`)\r\n\r\n### Reference IDs\r\nMost entities require reference IDs in the format:\r\n```json\r\n{\r\n  \"value\": \"123\"\r\n}\r\n```\r\n\r\n### Line Item Details\r\nFor invoices and sales receipts, use `SalesItemLineDetail`.\r\nFor bills and expenses, use `AccountBasedExpenseLineDetail` or `ItemBasedExpenseLineDetail`.\r\n\r\n### Query Operators\r\n- `=` Equal to\r\n- `>` Greater than\r\n- `<` Less than\r\n- `>=` Greater than or equal\r\n- `<=` Less than or equal\r\n- `LIKE` Pattern matching (use `%` as wildcard)\r\n- `IN` Match any in list\r\n- `AND`, `OR` Logical operators\r\n\r\n### Common Pitfalls\r\n1. Always include required references (CustomerRef, ItemRef, etc.)\r\n2. Make sure referenced entities exist before creating dependent entities\r\n3. Use the correct entity type in queries (e.g., `FROM Customer` not `FROM Customers`)\r\n4. Include SyncToken when updating entities\r\n5. Check that dates are not in the future (QuickBooks may reject them)\r\n\r\n### Performance Tips\r\n1. Use specific queries instead of `SELECT *` when possible\r\n2. Use batch operations for multiple creates/updates\r\n3. Cache frequently used reference IDs (accounts, items, etc.)\r\n4. Use pagination for large result sets\r\n\r\n## Need Help?\r\n\r\n- Review the [README.md](README.md) for setup instructions\r\n- Check [QuickBooks API Documentation](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/account)\r\n- Visit the [QuickBooks Developer Forum](https://help.developer.intuit.com/s/)\n\nFile v1.0.1:SECURITY.md\n\n# Security Considerations\r\n\r\n## Overview\r\n\r\nThis QuickBooks API skill stores sensitive credentials locally in `config.json`. While this is acceptable for OAuth client applications, you should understand the security implications and take appropriate precautions.\r\n\r\n## What is Stored\r\n\r\nThe `config.json` file contains:\r\n\r\n- **Client ID**: Your QuickBooks app identifier (semi-public)\r\n- **Client Secret**: Your QuickBooks app secret key (SENSITIVE)\r\n- **Access Token**: Short-lived API access token (SENSITIVE)\r\n- **Refresh Token**: Long-lived token for obtaining new access tokens (VERY SENSITIVE)\r\n- **Realm ID**: QuickBooks company identifier (semi-public)\r\n\r\n## Risk Assessment\r\n\r\n### Medium Risk Scenarios\r\n- **Local Machine Compromise**: If an attacker gains access to your machine, they can read `config.json` and access your QuickBooks data\r\n- **Backup Exposure**: Unencrypted backups may contain credentials\r\n- **Multi-user Systems**: Other users on the same machine may be able to read the file\r\n\r\n### Low Risk Scenarios  \r\n- **Network Eavesdropping**: All API communication is over HTTPS\r\n- **Version Control Leak**: `.gitignore` prevents committing credentials (if used properly)\r\n\r\n## Recommended Security Measures\r\n\r\n### 1. File Permissions (Critical)\r\n\r\n**Windows:**\r\n```powershell\r\n# Set to owner-only access\r\n$acl = Get-Acl \"config.json\"\r\n$acl.SetAccessRuleProtection($true, $false)\r\n$rule = New-Object System.Security.AccessControl.FileSystemAccessRule($env:USERNAME, \"FullControl\", \"Allow\")\r\n$acl.SetAccessRule($rule)\r\nSet-Acl \"config.json\" $acl\r\n```\r\n\r\n**Linux/Mac:**\r\n```bash\r\n# Set to owner read/write only\r\nchmod 600 config.json\r\n```\r\n\r\n### 2. Storage Location\r\n\r\nStore the skill in a secure directory:\r\n- ✅ User profile directory (`~/.openclaw/skills/`)\r\n- ✅ Encrypted home directory\r\n- ❌ Network shares\r\n- ❌ Shared/public folders\r\n\r\n### 3. Regular Credential Rotation\r\n\r\nRotate your QuickBooks app credentials regularly:\r\n\r\n1. Log in to [Intuit Developer Portal](https://developer.intuit.com)\r\n2. Go to your app's \"Keys & credentials\"\r\n3. Generate new Client Secret\r\n4. Update `config.json` with new secret\r\n5. Re-authenticate with `qb_authenticate`\r\n\r\n**Recommended rotation schedule**: Every 90 days for production, or immediately if compromise suspected\r\n\r\n### 4. Token Management\r\n\r\n- **Refresh tokens expire after 100 days of inactivity** - Use regularly or re-authenticate\r\n- **Access tokens expire after 1 hour** - Automatically refreshed by the skill\r\n- If you suspect token compromise, immediately:\r\n  1. Revoke tokens in QuickBooks Developer Portal\r\n  2. Delete `config.json`\r\n  3. Regenerate app credentials\r\n  4. Re-authenticate\r\n\r\n### 5. Environment Separation\r\n\r\nKeep sandbox and production credentials completely separate:\r\n\r\n- Use different `config.json` files or separate skill directories\r\n- Never use production credentials for testing\r\n- Mark production config clearly: `config.production.json`\r\n\r\n### 6. AutoStart Considerations\r\n\r\n⚠️ **Do NOT enable autoStart until you've thoroughly tested the skill**\r\n\r\nAutoStart means:\r\n- The skill loads automatically when OpenClaw starts\r\n- Credentials are loaded into memory without your explicit action\r\n- Higher exposure window if your session is compromised\r\n\r\nOnly enable after:\r\n- Verifying all tools work as expected\r\n- Testing error handling\r\n- Confirming no unexpected network calls\r\n- Reviewing all code\r\n\r\n### 7. Access Scoping\r\n\r\nIn your QuickBooks app settings, only enable the scopes you need:\r\n\r\n- `com.intuit.quickbooks.accounting` - Full accounting access (required for this skill)\r\n- Consider limited scopes if you only need read access\r\n\r\n### 8. Monitoring & Auditing\r\n\r\nWatch for suspicious activity:\r\n- Unexpected API calls in QuickBooks audit log\r\n- Unrecognized access from your app\r\n- Token refresh failures (may indicate stolen tokens being revoked)\r\n\r\n### 9. Machine Security\r\n\r\nProtect your development machine:\r\n- Use full disk encryption\r\n- Enable screen lock with timeout\r\n- Keep OS and security software updated\r\n- Use firewall to limit network exposure\r\n- Don't leave terminals with skill access open unattended\r\n\r\n### 10. Incident Response\r\n\r\nIf you suspect credential compromise:\r\n\r\n1. **Immediate Actions:**\r\n   - Disconnect machine from network\r\n   - Revoke tokens in QuickBooks Developer Portal\r\n   - Change QuickBooks password\r\n   - Delete `config.json`\r\n\r\n2. **Investigation:**\r\n   - Check QuickBooks audit logs for unauthorized access\r\n   - Review recent API calls\r\n   - Check file access logs for `config.json`\r\n\r\n3. **Recovery:**\r\n   - Generate new app credentials\r\n   - Update skill with new credentials\r\n   - Re-authenticate\r\n   - Monitor for 30 days\r\n\r\n## Alternative Security Approaches\r\n\r\nFor higher security requirements, consider:\r\n\r\n### Option 1: System Keyring\r\nModify the skill to store tokens in the OS keyring:\r\n- Windows Credential Manager\r\n- macOS Keychain\r\n- Linux Secret Service\r\n\r\n### Option 2: Encrypted Storage\r\nEncrypt `config.json` with a master password:\r\n- Use libraries like `node-keytar` or `cryptr`\r\n- Prompt for password on skill start\r\n- Adds complexity but increases security\r\n\r\n### Option 3: Environment Variables\r\nStore Client ID/Secret in environment variables:\r\n```bash\r\nexport QB_CLIENT_ID=\"your_id\"\r\nexport QB_CLIENT_SECRET=\"your_secret\"\r\n```\r\nModify skill to read from environment instead of config file\r\n\r\n### Option 4: External Secret Management\r\nFor enterprise use:\r\n- HashiCorp Vault\r\n- AWS Secrets Manager\r\n- Azure Key Vault\r\n- CyberArk\r\n\r\n## Comparison to OAuth Best Practices\r\n\r\nThis skill follows OAuth2 best practices:\r\n- ✅ Uses authorization code flow (not implicit)\r\n- ✅ Stores tokens securely in local file (standard for desktop apps)\r\n- ✅ Uses HTTPS for all API communication\r\n- ✅ Implements automatic token refresh\r\n- ✅ Does not expose credentials in code or logs\r\n- ⚠️ Stores client secret locally (acceptable for non-public clients)\r\n\r\n## Regulatory Compliance\r\n\r\nIf you're subject to compliance requirements:\r\n\r\n### PCI DSS\r\n- This skill does not handle credit card data directly\r\n- QuickBooks API calls are PCI compliant (Intuit is PCI certified)\r\n\r\n### SOC 2\r\n- Document access controls for config.json\r\n- Implement audit logging of skill usage\r\n- Regular security reviews\r\n\r\n### GDPR\r\n- QuickBooks data may contain personal information\r\n- Ensure proper data processing agreements\r\n- Implement data retention policies\r\n\r\n## FAQ\r\n\r\n**Q: Is it safe to use this skill with production QuickBooks data?**  \r\nA: Yes, if you follow the security measures above. The OAuth2 flow is industry-standard, and local credential storage is acceptable for desktop applications.\r\n\r\n**Q: Can someone steal my credentials remotely?**  \r\nA: Not unless they've already compromised your machine. All API traffic is over HTTPS. The main risk is local file access.\r\n\r\n**Q: Should I commit config.json to Git?**  \r\nA: **NO!** Never commit credentials to version control. It's already in `.gitignore`.\r\n\r\n**Q: How do I know if my tokens were compromised?**  \r\nA: Check QuickBooks audit logs for suspicious API activity or unexpected access times.\r\n\r\n**Q: What's the worst that could happen?**  \r\nA: An attacker with your tokens could read, create, modify, or delete QuickBooks data with the same permissions your account has. They cannot change your QuickBooks password or access other apps.\r\n\r\n## Support\r\n\r\nFor Intuit security issues:\r\n- [Intuit Security Center](https://security.intuit.com)\r\n- [Report Security Vulnerability](https://trust.intuit.com/report-a-security-issue)\r\n\r\nFor skill-specific security concerns:\r\n- Review this document\r\n- Audit the source code in `run.js`\r\n- Contact skill maintainer\r\n\r\n---\r\n\r\n**Last Updated**: February 21, 2026  \r\n**Version**: 1.0.1\n\nFile v1.0.1:TROUBLESHOOTING.md\n\n# QuickBooks API Skill - Troubleshooting Guide\r\n\r\n## Quick Diagnostics Checklist\r\n\r\n- [ ] Node.js version 18+ installed (`node --version`)\r\n- [ ] Dependencies installed (`npm install`)\r\n- [ ] config.json file exists with credentials\r\n- [ ] QuickBooks Developer app created\r\n- [ ] Redirect URI matches in app and config\r\n- [ ] Successfully completed OAuth flow\r\n- [ ] Access token not expired\r\n\r\n## Common Issues & Solutions\r\n\r\n### 1. Authentication Issues\r\n\r\n#### Problem: \"Not authenticated. Please run qb_authenticate first.\"\r\n\r\n**Cause:** No valid config.json file found or missing credentials.\r\n\r\n**Solution:**\r\n```bash\r\n# 1. Copy template\r\ncp config.json.template config.json\r\n\r\n# 2. Edit config.json with your credentials\r\n# Add your client_id and client_secret from QuickBooks Developer Portal\r\n\r\n# 3. Run authentication\r\n# Use qb_authenticate tool through OpenClaw\r\n```\r\n\r\n---\r\n\r\n#### Problem: \"Token refresh failed: 401 Unauthorized\"\r\n\r\n**Cause:** Refresh token has expired (they last 100 days) or invalid credentials.\r\n\r\n**Solution:**\r\n```bash\r\n# 1. Delete existing config\r\nrm config.json\r\n\r\n# 2. Copy template again\r\ncp config.json.template config.json\r\n\r\n# 3. Add credentials and re-authenticate\r\n# Use qb_authenticate tool\r\n```\r\n\r\n---\r\n\r\n#### Problem: Browser doesn't open during authentication\r\n\r\n**Cause:** System cannot open default browser or display server issue.\r\n\r\n**Solution:**\r\n1. Copy the authorization URL from the console output\r\n2. Manually paste it into your browser\r\n3. Complete the authorization\r\n4. You'll be redirected to localhost:3000/callback\r\n5. The process should complete automatically\r\n\r\n---\r\n\r\n#### Problem: \"Invalid redirect URI\"\r\n\r\n**Cause:** Redirect URI in config.json doesn't match QuickBooks app settings.\r\n\r\n**Solution:**\r\n1. Go to [Intuit Developer Portal](https://developer.intuit.com)\r\n2. Open your app\r\n3. Go to \"Keys & credentials\"\r\n4. Check \"Redirect URIs\"\r\n5. Ensure `http://localhost:3000/callback` is listed\r\n6. Update config.json to match exactly\r\n\r\n---\r\n\r\n### 2. API Errors\r\n\r\n#### Problem: \"QuickBooks API Error: 400 - Validation error\"\r\n\r\n**Cause:** Missing required fields or invalid data format.\r\n\r\n**Solution:**\r\n```javascript\r\n// Check your request has all required fields:\r\n// For Customer: DisplayName is required\r\n// For Invoice: CustomerRef and Line are required\r\n// For Item: Name and Type are required\r\n\r\n// Example of correct invoice structure:\r\n{\r\n  \"CustomerRef\": { \"value\": \"123\" },  // Note: nested \"value\"\r\n  \"Line\": [{\r\n    \"Amount\": 100.00,\r\n    \"DetailType\": \"SalesItemLineDetail\",\r\n    \"SalesItemLineDetail\": {\r\n      \"ItemRef\": { \"value\": \"1\" }\r\n    }\r\n  }]\r\n}\r\n```\r\n\r\n**Common validation errors:**\r\n- Missing `value` in reference objects (should be `{\"value\": \"123\"}` not `\"123\"`)\r\n- Wrong `DetailType` (use \"SalesItemLineDetail\" for invoices, not \"ExpenseLineDetail\")\r\n- Dates in wrong format (must be \"YYYY-MM-DD\")\r\n- Missing required nested objects\r\n\r\n---\r\n\r\n#### Problem: \"QuickBooks API Error: 404 - Not Found\"\r\n\r\n**Cause:** Referenced entity doesn't exist (customer, item, account, etc.).\r\n\r\n**Solution:**\r\n```javascript\r\n// 1. First verify the entity exists:\r\n// Query to check if customer exists:\r\n{\r\n  \"tool\": \"qb_query\",\r\n  \"arguments\": {\r\n    \"query\": \"SELECT * FROM Customer WHERE Id = '123'\"\r\n  }\r\n}\r\n\r\n// 2. If it doesn't exist, create it first\r\n// 3. Then use the Id from the creation response\r\n```\r\n\r\n---\r\n\r\n#### Problem: \"QuickBooks API Error: 429 - Too Many Requests\"\r\n\r\n**Cause:** Hit rate limit (500 requests/minute in sandbox).\r\n\r\n**Solution:**\r\n- Implement exponential backoff in your code\r\n- Use batch operations for multiple requests\r\n- Cache frequently used data (items, accounts)\r\n- Spread requests over time\r\n- Consider upgrading production plan for higher limits\r\n\r\n---\r\n\r\n#### Problem: \"Stale object error\" when updating\r\n\r\n**Cause:** Missing or incorrect `SyncToken` in update request.\r\n\r\n**Solution:**\r\n```javascript\r\n// Always get the latest version first\r\n{\r\n  \"tool\": \"qb_get_customer\",\r\n  \"arguments\": { \"customer_id\": \"123\" }\r\n}\r\n\r\n// Use the SyncToken from the response in your update\r\n{\r\n  \"tool\": \"qb_update_customer\",  // Note: Not yet implemented, use create with Id\r\n  \"arguments\": {\r\n    \"Id\": \"123\",\r\n    \"SyncToken\": \"5\",  // From the get response\r\n    \"DisplayName\": \"Updated Name\"\r\n  }\r\n}\r\n```\r\n\r\n---\r\n\r\n### 3. Query Issues\r\n\r\n#### Problem: \"No results returned\" from query\r\n\r\n**Cause:** Incorrect SQL syntax or entity name.\r\n\r\n**Solution:**\r\n```sql\r\n-- ❌ WRONG: Entity names must be singular\r\nSELECT * FROM Customers\r\n\r\n-- ✅ CORRECT: Entity is singular\r\nSELECT * FROM Customer\r\n\r\n-- ❌ WRONG: Missing quotes around string values\r\nSELECT * FROM Customer WHERE DisplayName = John\r\n\r\n-- ✅ CORRECT: Use single quotes\r\nSELECT * FROM Customer WHERE DisplayName = 'John'\r\n\r\n-- ❌ WRONG: Date comparison without quotes\r\nSELECT * FROM Invoice WHERE TxnDate > 2026-01-01\r\n\r\n-- ✅ CORRECT: Dates must be quoted\r\nSELECT * FROM Invoice WHERE TxnDate > '2026-01-01'\r\n```\r\n\r\n---\r\n\r\n#### Problem: \"Invalid query error\"\r\n\r\n**Cause:** Using unsupported SQL features.\r\n\r\n**Solution:**\r\n```sql\r\n-- QuickBooks SQL is limited. These are NOT supported:\r\n-- ❌ Joins between entities (use separate queries)\r\n-- ❌ Subqueries\r\n-- ❌ GROUP BY\r\n-- ❌ COUNT, SUM, AVG (use reports instead)\r\n-- ❌ HAVING\r\n-- ❌ LIMIT (use MAXRESULTS instead)\r\n\r\n-- ✅ Supported:\r\nSELECT * FROM Customer WHERE Active = true ORDER BY DisplayName\r\nSELECT *, MAXRESULTS 10 FROM Invoice ORDER BY TxnDate DESC\r\nSELECT Id, DisplayName FROM Customer WHERE Balance > 0\r\n```\r\n\r\n---\r\n\r\n### 4. Connection Issues\r\n\r\n#### Problem: \"ECONNREFUSED\" or \"Network error\"\r\n\r\n**Cause:** Cannot connect to QuickBooks API servers.\r\n\r\n**Solution:**\r\n1. Check your internet connection\r\n2. Verify you can reach https://quickbooks.api.intuit.com\r\n3. Check firewall settings\r\n4. Verify no proxy is blocking the connection\r\n5. Try from a different network\r\n\r\n---\r\n\r\n#### Problem: Port 3000 already in use\r\n\r\n**Cause:** Another application is using port 3000.\r\n\r\n**Solution:**\r\n\r\n**Option 1 - Use different port:**\r\n```javascript\r\n// In your QuickBooks app settings at developer.intuit.com:\r\n// Change redirect URI to: http://localhost:3001/callback\r\n\r\n// In config.json:\r\n{\r\n  \"redirect_uri\": \"http://localhost:3001/callback\"\r\n}\r\n\r\n// Then modify the code in run.js at line \"app.listen(3000\"\r\n// Change to: app.listen(3001\r\n```\r\n\r\n**Option 2 - Kill process using port 3000:**\r\n```bash\r\n# Windows PowerShell\r\nGet-Process -Id (Get-NetTCPConnection -LocalPort 3000).OwningProcess | Stop-Process\r\n\r\n# Or find and kill manually:\r\nnetstat -ano | findstr :3000\r\ntaskkill /PID [PID_NUMBER] /F\r\n```\r\n\r\n---\r\n\r\n### 5. Data Issues\r\n\r\n#### Problem: Invoice shows $0.00 total\r\n\r\n**Cause:** Line items not properly structured or Amount calculation incorrect.\r\n\r\n**Solution:**\r\n```javascript\r\n{\r\n  \"Line\": [\r\n    {\r\n      // Amount must match Qty * UnitPrice\r\n      \"Amount\": 100.00,  // This should be 2 * 50.00\r\n      \"DetailType\": \"SalesItemLineDetail\",\r\n      \"SalesItemLineDetail\": {\r\n        \"ItemRef\": { \"value\": \"1\" },\r\n        \"Qty\": 2,\r\n        \"UnitPrice\": 50.00\r\n      }\r\n    }\r\n  ]\r\n}\r\n```\r\n\r\n---\r\n\r\n#### Problem: Cannot link payment to invoice\r\n\r\n**Cause:** Incorrect LinkedTxn structure or invoice already paid.\r\n\r\n**Solution:**\r\n```javascript\r\n// 1. First check invoice balance\r\n{\r\n  \"tool\": \"qb_get_invoice\",\r\n  \"arguments\": { \"invoice_id\": \"456\" }\r\n}\r\n\r\n// 2. If balance > 0, create payment with correct structure:\r\n{\r\n  \"tool\": \"qb_create_payment\",\r\n  \"arguments\": {\r\n    \"CustomerRef\": { \"value\": \"123\" },\r\n    \"TotalAmt\": 500.00,\r\n    \"Line\": [{\r\n      \"Amount\": 500.00,\r\n      \"LinkedTxn\": [{\r\n        \"TxnId\": \"456\",        // Invoice ID\r\n        \"TxnType\": \"Invoice\"   // Must be exact\r\n      }]\r\n    }]\r\n  }\r\n}\r\n```\r\n\r\n---\r\n\r\n### 6. OpenClaw Integration Issues\r\n\r\n#### Problem: Skill not showing up in OpenClaw\r\n\r\n**Cause:** Configuration file not updated or OpenClaw not restarted.\r\n\r\n**Solution:**\r\n1. Check your OpenClaw configuration file and ensure the path to run.js is correct.\r\n2. Restart OpenClaw completely to load the skill.\r\n\r\n---\r\n\r\n#### Problem: \"Cannot find module '@modelcontextprotocol/sdk'\"\r\n\r\n**Cause:** Dependencies not installed.\r\n\r\n**Solution:**\r\n```bash\r\ncd \"c:\\Users\\Shaun\\Desktop\\Quickbooks skill\"\r\nnpm install\r\n```\r\n\r\n---\r\n\r\n#### Problem: Tool calls timing out\r\n\r\n**Cause:** Large queries or slow API responses.\r\n\r\n**Solution:**\r\n- Use more specific queries (avoid `SELECT *`)\r\n- Add MAXRESULTS to limit rows: `SELECT *, MAXRESULTS 50 FROM Customer`\r\n- Break large batch operations into smaller chunks\r\n- Increase timeout in OpenClaw configuration if available\r\n\r\n---\r\n\r\n### 7. Environment Issues\r\n\r\n#### Problem: Different results in sandbox vs production\r\n\r\n**Cause:** Using sandbox credentials with production data or vice versa.\r\n\r\n**Solution:**\r\n1. Verify you're using the correct credentials:\r\n   - Sandbox: Keys from \"Development\" tab\r\n   - Production: Keys from \"Production\" tab\r\n\r\n2. Ensure realm_id matches the environment:\r\n   - Sandbox companies have different realm IDs than production\r\n\r\n3. Check company info to verify:\r\n```javascript\r\n{\r\n  \"tool\": \"qb_get_company_info\",\r\n  \"arguments\": {}\r\n}\r\n```\r\n\r\n---\r\n\r\n### 8. Report Issues\r\n\r\n#### Problem: Report returns no data\r\n\r\n**Cause:** Date range has no transactions or wrong date format.\r\n\r\n**Solution:**\r\n```javascript\r\n// ✅ Correct date format:\r\n{\r\n  \"tool\": \"qb_get_profit_loss\",\r\n  \"arguments\": {\r\n    \"start_date\": \"2026-01-01\",  // YYYY-MM-DD\r\n    \"end_date\": \"2026-01-31\"\r\n  }\r\n}\r\n\r\n// Also check if company has data in that date range:\r\n{\r\n  \"tool\": \"qb_query\",\r\n  \"arguments\": {\r\n    \"query\": \"SELECT COUNT(*) FROM Invoice WHERE TxnDate >= '2026-01-01' AND TxnDate <= '2026-01-31'\"\r\n  }\r\n}\r\n```\r\n\r\n---\r\n\r\n### 9. Permission Issues\r\n\r\n#### Problem: \"Insufficient permissions\" error\r\n\r\n**Cause:** App doesn't have correct scopes or company hasn't granted permission.\r\n\r\n**Solution:**\r\n1. Check app scopes at developer.intuit.com:\r\n   - Should have \"com.intuit.quickbooks.accounting\" scope\r\n   \r\n2. Re-authenticate to grant new permissions:\r\n```bash\r\n# Delete config and re-authenticate\r\nrm config.json\r\ncp config.json.template config.json\r\n# Add credentials and use qb_authenticate tool\r\n```\r\n\r\n3. Check if specific features are enabled in QuickBooks subscription:\r\n   - Some features require QuickBooks Online Plus or Advanced\r\n\r\n---\r\n\r\n### 10. Windows-Specific Issues\r\n\r\n#### Problem: \"EPERM: operation not permitted\" when saving config\r\n\r\n**Cause:** File permissions or antivirus blocking file writes.\r\n\r\n**Solution:**\r\n```powershell\r\n# Check file permissions\r\nicacls config.json\r\n\r\n# Grant full control to current user\r\nicacls config.json /grant:r \"%USERNAME%:F\"\r\n\r\n# Or run PowerShell as Administrator\r\n```\r\n\r\n---\r\n\r\n#### Problem: Path issues with backslashes\r\n\r\n**Cause:** Windows uses backslashes, but JSON needs forward slashes or escaped backslashes.\r\n\r\n**Solution:**\r\n```json\r\n// ❌ WRONG:\r\n\"args\": [\"c:\\Users\\Shaun\\Desktop\\Quickbooks skill\\run.js\"]\r\n\r\n// ✅ CORRECT (option 1 - forward slashes):\r\n\"args\": [\"c:/Users/Shaun/Desktop/Quickbooks skill/run.js\"]\r\n\r\n// ✅ CORRECT (option 2 - escaped backslashes):\r\n\"args\": [\"c:\\\\Users\\\\Shaun\\\\Desktop\\\\Quickbooks skill\\\\run.js\"]\r\n```\r\n\r\n---\r\n\r\n## Debugging Tips\r\n\r\n### Enable Verbose Logging\r\n\r\nAdd this to run.js after the imports:\r\n```javascript\r\n// Add after require statements\r\naxios.interceptors.request.use(request => {\r\n  console.error('Request:', request.method, request.url);\r\n  return request;\r\n});\r\n\r\naxios.interceptors.response.use(response => {\r\n  console.error('Response:', response.status);\r\n  return response;\r\n});\r\n```\r\n\r\n### Check Token Status\r\n\r\nManually inspect your config.json:\r\n```javascript\r\n// Check if token is expired\r\nconst config = require('./config.json');\r\nconst expiryDate = new Date(config.token_expiry);\r\nconst now = new Date();\r\n\r\nconsole.log('Token expires:', expiryDate);\r\nconsole.log('Current time:', now);\r\nconsole.log('Token expired:', now > expiryDate);\r\n```\r\n\r\n### Test API Connectivity\r\n\r\n```bash\r\n# Test if you can reach QuickBooks API\r\ncurl https://quickbooks.api.intuit.com\r\n\r\n# Should return HTML or error page (not connection error)\r\n```\r\n\r\n### Validate JSON Syntax\r\n\r\n```bash\r\n# Check if your config.json is valid\r\nnode -e \"console.log(JSON.parse(require('fs').readFileSync('config.json')))\"\r\n```\r\n\r\n## Getting Help\r\n\r\n### Before Asking for Help\r\n\r\nCollect this information:\r\n1. Node.js version: `node --version`\r\n2. npm version: `npm --version`\r\n3. Operating System: Windows/Mac/Linux\r\n4. Environment: Sandbox or Production\r\n5. Error message (full text)\r\n6. Steps to reproduce\r\n7. What you tried already\r\n\r\n### Where to Get Help\r\n\r\n1. **QuickBooks Developer Forum**\r\n   - https://help.developer.intuit.com/s/\r\n   - Search existing issues first\r\n   - Tag questions with \"QuickBooks API\"\r\n\r\n2. **API Documentation**\r\n   - https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/account\r\n   - Check for entity-specific requirements\r\n\r\n3. **Stack Overflow**\r\n   - Tag: `quickbooks`, `intuit-partner-platform`\r\n   - Search before posting\r\n\r\n4. **Intuit Developer Support**\r\n   - For production app issues\r\n   - https://help.developer.intuit.com/s/contactsupport\r\n\r\n### Reporting Bugs\r\n\r\nWhen reporting issues with this skill:\r\n1. Include Node.js and OS version\r\n2. Provide error messages\r\n3. Share sanitized request/response (remove credentials!)\r\n4. Describe expected vs actual behavior\r\n5. List reproduction steps\r\n\r\n## Additional Resources\r\n\r\n- [QuickBooks API Status](https://status.developer.intuit.com/) - Check for outages\r\n- [Release Notes](https://developer.intuit.com/app/developer/qbo/docs/release-notes) - API changes\r\n- [Known Issues](https://help.developer.intuit.com/s/bug-tracker-page) - Current bugs\r\n- [Sample Apps](https://developer.intuit.com/app/developer/qbo/docs/get-started/start-developing-your-app) - Working examples\r\n\r\n## Emergency Fixes\r\n\r\n### Reset Everything\r\n\r\nIf nothing works, start fresh:\r\n```bash\r\n# 1. Delete node_modules and config\r\nrm -rf node_modules\r\nrm config.json\r\n\r\n# 2. Reinstall\r\nnpm install\r\n\r\n# 3. Copy template\r\ncp config.json.template config.json\r\n\r\n# 4. Add credentials\r\n# Edit config.json with your client_id and client_secret\r\n\r\n# 5. Re-authenticate\r\n# Use qb_authenticate tool\r\n```\r\n\r\n### Check QuickBooks API Status\r\n\r\n```bash\r\n# Quick status check\r\ncurl https://status.developer.intuit.com/\r\n```\r\n\r\nIf API is down, wait and retry later.\r\n\r\n---\r\n\r\n**Still stuck? Check the QuickBooks Developer Forum or contact Intuit Support.**\n\nFile v1.0.1:config.json\n\n{\r\n  \"client_id\": \"YOUR_QUICKBOOKS_CLIENT_ID\",\r\n  \"client_secret\": \"YOUR_QUICKBOOKS_CLIENT_SECRET\",\r\n  \"redirect_uri\": \"http://localhost:3001/callback\",\r\n  \"api_environment\": \"sandbox\",\r\n  \"access_token\": \"\",\r\n  \"refresh_token\": \"\",\r\n  \"realm_id\": \"\",\r\n  \"token_expiry\": 0\r\n}\n\nArchive v1.0.0: 4 files, 9043 bytes\n\nFiles: config.json (244b), run.js (13898b), SKILL.md (15282b), _meta.json (136b)\n\nFile v1.0.0:SKILL.md\n\n---\r\nname: quickbooks-openclaw\r\nversion: 1.0.0\r\ndescription: Comprehensive QuickBooks Online API integration for accounting, invoicing, payments, and financial reporting\r\nauthor: Armysarge\r\nlicense: MIT\r\ntags:\r\n  - accounting\r\n  - quickbooks\r\n  - invoicing\r\n  - payments\r\n  - financial\r\n  - erp\r\n  - bookkeeping\r\ncategory: Business & Finance\r\n---\r\n\r\n# QuickBooks API Skill for OpenClaw\r\n\r\nA complete QuickBooks Online API integration skill for OpenClaw providing full access to accounting, invoicing, customer management, inventory, payments, and financial reporting through the Intuit QuickBooks API.\r\n\r\n## Overview\r\n\r\nThis skill enables OpenClaw to interact with QuickBooks Online for:\r\n- **Customer & Vendor Management**: Create and manage business relationships\r\n- **Invoicing**: Generate, send, and track invoices\r\n- **Payments**: Record and reconcile payments\r\n- **Inventory**: Manage products, services, and stock levels\r\n- **Financial Reports**: Generate P&L, Balance Sheets, Cash Flow, and aging reports\r\n- **Estimates**: Create quotes and proposals\r\n- **Bills**: Track accounts payable\r\n- **Purchase Orders**: Manage procurement\r\n\r\n## Prerequisites\r\n\r\n1. **QuickBooks Developer Account**\r\n   - Sign up at [https://developer.intuit.com](https://developer.intuit.com)\r\n   - Create a new app in the Developer Portal\r\n   - Enable \"QuickBooks Online API\" scope\r\n\r\n2. **App Credentials**\r\n   - Client ID from your QuickBooks app\r\n   - Client Secret from your QuickBooks app\r\n   - Redirect URI: `http://localhost:3000/callback`\r\n\r\n3. **Node.js**\r\n   - Version 18.0.0 or higher\r\n   - npm or yarn package manager\r\n\r\n## Installation\r\n\r\n### 1. Install Dependencies\r\n\r\n```bash\r\ncd \"c:\\Users\\Shaun\\Desktop\\Quickbooks skill\"\r\nnpm install\r\n```\r\n\r\nRequired packages:\r\n- `@modelcontextprotocol/sdk` - MCP server SDK\r\n- `axios` - HTTP client for API requests\r\n- `express` - OAuth callback server\r\n- `open` - Browser automation for OAuth\r\n\r\n### 2. Configure Credentials\r\n\r\nCreate `config.json` from template:\r\n\r\n```bash\r\ncp config.json.template config.json\r\n```\r\n\r\nEdit `config.json` with your QuickBooks app credentials:\r\n\r\n```json\r\n{\r\n  \"client_id\": \"YOUR_CLIENT_ID_HERE\",\r\n  \"client_secret\": \"YOUR_CLIENT_SECRET_HERE\",\r\n  \"redirect_uri\": \"http://localhost:3000/callback\",\r\n  \"access_token\": \"\",\r\n  \"refresh_token\": \"\",\r\n  \"realm_id\": \"\",\r\n  \"token_expiry\": 0\r\n}\r\n```\r\n\r\n### 3. Add to Configuration\r\n\r\n**For OpenClaw:**\r\n\r\nAdd to your OpenClaw configuration:\r\n```json\r\n{\r\n  \"skills\": {\r\n    \"quickbooks\": {\r\n      \"path\": \"~/.openclaw/workspace/skills/Quickbooks-openclaw\",\r\n      \"enabled\": true,\r\n      \"autoStart\": true\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n## Authentication\r\n\r\n### First-Time Setup\r\n\r\n1. Use the `qb_authenticate` tool with your credentials:\r\n```\r\nUse qb_authenticate with client_id and client_secret\r\n```\r\n\r\n2. A browser window will open automatically\r\n3. Log in to your QuickBooks account\r\n4. Authorize the application\r\n5. You'll be redirected to localhost (handled automatically)\r\n6. Tokens are saved to `config.json`\r\n\r\n### Token Management\r\n\r\n- **Access tokens** expire after 1 hour (refreshed automatically)\r\n- **Refresh tokens** last 100 days (renewed on refresh)\r\n- The skill automatically refreshes tokens before they expire\r\n- Re-authenticate if you see \"Not authenticated\" errors\r\n\r\n## Available Tools\r\n\r\n### 🔐 Authentication\r\n\r\n#### `qb_authenticate`\r\nInitiate OAuth2 authentication flow.\r\n\r\n**Parameters:**\r\n- `client_id` (required): Your QuickBooks app Client ID\r\n- `client_secret` (required): Your QuickBooks app Client Secret\r\n- `redirect_uri` (optional): OAuth redirect URI (default: http://localhost:3000/callback)\r\n\r\n**Example:**\r\n```json\r\n{\r\n  \"client_id\": \"ABxxxxxxxxxxxxxxxxxxxx\",\r\n  \"client_secret\": \"xxxxxxxxxxxxxxxxxx\"\r\n}\r\n```\r\n\r\n---\r\n\r\n### 👥 Customer Management\r\n\r\n#### `qb_create_customer`\r\nCreate a new customer.\r\n\r\n**Parameters:**\r\n- `DisplayName` (required): Customer display name\r\n- `CompanyName`: Company name\r\n- `GivenName`: First name\r\n- `FamilyName`: Last name\r\n- `PrimaryEmailAddr`: Email address object\r\n- `PrimaryPhone`: Phone number object\r\n- `BillAddr`: Billing address object\r\n- `ShipAddr`: Shipping address object\r\n\r\n**Example:**\r\n```json\r\n{\r\n  \"DisplayName\": \"Acme Corporation\",\r\n  \"PrimaryEmailAddr\": {\r\n    \"Address\": \"billing@acme.com\"\r\n  }\r\n}\r\n```\r\n\r\n#### `qb_get_customer`\r\nGet customer details by ID.\r\n\r\n**Parameters:**\r\n- `customer_id` (required): Customer ID\r\n\r\n#### `qb_query_customers`\r\nQuery customers using SQL syntax.\r\n\r\n**Parameters:**\r\n- `query`: SQL query string (default: \"SELECT * FROM Customer\")\r\n\r\n**Example:**\r\n```json\r\n{\r\n  \"query\": \"SELECT * FROM Customer WHERE Active = true\"\r\n}\r\n```\r\n\r\n---\r\n\r\n### 🧾 Invoice Management\r\n\r\n#### `qb_create_invoice`\r\nCreate a new invoice.\r\n\r\n**Parameters:**\r\n- `CustomerRef` (required): Customer reference object\r\n- `Line` (required): Array of line items\r\n- `TxnDate`: Transaction date (YYYY-MM-DD)\r\n- `DueDate`: Due date (YYYY-MM-DD)\r\n- `CustomerMemo`: Message to customer\r\n- `BillEmail`: Email address for invoice\r\n\r\n**Example:**\r\n```json\r\n{\r\n  \"CustomerRef\": { \"value\": \"123\" },\r\n  \"Line\": [{\r\n    \"Amount\": 500.00,\r\n    \"DetailType\": \"SalesItemLineDetail\",\r\n    \"SalesItemLineDetail\": {\r\n      \"ItemRef\": { \"value\": \"1\" },\r\n      \"Qty\": 10,\r\n      \"UnitPrice\": 50.00\r\n    }\r\n  }],\r\n  \"DueDate\": \"2026-03-15\"\r\n}\r\n```\r\n\r\n#### `qb_get_invoice`\r\nGet invoice by ID.\r\n\r\n**Parameters:**\r\n- `invoice_id` (required): Invoice ID\r\n\r\n#### `qb_send_invoice`\r\nSend invoice via email.\r\n\r\n**Parameters:**\r\n- `invoice_id` (required): Invoice ID\r\n- `email` (required): Recipient email address\r\n\r\n#### `qb_query_invoices`\r\nQuery invoices using SQL syntax.\r\n\r\n**Parameters:**\r\n- `query`: SQL query string\r\n\r\n**Example:**\r\n```json\r\n{\r\n  \"query\": \"SELECT * FROM Invoice WHERE Balance > 0\"\r\n}\r\n```\r\n\r\n---\r\n\r\n### 📦 Item/Product Management\r\n\r\n#### `qb_create_item`\r\nCreate a new product or service item.\r\n\r\n**Parameters:**\r\n- `Name` (required): Item name\r\n- `Type` (required): Item type (Service, Inventory, NonInventory)\r\n- `Description`: Item description\r\n- `UnitPrice`: Sales price\r\n- `IncomeAccountRef`: Income account reference\r\n- `ExpenseAccountRef`: Expense account reference (for inventory)\r\n- `QtyOnHand`: Quantity on hand (for inventory)\r\n\r\n**Example:**\r\n```json\r\n{\r\n  \"Name\": \"Consulting Services\",\r\n  \"Type\": \"Service\",\r\n  \"UnitPrice\": 150.00,\r\n  \"IncomeAccountRef\": { \"value\": \"79\" }\r\n}\r\n```\r\n\r\n#### `qb_get_item`\r\nGet item by ID.\r\n\r\n**Parameters:**\r\n- `item_id` (required): Item ID\r\n\r\n#### `qb_query_items`\r\nQuery items using SQL syntax.\r\n\r\n**Parameters:**\r\n- `query`: SQL query string\r\n\r\n---\r\n\r\n### 💰 Payment Processing\r\n\r\n#### `qb_create_payment`\r\nRecord a payment received.\r\n\r\n**Parameters:**\r\n- `CustomerRef` (required): Customer reference\r\n- `TotalAmt` (required): Total payment amount\r\n- `TxnDate`: Transaction date\r\n- `Line`: Array of payment line items linking to invoices\r\n- `PaymentMethodRef`: Payment method reference\r\n\r\n**Example:**\r\n```json\r\n{\r\n  \"CustomerRef\": { \"value\": \"123\" },\r\n  \"TotalAmt\": 500.00,\r\n  \"Line\": [{\r\n    \"Amount\": 500.00,\r\n    \"LinkedTxn\": [{\r\n      \"TxnId\": \"456\",\r\n      \"TxnType\": \"Invoice\"\r\n    }]\r\n  }]\r\n}\r\n```\r\n\r\n#### `qb_query_payments`\r\nQuery payments using SQL syntax.\r\n\r\n---\r\n\r\n### 📊 Financial Reports\r\n\r\n#### `qb_get_profit_loss`\r\nGenerate Profit & Loss report.\r\n\r\n**Parameters:**\r\n- `start_date` (required): Start date (YYYY-MM-DD)\r\n- `end_date` (required): End date (YYYY-MM-DD)\r\n\r\n**Example:**\r\n```json\r\n{\r\n  \"start_date\": \"2026-01-01\",\r\n  \"end_date\": \"2026-01-31\"\r\n}\r\n```\r\n\r\n#### `qb_get_balance_sheet`\r\nGenerate Balance Sheet report.\r\n\r\n**Parameters:**\r\n- `date` (required): Report date (YYYY-MM-DD)\r\n\r\n#### `qb_get_cash_flow`\r\nGenerate Cash Flow report.\r\n\r\n**Parameters:**\r\n- `start_date` (required): Start date\r\n- `end_date` (required): End date\r\n\r\n#### `qb_get_aged_receivables`\r\nGenerate Aged Receivables (A/R Aging) report.\r\n\r\n**Parameters:** None\r\n\r\n#### `qb_get_aged_payables`\r\nGenerate Aged Payables (A/P Aging) report.\r\n\r\n**Parameters:** None\r\n\r\n---\r\n\r\n### 💼 Vendor & Bill Management\r\n\r\n#### `qb_create_vendor`\r\nCreate a new vendor.\r\n\r\n**Parameters:**\r\n- `DisplayName` (required): Vendor display name\r\n- `CompanyName`: Company name\r\n- `PrimaryEmailAddr`: Email address object\r\n- `PrimaryPhone`: Phone number object\r\n\r\n#### `qb_create_bill`\r\nCreate a bill for a vendor.\r\n\r\n**Parameters:**\r\n- `VendorRef` (required): Vendor reference\r\n- `Line` (required): Array of bill line items\r\n- `TxnDate`: Transaction date\r\n- `DueDate`: Due date\r\n\r\n#### `qb_query_vendors`\r\nQuery vendors using SQL syntax.\r\n\r\n---\r\n\r\n### 📝 Estimates & Quotes\r\n\r\n#### `qb_create_estimate`\r\nCreate a new estimate/quote.\r\n\r\n**Parameters:**\r\n- `CustomerRef` (required): Customer reference\r\n- `Line` (required): Array of line items\r\n- `TxnDate`: Transaction date\r\n- `ExpirationDate`: Expiration date\r\n\r\n#### `qb_query_estimates`\r\nQuery estimates using SQL syntax.\r\n\r\n---\r\n\r\n### 🛒 Purchase Orders\r\n\r\n#### `qb_create_purchase_order`\r\nCreate a purchase order.\r\n\r\n**Parameters:**\r\n- `VendorRef` (required): Vendor reference\r\n- `Line` (required): Array of PO line items\r\n\r\n---\r\n\r\n### 💵 Sales Receipts\r\n\r\n#### `qb_create_sales_receipt`\r\nCreate a sales receipt (cash sale).\r\n\r\n**Parameters:**\r\n- `CustomerRef` (required): Customer reference\r\n- `Line` (required): Array of line items\r\n- `TxnDate`: Transaction date\r\n\r\n---\r\n\r\n### 🏦 Chart of Accounts\r\n\r\n#### `qb_query_accounts`\r\nQuery chart of accounts.\r\n\r\n**Parameters:**\r\n- `query`: SQL query string\r\n\r\n**Example:**\r\n```json\r\n{\r\n  \"query\": \"SELECT * FROM Account WHERE AccountType = 'Income'\"\r\n}\r\n```\r\n\r\n---\r\n\r\n### 🏢 Company Information\r\n\r\n#### `qb_get_company_info`\r\nGet company information.\r\n\r\n**Parameters:** None\r\n\r\n---\r\n\r\n### 🔍 Generic Query\r\n\r\n#### `qb_query`\r\nExecute any SQL query against QuickBooks entities.\r\n\r\n**Parameters:**\r\n- `query` (required): SQL query string\r\n\r\n**Example:**\r\n```json\r\n{\r\n  \"query\": \"SELECT * FROM Customer WHERE Balance > 100 ORDER BY DisplayName\"\r\n}\r\n```\r\n\r\n**Supported Entities:**\r\nAccount, Bill, BillPayment, Class, CreditMemo, Customer, Department, Deposit, Employee, Estimate, Invoice, Item, JournalEntry, Payment, PaymentMethod, Purchase, PurchaseOrder, RefundReceipt, SalesReceipt, TaxCode, TaxRate, Term, TimeActivity, Transfer, Vendor, VendorCredit\r\n\r\n---\r\n\r\n### ⚡ Batch Operations\r\n\r\n#### `qb_batch`\r\nExecute multiple operations in a single batch request.\r\n\r\n**Parameters:**\r\n- `operations` (required): Array of batch operations\r\n\r\n**Example:**\r\n```json\r\n{\r\n  \"operations\": [\r\n    {\r\n      \"bId\": \"bid1\",\r\n      \"operation\": \"create\",\r\n      \"entity\": \"Customer\",\r\n      \"data\": { \"DisplayName\": \"Customer 1\" }\r\n    },\r\n    {\r\n      \"bId\": \"bid2\",\r\n      \"operation\": \"query\",\r\n      \"query\": \"SELECT * FROM Invoice WHERE Balance > 0\"\r\n    }\r\n  ]\r\n}\r\n```\r\n\r\n## Usage Examples\r\n\r\n### Create and Send an Invoice Workflow\r\n\r\n```\r\n1. First, create or find a customer:\r\n   \"Find customer with name 'Acme Corp' using qb_query_customers\"\r\n\r\n2. Create an invoice:\r\n   \"Create an invoice for customer ID 123 with consulting services \r\n    for 10 hours at $150/hour, due in 30 days\"\r\n\r\n3. Send the invoice:\r\n   \"Send invoice 456 to billing@acme.com\"\r\n```\r\n\r\n### Financial Reporting Workflow\r\n\r\n```\r\n1. Get month-end reports:\r\n   \"Show me the profit and loss for January 2026\"\r\n\r\n2. Check cash flow:\r\n   \"What's the cash flow for last quarter?\"\r\n\r\n3. Review outstanding receivables:\r\n   \"Show me the aged receivables report\"\r\n```\r\n\r\n### Inventory Management Workflow\r\n\r\n```\r\n1. Check low stock items:\r\n   \"Query items where quantity on hand is less than 10\"\r\n\r\n2. Create reorder purchase order:\r\n   \"Create a purchase order for vendor 789 to reorder low stock items\"\r\n\r\n3. Update item prices:\r\n   \"Update the price of item 'Widget Pro' to $299.99\"\r\n```\r\n\r\n## SQL Query Syntax\r\n\r\nQuickBooks uses a SQL-like query language:\r\n\r\n### Basic Query\r\n```sql\r\nSELECT * FROM Customer WHERE Active = true\r\n```\r\n\r\n### With Conditions\r\n```sql\r\nSELECT * FROM Invoice WHERE Balance > 0 AND DueDate < '2026-03-01'\r\n```\r\n\r\n### Pattern Matching\r\n```sql\r\nSELECT * FROM Customer WHERE DisplayName LIKE '%Corp%'\r\n```\r\n\r\n### Ordering Results\r\n```sql\r\nSELECT * FROM Invoice ORDER BY TxnDate DESC\r\n```\r\n\r\n### Limiting Results\r\n```sql\r\nSELECT *, MAXRESULTS 50 FROM Customer\r\n```\r\n\r\n### Multiple Conditions\r\n```sql\r\nSELECT * FROM Item WHERE Type = 'Inventory' AND QtyOnHand < 10\r\n```\r\n\r\n## Error Handling\r\n\r\nThe skill provides detailed error messages:\r\n\r\n- **Authentication Errors**: \"Not authenticated. Please run qb_authenticate first.\"\r\n- **API Errors**: Full QuickBooks error details with status codes\r\n- **Validation Errors**: Missing required fields or invalid data\r\n- **Rate Limit Errors**: \"Too Many Requests - retry after delay\"\r\n\r\n## Configuration\r\n\r\nAll configuration is stored in `config.json`. This file contains both your app credentials (Client ID and Secret) and the OAuth tokens that are saved after authentication.\r\n\r\n### Sandbox vs Production\r\n\r\n- **Sandbox**: Test environment for development (recommended for testing)\r\n- **Production**: Real company data (requires app approval)\r\n\r\nUse sandbox credentials for testing, production credentials for live data.\r\n\r\n## Rate Limits\r\n\r\n- **Sandbox**: 500 requests/minute per app\r\n- **Production**: Varies by subscription (500-1000/minute)\r\n\r\nThe skill automatically handles rate limiting with proper error messages.\r\n\r\n## Security\r\n\r\n- OAuth2 authentication (no password storage)\r\n- Tokens stored in `config.json` (excluded from git)\r\n- Automatic token refresh\r\n- Secure HTTPS API communication\r\n- No credentials in code\r\n\r\n## Troubleshooting\r\n\r\n### \"Not authenticated\" Error\r\nRun `qb_authenticate` with your credentials.\r\n\r\n### \"Token refresh failed\"\r\nDelete `config.json` and re-authenticate.\r\n\r\n### \"Invalid redirect URI\"\r\nEnsure redirect URI in config matches your QuickBooks app settings.\r\n\r\n### Port 3000 Already in Use\r\nChange port in code or kill the process using port 3000.\r\n\r\nFor more troubleshooting, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md).\r\n\r\n## Documentation\r\n\r\n- [README.md](README.md) - Complete setup guide\r\n- [EXAMPLES.md](EXAMPLES.md) - 50+ practical examples\r\n- [API_REFERENCE.md](API_REFERENCE.md) - Full API documentation\r\n- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Common issues and solutions\r\n- [CHANGELOG.md](CHANGELOG.md) - Version history\r\n\r\n## Support\r\n\r\n- [QuickBooks Developer Portal](https://developer.intuit.com)\r\n- [QuickBooks Developer Forum](https://help.developer.intuit.com/s/)\r\n- [API Documentation](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/account)\r\n- [API Status](https://status.developer.intuit.com/)\r\n\r\n## Contributing\r\n\r\nContributions welcome! Please:\r\n1. Fork the repository\r\n2. Create a feature branch\r\n3. Test thoroughly in sandbox\r\n4. Submit a pull request\r\n\r\n## License\r\n\r\nMIT License - See [LICENSE](LICENSE) file for details.\r\n\r\n## Version\r\n\r\n**Current Version**: 1.0.0  \r\n**Last Updated**: February 21, 2026  \r\n**MCP SDK Version**: 0.5.0+  \r\n**Node.js Required**: 18.0.0+\r\n\r\n## Tags\r\n\r\n`accounting` `quickbooks` `invoicing` `payments` `financial-reporting` `bookkeeping` `erp` `business` `intuit` `api-integration` `mcp-skill` `openclaw`\r\n\r\n---\r\n\r\n**Ready to use!** Run `npm install` and authenticate to get started.\n\nFile v1.0.0:_meta.json\n\n{\n  \"ownerId\": \"kn75r02ytvqq38hkzbx6tqctc981dm3h\",\n  \"slug\": \"quickbooks-direct\",\n  \"version\": \"1.0.0\",\n  \"publishedAt\": 1771664634362\n}\n\nFile v1.0.0:config.json\n\n{\r\n  \"client_id\": \"YOUR_QUICKBOOKS_CLIENT_ID\",\r\n  \"client_secret\": \"YOUR_QUICKBOOKS_CLIENT_SECRET\",\r\n  \"redirect_uri\": \"http://localhost:3000/callback\",\r\n  \"access_token\": \"\",\r\n  \"refresh_token\": \"\",\r\n  \"realm_id\": \"\",\r\n  \"token_expiry\": 0\r\n}","readmeExcerpt":"Skill: QuickBooks Direct Owner: armysarge Summary: Comprehensive QuickBooks Online API integration for accounting, invoicing, payments, and financial reporting Tags: latest:1.0.1 Version history: v1.0.1 | 2026-02-21T09:16:16.207Z | user - Added documentation files: API_REFERENCE.md, CHANGELOG.md, EXAMPLES.md, README.md, SECURITY.md, and TROUBLESHOOTING.md. - Updated OAuth redirect URI to http://localhost:3001/callbac","codeSnippets":[],"executableExamples":[],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\r\nname: quickbooks-openclaw\r\nversion: 1.0.1\r\ndescription: Comprehensive QuickBooks Online API integration for accounting, invoicing, payments, and financial reporting\r\nauthor: Armysarge\r\nlicense: MIT\r\ntags:\r\n  - accounting\r\n  - quickbooks\r\n  - invoicing\r\n  - payments\r\n  - financial\r\n  - erp\r\n  - bookkeeping\r\ncategory: Business & Finance\r\n---\r\n\r\n# QuickBooks API Skill for OpenClaw\r\n\r\nA complete QuickBooks Online direct API integration skill for OpenClaw providing full access to accounting, invoicing, customer management, inventory, payments, and financial reporting through the Intuit QuickBooks API.\r\n\r\n## Overview\r\n\r\nThis skill enables OpenClaw to interact with QuickBooks Online for:\r\n- **Customer & Vendor Management**: Create and manage business relationships\r\n- **Invoicing**: Generate, send, and track invoices\r\n- **Payments**: Record and reconcile payments\r\n- **Inventory**: Manage products, services, and stock levels\r\n- **Financial Reports**: Generate P&L, Balance Sheets, Cash Flow, and aging reports\r\n- **Estimates**: Create quotes and proposals\r\n- **Bills**: Track accounts payable\r\n- **Purchase Orders**: Manage procurement\r\n\r\n## Prerequisites\r\n\r\n1. **QuickBooks Developer Account**\r\n   - Sign up at [https://developer.intuit.com](https://developer.intuit.com)\r\n   - Create a new app in the Developer Portal\r\n   - Enable \"QuickBooks Online API\" scope\r\n\r\n2. **App Credentials**\r\n   - Client ID from your QuickBooks app\r\n   - Client Secret from your QuickBooks app\r\n   - Redirect URI: `http://localhost:3001/callback`\r\n\r\n3. **Node.js**\r\n   - Version 18.0.0 or higher\r\n   - npm or yarn package manager\r\n\r\n## Installation\r\n\r\n### 1. Install Dependencies\r\n\r\n```bash\r\ncd \"c:\\Users\\Shaun\\Desktop\\Quickbooks skill\"\r\nnpm install\r\n```\r\n\r\nRequired packages:\r\n- `axios` - HTTP client for API requests\r\n- `express` - OAuth callback server\r\n- `open` - Browser automation for OAuth\r\n\r\n### 2. Configure Credentials\r\n\r\nCreate `config.json` from template:\r\n\r\n```bash\r\ncp config.json.template config.json\r\n```\r\n\r\nEdit `config.json` with your QuickBooks app credentials:\r\n\r\n```json\r\n{\r\n  \"client_id\": \"YOUR_CLIENT_ID_HERE\",\r\n  \"client_secret\": \"YOUR_CLIENT_SECRET_HERE\",\r\n  \"redirect_uri\": \"http://localhost:3001/callback\",\r\n  \"api_environment\": \"sandbox\",\r\n  \"access_token\": \"\",\r\n  \"refresh_token\": \"\",\r\n  \"realm_id\": \"\",\r\n  \"token_expiry\": 0\r\n}\r\n```\r\n\r\n### 3. Add to Configuration\r\n\r\n**For OpenClaw:**\r\n\r\nAdd to your OpenClaw configuration:\r\n```json\r\n{\r\n  \"skills\": {\r\n    \"quickbooks\": {\r\n      \"path\": \"~/.openclaw/workspace/skills/Quickbooks-openclaw\",\r\n      \"enabled\": true,\r\n      \"autoStart\": true\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n## Authentication\r\n\r\n### First-Time Setup\r\n\r\n1. Use the `qb_authenticate` tool with your credentials:\r\n```\r\nUse qb_authenticate with client_id and client_secret\r\n```\r\n\r\n2. A browser window will open automatically\r\n3. Log in to your QuickBooks account\r\n4. Authorize the application\r\n5. You'll be redirected to localhost (handled automatically)\r\n6. Tokens are saved to `c"},{"path":"README.md","content":"# QuickBooks API Skill for OpenClaw\r\n\r\nA comprehensive QuickBooks Online API integration skill for OpenClaw, providing full access to QuickBooks accounting features.\r\n\r\n## Features\r\n\r\n### 🔐 Authentication\r\n- OAuth2 authentication flow with automatic token refresh\r\n- Secure credential storage\r\n- Automatic browser-based authorization\r\n\r\n### 📊 Customer Management\r\n- Create, read, and query customers\r\n- Manage customer details and contact information\r\n- Search customers with SQL-like queries\r\n\r\n### 🧾 Invoice Operations\r\n- Create and manage invoices\r\n- Send invoices via email\r\n- Query invoice history\r\n- Track invoice status\r\n\r\n### 📦 Inventory & Items\r\n- Create and manage products/services\r\n- Track inventory items\r\n- Manage pricing and descriptions\r\n- Support for Service, Inventory, and Non-Inventory items\r\n\r\n### 💰 Payment Processing\r\n- Record customer payments\r\n- Link payments to invoices\r\n- Query payment history\r\n\r\n### 📈 Financial Reports\r\n- Profit & Loss statements\r\n- Balance Sheet reports\r\n- Cash Flow reports\r\n- Aged Receivables (A/R Aging)\r\n- Aged Payables (A/P Aging)\r\n\r\n### 🏢 Vendor Management\r\n- Create and manage vendors\r\n- Create bills for vendors\r\n- Track vendor payments\r\n\r\n### 📝 Estimates & Quotes\r\n- Create estimates/quotes\r\n- Convert estimates to invoices\r\n- Track estimate status\r\n\r\n### 🛒 Purchase Orders\r\n- Create purchase orders\r\n- Track PO status\r\n\r\n### 💵 Sales Receipts\r\n- Create cash sale receipts\r\n- Record immediate payments\r\n\r\n### 🔍 Advanced Features\r\n- Generic SQL-like queries for any entity\r\n- Batch operations for multiple requests\r\n- Complete Chart of Accounts access\r\n- Tax code and rate management\r\n- Company information retrieval\r\n\r\n## Prerequisites\r\n\r\n1. **Node.js** (v18 or higher)\r\n2. **QuickBooks Developer Account**\r\n   - Sign up at [https://developer.intuit.com](https://developer.intuit.com)\r\n3. **QuickBooks App**\r\n   - Create an app in the Intuit Developer Portal\r\n   - Enable QuickBooks Online API scope\r\n\r\n## Setup Instructions\r\n\r\n### Step 1: Create QuickBooks Developer App\r\n\r\n1. Go to [Intuit Developer Portal](https://developer.intuit.com)\r\n2. Sign in and navigate to \"My Apps\"\r\n3. Click \"Create an app\" and select \"QuickBooks Online and Payments\"\r\n4. Fill in your app details:\r\n   - **App name**: Choose a name for your app\r\n   - **Redirect URI**: `http://localhost:3001/callback` (must match exactly)\r\n5. After creating the app, note your:\r\n   - **Client ID**\r\n   - **Client Secret**\r\n6. Under \"Keys & credentials\", make sure you're in the right environment:\r\n   - **Sandbox**: For testing (recommended to start)\r\n   - **Production**: For live data\r\n\r\n### Step 2: Install Dependencies\r\n\r\n```bash\r\ncd \"c:\\Users\\Shaun\\Desktop\\Quickbooks skill\"\r\nnpm install\r\n```\r\n\r\n### Step 3: Configure Authentication\r\n\r\nCreate a `config.json` file from the template:\r\n\r\n```bash\r\ncp config.json.template config.json\r\n```\r\n\r\nEdit `config.json` and add your credentials:\r\n\r\n```json\r\n{\r\n  \"client_id\": \"YOUR_CLIENT_ID_HERE\",\r\n  \"client_secret\": \"YOUR_C"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn75r02ytvqq38hkzbx6tqctc981dm3h\",\n  \"slug\": \"quickbooks-direct\",\n  \"version\": \"1.0.1\",\n  \"publishedAt\": 1771665376207\n}"},{"path":"API_REFERENCE.md","content":"# QuickBooks API Skill - Complete API Reference\r\n\r\n## Entity Relationships\r\n\r\n```\r\n┌─────────────┐\r\n│  Customer   │────┐\r\n└─────────────┘    │\r\n                   ├──► Invoice ──► Payment\r\n┌─────────────┐    │      │\r\n│    Item     │────┤      │\r\n└─────────────┘    │      └──► SalesReceipt\r\n                   │\r\n┌─────────────┐    └──► Estimate\r\n│   Account   │\r\n└─────────────┘\r\n\r\n┌─────────────┐\r\n│   Vendor    │────► Bill ──► BillPayment\r\n└─────────────┘    │\r\n                   └──► PurchaseOrder\r\n```\r\n\r\n## Core Entities\r\n\r\n### Customer\r\n\r\n**Fields:**\r\n- `DisplayName` (required) - Customer name\r\n- `Title` - Title (Mr., Mrs., etc.)\r\n- `GivenName` - First name\r\n- `MiddleName` - Middle name\r\n- `FamilyName` - Last name\r\n- `Suffix` - Name suffix (Jr., Sr., etc.)\r\n- `CompanyName` - Company name\r\n- `PrimaryEmailAddr.Address` - Email address\r\n- `PrimaryPhone.FreeFormNumber` - Phone number\r\n- `Mobile.FreeFormNumber` - Mobile number\r\n- `Fax.FreeFormNumber` - Fax number\r\n- `WebAddr.URI` - Website URL\r\n- `BillAddr` - Billing address object\r\n  - `Line1`, `Line2`, `Line3`, `Line4`, `Line5`\r\n  - `City`\r\n  - `CountrySubDivisionCode` (State/Province)\r\n  - `PostalCode`\r\n  - `Country`\r\n- `ShipAddr` - Shipping address (same structure as BillAddr)\r\n- `Notes` - Customer notes\r\n- `Active` - Boolean, customer status\r\n- `Balance` - Current balance (read-only)\r\n- `BalanceWithJobs` - Balance including jobs (read-only)\r\n- `PreferredDeliveryMethod` - Email, Print, or None\r\n- `ResaleNum` - Resale number\r\n- `PaymentMethodRef` - Default payment method\r\n- `TermRef` - Payment terms reference\r\n\r\n**Query Examples:**\r\n```sql\r\nSELECT * FROM Customer WHERE Active = true\r\nSELECT * FROM Customer WHERE Balance > 0\r\nSELECT * FROM Customer WHERE DisplayName LIKE '%ACME%'\r\nSELECT Id, DisplayName, Balance FROM Customer ORDER BY Balance DESC\r\n```\r\n\r\n### Invoice\r\n\r\n**Fields:**\r\n- `CustomerRef.value` (required) - Customer ID\r\n- `Line` (required) - Array of line items\r\n  - `Amount` (required)\r\n  - `DetailType` - Usually \"SalesItemLineDetail\"\r\n  - `Description`\r\n  - `SalesItemLineDetail`\r\n    - `ItemRef.value` (required) - Item ID\r\n    - `Qty` - Quantity\r\n    - `UnitPrice` - Price per unit\r\n    - `TaxCodeRef.value` - Tax code\r\n    - `DiscountAmt` - Discount amount\r\n- `TxnDate` - Transaction date (YYYY-MM-DD)\r\n- `DueDate` - Due date (YYYY-MM-DD)\r\n- `DocNumber` - Invoice number (auto-generated if omitted)\r\n- `PrivateNote` - Internal note\r\n- `CustomerMemo.value` - Message to customer\r\n- `BillEmail.Address` - Email for sending invoice\r\n- `BillEmailCc.Address` - CC email address\r\n- `BillEmailBcc.Address` - BCC email address\r\n- `ShipAddr` - Shipping address\r\n- `BillAddr` - Billing address\r\n- `TxnTaxDetail` - Tax details\r\n- `SalesTermRef` - Payment terms\r\n- `ShipMethodRef` - Shipping method\r\n- `ShipDate` - Ship date\r\n- `TrackingNum` - Tracking number\r\n- `TotalAmt` (read-only) - Total amount\r\n- `Balance` (read-only) - Remaining balance\r\n- `EmailStatus` - Email status (read-only)\r\n- `PrintStatus` - Prin"},{"path":"CHANGELOG.md","content":"# Changelog\r\n\r\nAll notable changes to the QuickBooks API Skill will be documented in this file.\r\n\r\nThe format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),\r\nand this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\r\n\r\n## [1.0.1] - 2026-02-21\r\n\r\n### Fixed\r\n- **Port Mismatch**: Standardized redirect URI and callback server to port 3001 across all documentation (was inconsistent between 3000 and 3001)\r\n- **Dependency Cleanup**: Removed unused `@modelcontextprotocol/sdk` reference from SKILL.md (not actually required)\r\n- **API Endpoint**: Changed from hard-coded sandbox URL to configurable environment setting\r\n\r\n### Added\r\n- **Configurable API Environment**: Added `api_environment` field to `config.json` allowing easy switching between sandbox and production\r\n- **Security Documentation**: Comprehensive security warnings about credential storage in plaintext\r\n- **Security Best Practices**: 10-point security checklist for production deployments\r\n- **Environment Troubleshooting**: Added guidance for API environment configuration issues\r\n\r\n### Changed\r\n- Config template now includes `api_environment: \"sandbox\"` by default\r\n- `run.js` now reads `api_environment` from config and selects correct API base URL dynamically\r\n- Enhanced documentation with specific security considerations for credential management\r\n- Updated version numbers across all documentation files\r\n\r\n### Security\r\n- Added explicit warnings about plaintext credential storage in `config.json`\r\n- Documented file permission requirements\r\n- Added recommendations for credential rotation\r\n- Included notes about autoStart risks\r\n\r\n## [1.0.0] - 2026-02-21\r\n\r\n### Added\r\n- Initial release of QuickBooks API Skill\r\n- OAuth2 authentication flow with automatic token refresh\r\n- Customer management (create, read, query)\r\n- Invoice operations (create, read, send, query)\r\n- Item/Product management (create, read, query)\r\n- Payment processing (create, query)\r\n- Estimate/Quote management (create, query)\r\n- Vendor management (create, query)\r\n- Bill management (create, query)\r\n- Purchase Order operations (create, query)\r\n- Sales Receipt operations (create, query)\r\n- Financial reports:\r\n  - Profit & Loss statement\r\n  - Balance Sheet\r\n  - Cash Flow statement\r\n  - Aged Receivables (A/R Aging)\r\n  - Aged Payables (A/P Aging)\r\n- Chart of Accounts querying\r\n- Company information retrieval\r\n- Generic SQL-like query support for all entities\r\n- Batch operations for multiple requests\r\n- Tax code and rate management\r\n- Comprehensive error handling\r\n- Automatic token refresh mechanism\r\n- Configuration file management\r\n- Complete documentation:\r\n  - README.md with setup instructions\r\n  - EXAMPLES.md with practical examples\r\n  - API_REFERENCE.md with complete API documentation\r\n  - TROUBLESHOOTING.md with common issues and solutions\r\n- Support for both Sandbox and Production environments\r\n\r\n### Features\r\n- 40+ tool implementations covering core QuickBooks operations\r\n- Suppo"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1584,"uniquenessScore":44,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T23:59:04.750Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T23:59:04.750Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-12T15:12:19.167Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}