@carto/api-client 0.4.2 → 0.4.4

package/build/index.d.ts

@@ -2,9 +2,9 @@ export * from './client.js';
 export * from './constants.js';
 export * from './filters.js';
 export * from './geo.js';
+export * from './sources/index.js';
 export * from './widget-sources/index.js';
 export * from './types.js';
 export { APIErrorContext, APIRequestType, CartoAPIError, QueryOptions, buildPublicMapUrl, // Internal, but required for fetchMap().
 buildStatsUrl, // Internal, but required for fetchMap().
 query, requestWithParameters, } from './api/index.js';
-export { BoundaryQuerySourceOptions, BoundaryTableSourceOptions, GeojsonResult, H3QuerySourceOptions, H3TableSourceOptions, H3TilesetSourceOptions, JsonResult, QuadbinQuerySourceOptions, QuadbinTableSourceOptions, QuadbinTilesetSourceOptions, QueryResult, QuerySourceOptions, RasterSourceOptions, SOURCE_DEFAULTS, SourceOptions, TableSourceOptions, TilejsonResult, TilesetSourceOptions, VectorQuerySourceOptions, VectorTableSourceOptions, VectorTilesetSourceOptions, boundaryQuerySource, boundaryTableSource, h3QuerySource, h3TableSource, h3TilesetSource, quadbinQuerySource, quadbinTableSource, quadbinTilesetSource, rasterSource, vectorQuerySource, vectorTableSource, vectorTilesetSource, } from './sources/index.js';

package/build/models/model.d.ts

@@ -1,6 +1,7 @@
 import { Filter, FilterLogicalOperator, MapType, QueryParameters, SpatialFilter } from '../types.js';
 import { ModelRequestOptions } from './common.js';
 import { ApiVersion } from '../constants.js';
+import { SpatialDataType, SpatialFilterPolyfillMode } from '../sources/types.js';
 /** @internalRemarks Source: @carto/react-api */
 declare const AVAILABLE_MODELS: readonly ["category", "histogram", "formula", "pick", "timeseries", "range", "scatterplot", "table"];
 export type Model = (typeof AVAILABLE_MODELS)[number];
