CARTO: Support private maps in fetchMap (#9139)

docs/api-reference/carto/fetch-map.md

@@ -50,13 +50,19 @@ const map = await fetchMap({cartoMapId, credentials, autoRefresh, onNewData});
 
 Required. Identifier of map created in CARTO Builder.
 
-#### `credentials` (object, optional) {#credentials}
+#### `accessToken` (string, optional) {#accesstoken}
 
-[CARTO Credentials](./overview.md#carto-credentials) to use in API requests.
+CARTO platform access token. Only required for private maps.
+
+#### `apiBaseUrl` (string, optional) {#apibaseurl}
+
+Base URL of the CARTO Maps API.
+
+Example for account located in EU-west region: `https://gcp-eu-west1.api.carto.com`
 
 #### `headers` (object, optional) {#headers}
 
-Custom headers to include in the map instantiation requests.
+Custom HTTP headers to include in the map instantiation requests.
 
 #### `autoRefresh` (number, optional) {#autorefresh}
 

examples/get-started/pure-js/carto/app.js

@@ -5,12 +5,11 @@ import {fetchMap} from '@deck.gl/carto';
 const cartoMapId = 'ff6ac53f-741a-49fb-b615-d040bc5a96b8';
 
 // Get map info from CARTO and update deck
-fetchMap({cartoMapId}).then(({initialViewState, mapStyle, layers}) => {
+fetchMap({cartoMapId}).then(({initialViewState, basemap, layers}) => {
   const deck = new Deck({canvas: 'deck-canvas', controller: true, initialViewState, layers});
 
   // Add Mapbox GL for the basemap. It's not a requirement if you don't need a basemap.
-  const MAP_STYLE = `https://basemaps.cartocdn.com/gl/${mapStyle.styleType}-gl-style/style.json`;
-  const map = new maplibregl.Map({container: 'map', style: MAP_STYLE, interactive: false});
+  const map = new maplibregl.Map({container: 'map', ...basemap?.props, interactive: false});
   deck.setProps({
     onViewStateChange: ({viewState}) => {
       const {longitude, latitude, ...rest} = viewState;

modules/carto/src/api/fetch-map.ts

@@ -1,7 +1,4 @@
 /* eslint-disable camelcase */
-/**
- * Maps API Client for Carto 3
- */
 import {CartoAPIError} from './carto-api-error';
 import {DEFAULT_API_BASE_URL, DEFAULT_CLIENT} from './common';
 import {buildPublicMapUrl, buildStatsUrl} from './endpoints';
@@ -206,11 +203,39 @@ async function fillInTileStats(
 }
 
 export type FetchMapOptions = {
+  /**
+   * CARTO platform access token. Only required for private maps.
+   */
+  accessToken?: string;
+
+  /**
+   * Base URL of the CARTO Maps API.
+   *
+   * Example for account located in EU-west region: `https://gcp-eu-west1.api.carto.com`
+   *
+   * @default https://gcp-us-east1.api.carto.com
+   */
   apiBaseUrl?: string;
+
+  /**
+   * Identifier of map created in CARTO Builder.
+   */
   cartoMapId: string;
   clientId?: string;
+
+  /**
+   * Custom HTTP headers added to map instantiation and data requests.
+   */
   headers?: Record<string, string>;
+
+  /**
+   * Interval in seconds at which to autoRefresh the data. If provided, `onNewData` must also be provided.
+   */
   autoRefresh?: number;
+
+  /**
+   * Callback function that will be invoked whenever data in layers is changed. If provided, `autoRefresh` must also be provided.
+   */
   onNewData?: (map: any) => void;
 };
 
@@ -224,6 +249,7 @@ export type FetchMapResult = ParseMapResult & {
 
 /* eslint-disable max-statements */
 export async function fetchMap({
+  accessToken,
   apiBaseUrl = DEFAULT_API_BASE_URL,
   cartoMapId,
   clientId = DEFAULT_CLIENT,
@@ -234,6 +260,10 @@ export async function fetchMap({
   assert(cartoMapId, 'Must define CARTO map id: fetchMap({cartoMapId: "XXXX-XXXX-XXXX"})');
   assert(apiBaseUrl, 'Must define apiBaseUrl');
 
+  if (accessToken) {
+    headers = {Authorization: `Bearer ${accessToken}`, ...headers};
+  }
+
   if (autoRefresh || onNewData) {
     assert(onNewData, 'Must define `onNewData` when using autoRefresh');
     assert(typeof onNewData === 'function', '`onNewData` must be a function');