@carto/api-client 0.5.30-alpha.b195e7f.118 → 0.5.30

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.30-alpha.b195e7f.118",
+  "version": "0.5.30",
   "license": "MIT",
   "publishConfig": {
     "access": "public"

package/src/api/auth.ts

@@ -0,0 +1,92 @@
+/**
+ * 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.
+ */
+export 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}.
+ */
+export 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.
+ */
+export function buildAuthHeaders(options: AuthOptions): Record<string, string> {
+  if (options.authMode === 'session') {
+    if (options.accessToken) {
+      throw new Error(
+        `accessToken must not be provided with authMode: 'session' — ` +
+          `authentication is delegated to the server behind apiBaseUrl`
+      );
+    }
+    return {};
+  }
+  if (!options.accessToken) {
+    throw new Error(
+      `accessToken is required (or pass authMode: 'session' to authenticate ` +
+        `via a same-origin session instead)`
+    );
+  }
+  return {Authorization: `Bearer ${options.accessToken}`};
+}
+
+/**
+ * `fetch()` credentials for the given auth mode. Session mode must send the
+ * cookie explicitly; token mode preserves today's behavior (unset).
+ */
+export function getAuthCredentials(
+  authMode?: AuthMode
+): RequestCredentials | undefined {
+  return authMode === 'session' ? 'same-origin' : 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.
+ */
+export function rewriteUrlForSessionMode(
+  url: string,
+  apiBaseUrl: string
+): string {
+  let origin: string;
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+      return url;
+    }
+    origin = parsed.origin;
+  } catch {
+    // Relative URL — already same-origin, nothing to rewrite.
+    return url;
+  }
+  // Keep the path+query as a raw slice rather than re-serializing through
+  // URL: tile URL templates contain literal placeholders ({z}/{x}/{y}) that
+  // URL#pathname would percent-encode, breaking template substitution.
+  const base = apiBaseUrl.replace(/\/+$/, '');
+  return base + url.slice(origin.length);
+}

package/src/api/index.ts

