@bonnard/cli 0.2.15 → 0.3.0

package/dist/docs/topics/sdk.md

@@ -0,0 +1,95 @@
+# SDK
+
+> Build data apps and dashboards on top of your semantic layer.
+
+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)
+
+```bash
+npm install @bonnard/sdk
+```
+
+```typescript
+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)
+
+```html
+<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 [sdk.browser](sdk.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 |
+
+```typescript
+// 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 [sdk.authentication](sdk.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 [sdk.query-reference](sdk.query-reference) for the full API reference.
+
+## 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:
+
+- [sdk.chartjs](sdk.chartjs) — Chart.js + SDK
+- [sdk.echarts](sdk.echarts) — ECharts + SDK
+- [sdk.apexcharts](sdk.apexcharts) — ApexCharts + SDK
+
+## See also
+
+- [sdk.browser](sdk.browser) — Browser / CDN quickstart
+- [sdk.query-reference](sdk.query-reference) — Full query API reference
+- [sdk.authentication](sdk.authentication) — Auth patterns
+- [security-context](security-context) — Row-level security for multi-tenant apps

package/dist/docs/topics/sdk.query-reference.md

@@ -0,0 +1,307 @@
+# Query API Reference
+
+> Complete reference for querying the Bonnard semantic layer via the SDK.
+
+## query()
+
+Execute a JSON query against the semantic layer. All field names must be fully qualified (e.g. `orders.revenue`, not `revenue`).
+
+```javascript
+const { data } = await bon.query({
+  measures: ['orders.revenue', 'orders.count'],
+  dimensions: ['orders.city'],
+  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: 10,
+});
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `measures` | `string[]` | No | Numeric aggregations to compute (e.g. `['orders.revenue']`) |
+| `dimensions` | `string[]` | No | Group-by columns (e.g. `['orders.city']`) |
+| `filters` | `Filter[]` | No | Row-level filters |
+| `timeDimension` | `TimeDimension` | No | Time-based grouping and date range |
+| `orderBy` | `Record<string, 'asc' \| 'desc'>` | No | Sort order |
+| `limit` | `number` | No | Max rows to return |
+
+At least one of `measures` or `dimensions` is required.
+
+### Response
+
+```javascript
+{
+  data: [
+    { "orders.revenue": 125000, "orders.count": 340, "orders.city": "Berlin" },
+    { "orders.revenue": 98000, "orders.count": 280, "orders.city": "Munich" },
+  ],
+  annotation: {
+    measures: {
+      "orders.revenue": { title: "Revenue", type: "number" },
+      "orders.count": { title: "Count", type: "number" },
+    },
+    dimensions: {
+      "orders.city": { title: "City", type: "string" },
+    },
+  }
+}
+```
+
+- `data` — array of result rows, keyed by fully qualified field names
+- `annotation` — optional metadata with field titles and types
+
+## Filters
+
+```javascript
+filters: [
+  { dimension: 'orders.status', operator: 'equals', values: ['completed'] },
+  { dimension: 'orders.revenue', operator: 'gt', values: [1000] },
+]
+```
+
+### Filter operators
+
+| Operator | Description | Example values |
+|----------|-------------|---------------|
+| `equals` | Exact match (any of values) | `['completed', 'shipped']` |
+| `notEquals` | Exclude matches | `['cancelled']` |
+| `contains` | Substring match | `['berlin']` |
+| `gt` | Greater than | `[1000]` |
+| `gte` | Greater than or equal | `[1000]` |
+| `lt` | Less than | `[100]` |
+| `lte` | Less than or equal | `[100]` |
+
+## Time dimensions
+
+Group data by time periods and filter by date range.
+
+```javascript
+timeDimension: {
+  dimension: 'orders.created_at',
+  granularity: 'month',
+  dateRange: ['2025-01-01', '2025-06-30'],
+}
+```
+
+### Granularities
+
+| Granularity | Groups by |
+|-------------|-----------|
+| `day` | Calendar day |
+| `week` | ISO week (Monday start) |
+| `month` | Calendar month |
+| `quarter` | Calendar quarter |
+| `year` | Calendar year |
+
+Omit `granularity` to filter by date range without time grouping.
+
+### Date range formats
+
+```javascript
+// ISO date strings (tuple)
+dateRange: ['2025-01-01', '2025-12-31']
+
+// Single string (relative)
+dateRange: 'last 30 days'
+dateRange: 'last 6 months'
+dateRange: 'this year'
+dateRange: 'last year'
+dateRange: 'today'
+dateRange: 'yesterday'
+dateRange: 'last week'
+dateRange: 'last month'
+dateRange: 'last quarter'
+```
+
+## Ordering and pagination
+
+```javascript
+// Sort by revenue descending
+orderBy: { 'orders.revenue': 'desc' }
+
+// Multiple sort keys
+orderBy: { 'orders.city': 'asc', 'orders.revenue': 'desc' }
+
+// Limit results
+limit: 10
+```
+
+## rawQuery()
+
+Pass a Cube-native query object directly, bypassing the SDK's query format conversion. Use when you need features not exposed by `query()` (e.g. segments, offset).
+
+```javascript
+const { data } = await bon.rawQuery({
+  measures: ['orders.revenue'],
+  dimensions: ['orders.city'],
+  order: [['orders.revenue', 'desc']],
+  limit: 10,
+  offset: 20,
+});
+```
+
+## sql()
+
+Execute a SQL query using Cube's SQL API. Use `MEASURE()` to reference semantic layer measures.
+
+```javascript
+const { data } = await bon.sql(
+  `SELECT city, MEASURE(revenue), MEASURE(count)
+   FROM orders
+   WHERE status = 'completed'
+   GROUP BY 1
+   ORDER BY 2 DESC
+   LIMIT 10`
+);
+```
+
+Response includes an optional schema:
+
+```javascript
+{
+  data: [
+    { city: "Berlin", revenue: 125000, count: 340 },
+  ],
+  schema: [
+    { name: "city", type: "string" },
+    { name: "revenue", type: "number" },
+    { name: "count", type: "number" },
+  ]
+}
+```
+
+## explore()
+
+Discover available views, measures, dimensions, and segments.
+
+```javascript
+const meta = await bon.explore();
+
+for (const view of meta.cubes) {
+  console.log(`${view.name}: ${view.description || ''}`);
+  for (const m of view.measures) {
+    console.log(`  measure: ${m.name} (${m.type})`);
+  }
+  for (const d of view.dimensions) {
+    console.log(`  dimension: ${d.name} (${d.type})`);
+  }
+}
+```
+
+By default returns only views (`viewsOnly: true`). To include underlying cubes:
+
+```javascript
+const meta = await bon.explore({ viewsOnly: false });
+```
+
+### Response shape
+
+```javascript
+{
+  cubes: [
+    {
+      name: "orders",
+      title: "Orders",
+      description: "Customer orders",
+      type: "view",
+      measures: [
+        { name: "orders.revenue", title: "Revenue", type: "number" },
+        { name: "orders.count", title: "Count", type: "number" },
+      ],
+      dimensions: [
+        { name: "orders.city", title: "City", type: "string" },
+        { name: "orders.created_at", title: "Created At", type: "time" },
+      ],
+      segments: [],
+    }
+  ]
+}
+```
+
+## toCubeQuery()
+
+Utility function that converts SDK `QueryOptions` into a Cube-native query object. Useful for debugging or when you need to inspect the query before sending.
+
+```javascript
+import { toCubeQuery } from '@bonnard/sdk';
+// or in browser: Bonnard.toCubeQuery(...)
+
+const cubeQuery = Bonnard.toCubeQuery({
+  measures: ['orders.revenue'],
+  dimensions: ['orders.city'],
+  orderBy: { 'orders.revenue': 'desc' },
+});
+
+console.log(JSON.stringify(cubeQuery, null, 2));
+// {
+//   "measures": ["orders.revenue"],
+//   "dimensions": ["orders.city"],
+//   "order": [["orders.revenue", "desc"]]
+// }
+```
+
+## Common patterns
+
+### KPI query (single row, no dimensions)
+
+```javascript
+const { data } = await bon.query({
+  measures: ['orders.revenue', 'orders.count', 'orders.avg_value'],
+});
+const kpis = data[0];
+// { "orders.revenue": 1250000, "orders.count": 3400, "orders.avg_value": 367.6 }
+```
+
+### Top N with dimension
+
+```javascript
+const { data } = await bon.query({
+  measures: ['orders.revenue'],
+  dimensions: ['orders.city'],
+  orderBy: { 'orders.revenue': 'desc' },
+  limit: 10,
+});
+```
+
+### Time series
+
+```javascript
+const { data } = await bon.query({
+  measures: ['orders.revenue'],
+  timeDimension: {
+    dimension: 'orders.created_at',
+    granularity: 'month',
+    dateRange: 'last 12 months',
+  },
+});
+// data[0]["orders.created_at"] is an ISO date string like "2025-01-01T00:00:00.000"
+```
+
+### Filtered breakdown
+
+```javascript
+const { data } = await bon.query({
+  measures: ['orders.revenue'],
+  dimensions: ['orders.product_category'],
+  filters: [
+    { dimension: 'orders.city', operator: 'equals', values: ['Berlin'] },
+    { dimension: 'orders.revenue', operator: 'gt', values: [100] },
+  ],
+  orderBy: { 'orders.revenue': 'desc' },
+});
+```
+
+## See also
+
+- [sdk.browser](sdk.browser) — Browser / CDN quickstart
+- [sdk.authentication](sdk.authentication) — Auth patterns
+- [sdk.chartjs](sdk.chartjs) — Building dashboards with Chart.js

package/dist/templates/claude/skills/bonnard-build-dashboard/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: bonnard-build-dashboard
+description: Guide a user through building and deploying a markdown dashboard. Use when user says "build a dashboard", "create a chart", "visualize data", or wants to create a dashboard.
+allowed-tools: Bash(bon *), Write, Edit, Read
+---
+
+# Build & Deploy a Markdown Dashboard
+
+This skill guides you through creating a markdown dashboard with built-in
+chart components and deploying it to Bonnard.
+
+## Phase 1: Explore Available Data
+
+Discover what measures and dimensions are available to query:
+
+```bash
+# List all views and their fields
+bon docs schema
+
+# Query a specific view to see what data looks like
+bon query '{"measures": ["view_name.measure"], "dimensions": ["view_name.dimension"], "limit": 5}'
+
+# Or use SQL format
+bon query --sql "SELECT MEASURE(total_revenue), date FROM sales_performance LIMIT 5"
+```
+
+Ask the user what data they want to visualize. Match their request to
+available views and measures.
+
+## Phase 2: Learn the Format
+
+Review the dashboard format docs for reference:
+
+```bash
+bon docs dashboards              # Overview + format
+bon docs dashboards.components   # Chart components (BigValue, LineChart, BarChart, etc.)
+bon docs dashboards.queries      # Query block syntax
+bon docs dashboards.inputs       # Interactive filters (DateRange, Dropdown)
+bon docs dashboards.examples     # Complete examples
+```
+
+## Phase 3: Build the Markdown File
+
+Create a `.md` file with three parts:
+
+1. **YAML frontmatter** — title and optional description
+2. **Query blocks** — ` ```query name ` code fences with YAML query options
+3. **Components** — `<BigValue />`, `<LineChart />`, `<BarChart />`, etc.
+
+Key points:
+- All field names must be fully qualified: `orders.total_revenue`, not `total_revenue`
+- Each component references a query by name: `data={query_name}`
+- Consecutive `<BigValue>` components auto-group into a row
+- Use `<Grid cols="2">` to place charts side by side
+- Use `<DateRange>` and `<Dropdown>` for interactive filters
+
+Example structure:
+
+```markdown
+---
+title: Revenue Dashboard
+description: Key revenue metrics and trends
+---
+
+` ``query total_revenue
+measures: [orders.total_revenue]
+` ``
+
+` ``query order_count
+measures: [orders.count]
+` ``
+
+<BigValue data={total_revenue} value="orders.total_revenue" title="Revenue" fmt="eur2" />
+<BigValue data={order_count} value="orders.count" title="Orders" />
+
+## Trend
+
+` ``query monthly
+measures: [orders.total_revenue]
+timeDimension:
+  dimension: orders.created_at
+  granularity: month
+` ``
+
+<LineChart data={monthly} x="orders.created_at" y="orders.total_revenue" title="Monthly Revenue" yFmt="eur" />
+```
+
+Save the file (e.g., `dashboard.md`).
+
+## Phase 4: Preview Locally
+
+Preview the dashboard with live reload:
+
+```bash
+bon dashboard dev dashboard.md
+```
+
+This opens a browser with the rendered dashboard. Edit the `.md` file and
+the preview updates automatically. Queries run against the deployed
+semantic layer using the user's credentials.
+
+Requires `bon login` — no API key needed.
+
+## Phase 5: Deploy
+
+Deploy the dashboard to Bonnard:
+
+```bash
+bon dashboard deploy dashboard.md
+```
+
+This will:
+- Upload the markdown content
+- Assign a slug (derived from filename, or use `--slug`)
+- Extract the title from frontmatter
+- Print the URL where the dashboard is accessible
+
+Options:
+- `--slug <slug>` — custom URL slug (default: derived from filename)
+- `--title <title>` — override frontmatter title
+
+## Phase 6: View Live
+
+Open the deployed dashboard in the browser:
+
+```bash
+bon dashboard open dashboard
+```
+
+## Iteration
+
+To update, edit the `.md` file and redeploy:
+
+```bash
+bon dashboard deploy dashboard.md
+```
+
+Each deploy increments the version. Use `bon dashboard list` to see all
+deployed dashboards with their versions and URLs.
+
+To remove a dashboard:
+
+```bash
+bon dashboard remove dashboard
+```

package/dist/templates/claude/skills/bonnard-get-started/SKILL.md

@@ -30,7 +30,7 @@ bon datasource add --name my_warehouse --type postgres \
 bon datasource add
 ```
 
-Supported types: `postgres`, `redshift`, `snowflake`, `bigquery`, `databricks`.
+Supported types: `postgres`, `redshift`, `snowflake`, `bigquery`, `databricks`, `duckdb`.
 
 The demo option adds a read-only Contoso retail dataset with tables like
 `fact_sales`, `dim_product`, `dim_store`, and `dim_customer`.

package/dist/templates/claude/skills/bonnard-metabase-migrate/SKILL.md

@@ -65,7 +65,7 @@ bon datasource add --from-dbt
 bon datasource add
 ```
 
-Supported types: `postgres`, `redshift`, `snowflake`, `bigquery`, `databricks`.
+Supported types: `postgres`, `redshift`, `snowflake`, `bigquery`, `databricks`, `duckdb`.
 
 The connection will be tested automatically during `bon deploy`.
 

package/dist/templates/cursor/rules/bonnard-build-dashboard.mdc

@@ -0,0 +1,144 @@
+---
+description: "Guide for building and deploying markdown dashboards with built-in chart components. Use when user says 'build a dashboard', 'create a chart', 'visualize data', or wants to create a dashboard."
+alwaysApply: false
+---
+
+# Build & Deploy a Markdown Dashboard
+
+This guide walks through creating a markdown dashboard with built-in
+chart components and deploying it to Bonnard.
+
+## Phase 1: Explore Available Data
+
+Discover what measures and dimensions are available to query:
+
+```bash
+# List all views and their fields
+bon docs schema
+
+# Query a specific view to see what data looks like
+bon query '{"measures": ["view_name.measure"], "dimensions": ["view_name.dimension"], "limit": 5}'
+
+# Or use SQL format
+bon query --sql "SELECT MEASURE(total_revenue), date FROM sales_performance LIMIT 5"
+```
+
+Ask the user what data they want to visualize. Match their request to
+available views and measures.
+
+## Phase 2: Learn the Format
+
+Review the dashboard format docs for reference:
+
+```bash
+bon docs dashboards              # Overview + format
+bon docs dashboards.components   # Chart components (BigValue, LineChart, BarChart, etc.)
+bon docs dashboards.queries      # Query block syntax
+bon docs dashboards.inputs       # Interactive filters (DateRange, Dropdown)
+bon docs dashboards.examples     # Complete examples
+```
+
+## Phase 3: Build the Markdown File
+
+Create a `.md` file with three parts:
+
+1. **YAML frontmatter** — title and optional description
+2. **Query blocks** — ` ```query name ` code fences with YAML query options
+3. **Components** — `<BigValue />`, `<LineChart />`, `<BarChart />`, etc.
+
+Key points:
+- All field names must be fully qualified: `orders.total_revenue`, not `total_revenue`
+- Each component references a query by name: `data={query_name}`
+- Consecutive `<BigValue>` components auto-group into a row
+- Use `<Grid cols="2">` to place charts side by side
+- Use `<DateRange>` and `<Dropdown>` for interactive filters
+
+Example structure:
+
+```markdown
+---
+title: Revenue Dashboard
+description: Key revenue metrics and trends
+---
+
+` ``query total_revenue
+measures: [orders.total_revenue]
+` ``
+
+` ``query order_count
+measures: [orders.count]
+` ``
+
+<BigValue data={total_revenue} value="orders.total_revenue" title="Revenue" fmt="eur2" />
+<BigValue data={order_count} value="orders.count" title="Orders" />
+
+## Trend
+
+` ``query monthly
+measures: [orders.total_revenue]
+timeDimension:
+  dimension: orders.created_at
+  granularity: month
+` ``
+
+<LineChart data={monthly} x="orders.created_at" y="orders.total_revenue" title="Monthly Revenue" yFmt="eur" />
+```
+
+Save the file (e.g., `dashboard.md`).
+
+## Phase 4: Preview Locally
+
+Preview the dashboard with live reload:
+
+```bash
+bon dashboard dev dashboard.md
+```
+
+This opens a browser with the rendered dashboard. Edit the `.md` file and
+the preview updates automatically. Queries run against the deployed
+semantic layer using the user's credentials.
+
+Requires `bon login` — no API key needed.
+
+## Phase 5: Deploy
+
+Deploy the dashboard to Bonnard:
+
+```bash
+bon dashboard deploy dashboard.md
+```
+
+This will:
+- Upload the markdown content
+- Assign a slug (derived from filename, or use `--slug`)
+- Extract the title from frontmatter
+- Print the URL where the dashboard is accessible
+
+Options:
+- `--slug <slug>` — custom URL slug (default: derived from filename)
+- `--title <title>` — override frontmatter title
+
+## Phase 6: View Live
+
+Open the deployed dashboard in the browser:
+
+```bash
+bon dashboard open dashboard
+```
+
+## Iteration
+
+To update, edit the `.md` file and redeploy:
+
+```bash
+bon dashboard deploy dashboard.md
+```
+
+Each deploy increments the version. Use `bon dashboard list` to see all
+deployed dashboards with their versions and URLs.
+
+To remove a dashboard:
+
+```bash
+bon dashboard remove dashboard
+```