@bonnard/sdk 0.2.1 → 0.4.0

package/README.md

@@ -20,13 +20,12 @@ const bon = createClient({
 });
 
 const { data } = await bon.query({
-  cube: 'orders',
-  measures: ['revenue', 'count'],
-  dimensions: ['status'],
+  measures: ['orders.revenue', 'orders.count'],
+  dimensions: ['orders.status'],
 });
 
 console.log(data);
-// [{ revenue: 45000, count: 120, status: "completed" }, ...]
+// [{ "orders.revenue": 45000, "orders.count": 120, "orders.status": "completed" }, ...]
 ```
 
 ### With token exchange (multi-tenant)
@@ -59,10 +58,9 @@ const bon = createClient({
 });
 
 const { data } = await bon.query({
-  cube: 'orders',
-  measures: ['revenue'],
+  measures: ['orders.revenue'],
   timeDimension: {
-    dimension: 'created_at',
+    dimension: 'orders.created_at',
     granularity: 'month',
     dateRange: ['2025-01-01', '2025-12-31'],
   },
@@ -87,18 +85,17 @@ JSON query against the semantic layer.
 
 ```typescript
 const { data } = await bon.query({
-  cube: 'orders',
-  measures: ['revenue', 'count'],
-  dimensions: ['product_category'],
+  measures: ['orders.revenue', 'orders.count'],
+  dimensions: ['orders.product_category'],
   filters: [
-    { dimension: 'status', operator: 'equals', values: ['completed'] },
+    { dimension: 'orders.status', operator: 'equals', values: ['completed'] },
   ],
   timeDimension: {
-    dimension: 'created_at',
+    dimension: 'orders.created_at',
     granularity: 'month',
     dateRange: ['2025-01-01', '2025-12-31'],
   },
-  orderBy: { revenue: 'desc' },
+  orderBy: { 'orders.revenue': 'desc' },
   limit: 100,
 });
 ```

package/dist/client.d.ts

@@ -1,14 +1,11 @@
 /**
  * Bonnard SDK — Client for querying semantic layer
  */
-import type { BonnardConfig, QueryOptions, QueryResult, SqlResult, CubeQuery, ExploreMeta, ExploreOptions, DashboardResult, DashboardListResult } from './types.js';
+import type { BonnardConfig, QueryOptions, QueryResult, SqlResult, CubeQuery, ExploreMeta, ExploreOptions, DashboardResult, DashboardListResult, DocsOptions, DocsTopicListResult, DocsTopicResult } from './types.js';
 export declare function createClient(config: BonnardConfig): {
     /**
      * Execute a JSON query against the semantic layer.
-     *
-     * Supports two modes:
-     * - **Short names**: provide `cube` and use unqualified field names (e.g. `"revenue"`)
-     * - **Fully-qualified names**: omit `cube` and use dot notation (e.g. `"orders.revenue"`)
+     * All field names must be fully qualified (e.g. "orders.revenue").
      */
     query<T = Record<string, unknown>>(options: QueryOptions): Promise<QueryResult<T>>;
     /**
@@ -33,4 +30,11 @@ export declare function createClient(config: BonnardConfig): {
      * List all dashboards for the current organization.
      */
     listDashboards(): Promise<DashboardListResult>;
+    /**
+     * Access Bonnard documentation.
+     * - `docs()` — list all topics
+     * - `docs({ category: 'dashboards' })` — list topics in a category
+     * - `docs({ topic: 'dashboards.components' })` — get full markdown content
+     */
+    docs(options?: DocsOptions): Promise<DocsTopicListResult | DocsTopicResult>;
 };

package/dist/client.js

@@ -1,7 +1,7 @@
 /**
  * Bonnard SDK — Client for querying semantic layer
  */
-import { buildCubeQuery, simplifyResult, isCubeNativeFormat } from './query.js';
+import { toCubeQuery } 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.
@@ -74,62 +74,15 @@ export function createClient(config) {
         }
         return res.json();
     }
-    /**
-     * Build a Cube-native query from QueryOptions that already use fully-qualified names.
-     */
-    function buildNativeQuery(options) {
-        const cubeQuery = {};
-        if (options.measures) {
-            cubeQuery.measures = options.measures;
-        }
-        if (options.dimensions) {
-            cubeQuery.dimensions = options.dimensions;
-        }
-        if (options.filters) {
-            cubeQuery.filters = options.filters.map(f => ({
-                member: f.dimension,
-                operator: f.operator,
-                values: f.values,
-            }));
-        }
-        if (options.timeDimension) {
-            cubeQuery.timeDimensions = [{
-                    dimension: options.timeDimension.dimension,
-                    granularity: options.timeDimension.granularity,
-                    dateRange: options.timeDimension.dateRange,
-                }];
-        }
-        if (options.orderBy) {
-            cubeQuery.order = Object.entries(options.orderBy).map(([key, dir]) => [key, dir]);
-        }
-        if (options.limit) {
-            cubeQuery.limit = options.limit;
-        }
-        return cubeQuery;
-    }
     return {
         /**
          * Execute a JSON query against the semantic layer.
-         *
-         * Supports two modes:
-         * - **Short names**: provide `cube` and use unqualified field names (e.g. `"revenue"`)
-         * - **Fully-qualified names**: omit `cube` and use dot notation (e.g. `"orders.revenue"`)
+         * All field names must be fully qualified (e.g. "orders.revenue").
          */
         async query(options) {
-            let cubeQuery;
-            if (isCubeNativeFormat(options)) {
-                cubeQuery = buildNativeQuery(options);
-            }
-            else {
-                if (!options.cube) {
-                    throw new Error('QueryOptions requires "cube" when using short field names. ' +
-                        'Either set "cube" or use fully-qualified names (e.g. "orders.revenue").');
-                }
-                cubeQuery = buildCubeQuery(options);
-            }
+            const cubeQuery = toCubeQuery(options);
             const result = await request('/api/cube/query', { query: cubeQuery });
-            const simplifiedData = simplifyResult(result.data);
-            return { data: simplifiedData, annotation: result.annotation };
+            return { data: result.data, annotation: result.annotation };
         },
         /**
          * Execute a raw Cube-native JSON query against the semantic layer.
@@ -137,8 +90,7 @@ export function createClient(config) {
          */
         async rawQuery(cubeQuery) {
             const result = await request('/api/cube/query', { query: cubeQuery });
-            const simplifiedData = simplifyResult(result.data);
-            return { data: simplifiedData, annotation: result.annotation };
+            return { data: result.data, annotation: result.annotation };
         },
         /**
          * Execute a SQL query against the semantic layer
@@ -170,5 +122,20 @@ export function createClient(config) {
         async listDashboards() {
             return requestGet('/api/dashboards');
         },
+        /**
+         * Access Bonnard documentation.
+         * - `docs()` — list all topics
+         * - `docs({ category: 'dashboards' })` — list topics in a category
+         * - `docs({ topic: 'dashboards.components' })` — get full markdown content
+         */
+        async docs(options) {
+            const params = new URLSearchParams();
+            if (options?.topic)
+                params.set('topic', options.topic);
+            else if (options?.category)
+                params.set('category', options.category);
+            const qs = params.toString();
+            return requestGet(`/api/docs${qs ? `?${qs}` : ''}`);
+        },
     };
 }

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { createClient } from './client.js';
-export { buildCubeQuery, simplifyResult, isCubeNativeFormat } from './query.js';
-export type { BonnardConfig, QueryOptions, QueryResult, SqlResult, Filter, TimeDimension, InferQueryResult, CubeQuery, ExploreMeta, CubeMetaItem, CubeFieldMeta, CubeSegmentMeta, ExploreOptions, DashboardResult, DashboardListResult, } from './types.js';
+export { toCubeQuery } from './query.js';
+export type { BonnardConfig, QueryOptions, QueryResult, SqlResult, Filter, TimeDimension, InferQueryResult, CubeQuery, ExploreMeta, CubeMetaItem, CubeFieldMeta, CubeSegmentMeta, ExploreOptions, DashboardResult, DashboardListResult, DocsOptions, DocsTopicSummary, DocsTopicListResult, DocsTopicResult, } from './types.js';

package/dist/index.js

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

package/dist/query.d.ts

@@ -1,19 +1,9 @@
 /**
- * Bonnard SDK — Pure query-building functions (zero IO)
+ * Bonnard SDK — Query format conversion (zero IO)
  */
 import type { QueryOptions } from './types.js';
-/**
- * Detect whether a QueryOptions object uses Cube-native fully-qualified names
- * (i.e. "view.field" dot notation) rather than short names that need a cube prefix.
- */
-export declare function isCubeNativeFormat(options: QueryOptions): boolean;
 /**
  * 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 }
+ * All field names must be fully qualified (e.g. "orders.revenue").
  */
-export declare function simplifyResult<T = Record<string, unknown>>(data: Record<string, unknown>[]): T[];
+export declare function toCubeQuery(options: QueryOptions): Record<string, unknown>;

package/dist/query.js

@@ -1,69 +1,37 @@
 /**
- * Bonnard SDK — Pure query-building functions (zero IO)
+ * Bonnard SDK — Query format conversion (zero IO)
  */
-/**
- * Detect whether a QueryOptions object uses Cube-native fully-qualified names
- * (i.e. "view.field" dot notation) rather than short names that need a cube prefix.
- */
-export function isCubeNativeFormat(options) {
-    const fields = [
-        ...(options.measures ?? []),
-        ...(options.dimensions ?? []),
-        ...(options.filters?.map(f => f.dimension) ?? []),
-        ...(options.timeDimension ? [options.timeDimension.dimension] : []),
-    ];
-    return fields.some(f => f.includes('.'));
-}
 /**
  * Convert SDK QueryOptions into a Cube-native query object.
- * Handles cube-name prefixing for all field references.
+ * All field names must be fully qualified (e.g. "orders.revenue").
  */
-export function buildCubeQuery(options) {
+export function toCubeQuery(options) {
     const cubeQuery = {};
     if (options.measures) {
-        cubeQuery.measures = options.measures.map(m => m.includes('.') ? m : `${options.cube}.${m}`);
+        cubeQuery.measures = options.measures;
     }
     if (options.dimensions) {
-        cubeQuery.dimensions = options.dimensions.map(d => d.includes('.') ? d : `${options.cube}.${d}`);
+        cubeQuery.dimensions = options.dimensions;
     }
     if (options.filters) {
         cubeQuery.filters = options.filters.map(f => ({
-            dimension: f.dimension.includes('.') ? f.dimension : `${options.cube}.${f.dimension}`,
+            member: 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}`,
+                dimension: 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,
-        ]);
+        cubeQuery.order = Object.entries(options.orderBy).map(([key, dir]) => [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

@@ -7,7 +7,6 @@ export interface BonnardConfig {
     baseUrl?: string;
 }
 export interface QueryOptions {
-    cube?: string;
     measures?: string[];
     dimensions?: string[];
     filters?: Filter[];
@@ -115,3 +114,23 @@ export interface DashboardListResult {
         updated_at: string;
     }>;
 }
+export interface DocsOptions {
+    topic?: string;
+    category?: string;
+}
+export interface DocsTopicSummary {
+    id: string;
+    title: string;
+    description: string | null;
+    category: string;
+}
+export interface DocsTopicListResult {
+    topics: DocsTopicSummary[];
+}
+export interface DocsTopicResult {
+    topic: {
+        id: string;
+        title: string;
+        content: string;
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonnard/sdk",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Bonnard SDK - query your semantic layer from any JavaScript or TypeScript app",
   "type": "module",
   "main": "dist/index.js",