@carto/api-client 0.5.13 → 0.5.14

package/package.json

@@ -8,7 +8,7 @@
   "homepage": "https://github.com/CartoDB/carto-api-client#readme",
   "author": "Don McCurdy <donmccurdy@carto.com>",
   "packageManager": "yarn@4.3.1",
-  "version": "0.5.13",
+  "version": "0.5.14",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -125,8 +125,8 @@
     "tsup": "^8.3.6",
     "typescript": "~5.8.2",
     "typescript-eslint": "^8.26.1",
-    "vite": "^6.2.2",
-    "vitest": "3.2.3"
+    "vite": "^7.0.0",
+    "vitest": "3.2.4"
   },
   "resolutions": {
     "@carto/api-client": "portal:./",

package/src/sources/h3-tileset-source.ts

@@ -34,6 +34,7 @@ export const h3TilesetSource = async function (
         tileFormat: getTileFormat(result),
         spatialDataColumn,
         spatialDataType: 'h3',
+        spatialDataBounds: result.bounds,
       }),
     })
   ) as Promise<H3TilesetSourceResponse>;

package/src/sources/quadbin-tileset-source.ts

@@ -34,6 +34,7 @@ export const quadbinTilesetSource = async function (
         tileFormat: getTileFormat(result),
         spatialDataColumn,
         spatialDataType: 'quadbin',
+        spatialDataBounds: result.bounds,
       }),
     })
   ) as Promise<QuadbinTilesetSourceResponse>;

package/src/sources/raster-source.ts

@@ -43,6 +43,7 @@ export const rasterSource = async function (
         tileFormat: getTileFormat(result),
         spatialDataColumn: 'quadbin',
         spatialDataType: 'quadbin',
+        spatialDataBounds: result.bounds,
         rasterMetadata: result.raster_metadata!,
       }),
     })

package/src/sources/vector-tileset-source.ts

@@ -35,6 +35,7 @@ export const vectorTilesetSource = async function (
         tileFormat: getTileFormat(result),
         spatialDataColumn,
         spatialDataType: 'geo',
+        spatialDataBounds: result.bounds,
       }),
     })
   ) as Promise<VectorTilesetSourceResponse>;

package/src/widget-sources/types.ts

@@ -1,3 +1,4 @@
+import type {BBox} from 'geojson';
 import type {
   SpatialFilterPolyfillMode,
   TileResolution,
@@ -206,6 +207,9 @@ export interface TimeSeriesRequestOptions extends BaseRequestOptions {
   splitByCategoryValues?: string[];
 }
 
+/** @experimental */
+export type ExtentRequestOptions = BaseRequestOptions;
+
 /******************************************************************************
  * WIDGET API RESPONSES
  */
@@ -256,3 +260,6 @@ export type TimeSeriesResponse = {
 
 /** Response from {@link WidgetRemoteSource#getHistogram}. */
 export type HistogramResponse = number[];
+
+/** @experimental */
+export type ExtentResponse = {bbox: BBox};

package/src/widget-sources/widget-remote-source.ts

@@ -2,6 +2,8 @@ import {executeModel, type ModelSource} from '../models/index.js';
 import type {
   CategoryRequestOptions,
   CategoryResponse,
+  ExtentRequestOptions,
+  ExtentResponse,
   FeaturesRequestOptions,
   FeaturesResponse,
   FormulaRequestOptions,
@@ -24,6 +26,8 @@ import type {Filters} from '../types.js';
 import {AggregationTypes, ApiVersion} from '../constants.js';
 import {getApplicableFilters} from '../filters.js';
 import {OTHERS_CATEGORY_NAME} from './constants.js';
+import {requestWithParameters} from '../api/request-with-parameters.js';
+import type {APIErrorContext} from '../api/carto-api-error.js';
 
 export type WidgetRemoteSourceProps = WidgetSourceProps;
 
@@ -389,4 +393,64 @@ export abstract class WidgetRemoteSource<
       categories: res.metadata?.categories,
     }));
   }
