@bonnard/sdk 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Bonnard (meal-inc)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+# @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({
+  cube: 'orders',
+  measures: ['revenue', 'count'],
+  dimensions: ['status'],
+});
+
+console.log(data);
+// [{ revenue: 45000, count: 120, 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({
+  cube: 'orders',
+  measures: ['revenue'],
+  timeDimension: {
+    dimension: '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<string>` | 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({
+  cube: 'orders',
+  measures: ['revenue', 'count'],
+  dimensions: ['product_category'],
+  filters: [
+    { dimension: 'status', operator: 'equals', values: ['completed'] },
+  ],
+  timeDimension: {
+    dimension: 'created_at',
+    granularity: 'month',
+    dateRange: ['2025-01-01', '2025-12-31'],
+  },
+  orderBy: { 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`
+);
+```
+
+## 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)
+

package/dist/client.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Bonnard SDK — Client for querying semantic layer
+ */
+import type { BonnardConfig, QueryOptions, QueryResult, SqlResult } from './types.js';
+export declare function createClient(config: BonnardConfig): {
+    /**
+     * Execute a JSON query against the semantic layer
+     */
+    query<T = Record<string, unknown>>(options: QueryOptions): Promise<QueryResult<T>>;
+    /**
+     * Execute a SQL query against the semantic layer
+     */
+    sql<T = Record<string, unknown>>(query: string): Promise<SqlResult<T>>;
+};

package/dist/client.js

@@ -0,0 +1,85 @@
+/**
+ * Bonnard SDK — Client for querying semantic layer
+ */
+import { buildCubeQuery, simplifyResult } from './query.js';
+/**
+ * Parse JWT expiry from the payload (base64url-decoded middle segment).
+ * Returns the `exp` claim as a millisecond timestamp, or 0 if unparseable.
+ */
+function parseJwtExpiry(token) {
+    try {
+        const parts = token.split('.');
+        if (parts.length !== 3)
+            return 0;
+        // base64url → base64 → decode
+        const payload = parts[1].replace(/-/g, '+').replace(/_/g, '/');
+        const json = JSON.parse(atob(payload));
+        return typeof json.exp === 'number' ? json.exp * 1000 : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+const REFRESH_BUFFER_MS = 60_000; // refresh 60s before expiry
+export function createClient(config) {
+    const hasApiKey = !!config.apiKey;
+    const hasFetchToken = !!config.fetchToken;
+    if (!hasApiKey && !hasFetchToken) {
+        throw new Error('BonnardConfig requires either apiKey or fetchToken');
+    }
+    if (hasApiKey && hasFetchToken) {
+        throw new Error('BonnardConfig requires either apiKey or fetchToken, not both');
+    }
+    const baseUrl = config.baseUrl || 'https://app.bonnard.dev';
+    // Token cache for fetchToken mode
+    let cachedToken = null;
+    let cachedExpiry = 0;
+    async function getToken() {
+        // Static API key — return directly
+        if (config.apiKey) {
+            return config.apiKey;
+        }
+        // Token callback — cache and refresh
+        const now = Date.now();
+        if (cachedToken && cachedExpiry - REFRESH_BUFFER_MS > now) {
+            return cachedToken;
+        }
+        const token = await config.fetchToken();
+        cachedToken = token;
+        cachedExpiry = parseJwtExpiry(token);
+        return token;
+    }
+    async function request(endpoint, body) {
+        const token = await getToken();
+        const res = await fetch(`${baseUrl}${endpoint}`, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${token}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const error = await res.json().catch(() => ({ error: res.statusText }));
+            throw new Error(error.error || 'Query failed');
+        }
+        return res.json();
+    }
+    return {
+        /**
+         * Execute a JSON query against the semantic layer
+         */
+        async query(options) {
+            const cubeQuery = buildCubeQuery(options);
+            const result = await request('/api/cube/query', { query: cubeQuery });
+            const simplifiedData = simplifyResult(result.data);
+            return { data: simplifiedData, annotation: result.annotation };
+        },
+        /**
+         * Execute a SQL query against the semantic layer
+         */
+        async sql(query) {
+            return request('/api/cube/query', { sql: query });
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createClient } from './client.js';
+export { buildCubeQuery, simplifyResult } from './query.js';
+export type { BonnardConfig, QueryOptions, QueryResult, SqlResult, Filter, TimeDimension, InferQueryResult, } from './types.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createClient } from './client.js';
+export { buildCubeQuery, simplifyResult } from './query.js';

package/dist/query.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Bonnard SDK — Pure query-building functions (zero IO)
+ */
+import type { QueryOptions } from './types.js';
+/**
+ * Convert SDK QueryOptions into a Cube-native query object.
+ * Handles cube-name prefixing for all field references.
+ */
+export declare function buildCubeQuery(options: QueryOptions): Record<string, unknown>;
+/**
+ * Simplify Cube response keys by removing the cube prefix.
+ * e.g. { "orders.revenue": 100 } → { "revenue": 100 }
+ */
+export declare function simplifyResult<T = Record<string, unknown>>(data: Record<string, unknown>[]): T[];

package/dist/query.js

@@ -0,0 +1,56 @@
+/**
+ * Bonnard SDK — Pure query-building functions (zero IO)
+ */
+/**
+ * Convert SDK QueryOptions into a Cube-native query object.
+ * Handles cube-name prefixing for all field references.
+ */
+export function buildCubeQuery(options) {
+    const cubeQuery = {};
+    if (options.measures) {
+        cubeQuery.measures = options.measures.map(m => m.includes('.') ? m : `${options.cube}.${m}`);
+    }
+    if (options.dimensions) {
+        cubeQuery.dimensions = options.dimensions.map(d => d.includes('.') ? d : `${options.cube}.${d}`);
+    }
+    if (options.filters) {
+        cubeQuery.filters = options.filters.map(f => ({
+            dimension: f.dimension.includes('.') ? f.dimension : `${options.cube}.${f.dimension}`,
+            operator: f.operator,
+            values: f.values,
+        }));
+    }
+    if (options.timeDimension) {
+        cubeQuery.timeDimensions = [{
+                dimension: options.timeDimension.dimension.includes('.')
+                    ? options.timeDimension.dimension
+                    : `${options.cube}.${options.timeDimension.dimension}`,
+                granularity: options.timeDimension.granularity,
+                dateRange: options.timeDimension.dateRange,
+            }];
+    }
+    if (options.orderBy) {
+        cubeQuery.order = Object.entries(options.orderBy).map(([key, dir]) => [
+            key.includes('.') ? key : `${options.cube}.${key}`,
+            dir,
+        ]);
+    }
+    if (options.limit) {
+        cubeQuery.limit = options.limit;
+    }
+    return cubeQuery;
+}
+/**
+ * Simplify Cube response keys by removing the cube prefix.
+ * e.g. { "orders.revenue": 100 } → { "revenue": 100 }
+ */
+export function simplifyResult(data) {
+    return data.map(row => {
+        const simplified = {};
+        for (const [key, value] of Object.entries(row)) {
+            const simpleName = key.includes('.') ? key.split('.').pop() : key;
+            simplified[simpleName] = value;
+        }
+        return simplified;
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Bonnard SDK — Shared types
+ */
+export interface BonnardConfig {
+    apiKey?: string;
+    fetchToken?: () => Promise<string>;
+    baseUrl?: string;
+}
+export interface QueryOptions {
+    cube: string;
+    measures?: string[];
+    dimensions?: string[];
+    filters?: Filter[];
+    timeDimension?: TimeDimension;
+    orderBy?: Record<string, 'asc' | 'desc'>;
+    limit?: number;
+}
+export interface Filter {
+    dimension: string;
+    operator: 'equals' | 'notEquals' | 'contains' | 'gt' | 'gte' | 'lt' | 'lte';
+    values: (string | number)[];
+}
+export interface TimeDimension {
+    dimension: string;
+    granularity?: 'day' | 'week' | 'month' | 'quarter' | 'year';
+    dateRange?: string | [string, string];
+}
+export interface QueryResult<T = Record<string, unknown>> {
+    data: T[];
+    annotation?: {
+        measures: Record<string, {
+            title: string;
+            type: string;
+        }>;
+        dimensions: Record<string, {
+            title: string;
+            type: string;
+        }>;
+    };
+}
+export interface SqlResult<T = Record<string, unknown>> {
+    data: T[];
+    schema?: Array<{
+        name: string;
+        type: string;
+    }>;
+}
+/** Type helper for defining cube schemas */
+export type InferQueryResult<C extends string, M extends string[], D extends string[]> = {
+    [K in M[number] | D[number]]: K extends M[number] ? number : string;
+};

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * Bonnard SDK — Shared types
+ */
+export {};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@bonnard/sdk",
+  "version": "0.1.2",
+  "description": "Bonnard SDK - query your semantic layer from any JavaScript or TypeScript app",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "^5.3.3"
+  },
+  "keywords": [
+    "bonnard",
+    "semantic-layer",
+    "analytics",
+    "mcp",
+    "cube",
+    "dashboard",
+    "metrics",
+    "ai"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/meal-inc/bonnard-sdk.git"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}