@carto/api-client 0.0.1-0 → 0.0.1-2

package/src/models/model.ts

@@ -1,13 +1,18 @@
-import {getClient} from '../client';
-import {ApiVersion, MapType} from '../constants';
+import {getClient} from '../client.js';
 import {
+  ApiVersion,
   DEFAULT_GEO_COLUMN,
-  REQUEST_GET_MAX_URL_LENGTH,
-} from '../constants-internal';
-import {Source, SpatialFilter} from '../types';
-import {$TODO} from '../types-internal';
-import {assert} from '../utils';
-import {ModelRequestOptions, checkCredentials, makeCall} from './common';
+  MapType,
+} from '../constants-internal.js';
+import {
+  Filter,
+  FilterLogicalOperator,
+  QueryParameters,
+  SpatialFilter,
+} from '../types.js';
+import {$TODO} from '../types-internal.js';
+import {assert} from '../utils.js';
+import {ModelRequestOptions, makeCall} from './common.js';
 
 /** @internalRemarks Source: @carto/react-api */
 const AVAILABLE_MODELS = [
@@ -22,15 +27,32 @@ const AVAILABLE_MODELS = [
 
 export type Model = (typeof AVAILABLE_MODELS)[number];
 
+export interface ModelSource {
+  type: MapType;
+  apiVersion: ApiVersion;
+  apiBaseUrl: string;
+  accessToken: string;
+  clientId: string;
+  connectionName: string;
+  data: string;
+  filters?: Record<string, Filter>;
+  filtersLogicalOperator?: FilterLogicalOperator;
+  geoColumn?: string;
+  spatialFilter?: SpatialFilter;
+  queryParameters?: QueryParameters;
+}
+
+const {V3} = ApiVersion;
+const REQUEST_GET_MAX_URL_LENGTH = 2048;
+
 /**
  * Execute a SQL model request.
  * @internalRemarks Source: @carto/react-api
  */
 export function executeModel(props: {
   model: Model;
-  source: Source;
+  source: ModelSource;
   params: Record<string, unknown>;
-  spatialFilter?: SpatialFilter;
   opts?: Partial<ModelRequestOptions>;
 }) {
   assert(props.source, 'executeModel: missing source');
@@ -38,28 +60,23 @@ export function executeModel(props: {
   assert(props.params, 'executeModel: missing params');
 
   assert(
-    AVAILABLE_MODELS.indexOf(props.model) !== -1,
+    AVAILABLE_MODELS.includes(props.model),
     `executeModel: model provided isn't valid. Available models: ${AVAILABLE_MODELS.join(
       ', '
     )}`
   );
 
-  const {source, model, params, spatialFilter, opts} = props;
+  const {model, source, params, opts} = props;
+  const {type, apiVersion, apiBaseUrl, accessToken, connectionName} = source;
 
-  checkCredentials(source.credentials);
-
-  assert(
-    source.credentials.apiVersion === ApiVersion.V3,
-    'SQL Model API is a feature only available in CARTO 3.'
-  );
-  assert(
-    source.type !== MapType.TILESET,
-    'executeModel: Tileset not supported'
-  );
+  assert(apiBaseUrl, 'executeModel: missing apiBaseUrl');
+  assert(accessToken, 'executeModel: missing accessToken');
+  assert(apiVersion === V3, 'executeModel: SQL Model API requires CARTO 3+');
+  assert(type !== MapType.TILESET, 'executeModel: Tilesets not supported');
 
-  let url = `${source.credentials.apiBaseUrl}/v3/sql/${source.connection}/model/${model}`;
+  let url = `${apiBaseUrl}/v3/sql/${connectionName}/model/${model}`;
 
-  const {filters, filtersLogicalOperator = 'and', data, type} = source;
+  const {filters, filtersLogicalOperator = 'and', data} = source;
   const queryParameters = source.queryParameters
     ? JSON.stringify(source.queryParameters)
     : '';
@@ -75,10 +92,10 @@ export function executeModel(props: {
   };
 
   // API supports multiple filters, we apply it only to geoColumn
-  const spatialFilters = spatialFilter
+  const spatialFilters = source.spatialFilter
     ? {
         [source.geoColumn ? source.geoColumn : DEFAULT_GEO_COLUMN]:
-          spatialFilter,
+          source.spatialFilter,
       }
     : undefined;
 
@@ -102,7 +119,7 @@ export function executeModel(props: {
   }
   return makeCall({
     url,
-    credentials: source.credentials,
+    accessToken: source.accessToken,
     opts: {
       ...opts,
       method: isGet ? 'GET' : 'POST',

package/src/sources/types.ts

@@ -1,3 +1,4 @@
+import {GroupDateType} from '../constants';
 import {
   AggregationType,
   SortColumnType,
@@ -9,28 +10,48 @@ import {
  * WIDGET API REQUESTS
  */
 
+/** Common options for {@link WidgetBaseSource} requests. */
 interface BaseRequestOptions {
   spatialFilter?: SpatialFilter;
   abortController?: AbortController;
   filterOwner?: string;
 }
 
+/** Options for {@link WidgetBaseSource#getCategories}. */
+export interface CategoryRequestOptions extends BaseRequestOptions {
+  column: string;
+  operation?: AggregationType;
+  operationColumn?: string;
+}
+
+/** Options for {@link WidgetBaseSource#getFormula}. */
 export interface FormulaRequestOptions extends BaseRequestOptions {
   column: string;
   operation?: AggregationType;
   operationExp?: string;
 }
 
-export interface CategoryRequestOptions extends BaseRequestOptions {
+/** Options for {@link WidgetBaseSource#getHistogram}. */
+export interface HistogramRequestOptions extends BaseRequestOptions {
   column: string;
+  ticks: number[];
   operation?: AggregationType;
-  operationColumn?: string;
 }
 
+/** Options for {@link WidgetBaseSource#getRange}. */
 export interface RangeRequestOptions extends BaseRequestOptions {
   column: string;
 }
 
+/** Options for {@link WidgetBaseSource#getScatter}. */
+export interface ScatterRequestOptions extends BaseRequestOptions {
+  xAxisColumn: string;
+  xAxisJoinOperation?: AggregationType;
+  yAxisColumn: string;
+  yAxisJoinOperation?: AggregationType;
+}
+
+/** Options for {@link WidgetBaseSource#getTable}. */
 export interface TableRequestOptions extends BaseRequestOptions {
   columns: string[];
   sortBy?: string;
@@ -40,16 +61,10 @@ export interface TableRequestOptions extends BaseRequestOptions {
   rowsPerPage?: number;
 }
 
-export interface ScatterRequestOptions extends BaseRequestOptions {
-  xAxisColumn: string;
-  xAxisJoinOperation?: AggregationType;
-  yAxisColumn: string;
-  yAxisJoinOperation?: AggregationType;
-}
-
+/** Options for {@link WidgetBaseSource#getTimeSeries}. */
 export interface TimeSeriesRequestOptions extends BaseRequestOptions {
   column: string;
-  stepSize?: number;
+  stepSize?: GroupDateType;
   stepMultiplier?: number;
   operation?: AggregationType;
   operationColumn?: string;
@@ -59,32 +74,33 @@ export interface TimeSeriesRequestOptions extends BaseRequestOptions {
   splitByCategoryValues?: string[];
 }
 
-export interface HistogramRequestOptions extends BaseRequestOptions {
-  column: string;
-  ticks: number[];
-  operation?: AggregationType;
-}
-
 /******************************************************************************
  * WIDGET API RESPONSES
  */
 
+/** Response from {@link WidgetBaseSource#getFormula}. */
 export type FormulaResponse = {value: number};
 
+/** Response from {@link WidgetBaseSource#getCategories}. */
 export type CategoryResponse = {name: string; value: number}[];
 
+/** Response from {@link WidgetBaseSource#getRange}. */
 export type RangeResponse = {min: number; max: number};
 
+/** Response from {@link WidgetBaseSource#getTable}. */
 export type TableResponse = {
   totalCount: number;
   rows: Record<string, number | string>[];
 };
 
+/** Response from {@link WidgetBaseSource#getScatter}. */
 export type ScatterResponse = [number, number][];
 
+/** Response from {@link WidgetBaseSource#getTimeSeries}. */
 export type TimeSeriesResponse = {
   rows: {name: string; value: number}[];
   categories: string[];
 };
 
+/** Response from {@link WidgetBaseSource#getHistogram}. */
 export type HistogramResponse = number[];

package/src/sources/widget-base-source.ts

@@ -15,61 +15,107 @@ import {
   TimeSeriesRequestOptions,
   TimeSeriesResponse,
 } from './types.js';
-import {Source, FilterLogicalOperator, Credentials, Filter} from '../types.js';
+import {FilterLogicalOperator, Filter} from '../types.js';
 import {SourceOptions} from '@deck.gl/carto';
 import {getApplicableFilters, normalizeObjectKeys} from '../utils.js';
-import {ApiVersion, MapType} from '../constants.js';
 import {
   DEFAULT_API_BASE_URL,
   DEFAULT_GEO_COLUMN,
+  ApiVersion,
 } from '../constants-internal.js';
 import {getClient} from '../client.js';
-import {$TODO} from '../types-internal.js';
+import {ModelSource} from '../models/model.js';
 
-/**
- * TODO(cleanup): Consolidate {@link SourceOptions} and {@link Source}.
- */
-export interface WidgetBaseSourceProps extends SourceOptions, Credentials {
-  type?: MapType;
+export interface WidgetBaseSourceProps extends Omit<SourceOptions, 'filters'> {
+  apiVersion?: ApiVersion;
+  geoColumn?: string;
   filters?: Record<string, Filter>;
   filtersLogicalOperator?: FilterLogicalOperator;
-  queryParameters?: unknown[];
-  provider?: string;
 }
 
 export type WidgetSource = WidgetBaseSource<WidgetBaseSourceProps>;
 
-export class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
+/**
+ * Source for Widget API requests on a data source defined by a SQL query.
+ *
+ * Abstract class. Use {@link WidgetQuerySource} or {@link WidgetTableSource}.
+ */
+export abstract class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
   readonly props: Props;
-  readonly credentials: Required<Credentials> & {clientId: string};
-  readonly connectionName: string;
 
   static defaultProps: Partial<WidgetBaseSourceProps> = {
+    apiVersion: ApiVersion.V3,
+    apiBaseUrl: DEFAULT_API_BASE_URL,
+    clientId: getClient(),
     filters: {},
     filtersLogicalOperator: 'and',
+    geoColumn: DEFAULT_GEO_COLUMN,
   };
 
   constructor(props: Props) {
     this.props = {...WidgetBaseSource.defaultProps, ...props};
-    this.connectionName = props.connectionName;
-    this.credentials = {
-      apiVersion: props.apiVersion || ApiVersion.V3,
-      apiBaseUrl: props.apiBaseUrl || DEFAULT_API_BASE_URL,
-      clientId: props.clientId || getClient(),
-      accessToken: props.accessToken,
-      geoColumn: props.geoColumn || DEFAULT_GEO_COLUMN,
-    };
   }
 
-  protected getSource(owner?: string): Source {
+  /**
+   * Subclasses of {@link WidgetBaseSource} must implement this method, calling
+   * {@link WidgetBaseSource.prototype._getModelSource} for common source
+   * properties, and adding additional required properties including 'type' and
+   * 'data'.
+   */
+  protected abstract getModelSource(owner: string | undefined): ModelSource;
+
+  protected _getModelSource(
+    owner?: string
+  ): Omit<ModelSource, 'type' | 'data'> {
+    const props = this.props;
     return {
-      ...(this.props as $TODO),
-      credentials: this.credentials,
-      connection: this.connectionName,
-      filters: getApplicableFilters(owner, this.props.filters),
+      apiVersion: props.apiVersion as ApiVersion,
+      apiBaseUrl: props.apiBaseUrl as string,
+      clientId: props.clientId as string,
+      accessToken: props.accessToken,
+      connectionName: props.connectionName,
+      filters: getApplicableFilters(owner, props.filters),
+      filtersLogicalOperator: props.filtersLogicalOperator,
+      geoColumn: props.geoColumn,
     };
   }
 
+  /****************************************************************************
+   * CATEGORIES
+   */
+
+  /**
+   * Returns a list of labeled datapoints for categorical data. Suitable for
+   * charts including grouped bar charts, pie charts, and tree charts.
+   */
+  async getCategories(
+    props: CategoryRequestOptions
+  ): Promise<CategoryResponse> {
+    const {filterOwner, spatialFilter, abortController, ...params} = props;
+    const {column, operation, operationColumn} = params;
+
+    type CategoriesModelResponse = {rows: {name: string; value: number}[]};
+
+    return executeModel({
+      model: 'category',
+      source: {...this.getModelSource(filterOwner), spatialFilter},
+      params: {
+        column,
+        operation,
+        operationColumn: operationColumn || column,
+      },
+      opts: {abortController},
+    }).then((res: CategoriesModelResponse) => normalizeObjectKeys(res.rows));
+  }
+
+  /****************************************************************************
+   * FORMULA
+   */
+
+  /**
+   * Returns a scalar numerical statistic over all matching data. Suitable
+   * for 'headline' or 'scorecard' figures such as counts and sums.
+   */
   async getFormula(props: FormulaRequestOptions): Promise<FormulaResponse> {
     const {
       filterOwner,
@@ -84,34 +130,57 @@ export class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
 
     return executeModel({
       model: 'formula',
-      source: this.getSource(filterOwner),
-      spatialFilter,
+      source: {...this.getModelSource(filterOwner), spatialFilter},
       params: {column: column ?? '*', operation, operationExp},
       opts: {abortController},
     }).then((res: FormulaModelResponse) => normalizeObjectKeys(res.rows[0]));
   }
 
-  async getCategories(
-    props: CategoryRequestOptions
-  ): Promise<CategoryResponse> {
+  /****************************************************************************
+   * HISTOGRAM
+   */
+
+  /**
+   * Returns a list of labeled datapoints for 'bins' of data defined as ticks
+   * over a numerical range. Suitable for histogram charts.
+   */
+  async getHistogram(
+    props: HistogramRequestOptions
+  ): Promise<HistogramResponse> {
     const {filterOwner, spatialFilter, abortController, ...params} = props;
-    const {column, operation, operationColumn} = params;
+    const {column, operation, ticks} = params;
 
-    type CategoriesModelResponse = {rows: {name: string; value: number}[]};
+    type HistogramModelResponse = {rows: {tick: number; value: number}[]};
 
-    return executeModel({
-      model: 'category',
-      source: this.getSource(filterOwner),
-      spatialFilter,
-      params: {
-        column,
-        operation,
-        operationColumn: operationColumn || column,
-      },
+    const data = await executeModel({
+      model: 'histogram',
+      source: {...this.getModelSource(filterOwner), spatialFilter},
+      params: {column, operation, ticks},
       opts: {abortController},
-    }).then((res: CategoriesModelResponse) => normalizeObjectKeys(res.rows));
+    }).then((res: HistogramModelResponse) => normalizeObjectKeys(res.rows));
+
+    if (data.length) {
+      // Given N ticks the API returns up to N+1 bins, omitting any empty bins. Bins
+      // include 1 bin below the lowest tick, N-1 between ticks, and 1 bin above the highest tick.
+      const result = Array(ticks.length + 1).fill(0);
+      data.forEach(
+        ({tick, value}: {tick: number; value: number}) => (result[tick] = value)
+      );
+      return result;
+    }
+
+    return [];
   }
 
+  /****************************************************************************
+   * RANGE
+   */
+
+  /**
+   * Returns a range (min and max) for a numerical column of matching rows.
+   * Suitable for displaying certain 'headline' or 'scorecard' statistics,
+   * or rendering a range slider UI for filtering.
+   */
   async getRange(props: RangeRequestOptions): Promise<RangeResponse> {
     const {filterOwner, spatialFilter, abortController, ...params} = props;
     const {column} = params;
@@ -120,40 +189,20 @@ export class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
 
     return executeModel({
       model: 'range',
-      source: this.getSource(filterOwner),
-      spatialFilter,
+      source: {...this.getModelSource(filterOwner), spatialFilter},
       params: {column},
       opts: {abortController},
     }).then((res: RangeModelResponse) => normalizeObjectKeys(res.rows[0]));
   }
 
-  async getTable(props: TableRequestOptions): Promise<TableResponse> {
-    const {filterOwner, spatialFilter, abortController, ...params} = props;
-    const {columns, sortBy, sortDirection, page = 0, rowsPerPage = 10} = params;
-
-    type TableModelResponse = {
-      rows: Record<string, number | string>[];
-      metadata: {total: number};
-    };
-
-    return executeModel({
-      model: 'table',
-      source: this.getSource(filterOwner),
-      spatialFilter,
-      params: {
-        column: columns,
-        sortBy,
-        sortDirection,
-        limit: rowsPerPage,
-        offset: page * rowsPerPage,
-      },
-      opts: {abortController},
-    }).then((res: TableModelResponse) => ({
-      rows: normalizeObjectKeys(res.rows),
-      totalCount: res.metadata.total,
-    }));
-  }
+  /****************************************************************************
+   * SCATTER
+   */
 
+  /**
+   * Returns a list of bivariate datapoints defined as numerical 'x' and 'y'
+   * values. Suitable for rendering scatter plots.
+   */
   async getScatter(props: ScatterRequestOptions): Promise<ScatterResponse> {
     const {filterOwner, spatialFilter, abortController, ...params} = props;
     const {xAxisColumn, xAxisJoinOperation, yAxisColumn, yAxisJoinOperation} =
@@ -166,8 +215,7 @@ export class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
 
     return executeModel({
       model: 'scatterplot',
-      source: this.getSource(filterOwner),
-      spatialFilter,
+      source: {...this.getModelSource(filterOwner), spatialFilter},
       params: {
         xAxisColumn,
         xAxisJoinOperation,
@@ -181,6 +229,48 @@ export class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
       .then((res) => res.map(({x, y}: {x: number; y: number}) => [x, y]));
   }
 
+  /****************************************************************************
+   * TABLE
+   */
+
+  /**
+   * Returns a list of arbitrary data rows, with support for pagination and
+   * sorting. Suitable for displaying tables and lists.
+   */
+  async getTable(props: TableRequestOptions): Promise<TableResponse> {
+    const {filterOwner, spatialFilter, abortController, ...params} = props;
+    const {columns, sortBy, sortDirection, page = 0, rowsPerPage = 10} = params;
+
+    type TableModelResponse = {
+      rows: Record<string, number | string>[];
+      metadata: {total: number};
+    };
+
+    return executeModel({
+      model: 'table',
+      source: {...this.getModelSource(filterOwner), spatialFilter},
+      params: {
+        column: columns,
+        sortBy,
+        sortDirection,
+        limit: rowsPerPage,
+        offset: page * rowsPerPage,
+      },
+      opts: {abortController},
+    }).then((res: TableModelResponse) => ({
+      rows: normalizeObjectKeys(res.rows),
+      totalCount: res.metadata.total,
+    }));
+  }
+
+  /****************************************************************************
+   * TIME SERIES
+   */
+
+  /**
+   * Returns a series of labeled numerical values, grouped into equally-sized
+   * time intervals. Suitable for rendering time series charts.
+   */
   async getTimeSeries(
     props: TimeSeriesRequestOptions
   ): Promise<TimeSeriesResponse> {
@@ -204,8 +294,7 @@ export class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
 
     return executeModel({
       model: 'timeseries',
-      source: this.getSource(filterOwner),
-      spatialFilter,
+      source: {...this.getModelSource(filterOwner), spatialFilter},
       params: {
         column,
         stepSize,
@@ -223,33 +312,4 @@ export class WidgetBaseSource<Props extends WidgetBaseSourceProps> {
       categories: res.metadata?.categories,
     }));
   }
-
-  async getHistogram(
-    props: HistogramRequestOptions
-  ): Promise<HistogramResponse> {
-    const {filterOwner, spatialFilter, abortController, ...params} = props;
-    const {column, operation, ticks} = params;
-
-    type HistogramModelResponse = {rows: {tick: number; value: number}[]};
-
-    const data = await executeModel({
-      model: 'histogram',
-      source: this.getSource(filterOwner),
-      spatialFilter,
-      params: {column, operation, ticks},
-      opts: {abortController},
-    }).then((res: HistogramModelResponse) => normalizeObjectKeys(res.rows));
-
-    if (data.length) {
-      // Given N ticks the API returns up to N+1 bins, omitting any empty bins. Bins
-      // include 1 bin below the lowest tick, N-1 between ticks, and 1 bin above the highest tick.
-      const result = Array(ticks.length + 1).fill(0);
-      data.forEach(
-        ({tick, value}: {tick: number; value: number}) => (result[tick] = value)
-      );
-      return result;
-    }
-
-    return [];
-  }
 }

package/src/sources/widget-query-source.ts

@@ -3,23 +3,46 @@ import {
   QuadbinQuerySourceOptions,
   VectorQuerySourceOptions,
 } from '@deck.gl/carto';
-import {MapType} from '../constants.js';
+import {MapType} from '../constants-internal.js';
 import {WidgetBaseSource, WidgetBaseSourceProps} from './widget-base-source.js';
-import {Source} from '../types.js';
+import {ModelSource} from '../models/model.js';
 
 type LayerQuerySourceOptions =
-  | VectorQuerySourceOptions
-  | H3QuerySourceOptions
-  | QuadbinQuerySourceOptions;
+  | Omit<VectorQuerySourceOptions, 'filters'>
+  | Omit<H3QuerySourceOptions, 'filters'>
+  | Omit<QuadbinQuerySourceOptions, 'filters'>;
 
+/**
+ * Source for Widget API requests on a data source defined by a SQL query.
+ *
+ * Generally not intended to be constructed directly. Instead, call
+ * {@link vectorQuerySource}, {@link h3QuerySource}, or {@link quadbinQuerySource},
+ * which can be shared with map layers. Sources contain a `widgetSource` property,
+ * for use by widget implementations.
+ *
+ * Example:
+ *
+ * ```javascript
+ * import { vectorQuerySource } from '@carto/api-client';
+ *
+ * const data = vectorQuerySource({
+ *   accessToken: '••••',
+ *   connectionName: 'carto_dw',
+ *   sqlQuery: 'SELECT * FROM carto-demo-data.demo_tables.retail_stores'
+ * });
+ *
+ * const { widgetSource } = await data;
+ * ```
+ */
 export class WidgetQuerySource extends WidgetBaseSource<
   LayerQuerySourceOptions & WidgetBaseSourceProps
 > {
-  protected override getSource(owner: string): Source {
+  protected override getModelSource(owner: string): ModelSource {
     return {
-      ...super.getSource(owner),
+      ...super._getModelSource(owner),
       type: MapType.QUERY,
       data: this.props.sqlQuery,
+      queryParameters: this.props.queryParameters,
     };
   }
 }