@@ -2,6 +2,13 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
+export {
+  buildAuthHeaders,
+  getAuthCredentials,
+  rewriteUrlForSessionMode,
+  type AuthMode,
+  type AuthOptions,
+} from './auth.js';
 export {
   CartoAPIError,
   type APIErrorContext,

package/src/api/query.ts

@@ -9,6 +9,7 @@ import type {
   QueryResult,
 } from '../sources/types.js';
 import {buildQueryUrl} from './endpoints.js';
+import {buildAuthHeaders, getAuthCredentials} from './auth.js';
 import {requestWithParameters} from './request-with-parameters.js';
 import type {APIErrorContext} from './carto-api-error.js';
 import {getClient} from '../client.js';
@@ -50,7 +51,7 @@ export const query = async function (
 
   const baseUrl = buildQueryUrl({apiBaseUrl, connectionName});
   const headers = {
-    Authorization: `Bearer ${options.accessToken}`,
+    ...buildAuthHeaders(options),
     ...options.headers,
   };
   const parameters = {
@@ -74,5 +75,6 @@ export const query = async function (
     maxLengthURL,
     localCache,
     signal: options.signal,
+    credentials: getAuthCredentials(options.authMode),
   });
 };

package/src/api/request-with-parameters.ts

@@ -24,6 +24,7 @@ export async function requestWithParameters<T = any>({
   maxLengthURL = DEFAULT_MAX_LENGTH_URL,
   localCache,
   signal,
+  credentials,
 }: {
   baseUrl: string;
   parameters?: Record<string, unknown>;
@@ -32,6 +33,8 @@ export async function requestWithParameters<T = any>({
   maxLengthURL?: number;
   localCache?: LocalCacheOptions;
   signal?: AbortSignal;
+  /** Forwarded to `fetch()`. Session auth mode passes 'same-origin'. */
+  credentials?: RequestCredentials;
 }): Promise<T> {
   // Parameters added to all requests issued with `requestWithParameters()`.
   // These parameters override parameters already in the base URL, but not
@@ -68,8 +71,9 @@ export async function requestWithParameters<T = any>({
           body: JSON.stringify(parameters),
           headers,
           signal,
+          ...(credentials && {credentials}),
         })
-      : fetch(url, {headers, signal});
+      : fetch(url, {headers, signal, ...(credentials && {credentials})});
 
   let response: Response | undefined;
   let responseJson: unknown;
@@ -132,6 +136,29 @@ function createCacheKey(
   });
 }
 
+/**
+ * Base URLs may be relative (e.g. a same-origin proxy like
+ * '/app/_proxy/<slug>/v3/...' used with session auth mode). `new URL()`
+ * requires an origin, so relative URLs are resolved against a marker origin
+ * that is stripped back off before returning.
+ */
+const RELATIVE_ORIGIN = 'https://relative.invalid';
+
+function parseBaseUrl(baseUrlString: string): {url: URL; isRelative: boolean} {
+  // Protocol-relative URLs ('//host/...') carry a host and must not be treated
+  // as relative, or the host would be lost when resolved against RELATIVE_ORIGIN.
+  const isRelative =
+    baseUrlString.startsWith('/') && !baseUrlString.startsWith('//');
+  return {
+    url: new URL(baseUrlString, isRelative ? RELATIVE_ORIGIN : undefined),
+    isRelative,
+  };
+}
+
+function serializeBaseUrl(url: URL, isRelative: boolean): string {
+  return isRelative ? `${url.pathname}${url.search}` : url.toString();
+}
+
 /**
  * Appends query string parameters to a URL. Existing URL parameters are kept,
  * unless there is a conflict, in which case the new parameters override
@@ -141,7 +168,7 @@ function createURLWithParameters(
   baseUrlString: string,
   parameters: Record<string, unknown>
 ): string {
-  const baseUrl = new URL(baseUrlString);
+  const {url: baseUrl, isRelative} = parseBaseUrl(baseUrlString);
   for (const [key, value] of Object.entries(parameters)) {
     if (isPureObject(value) || Array.isArray(value)) {
       baseUrl.searchParams.set(key, JSON.stringify(value));
@@ -154,20 +181,20 @@ function createURLWithParameters(
       }
     }
   }
-  return baseUrl.toString();
+  return serializeBaseUrl(baseUrl, isRelative);
 }
 
 /**
  * Deletes query string parameters from a URL.
  */
 function excludeURLParameters(baseUrlString: string, parameters: string[]) {
-  const baseUrl = new URL(baseUrlString);
+  const {url: baseUrl, isRelative} = parseBaseUrl(baseUrlString);
   for (const param of parameters) {
     if (baseUrl.searchParams.has(param)) {
       baseUrl.searchParams.delete(param);
     }
   }
-  return baseUrl.toString();
+  return serializeBaseUrl(baseUrl, isRelative);
 }
 
 /**

package/src/fetch-map/parse-map.ts

@@ -754,7 +754,13 @@ function createChannelProps(
   };
 }
 
-function createLoadOptions(accessToken: string) {
+function createLoadOptions(accessToken?: string) {
+  // No token (e.g. a source created with authMode: 'session', where tile URLs
+  // are same-origin and authenticated by a session cookie): attach no
+  // Authorization header rather than a literal 'Bearer undefined'.
+  if (!accessToken) {
+    return {loadOptions: {fetch: {credentials: 'same-origin'}}};
+  }
   return {
     loadOptions: {fetch: {headers: {Authorization: `Bearer ${accessToken}`}}},
   };

package/src/index.ts

@@ -18,6 +18,11 @@ export * from './types.js';
 export {
   type APIErrorContext,
   type APIRequestType,
+  type AuthMode,
+  type AuthOptions,
+  buildAuthHeaders,
+  getAuthCredentials,
+  rewriteUrlForSessionMode,
   CartoAPIError,
   type QueryOptions,
   buildPublicMapUrl, // Internal, but required for fetchMap().
@@ -28,6 +33,7 @@ export {
 } from './api/index.js';
 
 export {_getHexagonResolution} from './spatial-index.js';
+export {getPointsAggregationLevel as _getPointsAggregationLevel} from './spatial-index.js';
 
 // For unit testing only.
 export * from './filters/index.js';

package/src/models/common.ts

@@ -1,4 +1,9 @@
 import {InvalidColumnError} from '../utils.js';
+import {
+  buildAuthHeaders,
+  getAuthCredentials,
+  type AuthMode,
+} from '../api/auth.js';
 
 /** @privateRemarks Source: @carto/react-api */
 export interface ModelRequestOptions {
@@ -55,10 +60,12 @@ export function dealWithApiError({
 export async function makeCall({
   url,
   accessToken,
+  authMode,
   opts,
 }: {
   url: string;
-  accessToken: string;
+  accessToken?: string;
+  authMode?: AuthMode;
   opts: ModelRequestOptions;
 }) {
   let response;
@@ -67,10 +74,13 @@ export async function makeCall({
   try {
     response = await fetch(url.toString(), {
       headers: {
-        Authorization: `Bearer ${accessToken}`,
+        ...buildAuthHeaders({accessToken, authMode}),
         ...(isPost && {'Content-Type': 'application/json'}),
         ...opts.headers,
       },
+      ...(getAuthCredentials(authMode) && {
+        credentials: getAuthCredentials(authMode),
+      }),
       ...(isPost && {
         method: opts?.method,
         body: opts?.body,

package/src/models/model.ts

@@ -1,4 +1,5 @@
 import {DEFAULT_GEO_COLUMN} from '../constants-internal.js';
+import type {AuthMode} from '../api/auth.js';
 import type {
   Filter,
   FilterLogicalOperator,
@@ -33,7 +34,8 @@ export interface ModelSource {
   type: MapType;
   apiVersion: ApiVersion;
   apiBaseUrl: string;
-  accessToken: string;
+  accessToken?: string;
+  authMode?: AuthMode;
   clientId: string;
   connectionName: string;
   data: string;
@@ -72,11 +74,12 @@ export function executeModel(props: {
   );
 
   const {model, source, params, opts} = props;
-  const {type, apiVersion, apiBaseUrl, accessToken, connectionName, clientId} =
-    source;
+  const {type, apiVersion, apiBaseUrl, connectionName, clientId} = source;
 
   assert(apiBaseUrl, 'executeModel: missing apiBaseUrl');
-  assert(accessToken, 'executeModel: missing accessToken');
+  // Auth (token vs session mode) is validated centrally by buildAuthHeaders,
+  // invoked from makeCall below — no separate accessToken assertion here, so
+  // that session mode (no accessToken) is not rejected before the request.
   assert(apiVersion === V3, 'executeModel: SQL Model API requires CARTO 3+');
   assert(type !== 'tileset', 'executeModel: Tilesets not supported');
 
@@ -123,6 +126,7 @@ export function executeModel(props: {
   return makeCall({
     url,
     accessToken: source.accessToken,
+    authMode: source.authMode,
     opts: {
       ...opts,
       method: isGet ? 'GET' : 'POST',

package/src/sources/base-source.ts

@@ -5,6 +5,11 @@
 import {DEFAULT_API_BASE_URL} from '../constants.js';
 import {DEFAULT_MAX_LENGTH_URL} from '../constants-internal.js';
 import {buildSourceUrl} from '../api/endpoints.js';
+import {
+  buildAuthHeaders,
+  getAuthCredentials,
+  rewriteUrlForSessionMode,
+} from '../api/auth.js';
 import {requestWithParameters} from '../api/request-with-parameters.js';
 import type {
   SourceOptionalOptions,
@@ -43,10 +48,12 @@ export async function baseSource<UrlParameters extends Record<string, unknown>>(
   }
   const baseUrl = buildSourceUrl(mergedOptions);
   const {clientId, maxLengthURL, localCache} = mergedOptions;
+  const sessionMode = options.authMode === 'session';
   const headers = {
-    Authorization: `Bearer ${options.accessToken}`,
+    ...buildAuthHeaders(options),
     ...options.headers,
   };
+  const credentials = getAuthCredentials(options.authMode);
   const parameters = {client: clientId, ...options.tags, ...urlParameters};
 
   const errorContext: APIErrorContext = {
@@ -63,15 +70,22 @@ export async function baseSource<UrlParameters extends Record<string, unknown>>(
       errorContext,
       maxLengthURL,
       localCache,
+      credentials,
     });
 
-  const dataUrl = tilejson.url[0];
+  let dataUrl = tilejson.url[0];
   if (cache) {
     cache.value = parseInt(
       new URL(dataUrl).searchParams.get('cache') || '',
       10
     );
   }
+  if (sessionMode) {
+    // The instantiation response points at the tenant API host, which the
+    // browser cannot reach directly in session mode — route it through the
+    // same-origin proxy behind apiBaseUrl.
+    dataUrl = rewriteUrlForSessionMode(dataUrl, mergedOptions.apiBaseUrl);
+  }
   errorContext.requestType = 'Map data';
 
   const json = await requestWithParameters<TilejsonResult>({
@@ -81,8 +95,17 @@ export async function baseSource<UrlParameters extends Record<string, unknown>>(
     errorContext,
     maxLengthURL,
     localCache,
+    credentials,
   });
-  if (accessToken) {
+  if (sessionMode) {
+    // Tile URL templates also point at the tenant API host. Rewrite them onto
+    // the proxy, and deliberately leave `json.accessToken` unset: consumers
+    // (e.g. deck.gl tile layers) must not attach an Authorization header —
+    // the session credential rides on the same-origin cookie instead.
+    json.tiles = json.tiles?.map((template) =>
+      rewriteUrlForSessionMode(template, mergedOptions.apiBaseUrl)
+    );
+  } else if (accessToken) {
     json.accessToken = accessToken;
   }
   if (schema) {

package/src/sources/types.ts

@@ -3,12 +3,10 @@
 // Copyright (c) vis.gl contributors
 
 import type {Filters, SchemaField, QueryParameters} from '../types.js';
+import type {AuthOptions} from '../api/auth.js';
 import type {RasterBandColorinterp} from './constants.js';
 
-export type SourceRequiredOptions = {
-  /** Carto platform access token. */
-  accessToken: string;
-
+export type SourceRequiredOptions = AuthOptions & {
   /** Data warehouse connection name in Carto platform. */
   connectionName: string;
 };
@@ -466,7 +464,13 @@ export type RasterMetadata = {
 };
 
 export 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[];
 };
 

package/src/spatial-index.ts

@@ -1,3 +1,5 @@
+import type {TileResolution} from './sources/types.js';
+
 // Default tile display size in deck.gl, in viewport pixels. May differ
 // from size or resolution assumed when generating the tile data,
 const DEFAULT_TILE_SIZE = 512;
@@ -30,3 +32,42 @@ export function _getHexagonResolution(
     Math.floor(hexagonScaleFactor + latitudeScaleFactor - BIAS)
   );
 }
+
+// Default of the maps-api setting MAPS_API_V3_DYNAMIC_TILES_POINTS_AGGREGATION_LEVEL.
+const DYNAMIC_TILES_POINTS_AGGREGATION_LEVEL = 8;
+
+// Per-tileResolution correction, identical to the maps-api dynamic tiler.
+const AGG_LEVEL_CORRECTION_BY_TILE_RESOLUTION: Record<TileResolution, number> =
+  {
+    0.25: -1,
+    0.5: 0,
+    1: 1,
+    2: 2,
+    4: 3,
+  };
+
+/**
+ * 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
+ */
+export function getPointsAggregationLevel({
+  tileResolution,
+  zoomLevel,
+}: {
+  tileResolution: TileResolution;
+  zoomLevel: number;
+}): number {
+  return (
+    zoomLevel +
+    DYNAMIC_TILES_POINTS_AGGREGATION_LEVEL +
+    AGG_LEVEL_CORRECTION_BY_TILE_RESOLUTION[tileResolution]
+  );
+}

package/src/types.ts

@@ -116,21 +116,13 @@ export type AggregationType =
 export type GeometrySpatialFilter = Polygon | MultiPolygon;
 
 /**
- * Filter restricting a widget query to a set of spatial-index cells (H3 or
- * Quadbin). Used for point-and-click selection on cell-rendered layers. Sent to
- * the server-side model API only; maps-api chooses the SQL strategy from
- * `spatialDataType`, so the same payload works for both natively-indexed
- * sources and point/geometry sources dynamically aggregated into cells.
- *
- * @privateRemarks Source: @carto/query-builder (SpatialIndexFilter)
+ * Filter restricting a widget query to a selection of spatial-index cells,
+ * e.g. from point-and-click on an H3 or Quadbin layer.
  */
 export interface SpatialIndexFilter {
-  /**
-   * Selected cell ids. h3 = hex string; h3int = `BigInt(\`0x${id}\`)`; quadbin
-   * = decimal or `0x`-hex string.
-   */
+  /** Selected cell ids. */
   indexes: string[];
-  /** Must match the column type; `h3` and `h3int` are interchangeable. */
+  /** Spatial index type of the filtered column. */
   type: 'h3' | 'h3int' | 'quadbin';
 }
 
@@ -141,7 +133,14 @@ export type SpatialFilter = GeometrySpatialFilter | SpatialIndexFilter;
 export function isSpatialIndexFilter(
   spatialFilter: SpatialFilter
 ): spatialFilter is SpatialIndexFilter {
-  return Array.isArray((spatialFilter as SpatialIndexFilter).indexes);
+  const filter = spatialFilter as
+    | Partial<SpatialIndexFilter>
+    | null
+    | undefined;
+  return (
+    Array.isArray(filter?.indexes) &&
+    ['h3', 'h3int', 'quadbin'].includes(filter?.type as string)
+  );
 }
 
 /** @privateRemarks Source: @deck.gl/carto */

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

@@ -30,6 +30,7 @@ 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 {buildAuthHeaders, getAuthCredentials} from '../api/auth.js';
 import type {APIErrorContext} from '../api/carto-api-error.js';
 
 export type WidgetRemoteSourceProps = WidgetSourceProps;
@@ -88,6 +89,7 @@ export abstract class WidgetRemoteSource<
       apiBaseUrl: props.apiBaseUrl as string,
       clientId: props.clientId as string,
       accessToken: props.accessToken,
+      authMode: props.authMode,
       connectionName: props.connectionName,
       filters: getApplicableFilters(filterOwner, filters || props.filters),
       filtersLogicalOperator: props.filtersLogicalOperator,
@@ -486,7 +488,7 @@ export abstract class WidgetRemoteSource<
     }
 
     const headers = {
-      Authorization: `Bearer ${this.props.accessToken}`,
+      ...buildAuthHeaders(this.props),
       ...this.props.headers,
     };
 
@@ -511,6 +513,7 @@ export abstract class WidgetRemoteSource<
       signal,
       errorContext,
       parameters,
+      credentials: getAuthCredentials(this.props.authMode),
     }).then(({extent: {xmin, ymin, xmax, ymax}}) => ({
       bbox: [xmin, ymin, xmax, ymax],
     }));