@carto/api-client 0.3.1 → 0.4.0-alpha.1

package/src/api/carto-api-error.ts

@@ -0,0 +1,88 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {MapType} from '../types';
+
+export type APIRequestType =
+  | 'Map data'
+  | 'Map instantiation'
+  | 'Public map'
+  | 'Tile stats'
+  | 'SQL'
+  | 'Basemap style';
+
+export type APIErrorContext = {
+  requestType: APIRequestType;
+  mapId?: string;
+  connection?: string;
+  source?: string;
+  type?: MapType;
+};
+
+/**
+ *
+ * Custom error for reported errors in CARTO Maps API.
+ * Provides useful debugging information in console and context for applications.
+ *
+ */
+export class CartoAPIError extends Error {
+  /** Source error from server */
+  error: Error;
+
+  /** Context (API call & parameters) in which error occured */
+  errorContext: APIErrorContext;
+
+  /** Response from server */
+  response?: Response;
+
+  /** JSON Response from server */
+  responseJson?: any;
+
+  constructor(
+    error: Error,
+    errorContext: APIErrorContext,
+    response?: Response,
+    responseJson?: any
+  ) {
+    let responseString = 'Failed to connect';
+    if (response) {
+      responseString = 'Server returned: ';
+      if (response.status === 400) {
+        responseString += 'Bad request';
+      } else if (response.status === 401 || response.status === 403) {
+        responseString += 'Unauthorized access';
+      } else if (response.status === 404) {
+        responseString += 'Not found';
+      } else {
+        responseString += 'Error';
+      }
+
+      responseString += ` (${response.status}):`;
+    }
+    responseString += ` ${error.message || error}`;
+
+    let message = `${errorContext.requestType} API request failed`;
+    message += `\n${responseString}`;
+    for (const key of Object.keys(errorContext)) {
+      if (key === 'requestType') continue;
+      message += `\n${formatErrorKey(key)}: ${(errorContext as any)[key]}`;
+    }
+    message += '\n';
+
+    super(message);
+
+    this.name = 'CartoAPIError';
+    this.response = response;
+    this.responseJson = responseJson;
+    this.error = error;
+    this.errorContext = errorContext;
+  }
+}
+
+/**
+ * Converts camelCase to Camel Case
+ */
+function formatErrorKey(key: string) {
+  return key.replace(/([A-Z])/g, ' $1').replace(/^./, (s) => s.toUpperCase());
+}

package/src/api/endpoints.ts

@@ -0,0 +1,84 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {MapType} from '../types.js';
+
+export type V3Endpoint = 'maps' | 'stats' | 'sql';
+
+function joinPath(...args: string[]): string {
+  return args
+    .map((part) => (part.endsWith('/') ? part.slice(0, -1) : part))
+    .join('/');
+}
+
+function buildV3Path(
+  apiBaseUrl: string,
+  version: 'v3',
+  endpoint: V3Endpoint,
+  ...rest: string[]
+): string {
+  return joinPath(apiBaseUrl, version, endpoint, ...rest);
+}
+
+/** @internal Required by fetchMap(). */
+export function buildPublicMapUrl({
+  apiBaseUrl,
+  cartoMapId,
+}: {
+  apiBaseUrl: string;
+  cartoMapId: string;
+}): string {
+  return buildV3Path(apiBaseUrl, 'v3', 'maps', 'public', cartoMapId);
+}
+
+/** @internal Required by fetchMap(). */
+export function buildStatsUrl({
+  attribute,
+  apiBaseUrl,
+  connectionName,
+  source,
+  type,
+}: {
+  attribute: string;
+  apiBaseUrl: string;
+  connectionName: string;
+  source: string;
+  type: MapType;
+}): string {
+  if (type === 'query') {
+    return buildV3Path(apiBaseUrl, 'v3', 'stats', connectionName, attribute);
+  }
+
+  // type === 'table'
+  return buildV3Path(
+    apiBaseUrl,
+    'v3',
+    'stats',
+    connectionName,
+    source,
+    attribute
+  );
+}
+
+export function buildSourceUrl({
+  apiBaseUrl,
+  connectionName,
+  endpoint,
+}: {
+  apiBaseUrl: string;
+  connectionName: string;
+  endpoint: MapType;
+}): string {
+  return buildV3Path(apiBaseUrl, 'v3', 'maps', connectionName, endpoint);
+}
+
+export function buildQueryUrl({
+  apiBaseUrl,
+  connectionName,
+}: {
+  apiBaseUrl: string;
+  connectionName: string;
+}): string {
+  return buildV3Path(apiBaseUrl, 'v3', 'sql', connectionName, 'query');
+}

package/src/api/index.ts

@@ -0,0 +1,14 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export {
+  CartoAPIError,
+  APIErrorContext,
+  APIRequestType,
+} from './carto-api-error.js';
+// Internal, but required for fetchMap().
+export {buildPublicMapUrl, buildStatsUrl} from './endpoints.js';
+export {query} from './query.js';
+export type {QueryOptions} from './query.js';
+export {requestWithParameters} from './request-with-parameters.js';

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 './carto-api-error';
+
+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,135 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {isPureObject} from '../utils';
+import {CartoAPIError, APIErrorContext} from './carto-api-error';
+import {V3_MINOR_VERSION} from '../constants-internal';
+import {DEFAULT_CLIENT, DEFAULT_MAX_LENGTH_URL} 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/constants-internal.ts

@@ -1,45 +1,24 @@
 /******************************************************************************
- * DEFAULTS
+ * VERSIONS
  */
 
 /**
- * @internalRemarks Source: @carto/constants
+ * Current version of @carto/api-client.
  * @internal
  */