@@ -14,9 +15,14 @@ export interface ModelSource {
     data: string;
     filters?: Record<string, Filter>;
     filtersLogicalOperator?: FilterLogicalOperator;
-    geoColumn?: string;
     spatialFilter?: SpatialFilter;
     queryParameters?: QueryParameters;
+    spatialDataColumn?: string;
+    spatialDataType?: SpatialDataType;
+    spatialFiltersResolution?: number;
+    spatialFiltersMode?: SpatialFilterPolyfillMode;
+    /** original resolution of the spatial index data as stored in the DW */
+    dataResolution?: number;
 }
 /**
  * Execute a SQL model request.

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

@@ -6,4 +6,5 @@ export type BoundaryQuerySourceOptions = SourceOptions & FilterOptions & {
     propertiesSqlQuery: string;
     queryParameters?: QueryParameters;
 };
-export declare const boundaryQuerySource: (options: BoundaryQuerySourceOptions) => Promise<TilejsonResult>;
+export type BoundaryQuerySourceResponse = TilejsonResult;
+export declare const boundaryQuerySource: (options: BoundaryQuerySourceOptions) => Promise<BoundaryQuerySourceResponse>;

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

@@ -4,4 +4,5 @@ export type BoundaryTableSourceOptions = SourceOptions & FilterOptions & {
     columns?: string[];
     propertiesTableName: string;
 };
-export declare const boundaryTableSource: (options: BoundaryTableSourceOptions) => Promise<TilejsonResult>;
+export type BoundaryTableSourceResponse = TilejsonResult;
+export declare const boundaryTableSource: (options: BoundaryTableSourceOptions) => Promise<BoundaryTableSourceResponse>;

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

@@ -1,4 +1,5 @@
 import { WidgetQuerySourceResult } from '../widget-sources';
 import type { AggregationOptions, FilterOptions, QuerySourceOptions, SourceOptions, TilejsonResult } from './types';
 export type H3QuerySourceOptions = SourceOptions & QuerySourceOptions & AggregationOptions & FilterOptions;
-export declare const h3QuerySource: (options: H3QuerySourceOptions) => Promise<TilejsonResult & WidgetQuerySourceResult>;
+export type H3QuerySourceResponse = TilejsonResult & WidgetQuerySourceResult;
+export declare const h3QuerySource: (options: H3QuerySourceOptions) => Promise<H3QuerySourceResponse>;

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

@@ -1,4 +1,5 @@
 import { WidgetTableSourceResult } from '../widget-sources';
 import type { AggregationOptions, FilterOptions, SourceOptions, TableSourceOptions, TilejsonResult } from './types';
 export type H3TableSourceOptions = SourceOptions & TableSourceOptions & AggregationOptions & FilterOptions;
-export declare const h3TableSource: (options: H3TableSourceOptions) => Promise<TilejsonResult & WidgetTableSourceResult>;
+export type H3TableSourceResponse = TilejsonResult & WidgetTableSourceResult;
+export declare const h3TableSource: (options: H3TableSourceOptions) => Promise<H3TableSourceResponse>;

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

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

package/build/sources/index.d.ts

@@ -1,27 +1,26 @@
 export { SOURCE_DEFAULTS } from './base-source';
-export type { VectorLayer, RasterMetadataBandStats, RasterBandColorinterp, RasterMetadataBand, RasterMetadata, TilejsonResult, GeojsonResult, JsonResult, QueryResult, } from './types';
+export type { GeojsonResult, JsonResult, QueryResult, QuerySourceOptions, RasterBandColorinterp, RasterMetadata, RasterMetadataBand, RasterMetadataBandStats, SourceOptions, TableSourceOptions, TilejsonResult, TilesetSourceOptions, VectorLayer, } from './types';
 export { boundaryQuerySource } from './boundary-query-source';
-export type { BoundaryQuerySourceOptions } from './boundary-query-source';
+export type { BoundaryQuerySourceOptions, BoundaryQuerySourceResponse, } from './boundary-query-source';
 export { boundaryTableSource } from './boundary-table-source';
-export type { BoundaryTableSourceOptions } from './boundary-table-source';
+export type { BoundaryTableSourceOptions, BoundaryTableSourceResponse, } from './boundary-table-source';
 export { h3QuerySource } from './h3-query-source';
-export type { H3QuerySourceOptions } from './h3-query-source';
+export type { H3QuerySourceOptions, H3QuerySourceResponse, } from './h3-query-source';
 export { h3TableSource } from './h3-table-source';
-export type { H3TableSourceOptions } from './h3-table-source';
+export type { H3TableSourceOptions, H3TableSourceResponse, } from './h3-table-source';
 export { h3TilesetSource } from './h3-tileset-source';
-export type { H3TilesetSourceOptions } from './h3-tileset-source';
+export type { H3TilesetSourceOptions, H3TilesetSourceResponse, } from './h3-tileset-source';
 export { rasterSource } from './raster-source';
-export type { RasterSourceOptions } from './raster-source';
+export type { RasterSourceOptions, RasterSourceResponse } from './raster-source';
 export { quadbinQuerySource } from './quadbin-query-source';
-export type { QuadbinQuerySourceOptions } from './quadbin-query-source';
+export type { QuadbinQuerySourceOptions, QuadbinQuerySourceResponse, } from './quadbin-query-source';
 export { quadbinTableSource } from './quadbin-table-source';
-export type { QuadbinTableSourceOptions } from './quadbin-table-source';
+export type { QuadbinTableSourceOptions, QuadbinTableSourceResponse, } from './quadbin-table-source';
 export { quadbinTilesetSource } from './quadbin-tileset-source';
-export type { QuadbinTilesetSourceOptions } from './quadbin-tileset-source';
+export type { QuadbinTilesetSourceOptions, QuadbinTilesetSourceResponse, } from './quadbin-tileset-source';
 export { vectorQuerySource } from './vector-query-source';
-export type { VectorQuerySourceOptions } from './vector-query-source';
+export type { VectorQuerySourceOptions, VectorQuerySourceResponse, } from './vector-query-source';
 export { vectorTableSource } from './vector-table-source';
-export type { VectorTableSourceOptions } from './vector-table-source';
+export type { VectorTableSourceOptions, VectorTableSourceResponse, } from './vector-table-source';
 export { vectorTilesetSource } from './vector-tileset-source';
-export type { VectorTilesetSourceOptions } from './vector-tileset-source';
-export type { SourceOptions, QuerySourceOptions, TableSourceOptions, TilesetSourceOptions, } from './types';
+export type { VectorTilesetSourceOptions, VectorTilesetSourceResponse, } from './vector-tileset-source';

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

@@ -1,4 +1,5 @@
 import { WidgetQuerySourceResult } from '../widget-sources';
 import type { AggregationOptions, FilterOptions, QuerySourceOptions, SourceOptions, TilejsonResult } from './types';
 export type QuadbinQuerySourceOptions = SourceOptions & QuerySourceOptions & AggregationOptions & FilterOptions;
-export declare const quadbinQuerySource: (options: QuadbinQuerySourceOptions) => Promise<TilejsonResult & WidgetQuerySourceResult>;
+export type QuadbinQuerySourceResponse = TilejsonResult & WidgetQuerySourceResult;
+export declare const quadbinQuerySource: (options: QuadbinQuerySourceOptions) => Promise<QuadbinQuerySourceResponse>;

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

@@ -1,4 +1,5 @@
 import { WidgetTableSourceResult } from '../widget-sources';
 import type { AggregationOptions, FilterOptions, SourceOptions, TableSourceOptions, TilejsonResult } from './types';
 export type QuadbinTableSourceOptions = SourceOptions & TableSourceOptions & AggregationOptions & FilterOptions;
-export declare const quadbinTableSource: (options: QuadbinTableSourceOptions) => Promise<TilejsonResult & WidgetTableSourceResult>;
+export type QuadbinTableSourceResponse = TilejsonResult & WidgetTableSourceResult;
+export declare const quadbinTableSource: (options: QuadbinTableSourceOptions) => Promise<QuadbinTableSourceResponse>;

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

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

package/build/sources/raster-source.d.ts

@@ -1,3 +1,4 @@
 import type { FilterOptions, SourceOptions, TilejsonResult, TilesetSourceOptions } from './types';
 export type RasterSourceOptions = SourceOptions & TilesetSourceOptions & FilterOptions;
-export declare const rasterSource: (options: RasterSourceOptions) => Promise<TilejsonResult>;
+export type RasterSourceResponse = TilejsonResult;
+export declare const rasterSource: (options: RasterSourceOptions) => Promise<RasterSourceResponse>;

package/build/sources/types.d.ts

@@ -38,6 +38,30 @@ export type SourceOptionalOptions = {
      * @default {@link DEFAULT_MAX_LENGTH_URL}
      */
     maxLengthURL?: number;
