@carto/api-client 0.3.0 → 0.4.0-alpha.0

package/src/api/query.ts

@@ -0,0 +1,56 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {SOURCE_DEFAULTS} from '../sources/index';
+import type {
+  SourceOptions,
+  QuerySourceOptions,
+  QueryResult,
+} from '../sources/types';
+import {buildQueryUrl} from './endpoints';
+import {requestWithParameters} from './request-with-parameters';
+import {APIErrorContext} from './types';
+
+export type QueryOptions = SourceOptions &
+  Omit<QuerySourceOptions, 'spatialDataColumn'>;
+type UrlParameters = {q: string; queryParameters?: string};
+
+export const query = async function (
+  options: QueryOptions
+): Promise<QueryResult> {
+  const {
+    apiBaseUrl = SOURCE_DEFAULTS.apiBaseUrl,
+    clientId = SOURCE_DEFAULTS.clientId,
+    maxLengthURL = SOURCE_DEFAULTS.maxLengthURL,
+    connectionName,
+    sqlQuery,
+    queryParameters,
+  } = options;
+  const urlParameters: UrlParameters = {q: sqlQuery};
+
+  if (queryParameters) {
+    urlParameters.queryParameters = JSON.stringify(queryParameters);
+  }
+
+  const baseUrl = buildQueryUrl({apiBaseUrl, connectionName});
+  const headers = {
+    Authorization: `Bearer ${options.accessToken}`,
+    ...options.headers,
+  };
+  const parameters = {client: clientId, ...urlParameters};
+
+  const errorContext: APIErrorContext = {
+    requestType: 'SQL',
+    connection: options.connectionName,
+    type: 'query',
+    source: JSON.stringify(parameters, undefined, 2),
+  };
+  return await requestWithParameters<QueryResult>({
+    baseUrl,
+    parameters,
+    headers,
+    errorContext,
+    maxLengthURL,
+  });
+};

package/src/api/request-with-parameters.ts

@@ -0,0 +1,139 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {isPureObject} from '../utils';
+import {CartoAPIError} from './carto-api-error';
+import type {APIErrorContext} from './types';
+import {
+  DEFAULT_CLIENT,
+  DEFAULT_MAX_LENGTH_URL,
+  V3_MINOR_VERSION,
+} from '../constants';
+
+const DEFAULT_HEADERS = {
+  Accept: 'application/json',
+  'Content-Type': 'application/json',
+};
+
+const REQUEST_CACHE = new Map<string, Promise<unknown>>();
+
+export async function requestWithParameters<T = any>({
+  baseUrl,
+  parameters = {},
+  headers: customHeaders = {},
+  errorContext,
+  maxLengthURL = DEFAULT_MAX_LENGTH_URL,
+}: {
+  baseUrl: string;
+  parameters?: Record<string, unknown>;
+  headers?: Record<string, string>;
+  errorContext: APIErrorContext;
+  maxLengthURL?: number;
+}): Promise<T> {
+  // Parameters added to all requests issued with `requestWithParameters()`.
+  // These parameters override parameters already in the base URL, but not
+  // user-provided parameters.
+  parameters = {
+    v: V3_MINOR_VERSION,
+    clientId: DEFAULT_CLIENT,
+    ...(typeof deck !== 'undefined' &&
+      deck.VERSION && {deckglVersion: deck.VERSION}),
+    ...parameters,
+  };
+
+  baseUrl = excludeURLParameters(baseUrl, Object.keys(parameters));
+  const key = createCacheKey(baseUrl, parameters, customHeaders);
+  if (REQUEST_CACHE.has(key)) {
+    return REQUEST_CACHE.get(key) as Promise<T>;
+  }
+
+  const url = createURLWithParameters(baseUrl, parameters);
+  const headers = {...DEFAULT_HEADERS, ...customHeaders};
+
+  /* global fetch */
+  const fetchPromise =
+    url.length > maxLengthURL
+      ? fetch(baseUrl, {
+          method: 'POST',
+          body: JSON.stringify(parameters),
+          headers,
+        })
+      : fetch(url, {headers});
+
+  let response: Response | undefined;
+  let responseJson: unknown;
+  const jsonPromise: Promise<T> = fetchPromise
+    .then((_response: Response) => {
+      response = _response;
+      return response.json();
+    })
+    .then((json: any) => {
+      responseJson = json;
+      if (!response || !response.ok) {
+        throw new Error(json.error);
+      }
+      return json;
+    })
+    .catch((error: Error) => {
+      REQUEST_CACHE.delete(key);
+      throw new CartoAPIError(error, errorContext, response, responseJson);
+    });
+
+  REQUEST_CACHE.set(key, jsonPromise);
+  return jsonPromise;
+}
+
+function createCacheKey(
+  baseUrl: string,
+  parameters: Record<string, unknown>,
+  headers: Record<string, string>
+): string {
+  const parameterEntries = Object.entries(parameters).sort(([a], [b]) =>
+    a > b ? 1 : -1
+  );
+  const headerEntries = Object.entries(headers).sort(([a], [b]) =>
+    a > b ? 1 : -1
+  );
+  return JSON.stringify({
+    baseUrl,
+    parameters: parameterEntries,
+    headers: headerEntries,
+  });
+}
+
+/**
+ * Appends query string parameters to a URL. Existing URL parameters are kept,
+ * unless there is a conflict, in which case the new parameters override
+ * those already in the URL.
+ */
+function createURLWithParameters(
+  baseUrlString: string,
+  parameters: Record<string, unknown>
+): string {
+  const baseUrl = new URL(baseUrlString);
+  for (const [key, value] of Object.entries(parameters)) {
+    if (isPureObject(value) || Array.isArray(value)) {
+      baseUrl.searchParams.set(key, JSON.stringify(value));
+    } else {
+      baseUrl.searchParams.set(
+        key,
+        (value as string | boolean | number).toString()
+      );
+    }
+  }
+  return baseUrl.toString();
+}
+
+/**
+ * Deletes query string parameters from a URL.
+ */
+function excludeURLParameters(baseUrlString: string, parameters: string[]) {
+  const baseUrl = new URL(baseUrlString);
+  for (const param of parameters) {
+    if (baseUrl.searchParams.has(param)) {
+      baseUrl.searchParams.delete(param);
+    }
+  }
+  return baseUrl.toString();
+}

