SDK

The Bonnard SDK (@bonnard/sdk) is a lightweight TypeScript/JavaScript client for querying your deployed semantic layer. Zero dependencies, ~3KB minified — works in Node.js, browsers, and edge runtimes.

Before you start

The SDK queries your deployed semantic layer — you need these in place first:

1. A deployed semantic layer — at least one cube and view, deployed with bon deploy. See Getting Started if you haven't done this yet.
2. A publishable key — go to Settings > API Keys in the Bonnard dashboard and create one. It starts with bon_pk_....

Once you have a key, use explore() to discover what's available before writing your first query:

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

// Step 1: see what views exist
const meta = await bon.explore();
console.log(meta.cubes.map((v) => v.name)); // ['orders', 'customers', ...]

// Step 2: see what fields a view has
const orders = meta.cubes.find((v) => v.name === "orders");
console.log(orders.measures.map((m) => m.name)); // ['orders.revenue', 'orders.count']
console.log(orders.dimensions.map((d) => d.name)); // ['orders.city', 'orders.status']

// Step 3: query using those field names
const { data } = await bon.query({
  measures: ["orders.revenue"],
  dimensions: ["orders.city"],
});

Reading order for new SDK users: this page → Authentication → Query Reference → Errors → then whichever integration guide fits your use case (React, browser, AI agents, chart libraries).

Two ways to use it

npm (TypeScript / Node.js / React)

npm install @bonnard/sdk

import { createClient } from "@bonnard/sdk";

const bon = createClient({ apiKey: "bon_pk_..." });
const { data } = await bon.query({
  measures: ["orders.revenue"],
  dimensions: ["orders.city"],
});

CDN (browser / HTML dashboards)

<script src="https://cdn.jsdelivr.net/npm/@bonnard/sdk/dist/bonnard.iife.js"></script>
<script>
  const bon = Bonnard.createClient({ apiKey: "bon_pk_..." });
</script>

Exposes window.Bonnard with createClient and toCubeQuery. See Browser for the full browser quickstart.

Authentication

Two modes depending on your use case:

// Simple: publishable key
const bon = createClient({ apiKey: "bon_pk_..." });

// Multi-tenant: token exchange
const bon = createClient({
  fetchToken: async () => {
    const res = await fetch("/my-backend/bonnard-token");
    const { token } = await res.json();
    return token;
  },
});

The SDK automatically caches tokens and refreshes them 60 seconds before expiry.

See Authentication for the full auth guide.

What you can query

See Query Reference for the full API reference.

Building AI agents

Give your AI agents direct access to your semantic layer. Import createTools with a framework adapter and get four production-ready tools — schema discovery, querying, SQL, and field metadata.

import { createClient } from "@bonnard/sdk";
import { createTools } from "@bonnard/sdk/ai/vercel";

const bon = createClient({ apiKey: "bon_pk_..." });
const tools = createTools(bon);
// → { explore_schema, query, sql_query, describe_field }

Adapters for Vercel AI SDK and LangChain/LangGraph included. See AI Agents for the full guide.

Building with React

For React apps, use @bonnard/react — pre-built chart components with theming, formatting, and dark mode built in. No chart library wiring required.

npm install @bonnard/react @bonnard/sdk

See React for the full component reference (BigValue, BarChart, LineChart, AreaChart, PieChart, DataTable, useBonnardQuery hook).

Building HTML dashboards

The SDK pairs with any chart library for single-file HTML dashboards. No build step required — load both from CDN and start querying.

Each guide includes a complete, copy-pasteable HTML starter template:

• Chartjs — Chart.js + SDK
• Echarts — ECharts + SDK
• Apexcharts — ApexCharts + SDK

See also

• AI Agents — AI agent tools (Vercel AI, LangChain, framework-agnostic)
• React — React components (BigValue, charts, DataTable, hooks)
• Browser — Browser / CDN quickstart
• Query Reference — Full query API reference
• Authentication — Auth patterns
• Errors — Error handling, status codes, and retry patterns
• Security Context — Row-level security for multi-tenant apps