@carto/api-client 0.4.2 → 0.4.3

package/build/api-client.cjs

@@ -381,449 +381,603 @@ 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
- */
-
-/** @internalRemarks Source: @carto/react-api */
-
-function _catch(body, recover) {
-  try {
-    var result = body();
-  } catch (e) {
-    return recover(e);
-  }
-  if (result && result.then) {
-    return result.then(void 0, recover);
-  }
-  return result;
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+function joinPath() {
+  return [].slice.call(arguments).map(part => part.endsWith('/') ? part.slice(0, -1) : part).join('/');
 }
-const makeCall = function (_ref2) {
+function buildV3Path(apiBaseUrl, version, endpoint) {
+  return joinPath(apiBaseUrl, version, endpoint, ...[].slice.call(arguments, 3));
+}
+/** @internal Required by fetchMap(). */
+function buildPublicMapUrl(_ref) {
   let {
-    url,
-    accessToken,
-    opts
+    apiBaseUrl,
+    cartoMapId
+  } = _ref;
+  return buildV3Path(apiBaseUrl, 'v3', 'maps', 'public', cartoMapId);
+}
+/** @internal Required by fetchMap(). */
+function buildStatsUrl(_ref2) {
+  let {
+    attribute,
+    apiBaseUrl,
+    connectionName,
+    source,
+    type
   } = _ref2;
-  try {
-    let _exit;
-    function _temp2(_result) {
-      if (_exit) ;
-      if (!response.ok) {
-        dealWithApiError({
-          response,
-          data
-        });
-      }
-      return data;
-    }
-    let response;
-    let data;
-    const isPost = opts?.method === 'POST';
-    const _temp = _catch(function () {
-      return Promise.resolve(fetch(url.toString(), {
-        headers: {
-          Authorization: `Bearer ${accessToken}`,
-          ...(isPost && {
-            'Content-Type': 'application/json'
-          })
-        },
-        ...(isPost && {
-          method: opts?.method,
-          body: opts?.body
-        }),
-        signal: opts?.abortController?.signal,
-        ...opts?.otherOptions
-      })).then(function (_fetch) {
-        response = _fetch;
-        return Promise.resolve(response.json()).then(function (_response$json) {
-          data = _response$json;
-        });
-      });
-    }, function (error) {
-      if (error.name === 'AbortError') throw error;
-      throw new Error(`Failed request: ${error}`);
-    });
-    return Promise.resolve(_temp && _temp.then ? _temp.then(_temp2) : _temp2(_temp));
-  } catch (e) {
-    return Promise.reject(e);
+  if (type === 'query') {
+    return buildV3Path(apiBaseUrl, 'v3', 'stats', connectionName, attribute);
   }
-};
-function dealWithApiError(_ref) {
+  // type === 'table'
+  return buildV3Path(apiBaseUrl, 'v3', 'stats', connectionName, source, attribute);
+}
+function buildSourceUrl(_ref3) {
   let {
-    response,
-    data
-  } = _ref;
-  if (data.error === 'Column not found') {
-    throw new InvalidColumnError(`${data.error} ${data.column_name}`);
-  }
-  if (typeof data.error === 'string' && 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?.hint || data.error?.[0]);
-      throw new Error(msg);
-  }
+    apiBaseUrl,
+    connectionName,
+    endpoint
+  } = _ref3;
+  return buildV3Path(apiBaseUrl, 'v3', 'maps', connectionName, endpoint);
+}
+function buildQueryUrl(_ref4) {
+  let {
+    apiBaseUrl,
+    connectionName
+  } = _ref4;
+  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
-} = exports.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}):`;
     }
-  }
-  return makeCall({
-    url,
-    accessToken: source.accessToken,
-    opts: {
-      ...opts,
-      method: isGet ? 'GET' : 'POST',
-      ...(!isGet && {
-        body: JSON.stringify(queryParams)
-      })
+    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;
+  }
 }
-
 /**
- * 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 = {
-      ...WidgetBaseSource.defaultProps,
-      ...props
+function formatErrorKey(key) {
+  return key.replace(/([A-Z])/g, ' $1').replace(/^./, s => s.toUpperCase());
+}
+
+// deck.gl
+const requestWithParameters = function (_ref) {
+  let {
+    baseUrl,
+    parameters = {},
+    headers: customHeaders = {},
+    errorContext,
+    maxLengthURL = DEFAULT_MAX_LENGTH_URL,
+    localCache
+  } = _ref;
+  try {
+    // 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,
+      client: getClient(),
+      ...(typeof deck !== 'undefined' && deck.VERSION && {
+        deckglVersion: deck.VERSION
+      }),
+      ...parameters
     };
-  }
-  _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
+    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 Promise.resolve(REQUEST_CACHE.get(key));
+    }
+    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;
+    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);
+    }
+    return Promise.resolve(jsonPromise);
+  } catch (e) {
+    return Promise.reject(e);
   }
-  /****************************************************************************
-   * CATEGORIES
-   */
-  /**
-   * Returns a list of labeled datapoints for categorical data. Suitable for
-   * charts including grouped bar charts, pie charts, and tree charts.
-   */
-  getCategories(options) {
-    try {
-      const _this = this;
-      const {
-        filterOwner,
-        spatialFilter,
-        abortController,
-        ...params
-      } = options;
-      const {
-        column,
-        operation,
-        operationColumn
-      } = params;
-      return Promise.resolve(executeModel({
-        model: 'category',
-        source: {
-          ..._this.getModelSource(filterOwner),
-          spatialFilter
-        },
-        params: {
-          column,
-          operation,
-          operationColumn: operationColumn || column
-        },
-        opts: {
-          abortController
-        }
-      }).then(res => normalizeObjectKeys(res.rows)));
-    } catch (e) {
-      return Promise.reject(e);
+};
+const DEFAULT_HEADERS = {
+  Accept: 'application/json',
+  'Content-Type': 'application/json'
+};
+const DEFAULT_REQUEST_CACHE = new Map();
+function getCacheSettings(localCache) {
+  const canReadCache = localCache?.cacheControl?.includes('no-cache') ? false : true;
+  const canStoreInCache = localCache?.cacheControl?.includes('no-store') ? false : true;
+  const cache = localCache?.cache || DEFAULT_REQUEST_CACHE;
+  return {
+    cache,
+    canReadCache,
+    canStoreInCache
+  };
+}
+function createCacheKey(baseUrl, parameters, headers) {
+  const parameterEntries = Object.entries(parameters).sort((_ref2, _ref3) => {
+    let [a] = _ref2;
+    let [b] = _ref3;
+    return a > b ? 1 : -1;
+  });
+  const headerEntries = Object.entries(headers).sort((_ref4, _ref5) => {
+    let [a] = _ref4;
+    let [b] = _ref5;
+    return 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());
     }
   }
-  /****************************************************************************
-   * 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
-   */
-  getFeatures(options) {
-    try {
-      const _this2 = this;
-      const {
-        filterOwner,
-        spatialFilter,
-        abortController,
-        ...params
-      } = options;
-      const {
-        columns,
-        dataType,
-        featureIds,
-        z,
-        limit,
-        tileResolution
-      } = params;
-      return Promise.resolve(executeModel({
-        model: 'pick',
-        source: {
-          ..._this2.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(_ref => {
-        let {
-          rows
-        } = _ref;
-        return {
-          rows
-        };
-      }));
-    } catch (e) {
-      return Promise.reject(e);
+  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);
     }
   }
-  /****************************************************************************
-   * FORMULA
-   */
-  /**
-   * Returns a scalar numerical statistic over all matching data. Suitable
-   * for 'headline' or 'scorecard' figures such as counts and sums.
-   */
-  getFormula(options) {
-    try {
-      const _this3 = this;
-      const {
-        filterOwner,
-        spatialFilter,
-        abortController,
-        operationExp,
-        ...params
-      } = options;
-      const {
-        column,
-        operation
-      } = params;
-      return Promise.resolve(executeModel({
-        model: 'formula',
-        source: {
-          ..._this3.getModelSource(filterOwner),
-          spatialFilter
-        },
-        params: {
-          column: column ?? '*',
-          operation,
-          operationExp
-        },
-        opts: {
-          abortController
-        }
-      }).then(res => normalizeObjectKeys(res.rows[0])));
-    } catch (e) {
-      return Promise.reject(e);
+  return baseUrl.toString();
+}
+
+// deck.gl
+const baseSource = function (endpoint, options, urlParameters) {
+  try {
+    const {
+      accessToken,
+      connectionName,
+      cache,
+      ...optionalOptions
+    } = options;
+    const mergedOptions = {
+      ...SOURCE_DEFAULTS,
+      accessToken,
+      connectionName,
+      endpoint
+    };
+    for (const key in optionalOptions) {
+      if (optionalOptions[key]) {
+        mergedOptions[key] = optionalOptions[key];
+      }
     }
-  }
-  /****************************************************************************
-   * HISTOGRAM
-   */
-  /**
-   * Returns a list of labeled datapoints for 'bins' of data defined as ticks
-   * over a numerical range. Suitable for histogram charts.
-   */
-  getHistogram(options) {
-    try {
-      const _this4 = this;
-      const {
-        filterOwner,
-        spatialFilter,
-        abortController,
-        ...params
-      } = options;
-      const {
-        column,
-        operation,
-        ticks
-      } = params;
-      return Promise.resolve(executeModel({
-        model: 'histogram',
-        source: {
-          ..._this4.getModelSource(filterOwner),
-          spatialFilter
-        },
-        params: {
-          column,
-          operation,
-          ticks
-        },
-        opts: {
-          abortController
-        }
-      }).then(res => normalizeObjectKeys(res.rows))).then(function (data) {
-        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(_ref2 => {
-            let {
-              tick,
-              value
-            } = _ref2;
-            return result[tick] = value;
+    const baseUrl = buildSourceUrl(mergedOptions);
+    const {
+      clientId,
+      maxLengthURL,
+      format,
+      localCache
+    } = mergedOptions;
+    const headers = {
+      Authorization: `Bearer ${options.accessToken}`,
+      ...options.headers
+    };
+    const parameters = {
+      client: clientId,
+      ...urlParameters
+    };
+    const errorContext = {
+      requestType: 'Map instantiation',
+      connection: options.connectionName,
+      type: endpoint,
+      source: JSON.stringify(parameters, undefined, 2)
+    };
+    return Promise.resolve(requestWithParameters({
+      baseUrl,
+      parameters,
+      headers,
+      errorContext,
+      maxLengthURL,
+      localCache
+    })).then(function (mapInstantiation) {
+      let _exit;
+      function _temp2(_result) {
+        return _exit ? _result : Promise.resolve(requestWithParameters({
+          baseUrl: dataUrl,
+          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';
+      const _temp = function () {
+        if (format === 'tilejson') {
+          return Promise.resolve(requestWithParameters({
+            baseUrl: dataUrl,
+            headers,
+            errorContext,
+            maxLengthURL,
+            localCache
+          })).then(function (json) {
+            if (accessToken) {
+              json.accessToken = accessToken;
+            }
+            _exit = 1;
+            return json;
           });
-          return result;
         }
-        return [];
-      });
-    } catch (e) {
-      return Promise.reject(e);
+      }();
+      return _temp && _temp.then ? _temp.then(_temp2) : _temp2(_temp);
+    });
+  } catch (e) {
+    return Promise.reject(e);
+  }
+};
+const SOURCE_DEFAULTS = {
+  apiBaseUrl: DEFAULT_API_BASE_URL,
+  clientId: getClient(),
+  format: 'tilejson',
+  headers: {},
+  maxLengthURL: DEFAULT_MAX_LENGTH_URL
+};
+
+// deck.gl
+const boundaryQuerySource = function (options) {
+  try {
+    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 Promise.resolve(baseSource('boundary', options, urlParameters));
+  } catch (e) {
+    return Promise.reject(e);
   }
-  /****************************************************************************
-   * 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.
-   */
-  getRange(options) {
-    try {
-      const _this5 = this;
-      const {
-        filterOwner,
-        spatialFilter,
-        abortController,
-        ...params
-      } = options;
-      const {
-        column
-      } = params;
-      return Promise.resolve(executeModel({
-        model: 'range',
-        source: {
-          ..._this5.getModelSource(filterOwner),
-          spatialFilter
-        },
-        params: {
-          column
-        },
-        opts: {
-          abortController
-        }
-      }).then(res => normalizeObjectKeys(res.rows[0])));
-    } catch (e) {
-      return Promise.reject(e);
+};
+
+// deck.gl
+const boundaryTableSource = function (options) {
+  try {
+    const {
+      filters,
+      tilesetTableName,
+      columns,
+      propertiesTableName
+    } = options;
+    const urlParameters = {
+      tilesetTableName,
+      propertiesTableName
+    };
+    if (columns) {
+      urlParameters.columns = columns.join(',');
+    }
+    if (filters) {
+      urlParameters.filters = filters;
     }
+    return Promise.resolve(baseSource('boundary', options, urlParameters));
+  } catch (e) {
+    return Promise.reject(e);
   }
-  /****************************************************************************
-   * SCATTER
-   */
-  /**
-   * Returns a list of bivariate datapoints defined as numerical 'x' and 'y'
-   * values. Suitable for rendering scatter plots.
-   */
-  getScatter(options) {
-    try {
-      const _this6 = this;
+};
+
+/**
+ * Return more descriptive error from API
+ * @internalRemarks Source: @carto/react-api
+ */
+
+/** @internalRemarks Source: @carto/react-api */
+
+function _catch(body, recover) {
+  try {
+    var result = body();
+  } catch (e) {
+    return recover(e);
+  }
+  if (result && result.then) {
+    return result.then(void 0, recover);
+  }
+  return result;
+}
+const makeCall = function (_ref2) {
+  let {
+    url,
+    accessToken,
+    opts
+  } = _ref2;
+  try {
+    let _exit;
+    function _temp2(_result) {
+      if (_exit) ;
+      if (!response.ok) {
+        dealWithApiError({
+          response,
+          data
+        });
+      }
+      return data;
+    }
+    let response;
+    let data;
+    const isPost = opts?.method === 'POST';
+    const _temp = _catch(function () {
+      return Promise.resolve(fetch(url.toString(), {
+        headers: {
+          Authorization: `Bearer ${accessToken}`,
+          ...(isPost && {
+            'Content-Type': 'application/json'
+          })
+        },
+        ...(isPost && {
+          method: opts?.method,
+          body: opts?.body
+        }),
+        signal: opts?.abortController?.signal,
+        ...opts?.otherOptions
+      })).then(function (_fetch) {
+        response = _fetch;
+        return Promise.resolve(response.json()).then(function (_response$json) {
+          data = _response$json;
+        });
+      });
+    }, function (error) {
+      if (error.name === 'AbortError') throw error;
+      throw new Error(`Failed request: ${error}`);
+    });
+    return Promise.resolve(_temp && _temp.then ? _temp.then(_temp2) : _temp2(_temp));
+  } catch (e) {
+    return Promise.reject(e);
+  }
+};
+function dealWithApiError(_ref) {
+  let {
+    response,
+    data
+  } = _ref;
+  if (data.error === 'Column not found') {
+    throw new InvalidColumnError(`${data.error} ${data.column_name}`);
+  }
+  if (typeof data.error === 'string' && 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?.hint || data.error?.[0]);
+      throw new Error(msg);
+  }
+}
+
+/** @internalRemarks Source: @carto/react-api */
+const AVAILABLE_MODELS = ['category', 'histogram', 'formula', 'pick', 'timeseries', 'range', 'scatterplot', 'table'];
+const {
+  V3
+} = exports.ApiVersion;
+const REQUEST_GET_MAX_URL_LENGTH = 2048;
+/**
+ * Execute a SQL model request.
+ * @internalRemarks Source: @carto/react-api
+ */
+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;
+    }
+  }
+  return makeCall({
+    url,
+    accessToken: source.accessToken,
+    opts: {
+      ...opts,
+      method: isGet ? 'GET' : 'POST',
+      ...(!isGet && {
+        body: JSON.stringify(queryParams)
+      })
+    }
+  });
+}
+
+/**
+ * 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 = {
+      ...WidgetBaseSource.defaultProps,
+      ...props
+    };
+  }
+  _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.
+   */
+  getCategories(options) {
+    try {
+      const _this = this;
       const {
         filterOwner,
         spatialFilter,
@@ -831,50 +985,43 @@ class WidgetBaseSource {
         ...params
       } = options;
       const {
-        xAxisColumn,
-        xAxisJoinOperation,
-        yAxisColumn,
-        yAxisJoinOperation
+        column,
+        operation,
+        operationColumn
       } = params;
-      // Make sure this is sync with the same constant in cloud-native/maps-api
-      const HARD_LIMIT = 500;
       return Promise.resolve(executeModel({
-        model: 'scatterplot',
+        model: 'category',
         source: {
-          ..._this6.getModelSource(filterOwner),
+          ..._this.getModelSource(filterOwner),
           spatialFilter
         },
         params: {
-          xAxisColumn,
-          xAxisJoinOperation,
-          yAxisColumn,
-          yAxisJoinOperation,
-          limit: HARD_LIMIT
+          column,
+          operation,
+          operationColumn: operationColumn || column
         },
         opts: {
           abortController
         }
-      }).then(res => normalizeObjectKeys(res.rows)).then(res => res.map(_ref3 => {
-        let {
-          x,
-          y
-        } = _ref3;
-        return [x, y];
-      })));
+      }).then(res => normalizeObjectKeys(res.rows)));
     } catch (e) {
       return Promise.reject(e);
     }
   }
   /****************************************************************************
-   * TABLE
+   * FEATURES
    */
   /**
-   * Returns a list of arbitrary data rows, with support for pagination and
-   * sorting. Suitable for displaying tables and lists.
+   * 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
    */
-  getTable(options) {
+  getFeatures(options) {
     try {
-      const _this7 = this;
+      const _this2 = this;
       const {
         filterOwner,
         spatialFilter,
@@ -883,549 +1030,402 @@ class WidgetBaseSource {
       } = options;
       const {
         columns,
-        sortBy,
-        sortDirection,
-        offset = 0,
-        limit = 10
+        dataType,
+        featureIds,
+        z,
+        limit,
+        tileResolution
       } = params;
       return Promise.resolve(executeModel({
-        model: 'table',
+        model: 'pick',
         source: {
-          ..._this7.getModelSource(filterOwner),
+          ..._this2.getModelSource(filterOwner),
           spatialFilter
         },
         params: {
-          column: columns,
-          sortBy,
-          sortDirection,
-          limit,
-          offset
+          columns,
+          dataType,
+          featureIds,
+          z,
+          limit: limit || 1000,
+          tileResolution: tileResolution || DEFAULT_TILE_RESOLUTION
         },
         opts: {
           abortController
         }
-      }).then(res => ({
         // Avoid `normalizeObjectKeys()`, which changes column names.
-        rows: res.rows ?? res.ROWS,
-        totalCount: res.metadata?.total ?? res.METADATA?.TOTAL
-      })));
+      }).then(_ref => {
+        let {
+          rows
+        } = _ref;
+        return {
+          rows
+        };
+      }));
     } catch (e) {
       return Promise.reject(e);
     }
   }
   /****************************************************************************
-   * TIME SERIES
+   * FORMULA
    */
   /**
-   * Returns a series of labeled numerical values, grouped into equally-sized
-   * time intervals. Suitable for rendering time series charts.
+   * Returns a scalar numerical statistic over all matching data. Suitable
+   * for 'headline' or 'scorecard' figures such as counts and sums.
    */
-  getTimeSeries(options) {
+  getFormula(options) {
     try {
-      const _this8 = this;
+      const _this3 = this;
       const {
         filterOwner,
+        spatialFilter,
         abortController,
+        operationExp,
+        ...params
+      } = options;
+      const {
+        column,
+        operation
+      } = params;
+      return Promise.resolve(executeModel({
+        model: 'formula',
+        source: {
+          ..._this3.getModelSource(filterOwner),
+          spatialFilter
+        },
+        params: {
+          column: column ?? '*',
+          operation,
+          operationExp
+        },
+        opts: {
+          abortController
+        }
+      }).then(res => normalizeObjectKeys(res.rows[0])));
+    } catch (e) {
+      return Promise.reject(e);
+    }
+  }
+  /****************************************************************************
+   * HISTOGRAM
+   */
+  /**
+   * Returns a list of labeled datapoints for 'bins' of data defined as ticks
+   * over a numerical range. Suitable for histogram charts.
+   */
+  getHistogram(options) {
+    try {
+      const _this4 = this;
+      const {
+        filterOwner,
         spatialFilter,
+        abortController,
         ...params
       } = options;
       const {
         column,
-        operationColumn,
-        joinOperation,
         operation,
-        stepSize,
-        stepMultiplier,
-        splitByCategory,
-        splitByCategoryLimit,
-        splitByCategoryValues
+        ticks
       } = params;
       return Promise.resolve(executeModel({
-        model: 'timeseries',
+        model: 'histogram',
         source: {
-          ..._this8.getModelSource(filterOwner),
+          ..._this4.getModelSource(filterOwner),
           spatialFilter
         },
         params: {
           column,
-          stepSize,
-          stepMultiplier,
-          operationColumn: operationColumn || column,
-          joinOperation,
           operation,
-          splitByCategory,
-          splitByCategoryLimit,
-          splitByCategoryValues
+          ticks
         },
         opts: {
           abortController
         }
-      }).then(res => ({
-        rows: normalizeObjectKeys(res.rows),
-        categories: res.metadata?.categories
-      })));
+      }).then(res => normalizeObjectKeys(res.rows))).then(function (data) {
+        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(_ref2 => {
+            let {
+              tick,
+              value
+            } = _ref2;
+            return result[tick] = value;
+          });
+          return result;
+        }
+        return [];
+      });
     } catch (e) {
       return Promise.reject(e);
     }
   }
-}
-WidgetBaseSource.defaultProps = {
-  apiVersion: exports.ApiVersion.V3,
-  apiBaseUrl: DEFAULT_API_BASE_URL,
-  clientId: getClient(),
-  filters: {},
-  filtersLogicalOperator: 'and',
-  geoColumn: DEFAULT_GEO_COLUMN
-};
-
-/**
- * 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 {
-      ...super._getModelSource(owner),
-      type: 'query',
-      data: this.props.sqlQuery,
-      queryParameters: this.props.queryParameters
-    };
-  }
-}
-
-/**
- * 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 {
-      ...super._getModelSource(owner),
-      type: 'table',
-      data: this.props.tableName
-    };
+  /****************************************************************************
+   * 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.
+   */
+  getRange(options) {
+    try {
+      const _this5 = this;
+      const {
+        filterOwner,
+        spatialFilter,
+        abortController,
+        ...params
+      } = options;
+      const {
+        column
+      } = params;
+      return Promise.resolve(executeModel({
+        model: 'range',
+        source: {
+          ..._this5.getModelSource(filterOwner),
+          spatialFilter
+        },
+        params: {
+          column
+        },
+        opts: {
+          abortController
+        }
+      }).then(res => normalizeObjectKeys(res.rows[0])));
+    } catch (e) {
+      return Promise.reject(e);
+    }
   }
-}
-
-// deck.gl
-// SPDX-License-Identifier: MIT
-// Copyright (c) vis.gl contributors
-/**
- *
- * Custom error for reported errors in CARTO Maps API.
- * Provides useful debugging information in console and context for applications.
- *
- */
-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;
-  }
-}
-/**
- * Converts camelCase to Camel Case
- */
-function formatErrorKey(key) {
-  return key.replace(/([A-Z])/g, ' $1').replace(/^./, s => s.toUpperCase());
-}
-
-// deck.gl
-// SPDX-License-Identifier: MIT
-// Copyright (c) vis.gl contributors
-function joinPath() {
-  return [].slice.call(arguments).map(part => part.endsWith('/') ? part.slice(0, -1) : part).join('/');
-}
-function buildV3Path(apiBaseUrl, version, endpoint) {
-  return joinPath(apiBaseUrl, version, endpoint, ...[].slice.call(arguments, 3));
-}
-/** @internal Required by fetchMap(). */
-function buildPublicMapUrl(_ref) {
-  let {
-    apiBaseUrl,
-    cartoMapId
-  } = _ref;
-  return buildV3Path(apiBaseUrl, 'v3', 'maps', 'public', cartoMapId);
-}
-/** @internal Required by fetchMap(). */
-function buildStatsUrl(_ref2) {
-  let {
-    attribute,
-    apiBaseUrl,
-    connectionName,
-    source,
-    type
-  } = _ref2;
-  if (type === 'query') {
-    return buildV3Path(apiBaseUrl, 'v3', 'stats', connectionName, attribute);
-  }
-  // type === 'table'
-  return buildV3Path(apiBaseUrl, 'v3', 'stats', connectionName, source, attribute);
-}
-function buildSourceUrl(_ref3) {
-  let {
-    apiBaseUrl,
-    connectionName,
-    endpoint
-  } = _ref3;
-  return buildV3Path(apiBaseUrl, 'v3', 'maps', connectionName, endpoint);
-}
-function buildQueryUrl(_ref4) {
-  let {
-    apiBaseUrl,
-    connectionName
-  } = _ref4;
-  return buildV3Path(apiBaseUrl, 'v3', 'sql', connectionName, 'query');
-}
-
-// deck.gl
-const requestWithParameters = function (_ref) {
-  let {
-    baseUrl,
-    parameters = {},
-    headers: customHeaders = {},
-    errorContext,
-    maxLengthURL = DEFAULT_MAX_LENGTH_URL,
-    localCache
-  } = _ref;
-  try {
-    // 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,
-      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 Promise.resolve(REQUEST_CACHE.get(key));
-    }
-    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;
-    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);
-    }
-    return Promise.resolve(jsonPromise);
-  } catch (e) {
-    return Promise.reject(e);
-  }
-};
-const DEFAULT_HEADERS = {
-  Accept: 'application/json',
-  'Content-Type': 'application/json'
-};
-const DEFAULT_REQUEST_CACHE = new Map();
-function getCacheSettings(localCache) {
-  const canReadCache = localCache?.cacheControl?.includes('no-cache') ? false : true;
-  const canStoreInCache = localCache?.cacheControl?.includes('no-store') ? false : true;
-  const cache = localCache?.cache || DEFAULT_REQUEST_CACHE;
-  return {
-    cache,
-    canReadCache,
-    canStoreInCache
-  };
-}
-function createCacheKey(baseUrl, parameters, headers) {
-  const parameterEntries = Object.entries(parameters).sort((_ref2, _ref3) => {
-    let [a] = _ref2;
-    let [b] = _ref3;
-    return a > b ? 1 : -1;
-  });
-  const headerEntries = Object.entries(headers).sort((_ref4, _ref5) => {
-    let [a] = _ref4;
-    let [b] = _ref5;
-    return 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());
-    }
-  }
-  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);
+  /****************************************************************************
+   * SCATTER
+   */
+  /**
+   * Returns a list of bivariate datapoints defined as numerical 'x' and 'y'
+   * values. Suitable for rendering scatter plots.
+   */
+  getScatter(options) {
+    try {
+      const _this6 = this;
+      const {
+        filterOwner,
+        spatialFilter,
+        abortController,
+        ...params
+      } = options;
+      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 Promise.resolve(executeModel({
+        model: 'scatterplot',
+        source: {
+          ..._this6.getModelSource(filterOwner),
+          spatialFilter
+        },
+        params: {
+          xAxisColumn,
+          xAxisJoinOperation,
+          yAxisColumn,
+          yAxisJoinOperation,
+          limit: HARD_LIMIT
+        },
+        opts: {
+          abortController
+        }
+      }).then(res => normalizeObjectKeys(res.rows)).then(res => res.map(_ref3 => {
+        let {
+          x,
+          y
+        } = _ref3;
+        return [x, y];
+      })));
+    } catch (e) {
+      return Promise.reject(e);
     }
   }
-  return baseUrl.toString();
-}
-
-// deck.gl
-const baseSource = function (endpoint, options, urlParameters) {
-  try {
-    const {
-      accessToken,
-      connectionName,
-      cache,
-      ...optionalOptions
-    } = options;
-    const mergedOptions = {
-      ...SOURCE_DEFAULTS,
-      accessToken,
-      connectionName,
-      endpoint
-    };
-    for (const key in optionalOptions) {
-      if (optionalOptions[key]) {
-        mergedOptions[key] = optionalOptions[key];
-      }
+  /****************************************************************************
+   * TABLE
+   */
+  /**
+   * Returns a list of arbitrary data rows, with support for pagination and
+   * sorting. Suitable for displaying tables and lists.
+   */
+  getTable(options) {
+    try {
+      const _this7 = this;
+      const {
+        filterOwner,
+        spatialFilter,
+        abortController,
+        ...params
+      } = options;
+      const {
+        columns,
+        sortBy,
+        sortDirection,
+        offset = 0,
+        limit = 10
+      } = params;
+      return Promise.resolve(executeModel({
+        model: 'table',
+        source: {
+          ..._this7.getModelSource(filterOwner),
+          spatialFilter
+        },
+        params: {
+          column: columns,
+          sortBy,
+          sortDirection,
+          limit,
+          offset
+        },
+        opts: {
+          abortController
+        }
+      }).then(res => ({
+        // Avoid `normalizeObjectKeys()`, which changes column names.
+        rows: res.rows ?? res.ROWS,
+        totalCount: res.metadata?.total ?? res.METADATA?.TOTAL
+      })));
+    } catch (e) {
+      return Promise.reject(e);
     }
-    const baseUrl = buildSourceUrl(mergedOptions);
-    const {
-      clientId,
-      maxLengthURL,
-      format,
-      localCache
-    } = mergedOptions;
-    const headers = {
-      Authorization: `Bearer ${options.accessToken}`,
-      ...options.headers
-    };
-    const parameters = {
-      client: clientId,
-      ...urlParameters
-    };
-    const errorContext = {
-      requestType: 'Map instantiation',
-      connection: options.connectionName,
-      type: endpoint,
-      source: JSON.stringify(parameters, undefined, 2)
-    };
-    return Promise.resolve(requestWithParameters({
-      baseUrl,
-      parameters,
-      headers,
-      errorContext,
-      maxLengthURL,
-      localCache
-    })).then(function (mapInstantiation) {
-      let _exit;
-      function _temp2(_result) {
-        return _exit ? _result : Promise.resolve(requestWithParameters({
-          baseUrl: dataUrl,
-          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';
-      const _temp = function () {
-        if (format === 'tilejson') {
-          return Promise.resolve(requestWithParameters({
-            baseUrl: dataUrl,
-            headers,
-            errorContext,
-            maxLengthURL,
-            localCache
-          })).then(function (json) {
-            if (accessToken) {
-              json.accessToken = accessToken;
-            }
-            _exit = 1;
-            return json;
-          });
+  }
+  /****************************************************************************
+   * TIME SERIES
+   */
+  /**
+   * Returns a series of labeled numerical values, grouped into equally-sized
+   * time intervals. Suitable for rendering time series charts.
+   */
+  getTimeSeries(options) {
+    try {
+      const _this8 = this;
+      const {
+        filterOwner,
+        abortController,
+        spatialFilter,
+        ...params
+      } = options;
+      const {
+        column,
+        operationColumn,
+        joinOperation,
+        operation,
+        stepSize,
+        stepMultiplier,
+        splitByCategory,
+        splitByCategoryLimit,
+        splitByCategoryValues
+      } = params;
+      return Promise.resolve(executeModel({
+        model: 'timeseries',
+        source: {
+          ..._this8.getModelSource(filterOwner),
+          spatialFilter
+        },
+        params: {
+          column,
+          stepSize,
+          stepMultiplier,
+          operationColumn: operationColumn || column,
+          joinOperation,
+          operation,
+          splitByCategory,
+          splitByCategoryLimit,
+          splitByCategoryValues
+        },
+        opts: {
+          abortController
         }
-      }();
-      return _temp && _temp.then ? _temp.then(_temp2) : _temp2(_temp);
-    });
-  } catch (e) {
-    return Promise.reject(e);
+      }).then(res => ({
+        rows: normalizeObjectKeys(res.rows),
+        categories: res.metadata?.categories
+      })));
+    } catch (e) {
+      return Promise.reject(e);
+    }
   }
-};
-const SOURCE_DEFAULTS = {
+}
+WidgetBaseSource.defaultProps = {
+  apiVersion: exports.ApiVersion.V3,
   apiBaseUrl: DEFAULT_API_BASE_URL,
   clientId: getClient(),
-  format: 'tilejson',
-  headers: {},
-  maxLengthURL: DEFAULT_MAX_LENGTH_URL
+  filters: {},
+  filtersLogicalOperator: 'and',
+  geoColumn: DEFAULT_GEO_COLUMN
 };
 
-// deck.gl
-const boundaryQuerySource = function (options) {
-  try {
-    const {
-      columns,
-      filters,
-      tilesetTableName,
-      propertiesSqlQuery,
-      queryParameters
-    } = options;
-    const urlParameters = {
-      tilesetTableName,
-      propertiesSqlQuery
+/**
+ * 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 {
+      ...super._getModelSource(owner),
+      type: 'query',
+      data: this.props.sqlQuery,
+      queryParameters: this.props.queryParameters
     };
-    if (columns) {
-      urlParameters.columns = columns.join(',');
-    }
-    if (filters) {
-      urlParameters.filters = filters;
-    }
-    if (queryParameters) {
-      urlParameters.queryParameters = queryParameters;
-    }
-    return Promise.resolve(baseSource('boundary', options, urlParameters));
-  } catch (e) {
-    return Promise.reject(e);
   }
-};
+}
 
-// deck.gl
-const boundaryTableSource = function (options) {
-  try {
-    const {
-      filters,
-      tilesetTableName,
-      columns,
-      propertiesTableName
-    } = options;
-    const urlParameters = {
-      tilesetTableName,
-      propertiesTableName
+/**
+ * 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 {
+      ...super._getModelSource(owner),
+      type: 'table',
+      data: this.props.tableName
     };
-    if (columns) {
-      urlParameters.columns = columns.join(',');
-    }
-    if (filters) {
-      urlParameters.filters = filters;
-    }
-    return Promise.resolve(baseSource('boundary', options, urlParameters));
-  } catch (e) {
-    return Promise.reject(e);
   }
-};
+}
 
 // deck.gl
 const h3QuerySource = function (options) {
@@ -1617,7 +1617,8 @@ const vectorQuerySource = function (options) {
       spatialDataColumn = 'geom',
       sqlQuery,
       tileResolution = DEFAULT_TILE_RESOLUTION,
-      queryParameters
+      queryParameters,
+      aggregationExp
     } = options;
     const urlParameters = {
       spatialDataColumn,
@@ -1634,6 +1635,9 @@ const vectorQuerySource = function (options) {
     if (queryParameters) {
       urlParameters.queryParameters = queryParameters;
     }
+    if (aggregationExp) {
+      urlParameters.aggregationExp = aggregationExp;
+    }
     return Promise.resolve(baseSource('query', options, urlParameters).then(result => ({
       ...result,
       widgetSource: new WidgetQuerySource(options)
@@ -1651,7 +1655,8 @@ const vectorTableSource = function (options) {
       filters,
       spatialDataColumn = 'geom',
       tableName,
-      tileResolution = DEFAULT_TILE_RESOLUTION
+      tileResolution = DEFAULT_TILE_RESOLUTION,
+      aggregationExp
     } = options;
     const urlParameters = {
       name: tableName,
@@ -1665,6 +1670,9 @@ const vectorTableSource = function (options) {
     if (filters) {
       urlParameters.filters = filters;
     }
+    if (aggregationExp) {
+      urlParameters.aggregationExp = aggregationExp;
+    }
     return Promise.resolve(baseSource('table', options, urlParameters).then(result => ({
       ...result,
       widgetSource: new WidgetTableSource(options)