package/src/api/types.ts

@@ -0,0 +1,301 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export type Format = 'json' | 'geojson' | 'tilejson';
+export type MapType = 'boundary' | 'query' | 'table' | 'tileset' | 'raster';
+export type RequestType =
+  | 'Map data'
+  | 'Map instantiation'
+  | 'Public map'
+  | 'Tile stats'
+  | 'SQL'
+  | 'Basemap style';
+export type ScaleType =
+  | 'linear'
+  | 'ordinal'
+  | 'log'
+  | 'point'
+  | 'quantile'
+  | 'quantize'
+  | 'sqrt'
+  | 'custom'
+  | 'identity';
+
+export type APIErrorContext = {
+  requestType: RequestType;
+  mapId?: string;
+  connection?: string;
+  source?: string;
+  type?: MapType;
+};
+
+export enum SchemaFieldType {
+  Number = 'number',
+  Bigint = 'bigint',
+  String = 'string',
+  Geometry = 'geometry',
+  Timestamp = 'timestamp',
+  Object = 'object',
+  Boolean = 'boolean',
+  Variant = 'variant',
+  Unknown = 'unknown',
+}
+export interface SchemaField {
+  name: string;
+  type: SchemaFieldType; // Field type in the CARTO stack, common for all providers
+}
+
+export interface MapInstantiation extends MapInstantiationFormats {
+  nrows: number;
+  size?: number;
+  schema: SchemaField[];
+}
+
+type MapInstantiationFormats = Record<
+  Format,
+  {
+    url: string[];
+    error?: any;
+  }
+>;
+
+export type QueryParameterValue =
+  | string
+  | number
+  | boolean
+  | Array<QueryParameterValue>
+  | object;
+
+export type NamedQueryParameter = Record<string, QueryParameterValue>;
+
+export type PositionalQueryParameter = QueryParameterValue[];
+
+export type QueryParameters = NamedQueryParameter | PositionalQueryParameter;
+export type VisualChannelField = {
+  name: string;
+  type: string;
+  colorColumn?: string;
+};
+
+export interface Filters {
+  [column: string]: Filter;
+}
+
+interface Filter {
+  [FilterTypes.In]?: number[];
+  [FilterTypes.Between]?: number[][];
+  [FilterTypes.ClosedOpen]?: number[][];
+  [FilterTypes.Time]?: number[][];
+  [FilterTypes.StringSearch]?: string[];
+}
+
+export enum FilterTypes {
+  In = 'in',
+  Between = 'between', // [a, b] both are included
+  ClosedOpen = 'closed_open', // [a, b) a is included, b is not
+  Time = 'time',
+  StringSearch = 'stringSearch',
+}
+
+export type VisualChannels = {
+  colorField?: VisualChannelField;
+  colorScale?: ScaleType;
+
+  customMarkersField?: VisualChannelField;
+  customMarkersScale?: ScaleType;
+
+  radiusField?: VisualChannelField;
+  radiusScale?: ScaleType;
+
+  rotationScale?: ScaleType;
+  rotationField?: VisualChannelField;
+
+  sizeField?: VisualChannelField;
+  sizeScale?: ScaleType;
+
+  strokeColorField?: VisualChannelField;
+  strokeColorScale?: ScaleType;
+
+  heightField?: VisualChannelField;
+  heightScale?: ScaleType;
+
+  weightField?: VisualChannelField;
+};
+
+export type ColorRange = {
+  category: string;
+  colors: string[];
+  colorMap: string[][] | undefined;
+  name: string;
+  type: string;
+};
+
+export type CustomMarkersRange = {
+  markerMap: {
+    value: string;
+    markerUrl?: string;
+  }[];
+  othersMarker?: string;
+};
+
+export type VisConfig = {
+  filled?: boolean;
+  opacity?: number;
+  enable3d?: boolean;
+
+  colorAggregation?: any;
+  colorRange: ColorRange;
+
+  customMarkers?: boolean;
+  customMarkersRange?: CustomMarkersRange | null;
+  customMarkersUrl?: string | null;
+
+  radius: number;
+  radiusRange?: number[];
+
+  sizeAggregation?: any;
+  sizeRange?: any;
+
+  strokeColorAggregation?: any;
+  strokeOpacity?: number;
+  strokeColorRange?: ColorRange;
+
+  heightRange?: any;
+  heightAggregation?: any;
+
+  weightAggregation?: any;
+};
+
+export type TextLabel = {
+  field: VisualChannelField | null | undefined;
+  alignment?: 'center' | 'bottom' | 'top';
+  anchor?: 'middle' | 'start' | 'end';
+  size: number;
+  color?: number[];
+  offset?: [number, number];
+  outlineColor?: number[];
+};
+
+export type MapLayerConfig = {
+  columns?: Record<string, any>;
+  color?: number[];
+  label?: string;
+  dataId: string;
+  textLabel: TextLabel[];
+  visConfig: VisConfig;
+};
+
+export type MapTextSubLayerConfig = Omit<MapLayerConfig, 'textLabel'> & {
+  textLabel?: TextLabel;
+};
+
+export type MapConfigLayer = {
+  type: string;
+  id: string;
+  config: MapLayerConfig;
+  visualChannels: VisualChannels;
+};
+
+export type MapDataset = {
+  id: string;
+  data: any;
+  aggregationExp: string | null;
+  aggregationResLevel: number | null;
+  geoColumn: string;
+};
+
+export interface CustomStyle {
+  url?: string;
+  style?: any;
+  customAttribution?: string;
+}
+
+export type KeplerMapConfig = {
+  mapState: any;
+  mapStyle: {
+    styleType: string;
+    visibleLayerGroups: Record<string, boolean>;
+  };
+  visState: {
+    layers: MapConfigLayer[];
+  };
+  layerBlending: any;
+  interactionConfig: any;
+  customBaseMaps?: {
+    customStyle?: CustomStyle;
+  };
+};
+
+export type BasemapType = 'maplibre' | 'google-maps';
+
+export type Basemap = MapLibreBasemap | GoogleBasemap;
+
+export type BasemapCommon = {
+  /**
+   * Type of basemap.
+   */
+  type: BasemapType;
+
+  /**
+   * Custom attribution for style data if not provided by style definition.
+   */
+  attribution?: string;
+
+  /**
+   * Properties of the basemap. These properties are specific to the basemap type.
+   */
+  props: Record<string, any>;
+};
+
+export type MapLibreBasemap = BasemapCommon & {
+  type: 'maplibre';
+
+  /**
+   * MapLibre map properties.
+   *
+   * Meant to be passed to directly to `maplibregl.Map` object.
+   */
+  props: MapLibreBasemapProps;
+
+  /**
+   * Layer groups to be displayed in the basemap.
+   */
+  visibleLayerGroups?: Record<string, boolean>;
+
+  /**
+   * If `style` has been filtered by `visibleLayerGroups` then this property contains original style object, so user
+   * can use `applyLayerGroupFilters` again with new settings.
+   */
+  rawStyle?: string | Record<string, any>;
+};
+
+// Cherry-pick of maplibregl Map API props that are supported/provided by fetchMap interface
+export type MapLibreBasemapProps = {
+  style: string | Record<string, any>;
+  center: [number, number];
+  zoom: number;
+  pitch?: number;
+  bearing?: number;
+};
+
+export type GoogleBasemap = BasemapCommon & {
+  type: 'google-maps';
+
+  /**
+   * Google map properties.
+   *
+   * Meant to be passed to directly to `google.maps.Map` object.
+   */
+  props: GoogleBasemapProps;
+};
+
+// Cherry-pick of Google Map API props that are supported/provided by fetchMap interface
+export type GoogleBasemapProps = {
+  mapTypeId: string;
+  mapId?: string;
+  center?: {lat: number; lng: number};
+  zoom?: number;
+  tilt?: number;
+  heading?: number;
+};

