@carto/api-client 0.5.30-alpha.3cf7d80.116 → 0.5.30-alpha.bdcd62f.119

package/build/api-client.d.cts

@@ -184,8 +184,22 @@ type AggregationType = 'count' | 'avg' | 'min' | 'max' | 'sum' | 'custom';
 /******************************************************************************
  * FILTERS
  */
+/** A spatial filter expressed as a GeoJSON polygon, applied client- or server-side. */
+type GeometrySpatialFilter = Polygon | MultiPolygon;
+/**
+ * Filter restricting a widget query to a selection of spatial-index cells,
+ * e.g. from point-and-click on an H3 or Quadbin layer.
+ */
+interface SpatialIndexFilter {
+    /** Selected cell ids. */
+    indexes: string[];
+    /** Spatial index type of the filtered column. */
+    type: 'h3' | 'h3int' | 'quadbin';
+}
 /** @privateRemarks Source: @carto/react-api */
-type SpatialFilter = Polygon | MultiPolygon;
+type SpatialFilter = GeometrySpatialFilter | SpatialIndexFilter;
+/** True when a {@link SpatialFilter} selects spatial-index cells rather than a polygon. */
+declare function isSpatialIndexFilter(spatialFilter: SpatialFilter): spatialFilter is SpatialIndexFilter;
 /** @privateRemarks Source: @deck.gl/carto */
 interface Filters {
     [column: string]: Filter;
@@ -289,6 +303,54 @@ type _DataFilterExtensionProps = {
  */
 declare function getDataFilterExtensionProps(filters: Filters, filtersLogicalOperator?: FilterLogicalOperator): _DataFilterExtensionProps;
 
+/**
+ * How requests to the CARTO APIs are authenticated.
+ *
+ * - `'token'` (default): every request carries `Authorization: Bearer <accessToken>`.
+ * - `'session'`: requests carry NO Authorization header and are sent with
+ *   `credentials: 'same-origin'`. Authentication is delegated to the server
+ *   behind `apiBaseUrl` — typically a same-origin proxy that attaches the
+ *   credential server-side from a session cookie. Used by CARTO hosted apps
+ *   (`apiBaseUrl: '/app/_proxy/<slug>'`) and other single-origin deployments
+ *   where the access token must never be exposed to JavaScript.
+ */
+type AuthMode = 'token' | 'session';
+/**
+ * Authentication options shared by sources, queries, widget sources and
+ * fetchMap:
+ *
+ * - token mode (default): `accessToken` is required.
+ * - session mode: `authMode: 'session'` and no `accessToken`.
+ *
+ * Validated at request time by {@link buildAuthHeaders}.
+ */
+type AuthOptions = {
+    /** Carto platform access token. Required unless `authMode` is `'session'`. */
+    accessToken?: string;
+    /** @default 'token' */
+    authMode?: AuthMode;
+};
+/**
+ * Builds the Authorization headers for a request: a Bearer header in token
+ * mode, no auth headers at all in session mode (the server-side session
+ * middleware must see the header absent to engage). Also validates the
+ * options, so every request path fails fast on a misconfiguration.
+ */
+declare function buildAuthHeaders(options: AuthOptions): Record<string, string>;
+/**
+ * `fetch()` credentials for the given auth mode. Session mode must send the
+ * cookie explicitly; token mode preserves today's behavior (unset).
+ */
+declare function getAuthCredentials(authMode?: AuthMode): RequestCredentials | undefined;
+/**
+ * Rewrites an absolute CARTO API URL (e.g. a tilejson `tiles[]` template or
+ * the map-instantiation `dataUrl`, which always point at the tenant API host)
+ * onto the configured `apiBaseUrl`. In session mode the browser cannot reach
+ * the API host directly — every request must go through the same-origin
+ * proxy that `apiBaseUrl` points at. Relative URLs are returned unchanged.
+ */
+declare function rewriteUrlForSessionMode(url: string, apiBaseUrl: string): string;
+
 type APIRequestType = 'Map data' | 'Map instantiation' | 'Public map' | 'Tile stats' | 'SQL' | 'Basemap style';
 type APIErrorContext = {
     requestType: APIRequestType;
@@ -338,9 +400,7 @@ declare enum RasterBandColorinterp {
     Palette = "palette"
 }
 
-type SourceRequiredOptions = {
-    /** Carto platform access token. */
-    accessToken: string;
+type SourceRequiredOptions = AuthOptions & {
     /** Data warehouse connection name in Carto platform. */
     connectionName: string;
 };
@@ -712,7 +772,13 @@ type RasterMetadata = {
     pixel_resolution: number;
 };
 type TilejsonResult = Tilejson & {
-    accessToken: string;
+    /**
+     * Access token used to fetch the tiles. Absent when the source was created
+     * with `authMode: 'session'` — tile URLs are then rewritten onto the
+     * configured `apiBaseUrl` and authenticated by the server (session cookie),
+     * so consumers must not attach an Authorization header.
+     */
+    accessToken?: string;
     schema: SchemaField[];
 };
 type QueryResult = {
@@ -740,7 +806,7 @@ type QueryOptions = SourceOptions & QuerySourceOptions & {
 };
 declare const query: (options: QueryOptions) => Promise<QueryResult>;
 
-declare function requestWithParameters<T = any>({ baseUrl, parameters, headers: customHeaders, errorContext, maxLengthURL, localCache, signal, }: {
+declare function requestWithParameters<T = any>({ baseUrl, parameters, headers: customHeaders, errorContext, maxLengthURL, localCache, signal, credentials, }: {
     baseUrl: string;
     parameters?: Record<string, unknown>;
     headers?: Record<string, string>;
@@ -748,6 +814,8 @@ declare function requestWithParameters<T = any>({ baseUrl, parameters, headers:
     maxLengthURL?: number;
     localCache?: LocalCacheOptions;
     signal?: AbortSignal;
+    /** Forwarded to `fetch()`. Session auth mode passes 'same-origin'. */
+    credentials?: RequestCredentials;
 }): Promise<T>;
 /**
  * Clears the HTTP response cache for all requests using the default cache.
@@ -1684,7 +1752,8 @@ interface ModelSource {
     type: MapType;
     apiVersion: ApiVersion;
     apiBaseUrl: string;
-    accessToken: string;
+    accessToken?: string;
+    authMode?: AuthMode;
     clientId: string;
     connectionName: string;
     data: string;
@@ -1783,7 +1852,7 @@ declare const filterFunctions: Record<FilterType, FilterFunction>;
 
 declare function geojsonFeatures({ geojson, spatialFilter, uniqueIdProperty, }: {
     geojson: FeatureCollection;
-    spatialFilter: SpatialFilter;
+    spatialFilter: GeometrySpatialFilter;
     uniqueIdProperty?: string;
 }): FeatureData[];
 
@@ -1793,7 +1862,7 @@ type TileFeatures = {
     tileFormat: TileFormat;
     spatialDataType: SpatialDataType;
     spatialDataColumn?: string;
-    spatialFilter?: SpatialFilter;
+    spatialFilter?: GeometrySpatialFilter;
     uniqueIdProperty?: string;
     rasterMetadata?: RasterMetadata;
     storeGeometry?: boolean;
@@ -1815,14 +1884,14 @@ type GeometryExtractOptions = {
 declare function tileFeaturesGeometries({ tiles, tileFormat, spatialFilter, uniqueIdProperty, options, }: {
     tiles: Tile[];
     tileFormat?: TileFormat;
-    spatialFilter?: SpatialFilter;
+    spatialFilter?: GeometrySpatialFilter;
     uniqueIdProperty?: string;
     options?: GeometryExtractOptions;
 }): FeatureData[];
 
 type TileFeaturesSpatialIndexOptions = {
     tiles: SpatialIndexTile[];
-    spatialFilter?: SpatialFilter;
+    spatialFilter?: GeometrySpatialFilter;
     spatialDataColumn: string;
     spatialDataType: SpatialDataType;
 };
@@ -1869,7 +1938,7 @@ declare class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePr
      */
     loadGeoJSON({ geojson, spatialFilter, }: {
         geojson: FeatureCollection;
-        spatialFilter: SpatialFilter;
+        spatialFilter: GeometrySpatialFilter;
     }): void;
     getFeatures(): Promise<FeaturesResponse>;
     getFormula({ column, operation, joinOperation, filters, filterOwner, spatialFilter, }: FormulaRequestOptions): Promise<FormulaResponse>;
@@ -1950,7 +2019,7 @@ declare class WidgetTilesetSource<Props extends WidgetTilesetSourceProps = Widge
      */
     loadGeoJSON({ geojson, spatialFilter, }: {
         geojson: FeatureCollection;
-        spatialFilter: SpatialFilter;
+        spatialFilter: GeometrySpatialFilter;
     }): void;
     getFeatures(): Promise<FeaturesResponse>;
     getFormula({ signal, ...options }: FormulaRequestOptions): Promise<FormulaResponse>;
@@ -2137,6 +2206,22 @@ declare function _getHexagonResolution(viewport: {
     zoom: number;
     latitude: number;
 }, tileSize: number): number;
+/**
+ * Quadbin level at which the maps-api dynamic tiler implicitly aggregates a
+ * point source for a given tile zoom and resolution. Lets a client reproduce
+ * that level — and so the aggregation cell a point falls into — without an
+ * extra round-trip to the server.
+ *
+ * Ported verbatim from the maps-api dynamic tiler (`getPointsAggregationLevel`).
+ * The base offset mirrors the server default of
+ * `MAPS_API_V3_DYNAMIC_TILES_POINTS_AGGREGATION_LEVEL`; a deployment that
+ * overrides that env var drifts from this computation.
+ * @internal
+ */
+declare function getPointsAggregationLevel({ tileResolution, zoomLevel, }: {
+    tileResolution: TileResolution;
+    zoomLevel: number;
+}): number;
 
 /** @privateRemarks Source: @carto/react-core */
 type AggregationFunction = (values: unknown[] | FeatureData[], keys?: string[] | string, joinOperation?: AggregationType) => number;
@@ -2277,4 +2362,4 @@ declare function getColumnNameFromGeoColumn(geoColumn: string | null | undefined
  */
 declare function getSpatialIndexFromGeoColumn(geoColumn: string): SpatialIndex | null;
 
-export { type APIErrorContext, type APIRequestType, AUDIT_TAGS, type AddFilterOptions, type AggregationFunction, type AggregationType, AggregationTypes, type AggregationsRequestOptions, type AggregationsResponse, ApiVersion, type Attribute, _default as BASEMAP, type BaseRequestOptions, type Basemap, type BoundaryQuerySourceOptions, type BoundaryQuerySourceResponse, type BoundaryTableSourceOptions, type BoundaryTableSourceResponse, CARTO_SOURCES, CartoAPIError, type CategoryOrderBy, type CategoryRequestOptions, type CategoryResponse, type CategoryResponseEntry, type CategoryResponseRaw, CellSet, type ColumnsOption, type D3Scale, DEFAULT_API_BASE_URL, type ExtentRequestOptions, type ExtentResponse, FEATURE_GEOM_PROPERTY, type FeaturesRequestOptions, type FeaturesResponse, type FetchMapOptions, type FetchMapResult, type Filter, type FilterFunction, type FilterInterval, type FilterIntervalComplete, type FilterIntervalExtremum, type FilterLogicalOperator, type FilterOptions, FilterType, type Filters, type Format, type FormulaRequestOptions, type FormulaResponse, type GetFilterOptions, type GoogleBasemap, type GroupByFeature, type GroupDateType, type H3QuerySourceOptions, type H3QuerySourceResponse, type H3TableSourceOptions, type H3TableSourceResponse, type H3TilesetSourceOptions, type H3TilesetSourceResponse, type HasFilterOptions, type HistogramRequestOptions, type HistogramResponse, type KeplerMapConfig, type Layer, type LayerDescriptor, type LayerType, type MapLibreBasemap, type MapType, type NamedQueryParameter, OPACITY_MAP, OTHERS_CATEGORY_NAME, type ParseMapResult, type PositionalQueryParameter, Provider, type ProviderType, type QuadbinQuerySourceOptions, type QuadbinQuerySourceResponse, type QuadbinTableSourceOptions, type QuadbinTableSourceResponse, type QuadbinTilesetSourceOptions, type QuadbinTilesetSourceResponse, type QueryOptions, type QueryParameterValue, type QueryParameters, type QueryResult, type QuerySourceOptions, type RangeRequestOptions, type RangeResponse, type Raster, RasterBandColorinterp, type RasterBandType, type RasterMetadata, type RasterMetadataBand, type RasterMetadataBandStats, type RasterSourceOptions, type RasterTile, type RemoveFilterOptions, SOURCE_DEFAULTS, type Scale, type ScaleKey, type ScaleType, type Scales, type ScatterPlotFeature, type ScatterRequestOptions, type ScatterResponse, type SchemaField, SchemaFieldType, type SortColumnType, type SortDirection, type SourceOptionalOptions, type SourceOptions, type SourceRequiredOptions, type SpatialDataType, type SpatialFilter, type SpatialFilterPolyfillMode, SpatialIndex, SpatialIndexColumn, type SpatialIndexTile, type StringSearchOptions, TEXT_LABEL_INDEX, TEXT_NUMBER_FORMATTER, TEXT_OUTLINE_OPACITY, type TableRequestOptions, type TableResponse, type TableSourceOptions, type Tile, type TileFeatureExtractOptions, type TileFeatures, type TileFeaturesSpatialIndexOptions, TileFormat, type TileResolution, type Tilejson, type TilejsonResult, type TilesetSourceOptions, type Tilestats, type TimeSeriesRequestOptions, type TimeSeriesResponse, type TrajectoryQuerySourceOptions, type TrajectoryQuerySourceResponse, type TrajectoryTableSourceOptions, type TrajectoryTableSourceResponse, type VectorLayer, type VectorQuerySourceOptions, type VectorQuerySourceResponse, type VectorTableSourceOptions, type VectorTableSourceResponse, type VectorTilesetSourceOptions, type VectorTilesetSourceResponse, type ViewState, type Viewport, type WidgetFeatureGeometryType, WidgetQuerySource, type WidgetQuerySourceResult, WidgetRasterSource, type WidgetRasterSourceProps, type WidgetRasterSourceResult, WidgetRemoteSource, type WidgetRemoteSourceProps, WidgetSource, type WidgetSourceProps, WidgetTableSource, type WidgetTableSourceResult, WidgetTilesetSource, type WidgetTilesetSourceProps, type WidgetTilesetSourceResult, type _DataFilterExtensionProps, ErrorCode as _ErrorCode, type VecExprResult as _VecExprResult, applyLayerGroupFilters as _applyLayerGroupFilters, _buildFeatureFilter, createVecExprEvaluator as _createVecExprEvaluator, domainFromValues as _domainFromValues, evaluateVecExpr as _evaluateVecExpr, fillInMapDatasets as _fillInMapDatasets, fillInTileStats as _fillInTileStats, _getHexagonResolution, getLog10ScaleSteps as _getLog10ScaleSteps, getRasterTileLayerStyleProps as _getRasterTileLayerStyleProps, validateVecExprSyntax as _validateVecExprSyntax, addFilter, aggregate, aggregationFunctions, applyFilters, applySorting, boundaryQuerySource, boundaryTableSource, buildBinaryFeatureFilter, buildPublicMapUrl, buildStatsUrl, calculateClusterRadius, calculateClusterTextFontSize, calculateLayerScale, clearDefaultRequestCache, clearFilters, compileCustomAggregation, configureSource, createColorScale, createPolygonSpatialFilter, createViewportSpatialFilter, fetchBasemapProps, fetchMap, filterFunctions, geojsonFeatures, getApplicableFilters, getClient, getColorAccessor, getColumnNameFromGeoColumn, getDataFilterExtensionProps, getDefaultAggregationExpColumnAliasForLayerType, getFilter, getIconUrlAccessor, getLayerDescriptor, getLayerProps, getMaxMarkerSize, getSizeAccessor, getSorter, getSpatialIndexFromGeoColumn, getTextAccessor, groupValuesByColumn, groupValuesByDateColumn, h3QuerySource, h3TableSource, h3TilesetSource, hasFilter, histogram, makeIntervalComplete, negateAccessor, opacityToAlpha, parseMap, quadbinQuerySource, quadbinTableSource, quadbinTilesetSource, query, rasterSource, removeFilter, requestWithParameters, scaleAggregationResLevel, scatterPlot, setClient, tileFeatures, tileFeaturesGeometries, tileFeaturesSpatialIndex, trajectoryQuerySource, trajectoryTableSource, transformToTileCoords, vectorQuerySource, vectorTableSource, vectorTilesetSource };
+export { type APIErrorContext, type APIRequestType, AUDIT_TAGS, type AddFilterOptions, type AggregationFunction, type AggregationType, AggregationTypes, type AggregationsRequestOptions, type AggregationsResponse, ApiVersion, type Attribute, type AuthMode, type AuthOptions, _default as BASEMAP, type BaseRequestOptions, type Basemap, type BoundaryQuerySourceOptions, type BoundaryQuerySourceResponse, type BoundaryTableSourceOptions, type BoundaryTableSourceResponse, CARTO_SOURCES, CartoAPIError, type CategoryOrderBy, type CategoryRequestOptions, type CategoryResponse, type CategoryResponseEntry, type CategoryResponseRaw, CellSet, type ColumnsOption, type D3Scale, DEFAULT_API_BASE_URL, type ExtentRequestOptions, type ExtentResponse, FEATURE_GEOM_PROPERTY, type FeaturesRequestOptions, type FeaturesResponse, type FetchMapOptions, type FetchMapResult, type Filter, type FilterFunction, type FilterInterval, type FilterIntervalComplete, type FilterIntervalExtremum, type FilterLogicalOperator, type FilterOptions, FilterType, type Filters, type Format, type FormulaRequestOptions, type FormulaResponse, type GeometrySpatialFilter, type GetFilterOptions, type GoogleBasemap, type GroupByFeature, type GroupDateType, type H3QuerySourceOptions, type H3QuerySourceResponse, type H3TableSourceOptions, type H3TableSourceResponse, type H3TilesetSourceOptions, type H3TilesetSourceResponse, type HasFilterOptions, type HistogramRequestOptions, type HistogramResponse, type KeplerMapConfig, type Layer, type LayerDescriptor, type LayerType, type MapLibreBasemap, type MapType, type NamedQueryParameter, OPACITY_MAP, OTHERS_CATEGORY_NAME, type ParseMapResult, type PositionalQueryParameter, Provider, type ProviderType, type QuadbinQuerySourceOptions, type QuadbinQuerySourceResponse, type QuadbinTableSourceOptions, type QuadbinTableSourceResponse, type QuadbinTilesetSourceOptions, type QuadbinTilesetSourceResponse, type QueryOptions, type QueryParameterValue, type QueryParameters, type QueryResult, type QuerySourceOptions, type RangeRequestOptions, type RangeResponse, type Raster, RasterBandColorinterp, type RasterBandType, type RasterMetadata, type RasterMetadataBand, type RasterMetadataBandStats, type RasterSourceOptions, type RasterTile, type RemoveFilterOptions, SOURCE_DEFAULTS, type Scale, type ScaleKey, type ScaleType, type Scales, type ScatterPlotFeature, type ScatterRequestOptions, type ScatterResponse, type SchemaField, SchemaFieldType, type SortColumnType, type SortDirection, type SourceOptionalOptions, type SourceOptions, type SourceRequiredOptions, type SpatialDataType, type SpatialFilter, type SpatialFilterPolyfillMode, SpatialIndex, SpatialIndexColumn, type SpatialIndexFilter, type SpatialIndexTile, type StringSearchOptions, TEXT_LABEL_INDEX, TEXT_NUMBER_FORMATTER, TEXT_OUTLINE_OPACITY, type TableRequestOptions, type TableResponse, type TableSourceOptions, type Tile, type TileFeatureExtractOptions, type TileFeatures, type TileFeaturesSpatialIndexOptions, TileFormat, type TileResolution, type Tilejson, type TilejsonResult, type TilesetSourceOptions, type Tilestats, type TimeSeriesRequestOptions, type TimeSeriesResponse, type TrajectoryQuerySourceOptions, type TrajectoryQuerySourceResponse, type TrajectoryTableSourceOptions, type TrajectoryTableSourceResponse, type VectorLayer, type VectorQuerySourceOptions, type VectorQuerySourceResponse, type VectorTableSourceOptions, type VectorTableSourceResponse, type VectorTilesetSourceOptions, type VectorTilesetSourceResponse, type ViewState, type Viewport, type WidgetFeatureGeometryType, WidgetQuerySource, type WidgetQuerySourceResult, WidgetRasterSource, type WidgetRasterSourceProps, type WidgetRasterSourceResult, WidgetRemoteSource, type WidgetRemoteSourceProps, WidgetSource, type WidgetSourceProps, WidgetTableSource, type WidgetTableSourceResult, WidgetTilesetSource, type WidgetTilesetSourceProps, type WidgetTilesetSourceResult, type _DataFilterExtensionProps, ErrorCode as _ErrorCode, type VecExprResult as _VecExprResult, applyLayerGroupFilters as _applyLayerGroupFilters, _buildFeatureFilter, createVecExprEvaluator as _createVecExprEvaluator, domainFromValues as _domainFromValues, evaluateVecExpr as _evaluateVecExpr, fillInMapDatasets as _fillInMapDatasets, fillInTileStats as _fillInTileStats, _getHexagonResolution, getLog10ScaleSteps as _getLog10ScaleSteps, getPointsAggregationLevel as _getPointsAggregationLevel, getRasterTileLayerStyleProps as _getRasterTileLayerStyleProps, validateVecExprSyntax as _validateVecExprSyntax, addFilter, aggregate, aggregationFunctions, applyFilters, applySorting, boundaryQuerySource, boundaryTableSource, buildAuthHeaders, buildBinaryFeatureFilter, buildPublicMapUrl, buildStatsUrl, calculateClusterRadius, calculateClusterTextFontSize, calculateLayerScale, clearDefaultRequestCache, clearFilters, compileCustomAggregation, configureSource, createColorScale, createPolygonSpatialFilter, createViewportSpatialFilter, fetchBasemapProps, fetchMap, filterFunctions, geojsonFeatures, getApplicableFilters, getAuthCredentials, getClient, getColorAccessor, getColumnNameFromGeoColumn, getDataFilterExtensionProps, getDefaultAggregationExpColumnAliasForLayerType, getFilter, getIconUrlAccessor, getLayerDescriptor, getLayerProps, getMaxMarkerSize, getSizeAccessor, getSorter, getSpatialIndexFromGeoColumn, getTextAccessor, groupValuesByColumn, groupValuesByDateColumn, h3QuerySource, h3TableSource, h3TilesetSource, hasFilter, histogram, isSpatialIndexFilter, makeIntervalComplete, negateAccessor, opacityToAlpha, parseMap, quadbinQuerySource, quadbinTableSource, quadbinTilesetSource, query, rasterSource, removeFilter, requestWithParameters, rewriteUrlForSessionMode, scaleAggregationResLevel, scatterPlot, setClient, tileFeatures, tileFeaturesGeometries, tileFeaturesSpatialIndex, trajectoryQuerySource, trajectoryTableSource, transformToTileCoords, vectorQuerySource, vectorTableSource, vectorTilesetSource };

package/build/api-client.d.ts

@@ -184,8 +184,22 @@ type AggregationType = 'count' | 'avg' | 'min' | 'max' | 'sum' | 'custom';
 /******************************************************************************
  * FILTERS
  */
+/** A spatial filter expressed as a GeoJSON polygon, applied client- or server-side. */
+type GeometrySpatialFilter = Polygon | MultiPolygon;
+/**
+ * Filter restricting a widget query to a selection of spatial-index cells,
+ * e.g. from point-and-click on an H3 or Quadbin layer.
+ */
+interface SpatialIndexFilter {
+    /** Selected cell ids. */
+    indexes: string[];
+    /** Spatial index type of the filtered column. */
+    type: 'h3' | 'h3int' | 'quadbin';
+}
 /** @privateRemarks Source: @carto/react-api */
-type SpatialFilter = Polygon | MultiPolygon;
+type SpatialFilter = GeometrySpatialFilter | SpatialIndexFilter;
+/** True when a {@link SpatialFilter} selects spatial-index cells rather than a polygon. */
+declare function isSpatialIndexFilter(spatialFilter: SpatialFilter): spatialFilter is SpatialIndexFilter;
 /** @privateRemarks Source: @deck.gl/carto */
 interface Filters {
     [column: string]: Filter;
@@ -289,6 +303,54 @@ type _DataFilterExtensionProps = {
  */
 declare function getDataFilterExtensionProps(filters: Filters, filtersLogicalOperator?: FilterLogicalOperator): _DataFilterExtensionProps;
 
+/**
+ * How requests to the CARTO APIs are authenticated.
+ *
+ * - `'token'` (default): every request carries `Authorization: Bearer <accessToken>`.
+ * - `'session'`: requests carry NO Authorization header and are sent with
+ *   `credentials: 'same-origin'`. Authentication is delegated to the server
+ *   behind `apiBaseUrl` — typically a same-origin proxy that attaches the
+ *   credential server-side from a session cookie. Used by CARTO hosted apps
+ *   (`apiBaseUrl: '/app/_proxy/<slug>'`) and other single-origin deployments
+ *   where the access token must never be exposed to JavaScript.
+ */
+type AuthMode = 'token' | 'session';
+/**
+ * Authentication options shared by sources, queries, widget sources and
+ * fetchMap:
+ *
+ * - token mode (default): `accessToken` is required.
+ * - session mode: `authMode: 'session'` and no `accessToken`.
+ *
+ * Validated at request time by {@link buildAuthHeaders}.
+ */
+type AuthOptions = {
+    /** Carto platform access token. Required unless `authMode` is `'session'`. */
+    accessToken?: string;
+    /** @default 'token' */
+    authMode?: AuthMode;
+};
+/**
+ * Builds the Authorization headers for a request: a Bearer header in token
+ * mode, no auth headers at all in session mode (the server-side session
+ * middleware must see the header absent to engage). Also validates the
+ * options, so every request path fails fast on a misconfiguration.
+ */
+declare function buildAuthHeaders(options: AuthOptions): Record<string, string>;
+/**
+ * `fetch()` credentials for the given auth mode. Session mode must send the
+ * cookie explicitly; token mode preserves today's behavior (unset).
+ */
+declare function getAuthCredentials(authMode?: AuthMode): RequestCredentials | undefined;
+/**
+ * Rewrites an absolute CARTO API URL (e.g. a tilejson `tiles[]` template or
+ * the map-instantiation `dataUrl`, which always point at the tenant API host)
+ * onto the configured `apiBaseUrl`. In session mode the browser cannot reach
+ * the API host directly — every request must go through the same-origin
+ * proxy that `apiBaseUrl` points at. Relative URLs are returned unchanged.
+ */
+declare function rewriteUrlForSessionMode(url: string, apiBaseUrl: string): string;
+
 type APIRequestType = 'Map data' | 'Map instantiation' | 'Public map' | 'Tile stats' | 'SQL' | 'Basemap style';
 type APIErrorContext = {
     requestType: APIRequestType;
@@ -338,9 +400,7 @@ declare enum RasterBandColorinterp {
     Palette = "palette"
 }
 
-type SourceRequiredOptions = {
-    /** Carto platform access token. */
-    accessToken: string;
+type SourceRequiredOptions = AuthOptions & {
     /** Data warehouse connection name in Carto platform. */
     connectionName: string;
 };
@@ -712,7 +772,13 @@ type RasterMetadata = {
     pixel_resolution: number;
 };
 type TilejsonResult = Tilejson & {
-    accessToken: string;
+    /**
+     * Access token used to fetch the tiles. Absent when the source was created
+     * with `authMode: 'session'` — tile URLs are then rewritten onto the
+     * configured `apiBaseUrl` and authenticated by the server (session cookie),
+     * so consumers must not attach an Authorization header.
+     */
+    accessToken?: string;
     schema: SchemaField[];
 };
 type QueryResult = {
@@ -740,7 +806,7 @@ type QueryOptions = SourceOptions & QuerySourceOptions & {
 };
 declare const query: (options: QueryOptions) => Promise<QueryResult>;
 
-declare function requestWithParameters<T = any>({ baseUrl, parameters, headers: customHeaders, errorContext, maxLengthURL, localCache, signal, }: {
+declare function requestWithParameters<T = any>({ baseUrl, parameters, headers: customHeaders, errorContext, maxLengthURL, localCache, signal, credentials, }: {
     baseUrl: string;
     parameters?: Record<string, unknown>;
     headers?: Record<string, string>;
@@ -748,6 +814,8 @@ declare function requestWithParameters<T = any>({ baseUrl, parameters, headers:
     maxLengthURL?: number;
     localCache?: LocalCacheOptions;
     signal?: AbortSignal;
+    /** Forwarded to `fetch()`. Session auth mode passes 'same-origin'. */
+    credentials?: RequestCredentials;
 }): Promise<T>;
 /**
  * Clears the HTTP response cache for all requests using the default cache.
@@ -1684,7 +1752,8 @@ interface ModelSource {
     type: MapType;
     apiVersion: ApiVersion;
     apiBaseUrl: string;
-    accessToken: string;
+    accessToken?: string;
+    authMode?: AuthMode;
     clientId: string;
     connectionName: string;
     data: string;
@@ -1783,7 +1852,7 @@ declare const filterFunctions: Record<FilterType, FilterFunction>;
 
 declare function geojsonFeatures({ geojson, spatialFilter, uniqueIdProperty, }: {
     geojson: FeatureCollection;
-    spatialFilter: SpatialFilter;
+    spatialFilter: GeometrySpatialFilter;
     uniqueIdProperty?: string;
 }): FeatureData[];
 
@@ -1793,7 +1862,7 @@ type TileFeatures = {
     tileFormat: TileFormat;
     spatialDataType: SpatialDataType;
     spatialDataColumn?: string;
-    spatialFilter?: SpatialFilter;
+    spatialFilter?: GeometrySpatialFilter;
     uniqueIdProperty?: string;
     rasterMetadata?: RasterMetadata;
     storeGeometry?: boolean;
@@ -1815,14 +1884,14 @@ type GeometryExtractOptions = {
 declare function tileFeaturesGeometries({ tiles, tileFormat, spatialFilter, uniqueIdProperty, options, }: {
     tiles: Tile[];
     tileFormat?: TileFormat;
-    spatialFilter?: SpatialFilter;
+    spatialFilter?: GeometrySpatialFilter;
     uniqueIdProperty?: string;
     options?: GeometryExtractOptions;
 }): FeatureData[];
 
 type TileFeaturesSpatialIndexOptions = {
     tiles: SpatialIndexTile[];
-    spatialFilter?: SpatialFilter;
+    spatialFilter?: GeometrySpatialFilter;
     spatialDataColumn: string;
     spatialDataType: SpatialDataType;
 };
@@ -1869,7 +1938,7 @@ declare class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePr
      */
     loadGeoJSON({ geojson, spatialFilter, }: {
         geojson: FeatureCollection;
-        spatialFilter: SpatialFilter;
+        spatialFilter: GeometrySpatialFilter;
     }): void;
     getFeatures(): Promise<FeaturesResponse>;
     getFormula({ column, operation, joinOperation, filters, filterOwner, spatialFilter, }: FormulaRequestOptions): Promise<FormulaResponse>;
@@ -1950,7 +2019,7 @@ declare class WidgetTilesetSource<Props extends WidgetTilesetSourceProps = Widge
      */
     loadGeoJSON({ geojson, spatialFilter, }: {
         geojson: FeatureCollection;
-        spatialFilter: SpatialFilter;
+        spatialFilter: GeometrySpatialFilter;
     }): void;
     getFeatures(): Promise<FeaturesResponse>;
     getFormula({ signal, ...options }: FormulaRequestOptions): Promise<FormulaResponse>;
@@ -2137,6 +2206,22 @@ declare function _getHexagonResolution(viewport: {
     zoom: number;
     latitude: number;
 }, tileSize: number): number;
+/**
+ * Quadbin level at which the maps-api dynamic tiler implicitly aggregates a
+ * point source for a given tile zoom and resolution. Lets a client reproduce
+ * that level — and so the aggregation cell a point falls into — without an
+ * extra round-trip to the server.
+ *
+ * Ported verbatim from the maps-api dynamic tiler (`getPointsAggregationLevel`).
+ * The base offset mirrors the server default of
+ * `MAPS_API_V3_DYNAMIC_TILES_POINTS_AGGREGATION_LEVEL`; a deployment that
+ * overrides that env var drifts from this computation.
+ * @internal
+ */
+declare function getPointsAggregationLevel({ tileResolution, zoomLevel, }: {
+    tileResolution: TileResolution;
+    zoomLevel: number;
+}): number;
 
 /** @privateRemarks Source: @carto/react-core */
 type AggregationFunction = (values: unknown[] | FeatureData[], keys?: string[] | string, joinOperation?: AggregationType) => number;
@@ -2277,4 +2362,4 @@ declare function getColumnNameFromGeoColumn(geoColumn: string | null | undefined
  */
 declare function getSpatialIndexFromGeoColumn(geoColumn: string): SpatialIndex | null;
 
-export { type APIErrorContext, type APIRequestType, AUDIT_TAGS, type AddFilterOptions, type AggregationFunction, type AggregationType, AggregationTypes, type AggregationsRequestOptions, type AggregationsResponse, ApiVersion, type Attribute, _default as BASEMAP, type BaseRequestOptions, type Basemap, type BoundaryQuerySourceOptions, type BoundaryQuerySourceResponse, type BoundaryTableSourceOptions, type BoundaryTableSourceResponse, CARTO_SOURCES, CartoAPIError, type CategoryOrderBy, type CategoryRequestOptions, type CategoryResponse, type CategoryResponseEntry, type CategoryResponseRaw, CellSet, type ColumnsOption, type D3Scale, DEFAULT_API_BASE_URL, type ExtentRequestOptions, type ExtentResponse, FEATURE_GEOM_PROPERTY, type FeaturesRequestOptions, type FeaturesResponse, type FetchMapOptions, type FetchMapResult, type Filter, type FilterFunction, type FilterInterval, type FilterIntervalComplete, type FilterIntervalExtremum, type FilterLogicalOperator, type FilterOptions, FilterType, type Filters, type Format, type FormulaRequestOptions, type FormulaResponse, type GetFilterOptions, type GoogleBasemap, type GroupByFeature, type GroupDateType, type H3QuerySourceOptions, type H3QuerySourceResponse, type H3TableSourceOptions, type H3TableSourceResponse, type H3TilesetSourceOptions, type H3TilesetSourceResponse, type HasFilterOptions, type HistogramRequestOptions, type HistogramResponse, type KeplerMapConfig, type Layer, type LayerDescriptor, type LayerType, type MapLibreBasemap, type MapType, type NamedQueryParameter, OPACITY_MAP, OTHERS_CATEGORY_NAME, type ParseMapResult, type PositionalQueryParameter, Provider, type ProviderType, type QuadbinQuerySourceOptions, type QuadbinQuerySourceResponse, type QuadbinTableSourceOptions, type QuadbinTableSourceResponse, type QuadbinTilesetSourceOptions, type QuadbinTilesetSourceResponse, type QueryOptions, type QueryParameterValue, type QueryParameters, type QueryResult, type QuerySourceOptions, type RangeRequestOptions, type RangeResponse, type Raster, RasterBandColorinterp, type RasterBandType, type RasterMetadata, type RasterMetadataBand, type RasterMetadataBandStats, type RasterSourceOptions, type RasterTile, type RemoveFilterOptions, SOURCE_DEFAULTS, type Scale, type ScaleKey, type ScaleType, type Scales, type ScatterPlotFeature, type ScatterRequestOptions, type ScatterResponse, type SchemaField, SchemaFieldType, type SortColumnType, type SortDirection, type SourceOptionalOptions, type SourceOptions, type SourceRequiredOptions, type SpatialDataType, type SpatialFilter, type SpatialFilterPolyfillMode, SpatialIndex, SpatialIndexColumn, type SpatialIndexTile, type StringSearchOptions, TEXT_LABEL_INDEX, TEXT_NUMBER_FORMATTER, TEXT_OUTLINE_OPACITY, type TableRequestOptions, type TableResponse, type TableSourceOptions, type Tile, type TileFeatureExtractOptions, type TileFeatures, type TileFeaturesSpatialIndexOptions, TileFormat, type TileResolution, type Tilejson, type TilejsonResult, type TilesetSourceOptions, type Tilestats, type TimeSeriesRequestOptions, type TimeSeriesResponse, type TrajectoryQuerySourceOptions, type TrajectoryQuerySourceResponse, type TrajectoryTableSourceOptions, type TrajectoryTableSourceResponse, type VectorLayer, type VectorQuerySourceOptions, type VectorQuerySourceResponse, type VectorTableSourceOptions, type VectorTableSourceResponse, type VectorTilesetSourceOptions, type VectorTilesetSourceResponse, type ViewState, type Viewport, type WidgetFeatureGeometryType, WidgetQuerySource, type WidgetQuerySourceResult, WidgetRasterSource, type WidgetRasterSourceProps, type WidgetRasterSourceResult, WidgetRemoteSource, type WidgetRemoteSourceProps, WidgetSource, type WidgetSourceProps, WidgetTableSource, type WidgetTableSourceResult, WidgetTilesetSource, type WidgetTilesetSourceProps, type WidgetTilesetSourceResult, type _DataFilterExtensionProps, ErrorCode as _ErrorCode, type VecExprResult as _VecExprResult, applyLayerGroupFilters as _applyLayerGroupFilters, _buildFeatureFilter, createVecExprEvaluator as _createVecExprEvaluator, domainFromValues as _domainFromValues, evaluateVecExpr as _evaluateVecExpr, fillInMapDatasets as _fillInMapDatasets, fillInTileStats as _fillInTileStats, _getHexagonResolution, getLog10ScaleSteps as _getLog10ScaleSteps, getRasterTileLayerStyleProps as _getRasterTileLayerStyleProps, validateVecExprSyntax as _validateVecExprSyntax, addFilter, aggregate, aggregationFunctions, applyFilters, applySorting, boundaryQuerySource, boundaryTableSource, buildBinaryFeatureFilter, buildPublicMapUrl, buildStatsUrl, calculateClusterRadius, calculateClusterTextFontSize, calculateLayerScale, clearDefaultRequestCache, clearFilters, compileCustomAggregation, configureSource, createColorScale, createPolygonSpatialFilter, createViewportSpatialFilter, fetchBasemapProps, fetchMap, filterFunctions, geojsonFeatures, getApplicableFilters, getClient, getColorAccessor, getColumnNameFromGeoColumn, getDataFilterExtensionProps, getDefaultAggregationExpColumnAliasForLayerType, getFilter, getIconUrlAccessor, getLayerDescriptor, getLayerProps, getMaxMarkerSize, getSizeAccessor, getSorter, getSpatialIndexFromGeoColumn, getTextAccessor, groupValuesByColumn, groupValuesByDateColumn, h3QuerySource, h3TableSource, h3TilesetSource, hasFilter, histogram, makeIntervalComplete, negateAccessor, opacityToAlpha, parseMap, quadbinQuerySource, quadbinTableSource, quadbinTilesetSource, query, rasterSource, removeFilter, requestWithParameters, scaleAggregationResLevel, scatterPlot, setClient, tileFeatures, tileFeaturesGeometries, tileFeaturesSpatialIndex, trajectoryQuerySource, trajectoryTableSource, transformToTileCoords, vectorQuerySource, vectorTableSource, vectorTilesetSource };
+export { type APIErrorContext, type APIRequestType, AUDIT_TAGS, type AddFilterOptions, type AggregationFunction, type AggregationType, AggregationTypes, type AggregationsRequestOptions, type AggregationsResponse, ApiVersion, type Attribute, type AuthMode, type AuthOptions, _default as BASEMAP, type BaseRequestOptions, type Basemap, type BoundaryQuerySourceOptions, type BoundaryQuerySourceResponse, type BoundaryTableSourceOptions, type BoundaryTableSourceResponse, CARTO_SOURCES, CartoAPIError, type CategoryOrderBy, type CategoryRequestOptions, type CategoryResponse, type CategoryResponseEntry, type CategoryResponseRaw, CellSet, type ColumnsOption, type D3Scale, DEFAULT_API_BASE_URL, type ExtentRequestOptions, type ExtentResponse, FEATURE_GEOM_PROPERTY, type FeaturesRequestOptions, type FeaturesResponse, type FetchMapOptions, type FetchMapResult, type Filter, type FilterFunction, type FilterInterval, type FilterIntervalComplete, type FilterIntervalExtremum, type FilterLogicalOperator, type FilterOptions, FilterType, type Filters, type Format, type FormulaRequestOptions, type FormulaResponse, type GeometrySpatialFilter, type GetFilterOptions, type GoogleBasemap, type GroupByFeature, type GroupDateType, type H3QuerySourceOptions, type H3QuerySourceResponse, type H3TableSourceOptions, type H3TableSourceResponse, type H3TilesetSourceOptions, type H3TilesetSourceResponse, type HasFilterOptions, type HistogramRequestOptions, type HistogramResponse, type KeplerMapConfig, type Layer, type LayerDescriptor, type LayerType, type MapLibreBasemap, type MapType, type NamedQueryParameter, OPACITY_MAP, OTHERS_CATEGORY_NAME, type ParseMapResult, type PositionalQueryParameter, Provider, type ProviderType, type QuadbinQuerySourceOptions, type QuadbinQuerySourceResponse, type QuadbinTableSourceOptions, type QuadbinTableSourceResponse, type QuadbinTilesetSourceOptions, type QuadbinTilesetSourceResponse, type QueryOptions, type QueryParameterValue, type QueryParameters, type QueryResult, type QuerySourceOptions, type RangeRequestOptions, type RangeResponse, type Raster, RasterBandColorinterp, type RasterBandType, type RasterMetadata, type RasterMetadataBand, type RasterMetadataBandStats, type RasterSourceOptions, type RasterTile, type RemoveFilterOptions, SOURCE_DEFAULTS, type Scale, type ScaleKey, type ScaleType, type Scales, type ScatterPlotFeature, type ScatterRequestOptions, type ScatterResponse, type SchemaField, SchemaFieldType, type SortColumnType, type SortDirection, type SourceOptionalOptions, type SourceOptions, type SourceRequiredOptions, type SpatialDataType, type SpatialFilter, type SpatialFilterPolyfillMode, SpatialIndex, SpatialIndexColumn, type SpatialIndexFilter, type SpatialIndexTile, type StringSearchOptions, TEXT_LABEL_INDEX, TEXT_NUMBER_FORMATTER, TEXT_OUTLINE_OPACITY, type TableRequestOptions, type TableResponse, type TableSourceOptions, type Tile, type TileFeatureExtractOptions, type TileFeatures, type TileFeaturesSpatialIndexOptions, TileFormat, type TileResolution, type Tilejson, type TilejsonResult, type TilesetSourceOptions, type Tilestats, type TimeSeriesRequestOptions, type TimeSeriesResponse, type TrajectoryQuerySourceOptions, type TrajectoryQuerySourceResponse, type TrajectoryTableSourceOptions, type TrajectoryTableSourceResponse, type VectorLayer, type VectorQuerySourceOptions, type VectorQuerySourceResponse, type VectorTableSourceOptions, type VectorTableSourceResponse, type VectorTilesetSourceOptions, type VectorTilesetSourceResponse, type ViewState, type Viewport, type WidgetFeatureGeometryType, WidgetQuerySource, type WidgetQuerySourceResult, WidgetRasterSource, type WidgetRasterSourceProps, type WidgetRasterSourceResult, WidgetRemoteSource, type WidgetRemoteSourceProps, WidgetSource, type WidgetSourceProps, WidgetTableSource, type WidgetTableSourceResult, WidgetTilesetSource, type WidgetTilesetSourceProps, type WidgetTilesetSourceResult, type _DataFilterExtensionProps, ErrorCode as _ErrorCode, type VecExprResult as _VecExprResult, applyLayerGroupFilters as _applyLayerGroupFilters, _buildFeatureFilter, createVecExprEvaluator as _createVecExprEvaluator, domainFromValues as _domainFromValues, evaluateVecExpr as _evaluateVecExpr, fillInMapDatasets as _fillInMapDatasets, fillInTileStats as _fillInTileStats, _getHexagonResolution, getLog10ScaleSteps as _getLog10ScaleSteps, getPointsAggregationLevel as _getPointsAggregationLevel, getRasterTileLayerStyleProps as _getRasterTileLayerStyleProps, validateVecExprSyntax as _validateVecExprSyntax, addFilter, aggregate, aggregationFunctions, applyFilters, applySorting, boundaryQuerySource, boundaryTableSource, buildAuthHeaders, buildBinaryFeatureFilter, buildPublicMapUrl, buildStatsUrl, calculateClusterRadius, calculateClusterTextFontSize, calculateLayerScale, clearDefaultRequestCache, clearFilters, compileCustomAggregation, configureSource, createColorScale, createPolygonSpatialFilter, createViewportSpatialFilter, fetchBasemapProps, fetchMap, filterFunctions, geojsonFeatures, getApplicableFilters, getAuthCredentials, getClient, getColorAccessor, getColumnNameFromGeoColumn, getDataFilterExtensionProps, getDefaultAggregationExpColumnAliasForLayerType, getFilter, getIconUrlAccessor, getLayerDescriptor, getLayerProps, getMaxMarkerSize, getSizeAccessor, getSorter, getSpatialIndexFromGeoColumn, getTextAccessor, groupValuesByColumn, groupValuesByDateColumn, h3QuerySource, h3TableSource, h3TilesetSource, hasFilter, histogram, isSpatialIndexFilter, makeIntervalComplete, negateAccessor, opacityToAlpha, parseMap, quadbinQuerySource, quadbinTableSource, quadbinTilesetSource, query, rasterSource, removeFilter, requestWithParameters, rewriteUrlForSessionMode, scaleAggregationResLevel, scatterPlot, setClient, tileFeatures, tileFeaturesGeometries, tileFeaturesSpatialIndex, trajectoryQuerySource, trajectoryTableSource, transformToTileCoords, vectorQuerySource, vectorTableSource, vectorTilesetSource };