+    /**
+     * 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;
+    /**
+     * The type of geospatial support. Defaults to `'geo'`.
+     */
+    spatialDataType?: SpatialDataType;
+    /**
+     * 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;
     /**
      * By default, local in-memory caching is enabled.
      */
@@ -73,6 +97,10 @@ export type AggregationOptions = {
      * @default 6 for quadbin and 4 for h3 sources
      */
     aggregationResLevel?: number;
+    /**
+     * Original resolution of the spatial index data as stored in the DW
+     */
+    dataResolution?: number;
 };
 export type FilterOptions = {
     /**
@@ -81,28 +109,8 @@ export type FilterOptions = {
     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. */
+    /** Full SQL query with query paremeter placeholders (if any). */
     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.
      *
@@ -128,6 +136,14 @@ export type QuerySourceOptions = {
      *     ```
      */
     queryParameters?: QueryParameters;
+    /**
+     * Comma-separated aggregation expressions. If assigned on a vector source, source is grouped by geometry and then aggregated.
+     *
+     * Example:
+     *
+     *     1 as value, avg(rev) as average_revenue
+     */
+    aggregationExp?: string;
 };
 export type TableSourceOptions = {
     /**
@@ -135,25 +151,13 @@ export type TableSourceOptions = {
      */
     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.
+     * Comma-separated aggregation expressions. If assigned on a vector source, source is grouped by geometry and then aggregated.
      *
-     * Supported `tileResolution` values, with corresponding grid sizes:
+     * Example:
      *
-     * - 0.25: 256x256
-     * - 0.5: 512x512
-     * - 1: 1024x1024
-     * - 2: 2048x2048
-     * - 4: 4096x4096
+     *     1 as value, avg(rev) as average_revenue
      */
-    tileResolution?: TileResolution;
+    aggregationExp?: string;
 };
 export type TilesetSourceOptions = {
     /**
@@ -170,6 +174,13 @@ export type ColumnsOption = {
     columns?: string[];
 };
 export type SpatialDataType = 'geo' | 'h3' | 'quadbin';
+/**
+ * Strategy used for covering spatial filter geometry with spatial indexes.
+ * See https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/quadbin#quadbin_polyfill_mode
+ * or https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/sql-reference/h3#h3_polyfill_mode for more information.
+ * @internalRemarks Source: cloud-native maps-api
+ * */
+export type SpatialFilterPolyfillMode = 'center' | 'intersects' | 'contains';
 export type TilejsonMapInstantiation = MapInstantiation & {
     tilejson: {
         url: string[];

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

@@ -1,4 +1,5 @@
 import { WidgetQuerySourceResult } from '../widget-sources/index.js';
 import type { FilterOptions, SourceOptions, QuerySourceOptions, TilejsonResult, ColumnsOption } from './types';
 export type VectorQuerySourceOptions = SourceOptions & QuerySourceOptions & FilterOptions & ColumnsOption;
-export declare const vectorQuerySource: (options: VectorQuerySourceOptions) => Promise<TilejsonResult & WidgetQuerySourceResult>;
+export type VectorQuerySourceResponse = TilejsonResult & WidgetQuerySourceResult;
+export declare const vectorQuerySource: (options: VectorQuerySourceOptions) => Promise<VectorQuerySourceResponse>;

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

@@ -1,4 +1,5 @@
 import { WidgetTableSourceResult } from '../widget-sources/index.js';
 import type { FilterOptions, ColumnsOption, SourceOptions, TableSourceOptions, TilejsonResult } from './types';
 export type VectorTableSourceOptions = SourceOptions & TableSourceOptions & FilterOptions & ColumnsOption;
-export declare const vectorTableSource: (options: VectorTableSourceOptions) => Promise<TilejsonResult & WidgetTableSourceResult>;
+export type VectorTableSourceResponse = TilejsonResult & WidgetTableSourceResult;
+export declare const vectorTableSource: (options: VectorTableSourceOptions) => Promise<VectorTableSourceResponse>;

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

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

package/build/spatial-index.d.ts

@@ -0,0 +1,8 @@
+import type { ModelSource } from './models/model';
+import type { AggregationOptions } from './sources/types';
+import type { ViewState } from './widget-sources';
+export declare function getSpatialFiltersResolution(source: Partial<ModelSource & AggregationOptions>, viewState: ViewState): number | undefined;
+export declare function getHexagonResolution(viewport: {
+    zoom: number;
+    latitude: number;
+}, tileSize: number): number;

package/build/utils.d.ts

@@ -14,7 +14,7 @@ type Row<T> = Record<string, T> | Record<string, T>[] | T[] | T;
  */
 export declare function normalizeObjectKeys<T, R extends Row<T>>(el: R): R;
 /** @internalRemarks Source: @carto/react-core */
-export declare function assert(condition: unknown, message: string): void;
+export declare function assert(condition: unknown, message: string): asserts condition;
 /**
  * @internalRemarks Source: @carto/react-core
  * @internal

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

@@ -1,11 +1,19 @@
-import { TileResolution } from '../sources/types';
+import { SpatialFilterPolyfillMode, TileResolution } from '../sources/types';
 import { GroupDateType, SortColumnType, SortDirection, SpatialFilter } from '../types';
 /******************************************************************************
  * WIDGET API REQUESTS
  */
+export interface ViewState {
+    zoom: number;
+    latitude: number;
+    longitude: number;
+}
 /** Common options for {@link WidgetBaseSource} requests. */
 interface BaseRequestOptions {
     spatialFilter?: SpatialFilter;
+    spatialFiltersMode?: SpatialFilterPolyfillMode;
+    /** Required for table- and query-based spatial index sources (H3, Quadbin). */
+    spatialIndexReferenceViewState?: ViewState;
     abortController?: AbortController;
     filterOwner?: string;
 }

package/build/widget-sources/widget-base-source.d.ts

@@ -1,11 +1,10 @@
-import { CategoryRequestOptions, CategoryResponse, FeaturesRequestOptions, FeaturesResponse, FormulaRequestOptions, FormulaResponse, HistogramRequestOptions, HistogramResponse, RangeRequestOptions, RangeResponse, ScatterRequestOptions, ScatterResponse, TableRequestOptions, TableResponse, TimeSeriesRequestOptions, TimeSeriesResponse } from './types.js';
-import { FilterLogicalOperator, Filter } from '../types.js';
+import { CategoryRequestOptions, CategoryResponse, FeaturesRequestOptions, FeaturesResponse, FormulaRequestOptions, FormulaResponse, HistogramRequestOptions, HistogramResponse, RangeRequestOptions, RangeResponse, ScatterRequestOptions, ScatterResponse, TableRequestOptions, TableResponse, TimeSeriesRequestOptions, TimeSeriesResponse, ViewState } from './types.js';
+import { FilterLogicalOperator, Filter, SpatialFilter } from '../types.js';
 import { ModelSource } from '../models/model.js';
 import { SourceOptions } from '../sources/index.js';
 import { ApiVersion } from '../constants.js';
 export interface WidgetBaseSourceProps extends Omit<SourceOptions, 'filters'> {
     apiVersion?: ApiVersion;
-    geoColumn?: string;
     filters?: Record<string, Filter>;
     filtersLogicalOperator?: FilterLogicalOperator;
 }
@@ -27,6 +26,7 @@ export declare abstract class WidgetBaseSource<Props extends WidgetBaseSourcePro
      */
     protected abstract getModelSource(owner: string | undefined): ModelSource;
     protected _getModelSource(owner?: string): Omit<ModelSource, 'type' | 'data'>;
+    protected _getSpatialFiltersResolution(source: Omit<ModelSource, 'type' | 'data'>, spatialFilter?: SpatialFilter, referenceViewState?: ViewState): number | undefined;
     /****************************************************************************
      * CATEGORIES
      */

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.4.2",
+  "version": "0.4.4",
   "license": "MIT",
   "publishConfig": {
     "access": "public",

package/src/api/query.ts

@@ -12,8 +12,7 @@ import {buildQueryUrl} from './endpoints';
 import {requestWithParameters} from './request-with-parameters';
 import {APIErrorContext} from './carto-api-error';
 
-export type QueryOptions = SourceOptions &
-  Omit<QuerySourceOptions, 'spatialDataColumn'>;
+export type QueryOptions = SourceOptions & QuerySourceOptions;
 type UrlParameters = {q: string; queryParameters?: string};
 
 export const query = async function (

package/src/index.ts

@@ -2,6 +2,7 @@ export * from './client.js';
 export * from './constants.js';
 export * from './filters.js';
 export * from './geo.js';
+export * from './sources/index.js';
 export * from './widget-sources/index.js';
 export * from './types.js';
 
@@ -15,39 +16,3 @@ export {
   query,
   requestWithParameters,
 } from './api/index.js';
-
-export {
-  BoundaryQuerySourceOptions,
-  BoundaryTableSourceOptions,
-  GeojsonResult,
-  H3QuerySourceOptions,
-  H3TableSourceOptions,
-  H3TilesetSourceOptions,
-  JsonResult,
-  QuadbinQuerySourceOptions,
-  QuadbinTableSourceOptions,
-  QuadbinTilesetSourceOptions,
-  QueryResult,
-  QuerySourceOptions,
-  RasterSourceOptions,
-  SOURCE_DEFAULTS,
-  SourceOptions,
-  TableSourceOptions,
-  TilejsonResult,
-  TilesetSourceOptions,
-  VectorQuerySourceOptions,
-  VectorTableSourceOptions,
-  VectorTilesetSourceOptions,
-  boundaryQuerySource,
-  boundaryTableSource,
-  h3QuerySource,
-  h3TableSource,
-  h3TilesetSource,
-  quadbinQuerySource,
-  quadbinTableSource,
-  quadbinTilesetSource,
-  rasterSource,
-  vectorQuerySource,
-  vectorTableSource,
-  vectorTilesetSource,
-} from './sources/index.js';

package/src/models/model.ts

@@ -7,9 +7,10 @@ import {
   SpatialFilter,
 } from '../types.js';
 import {$TODO} from '../types-internal.js';
-import {assert} from '../utils.js';
+import {assert, isPureObject} from '../utils.js';
 import {ModelRequestOptions, makeCall} from './common.js';
 import {ApiVersion} from '../constants.js';
+import {SpatialDataType, SpatialFilterPolyfillMode} from '../sources/types.js';
 
 /** @internalRemarks Source: @carto/react-api */
 const AVAILABLE_MODELS = [
@@ -35,9 +36,14 @@ export interface ModelSource {
   data: string;
   filters?: Record<string, Filter>;
   filtersLogicalOperator?: FilterLogicalOperator;
-  geoColumn?: string;
   spatialFilter?: SpatialFilter;
   queryParameters?: QueryParameters;
+  spatialDataColumn?: string;
+  spatialDataType?: SpatialDataType;
+  spatialFiltersResolution?: number;
+  spatialFiltersMode?: SpatialFilterPolyfillMode;
+  /** original resolution of the spatial index data as stored in the DW */
+  dataResolution?: number;
 }
 
 const {V3} = ApiVersion;
@@ -79,50 +85,51 @@ export function executeModel(props: {
     data,
     filters,
     filtersLogicalOperator = 'and',
-    geoColumn = DEFAULT_GEO_COLUMN,
+    spatialDataType = 'geo',
+    spatialFiltersMode = 'intersects',
+    spatialFiltersResolution = 0,
   } = source;
 
-  const queryParameters = source.queryParameters
-    ? JSON.stringify(source.queryParameters)
-    : '';
-
-  const queryParams: Record<string, string> = {
+  const queryParams: Record<string, unknown> = {
     type,
     client: clientId,
     source: data,
-    params: JSON.stringify(params),
-    queryParameters,
-    filters: JSON.stringify(filters),
+    params,
+    queryParameters: source.queryParameters || '',
+    filters,
     filtersLogicalOperator,
   };
 
+  const spatialDataColumn = source.spatialDataColumn || DEFAULT_GEO_COLUMN;
+
   // Picking Model API requires 'spatialDataColumn'.
   if (model === 'pick') {
-    queryParams.spatialDataColumn = geoColumn;
+    queryParams.spatialDataColumn = spatialDataColumn;
   }
 
-  // API supports multiple filters, we apply it only to geoColumn
+  // API supports multiple filters, we apply it only to spatialDataColumn
   const spatialFilters = source.spatialFilter
-    ? {[geoColumn]: source.spatialFilter}
+    ? {[spatialDataColumn]: source.spatialFilter}
     : undefined;
 
   if (spatialFilters) {
-    queryParams.spatialFilters = JSON.stringify(spatialFilters);
+    queryParams.spatialFilters = spatialFilters;
+    queryParams.spatialDataColumn = spatialDataColumn;
+    queryParams.spatialDataType = spatialDataType;
+  }
+
+  if (spatialDataType !== 'geo') {
+    if (spatialFiltersResolution > 0) {
+      queryParams.spatialFiltersResolution = spatialFiltersResolution;
+    }
+    queryParams.spatialFiltersMode = spatialFiltersMode;
   }
 
   const urlWithSearchParams =
-    url + '?' + new URLSearchParams(queryParams).toString();
+    url + '?' + objectToURLSearchParams(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 as $TODO;
-    queryParams.filters = filters as $TODO;
-    queryParams.queryParameters = source.queryParameters as $TODO;
-    if (spatialFilters) {
-      queryParams.spatialFilters = spatialFilters as $TODO;
-    }
   }
   return makeCall({
     url,
@@ -134,3 +141,19 @@ export function executeModel(props: {
     },
   });
 }
+
+function objectToURLSearchParams(object: Record<string, unknown>) {
+  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;
+}

package/src/sources/boundary-query-source.ts

@@ -21,9 +21,11 @@ type UrlParameters = {
   queryParameters?: Record<string, unknown> | unknown[];
 };
 
+export type BoundaryQuerySourceResponse = TilejsonResult;
+
 export const boundaryQuerySource = async function (
   options: BoundaryQuerySourceOptions
-): Promise<TilejsonResult> {
+): Promise<BoundaryQuerySourceResponse> {
   const {
     columns,
     filters,
@@ -49,5 +51,5 @@ export const boundaryQuerySource = async function (
     'boundary',
     options,
     urlParameters
-  ) as Promise<TilejsonResult>;
+  ) as Promise<BoundaryQuerySourceResponse>;
 };

package/src/sources/boundary-table-source.ts

@@ -18,9 +18,11 @@ type UrlParameters = {
   propertiesTableName: string;
 };
 
+export type BoundaryTableSourceResponse = TilejsonResult;
+
 export const boundaryTableSource = async function (
   options: BoundaryTableSourceOptions
-): Promise<TilejsonResult> {
+): Promise<BoundaryTableSourceResponse> {
   const {filters, tilesetTableName, columns, propertiesTableName} = options;
   const urlParameters: UrlParameters = {
     tilesetTableName,
@@ -37,5 +39,5 @@ export const boundaryTableSource = async function (
     'boundary',
     options,
     urlParameters
-  ) as Promise<TilejsonResult>;
+  ) as Promise<BoundaryTableSourceResponse>;
 };

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

@@ -19,6 +19,7 @@ export type H3QuerySourceOptions = SourceOptions &
   QuerySourceOptions &
   AggregationOptions &
   FilterOptions;
+
 type UrlParameters = {
   aggregationExp: string;
   aggregationResLevel?: string;
@@ -29,9 +30,11 @@ type UrlParameters = {
   filters?: Record<string, unknown>;
 };
 
+export type H3QuerySourceResponse = TilejsonResult & WidgetQuerySourceResult;
+
 export const h3QuerySource = async function (
   options: H3QuerySourceOptions
-): Promise<TilejsonResult & WidgetQuerySourceResult> {
+): Promise<H3QuerySourceResponse> {
   const {
     aggregationExp,
     aggregationResLevel = DEFAULT_AGGREGATION_RES_LEVEL_H3,
@@ -59,7 +62,12 @@ export const h3QuerySource = async function (
   return baseSource<UrlParameters>('query', options, urlParameters).then(
     (result) => ({
       ...(result as TilejsonResult),
-      widgetSource: new WidgetQuerySource(options),
+      widgetSource: new WidgetQuerySource({
+        ...options,
+        // NOTE: passing redundant spatialDataColumn here to apply the default value 'h3'
+        spatialDataColumn,
+        spatialDataType: 'h3',
+      }),
     })
   );
 };