-export const DEFAULT_API_BASE_URL = 'https://gcp-us-east1.api.carto.com';
+export const API_CLIENT_VERSION = __CARTO_API_CLIENT_VERSION;
 
-/**
- * @internalRemarks Source: @carto/constants
- * @internal
- */
-export const DEFAULT_CLIENT = 'deck-gl-carto';
-
-/**
- * @internalRemarks Source: @carto/react-api
- * @internal
- */
-export const DEFAULT_GEO_COLUMN = 'geom';
-
-/******************************************************************************
- * ENUMS
- */
+/** @internal */
+export const V3_MINOR_VERSION = '3.4';
 
 /**
+ * @internalRemarks Source: @deck.gl/carto
  * @internal
- * @internalRemarks Source: @carto/constants
  */
-export enum MapType {
-  TABLE = 'table',
-  QUERY = 'query',
-  TILESET = 'tileset',
-}
+export const DEFAULT_AGGREGATION_RES_LEVEL_H3 = 4;
 
 /**
+ * @internalRemarks Source: @deck.gl/carto
  * @internal
- * @internalRemarks Source: @carto/constants
  */
-export enum ApiVersion {
-  V1 = 'v1',
-  V2 = 'v2',
-  V3 = 'v3',
-}
+export const DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN = 6;

package/src/constants.ts

@@ -1,6 +1,3 @@
-/** Current version of @carto/api-client. */
-export const API_CLIENT_VERSION = __CARTO_API_CLIENT_VERSION;
-
 /**
  * Defines a comparator used when matching a column's values against given filter values.
  *
@@ -24,3 +21,35 @@ export enum FilterType {
   TIME = 'time',
   STRING_SEARCH = 'stringSearch',
 }
+
+/** @internalRemarks Source: @carto/constants */
+export enum ApiVersion {
+  V1 = 'v1',
+  V2 = 'v2',
+  V3 = 'v3',
+}
+
+/******************************************************************************
+ * DEFAULTS
+ */
+
+/** @internalRemarks Source: @carto/constants, @deck.gl/carto */
+export const DEFAULT_API_BASE_URL = 'https://gcp-us-east1.api.carto.com';
+
+/** @internalRemarks Source: @carto/constants, @deck.gl/carto */
+export const DEFAULT_CLIENT = 'deck-gl-carto';
+
+/** @internalRemarks Source: @carto/constants, @deck.gl/carto */
+export const DEFAULT_GEO_COLUMN = 'geom';
+
+/**
+ * Fastly default limit is 8192; leave some padding.
+ * @internalRemarks Source: @deck.gl/carto
+ */
+export const DEFAULT_MAX_LENGTH_URL = 7000;
+
+/** @internalRemarks Source: @deck.gl/carto */
+export const DEFAULT_TILE_SIZE = 512;
+
+/** @internalRemarks Source: @deck.gl/carto */
+export const DEFAULT_TILE_RESOLUTION = 0.5;

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,42 @@ 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,
+  APIRequestType,
+  CartoAPIError,
+  QueryOptions,
+  buildPublicMapUrl, // Internal, but required for fetchMap().
+  buildStatsUrl, // Internal, but required for fetchMap().
+  query,
+  requestWithParameters,
+} from './api/index.js';
+
+export {
+  GeojsonResult,
+  JsonResult,
+  QueryResult,
+  QuerySourceOptions,
+  SOURCE_DEFAULTS,
+  SourceOptions,
+  TableSourceOptions,
+  TilejsonResult,
+  TilesetSourceOptions,
+
+  // Sources not wrapped in './widget-sources/index.js';
+  BoundaryQuerySourceOptions,
+  BoundaryTableSourceOptions,
+  H3TilesetSourceOptions,
+  QuadbinTilesetSourceOptions,
+  RasterSourceOptions,
+  VectorTilesetSourceOptions,
+  boundaryQuerySource,
+  boundaryTableSource,
+  h3TilesetSource,
+  quadbinTilesetSource,
+  rasterSource,
+  vectorTilesetSource,
+} from './sources/index.js';

package/src/models/model.ts

@@ -1,17 +1,15 @@
-import {
-  ApiVersion,
-  DEFAULT_GEO_COLUMN,
-  MapType,
-} from '../constants-internal.js';
+import {DEFAULT_GEO_COLUMN} from '../constants.js';
 import {
   Filter,
   FilterLogicalOperator,
+  MapType,
   QueryParameters,
   SpatialFilter,
 } from '../types.js';
 import {$TODO} from '../types-internal.js';
 import {assert} from '../utils.js';
 import {ModelRequestOptions, makeCall} from './common.js';
+import {ApiVersion} from '../constants.js';
 
 /** @internalRemarks Source: @carto/react-api */
 const AVAILABLE_MODELS = [
@@ -72,7 +70,7 @@ export function executeModel(props: {
   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');
+  assert(type !== 'tileset', 'executeModel: Tilesets not supported');
 
   let url = `${apiBaseUrl}/v3/sql/${connectionName}/model/${model}`;
 

package/src/sources/base-source.ts

@@ -0,0 +1,101 @@
+// 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 {
+  GeojsonResult,
+  JsonResult,
+  SourceOptionalOptions,
+  SourceRequiredOptions,
+  TilejsonMapInstantiation,
+  TilejsonResult,
+} from './types';
+import {MapType} from '../types';
+import {APIErrorContext} from '../api';
+
+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,
+  });
+}