package/src/constants.ts

@@ -1,6 +1,19 @@
 /** Current version of @carto/api-client. */
 export const API_CLIENT_VERSION = __CARTO_API_CLIENT_VERSION;
 
+export const DEFAULT_API_BASE_URL = 'https://gcp-us-east1.api.carto.com';
+export const DEFAULT_CLIENT = 'deck-gl-carto';
+export const V3_MINOR_VERSION = '3.4';
+
+// Fastly default limit is 8192; leave some padding.
+export const DEFAULT_MAX_LENGTH_URL = 7000;
+
+export const DEFAULT_TILE_SIZE = 512;
+export const DEFAULT_TILE_RESOLUTION = 0.5;
+
+export const DEFAULT_AGGREGATION_RES_LEVEL_H3 = 4;
+export const DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN = 6;
+
 /**
  * Defines a comparator used when matching a column's values against given filter values.
  *

package/src/global.d.ts

@@ -5,3 +5,6 @@
  * ```
  */
 declare const __CARTO_API_CLIENT_VERSION: string;
+
+/** Defined by @deck.gl/core. */
+declare const deck: {VERSION: string | undefined} | undefined;

package/src/index.ts

@@ -2,5 +2,14 @@ export * from './client.js';
 export * from './constants.js';
 export * from './filters.js';
 export * from './geo.js';
