@bonnard/sdk 0.1.2 → 0.1.3

package/dist/client.d.ts

@@ -1,14 +1,28 @@
 /**
  * Bonnard SDK — Client for querying semantic layer
  */
-import type { BonnardConfig, QueryOptions, QueryResult, SqlResult } from './types.js';
+import type { BonnardConfig, QueryOptions, QueryResult, SqlResult, CubeQuery, ExploreMeta, ExploreOptions } from './types.js';
 export declare function createClient(config: BonnardConfig): {
     /**
-     * Execute a JSON query against the semantic layer
+     * 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"`)
      */
     query<T = Record<string, unknown>>(options: QueryOptions): Promise<QueryResult<T>>;
+    /**
+     * Execute a raw Cube-native JSON query against the semantic layer.
+     * Use this when you already have a Cube API query object.
+     */
+    rawQuery<T = Record<string, unknown>>(cubeQuery: CubeQuery): Promise<QueryResult<T>>;
     /**
      * Execute a SQL query against the semantic layer
      */
     sql<T = Record<string, unknown>>(query: string): Promise<SqlResult<T>>;
+    /**
+     * Discover available cubes, measures, dimensions, and segments.
+     * By default returns only views (viewsOnly: true).
+     */
+    explore(options?: ExploreOptions): Promise<ExploreMeta>;
 };

package/dist/client.js

@@ -1,7 +1,7 @@
 /**
  * Bonnard SDK — Client for querying semantic layer
  */
-import { buildCubeQuery, simplifyResult } from './query.js';
+import { buildCubeQuery, simplifyResult, isCubeNativeFormat } 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.
@@ -22,14 +22,6 @@ function parseJwtExpiry(token) {
 }
 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;
@@ -40,14 +32,17 @@ export function createClient(config) {
             return config.apiKey;
         }
         // Token callback — cache and refresh
-        const now = Date.now();
-        if (cachedToken && cachedExpiry - REFRESH_BUFFER_MS > now) {
-            return cachedToken;
+        if (config.fetchToken) {
+            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;
         }
-        const token = await config.fetchToken();
-        cachedToken = token;
-        cachedExpiry = parseJwtExpiry(token);
-        return token;
+        throw new Error('BonnardConfig requires either apiKey or fetchToken');
     }
     async function request(endpoint, body) {
         const token = await getToken();
@@ -65,12 +60,82 @@ export function createClient(config) {
         }
         return res.json();
     }
+    async function requestGet(endpoint) {
+        const token = await getToken();
+        const res = await fetch(`${baseUrl}${endpoint}`, {
+            method: 'GET',
+            headers: {
+                'Authorization': `Bearer ${token}`,
+            },
+        });
+        if (!res.ok) {
+            const error = await res.json().catch(() => ({ error: res.statusText }));
+            throw new Error(error.error || 'Request failed');
+        }
+        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
+         * 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"`)
          */
         async query(options) {
-            const cubeQuery = buildCubeQuery(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 result = await request('/api/cube/query', { query: cubeQuery });
+            const simplifiedData = simplifyResult(result.data);
+            return { data: simplifiedData, annotation: result.annotation };
+        },
+        /**
+         * Execute a raw Cube-native JSON query against the semantic layer.
+         * Use this when you already have a Cube API query object.
+         */
+        async rawQuery(cubeQuery) {
             const result = await request('/api/cube/query', { query: cubeQuery });
             const simplifiedData = simplifyResult(result.data);
             return { data: simplifiedData, annotation: result.annotation };
@@ -81,5 +146,17 @@ export function createClient(config) {
         async sql(query) {
             return request('/api/cube/query', { sql: query });
         },
+        /**
+         * Discover available cubes, measures, dimensions, and segments.
+         * By default returns only views (viewsOnly: true).
+         */
+        async explore(options) {
+            const meta = await requestGet('/api/cube/meta');
+            const viewsOnly = options?.viewsOnly ?? true;
+            if (viewsOnly) {
+                return { cubes: meta.cubes.filter(c => c.type === 'view') };
+            }
+            return meta;
+        },
     };
 }

package/dist/index.d.ts

@@ -1,3 +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';
+export { buildCubeQuery, simplifyResult, isCubeNativeFormat } from './query.js';
+export type { BonnardConfig, QueryOptions, QueryResult, SqlResult, Filter, TimeDimension, InferQueryResult, CubeQuery, ExploreMeta, CubeMetaItem, CubeFieldMeta, CubeSegmentMeta, ExploreOptions, } from './types.js';

package/dist/index.js

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

package/dist/query.d.ts

@@ -2,6 +2,11 @@
  * Bonnard SDK — Pure query-building functions (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.

package/dist/query.js

@@ -1,6 +1,19 @@
 /**
  * Bonnard SDK — Pure query-building functions (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.

package/dist/types.d.ts

@@ -7,7 +7,7 @@ export interface BonnardConfig {
     baseUrl?: string;
 }
 export interface QueryOptions {
-    cube: string;
+    cube?: string;
     measures?: string[];
     dimensions?: string[];
     filters?: Filter[];
@@ -15,6 +15,24 @@ export interface QueryOptions {
     orderBy?: Record<string, 'asc' | 'desc'>;
     limit?: number;
 }
+export interface CubeQuery {
+    measures?: string[];
+    dimensions?: string[];
+    timeDimensions?: Array<{
+        dimension: string;
+        granularity?: 'day' | 'week' | 'month' | 'quarter' | 'year';
+        dateRange?: string | [string, string];
+    }>;
+    filters?: Array<{
+        member: string;
+        operator: string;
+        values?: (string | number)[];
+    }>;
+    segments?: string[];
+    order?: Record<string, 'asc' | 'desc'> | Array<[string, 'asc' | 'desc']>;
+    limit?: number;
+    offset?: number;
+}
 export interface Filter {
     dimension: string;
     operator: 'equals' | 'notEquals' | 'contains' | 'gt' | 'gte' | 'lt' | 'lte';
@@ -45,6 +63,34 @@ export interface SqlResult<T = Record<string, unknown>> {
         type: string;
     }>;
 }
+export interface ExploreMeta {
+    cubes: CubeMetaItem[];
+}
+export interface CubeMetaItem {
+    name: string;
+    title?: string;
+    description?: string;
+    type?: string;
+    measures: CubeFieldMeta[];
+    dimensions: CubeFieldMeta[];
+    segments: CubeSegmentMeta[];
+}
+export interface CubeFieldMeta {
+    name: string;
+    title?: string;
+    shortTitle?: string;
+    description?: string;
+    type: string;
+}
+export interface CubeSegmentMeta {
+    name: string;
+    title?: string;
+    shortTitle?: string;
+    description?: string;
+}
+export interface ExploreOptions {
+    viewsOnly?: boolean;
+}
 /** 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/package.json

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