npm package: @interweave-technologies/sdk
Description: TypeScript SDK for the InterWeave SmartIntegration API
Latest version: 0.1.0

# @interweave/sdk

Official TypeScript SDK for the [InterWeave SmartIntegration](https://interweave-ide.dev) API.

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

---

## Install

```bash
npm install @interweave/sdk
```

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

---

## Quick Start

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

const iw = new InterWeaveClient({ baseUrl: "https://interweave-ide.dev/iw-business-daemon" });
await iw.login("user@example.com", "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

```ts
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`:

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

try {
  await client.login('user@example.com', '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

```ts
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

```ts
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

```ts
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

```ts
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

```ts
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