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.

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:

Mode	Key type	Use case
Publishable key	`bon_pk_...`	Public dashboards, client-side apps — safe to expose in HTML
Token exchange	`bon_sk_...` → JWT	Multi-tenant / embedded analytics — server exchanges secret key for scoped token

// 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

Method	Purpose
`query()`	JSON query — measures, dimensions, filters, time dimensions
`rawQuery()`	Pass a Cube-native query object directly
`sql()`	SQL with `MEASURE()` syntax
`explore()`	Discover available views, measures, and dimensions

See Query Reference for the full API reference.

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.

Library	CDN size (gzip)	Best for
Chart.js	~65 KB	Default choice — most LLM training data, smallest payload
ECharts	~160 KB	Rich interactivity, built-in dark theme
ApexCharts	~130 KB	Best defaults out of box, SVG rendering

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

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