-export * from './sources/index.js';
+export * from './widget-sources/index.js';
 export * from './types.js';
+
+export {
+  APIErrorContext,
+  Format, // TODO: Move to `types.ts`?
+  MapType, // TODO: De-duplicate?
+  RequestType, // TODO: Move to `types.ts`?
+  QueryParameters, // TODO: Move to `types.ts`?
+  QueryOptions, // TODO: Move to `types.ts`?
+} from './api/index.js';

package/src/sources/base-source.ts

@@ -0,0 +1,100 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/* eslint-disable camelcase */
+import {
+  DEFAULT_API_BASE_URL,
+  DEFAULT_CLIENT,
+  DEFAULT_MAX_LENGTH_URL,
+} from '../constants';
+import {buildSourceUrl} from '../api/endpoints';
+import {requestWithParameters} from '../api/request-with-parameters';
+import type {APIErrorContext, MapType} from '../api/types';
+import type {
+  GeojsonResult,
+  JsonResult,
+  SourceOptionalOptions,
+  SourceRequiredOptions,
+  TilejsonMapInstantiation,
+  TilejsonResult,
+} from './types';
+
+export const SOURCE_DEFAULTS: SourceOptionalOptions = {
+  apiBaseUrl: DEFAULT_API_BASE_URL,
+  clientId: DEFAULT_CLIENT,
+  format: 'tilejson',
+  headers: {},
+  maxLengthURL: DEFAULT_MAX_LENGTH_URL,
+};
+
+export async function baseSource<UrlParameters extends Record<string, unknown>>(
+  endpoint: MapType,
+  options: Partial<SourceOptionalOptions> & SourceRequiredOptions,
+  urlParameters: UrlParameters
+): Promise<TilejsonResult | GeojsonResult | JsonResult> {
+  const {accessToken, connectionName, cache, ...optionalOptions} = options;
+  const mergedOptions = {
+    ...SOURCE_DEFAULTS,
+    accessToken,
+    connectionName,
+    endpoint,
+  };
+  for (const key in optionalOptions) {
+    if (optionalOptions[key as keyof typeof optionalOptions]) {
+      (mergedOptions as any)[key] =
+        optionalOptions[key as keyof typeof optionalOptions];
+    }
+  }
+  const baseUrl = buildSourceUrl(mergedOptions);
+  const {clientId, maxLengthURL, format} = mergedOptions;
+  const headers = {
+    Authorization: `Bearer ${options.accessToken}`,
+    ...options.headers,
+  };
+  const parameters = {client: clientId, ...urlParameters};
+
+  const errorContext: APIErrorContext = {
+    requestType: 'Map instantiation',
+    connection: options.connectionName,
+    type: endpoint,
+    source: JSON.stringify(parameters, undefined, 2),
+  };
+  const mapInstantiation =
+    await requestWithParameters<TilejsonMapInstantiation>({
+      baseUrl,
+      parameters,
+      headers,
+      errorContext,
+      maxLengthURL,
+    });
+
+  const dataUrl = mapInstantiation[format].url[0];
+  if (cache) {
+    cache.value = parseInt(
+      new URL(dataUrl).searchParams.get('cache') || '',
+      10
+    );
+  }
+  errorContext.requestType = 'Map data';
+
+  if (format === 'tilejson') {
+    const json = await requestWithParameters<TilejsonResult>({
+      baseUrl: dataUrl,
+      headers,
+      errorContext,
+      maxLengthURL,
+    });
+    if (accessToken) {
+      json.accessToken = accessToken;
+    }
+    return json;
+  }
+
+  return await requestWithParameters<GeojsonResult | JsonResult>({
+    baseUrl: dataUrl,
+    headers,
+    errorContext,
+    maxLengthURL,
+  });
+}

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

