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

package/build/sources/types.d.ts

@@ -1,95 +1,218 @@
-import { GroupDateType, SortColumnType, SortDirection, SpatialFilter } from '../types';
-/******************************************************************************
- * WIDGET API REQUESTS
- */
-/** Common options for {@link WidgetBaseSource} requests. */
-interface BaseRequestOptions {
-    spatialFilter?: SpatialFilter;
-    abortController?: AbortController;
-    filterOwner?: string;
-}
-/** Options for {@link WidgetBaseSource#getCategories}. */
-export interface CategoryRequestOptions extends BaseRequestOptions {
-    column: string;
-    operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
-    operationColumn?: string;
-}
-/** Options for {@link WidgetBaseSource#getFormula}. */
-export interface FormulaRequestOptions extends BaseRequestOptions {
-    column: string;
-    operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
-    operationExp?: string;
-}
-/** Options for {@link WidgetBaseSource#getHistogram}. */
-export interface HistogramRequestOptions extends BaseRequestOptions {
-    column: string;
-    ticks: number[];
-    operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
+import type { Feature } from 'geojson';
+import type { Filters, Format, MapInstantiation, QueryParameters } from '../api/types';
+export type SourceRequiredOptions = {
+    /** Carto platform access token. */
+    accessToken: string;
+    /** Data warehouse connection name in Carto platform. */
+    connectionName: string;
+};
+export type SourceOptionalOptions = {
+    /**
+     * Base URL of the CARTO Maps API.
+     *
+     * Example for account located in EU-west region: `https://gcp-eu-west1.api.carto.com`
+     *
+     * @default https://gcp-us-east1.api.carto.com
+     */
+    apiBaseUrl: string;
+    /**
+     * Custom HTTP headers added to map instantiation and data requests.
+     */
+    headers: Record<string, string>;
+    /**
+     * Cache buster value returned by map instantiation.
+     *
+     * Carto source saves `cache` value of map instantiation response in `cache.value`, so it can be used to
+     * check if underlying map data has changed between distinct source requests.
+     */
+    cache?: {
+        value?: number;
+    };
+    clientId: string;
+    /** @deprecated  use `query` instead **/
+    format: Format;
+    /**
+     * Maximum URL character length. Above this limit, requests use POST.
+     * Used to avoid browser and CDN limits.
+     * @default {@link DEFAULT_MAX_LENGTH_URL}
+     */
+    maxLengthURL?: number;
+};
+export type SourceOptions = SourceRequiredOptions & Partial<SourceOptionalOptions>;
+export type AggregationOptions = {
+    /**
+     * Defines the aggregation expressions that will be calculated from the resulting columns on each grid cell.
+     *
+     * Example:
+     *
+     *     sum(pop) as total_population, avg(rev) as average_revenue
+     */
+    aggregationExp: string;
+    /**
+     * Defines the tile aggregation resolution.
+     *
+     * @default 6 for quadbin and 4 for h3 sources
+     */
+    aggregationResLevel?: number;
+};
+export type FilterOptions = {
+    /**
+     * Filters to apply to the data source on the server
+     */
+    filters?: Filters;
+};
+export type QuerySourceOptions = {
+    /**
+     * The column name and the type of geospatial support.
+     *
+     * If not present, defaults to `'geom'` for generic queries, `'quadbin'` for Quadbin sources and `'h3'` for H3 sources.
+     */
+    spatialDataColumn?: string;
+    /** SQL query. */
+    sqlQuery: string;
+    /**
+     * Relative resolution of a tile. Higher values increase density and data size. At `tileResolution = 1`, tile geometry is
+     * quantized to a 1024x1024 grid. Increasing or decreasing the resolution will increase or decrease the dimensions of
+     * the quantization grid proportionately.
+     *
+     * Supported `tileResolution` values, with corresponding grid sizes:
+     *
+     * - 0.25: 256x256
+     * - 0.5: 512x512
+     * - 1: 1024x1024
+     * - 2: 2048x2048
+     * - 4: 4096x4096
+     */
+    tileResolution?: TileResolution;
+    /**
+     * Values for named or positional paramteres in the query.
+     *
+     * The way query parameters are determined by data warehouse.
+     *
+     *  * BigQuery has named query parameters, specified with a dictionary, and referenced by key (`@key`)
+     *
+     *     ```
+     *     sqlQuery: "SELECT * FROM carto-demo-data.demo_tables.retail_stores WHERE storetype = ⁣@type AND revenue > ⁣@minRevenue"
+     *     queryParameters: { type: 'Supermarket', minRevenue: 1000000 }
+     *     ```
+     * * Snowflake supports positional parameters, in the form `:1`, `:2`, etc.
+     *
+     *     ```
+     *     sqlQuery: "SELECT * FROM demo_db.public.import_retail_stores WHERE storetype = :2 AND revenue > :1
+     *     queryParameters: [100000, "Supermarket"]
+     *     ```
+     * * Postgres and Redhisft supports positional parameters, but in the form `$1`, `$2`, etc.
+     *
+     *     ```
+     *     sqlQuery: "SELECT * FROM carto_demo_data.demo_tables.retail_stores WHERE storetype = $2 AND revenue > $1
+     *     queryParameters: [100000, "Supermarket"]
+     *     ```
+     */
+    queryParameters?: QueryParameters;
+};
+export type TableSourceOptions = {
+    /**
+     * Fully qualified name of table.
+     */
+    tableName: string;
+    /**
+     * The column name and the type of geospatial support.
+     *
+     * If not present, defaults to `'geom'` for generic tables, `'quadbin'` for Quadbin sources and `'h3'` for H3 sources.
+     */
+    spatialDataColumn?: string;
+    /**
+     * Relative resolution of a tile. Higher values increase density and data size. At `tileResolution = 1`, tile geometry is
+     * quantized to a 1024x1024 grid. Increasing or decreasing the resolution will increase or decrease the dimensions of
+     * the quantization grid proportionately.
+     *
+     * Supported `tileResolution` values, with corresponding grid sizes:
+     *
+     * - 0.25: 256x256
+     * - 0.5: 512x512
+     * - 1: 1024x1024
+     * - 2: 2048x2048
+     * - 4: 4096x4096
+     */
+    tileResolution?: TileResolution;
+};
+export type TilesetSourceOptions = {
+    /**
+     * Fully qualified name of tileset.
+     */
+    tableName: string;
+};
+export type ColumnsOption = {
+    /**
+     * Columns to retrieve from the table.
+     *
+     * If not present, all columns are returned.
+     */
+    columns?: string[];
+};
+export type SpatialDataType = 'geo' | 'h3' | 'quadbin';
+export type TilejsonMapInstantiation = MapInstantiation & {
+    tilejson: {
+        url: string[];
+    };
+};
+export type TileResolution = 0.25 | 0.5 | 1 | 2 | 4;
+export interface Tilejson {
+    tilejson: string;
+    name: string;
+    description: string;
+    version: string;
+    attribution: string;
+    scheme: string;
+    tiles: string[];
+    properties_tiles: string[];
+    minresolution: number;
+    maxresolution: number;
+    minzoom: number;
+    maxzoom: number;
+    bounds: [number, number, number, number];
+    center: [number, number, number];
+    vector_layers: VectorLayer[];
+    tilestats: Tilestats;
+    tileResolution?: TileResolution;
 }
-/** Options for {@link WidgetBaseSource#getRange}. */
-export interface RangeRequestOptions extends BaseRequestOptions {
-    column: string;
+export interface Tilestats {
+    layerCount: number;
+    layers: Layer[];
 }
-/** Options for {@link WidgetBaseSource#getScatter}. */
-export interface ScatterRequestOptions extends BaseRequestOptions {
-    xAxisColumn: string;
-    xAxisJoinOperation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
-    yAxisColumn: string;
-    yAxisJoinOperation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
+export interface Layer {
+    layer: string;
+    count: number;
+    attributeCount: number;
+    attributes: Attribute[];
 }
-/** Options for {@link WidgetBaseSource#getTable}. */
-export interface TableRequestOptions extends BaseRequestOptions {
-    columns: string[];
-    sortBy?: string;
-    sortDirection?: SortDirection;
-    sortByColumnType?: SortColumnType;
-    offset?: number;
-    limit?: number;
+export interface Attribute {
+    attribute: string;
+    type: string;
 }
-/** Options for {@link WidgetBaseSource#getTimeSeries}. */
-export interface TimeSeriesRequestOptions extends BaseRequestOptions {
-    column: string;
-    stepSize?: GroupDateType;
-    stepMultiplier?: number;
-    operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
-    operationColumn?: string;
-    joinOperation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
-    splitByCategory?: string;
-    splitByCategoryLimit?: number;
-    splitByCategoryValues?: string[];
+export interface VectorLayer {
+    id: string;
+    minzoom: number;
+    maxzoom: number;
+    fields: Record<string, string>;
 }
-/******************************************************************************
- * WIDGET API RESPONSES
- */
-/** Response from {@link WidgetBaseSource#getFormula}. */
-export type FormulaResponse = {
-    value: number;
-};
-/** Response from {@link WidgetBaseSource#getCategories}. */
-export type CategoryResponse = {
-    name: string;
-    value: number;
-}[];
-/** Response from {@link WidgetBaseSource#getRange}. */
-export type RangeResponse = {
-    min: number;
-    max: number;
+export type TilejsonResult = Tilejson & {
+    accessToken: string;
 };
-/** Response from {@link WidgetBaseSource#getTable}. */
-export type TableResponse = {
-    totalCount: number;
-    rows: Record<string, number | string>[];
+export type GeojsonResult = {
+    type: 'FeatureCollection';
+    features: Feature[];
 };
-/** Response from {@link WidgetBaseSource#getScatter}. */
-export type ScatterResponse = [number, number][];
-/** Response from {@link WidgetBaseSource#getTimeSeries}. */
-export type TimeSeriesResponse = {
-    rows: {
+export type JsonResult = any[];
+export type QueryResult = {
+    meta: {
+        cacheHit: boolean;
+        location: string;
+        totalBytesProcessed: string;
+    };
+    rows: Record<string, any>[];
+    schema: {
         name: string;
-        value: number;
+        type: string;
     }[];
-    categories: string[];
 };
-/** Response from {@link WidgetBaseSource#getHistogram}. */
-export type HistogramResponse = number[];
-export {};

package/build/sources/vector-query-source.d.ts

@@ -0,0 +1,3 @@
+import type { FilterOptions, SourceOptions, QuerySourceOptions, TilejsonResult, ColumnsOption } from './types';
+export type VectorQuerySourceOptions = SourceOptions & QuerySourceOptions & FilterOptions & ColumnsOption;
+export declare const vectorQuerySource: (options: VectorQuerySourceOptions) => Promise<TilejsonResult>;

package/build/sources/vector-table-source.d.ts

@@ -0,0 +1,3 @@
+import type { FilterOptions, ColumnsOption, SourceOptions, TableSourceOptions, TilejsonResult } from './types';
+export type VectorTableSourceOptions = SourceOptions & TableSourceOptions & FilterOptions & ColumnsOption;
+export declare const vectorTableSource: (options: VectorTableSourceOptions) => Promise<TilejsonResult>;

package/build/sources/vector-tileset-source.d.ts

@@ -0,0 +1,3 @@
+import type { SourceOptions, TilesetSourceOptions, TilejsonResult } from './types';
+export type VectorTilesetSourceOptions = SourceOptions & TilesetSourceOptions;
+export declare const vectorTilesetSource: (options: VectorTilesetSourceOptions) => Promise<TilejsonResult>;

package/build/utils.d.ts

@@ -25,4 +25,8 @@ export declare class InvalidColumnError extends Error {
     static is(error: unknown): boolean;
 }
 export declare function isEmptyObject(object: object): boolean;
+/** @internal */
+export declare const isObject: (x: unknown) => boolean;
+/** @internal */
+export declare const isPureObject: (x: any) => boolean;
 export {};

package/build/widget-sources/index.d.ts

@@ -0,0 +1,5 @@
+export * from './widget-base-source.js';
+export * from './widget-query-source.js';
+export * from './widget-table-source.js';
+export * from './wrappers.js';
+export * from './types.js';

package/build/widget-sources/types.d.ts

@@ -0,0 +1,95 @@
+import { GroupDateType, SortColumnType, SortDirection, SpatialFilter } from '../types';
+/******************************************************************************
+ * WIDGET API REQUESTS
+ */
+/** Common options for {@link WidgetBaseSource} requests. */
+interface BaseRequestOptions {
+    spatialFilter?: SpatialFilter;
+    abortController?: AbortController;
+    filterOwner?: string;
+}
+/** Options for {@link WidgetBaseSource#getCategories}. */
+export interface CategoryRequestOptions extends BaseRequestOptions {
+    column: string;
+    operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
+    operationColumn?: string;
+}
+/** Options for {@link WidgetBaseSource#getFormula}. */
+export interface FormulaRequestOptions extends BaseRequestOptions {
+    column: string;
+    operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
+    operationExp?: string;
+}
+/** Options for {@link WidgetBaseSource#getHistogram}. */
+export interface HistogramRequestOptions extends BaseRequestOptions {
+    column: string;
+    ticks: number[];
+    operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
+}
+/** Options for {@link WidgetBaseSource#getRange}. */
+export interface RangeRequestOptions extends BaseRequestOptions {
+    column: string;
+}
+/** Options for {@link WidgetBaseSource#getScatter}. */
+export interface ScatterRequestOptions extends BaseRequestOptions {
+    xAxisColumn: string;
+    xAxisJoinOperation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
+    yAxisColumn: string;
+    yAxisJoinOperation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
+}
+/** Options for {@link WidgetBaseSource#getTable}. */
+export interface TableRequestOptions extends BaseRequestOptions {
+    columns: string[];
+    sortBy?: string;
+    sortDirection?: SortDirection;
+    sortByColumnType?: SortColumnType;
+    offset?: number;
+    limit?: number;
+}
+/** Options for {@link WidgetBaseSource#getTimeSeries}. */
+export interface TimeSeriesRequestOptions extends BaseRequestOptions {
+    column: string;
+    stepSize?: GroupDateType;
+    stepMultiplier?: number;
+    operation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
+    operationColumn?: string;
+    joinOperation?: 'count' | 'avg' | 'min' | 'max' | 'sum';
+    splitByCategory?: string;
+    splitByCategoryLimit?: number;
+    splitByCategoryValues?: string[];
+}
+/******************************************************************************
+ * WIDGET API RESPONSES
+ */
+/** Response from {@link WidgetBaseSource#getFormula}. */
+export type FormulaResponse = {
+    value: number;
+};
+/** Response from {@link WidgetBaseSource#getCategories}. */
+export type CategoryResponse = {
+    name: string;
+    value: number;
+}[];
+/** Response from {@link WidgetBaseSource#getRange}. */
+export type RangeResponse = {
+    min: number;
+    max: number;
+};
+/** Response from {@link WidgetBaseSource#getTable}. */
+export type TableResponse = {
+    totalCount: number;
+    rows: Record<string, number | string>[];
+};
+/** Response from {@link WidgetBaseSource#getScatter}. */
+export type ScatterResponse = [number, number][];
+/** Response from {@link WidgetBaseSource#getTimeSeries}. */
+export type TimeSeriesResponse = {
+    rows: {
+        name: string;
+        value: number;
+    }[];
+    categories: string[];
+};
+/** Response from {@link WidgetBaseSource#getHistogram}. */
+export type HistogramResponse = number[];
+export {};

package/build/{sources → widget-sources}/widget-base-source.d.ts

@@ -1,8 +1,8 @@
 import { CategoryRequestOptions, CategoryResponse, FormulaRequestOptions, FormulaResponse, HistogramRequestOptions, HistogramResponse, RangeRequestOptions, RangeResponse, ScatterRequestOptions, ScatterResponse, TableRequestOptions, TableResponse, TimeSeriesRequestOptions, TimeSeriesResponse } from './types.js';
 import { FilterLogicalOperator, Filter } from '../types.js';
-import { SourceOptions } from '@deck.gl/carto';
 import { ApiVersion } from '../constants-internal.js';
 import { ModelSource } from '../models/model.js';
+import { SourceOptions } from '../sources/index.js';
 export interface WidgetBaseSourceProps extends Omit<SourceOptions, 'filters'> {
     apiVersion?: ApiVersion;
     geoColumn?: string;

package/build/{sources → widget-sources}/widget-query-source.d.ts

@@ -1,4 +1,4 @@
-import { H3QuerySourceOptions, QuadbinQuerySourceOptions, VectorQuerySourceOptions } from '@deck.gl/carto';
+import { H3QuerySourceOptions, QuadbinQuerySourceOptions, VectorQuerySourceOptions } from '../sources/index.js';
 import { WidgetBaseSource, WidgetBaseSourceProps } from './widget-base-source.js';
 import { ModelSource } from '../models/model.js';
 type LayerQuerySourceOptions = Omit<VectorQuerySourceOptions, 'filters'> | Omit<H3QuerySourceOptions, 'filters'> | Omit<QuadbinQuerySourceOptions, 'filters'>;

package/build/{sources → widget-sources}/widget-table-source.d.ts

@@ -1,4 +1,4 @@
-import { H3TableSourceOptions, QuadbinTableSourceOptions, VectorTableSourceOptions } from '@deck.gl/carto';
+import { H3TableSourceOptions, QuadbinTableSourceOptions, VectorTableSourceOptions } from '../sources/index.js';
 import { WidgetBaseSource, WidgetBaseSourceProps } from './widget-base-source.js';
 import { ModelSource } from '../models/model.js';
 type LayerTableSourceOptions = Omit<VectorTableSourceOptions, 'filters'> | Omit<H3TableSourceOptions, 'filters'> | Omit<QuadbinTableSourceOptions, 'filters'>;

package/build/{sources → widget-sources}/wrappers.d.ts

@@ -1,4 +1,4 @@
-import { h3TableSource as _h3TableSource, h3QuerySource as _h3QuerySource, vectorTableSource as _vectorTableSource, vectorQuerySource as _vectorQuerySource, quadbinTableSource as _quadbinTableSource, quadbinQuerySource as _quadbinQuerySource, VectorTableSourceOptions as _VectorTableSourceOptions, VectorQuerySourceOptions as _VectorQuerySourceOptions, H3TableSourceOptions as _H3TableSourceOptions, H3QuerySourceOptions as _H3QuerySourceOptions, QuadbinTableSourceOptions as _QuadbinTableSourceOptions, QuadbinQuerySourceOptions as _QuadbinQuerySourceOptions } from '@deck.gl/carto';
+import { h3TableSource as _h3TableSource, h3QuerySource as _h3QuerySource, vectorTableSource as _vectorTableSource, vectorQuerySource as _vectorQuerySource, quadbinTableSource as _quadbinTableSource, quadbinQuerySource as _quadbinQuerySource, VectorTableSourceOptions as _VectorTableSourceOptions, VectorQuerySourceOptions as _VectorQuerySourceOptions, H3TableSourceOptions as _H3TableSourceOptions, H3QuerySourceOptions as _H3QuerySourceOptions, QuadbinTableSourceOptions as _QuadbinTableSourceOptions, QuadbinQuerySourceOptions as _QuadbinQuerySourceOptions } from '../sources/index.js';
 import { WidgetBaseSourceProps } from './widget-base-source.js';
 import { WidgetQuerySource } from './widget-query-source.js';
 import { WidgetTableSource } from './widget-table-source.js';

package/package.json

@@ -4,7 +4,7 @@
   "repository": "github:CartoDB/carto-api-client",
   "author": "Don McCurdy <donmccurdy@carto.com>",
   "packageManager": "yarn@4.3.1",
-  "version": "0.3.0",
+  "version": "0.4.0-alpha.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
@@ -52,7 +52,6 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@deck.gl/carto": "^9.0.30",
     "@turf/bbox-clip": "^7.1.0",
     "@turf/bbox-polygon": "^7.1.0",
     "@turf/helpers": "^7.1.0",
@@ -62,6 +61,7 @@
   },
   "devDependencies": {
     "@deck.gl/aggregation-layers": "^9.0.30",
+    "@deck.gl/carto": "^9.0.30",
     "@deck.gl/core": "^9.0.30",
     "@deck.gl/extensions": "^9.0.30",
     "@deck.gl/geo-layers": "^9.0.30",
@@ -98,5 +98,6 @@
     "vite": "^5.2.10",
     "vitest": "1.6.0",
     "vue": "^3.4.27"
-  }
+  },
+  "stableVersion": "0.3.1"
 }

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

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

package/src/api/endpoints.ts

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

package/src/api/index.ts

@@ -0,0 +1,17 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export {CartoAPIError} from './carto-api-error';
+export type {
+  APIErrorContext,
+  Format,
+  MapType,
+  RequestType,
+  QueryParameters,
+  Basemap,
+  MapLibreBasemap,
+  GoogleBasemap,
+} from './types';
+export {query} from './query';
+export type {QueryOptions} from './query';