@interweave/sdk

Official TypeScript SDK for the InterWeave SmartIntegration API.

Zero runtime dependencies. Strict TypeScript. Built-in fetch.

Install

npm install @interweave/sdk

Requires Node 18+ (for built-in fetch) or any modern browser.

Quick Start

import { InterWeaveClient } from "@interweave/sdk";

const iw = new InterWeaveClient({ baseUrl: "https://interweave-ide.dev/iw-business-daemon" });
await iw.login("[email protected]", "password");

// List all flows
const flows = await iw.listFlows();

// Start a sync
await iw.startFlow({ flowIndex: 0 });

// Check health (no auth required)
const health = await iw.getHealth();

Available Methods

The SDK provides the following method categories:

• Auth — login(), logout(), getSession()
• Flows — listFlows(), startFlow(), stopFlow(), initializeFlows()
• Monitoring — getHealth(), getDashboard(), getConnectionHealth(), getMetrics(), listTransactions(), getTransaction()
• QBO Proxy — qboPost(), qboGet()
• MCP Bridge — listMcpTools(), mcpInvoke()

For full method signatures and options, see the Constructor and Methods sections below.

Constructor

const client = new InterWeaveClient({
  baseUrl: 'http://localhost:9090/iw-business-daemon', // local dev
  token: 'existing-bearer-token',                      // optional — skip login
});

| Option | Type | Required | Description | |-----------|----------|----------|----------------------------------------------| | baseUrl | string | Yes | Base URL of the iw-business-daemon | | token | string | No | Bearer token; can also be set via login() |

Methods

Auth

| Method | Description | |--------|-------------| | login(email, password) | Authenticate and store the Bearer token automatically | | logout() | Invalidate the session and clear the stored token | | getSession() | Check if the current session is authenticated |

QuickBooks Online Proxy

| Method | Description | |--------|-------------| | qboPost(opts) | Proxy a write request (create, update, delete, void, send) to QBO | | qboGet(entity, action?) | Proxy a read/query request to QBO |

Both methods support dryRun: true to simulate writes without touching QBO.

Flows

| Method | Description | |--------|-------------| | listFlows() | List all integration flows (scheduled, utility, query) with state | | startFlow({ flowIndex }) | Start a flow by index (admin only) | | stopFlow({ flowIndex }) | Stop a running flow by index (admin only) | | initializeFlows() | Reload the engine profile for the current user (admin only) |

Monitoring

| Method | Description | |--------|-------------| | getHealth() | System health check — no auth required | | getDashboard(opts?) | Real-time dashboard: counts, running transactions, recent activity | | getConnectionHealth() | Per-connection health with live OAuth/endpoint checks | | getMetrics(opts?) | Time-series Chart.js-compatible metrics | | listTransactions(opts?) | Paginated, filterable transaction execution history | | getTransaction(id) | Full transaction detail with request/response payloads |

MCP (AI Agent Bridge)

| Method | Description | |--------|-------------| | listMcpTools() | Discover available MCP tools and their input schemas | | mcpInvoke(tool, input?) | Invoke an MCP tool by name |

Available MCP tools: interweave_sync_records, interweave_check_health, interweave_run_validation, interweave_reconcile, interweave_list_connections, interweave_export_data.

Error handling

All non-2xx responses throw an InterWeaveError:

import { InterWeaveClient, InterWeaveError } from '@interweave/sdk';

try {
  await client.login('[email protected]', 'wrong-password');
} catch (err) {
  if (err instanceof InterWeaveError) {
    console.error(`[${err.status}] ${err.code}: ${err.userFacingMessage}`);
    // e.g. [401] AUTH001: The email or password you entered is incorrect.
  }
}

| Property | Type | Description | |----------|------|-------------| | status | number | HTTP status code | | code | string | Structured error code from the server (e.g. AUTH001) | | userFacingMessage | string | Plain-English message safe to display to end users | | message | string | Technical detail for logs and developer tools |

Examples

Start a flow and wait for confirmation

const response = await client.startFlow({ flowIndex: 0 });
if (response.data?.running) {
  console.log(`Flow "${response.data.flowId}" is now running`);
}

Dry-run a QBO write

const result = await client.qboPost({
  entity: 'Invoice',
  action: 'create',
  dryRun: true,
  body: { Line: [], CustomerRef: { value: '123' } },
});
// result.simulated === true — nothing was sent to QuickBooks

Fetch the monitoring dashboard

const { data } = await client.getDashboard({ include_running: true });
console.log(`${data.summary.running_count} flows running, ${data.summary.success_rate_24h}% success today`);

Invoke an MCP tool from an AI agent

const catalog = await client.listMcpTools();
const syncTool = catalog.tools.find(t => t.name === 'interweave_sync_records');

const result = await client.mcpInvoke('interweave_sync_records', {
  entityType: 'accounts',
  mode: 'upsert',
});
console.log(result.status); // "ok"

Local development server

const client = new InterWeaveClient({
  baseUrl: 'http://localhost:9090/iw-business-daemon',
});

API documentation

Full OpenAPI 3.1 spec: public/openapi.yaml in the IW_Launcher repository.

License

MIT — InterWeave SmartSolutions