@@ -0,0 +1,53 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {QueryParameters} from '../api/index';
+import {baseSource} from './base-source';
+import type {FilterOptions, SourceOptions, TilejsonResult} from './types';
+
+export type BoundaryQuerySourceOptions = SourceOptions &
+  FilterOptions & {
+    columns?: string[];
+    tilesetTableName: string;
+    propertiesSqlQuery: string;
+    queryParameters?: QueryParameters;
+  };
+type UrlParameters = {
+  columns?: string;
+  filters?: Record<string, unknown>;
+  tilesetTableName: string;
+  propertiesSqlQuery: string;
+  queryParameters?: Record<string, unknown> | unknown[];
+};
+
+export const boundaryQuerySource = async function (
+  options: BoundaryQuerySourceOptions
+): Promise<TilejsonResult> {
+  const {
+    columns,
+    filters,
+    tilesetTableName,
+    propertiesSqlQuery,
+    queryParameters,
+  } = options;
+  const urlParameters: UrlParameters = {
+    tilesetTableName,
+    propertiesSqlQuery,
+  };
+
+  if (columns) {
+    urlParameters.columns = columns.join(',');
+  }
+  if (filters) {
+    urlParameters.filters = filters;
+  }
+  if (queryParameters) {
+    urlParameters.queryParameters = queryParameters;
+  }
+  return baseSource<UrlParameters>(
+    'boundary',
+    options,
+    urlParameters
+  ) as Promise<TilejsonResult>;
+};