# Bonnard Sdk

> TypeScript SDK for querying the Bonnard semantic layer. JSON queries, SQL interface, multi-tenant token exchange. Works in Node.js, Edge, and browser.

- **Type:** MCP server
- **Install:** `agentstack add mcp-bonnard-data-bonnard-sdk`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [bonnard-data](https://agentstack.voostack.com/s/bonnard-data)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [bonnard-data](https://github.com/bonnard-data)
- **Source:** https://github.com/bonnard-data/bonnard-sdk
- **Website:** https://bonnard.dev

## Install

```sh
agentstack add mcp-bonnard-data-bonnard-sdk
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

> [!IMPORTANT]
> **This repository is archived and no longer maintained.**
> It was part of an earlier version of Bonnard. Our current products live at **[bonnard.dev](https://bonnard.dev)**. Start with **[`@bonnard/mcp-charts`](https://github.com/bonnard-data/mcp-charts)**.
> Questions: pierre@bonnard.dev

# @bonnard/sdk

TypeScript SDK for querying the [Bonnard](https://www.bonnard.dev) semantic layer from any JavaScript or TypeScript application.

## Install

```bash
npm install @bonnard/sdk
```

## Quick Start

### With a publishable key

```typescript
import { createClient } from '@bonnard/sdk';

const bon = createClient({
  apiKey: 'bon_pk_...',
});

const { data } = await bon.query({
  measures: ['orders.revenue', 'orders.count'],
  dimensions: ['orders.status'],
});

console.log(data);
// [{ "orders.revenue": 45000, "orders.count": 120, "orders.status": "completed" }, ...]
```

### With token exchange (multi-tenant)

For B2B apps where each user sees their own data, use a server-side secret key to mint scoped tokens:

```typescript
// Server: exchange secret key for a scoped JWT
const res = await fetch('https://app.bonnard.dev/api/sdk/token', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer bon_sk_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    security_context: { tenant_id: 'acme-123' },
  }),
});
const { token } = await res.json();
```

```typescript
// Client: use the token callback
const bon = createClient({
  fetchToken: async () => {
    const res = await fetch('/api/analytics/token');
    const { token } = await res.json();
    return token;
  },
});

const { data } = await bon.query({
  measures: ['orders.revenue'],
  timeDimension: {
    dimension: 'orders.created_at',
    granularity: 'month',
    dateRange: ['2025-01-01', '2025-12-31'],
  },
});
```

Tokens are cached automatically and refreshed 60 seconds before expiry.

## API

### `createClient(config)`

| Option | Type | Description |
|--------|------|-------------|
| `apiKey` | `string` | Publishable key (`bon_pk_...`). Use one of `apiKey` or `fetchToken`. |
| `fetchToken` | `() => Promise` | Async callback that returns a JWT. Use for multi-tenant setups. |
| `baseUrl` | `string` | API base URL (default: `https://app.bonnard.dev`) |

### `client.query(options)`

JSON query against the semantic layer.

```typescript
const { data } = await bon.query({
  measures: ['orders.revenue', 'orders.count'],
  dimensions: ['orders.product_category'],
  filters: [
    { dimension: 'orders.status', operator: 'equals', values: ['completed'] },
  ],
  timeDimension: {
    dimension: 'orders.created_at',
    granularity: 'month',
    dateRange: ['2025-01-01', '2025-12-31'],
  },
  orderBy: { 'orders.revenue': 'desc' },
  limit: 100,
});
```

### `client.sql(query)`

Raw SQL query using Cube SQL syntax.

```typescript
const { data } = await bon.sql(
  `SELECT product_category, MEASURE(revenue) FROM orders GROUP BY 1`
);
```

### Error handling

All API errors throw `BonnardError` with the HTTP status code:

```typescript
import { createClient, BonnardError } from '@bonnard/sdk';

try {
  const { data } = await bon.query({ measures: ['orders.revenue'] });
} catch (err) {
  if (err instanceof BonnardError) {
    console.log(err.statusCode); // 401, 400, 500, etc.
    console.log(err.retryable);  // true for 429 and 5xx
  }
}
```

## Links

- [Bonnard Docs](https://docs.bonnard.dev)
- [Getting Started](https://docs.bonnard.dev/docs/getting-started)
- [Discord](https://discord.com/invite/RQuvjGRz)

## License

[MIT](./LICENSE)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [bonnard-data](https://github.com/bonnard-data)
- **Source:** [bonnard-data/bonnard-sdk](https://github.com/bonnard-data/bonnard-sdk)
- **License:** MIT
- **Homepage:** https://bonnard.dev

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-bonnard-data-bonnard-sdk
- Seller: https://agentstack.voostack.com/s/bonnard-data
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.