@carto/api-client 0.4.2 → 0.4.4

package/build/api-client.modern.js

@@ -393,926 +393,1043 @@ const DEFAULT_AGGREGATION_RES_LEVEL_H3 = 4;
  */
 const DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN = 6;
 
-/**
- * Return more descriptive error from API
- * @internalRemarks Source: @carto/react-api
- */
-function dealWithApiError({
-  response,
-  data
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+function joinPath(...args) {
+  return args.map(part => part.endsWith('/') ? part.slice(0, -1) : part).join('/');
+}
+function buildV3Path(apiBaseUrl, version, endpoint, ...rest) {
+  return joinPath(apiBaseUrl, version, endpoint, ...rest);
+}
+/** @internal Required by fetchMap(). */
+function buildPublicMapUrl({
+  apiBaseUrl,
+  cartoMapId
 }) {
-  var _data$error, _data$error2;
-  if (data.error === 'Column not found') {
-    throw new InvalidColumnError(`${data.error} ${data.column_name}`);
-  }
-  if (typeof data.error === 'string' && (_data$error = data.error) != null && _data$error.includes('Missing columns')) {
-    throw new InvalidColumnError(data.error);
-  }
-  switch (response.status) {
-    case 401:
-      throw new Error('Unauthorized access. Invalid credentials');
-    case 403:
-      throw new Error('Forbidden access to the requested data');
-    default:
-      const msg = data && data.error && typeof data.error === 'string' ? data.error : JSON.stringify((data == null ? void 0 : data.hint) || ((_data$error2 = data.error) == null ? void 0 : _data$error2[0]));
-      throw new Error(msg);
-  }
+  return buildV3Path(apiBaseUrl, 'v3', 'maps', 'public', cartoMapId);
 }
-/** @internalRemarks Source: @carto/react-api */
-async function makeCall({
-  url,
-  accessToken,
-  opts
+/** @internal Required by fetchMap(). */
+function buildStatsUrl({
+  attribute,
+  apiBaseUrl,
+  connectionName,
+  source,
+  type
 }) {
-  let response;
-  let data;
-  const isPost = (opts == null ? void 0 : opts.method) === 'POST';
-  try {
-    var _opts$abortController;
-    response = await fetch(url.toString(), _extends({
-      headers: _extends({
-        Authorization: `Bearer ${accessToken}`
-      }, isPost && {
-        'Content-Type': 'application/json'
-      })
-    }, isPost && {
-      method: opts == null ? void 0 : opts.method,
-      body: opts == null ? void 0 : opts.body
-    }, {
-      signal: opts == null || (_opts$abortController = opts.abortController) == null ? void 0 : _opts$abortController.signal
-    }, opts == null ? void 0 : opts.otherOptions));
-    data = await response.json();
-  } catch (error) {
-    if (error.name === 'AbortError') throw error;
-    throw new Error(`Failed request: ${error}`);
-  }
-  if (!response.ok) {
-    dealWithApiError({
-      response,
-      data
-    });
+  if (type === 'query') {
+    return buildV3Path(apiBaseUrl, 'v3', 'stats', connectionName, attribute);
   }
-  return data;
+  // type === 'table'
+  return buildV3Path(apiBaseUrl, 'v3', 'stats', connectionName, source, attribute);
+}
+function buildSourceUrl({
+  apiBaseUrl,
+  connectionName,
+  endpoint
+}) {
+  return buildV3Path(apiBaseUrl, 'v3', 'maps', connectionName, endpoint);
+}
+function buildQueryUrl({
+  apiBaseUrl,
+  connectionName
+}) {
+  return buildV3Path(apiBaseUrl, 'v3', 'sql', connectionName, 'query');
 }
 
-/** @internalRemarks Source: @carto/react-api */
-const AVAILABLE_MODELS = ['category', 'histogram', 'formula', 'pick', 'timeseries', 'range', 'scatterplot', 'table'];
-const {
-  V3
-} = ApiVersion;
-const REQUEST_GET_MAX_URL_LENGTH = 2048;
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
 /**
- * Execute a SQL model request.
- * @internalRemarks Source: @carto/react-api
+ *
+ * Custom error for reported errors in CARTO Maps API.
+ * Provides useful debugging information in console and context for applications.
+ *
  */
-function executeModel(props) {
-  assert(props.source, 'executeModel: missing source');
-  assert(props.model, 'executeModel: missing model');
-  assert(props.params, 'executeModel: missing params');
-  assert(AVAILABLE_MODELS.includes(props.model), `executeModel: model provided isn't valid. Available models: ${AVAILABLE_MODELS.join(', ')}`);
-  const {
-    model,
-    source,
-    params,
-    opts
-  } = props;
-  const {
-    type,
-    apiVersion,
-    apiBaseUrl,
-    accessToken,
-    connectionName,
-    clientId
-  } = source;
-  assert(apiBaseUrl, 'executeModel: missing apiBaseUrl');
-  assert(accessToken, 'executeModel: missing accessToken');
-  assert(apiVersion === V3, 'executeModel: SQL Model API requires CARTO 3+');
-  assert(type !== 'tileset', 'executeModel: Tilesets not supported');
-  let url = `${apiBaseUrl}/v3/sql/${connectionName}/model/${model}`;
-  const {
-    data,
-    filters,
-    filtersLogicalOperator = 'and',
-    geoColumn = DEFAULT_GEO_COLUMN
-  } = source;
-  const queryParameters = source.queryParameters ? JSON.stringify(source.queryParameters) : '';
-  const queryParams = {
-    type,
-    client: clientId,
-    source: data,
-    params: JSON.stringify(params),
-    queryParameters,
-    filters: JSON.stringify(filters),
-    filtersLogicalOperator
-  };
-  // Picking Model API requires 'spatialDataColumn'.
-  if (model === 'pick') {
-    queryParams.spatialDataColumn = geoColumn;
-  }
-  // API supports multiple filters, we apply it only to geoColumn
-  const spatialFilters = source.spatialFilter ? {
-    [geoColumn]: source.spatialFilter
-  } : undefined;
-  if (spatialFilters) {
-    queryParams.spatialFilters = JSON.stringify(spatialFilters);
-  }
-  const urlWithSearchParams = url + '?' + new URLSearchParams(queryParams).toString();
-  const isGet = urlWithSearchParams.length <= REQUEST_GET_MAX_URL_LENGTH;
-  if (isGet) {
-    url = urlWithSearchParams;
-  } else {
-    // undo the JSON.stringify, @TODO find a better pattern
-    queryParams.params = params;
-    queryParams.filters = filters;
-    queryParams.queryParameters = source.queryParameters;
-    if (spatialFilters) {
-      queryParams.spatialFilters = spatialFilters;
+class CartoAPIError extends Error {
+  constructor(error, errorContext, response, responseJson) {
+    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[key]}`;
     }
+    message += '\n';
+    super(message);
+    /** Source error from server */
+    this.error = void 0;
+    /** Context (API call & parameters) in which error occured */
+    this.errorContext = void 0;
+    /** Response from server */
+    this.response = void 0;
+    /** JSON Response from server */
+    this.responseJson = void 0;
+    this.name = 'CartoAPIError';
+    this.response = response;
+    this.responseJson = responseJson;
+    this.error = error;
+    this.errorContext = errorContext;
   }
-  return makeCall({
-    url,
-    accessToken: source.accessToken,
-    opts: _extends({}, opts, {
-      method: isGet ? 'GET' : 'POST'
-    }, !isGet && {
-      body: JSON.stringify(queryParams)
-    })
-  });
 }
-
-const _excluded$1 = ["filterOwner", "spatialFilter", "abortController"],
-  _excluded2 = ["filterOwner", "spatialFilter", "abortController"],
-  _excluded3 = ["filterOwner", "spatialFilter", "abortController", "operationExp"],
-  _excluded4 = ["filterOwner", "spatialFilter", "abortController"],
-  _excluded5 = ["filterOwner", "spatialFilter", "abortController"],
-  _excluded6 = ["filterOwner", "spatialFilter", "abortController"],
-  _excluded7 = ["filterOwner", "spatialFilter", "abortController"],
-  _excluded8 = ["filterOwner", "abortController", "spatialFilter"];
 /**
- * Source for Widget API requests on a data source defined by a SQL query.
- *
- * Abstract class. Use {@link WidgetQuerySource} or {@link WidgetTableSource}.
+ * Converts camelCase to Camel Case
  */
-class WidgetBaseSource {
-  constructor(props) {
-    this.props = void 0;
-    this.props = _extends({}, WidgetBaseSource.defaultProps, props);
+function formatErrorKey(key) {
+  return key.replace(/([A-Z])/g, ' $1').replace(/^./, s => s.toUpperCase());
+}
+
+const DEFAULT_HEADERS = {
+  Accept: 'application/json',
+  'Content-Type': 'application/json'
+};
+const DEFAULT_REQUEST_CACHE = new Map();
+async function requestWithParameters({
+  baseUrl,
+  parameters = {},
+  headers: customHeaders = {},
+  errorContext,
+  maxLengthURL = DEFAULT_MAX_LENGTH_URL,
+  localCache
+}) {
+  // Parameters added to all requests issued with `requestWithParameters()`.
+  // These parameters override parameters already in the base URL, but not
+  // user-provided parameters.
+  parameters = _extends({
+    v: V3_MINOR_VERSION,
+    client: getClient()
+  }, typeof deck !== 'undefined' && deck.VERSION && {
+    deckglVersion: deck.VERSION
+  }, parameters);
+  baseUrl = excludeURLParameters(baseUrl, Object.keys(parameters));
+  const key = createCacheKey(baseUrl, parameters, customHeaders);
+  const {
+    cache: REQUEST_CACHE,
+    canReadCache,
+    canStoreInCache
+  } = getCacheSettings(localCache);
+  if (canReadCache && REQUEST_CACHE.has(key)) {
+    return REQUEST_CACHE.get(key);
   }
-  _getModelSource(owner) {
-    const props = this.props;
-    return {
-      apiVersion: props.apiVersion,
-      apiBaseUrl: props.apiBaseUrl,
-      clientId: props.clientId,
-      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(options) {
-    const {
-        filterOwner,
-        spatialFilter,
-        abortController
-      } = options,
-      params = _objectWithoutPropertiesLoose(options, _excluded$1);
-    const {
-      column,
-      operation,
-      operationColumn
-    } = params;
-    return executeModel({
-      model: 'category',
-      source: _extends({}, this.getModelSource(filterOwner), {
-        spatialFilter
-      }),
-      params: {
-        column,
-        operation,
-        operationColumn: operationColumn || column
-      },
-      opts: {
-        abortController
-      }
-    }).then(res => normalizeObjectKeys(res.rows));
+  const url = createURLWithParameters(baseUrl, parameters);
+  const headers = _extends({}, DEFAULT_HEADERS, customHeaders);
+  /* global fetch */
+  const fetchPromise = url.length > maxLengthURL ? fetch(baseUrl, {
+    method: 'POST',
+    body: JSON.stringify(parameters),
+    headers
+  }) : fetch(url, {
+    headers
+  });
+  let response;
+  let responseJson;
+  const jsonPromise = fetchPromise.then(_response => {
+    response = _response;
+    return response.json();
+  }).then(json => {
+    responseJson = json;
+    if (!response || !response.ok) {
+      throw new Error(json.error);
+    }
+    return json;
+  }).catch(error => {
+    if (canStoreInCache) {
+      REQUEST_CACHE.delete(key);
+    }
+    throw new CartoAPIError(error, errorContext, response, responseJson);
+  });
+  if (canStoreInCache) {
+    REQUEST_CACHE.set(key, jsonPromise);
   }
-  /****************************************************************************
-   * FEATURES
-   */
-  /**
-   * Given a list of feature IDs (as found in `_carto_feature_id`) returns all
-   * matching features. In datasets containing features with duplicate geometries,
-   * feature IDs may be duplicated (IDs are a hash of geometry) and so more
-   * results may be returned than IDs in the request.
-   * @internal
-   * @experimental
-   */
-  async getFeatures(options) {
-    const {
-        filterOwner,
-        spatialFilter,
-        abortController
-      } = options,
-      params = _objectWithoutPropertiesLoose(options, _excluded2);
-    const {
-      columns,
-      dataType,
-      featureIds,
-      z,
-      limit,
-      tileResolution
-    } = params;
-    return executeModel({
-      model: 'pick',
-      source: _extends({}, this.getModelSource(filterOwner), {
-        spatialFilter
-      }),
-      params: {
-        columns,
-        dataType,
-        featureIds,
-        z,
-        limit: limit || 1000,
-        tileResolution: tileResolution || DEFAULT_TILE_RESOLUTION
-      },
-      opts: {
-        abortController
-      }
-      // Avoid `normalizeObjectKeys()`, which changes column names.
-    }).then(({
-      rows
-    }) => ({
-      rows
-    }));
+  return jsonPromise;
+}
+function getCacheSettings(localCache) {
+  var _localCache$cacheCont, _localCache$cacheCont2;
+  const canReadCache = localCache != null && (_localCache$cacheCont = localCache.cacheControl) != null && _localCache$cacheCont.includes('no-cache') ? false : true;
+  const canStoreInCache = localCache != null && (_localCache$cacheCont2 = localCache.cacheControl) != null && _localCache$cacheCont2.includes('no-store') ? false : true;
+  const cache = (localCache == null ? void 0 : localCache.cache) || DEFAULT_REQUEST_CACHE;
+  return {
+    cache,
+    canReadCache,
+    canStoreInCache
+  };
+}
+function createCacheKey(baseUrl, parameters, headers) {
+  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, parameters) {
+  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.toString());
+    }
   }
-  /****************************************************************************
-   * FORMULA
-   */
-  /**
-   * Returns a scalar numerical statistic over all matching data. Suitable
-   * for 'headline' or 'scorecard' figures such as counts and sums.
-   */
-  async getFormula(options) {
-    const {
-        filterOwner,
-        spatialFilter,
-        abortController,
-        operationExp
-      } = options,
-      params = _objectWithoutPropertiesLoose(options, _excluded3);
-    const {
-      column,
-      operation
-    } = params;
-    return executeModel({
-      model: 'formula',
-      source: _extends({}, this.getModelSource(filterOwner), {
-        spatialFilter
-      }),
-      params: {
-        column: column != null ? column : '*',
-        operation,
-        operationExp
-      },
-      opts: {
-        abortController
-      }
-    }).then(res => normalizeObjectKeys(res.rows[0]));
+  return baseUrl.toString();
+}
+/**
+ * Deletes query string parameters from a URL.
+ */
+function excludeURLParameters(baseUrlString, parameters) {
+  const baseUrl = new URL(baseUrlString);
+  for (const param of parameters) {
+    if (baseUrl.searchParams.has(param)) {
+      baseUrl.searchParams.delete(param);
+    }
   }
-  /****************************************************************************
-   * HISTOGRAM
-   */
-  /**
-   * Returns a list of labeled datapoints for 'bins' of data defined as ticks
-   * over a numerical range. Suitable for histogram charts.
-   */
-  async getHistogram(options) {
-    const {
-        filterOwner,
-        spatialFilter,
-        abortController
-      } = options,
-      params = _objectWithoutPropertiesLoose(options, _excluded4);
-    const {
-      column,
-      operation,
-      ticks
-    } = params;
-    const data = await executeModel({
-      model: 'histogram',
-      source: _extends({}, this.getModelSource(filterOwner), {
-        spatialFilter
-      }),
-      params: {
-        column,
-        operation,
-        ticks
-      },
-      opts: {
-        abortController
-      }
-    }).then(res => 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
-      }) => result[tick] = value);
-      return result;
+  return baseUrl.toString();
+}
+
+const _excluded$1 = ["accessToken", "connectionName", "cache"];
+const SOURCE_DEFAULTS = {
+  apiBaseUrl: DEFAULT_API_BASE_URL,
+  clientId: getClient(),
+  format: 'tilejson',
+  headers: {},
+  maxLengthURL: DEFAULT_MAX_LENGTH_URL
+};
+async function baseSource(endpoint, options, urlParameters) {
+  const {
+      accessToken,
+      connectionName,
+      cache
+    } = options,
+    optionalOptions = _objectWithoutPropertiesLoose(options, _excluded$1);
+  const mergedOptions = _extends({}, SOURCE_DEFAULTS, {
+    accessToken,
+    connectionName,
+    endpoint
+  });
+  for (const key in optionalOptions) {
+    if (optionalOptions[key]) {
+      mergedOptions[key] = optionalOptions[key];
     }
-    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(options) {
-    const {
-        filterOwner,
-        spatialFilter,
-        abortController
-      } = options,
-      params = _objectWithoutPropertiesLoose(options, _excluded5);
-    const {
-      column
-    } = params;
-    return executeModel({
-      model: 'range',
-      source: _extends({}, this.getModelSource(filterOwner), {
-        spatialFilter
-      }),
-      params: {
-        column
-      },
-      opts: {
-        abortController
-      }
-    }).then(res => normalizeObjectKeys(res.rows[0]));
-  }
-  /****************************************************************************
-   * SCATTER
-   */
-  /**
-   * Returns a list of bivariate datapoints defined as numerical 'x' and 'y'
-   * values. Suitable for rendering scatter plots.
-   */
-  async getScatter(options) {
-    const {
-        filterOwner,
-        spatialFilter,
-        abortController
-      } = options,
-      params = _objectWithoutPropertiesLoose(options, _excluded6);
-    const {
-      xAxisColumn,
-      xAxisJoinOperation,
-      yAxisColumn,
-      yAxisJoinOperation
-    } = params;
-    // Make sure this is sync with the same constant in cloud-native/maps-api
-    const HARD_LIMIT = 500;
-    return executeModel({
-      model: 'scatterplot',
-      source: _extends({}, this.getModelSource(filterOwner), {
-        spatialFilter
-      }),
-      params: {
-        xAxisColumn,
-        xAxisJoinOperation,
-        yAxisColumn,
-        yAxisJoinOperation,
-        limit: HARD_LIMIT
-      },
-      opts: {
-        abortController
-      }
-    }).then(res => normalizeObjectKeys(res.rows)).then(res => res.map(({
-      x,
-      y
-    }) => [x, y]));
-  }
-  /****************************************************************************
-   * TABLE
-   */
-  /**
-   * Returns a list of arbitrary data rows, with support for pagination and
-   * sorting. Suitable for displaying tables and lists.
-   */
-  async getTable(options) {
-    const {
-        filterOwner,
-        spatialFilter,
-        abortController
-      } = options,
-      params = _objectWithoutPropertiesLoose(options, _excluded7);
-    const {
-      columns,
-      sortBy,
-      sortDirection,
-      offset = 0,
-      limit = 10
-    } = params;
-    return executeModel({
-      model: 'table',
-      source: _extends({}, this.getModelSource(filterOwner), {
-        spatialFilter
-      }),
-      params: {
-        column: columns,
-        sortBy,
-        sortDirection,
-        limit,
-        offset
-      },
-      opts: {
-        abortController
-      }
-    }).then(res => {
-      var _res$rows, _res$metadata$total, _res$metadata, _res$METADATA;
-      return {
-        // Avoid `normalizeObjectKeys()`, which changes column names.
-        rows: (_res$rows = res.rows) != null ? _res$rows : res.ROWS,
-        totalCount: (_res$metadata$total = (_res$metadata = res.metadata) == null ? void 0 : _res$metadata.total) != null ? _res$metadata$total : (_res$METADATA = res.METADATA) == null ? void 0 : _res$METADATA.TOTAL
-      };
-    });
+  const baseUrl = buildSourceUrl(mergedOptions);
+  const {
+    clientId,
+    maxLengthURL,
+    format,
+    localCache
+  } = mergedOptions;
+  const headers = _extends({
+    Authorization: `Bearer ${options.accessToken}`
+  }, options.headers);
+  const parameters = _extends({
+    client: clientId
+  }, urlParameters);
+  const errorContext = {
+    requestType: 'Map instantiation',
+    connection: options.connectionName,
+    type: endpoint,
+    source: JSON.stringify(parameters, undefined, 2)
+  };
+  const mapInstantiation = await requestWithParameters({
+    baseUrl,
+    parameters,
+    headers,
+    errorContext,
+    maxLengthURL,
+    localCache
+  });
+  const dataUrl = mapInstantiation[format].url[0];
+  if (cache) {
+    cache.value = parseInt(new URL(dataUrl).searchParams.get('cache') || '', 10);
   }
-  /****************************************************************************
-   * TIME SERIES
-   */
-  /**
-   * Returns a series of labeled numerical values, grouped into equally-sized
-   * time intervals. Suitable for rendering time series charts.
-   */
-  async getTimeSeries(options) {
-    const {
-        filterOwner,
-        abortController,
-        spatialFilter
-      } = options,
-      params = _objectWithoutPropertiesLoose(options, _excluded8);
-    const {
-      column,
-      operationColumn,
-      joinOperation,
-      operation,
-      stepSize,
-      stepMultiplier,
-      splitByCategory,
-      splitByCategoryLimit,
-      splitByCategoryValues
-    } = params;
-    return executeModel({
-      model: 'timeseries',
-      source: _extends({}, this.getModelSource(filterOwner), {
-        spatialFilter
-      }),
-      params: {
-        column,
-        stepSize,
-        stepMultiplier,
-        operationColumn: operationColumn || column,
-        joinOperation,
-        operation,
-        splitByCategory,
-        splitByCategoryLimit,
-        splitByCategoryValues
-      },
-      opts: {
-        abortController
-      }
-    }).then(res => {
-      var _res$metadata2;
-      return {
-        rows: normalizeObjectKeys(res.rows),
-        categories: (_res$metadata2 = res.metadata) == null ? void 0 : _res$metadata2.categories
-      };
+  errorContext.requestType = 'Map data';
+  if (format === 'tilejson') {
+    const json = await requestWithParameters({
+      baseUrl: dataUrl,
+      headers,
+      errorContext,
+      maxLengthURL,
+      localCache
     });
+    if (accessToken) {
+      json.accessToken = accessToken;
+    }
+    return json;
   }
+  return await requestWithParameters({
+    baseUrl: dataUrl,
+    headers,
+    errorContext,
+    maxLengthURL,
+    localCache
+  });
 }
-WidgetBaseSource.defaultProps = {
-  apiVersion: ApiVersion.V3,
-  apiBaseUrl: DEFAULT_API_BASE_URL,
-  clientId: getClient(),
-  filters: {},
-  filtersLogicalOperator: 'and',
-  geoColumn: DEFAULT_GEO_COLUMN
+
+// deck.gl
+const boundaryQuerySource = async function boundaryQuerySource(options) {
+  const {
+    columns,
+    filters,
+    tilesetTableName,
+    propertiesSqlQuery,
+    queryParameters
+  } = options;
+  const urlParameters = {
+    tilesetTableName,
+    propertiesSqlQuery
+  };
+  if (columns) {
+    urlParameters.columns = columns.join(',');
+  }
+  if (filters) {
+    urlParameters.filters = filters;
+  }
+  if (queryParameters) {
+    urlParameters.queryParameters = queryParameters;
+  }
+  return baseSource('boundary', options, urlParameters);
 };
 
-/**
- * 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;
- * ```
- */
-class WidgetQuerySource extends WidgetBaseSource {
-  getModelSource(owner) {
-    return _extends({}, super._getModelSource(owner), {
-      type: 'query',
-      data: this.props.sqlQuery,
-      queryParameters: this.props.queryParameters
-    });
+// deck.gl
+const boundaryTableSource = async function boundaryTableSource(options) {
+  const {
+    filters,
+    tilesetTableName,
+    columns,
+    propertiesTableName
+  } = options;
+  const urlParameters = {
+    tilesetTableName,
+    propertiesTableName
+  };
+  if (columns) {
+    urlParameters.columns = columns.join(',');
   }
-}
+  if (filters) {
+    urlParameters.filters = filters;
+  }
+  return baseSource('boundary', options, urlParameters);
+};
 
 /**
- * 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;
- * ```
+ * Return more descriptive error from API
+ * @internalRemarks Source: @carto/react-api
  */
-class WidgetTableSource extends WidgetBaseSource {
-  getModelSource(owner) {
-    return _extends({}, super._getModelSource(owner), {
-      type: 'table',
-      data: this.props.tableName
+function dealWithApiError({
+  response,
+  data
+}) {
+  var _data$error, _data$error2;
+  if (data.error === 'Column not found') {
+    throw new InvalidColumnError(`${data.error} ${data.column_name}`);
+  }
+  if (typeof data.error === 'string' && (_data$error = data.error) != null && _data$error.includes('Missing columns')) {
+    throw new InvalidColumnError(data.error);
+  }
+  switch (response.status) {
+    case 401:
+      throw new Error('Unauthorized access. Invalid credentials');
+    case 403:
+      throw new Error('Forbidden access to the requested data');
+    default:
+      const msg = data && data.error && typeof data.error === 'string' ? data.error : JSON.stringify((data == null ? void 0 : data.hint) || ((_data$error2 = data.error) == null ? void 0 : _data$error2[0]));
+      throw new Error(msg);
+  }
+}
+/** @internalRemarks Source: @carto/react-api */
+async function makeCall({
+  url,
+  accessToken,
+  opts
+}) {
+  let response;
+  let data;
+  const isPost = (opts == null ? void 0 : opts.method) === 'POST';
+  try {
+    var _opts$abortController;
+    response = await fetch(url.toString(), _extends({
+      headers: _extends({
+        Authorization: `Bearer ${accessToken}`
+      }, isPost && {
+        'Content-Type': 'application/json'
+      })
+    }, isPost && {
+      method: opts == null ? void 0 : opts.method,
+      body: opts == null ? void 0 : opts.body
+    }, {
+      signal: opts == null || (_opts$abortController = opts.abortController) == null ? void 0 : _opts$abortController.signal
+    }, opts == null ? void 0 : opts.otherOptions));
+    data = await response.json();
+  } catch (error) {
+    if (error.name === 'AbortError') throw error;
+    throw new Error(`Failed request: ${error}`);
+  }
+  if (!response.ok) {
+    dealWithApiError({
+      response,
+      data
     });
   }
+  return data;
 }
 
-// deck.gl
-// SPDX-License-Identifier: MIT
-// Copyright (c) vis.gl contributors
+/** @internalRemarks Source: @carto/react-api */
+const AVAILABLE_MODELS = ['category', 'histogram', 'formula', 'pick', 'timeseries', 'range', 'scatterplot', 'table'];
+const {
+  V3
+} = ApiVersion;
+const REQUEST_GET_MAX_URL_LENGTH = 2048;
 /**
- *
- * Custom error for reported errors in CARTO Maps API.
- * Provides useful debugging information in console and context for applications.
- *
+ * Execute a SQL model request.
+ * @internalRemarks Source: @carto/react-api
  */
-class CartoAPIError extends Error {
-  constructor(error, errorContext, response, responseJson) {
-    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[key]}`;
+function executeModel(props) {
+  assert(props.source, 'executeModel: missing source');
+  assert(props.model, 'executeModel: missing model');
+  assert(props.params, 'executeModel: missing params');
+  assert(AVAILABLE_MODELS.includes(props.model), `executeModel: model provided isn't valid. Available models: ${AVAILABLE_MODELS.join(', ')}`);
+  const {
+    model,
+    source,
+    params,
+    opts
+  } = props;
+  const {
+    type,
+    apiVersion,
+    apiBaseUrl,
+    accessToken,
+    connectionName,
+    clientId
+  } = source;
+  assert(apiBaseUrl, 'executeModel: missing apiBaseUrl');
+  assert(accessToken, 'executeModel: missing accessToken');
+  assert(apiVersion === V3, 'executeModel: SQL Model API requires CARTO 3+');
+  assert(type !== 'tileset', 'executeModel: Tilesets not supported');
+  let url = `${apiBaseUrl}/v3/sql/${connectionName}/model/${model}`;
+  const {
+    data,
+    filters,
+    filtersLogicalOperator = 'and',
+    spatialDataType = 'geo',
+    spatialFiltersMode = 'intersects',
+    spatialFiltersResolution = 0
+  } = source;
+  const queryParams = {
+    type,
+    client: clientId,
+    source: data,
+    params,
+    queryParameters: source.queryParameters || '',
+    filters,
+    filtersLogicalOperator
+  };
+  const spatialDataColumn = source.spatialDataColumn || DEFAULT_GEO_COLUMN;
+  // Picking Model API requires 'spatialDataColumn'.
+  if (model === 'pick') {
+    queryParams.spatialDataColumn = spatialDataColumn;
+  }
+  // API supports multiple filters, we apply it only to spatialDataColumn
+  const spatialFilters = source.spatialFilter ? {
+    [spatialDataColumn]: source.spatialFilter
+  } : undefined;
+  if (spatialFilters) {
+    queryParams.spatialFilters = spatialFilters;
+    queryParams.spatialDataColumn = spatialDataColumn;
+    queryParams.spatialDataType = spatialDataType;
+  }
+  if (spatialDataType !== 'geo') {
+    if (spatialFiltersResolution > 0) {
+      queryParams.spatialFiltersResolution = spatialFiltersResolution;
     }
-    message += '\n';
-    super(message);
-    /** Source error from server */
-    this.error = void 0;
-    /** Context (API call & parameters) in which error occured */
-    this.errorContext = void 0;
-    /** Response from server */
-    this.response = void 0;
-    /** JSON Response from server */
-    this.responseJson = void 0;
-    this.name = 'CartoAPIError';
-    this.response = response;
-    this.responseJson = responseJson;
-    this.error = error;
-    this.errorContext = errorContext;
+    queryParams.spatialFiltersMode = spatialFiltersMode;
   }
+  const urlWithSearchParams = url + '?' + objectToURLSearchParams(queryParams).toString();
+  const isGet = urlWithSearchParams.length <= REQUEST_GET_MAX_URL_LENGTH;
+  if (isGet) {
+    url = urlWithSearchParams;
+  }
+  return makeCall({
+    url,
+    accessToken: source.accessToken,
+    opts: _extends({}, opts, {
+      method: isGet ? 'GET' : 'POST'
+    }, !isGet && {
+      body: JSON.stringify(queryParams)
+    })
+  });
 }
-/**
- * Converts camelCase to Camel Case
- */
-function formatErrorKey(key) {
-  return key.replace(/([A-Z])/g, ' $1').replace(/^./, s => s.toUpperCase());
+function objectToURLSearchParams(object) {
+  const params = new URLSearchParams();
+  for (const key in object) {
+    if (isPureObject(object[key])) {
+      params.append(key, JSON.stringify(object[key]));
+    } else if (Array.isArray(object[key])) {
+      params.append(key, JSON.stringify(object[key]));
+    } else if (object[key] === null) {
+      params.append(key, 'null');
+    } else if (object[key] !== undefined) {
+      params.append(key, String(object[key]));
+    }
+  }
+  return params;
 }
 
-// deck.gl
-// SPDX-License-Identifier: MIT
-// Copyright (c) vis.gl contributors
-function joinPath(...args) {
-  return args.map(part => part.endsWith('/') ? part.slice(0, -1) : part).join('/');
-}
-function buildV3Path(apiBaseUrl, version, endpoint, ...rest) {
-  return joinPath(apiBaseUrl, version, endpoint, ...rest);
-}
-/** @internal Required by fetchMap(). */
-function buildPublicMapUrl({
-  apiBaseUrl,
-  cartoMapId
-}) {
-  return buildV3Path(apiBaseUrl, 'v3', 'maps', 'public', cartoMapId);
+const DEFAULT_TILE_SIZE = 512;
+const QUADBIN_ZOOM_MAX_OFFSET = 4;
+function getSpatialFiltersResolution(source, viewState) {
+  var _source$dataResolutio, _source$aggregationRe;
+  const dataResolution = (_source$dataResolutio = source.dataResolution) != null ? _source$dataResolutio : Number.MAX_VALUE;
+  const aggregationResLevel = (_source$aggregationRe = source.aggregationResLevel) != null ? _source$aggregationRe : source.spatialDataType === 'h3' ? DEFAULT_AGGREGATION_RES_LEVEL_H3 : DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN;
+  const aggregationResLevelOffset = Math.max(0, Math.floor(aggregationResLevel));
+  const currentZoomInt = Math.ceil(viewState.zoom);
+  if (source.spatialDataType === 'h3') {
+    var _maxH3SpatialFiltersR, _maxH3SpatialFiltersR2;
+    const tileSize = DEFAULT_TILE_SIZE;
+    const maxResolutionForZoom = (_maxH3SpatialFiltersR = (_maxH3SpatialFiltersR2 = maxH3SpatialFiltersResolutions.find(([zoom]) => zoom === currentZoomInt)) == null ? void 0 : _maxH3SpatialFiltersR2[1]) != null ? _maxH3SpatialFiltersR : Math.max(0, currentZoomInt - 3);
+    const maxSpatialFiltersResolution = maxResolutionForZoom ? Math.min(dataResolution, maxResolutionForZoom) : dataResolution;
+    const hexagonResolution = getHexagonResolution(viewState, tileSize) + aggregationResLevelOffset;
+    return Math.min(hexagonResolution, maxSpatialFiltersResolution);
+  }
+  if (source.spatialDataType === 'quadbin') {
+    const maxResolutionForZoom = currentZoomInt + QUADBIN_ZOOM_MAX_OFFSET;
+    const maxSpatialFiltersResolution = Math.min(dataResolution, maxResolutionForZoom);
+    const quadsResolution = Math.floor(viewState.zoom) + aggregationResLevelOffset;
+    return Math.min(quadsResolution, maxSpatialFiltersResolution);
+  }
+  return undefined;
 }
-/** @internal Required by fetchMap(). */
-function buildStatsUrl({
-  attribute,
-  apiBaseUrl,
-  connectionName,
-  source,
-  type
-}) {
-  if (type === 'query') {
-    return buildV3Path(apiBaseUrl, 'v3', 'stats', connectionName, attribute);
-  }
-  // type === 'table'
-  return buildV3Path(apiBaseUrl, 'v3', 'stats', connectionName, source, attribute);
-}
-function buildSourceUrl({
-  apiBaseUrl,
-  connectionName,
-  endpoint
-}) {
-  return buildV3Path(apiBaseUrl, 'v3', 'maps', connectionName, endpoint);
-}
-function buildQueryUrl({
-  apiBaseUrl,
-  connectionName
-}) {
-  return buildV3Path(apiBaseUrl, 'v3', 'sql', connectionName, 'query');
+const maxH3SpatialFiltersResolutions = [[20, 14], [19, 13], [18, 12], [17, 11], [16, 10], [15, 9], [14, 8], [13, 7], [12, 7], [11, 7], [10, 6], [9, 6], [8, 5], [7, 4], [6, 4], [5, 3], [4, 2], [3, 1], [2, 1], [1, 0]];
+// stolen from https://github.com/visgl/deck.gl/blob/master/modules/carto/src/layers/h3-tileset-2d.ts
+// Relative scale factor (0 = no biasing, 2 = a few hexagons cover view)
+const BIAS = 2;
+// Resolution conversion function. Takes a WebMercatorViewport and returns
+// a H3 resolution such that the screen space size of the hexagons is
+// similar
+function getHexagonResolution(viewport, tileSize) {
+  // Difference in given tile size compared to deck's internal 512px tile size,
+  // expressed as an offset to the viewport zoom.
+  const zoomOffset = Math.log2(tileSize / DEFAULT_TILE_SIZE);
+  const hexagonScaleFactor = 2 / 3 * (viewport.zoom - zoomOffset);
+  const latitudeScaleFactor = Math.log(1 / Math.cos(Math.PI * viewport.latitude / 180));
+  // Clip and bias
+  return Math.max(0, Math.floor(hexagonScaleFactor + latitudeScaleFactor - BIAS));
 }
 
-const DEFAULT_HEADERS = {
-  Accept: 'application/json',
-  'Content-Type': 'application/json'
-};
-const DEFAULT_REQUEST_CACHE = new Map();
-async function requestWithParameters({
-  baseUrl,
-  parameters = {},
-  headers: customHeaders = {},
-  errorContext,
-  maxLengthURL = DEFAULT_MAX_LENGTH_URL,
-  localCache
-}) {
-  // Parameters added to all requests issued with `requestWithParameters()`.
-  // These parameters override parameters already in the base URL, but not
-  // user-provided parameters.
-  parameters = _extends({
-    v: V3_MINOR_VERSION,
-    client: getClient()
-  }, typeof deck !== 'undefined' && deck.VERSION && {
-    deckglVersion: deck.VERSION
-  }, parameters);
-  baseUrl = excludeURLParameters(baseUrl, Object.keys(parameters));
-  const key = createCacheKey(baseUrl, parameters, customHeaders);
-  const {
-    cache: REQUEST_CACHE,
-    canReadCache,
-    canStoreInCache
-  } = getCacheSettings(localCache);
-  if (canReadCache && REQUEST_CACHE.has(key)) {
-    return REQUEST_CACHE.get(key);
+const _excluded = ["filterOwner", "spatialFilter", "spatialFiltersMode", "spatialIndexReferenceViewState", "abortController"],
+  _excluded2 = ["filterOwner", "spatialFilter", "spatialFiltersMode", "spatialIndexReferenceViewState", "abortController"],
+  _excluded3 = ["filterOwner", "spatialFilter", "spatialFiltersMode", "spatialIndexReferenceViewState", "abortController", "operationExp"],
+  _excluded4 = ["filterOwner", "spatialFilter", "spatialFiltersMode", "spatialIndexReferenceViewState", "abortController"],
+  _excluded5 = ["filterOwner", "spatialFilter", "spatialFiltersMode", "spatialIndexReferenceViewState", "abortController"],
+  _excluded6 = ["filterOwner", "spatialFilter", "spatialFiltersMode", "spatialIndexReferenceViewState", "abortController"],
+  _excluded7 = ["filterOwner", "spatialFilter", "spatialFiltersMode", "spatialIndexReferenceViewState", "abortController"],
+  _excluded8 = ["filterOwner", "abortController", "spatialFilter", "spatialFiltersMode", "spatialIndexReferenceViewState"];
+/**
+ * Source for Widget API requests on a data source defined by a SQL query.
+ *
+ * Abstract class. Use {@link WidgetQuerySource} or {@link WidgetTableSource}.
+ */
+class WidgetBaseSource {
+  constructor(props) {
+    this.props = void 0;
+    this.props = _extends({}, WidgetBaseSource.defaultProps, props);
   }
-  const url = createURLWithParameters(baseUrl, parameters);
-  const headers = _extends({}, DEFAULT_HEADERS, customHeaders);
-  /* global fetch */
-  const fetchPromise = url.length > maxLengthURL ? fetch(baseUrl, {
-    method: 'POST',
-    body: JSON.stringify(parameters),
-    headers
-  }) : fetch(url, {
-    headers
-  });
-  let response;
-  let responseJson;
-  const jsonPromise = fetchPromise.then(_response => {
-    response = _response;
-    return response.json();
-  }).then(json => {
-    responseJson = json;
-    if (!response || !response.ok) {
-      throw new Error(json.error);
+  _getModelSource(owner) {
+    const props = this.props;
+    return {
+      apiVersion: props.apiVersion,
+      apiBaseUrl: props.apiBaseUrl,
+      clientId: props.clientId,
+      accessToken: props.accessToken,
+      connectionName: props.connectionName,
+      filters: getApplicableFilters(owner, props.filters),
+      filtersLogicalOperator: props.filtersLogicalOperator,
+      spatialDataType: props.spatialDataType,
+      spatialDataColumn: props.spatialDataColumn,
+      dataResolution: props.dataResolution
+    };
+  }
+  _getSpatialFiltersResolution(source, spatialFilter, referenceViewState) {
+    // spatialFiltersResolution applies only to spatial index sources.
+    if (!spatialFilter || source.spatialDataType === 'geo') {
+      return;
     }
-    return json;
-  }).catch(error => {
-    if (canStoreInCache) {
-      REQUEST_CACHE.delete(key);
+    if (!referenceViewState) {
+      throw new Error('Missing required option, "spatialIndexReferenceViewState".');
     }
-    throw new CartoAPIError(error, errorContext, response, responseJson);
-  });
-  if (canStoreInCache) {
-    REQUEST_CACHE.set(key, jsonPromise);
+    return getSpatialFiltersResolution(source, referenceViewState);
   }
-  return jsonPromise;
-}
-function getCacheSettings(localCache) {
-  var _localCache$cacheCont, _localCache$cacheCont2;
-  const canReadCache = localCache != null && (_localCache$cacheCont = localCache.cacheControl) != null && _localCache$cacheCont.includes('no-cache') ? false : true;
-  const canStoreInCache = localCache != null && (_localCache$cacheCont2 = localCache.cacheControl) != null && _localCache$cacheCont2.includes('no-store') ? false : true;
-  const cache = (localCache == null ? void 0 : localCache.cache) || DEFAULT_REQUEST_CACHE;
-  return {
-    cache,
-    canReadCache,
-    canStoreInCache
-  };
-}
-function createCacheKey(baseUrl, parameters, headers) {
-  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, parameters) {
-  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.toString());
+  /****************************************************************************
+   * CATEGORIES
+   */
+  /**
+   * Returns a list of labeled datapoints for categorical data. Suitable for
+   * charts including grouped bar charts, pie charts, and tree charts.
+   */
+  async getCategories(options) {
+    const {
+        filterOwner,
+        spatialFilter,
+        spatialFiltersMode,
+        spatialIndexReferenceViewState,
+        abortController
+      } = options,
+      params = _objectWithoutPropertiesLoose(options, _excluded);
+    const {
+      column,
+      operation,
+      operationColumn
+    } = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(source, spatialFilter, spatialIndexReferenceViewState);
+    return executeModel({
+      model: 'category',
+      source: _extends({}, source, {
+        spatialFiltersResolution,
+        spatialFiltersMode,
+        spatialFilter
+      }),
+      params: {
+        column,
+        operation,
+        operationColumn: operationColumn || column
+      },
+      opts: {
+        abortController
+      }
+    }).then(res => normalizeObjectKeys(res.rows));
+  }
+  /****************************************************************************
+   * FEATURES
+   */
+  /**
+   * Given a list of feature IDs (as found in `_carto_feature_id`) returns all
+   * matching features. In datasets containing features with duplicate geometries,
+   * feature IDs may be duplicated (IDs are a hash of geometry) and so more
+   * results may be returned than IDs in the request.
+   * @internal
+   * @experimental
+   */
+  async getFeatures(options) {
+    const {
+        filterOwner,
+        spatialFilter,
+        spatialFiltersMode,
+        spatialIndexReferenceViewState,
+        abortController
+      } = options,
+      params = _objectWithoutPropertiesLoose(options, _excluded2);
+    const {
+      columns,
+      dataType,
+      featureIds,
+      z,
+      limit,
+      tileResolution
+    } = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(source, spatialFilter, spatialIndexReferenceViewState);
+    return executeModel({
+      model: 'pick',
+      source: _extends({}, source, {
+        spatialFiltersResolution,
+        spatialFiltersMode,
+        spatialFilter
+      }),
+      params: {
+        columns,
+        dataType,
+        featureIds,
+        z,
+        limit: limit || 1000,
+        tileResolution: tileResolution || DEFAULT_TILE_RESOLUTION
+      },
+      opts: {
+        abortController
+      }
+      // Avoid `normalizeObjectKeys()`, which changes column names.
+    }).then(({
+      rows
+    }) => ({
+      rows
+    }));
+  }
+  /****************************************************************************
+   * FORMULA
+   */
+  /**
+   * Returns a scalar numerical statistic over all matching data. Suitable
+   * for 'headline' or 'scorecard' figures such as counts and sums.
+   */
+  async getFormula(options) {
+    const {
+        filterOwner,
+        spatialFilter,
+        spatialFiltersMode,
+        spatialIndexReferenceViewState,
+        abortController,
+        operationExp
+      } = options,
+      params = _objectWithoutPropertiesLoose(options, _excluded3);
+    const {
+      column,
+      operation
+    } = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(source, spatialFilter, spatialIndexReferenceViewState);
+    return executeModel({
+      model: 'formula',
+      source: _extends({}, source, {
+        spatialFiltersResolution,
+        spatialFiltersMode,
+        spatialFilter
+      }),
+      params: {
+        column: column != null ? column : '*',
+        operation,
+        operationExp
+      },
+      opts: {
+        abortController
+      }
+    }).then(res => normalizeObjectKeys(res.rows[0]));
+  }
+  /****************************************************************************
+   * HISTOGRAM
+   */
+  /**
+   * Returns a list of labeled datapoints for 'bins' of data defined as ticks
+   * over a numerical range. Suitable for histogram charts.
+   */
+  async getHistogram(options) {
+    const {
+        filterOwner,
+        spatialFilter,
+        spatialFiltersMode,
+        spatialIndexReferenceViewState,
+        abortController
+      } = options,
+      params = _objectWithoutPropertiesLoose(options, _excluded4);
+    const {
+      column,
+      operation,
+      ticks
+    } = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(source, spatialFilter, spatialIndexReferenceViewState);
+    const data = await executeModel({
+      model: 'histogram',
+      source: _extends({}, source, {
+        spatialFiltersResolution,
+        spatialFiltersMode,
+        spatialFilter
+      }),
+      params: {
+        column,
+        operation,
+        ticks
+      },
+      opts: {
+        abortController
+      }
+    }).then(res => 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
+      }) => 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(options) {
+    const {
+        filterOwner,
+        spatialFilter,
+        spatialFiltersMode,
+        spatialIndexReferenceViewState,
+        abortController
+      } = options,
+      params = _objectWithoutPropertiesLoose(options, _excluded5);
+    const {
+      column
+    } = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(source, spatialFilter, spatialIndexReferenceViewState);
+    return executeModel({
+      model: 'range',
+      source: _extends({}, source, {
+        spatialFiltersResolution,
+        spatialFiltersMode,
+        spatialFilter
+      }),
+      params: {
+        column
+      },
+      opts: {
+        abortController
+      }
+    }).then(res => normalizeObjectKeys(res.rows[0]));
+  }
+  /****************************************************************************
+   * SCATTER
+   */
+  /**
+   * Returns a list of bivariate datapoints defined as numerical 'x' and 'y'
+   * values. Suitable for rendering scatter plots.
+   */
+  async getScatter(options) {
+    const {
+        filterOwner,
+        spatialFilter,
+        spatialFiltersMode,
+        spatialIndexReferenceViewState,
+        abortController
+      } = options,
+      params = _objectWithoutPropertiesLoose(options, _excluded6);
+    const {
+      xAxisColumn,
+      xAxisJoinOperation,
+      yAxisColumn,
+      yAxisJoinOperation
+    } = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(source, spatialFilter, spatialIndexReferenceViewState);
+    // Make sure this is sync with the same constant in cloud-native/maps-api
+    const HARD_LIMIT = 500;
+    return executeModel({
+      model: 'scatterplot',
+      source: _extends({}, source, {
+        spatialFiltersResolution,
+        spatialFiltersMode,
+        spatialFilter
+      }),
+      params: {
+        xAxisColumn,
+        xAxisJoinOperation,
+        yAxisColumn,
+        yAxisJoinOperation,
+        limit: HARD_LIMIT
+      },
+      opts: {
+        abortController
+      }
+    }).then(res => normalizeObjectKeys(res.rows)).then(res => res.map(({
+      x,
+      y
+    }) => [x, y]));
+  }
+  /****************************************************************************
+   * TABLE
+   */
+  /**
+   * Returns a list of arbitrary data rows, with support for pagination and
+   * sorting. Suitable for displaying tables and lists.
+   */
+  async getTable(options) {
+    const {
+        filterOwner,
+        spatialFilter,
+        spatialFiltersMode,
+        spatialIndexReferenceViewState,
+        abortController
+      } = options,
+      params = _objectWithoutPropertiesLoose(options, _excluded7);
+    const {
+      columns,
+      sortBy,
+      sortDirection,
+      offset = 0,
+      limit = 10
+    } = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(source, spatialFilter, spatialIndexReferenceViewState);
+    return executeModel({
+      model: 'table',
+      source: _extends({}, source, {
+        spatialFiltersResolution,
+        spatialFiltersMode,
+        spatialFilter
+      }),
+      params: {
+        column: columns,
+        sortBy,
+        sortDirection,
+        limit,
+        offset
+      },
+      opts: {
+        abortController
+      }
+    }).then(res => {
+      var _res$rows, _res$metadata$total, _res$metadata, _res$METADATA;
+      return {
+        // Avoid `normalizeObjectKeys()`, which changes column names.
+        rows: (_res$rows = res.rows) != null ? _res$rows : res.ROWS,
+        totalCount: (_res$metadata$total = (_res$metadata = res.metadata) == null ? void 0 : _res$metadata.total) != null ? _res$metadata$total : (_res$METADATA = res.METADATA) == null ? void 0 : _res$METADATA.TOTAL
+      };
+    });
   }
-  return baseUrl.toString();
-}
-/**
- * Deletes query string parameters from a URL.
- */
-function excludeURLParameters(baseUrlString, parameters) {
-  const baseUrl = new URL(baseUrlString);
-  for (const param of parameters) {
-    if (baseUrl.searchParams.has(param)) {
-      baseUrl.searchParams.delete(param);
-    }
+  /****************************************************************************
+   * TIME SERIES
+   */
+  /**
+   * Returns a series of labeled numerical values, grouped into equally-sized
+   * time intervals. Suitable for rendering time series charts.
+   */
+  async getTimeSeries(options) {
+    const {
+        filterOwner,
+        abortController,
+        spatialFilter,
+        spatialFiltersMode,
+        spatialIndexReferenceViewState
+      } = options,
+      params = _objectWithoutPropertiesLoose(options, _excluded8);
+    const {
+      column,
+      operationColumn,
+      joinOperation,
+      operation,
+      stepSize,
+      stepMultiplier,
+      splitByCategory,
+      splitByCategoryLimit,
+      splitByCategoryValues
+    } = params;
+    const source = this.getModelSource(filterOwner);
+    const spatialFiltersResolution = this._getSpatialFiltersResolution(source, spatialFilter, spatialIndexReferenceViewState);
+    return executeModel({
+      model: 'timeseries',
+      source: _extends({}, source, {
+        spatialFiltersResolution,
+        spatialFiltersMode,
+        spatialFilter
+      }),
+      params: {
+        column,
+        stepSize,
+        stepMultiplier,
+        operationColumn: operationColumn || column,
+        joinOperation,
+        operation,
+        splitByCategory,
+        splitByCategoryLimit,
+        splitByCategoryValues
+      },
+      opts: {
+        abortController
+      }
+    }).then(res => {
+      var _res$metadata2;
+      return {
+        rows: normalizeObjectKeys(res.rows),
+        categories: (_res$metadata2 = res.metadata) == null ? void 0 : _res$metadata2.categories
+      };
+    });
   }
-  return baseUrl.toString();
 }
-
-const _excluded = ["accessToken", "connectionName", "cache"];
-const SOURCE_DEFAULTS = {
+WidgetBaseSource.defaultProps = {
+  apiVersion: ApiVersion.V3,
   apiBaseUrl: DEFAULT_API_BASE_URL,
   clientId: getClient(),
-  format: 'tilejson',
-  headers: {},
-  maxLengthURL: DEFAULT_MAX_LENGTH_URL
+  filters: {},
+  filtersLogicalOperator: 'and'
 };
-async function baseSource(endpoint, options, urlParameters) {
-  const {
-      accessToken,
-      connectionName,
-      cache
-    } = options,
-    optionalOptions = _objectWithoutPropertiesLoose(options, _excluded);
-  const mergedOptions = _extends({}, SOURCE_DEFAULTS, {
-    accessToken,
-    connectionName,
-    endpoint
-  });
-  for (const key in optionalOptions) {
-    if (optionalOptions[key]) {
-      mergedOptions[key] = optionalOptions[key];
-    }
-  }
-  const baseUrl = buildSourceUrl(mergedOptions);
-  const {
-    clientId,
-    maxLengthURL,
-    format,
-    localCache
-  } = mergedOptions;
-  const headers = _extends({
-    Authorization: `Bearer ${options.accessToken}`
-  }, options.headers);
-  const parameters = _extends({
-    client: clientId
-  }, urlParameters);
-  const errorContext = {
-    requestType: 'Map instantiation',
-    connection: options.connectionName,
-    type: endpoint,
-    source: JSON.stringify(parameters, undefined, 2)
-  };
-  const mapInstantiation = await requestWithParameters({
-    baseUrl,
-    parameters,
-    headers,
-    errorContext,
-    maxLengthURL,
-    localCache
-  });
-  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({
-      baseUrl: dataUrl,
-      headers,
-      errorContext,
-      maxLengthURL,
-      localCache
+
+/**
+ * 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;
+ * ```
+ */
+class WidgetQuerySource extends WidgetBaseSource {
+  getModelSource(owner) {
+    return _extends({}, super._getModelSource(owner), {
+      type: 'query',
+      data: this.props.sqlQuery,
+      queryParameters: this.props.queryParameters
     });
-    if (accessToken) {
-      json.accessToken = accessToken;
-    }
-    return json;
   }
-  return await requestWithParameters({
-    baseUrl: dataUrl,
-    headers,
-    errorContext,
-    maxLengthURL,
-    localCache
-  });
 }
 
-// deck.gl
-const boundaryQuerySource = async function boundaryQuerySource(options) {
-  const {
-    columns,
-    filters,
-    tilesetTableName,
-    propertiesSqlQuery,
-    queryParameters
-  } = options;
-  const urlParameters = {
-    tilesetTableName,
-    propertiesSqlQuery
-  };
-  if (columns) {
-    urlParameters.columns = columns.join(',');
-  }
-  if (filters) {
-    urlParameters.filters = filters;
-  }
-  if (queryParameters) {
-    urlParameters.queryParameters = queryParameters;
-  }
-  return baseSource('boundary', options, urlParameters);
-};
-
-// deck.gl
-const boundaryTableSource = async function boundaryTableSource(options) {
-  const {
-    filters,
-    tilesetTableName,
-    columns,
-    propertiesTableName
-  } = options;
-  const urlParameters = {
-    tilesetTableName,
-    propertiesTableName
-  };
-  if (columns) {
-    urlParameters.columns = columns.join(',');
-  }
-  if (filters) {
-    urlParameters.filters = 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;
+ * ```
+ */
+class WidgetTableSource extends WidgetBaseSource {
+  getModelSource(owner) {
+    return _extends({}, super._getModelSource(owner), {
+      type: 'table',
+      data: this.props.tableName
+    });
   }
-  return baseSource('boundary', options, urlParameters);
-};
+}
 
 const h3QuerySource = async function h3QuerySource(options) {
   const {
@@ -1339,7 +1456,11 @@ const h3QuerySource = async function h3QuerySource(options) {
     urlParameters.filters = filters;
   }
   return baseSource('query', options, urlParameters).then(result => _extends({}, result, {
-    widgetSource: new WidgetQuerySource(options)
+    widgetSource: new WidgetQuerySource(_extends({}, options, {
+      // NOTE: passing redundant spatialDataColumn here to apply the default value 'h3'
+      spatialDataColumn,
+      spatialDataType: 'h3'
+    }))
   }));
 };
 
@@ -1364,7 +1485,11 @@ const h3TableSource = async function h3TableSource(options) {
     urlParameters.filters = filters;
   }
   return baseSource('table', options, urlParameters).then(result => _extends({}, result, {
-    widgetSource: new WidgetTableSource(options)
+    widgetSource: new WidgetTableSource(_extends({}, options, {
+      // NOTE: passing redundant spatialDataColumn here to apply the default value 'h3'
+      spatialDataColumn,
+      spatialDataType: 'h3'
+    }))
   }));
 };
 
@@ -1419,7 +1544,11 @@ const quadbinQuerySource = async function quadbinQuerySource(options) {
     urlParameters.filters = filters;
   }
   return baseSource('query', options, urlParameters).then(result => _extends({}, result, {
-    widgetSource: new WidgetQuerySource(options)
+    widgetSource: new WidgetQuerySource(_extends({}, options, {
+      // NOTE: passing redundant spatialDataColumn here to apply the default value 'quadbin'
+      spatialDataColumn,
+      spatialDataType: 'quadbin'
+    }))
   }));
 };
 
@@ -1444,7 +1573,11 @@ const quadbinTableSource = async function quadbinTableSource(options) {
     urlParameters.filters = filters;
   }
   return baseSource('table', options, urlParameters).then(result => _extends({}, result, {
-    widgetSource: new WidgetTableSource(options)
+    widgetSource: new WidgetTableSource(_extends({}, options, {
+      // NOTE: passing redundant spatialDataColumn here to apply the default value 'quadbin'
+      spatialDataColumn,
+      spatialDataType: 'quadbin'
+    }))
   }));
 };
 
@@ -1466,7 +1599,8 @@ const vectorQuerySource = async function vectorQuerySource(options) {
     spatialDataColumn = 'geom',
     sqlQuery,
     tileResolution = DEFAULT_TILE_RESOLUTION,
-    queryParameters
+    queryParameters,
+    aggregationExp
   } = options;
   const urlParameters = {
     spatialDataColumn,
@@ -1483,8 +1617,13 @@ const vectorQuerySource = async function vectorQuerySource(options) {
   if (queryParameters) {
     urlParameters.queryParameters = queryParameters;
   }
+  if (aggregationExp) {
+    urlParameters.aggregationExp = aggregationExp;
+  }
   return baseSource('query', options, urlParameters).then(result => _extends({}, result, {
-    widgetSource: new WidgetQuerySource(options)
+    widgetSource: new WidgetQuerySource(_extends({}, options, {
+      spatialDataType: 'geo'
+    }))
   }));
 };
 
@@ -1494,7 +1633,8 @@ const vectorTableSource = async function vectorTableSource(options) {
     filters,
     spatialDataColumn = 'geom',
     tableName,
-    tileResolution = DEFAULT_TILE_RESOLUTION
+    tileResolution = DEFAULT_TILE_RESOLUTION,
+    aggregationExp
   } = options;
   const urlParameters = {
     name: tableName,
@@ -1508,8 +1648,13 @@ const vectorTableSource = async function vectorTableSource(options) {
   if (filters) {
     urlParameters.filters = filters;
   }
+  if (aggregationExp) {
+    urlParameters.aggregationExp = aggregationExp;
+  }
   return baseSource('table', options, urlParameters).then(result => _extends({}, result, {
-    widgetSource: new WidgetTableSource(options)
+    widgetSource: new WidgetTableSource(_extends({}, options, {
+      spatialDataType: 'geo'
+    }))
   }));
 };