+
+  /** @experimental */
+  async getExtent(options: ExtentRequestOptions = {}): Promise<ExtentResponse> {
+    const {signal, filters = this.props.filters, filterOwner} = options;
+
+    const {
+      type,
+      data,
+      apiBaseUrl,
+      apiVersion,
+      connectionName,
+      spatialDataColumn,
+      spatialDataType,
+      queryParameters,
+    } = this.getModelSource(filters, filterOwner);
+
+    assert(apiVersion === ApiVersion.V3, 'Stats API requires CARTO 3+');
+
+    let url: string;
+
+    const parameters: Record<string, unknown> = {filters, spatialDataType};
+
+    if (type === 'query') {
+      url = `${apiBaseUrl}/${apiVersion}/stats/${connectionName}/${spatialDataColumn}`;
+      parameters.q = data;
+      parameters.queryParameters = queryParameters;
+    } else {
+      url = `${apiBaseUrl}/${apiVersion}/stats/${connectionName}/${data}/${spatialDataColumn}`;
+    }
+
+    const headers = {
+      Authorization: `Bearer ${this.props.accessToken}`,
+      ...this.props.headers,
+    };
+
+    const errorContext: APIErrorContext = {
+      requestType: 'Tile stats',
+      connection: connectionName,
+      type: type,
+    };
+
+    type StatsResponse = {
+      extent: {
+        xmin: number;
+        ymin: number;
+        xmax: number;
+        ymax: number;
+      };
+    };
+
+    return requestWithParameters<StatsResponse>({
+      baseUrl: url,
+      headers,
+      signal,
+      errorContext,
+      parameters,
+    }).then(({extent: {xmin, ymin, xmax, ymax}}) => ({
+      bbox: [xmin, ymin, xmax, ymax],
+    }));
+  }
 }

package/src/widget-sources/widget-source.ts

@@ -1,6 +1,8 @@
 import type {
   CategoryRequestOptions,
   CategoryResponse,
+  ExtentRequestOptions,
+  ExtentResponse,
   FeaturesRequestOptions,
   FeaturesResponse,
   FormulaRequestOptions,
@@ -124,4 +126,7 @@ export abstract class WidgetSource<
   abstract getTimeSeries(
     options: TimeSeriesRequestOptions
   ): Promise<TimeSeriesResponse>;
+
+  /** @experimental */
+  abstract getExtent(options?: ExtentRequestOptions): Promise<ExtentResponse>;
 }

package/src/widget-sources/widget-tileset-source-impl.ts

@@ -2,6 +2,7 @@
 import type {
   CategoryRequestOptions,
   CategoryResponse,
+  ExtentResponse,
   FeaturesResponse,
   FormulaRequestOptions,
   FormulaResponse,
@@ -390,6 +391,11 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
     };
   }
 
+  /** @experimental */
+  async getExtent(): Promise<ExtentResponse> {
+    return Promise.reject(new Error('not implemented'));
+  }
+
   /****************************************************************************
    * INTERNAL
    */

package/src/widget-sources/widget-tileset-source.ts

@@ -1,6 +1,7 @@
 import type {
   CategoryRequestOptions,
   CategoryResponse,
+  ExtentResponse,
   FeaturesResponse,
   FormulaRequestOptions,
   FormulaResponse,
@@ -17,7 +18,7 @@ import type {
 } from './types.js';
 import type {SpatialFilter, Tile} from '../types.js';
 import type {TileFeatureExtractOptions} from '../filters/index.js';
-import type {FeatureCollection} from 'geojson';
+import type {BBox, FeatureCollection} from 'geojson';
 import {WidgetSource, type WidgetSourceProps} from './widget-source.js';
 import {Method} from '../workers/constants.js';
 import type {WorkerRequest, WorkerResponse} from '../workers/types.js';
@@ -29,6 +30,10 @@ export type WidgetTilesetSourceProps = WidgetSourceProps &
   Omit<TilesetSourceOptions, 'filters'> & {
     tileFormat: TileFormat;
     spatialDataType: SpatialDataType;
+    /**
+     * Extent of spatial data, typically from TileJSON. Does not include filters.
+     */
+    spatialDataBounds: BBox;
   };
 
 export type WidgetTilesetSourceResult = {widgetSource: WidgetTilesetSource};
@@ -320,4 +325,11 @@ export class WidgetTilesetSource<
   }: RangeRequestOptions): Promise<RangeResponse> {
     return this._executeWorkerMethod(Method.GET_RANGE, [options], signal);
   }
+
+  /** @experimental */
+  async getExtent(): Promise<ExtentResponse> {
+    return Promise.resolve({
+      bbox: this.props.spatialDataBounds,
+    });
+  }
 }