@carto/api-client 0.0.1-1 → 0.0.30

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

@@ -4,20 +4,42 @@ import {
   VectorTableSourceOptions,
 } from '@deck.gl/carto';
 import {WidgetBaseSource, WidgetBaseSourceProps} from './widget-base-source.js';
-import {MapType} from '../constants.js';
-import {Source} from '../types.js';
+import {MapType} from '../constants-internal.js';
+import {ModelSource} from '../models/model.js';
 
 type LayerTableSourceOptions =
-  | VectorTableSourceOptions
-  | H3TableSourceOptions
-  | QuadbinTableSourceOptions;
+  | Omit<VectorTableSourceOptions, 'filters'>
+  | Omit<H3TableSourceOptions, 'filters'>
+  | Omit<QuadbinTableSourceOptions, 'filters'>;
 
+/**
+ * Source for Widget API requests on a data source defined as a table.
+ *
+ * Generally not intended to be constructed directly. Instead, call
+ * {@link vectorTableSource}, {@link h3TableSource}, or {@link quadbinTableSource},
+ * which can be shared with map layers. Sources contain a `widgetSource` property,
+ * for use by widget implementations.
+ *
+ * Example:
+ *
+ * ```javascript
+ * import { vectorTableSource } from '@carto/api-client';
+ *
+ * const data = vectorTableSource({
+ *   accessToken: '••••',
+ *   connectionName: 'carto_dw',
+ *   tableName: 'carto-demo-data.demo_tables.retail_stores'
+ * });
+ *
+ * const { widgetSource } = await data;
+ * ```
+ */
 export class WidgetTableSource extends WidgetBaseSource<
   LayerTableSourceOptions & WidgetBaseSourceProps
 > {
-  protected override getSource(owner: string): Source {
+  protected override getModelSource(owner: string): ModelSource {
     return {
-      ...super.getSource(owner),
+      ...super._getModelSource(owner),
       type: MapType.TABLE,
       data: this.props.tableName,
     };

package/src/sources/wrappers.ts

@@ -5,17 +5,19 @@ import {
   vectorQuerySource as _vectorQuerySource,
   quadbinTableSource as _quadbinTableSource,
   quadbinQuerySource as _quadbinQuerySource,
-  VectorTableSourceOptions,
-  VectorQuerySourceOptions,
-  H3TableSourceOptions,
-  H3QuerySourceOptions,
-  QuadbinQuerySourceOptions,
-  QuadbinTableSourceOptions,
+  VectorTableSourceOptions as _VectorTableSourceOptions,
+  VectorQuerySourceOptions as _VectorQuerySourceOptions,
+  H3TableSourceOptions as _H3TableSourceOptions,
+  H3QuerySourceOptions as _H3QuerySourceOptions,
+  QuadbinTableSourceOptions as _QuadbinTableSourceOptions,
+  QuadbinQuerySourceOptions as _QuadbinQuerySourceOptions,
 } from '@deck.gl/carto';
 import {WidgetBaseSourceProps} from './widget-base-source.js';
 import {WidgetQuerySource} from './widget-query-source.js';
 import {WidgetTableSource} from './widget-table-source.js';
 
+type WrappedSourceOptions<T> = Omit<T, 'filters'> & WidgetBaseSourceProps;
+
 /******************************************************************************
  * RESPONSE OBJECTS
  */
@@ -42,23 +44,29 @@ export type QuadbinQuerySourceResponse = WidgetQuerySourceResponse &
  * VECTOR SOURCES
  */
 
-/** Wrapper adding widget support to {@link _vectorTableSource}. */
+export type VectorTableSourceOptions =
+  WrappedSourceOptions<_VectorTableSourceOptions>;
+
+export type VectorQuerySourceOptions =
+  WrappedSourceOptions<_VectorQuerySourceOptions>;
+
+/** Wrapper adding Widget API support to [vectorTableSource](https://deck.gl/docs/api-reference/carto/data-sources). */
 export async function vectorTableSource(
-  props: VectorTableSourceOptions & WidgetBaseSourceProps
+  props: VectorTableSourceOptions
 ): Promise<VectorTableSourceResponse> {
-  const response = await _vectorTableSource(props);
+  const response = await _vectorTableSource(props as _VectorTableSourceOptions);
   return {...response, widgetSource: new WidgetTableSource(props)};
 }
 
-/** Wrapper adding widget support to {@link _vectorQuerySource}. */
+/** Wrapper adding Widget API support to [vectorQuerySource](https://deck.gl/docs/api-reference/carto/data-sources). */
 export async function vectorQuerySource(
-  props: VectorQuerySourceOptions & WidgetBaseSourceProps
+  props: VectorQuerySourceOptions
 ): Promise<VectorQuerySourceResponse> {
-  const response = await _vectorQuerySource(props);
+  const response = await _vectorQuerySource(props as _VectorQuerySourceOptions);
   return {...response, widgetSource: new WidgetQuerySource(props)};
 }
 
-/** Wrapper adding widget support to {@link _vectorTilesetSource}. */
+/** Wrapper adding Widget API support to [vectorTilesetSource](https://deck.gl/docs/api-reference/carto/data-sources). */
 export async function vectorTilesetSource() {
   throw new Error('not implemented');
 }
@@ -67,23 +75,26 @@ export async function vectorTilesetSource() {
  * H3 SOURCES
  */
 
-/** Wrapper adding widget support to {@link _h3TableSource}. */
+export type H3TableSourceOptions = WrappedSourceOptions<_H3TableSourceOptions>;
+export type H3QuerySourceOptions = WrappedSourceOptions<_H3QuerySourceOptions>;
+
+/** Wrapper adding Widget API support to [h3TableSource](https://deck.gl/docs/api-reference/carto/data-sources). */
 export async function h3TableSource(
-  props: H3TableSourceOptions & WidgetBaseSourceProps
+  props: H3TableSourceOptions
 ): Promise<H3TableSourceResponse> {
   const response = await _h3TableSource(props);
   return {...response, widgetSource: new WidgetTableSource(props)};
 }
 
-/** Wrapper adding widget support to {@link _h3QuerySource}. */
+/** Wrapper adding Widget API support to [h3QuerySource](https://deck.gl/docs/api-reference/carto/data-sources). */
 export async function h3QuerySource(
-  props: H3QuerySourceOptions & WidgetBaseSourceProps
+  props: H3QuerySourceOptions
 ): Promise<H3QuerySourceResponse> {
   const response = await _h3QuerySource(props);
   return {...response, widgetSource: new WidgetQuerySource(props)};
 }
 
-/** Wrapper adding widget support to {@link _h3TilesetSource}. */
+/** Wrapper adding Widget API support to [h3TilesetSource](https://deck.gl/docs/api-reference/carto/data-sources). */
 export async function h3TilesetSource() {
   throw new Error('not implemented');
 }
@@ -92,7 +103,13 @@ export async function h3TilesetSource() {
  * QUADBIN SOURCES
  */
 
-/** Wrapper adding widget support to {@link _quadbinTableSource}. */
+export type QuadbinTableSourceOptions =
+  WrappedSourceOptions<_QuadbinTableSourceOptions>;
+
+export type QuadbinQuerySourceOptions =
+  WrappedSourceOptions<_QuadbinQuerySourceOptions>;
+
+/** Wrapper adding Widget API support to [quadbinTableSource](https://deck.gl/docs/api-reference/carto/data-sources). */
 export async function quadbinTableSource(
   props: QuadbinTableSourceOptions & WidgetBaseSourceProps
 ): Promise<QuadbinTableSourceResponse> {
@@ -100,7 +117,7 @@ export async function quadbinTableSource(
   return {...response, widgetSource: new WidgetTableSource(props)};
 }
 
-/** Wrapper adding widget support to {@link _quadbinQuerySource}. */
+/** Wrapper adding Widget API support to [quadbinQuerySource](https://deck.gl/docs/api-reference/carto/data-sources). */
 export async function quadbinQuerySource(
   props: QuadbinQuerySourceOptions & WidgetBaseSourceProps
 ): Promise<QuadbinQuerySourceResponse> {
@@ -108,7 +125,7 @@ export async function quadbinQuerySource(
   return {...response, widgetSource: new WidgetQuerySource(props)};
 }
 
-/** Wrapper adding widget support to {@link _quadbinTilesetSource}. */
+/** Wrapper adding Widget API support to [quadbinTilesetSource](https://deck.gl/docs/api-reference/carto/data-sources). */
 export async function quadbinTilesetSource() {
   throw new Error('not implemented');
 }

package/src/types.ts

@@ -1,41 +1,12 @@
-import type {ApiVersion, MapType, FilterType} from './constants';
-
-/******************************************************************************
- * AUTHENTICATION
- */
-
-/** @internalRemarks Source: @carto/react-api */
-export type Credentials = {
-  apiVersion?: ApiVersion;
-  apiBaseUrl?: string;
-  geoColumn?: string;
-  accessToken: string;
-};
-
-/******************************************************************************
- * SOURCES
- */
-
-/** @internalRemarks Source: @carto/react-api */
-export type Source = {
-  type: MapType;
-  connection: string;
-  credentials: Credentials;
-  data: string;
-  geoColumn?: string;
-  queryParameters?: unknown[];
-  filters?: Record<string, Filter>;
-  filtersLogicalOperator?: 'and' | 'or';
-};
+import type {FilterType} from './constants';
 
 /******************************************************************************
  * AGGREGATION
  */
 
 /**
- * Enum for the different types of aggregations available for widgets
- * @enum {string}
- * @readonly
+ * Enum for the different types of aggregations available for widgets.
+ *
  * @internalRemarks Source: @carto/constants
  * @internalRemarks Converted from enum to type union, for improved declarative API.
  */
@@ -74,3 +45,24 @@ export type FilterLogicalOperator = 'and' | 'or';
 
 export type SortDirection = 'asc' | 'desc';
 export type SortColumnType = 'number' | 'string' | 'date';
+
+/******************************************************************************
+ * SQL QUERY PARAMETERS
+ */
+
+/** @internalRemarks Source: @deck.gl/carto */
+export type QueryParameterValue =
+  | string
+  | number
+  | boolean
+  | Array<QueryParameterValue>
+  | object;
+
+/** @internalRemarks Source: @deck.gl/carto */
+export type NamedQueryParameter = Record<string, QueryParameterValue>;
+
+/** @internalRemarks Source: @deck.gl/carto */
+export type PositionalQueryParameter = QueryParameterValue[];
+
+/** @internalRemarks Source: @deck.gl/carto */
+export type QueryParameters = NamedQueryParameter | PositionalQueryParameter;