esri-gl 1.0.5 → 2.0.0

package/dist/{IdentifyImage-DmyKcbAv.js → index-DsY1_0df.js}

@@ -1,9 +1,163 @@
+import { BasemapStyleSession } from '@esri/arcgis-rest-basemap-sessions';
+import { SearchQueryBuilder, searchItems, getItem, getItemData } from '@esri/arcgis-rest-portal';
+import { ApiKeyManager, request } from '@esri/arcgis-rest-request';
+import { queryFeatures, getLayer, getAllLayersAndTables, queryRelated, decodeValues, addFeatures, updateFeatures, deleteFeatures, applyEdits, getAttachments, deleteAttachments } from '@esri/arcgis-rest-feature-service';
 import * as tilebelt from '@mapbox/tilebelt';
 import tileDecode from 'arcgis-pbf-parser';
 
+/**
+ * Shared request + authentication adapter built on `@esri/arcgis-rest-request`.
+ *
+ * Every network call in esri-gl that talks to an ArcGIS REST endpoint flows
+ * through this module so that authentication, error handling and parameter
+ * encoding are handled once by the official ArcGIS REST JS client instead of
+ * the bespoke `fetch` wrappers this library used to ship.
+ */
+/**
+ * Normalise the various auth inputs into an `IAuthenticationManager` (or
+ * `undefined` for anonymous requests). A bare string is wrapped in an
+ * `ApiKeyManager` so it is sent as the `token` parameter, matching ArcGIS REST
+ * conventions.
+ */
+function resolveAuthentication(options) {
+  if (!options) return undefined;
+  const {
+    authentication,
+    apiKey,
+    token
+  } = options;
+  if (authentication) {
+    return typeof authentication === 'string' ? ApiKeyManager.fromKey(authentication) : authentication;
+  }
+  const key = apiKey ?? token;
+  return key ? ApiKeyManager.fromKey(key) : undefined;
+}
+/**
+ * Thin wrapper over `@esri/arcgis-rest-request`'s `request()` that applies
+ * esri-gl's auth resolution and sensible defaults. Throws `ArcGISRequestError`
+ * (and friends) on ArcGIS service-level or HTTP errors.
+ */
+function esriRequest(url, options = {}) {
+  const {
+    params,
+    httpMethod,
+    rawResponse,
+    signal,
+    headers,
+    ...auth
+  } = options;
+  const requestOptions = {
+    params: {
+      f: 'json',
+      ...params
+    },
+    authentication: resolveAuthentication(auth)
+  };
+  if (httpMethod) requestOptions.httpMethod = httpMethod;
+  if (rawResponse) requestOptions.rawResponse = true;
+  if (signal) requestOptions.signal = signal;
+  if (headers) requestOptions.headers = headers;
+  return request(url, requestOptions);
+}
+/**
+ * Fetch a **binary** ArcGIS response (PBF tiles, exported images) as a raw
+ * `Response`, applying esri-gl auth. Used instead of `esriRequest`'s deprecated
+ * `rawResponse` option (removed in ArcGIS REST JS v5).
+ */
+async function esriRawRequest(url, options = {}) {
+  const {
+    params,
+    signal,
+    headers,
+    ...auth
+  } = options;
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params ?? {})) {
+    if (value === undefined || value === null) continue;
+    search.append(key, typeof value === 'object' ? JSON.stringify(value) : String(value));
+  }
+  const manager = resolveAuthentication(auth);
+  if (manager) {
+    try {
+      const token = await manager.getToken(url);
+      if (token) search.append('token', token);
+    } catch {
+      // fall through and request anonymously
+    }
+  }
+  const response = await fetch(`${url}?${search.toString()}`, {
+    signal,
+    headers
+  });
+  if (!response.ok) {
+    throw new Error(`Request failed: HTTP ${response.status}`);
+  }
+  return response;
+}
+
 function cleanTrailingSlash(url) {
   return url.replace(/\/$/, '');
 }
+/**
+ * Append a `token` query parameter if a non-empty token is supplied.
+ * Centralizes the duplicated token-injection logic used by every service.
+ */
+function appendTokenIfExists(params, token) {
+  if (token) {
+    params.append('token', token);
+  }
+}
+/**
+ * Remove every layer that references the given source, then remove the
+ * source itself. Safe against disposed maps, missing style methods, and
+ * layers that were already removed elsewhere.
+ */
+function removeMapSource(map, sourceId) {
+  if (!map || typeof map.removeSource !== 'function') return;
+  try {
+    if (!map.style) return;
+    const mapWithStyle = map;
+    if (typeof mapWithStyle.getStyle === 'function') {
+      const style = mapWithStyle.getStyle();
+      const layers = style?.layers || [];
+      layers.forEach(layer => {
+        if (layer.source !== sourceId) return;
+        if (typeof mapWithStyle.getLayer !== 'function' || typeof mapWithStyle.removeLayer !== 'function') {
+          return;
+        }
+        let hasLayer = false;
+        try {
+          hasLayer = Boolean(mapWithStyle.getLayer(layer.id));
+        } catch {
+          hasLayer = false;
+        }
+        if (!hasLayer) return;
+        try {
+          mapWithStyle.removeLayer(layer.id);
+        } catch (error) {
+          console.warn(`Failed to remove layer ${layer.id} for source ${sourceId}:`, error);
+        }
+      });
+    }
+    if (typeof mapWithStyle.getSource === 'function') {
+      let hasSource = false;
+      try {
+        hasSource = Boolean(mapWithStyle.getSource(sourceId));
+      } catch {
+        hasSource = false;
+      }
+      if (hasSource) {
+        try {
+          map.removeSource(sourceId);
+        } catch (error) {
+          console.warn(`Failed to remove source ${sourceId}:`, error);
+        }
+      }
+    }
+  } catch (error) {
+    console.warn(`Failed to remove source ${sourceId}:`, error);
+  }
+}
 /**
  * Check if an error represents an AbortError (request was cancelled)
  * Handles various error shapes from different browsers and environments
@@ -27,22 +181,18 @@ function isAbortError(error) {
   const stringified = String(error).toLowerCase();
   return stringified.includes('abort');
 }
-async function getServiceDetails(url, fetchOptions = {}, token) {
-  const params = new URLSearchParams({
-    f: 'json'
+/**
+ * Fetch the `?f=json` metadata document for an ArcGIS service endpoint.
+ *
+ * Delegates to `@esri/arcgis-rest-request` via {@link esriRequest}, which
+ * handles authentication and ArcGIS error responses. Accepts an
+ * {@link EsriRequestOptions} object (`token` / `apiKey` / `authentication`).
+ */
+async function getServiceDetails(url, options = {}) {
+  return esriRequest(url, {
+    httpMethod: 'GET',
+    ...options
   });
-  if (token) {
-    params.append('token', token);
-  }
-  const response = await fetch(`${url}?${params.toString()}`, fetchOptions);
-  if (!response.ok) {
-    throw new Error(`Failed to fetch service details: HTTP ${response.status}`);
-  }
-  const data = await response.json();
-  if (data.error) {
-    throw new Error(data.error.message || 'Service returned an error');
-  }
-  return data;
 }
 const POWERED_BY_ESRI_ATTRIBUTION_STRING = 'Powered by <a href="https://www.esri.com">Esri</a>';
 // This requires hooking into some undocumented properties
@@ -274,12 +424,11 @@ class Service {
     const wrappedCallback = this._createServiceCallback(method, path, params, (error, response) => {
       callback(error, response);
     });
+    // Token/apiKey/authentication are applied by the request adapter, not as
+    // raw params, so they are not injected here.
     let finalParams = {
       ...params
     };
-    if (this.options.token) {
-      finalParams.token = this.options.token;
-    }
     if (this.options.requestParams) {
       finalParams = {
         ...finalParams,
@@ -326,7 +475,7 @@ class Service {
     });
   }
   async _makeRequest(method, path, params, callback) {
-    const url = this.options.proxy ? `${this.options.proxy}?${this.options.url}${path}` : `${this.options.url}${path}`;
+    const url = `${this.options.url}${path}`;
     // Set up abort controller for timeout support
     const controller = new AbortController();
     let timeoutId;
@@ -336,71 +485,22 @@ class Service {
       }, this.options.timeout);
     }
     try {
-      let response;
-      const fetchOptions = {
-        signal: controller.signal
-      };
-      // Add API key header if present
-      if (this.options.apiKey) {
-        fetchOptions.headers = {
-          'X-Esri-Authorization': `Bearer ${this.options.apiKey}`
-        };
-      }
-      if (method === 'POST') {
-        const formData = new FormData();
-        Object.keys(params).forEach(key => {
-          const value = params[key];
-          if (value !== undefined && value !== null) {
-            if (typeof value === 'object') {
-              formData.append(key, JSON.stringify(value));
-            } else {
-              formData.append(key, value.toString());
-            }
-          }
-        });
-        response = await fetch(url, {
-          ...fetchOptions,
-          method: 'POST',
-          body: formData
-        });
-      } else {
-        const searchParams = new URLSearchParams();
-        Object.keys(params).forEach(key => {
-          const value = params[key];
-          if (value !== undefined && value !== null) {
-            if (Array.isArray(value)) {
-              searchParams.append(key, value.join(','));
-            } else if (typeof value === 'object') {
-              searchParams.append(key, JSON.stringify(value));
-            } else {
-              searchParams.append(key, value.toString());
-            }
-          }
-        });
-        const fullUrl = `${url}?${searchParams.toString()}`;
-        response = await fetch(fullUrl, fetchOptions);
-      }
-      if (!response.ok) {
-        const error = new Error(`HTTP error! status: ${response.status}`);
-        error.code = response.status;
-        throw error;
-      }
-      const data = await response.json();
-      // Check for AGOL JSON-level errors (HTTP 200 with error body)
-      if (data && typeof data === 'object' && data.error) {
-        const err = new Error(data.error.message || 'ArcGIS service error');
-        err.code = data.error.code;
-        err.details = data.error.details;
-        callback(err);
-        return;
-      }
+      const data = await esriRequest(url, {
+        params,
+        httpMethod: method === 'POST' ? 'POST' : 'GET',
+        signal: controller.signal,
+        token: this.options.token,
+        apiKey: this.options.apiKey,
+        authentication: this.options.authentication
+      });
       callback(undefined, data);
     } catch (error) {
       // Provide clearer error message for timeout
       if (error instanceof Error && error.name === 'AbortError' && this.options.timeout > 0) {
-        const timeoutError = new Error(`Request timed out after ${this.options.timeout}ms`);
-        callback(timeoutError);
+        callback(new Error(`Request timed out after ${this.options.timeout}ms`));
       } else {
+        // ArcGISRequestError exposes a numeric `code` used downstream for
+        // authentication (498/499) detection.
         callback(error);
       }
     } finally {
@@ -797,10 +897,21 @@ class DynamicMapService {
     if (where) this.setLayerDefinition(layerId, where);
   }
   _appendTokenIfExists(params) {
-    const token = this.esriServiceOptions.token;
-    if (token) {
-      params.append('token', token);
-    }
+    // apiKey is sent as the token URL parameter, matching the request-based paths.
+    const auth = this.esriServiceOptions;
+    appendTokenIfExists(params, auth.token ?? auth.apiKey);
+  }
+  _auth() {
+    const o = this.esriServiceOptions;
+    return {
+      token: o.token,
+      apiKey: o.apiKey,
+      authentication: o.authentication
+    };
+  }
+  /** Resolved ArcGIS REST JS auth manager for the typed feature-service helpers. */
+  _authentication() {
+    return resolveAuthentication(this._auth());
   }
   _escapeValue(val) {
     if (val === null) return 'NULL';
@@ -876,7 +987,7 @@ class DynamicMapService {
   getMetadata() {
     if (this._serviceMetadata !== null) return Promise.resolve(this._serviceMetadata);
     return new Promise((resolve, reject) => {
-      getServiceDetails(this.esriServiceOptions.url, this.esriServiceOptions.fetchOptions, this.esriServiceOptions.token).then(data => {
+      getServiceDetails(this.esriServiceOptions.url, this._auth()).then(data => {
         this._serviceMetadata = data;
         resolve(this._serviceMetadata);
       }).catch(err => reject(err));
@@ -891,7 +1002,7 @@ class DynamicMapService {
     const canvas = this._map.getCanvas();
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const bounds = this._map.getBounds().toArray();
-    const params = new URLSearchParams({
+    const params = {
       sr: '4326',
       geometryType: 'esriGeometryPoint',
       geometry: JSON.stringify({
@@ -905,21 +1016,15 @@ class DynamicMapService {
       returnGeometry: returnGeometry.toString(),
       imageDisplay: `${canvas.width},${canvas.height},${this.options.dpi}`,
       mapExtent: `${bounds[0][0]},${bounds[0][1]},${bounds[1][0]},${bounds[1][1]}`,
-      layers: this._layersStrIdentify || '',
-      f: 'json'
+      layers: this._layersStrIdentify || ''
+    };
+    if (this._layerDefs) params.layerDefs = this._layerDefs;
+    if (this._dynamicLayers) params.dynamicLayers = this._dynamicLayers;
+    if (this._time) params.time = this._time;
+    const data = await esriRequest(`${this.esriServiceOptions.url}/identify`, {
+      params,
+      ...this._auth()
     });
-    if (this._layerDefs) params.append('layerDefs', this._layerDefs);
-    if (this._dynamicLayers) params.append('dynamicLayers', this._dynamicLayers);
-    if (this._time) params.append('time', this._time);
-    this._appendTokenIfExists(params);
-    const response = await fetch(`${this.esriServiceOptions.url}/identify?${params.toString()}`, this.esriServiceOptions.fetchOptions);
-    if (!response.ok) {
-      throw new Error(`Identify request failed: HTTP ${response.status}`);
-    }
-    const data = await response.json();
-    if (data.error) {
-      throw new Error(`Identify request failed: ${data.error.message}`);
-    }
     return data;
   }
   // ========================================
@@ -1046,71 +1151,44 @@ class DynamicMapService {
   }
   /** Get statistics for a sublayer */
   async getLayerStatistics(layerId, statisticFields, options = {}) {
-    const queryUrl = `${this.esriServiceOptions.url}/${layerId}/query`;
-    const params = new URLSearchParams({
-      f: 'json',
+    const data = await queryFeatures({
+      url: `${this.esriServiceOptions.url}/${layerId}`,
       where: options.where || '1=1',
-      outStatistics: JSON.stringify(statisticFields),
-      returnGeometry: 'false'
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      outStatistics: statisticFields,
+      groupByFieldsForStatistics: options.groupByFieldsForStatistics,
+      returnGeometry: false,
+      authentication: this._authentication()
     });
-    if (options.groupByFieldsForStatistics) {
-      params.append('groupByFieldsForStatistics', options.groupByFieldsForStatistics);
-    }
-    this._appendTokenIfExists(params);
-    const response = await fetch(`${queryUrl}?${params.toString()}`);
-    if (!response.ok) {
-      throw new Error(`Statistics query failed: HTTP ${response.status}`);
-    }
-    const data = await response.json();
-    if (data.error) {
-      throw new Error(`Statistics query failed: ${data.error.message}`);
-    }
     return data.features || [];
   }
   /** Query features from a specific sublayer */
   async queryLayerFeatures(layerId, options = {}) {
-    const queryUrl = `${this.esriServiceOptions.url}/${layerId}/query`;
-    const params = new URLSearchParams({
-      f: 'json',
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const requestOptions = {
+      url: `${this.esriServiceOptions.url}/${layerId}`,
       where: options.where || '1=1',
-      returnGeometry: options.returnGeometry !== false ? 'true' : 'false',
-      outFields: Array.isArray(options.outFields) ? options.outFields.join(',') : options.outFields || '*'
-    });
+      returnGeometry: options.returnGeometry !== false,
+      outFields: options.outFields || '*',
+      authentication: this._authentication()
+    };
     if (options.geometry) {
-      params.append('geometry', JSON.stringify(options.geometry));
-      params.append('geometryType', options.geometryType || 'esriGeometryEnvelope');
-      params.append('spatialRel', options.spatialRel || 'esriSpatialRelIntersects');
-    }
-    if (options.orderByFields) {
-      params.append('orderByFields', options.orderByFields);
-    }
-    if (options.resultOffset) {
-      params.append('resultOffset', options.resultOffset.toString());
-    }
-    if (options.resultRecordCount) {
-      params.append('resultRecordCount', options.resultRecordCount.toString());
-    }
-    if (options.returnCountOnly) {
-      params.append('returnCountOnly', 'true');
-    }
-    if (options.returnIdsOnly) {
-      params.append('returnIdsOnly', 'true');
-    }
-    this._appendTokenIfExists(params);
-    const response = await fetch(`${queryUrl}?${params.toString()}`);
-    if (!response.ok) {
-      throw new Error(`Layer query failed: HTTP ${response.status}`);
-    }
-    const data = await response.json();
-    if (data.error) {
-      throw new Error(`Layer query failed: ${data.error.message}`);
-    }
+      requestOptions.geometry = options.geometry;
+      requestOptions.geometryType = options.geometryType || 'esriGeometryEnvelope';
+      requestOptions.spatialRel = options.spatialRel || 'esriSpatialRelIntersects';
+    }
+    if (options.orderByFields) requestOptions.orderByFields = options.orderByFields;
+    if (options.resultOffset) requestOptions.resultOffset = options.resultOffset;
+    if (options.resultRecordCount) requestOptions.resultRecordCount = options.resultRecordCount;
+    if (options.returnCountOnly) requestOptions.returnCountOnly = true;
+    if (options.returnIdsOnly) requestOptions.returnIdsOnly = true;
+    const data = await queryFeatures(requestOptions);
     return data;
   }
   /** Export high-resolution map image */
   async exportMapImage(options) {
     const exportUrl = `${this.esriServiceOptions.url}/export`;
-    const params = new URLSearchParams({
+    const params = {
       f: 'image',
       bbox: options.bbox.join(','),
       size: options.size.join(','),
@@ -1119,62 +1197,45 @@ class DynamicMapService {
       dpi: (options.dpi || 96).toString(),
       bboxSR: (options.bboxSR || 3857).toString(),
       imageSR: (options.imageSR || 3857).toString()
-    });
+    };
     if (options.layerDefs) {
-      params.append('layerDefs', JSON.stringify(options.layerDefs));
+      params.layerDefs = JSON.stringify(options.layerDefs);
     }
     if (options.dynamicLayers) {
       const normalized = this._ensureAllVisibleLayers(options.dynamicLayers);
-      params.append('dynamicLayers', JSON.stringify(normalized));
+      params.dynamicLayers = JSON.stringify(normalized);
     }
     if (options.gdbVersion) {
-      params.append('gdbVersion', options.gdbVersion);
+      params.gdbVersion = options.gdbVersion;
     }
     if (options.historicMoment) {
-      params.append('historicMoment', options.historicMoment.toString());
-    }
-    this._appendTokenIfExists(params);
-    const response = await fetch(`${exportUrl}?${params.toString()}`);
-    if (!response.ok) {
-      throw new Error(`Export failed: ${response.statusText}`);
+      params.historicMoment = options.historicMoment.toString();
     }
+    const response = await esriRawRequest(`${exportUrl}`, {
+      params,
+      ...this._auth()
+    });
     return response.blob();
   }
   /** Generate legend information for layers */
   async generateLegend(layerIds) {
     const legendUrl = `${this.esriServiceOptions.url}/legend`;
-    const params = new URLSearchParams({
-      f: 'json'
-    });
+    const params = {};
     if (layerIds?.length) {
-      params.append('layers', layerIds.join(','));
-    }
-    this._appendTokenIfExists(params);
-    const response = await fetch(`${legendUrl}?${params.toString()}`);
-    if (!response.ok) {
-      throw new Error(`Legend generation failed: HTTP ${response.status}`);
-    }
-    const data = await response.json();
-    if (data.error) {
-      throw new Error(`Legend generation failed: ${data.error.message}`);
+      params.layers = layerIds.join(',');
     }
+    const data = await esriRequest(legendUrl, {
+      params,
+      ...this._auth()
+    });
     return data.layers || [];
   }
   /** Get detailed information about a specific layer */
   async getLayerInfo(layerId) {
-    const layerUrl = `${this.esriServiceOptions.url}/${layerId}`;
-    const params = new URLSearchParams({
-      f: 'json'
+    const data = await getLayer({
+      url: `${this.esriServiceOptions.url}/${layerId}`,
+      authentication: this._authentication()
     });
-    this._appendTokenIfExists(params);
-    const response = await fetch(`${layerUrl}?${params.toString()}`);
-    if (!response.ok) {
-      throw new Error(`Layer info request failed: HTTP ${response.status}`);
-    }
-    const data = await response.json();
-    if (data.error) {
-      throw new Error(`Layer info request failed: ${data.error.message}`);
-    }
     return data;
   }
   /** Get field information for a layer */
@@ -1192,19 +1253,10 @@ class DynamicMapService {
   }
   /** Discover all layers in the service */
   async discoverLayers() {
-    const serviceUrl = this.esriServiceOptions.url;
-    const params = new URLSearchParams({
-      f: 'json'
+    const data = await getAllLayersAndTables({
+      url: this.esriServiceOptions.url,
+      authentication: this._authentication()
     });
-    this._appendTokenIfExists(params);
-    const response = await fetch(`${serviceUrl}?${params.toString()}`);
-    if (!response.ok) {
-      throw new Error(`Service discovery failed: HTTP ${response.status}`);
-    }
-    const data = await response.json();
-    if (data.error) {
-      throw new Error(`Service discovery failed: ${data.error.message}`);
-    }
     return data.layers || [];
   }
   /** Apply multiple layer operations in a single update */
@@ -1283,56 +1335,7 @@ class DynamicMapService {
     this._updateSource();
   }
   remove() {
-    const map = this._map;
-    if (!map || typeof map.removeSource !== 'function') {
-      return;
-    }
-    try {
-      // Guard against map whose style has already been destroyed
-      if (!map.style) return;
-      const mapWithStyle = map;
-      const mapLayerApi = map;
-      const mapSourceApi = map;
-      if (typeof mapWithStyle.getStyle === 'function') {
-        const style = mapWithStyle.getStyle();
-        const layers = style?.layers || [];
-        layers.forEach(layer => {
-          if (layer.source !== this._sourceId) return;
-          if (typeof mapLayerApi.getLayer !== 'function' || typeof mapLayerApi.removeLayer !== 'function') {
-            return;
-          }
-          let hasLayer = false;
-          try {
-            hasLayer = Boolean(mapLayerApi.getLayer(layer.id));
-          } catch {
-            hasLayer = false;
-          }
-          if (!hasLayer) return;
-          try {
-            mapLayerApi.removeLayer(layer.id);
-          } catch (error) {
-            console.warn(`Failed to remove layer ${layer.id} for source ${this._sourceId}:`, error);
-          }
-        });
-      }
-      if (typeof mapSourceApi.getSource === 'function') {
-        let hasSource = false;
-        try {
-          hasSource = Boolean(mapSourceApi.getSource(this._sourceId));
-        } catch {
-          hasSource = false;
-        }
-        if (hasSource) {
-          try {
-            map.removeSource(this._sourceId);
-          } catch (error) {
-            console.warn(`Failed to remove source ${this._sourceId}:`, error);
-          }
-        }
-      }
-    } catch (error) {
-      console.warn(`Failed to remove source ${this._sourceId}:`, error);
-    }
+    removeMapSource(this._map, this._sourceId);
   }
 }
 
@@ -1417,8 +1420,17 @@ class TiledMapService {
   }
   getMetadata() {
     if (this._serviceMetadata !== null) return Promise.resolve(this._serviceMetadata);
+    const {
+      token,
+      apiKey,
+      authentication
+    } = this.esriServiceOptions;
     return new Promise((resolve, reject) => {
-      getServiceDetails(this.esriServiceOptions.url, this.esriServiceOptions.fetchOptions, this.esriServiceOptions.token).then(data => {
+      getServiceDetails(this.esriServiceOptions.url, {
+        token,
+        apiKey,
+        authentication
+      }).then(data => {
         this._serviceMetadata = data;
         resolve(data);
       }).catch(err => reject(err));
@@ -1429,41 +1441,7 @@ class TiledMapService {
     // This is a no-op to satisfy the common service interface.
   }
   remove() {
-    // Guard against disposed or invalid map
-    if (!this._map || typeof this._map.removeSource !== 'function') {
-      return;
-    }
-    try {
-      // Guard against map whose style has already been destroyed
-      if (!this._map.style) return;
-      // First, remove any layers that are using this source
-      const mapWithStyle = this._map;
-      if (mapWithStyle.getStyle && typeof mapWithStyle.getLayer === 'function') {
-        const style = mapWithStyle.getStyle();
-        const layers = style?.layers || [];
-        const getLayer = mapWithStyle.getLayer;
-        layers.forEach(layer => {
-          if (layer.source === this._sourceId) {
-            try {
-              if (getLayer(layer.id)) {
-                this._map.removeLayer(layer.id);
-              }
-            } catch {
-              // Layer may already be removed
-            }
-          }
-        });
-      }
-      // Then check if source exists before trying to remove it
-      if (typeof this._map.getSource === 'function') {
-        const source = this._map.getSource(this._sourceId);
-        if (source) {
-          this._map.removeSource(this._sourceId);
-        }
-      }
-    } catch (error) {
-      console.warn(`Failed to remove source ${this._sourceId}:`, error);
-    }
+    removeMapSource(this._map, this._sourceId);
   }
 }
 
@@ -1559,9 +1537,9 @@ class ImageService {
     if (this._time) params.append('time', this._time);
     if (this.options.mosaicRule) params.append('mosaicRule', JSON.stringify(this.options.mosaicRule));
     if (this.options.renderingRule) params.append('renderingRule', JSON.stringify(this.options.renderingRule));
-    if (this.esriServiceOptions.token) {
-      params.append('token', this.esriServiceOptions.token);
-    }
+    // apiKey is sent as the token URL parameter, matching the request-based paths.
+    const auth = this.esriServiceOptions;
+    appendTokenIfExists(params, auth.token ?? auth.apiKey);
     return {
       type: 'raster',
       tiles: [`${this.options.url}/exportImage?bbox={bbox-epsg-3857}&${params.toString()}`],
@@ -1625,8 +1603,17 @@ class ImageService {
   }
   getMetadata() {
     if (this._serviceMetadata !== null) return Promise.resolve(this._serviceMetadata);
+    const {
+      token,
+      apiKey,
+      authentication
+    } = this.esriServiceOptions;
     return new Promise((resolve, reject) => {
-      getServiceDetails(this.esriServiceOptions.url, this.esriServiceOptions.fetchOptions, this.esriServiceOptions.token).then(data => {
+      getServiceDetails(this.esriServiceOptions.url, {
+        token,
+        apiKey,
+        authentication
+      }).then(data => {
         this._serviceMetadata = data;
         resolve(this._serviceMetadata);
       }).catch(err => reject(err));
@@ -1637,7 +1624,7 @@ class ImageService {
     const canvas = this._map.getCanvas();
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const bounds = this._map.getBounds().toArray();
-    const params = new URLSearchParams({
+    const params = {
       sr: '4326',
       geometryType: 'esriGeometryPoint',
       geometry: JSON.stringify({
@@ -1650,50 +1637,26 @@ class ImageService {
       tolerance: '3',
       returnGeometry: returnGeometry.toString(),
       imageDisplay: `${canvas.width},${canvas.height},${this.options.dpi}`,
-      mapExtent: `${bounds[0][0]},${bounds[0][1]},${bounds[1][0]},${bounds[1][1]}`,
-      f: 'json'
+      mapExtent: `${bounds[0][0]},${bounds[0][1]},${bounds[1][0]},${bounds[1][1]}`
+    };
+    if (this._time) params.time = this._time;
+    const {
+      token,
+      apiKey,
+      authentication
+    } = this.esriServiceOptions;
+    return esriRequest(`${this.esriServiceOptions.url}/identify`, {
+      params,
+      token,
+      apiKey,
+      authentication
     });
-    if (this._time) params.append('time', this._time);
-    if (this.esriServiceOptions.token) {
-      params.append('token', this.esriServiceOptions.token);
-    }
-    const response = await fetch(`${this.esriServiceOptions.url}/identify?${params.toString()}`, this.esriServiceOptions.fetchOptions);
-    if (!response.ok) {
-      throw new Error(`Identify request failed: HTTP ${response.status}`);
-    }
-    const data = await response.json();
-    if (data.error) {
-      throw new Error(`Identify request failed: ${data.error.message}`);
-    }
-    return data;
   }
   update() {
     this._updateSource();
   }
   remove() {
-    if (this._map && typeof this._map.removeSource === 'function') {
-      try {
-        // Guard against map whose style has already been destroyed
-        const mapWithStyle = this._map;
-        if (!mapWithStyle.style) return;
-        // First, remove any layers that are using this source
-        if (mapWithStyle.getStyle) {
-          const style = mapWithStyle.getStyle();
-          const layers = style?.layers || [];
-          layers.forEach(layer => {
-            if (layer.source === this._sourceId && this._map.getLayer(layer.id)) {
-              this._map.removeLayer(layer.id);
-            }
-          });
-        }
-        // Then check if source exists before trying to remove it
-        if (this._map.getSource && this._map.getSource(this._sourceId)) {
-          this._map.removeSource(this._sourceId);
-        }
-      } catch (error) {
-        console.warn(`Failed to remove source ${this._sourceId}:`, error);
-      }
-    }
+    removeMapSource(this._map, this._sourceId);
   }
 }
 
@@ -1767,6 +1730,24 @@ class VectorBasemapStyle {
       writable: true,
       value: void 0
     });
+    Object.defineProperty(this, "_useSession", {
+      enumerable: true,
+      configurable: true,
+      writable: true,
+      value: void 0
+    });
+    Object.defineProperty(this, "_sessionDuration", {
+      enumerable: true,
+      configurable: true,
+      writable: true,
+      value: void 0
+    });
+    Object.defineProperty(this, "_session", {
+      enumerable: true,
+      configurable: true,
+      writable: true,
+      value: void 0
+    });
     let opts;
     if (typeof auth === 'string') {
       opts = {
@@ -1783,6 +1764,8 @@ class VectorBasemapStyle {
     this._language = opts.language;
     this._worldview = opts.worldview;
     this._itemId = opts.itemId;
+    this._useSession = opts.useSession ?? false;
+    this._sessionDuration = opts.sessionDuration;
     // Infer version: token => v2, else apiKey => v1
     this._version = opts.version || (this._token ? 'v2' : 'v1');
     // Determine host based on version if not overridden
@@ -1847,6 +1830,71 @@ class VectorBasemapStyle {
     const vectorStyle = new VectorBasemapStyle(styleName, auth);
     map.setStyle(vectorStyle.styleUrl);
   }
+  /**
+   * The style family for the official basemap sessions API, derived from the
+   * canonical style id. esri-gl styles are all in the `arcgis` family.
+   */
+  get _styleFamily() {
+    return this._canonical.startsWith('open/') ? 'open' : 'arcgis';
+  }
+  /**
+   * The token from the active session, if a session has been started. Useful
+   * for inspection / debugging. Returns `undefined` until `startSession()` runs.
+   */
+  get sessionToken() {
+    return this._session?.token;
+  }
+  /**
+   * Start (or reuse) an official basemap style session via
+   * `@esri/arcgis-rest-basemap-sessions`. Requires an apiKey or token. The
+   * resulting session is cached so repeated calls return the same instance.
+   */
+  async startSession() {
+    if (this._session) return this._session;
+    const authentication = resolveAuthentication({
+      apiKey: this._apiKey,
+      token: this._token
+    });
+    if (!authentication) {
+      throw new Error('An Esri API Key or token must be supplied to start a basemap style session');
+    }
+    this._session = await BasemapStyleSession.start({
+      authentication,
+      styleFamily: this._styleFamily,
+      ...(this._sessionDuration !== undefined ? {
+        duration: this._sessionDuration
+      } : {})
+    });
+    return this._session;
+  }
+  /**
+   * Resolve the style URL to apply. When `useSession` is enabled this starts a
+   * session and returns a v2 style URL backed by the session token; otherwise it
+   * returns the synchronous `styleUrl`.
+   */
+  async getStyleUrl() {
+    if (!this._useSession) return this.styleUrl;
+    const session = await this.startSession();
+    const token = await session.getToken();
+    const params = new URLSearchParams();
+    params.set('f', this._format);
+    params.set('token', token);
+    if (this._language) params.set('language', this._language);
+    if (this._worldview) params.set('worldview', this._worldview);
+    return `https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/${this._canonical}?${params.toString()}`;
+  }
+  /**
+   * Apply a basemap style to a MapLibre/Mapbox map using a session-backed style
+   * URL. Mirrors {@link applyStyle} but starts a basemap style session first.
+   */
+  static async applyStyleWithSession(map, styleName, auth) {
+    const vectorStyle = new VectorBasemapStyle(styleName, {
+      ...auth,
+      useSession: true
+    });
+    const url = await vectorStyle.getStyleUrl();
+    map.setStyle(url);
+  }
   static _toCanonical(name) {
     if (!name) return 'arcgis/streets';
     // Already slash form
@@ -1994,10 +2042,17 @@ class VectorTileService {
     });
   }
   _retrieveStyle() {
+    const {
+      token,
+      apiKey,
+      authentication
+    } = this.esriServiceOptions;
     return new Promise((resolve, reject) => {
-      fetch(`${this.options.url}/${this._styleUrl}`, this.esriServiceOptions.fetchOptions).then(response => {
-        if (!response.ok) throw new Error(`Failed to fetch style: ${response.status}`);
-        return response.json();
+      esriRequest(`${this.options.url}/${this._styleUrl}`, {
+        httpMethod: 'GET',
+        token,
+        apiKey,
+        authentication
       }).then(data => {
         if (!data || !Array.isArray(data.layers) || data.layers.length === 0) {
           throw new Error('VectorTile style document is missing layers.');
@@ -2010,8 +2065,17 @@ class VectorTileService {
   }
   getMetadata() {
     if (this._serviceMetadata !== null) return Promise.resolve(this._serviceMetadata);
+    const {
+      token,
+      apiKey,
+      authentication
+    } = this.esriServiceOptions;
     return new Promise((resolve, reject) => {
-      getServiceDetails(this.esriServiceOptions.url, this.esriServiceOptions.fetchOptions).then(data => {
+      getServiceDetails(this.esriServiceOptions.url, {
+        token,
+        apiKey,
+        authentication
+      }).then(data => {
         this._serviceMetadata = data;
         resolve(this._serviceMetadata);
       }).catch(err => reject(err));
@@ -2021,56 +2085,7 @@ class VectorTileService {
     // Vector tile services don't need dynamic updates like dynamic services
   }
   remove() {
-    const map = this._map;
-    if (!map || typeof map.removeSource !== 'function') {
-      return;
-    }
-    try {
-      // Guard against map whose style has already been destroyed
-      if (!map.style) return;
-      const mapWithStyle = map;
-      const mapLayerApi = map;
-      const mapSourceApi = map;
-      if (typeof mapWithStyle.getStyle === 'function') {
-        const style = mapWithStyle.getStyle();
-        const layers = style?.layers || [];
-        layers.forEach(layer => {
-          if (layer.source !== this._sourceId) return;
-          if (typeof mapLayerApi.getLayer !== 'function' || typeof mapLayerApi.removeLayer !== 'function') {
-            return;
-          }
-          let hasLayer = false;
-          try {
-            hasLayer = Boolean(mapLayerApi.getLayer(layer.id));
-          } catch {
-            hasLayer = false;
-          }
-          if (!hasLayer) return;
-          try {
-            mapLayerApi.removeLayer(layer.id);
-          } catch (error) {
-            console.warn(`Failed to remove layer ${layer.id} for source ${this._sourceId}:`, error);
-          }
-        });
-      }
-      if (typeof mapSourceApi.getSource === 'function') {
-        let hasSource = false;
-        try {
-          hasSource = Boolean(mapSourceApi.getSource(this._sourceId));
-        } catch {
-          hasSource = false;
-        }
-        if (hasSource) {
-          try {
-            map.removeSource(this._sourceId);
-          } catch (error) {
-            console.warn(`Failed to remove source ${this._sourceId}:`, error);
-          }
-        }
-      }
-    } catch (error) {
-      console.warn(`Failed to remove source ${this._sourceId}:`, error);
-    }
+    removeMapSource(this._map, this._sourceId);
   }
 }
 
@@ -2149,6 +2164,12 @@ class FeatureService {
       writable: true,
       value: null
     });
+    Object.defineProperty(this, "_removed", {
+      enumerable: true,
+      configurable: true,
+      writable: true,
+      value: false
+    });
     Object.defineProperty(this, "_format", {
       enumerable: true,
       configurable: true,
@@ -2292,29 +2313,9 @@ class FeatureService {
    * Remove the source and clean up event listeners
    */
   remove() {
+    this._removed = true;
     this.disableRequests();
-    if (this._map && typeof this._map.removeSource === 'function') {
-      try {
-        // Guard against map whose style has already been destroyed
-        const mapWithStyle = this._map;
-        if (!mapWithStyle.style) return;
-        // First, remove any layers that are using this source
-        if (mapWithStyle.getStyle) {
-          const style = mapWithStyle.getStyle();
-          const layers = style?.layers || [];
-          layers.forEach(layer => {
-            if (layer.source === this._sourceId && this._map.getLayer && this._map.getLayer(layer.id)) {
-              this._map.removeLayer(layer.id);
-            }
-          });
-        }
-        if (this._map.getSource && this._map.getSource(this._sourceId)) {
-          this._map.removeSource(this._sourceId);
-        }
-      } catch (error) {
-        console.warn(`Failed to remove source ${this._sourceId}:`, error);
-      }
-    }
+    removeMapSource(this._map, this._sourceId);
   }
   /** Alias for remove() for API compatibility */
   destroySource() {
@@ -2485,6 +2486,7 @@ class FeatureService {
     return newFeatureIdIndex;
   }
   async _findAndMapData() {
+    if (this._removed) return;
     const z = this._map.getZoom();
     if (z < this._esriServiceOptions.minZoom) {
       return;
@@ -2583,7 +2585,7 @@ class FeatureService {
       xmax: tileBounds[2],
       ymax: tileBounds[3]
     };
-    const params = new URLSearchParams({
+    const params = {
       f: this._format,
       geometry: JSON.stringify(extent),
       where: this._esriServiceOptions.where,
@@ -2601,18 +2603,24 @@ class FeatureService {
       spatialRel: 'esriSpatialRelIntersects',
       geometryType: 'esriGeometryEnvelope',
       inSR: '4326'
-    });
+    };
     if (this._time) {
-      params.append('time', this._time);
+      params.time = this._time;
     }
-    this._appendTokenIfExists(params);
+    const {
+      token,
+      apiKey,
+      authentication
+    } = this._authOptions();
+    const queryUrl = `${this._esriServiceOptions.url}/query`;
     try {
-      const response = await fetch(`${this._esriServiceOptions.url}/query?${params.toString()}`, this._esriServiceOptions.fetchOptions);
-      if (!response.ok) {
-        console.warn(`Tile fetch failed: HTTP ${response.status}`);
-        return null;
-      }
       if (this._format === 'pbf') {
+        const response = await esriRawRequest(queryUrl, {
+          params,
+          token,
+          apiKey,
+          authentication
+        });
         const buffer = await response.arrayBuffer();
         try {
           const decoded = tileDecode(new Uint8Array(buffer));
@@ -2622,8 +2630,12 @@ class FeatureService {
           return null;
         }
       } else {
-        const data = await response.json();
-        this._checkAgolError(data);
+        const data = await esriRequest(queryUrl, {
+          params,
+          token,
+          apiKey,
+          authentication
+        });
         return data;
       }
     } catch (error) {
@@ -2633,8 +2645,17 @@ class FeatureService {
     }
   }
   _updateFcOnMap(fc) {
-    const source = this._map.getSource(this._sourceId);
-    if (source && 'setData' in source) {
+    // Guard against an in-flight tile request resolving after the service/map
+    // was removed (e.g. a moveend handler firing during unmount).
+    const map = this._map;
+    if (this._removed || !map || !map.style || typeof map.getSource !== 'function') return;
+    let source;
+    try {
+      source = map.getSource(this._sourceId);
+    } catch {
+      return;
+    }
+    if (source && typeof source === 'object' && 'setData' in source) {
       source.setData(fc);
     }
   }
@@ -2648,18 +2669,13 @@ class FeatureService {
   }
   async _getServiceMetadata() {
     if (this._serviceMetadata !== null) return this._serviceMetadata;
-    const params = new URLSearchParams({
-      f: 'json'
+    // The FeatureService url is a layer endpoint, so the layer definition
+    // (supportedQueryFormats, uniqueIdField, extent, geometryType, …) comes
+    // from the typed `getLayer` helper.
+    const data = await getLayer({
+      url: this._esriServiceOptions.url,
+      authentication: this._authentication()
     });
-    this._appendTokenIfExists(params);
-    const response = await fetch(`${this._esriServiceOptions.url}?${params.toString()}`, this._esriServiceOptions.fetchOptions);
-    if (!response.ok) {
-      throw new Error(`Failed to fetch service metadata: HTTP ${response.status}`);
-    }
-    const data = await response.json();
-    if (data.error) {
-      throw new Error(JSON.stringify(data.error));
-    }
     this._serviceMetadata = data;
     return this._serviceMetadata;
   }
@@ -2667,7 +2683,7 @@ class FeatureService {
    * Query features by longitude/latitude with optional radius
    */
   async getFeaturesByLonLat(lnglat, radius = 20, returnGeometry = false) {
-    const params = new URLSearchParams({
+    const params = {
       sr: '4326',
       geometryType: 'esriGeometryPoint',
       geometry: JSON.stringify({
@@ -2677,41 +2693,41 @@ class FeatureService {
           wkid: 4326
         }
       }),
-      returnGeometry: returnGeometry.toString(),
+      returnGeometry,
       outFields: '*',
       spatialRel: 'esriSpatialRelIntersects',
       units: 'esriSRUnit_Meter',
-      distance: radius.toString(),
+      distance: radius,
       f: 'geojson'
-    });
+    };
     if (this._time) {
-      params.append('time', this._time);
+      params.time = this._time;
     }
-    this._appendTokenIfExists(params);
-    const response = await fetch(`${this._esriServiceOptions.url}/query?${params.toString()}`, this._esriServiceOptions.fetchOptions);
-    if (!response.ok) {
-      throw new Error(`Query failed: HTTP ${response.status}`);
-    }
-    return await response.json();
+    const result = await queryFeatures({
+      url: this._esriServiceOptions.url,
+      params,
+      authentication: this._authentication()
+    });
+    return result;
   }
   /**
    * Query features by object IDs
    */
   async getFeaturesByObjectIds(objectIds, returnGeometry = false) {
     const idsString = Array.isArray(objectIds) ? objectIds.join(',') : objectIds;
-    const params = new URLSearchParams({
+    const params = {
       sr: '4326',
       objectIds: idsString,
-      returnGeometry: returnGeometry.toString(),
+      returnGeometry,
       outFields: '*',
       f: 'geojson'
+    };
+    const result = await queryFeatures({
+      url: this._esriServiceOptions.url,
+      params,
+      authentication: this._authentication()
     });
-    this._appendTokenIfExists(params);
-    const response = await fetch(`${this._esriServiceOptions.url}/query?${params.toString()}`, this._esriServiceOptions.fetchOptions);
-    if (!response.ok) {
-      throw new Error(`Query failed: HTTP ${response.status}`);
-    }
-    return await response.json();
+    return result;
   }
   /**
    * Query features with custom options
@@ -2721,31 +2737,31 @@ class FeatureService {
       ...this._esriServiceOptions,
       ...options
     };
-    const params = new URLSearchParams();
-    params.append('f', 'geojson');
-    params.append('where', queryOptions.where || '1=1');
-    params.append('outFields', typeof queryOptions.outFields === 'string' ? queryOptions.outFields : queryOptions.outFields?.join(',') || '*');
-    params.append('returnGeometry', (queryOptions.returnGeometry !== false).toString());
+    const params = {};
+    params.f = 'geojson';
+    params.where = queryOptions.where || '1=1';
+    params.outFields = typeof queryOptions.outFields === 'string' ? queryOptions.outFields : queryOptions.outFields?.join(',') || '*';
+    params.returnGeometry = (queryOptions.returnGeometry !== false).toString();
     if (queryOptions.geometry) {
-      params.append('geometry', JSON.stringify(queryOptions.geometry));
-      if (queryOptions.geometryType) params.append('geometryType', queryOptions.geometryType);
-      if (queryOptions.spatialRel) params.append('spatialRel', queryOptions.spatialRel);
-      if (queryOptions.inSR) params.append('inSR', queryOptions.inSR);
-    }
-    if (queryOptions.outSR) params.append('outSR', queryOptions.outSR);
-    if (queryOptions.orderByFields) params.append('orderByFields', queryOptions.orderByFields);
-    if (queryOptions.groupByFieldsForStatistics) params.append('groupByFieldsForStatistics', queryOptions.groupByFieldsForStatistics);
-    if (queryOptions.outStatistics && queryOptions.outStatistics.length > 0) params.append('outStatistics', JSON.stringify(queryOptions.outStatistics));
-    if (queryOptions.having) params.append('having', queryOptions.having);
-    if (queryOptions.resultOffset) params.append('resultOffset', queryOptions.resultOffset.toString());
-    if (queryOptions.resultRecordCount) params.append('resultRecordCount', queryOptions.resultRecordCount.toString());
-    if (queryOptions.token) params.append('token', queryOptions.token);
+      params.geometry = JSON.stringify(queryOptions.geometry);
+      if (queryOptions.geometryType) params.geometryType = queryOptions.geometryType;
+      if (queryOptions.spatialRel) params.spatialRel = queryOptions.spatialRel;
+      if (queryOptions.inSR) params.inSR = queryOptions.inSR;
+    }
+    if (queryOptions.outSR) params.outSR = queryOptions.outSR;
+    if (queryOptions.orderByFields) params.orderByFields = queryOptions.orderByFields;
+    if (queryOptions.groupByFieldsForStatistics) params.groupByFieldsForStatistics = queryOptions.groupByFieldsForStatistics;
+    if (queryOptions.outStatistics && queryOptions.outStatistics.length > 0) params.outStatistics = JSON.stringify(queryOptions.outStatistics);
+    if (queryOptions.having) params.having = queryOptions.having;
+    if (queryOptions.resultOffset) params.resultOffset = queryOptions.resultOffset.toString();
+    if (queryOptions.resultRecordCount) params.resultRecordCount = queryOptions.resultRecordCount.toString();
     try {
-      const response = await fetch(`${this._esriServiceOptions.url}/query?${params.toString()}`, this._esriServiceOptions.fetchOptions);
-      if (!response.ok) {
-        throw new Error(`HTTP error! status: ${response.status}`);
-      }
-      return await response.json();
+      const result = await queryFeatures({
+        url: this._esriServiceOptions.url,
+        params,
+        authentication: this._authentication()
+      });
+      return result;
     } catch (error) {
       const isTestEnvironment = typeof process !== 'undefined' && process.env?.NODE_ENV === 'test';
       if (!isTestEnvironment) {
@@ -2756,7 +2772,7 @@ class FeatureService {
   }
   async _projectBounds() {
     if (!this._serviceMetadata?.extent) return;
-    const params = new URLSearchParams({
+    const params = {
       geometries: JSON.stringify({
         geometryType: 'esriGeometryEnvelope',
         geometries: [this._serviceMetadata.extent]
@@ -2764,22 +2780,15 @@ class FeatureService {
       inSR: (this._serviceMetadata.extent.spatialReference?.wkid || 4326).toString(),
       outSR: '4326',
       f: 'json'
-    });
-    let fetchOptions = this._esriServiceOptions.fetchOptions;
-    if (!this._projectionEndpointIsFallback()) {
-      this._appendTokenIfExists(params);
-    } else {
-      fetchOptions = undefined;
-    }
+    };
+    // The public fallback projection endpoint is anonymous; only forward auth
+    // to the service's own projection endpoint.
+    const auth = this._projectionEndpointIsFallback() ? {} : this._authOptions();
     try {
-      const response = await fetch(`${this._esriServiceOptions.projectionEndpoint}?${params.toString()}`, fetchOptions);
-      if (!response.ok) {
-        throw new Error(`Projection failed: HTTP ${response.status}`);
-      }
-      const data = await response.json();
-      if (data.error) {
-        throw new Error(JSON.stringify(data.error));
-      }
+      const data = await esriRequest(this._esriServiceOptions.projectionEndpoint, {
+        params,
+        ...auth
+      });
       const extent = data.geometries[0];
       this._maxExtent = [extent.xmin, extent.ymin, extent.xmax, extent.ymax];
     } catch (error) {
@@ -2805,28 +2814,22 @@ class FeatureService {
       updateAttribution('', this._sourceId, this._map);
     }
   }
-  _appendTokenIfExists(params) {
-    const token = this._esriServiceOptions.token;
-    if (token) {
-      params.append('token', token);
-    }
-  }
-  _getFetchHeaders() {
-    if (this._esriServiceOptions.apiKey) {
-      return {
-        'X-Esri-Authorization': `Bearer ${this._esriServiceOptions.apiKey}`
-      };
-    }
-    return undefined;
+  /**
+   * Read the authentication-related fields off the service options. The
+   * `authentication` field is not part of the public options type, so the
+   * options object is cast to surface it for {@link resolveAuthentication}.
+   */
+  _authOptions() {
+    const opts = this._esriServiceOptions;
+    return {
+      token: opts.token,
+      apiKey: opts.apiKey,
+      authentication: opts.authentication
+    };
   }
-  _checkAgolError(data) {
-    if (data && typeof data === 'object' && 'error' in data) {
-      const errorData = data.error;
-      const err = new Error(errorData.message || 'ArcGIS service error');
-      err.code = errorData.code;
-      err.details = errorData.details;
-      throw err;
-    }
+  /** Build an ArcGIS REST JS authentication manager from the service options. */
+  _authentication() {
+    return resolveAuthentication(this._authOptions());
   }
   _handleAuthError(error) {
     if (error && typeof error === 'object' && 'code' in error) {
@@ -2868,104 +2871,101 @@ class FeatureService {
     return this;
   }
   // ========================================
+  // Related Records & Domain Decoding
+  // ========================================
+  /**
+   * Query records related to this layer's features through a relationship
+   * class. Wraps `queryRelated` from `@esri/arcgis-rest-feature-service`.
+   */
+  async queryRelatedRecords(options) {
+    return queryRelated({
+      url: this._esriServiceOptions.url,
+      relationshipId: options.relationshipId,
+      objectIds: options.objectIds,
+      outFields: options.outFields,
+      definitionExpression: options.definitionExpression,
+      // `returnGeometry` is not a top-level queryRelated option; pass via params.
+      params: options.returnGeometry !== undefined ? {
+        returnGeometry: options.returnGeometry
+      } : undefined,
+      authentication: this._authentication()
+    });
+  }
+  /**
+   * Replace coded-value-domain codes with their human-readable names in a
+   * query response. Wraps `decodeValues` from
+   * `@esri/arcgis-rest-feature-service`.
+   *
+   * @param queryResponse A response from a `f=json` feature query.
+   * @param fields Optional subset of field names to decode (defaults to all).
+   */
+  async decodeValues(queryResponse, fields) {
+    return decodeValues({
+      url: this._esriServiceOptions.url,
+      queryResponse: queryResponse,
+      fields: fields,
+      authentication: this._authentication()
+    });
+  }
+  // ========================================
   // Feature Editing Methods
   // ========================================
   /**
    * Add features to the service
    */
   async addFeatures(features, options) {
-    const params = new URLSearchParams({
-      f: 'json',
-      features: JSON.stringify(features)
-    });
-    if (options?.gdbVersion) params.append('gdbVersion', options.gdbVersion);
-    this._appendTokenIfExists(params);
-    const response = await fetch(`${this._esriServiceOptions.url}/addFeatures`, {
-      method: 'POST',
-      body: params,
-      headers: this._getFetchHeaders(),
-      ...this._esriServiceOptions.fetchOptions
+    const res = await addFeatures({
+      url: this._esriServiceOptions.url,
+      features: features,
+      gdbVersion: options?.gdbVersion,
+      authentication: this._authentication()
     });
-    if (!response.ok) {
-      throw new Error(`Add features failed: HTTP ${response.status}`);
-    }
-    const data = await response.json();
-    this._checkAgolError(data);
-    return data.addResults;
+    return res.addResults;
   }
   /**
    * Update existing features
    */
   async updateFeatures(features, options) {
-    const params = new URLSearchParams({
-      f: 'json',
-      features: JSON.stringify(features)
+    const res = await updateFeatures({
+      url: this._esriServiceOptions.url,
+      features: features,
+      gdbVersion: options?.gdbVersion,
+      authentication: this._authentication()
     });
-    if (options?.gdbVersion) params.append('gdbVersion', options.gdbVersion);
-    this._appendTokenIfExists(params);
-    const response = await fetch(`${this._esriServiceOptions.url}/updateFeatures`, {
-      method: 'POST',
-      body: params,
-      headers: this._getFetchHeaders(),
-      ...this._esriServiceOptions.fetchOptions
-    });
-    if (!response.ok) {
-      throw new Error(`Update features failed: HTTP ${response.status}`);
-    }
-    const data = await response.json();
-    this._checkAgolError(data);
-    return data.updateResults;
+    return res.updateResults;
   }
   /**
    * Delete features by objectIds or where clause
    */
   async deleteFeatures(deleteParams) {
-    const params = new URLSearchParams({
-      f: 'json'
-    });
-    if (deleteParams.objectIds) {
-      params.append('objectIds', deleteParams.objectIds.join(','));
-    }
-    if (deleteParams.where) {
-      params.append('where', deleteParams.where);
-    }
-    this._appendTokenIfExists(params);
-    const response = await fetch(`${this._esriServiceOptions.url}/deleteFeatures`, {
-      method: 'POST',
-      body: params,
-      headers: this._getFetchHeaders(),
-      ...this._esriServiceOptions.fetchOptions
+    // Pass objectIds / where as first-order fields so arcgis-rest encodes them.
+    // Only include each when supplied: deletion by `where` alone must not send
+    // an empty objectIds list, and a hardcoded `objectIds: []` would (being
+    // truthy) override a supplied `where`/objectIds via appendCustomParams.
+    const res = await deleteFeatures({
+      url: this._esriServiceOptions.url,
+      authentication: this._authentication(),
+      ...(deleteParams.objectIds ? {
+        objectIds: deleteParams.objectIds
+      } : {}),
+      ...(deleteParams.where ? {
+        where: deleteParams.where
+      } : {})
     });
-    if (!response.ok) {
-      throw new Error(`Delete features failed: HTTP ${response.status}`);
-    }
-    const data = await response.json();
-    this._checkAgolError(data);
-    return data.deleteResults;
+    return res.deleteResults;
   }
   /**
    * Apply multiple edits in a single transaction
    */
   async applyEdits(edits, options) {
-    const params = new URLSearchParams({
-      f: 'json'
+    const data = await applyEdits({
+      url: this._esriServiceOptions.url,
+      adds: edits.adds,
+      updates: edits.updates,
+      deletes: edits.deletes,
+      gdbVersion: options?.gdbVersion,
+      authentication: this._authentication()
     });
-    if (edits.adds) params.append('adds', JSON.stringify(edits.adds));
-    if (edits.updates) params.append('updates', JSON.stringify(edits.updates));
-    if (edits.deletes) params.append('deletes', edits.deletes.join(','));
-    if (options?.gdbVersion) params.append('gdbVersion', options.gdbVersion);
-    this._appendTokenIfExists(params);
-    const response = await fetch(`${this._esriServiceOptions.url}/applyEdits`, {
-      method: 'POST',
-      body: params,
-      headers: this._getFetchHeaders(),
-      ...this._esriServiceOptions.fetchOptions
-    });
-    if (!response.ok) {
-      throw new Error(`Apply edits failed: HTTP ${response.status}`);
-    }
-    const data = await response.json();
-    this._checkAgolError(data);
     return data;
   }
   // ========================================
@@ -2975,71 +2975,45 @@ class FeatureService {
    * Query attachments for a feature
    */
   async queryAttachments(objectId, options) {
-    const params = new URLSearchParams({
-      f: 'json'
-    });
-    if (options?.globalIds) {
-      params.append('globalIds', options.globalIds.join(','));
-    }
-    this._appendTokenIfExists(params);
-    const response = await fetch(`${this._esriServiceOptions.url}/${objectId}/attachments?${params.toString()}`, {
-      headers: this._getFetchHeaders(),
-      ...this._esriServiceOptions.fetchOptions
+    const res = await getAttachments({
+      url: this._esriServiceOptions.url,
+      featureId: objectId,
+      params: options?.globalIds ? {
+        globalIds: options.globalIds.join(',')
+      } : undefined,
+      authentication: this._authentication()
     });
-    if (!response.ok) {
-      throw new Error(`Query attachments failed: HTTP ${response.status}`);
-    }
-    const data = await response.json();
-    this._checkAgolError(data);
-    return data.attachmentInfos || [];
+    return res.attachmentInfos || [];
   }
   /**
    * Add an attachment to a feature
    */
   async addAttachment(objectId, file, fileName) {
-    const formData = new FormData();
-    formData.append('f', 'json');
-    formData.append('attachment', file, fileName || (file instanceof File ? file.name : 'attachment'));
-    if (this._esriServiceOptions.token) {
-      formData.append('token', this._esriServiceOptions.token);
-    }
-    const headers = {};
-    if (this._esriServiceOptions.apiKey) {
-      headers['X-Esri-Authorization'] = `Bearer ${this._esriServiceOptions.apiKey}`;
-    }
-    const response = await fetch(`${this._esriServiceOptions.url}/${objectId}/addAttachment`, {
-      method: 'POST',
-      body: formData,
-      headers: Object.keys(headers).length > 0 ? headers : undefined
+    // The package `addAttachment` only accepts a `File`. Preserve the existing
+    // support for bare `Blob`s and an explicit `fileName` by posting the
+    // attachment ourselves; `esriRequest` handles auth and error responses.
+    const name = fileName || (file instanceof File ? file.name : 'attachment');
+    const res = await esriRequest(`${this._esriServiceOptions.url}/${objectId}/addAttachment`, {
+      params: {
+        attachment: file,
+        fileName: name
+      },
+      httpMethod: 'POST',
+      ...this._authOptions()
     });
-    if (!response.ok) {
-      throw new Error(`Add attachment failed: HTTP ${response.status}`);
-    }
-    const data = await response.json();
-    this._checkAgolError(data);
-    return data.addAttachmentResult;
+    return res.addAttachmentResult;
   }
   /**
    * Delete attachments from a feature
    */
   async deleteAttachments(objectId, attachmentIds) {
-    const params = new URLSearchParams({
-      f: 'json',
-      attachmentIds: attachmentIds.join(',')
-    });
-    this._appendTokenIfExists(params);
-    const response = await fetch(`${this._esriServiceOptions.url}/${objectId}/deleteAttachments`, {
-      method: 'POST',
-      body: params,
-      headers: this._getFetchHeaders(),
-      ...this._esriServiceOptions.fetchOptions
+    const res = await deleteAttachments({
+      url: this._esriServiceOptions.url,
+      featureId: objectId,
+      attachmentIds,
+      authentication: this._authentication()
     });
-    if (!response.ok) {
-      throw new Error(`Delete attachments failed: HTTP ${response.status}`);
-    }
-    const data = await response.json();
-    this._checkAgolError(data);
-    return data.deleteAttachmentResults;
+    return res.deleteAttachmentResults;
   }
   // Legacy method aliases for backwards compatibility
   /** @deprecated Use setWhere instead */
@@ -3212,58 +3186,31 @@ class Task {
     });
   }
   /**
-   * Direct HTTP request (when not using a service)
+   * Direct HTTP request (when not using a service), delegated to
+   * `@esri/arcgis-rest-request`. Token/apiKey supplied either as task options
+   * or as `token`/`apiKey` params are routed through the auth layer rather than
+   * being sent as raw query parameters.
    */
   _request(method, path, params, callback) {
     if (!this.options.url) {
       callback(new Error('URL is required for task execution'));
       return;
     }
-    // Ensure proper URL construction with path separator
-    const baseUrl = this.options.url.endsWith('/') ? this.options.url.slice(0, -1) : this.options.url;
+    const baseUrl = cleanTrailingSlash(this.options.url);
     const cleanPath = path.startsWith('/') ? path : `/${path}`;
-    const fullServiceUrl = `${baseUrl}${cleanPath}`;
-    const url = this.options.proxy ? `${this.options.proxy}?${fullServiceUrl}` : fullServiceUrl;
-    // Convert params to URLSearchParams
-    const searchParams = new URLSearchParams();
-    Object.keys(params).forEach(key => {
-      const value = params[key];
-      if (value !== undefined && value !== null) {
-        if (Array.isArray(value)) {
-          searchParams.append(key, value.join(','));
-        } else if (typeof value === 'object') {
-          searchParams.append(key, JSON.stringify(value));
-        } else {
-          searchParams.append(key, value.toString());
-        }
-      }
-    });
-    const fullUrl = method === 'GET' ? `${url}?${searchParams.toString()}` : url;
-    const fetchOptions = {
-      method,
-      headers: {
-        'Content-Type': 'application/x-www-form-urlencoded'
-      }
-    };
-    if (method === 'POST') {
-      fetchOptions.body = searchParams.toString();
-    }
-    fetch(fullUrl, fetchOptions).then(response => {
-      if (!response.ok) {
-        throw new Error(`HTTP error! status: ${response.status}`);
-      }
-      return response.json();
-    }).then(data => {
-      // Check for AGOL JSON-level errors (HTTP 200 with error body)
-      if (data && typeof data === 'object' && data.error) {
-        const err = new Error(data.error.message || 'ArcGIS service error');
-        err.code = data.error.code;
-        err.details = data.error.details;
-        callback(err);
-        return;
-      }
-      callback(undefined, data);
-    }).catch(error => callback(error));
+    const url = `${baseUrl}${cleanPath}`;
+    const {
+      token,
+      apiKey,
+      ...restParams
+    } = params;
+    esriRequest(url, {
+      params: restParams,
+      httpMethod: method === 'GET' ? 'GET' : 'POST',
+      token: token ?? this.options.token,
+      apiKey: apiKey ?? this.options.apikey,
+      authentication: this.options.authentication
+    }).then(data => callback(undefined, data)).catch(error => callback(error));
   }
 }
 
@@ -4276,5 +4223,205 @@ function identifyImage(options) {
   return new IdentifyImage(options);
 }
 
-export { DynamicMapService as D, FeatureService as F, IdentifyFeatures as I, Query as Q, Service as S, Task as T, VectorBasemapStyle as V, Find as a, IdentifyImage as b, ImageService as c, TiledMapService as d, VectorTileService as e, cleanTrailingSlash as f, find as g, getServiceDetails as h, identifyImage as i, query as q, updateAttribution as u };
-//# sourceMappingURL=IdentifyImage-DmyKcbAv.js.map
+/**
+ * Portal item resolution.
+ *
+ * Turns an ArcGIS portal item id into ready-to-render esri-gl services using
+ * `@esri/arcgis-rest-portal`. Two entry points are provided:
+ *
+ * - {@link serviceFromPortalItem} — resolve a single-layer item (Feature / Map /
+ *   Image / Vector Tile service) to the matching esri-gl service.
+ * - {@link servicesFromWebMap} — read a Web Map item's `operationalLayers`
+ *   (and optionally its basemap) and instantiate a service per layer.
+ */
+function requestOptions(options) {
+  const authentication = resolveAuthentication(options);
+  const opts = {};
+  if (authentication) opts.authentication = authentication;
+  if (options?.portal) opts.portal = options.portal;
+  return opts;
+}
+/** Shared auth fields forwarded into a constructed service's options. */
+function authServiceFields(options) {
+  const fields = {};
+  if (options?.authentication !== undefined) fields.authentication = options.authentication;
+  if (options?.apiKey !== undefined) fields.apiKey = options.apiKey;
+  if (options?.token !== undefined) fields.token = options.token;
+  return fields;
+}
+/** True when a Feature Service url already points at a specific sublayer. */
+function urlHasLayerIndex(url) {
+  return /\/\d+$/.test(cleanTrailingSlash(url));
+}
+/**
+ * Construct an esri-gl service for a known ArcGIS service `url` and a
+ * normalized service `kind`. Shared by single-item and web map resolution.
+ */
+function constructService(kind, sourceId, map, url, options) {
+  const auth = authServiceFields(options);
+  const serviceOptions = options?.serviceOptions ?? {};
+  const baseOptions = {
+    url,
+    ...auth,
+    ...serviceOptions
+  };
+  switch (kind) {
+    case 'tiled':
+      return new TiledMapService(sourceId, map, baseOptions, options?.rasterSrcOptions);
+    case 'image':
+      return new ImageService(sourceId, map, baseOptions, options?.rasterSrcOptions);
+    case 'vector-tile':
+      return new VectorTileService(sourceId, map, baseOptions, options?.vectorSrcOptions);
+    case 'feature':
+      {
+        let layerUrl = cleanTrailingSlash(url);
+        if (!urlHasLayerIndex(layerUrl)) {
+          layerUrl = `${layerUrl}/${options?.layerId ?? 0}`;
+        }
+        return new FeatureService(sourceId, map, {
+          ...baseOptions,
+          url: layerUrl
+        }, options?.geojsonSourceOptions);
+      }
+    case 'dynamic':
+    default:
+      return new DynamicMapService(sourceId, map, baseOptions, options?.rasterSrcOptions);
+  }
+}
+/** Map a portal item `type` (+ typeKeywords) to an esri-gl service kind. */
+function kindFromItemType(type, typeKeywords = []) {
+  switch (type) {
+    case 'Feature Service':
+    case 'Feature Layer':
+      return 'feature';
+    case 'Image Service':
+      return 'image';
+    case 'Vector Tile Service':
+      return 'vector-tile';
+    case 'Map Service':
+      {
+        const tiled = typeKeywords.some(k => /tiled|cached/i.test(k));
+        return tiled ? 'tiled' : 'dynamic';
+      }
+    default:
+      return null;
+  }
+}
+/**
+ * Resolve a single-layer portal item to the matching esri-gl service and add
+ * its source to the map.
+ *
+ * @example
+ * const { service } = await serviceFromPortalItem('my-source', map, 'a1b2c3', { token });
+ */
+async function serviceFromPortalItem(sourceId, map, itemId, options) {
+  const item = await getItem(itemId, requestOptions(options));
+  if (!item.url) {
+    throw new Error(`Portal item ${itemId} ("${item.title}") has no service url.`);
+  }
+  const kind = kindFromItemType(item.type, item.typeKeywords);
+  if (!kind) {
+    throw new Error(`Portal item ${itemId} has unsupported type "${item.type}" for esri-gl.`);
+  }
+  const service = constructService(kind, sourceId, map, item.url, options);
+  return {
+    service,
+    kind,
+    sourceId,
+    url: item.url,
+    item,
+    title: item.title
+  };
+}
+/** Map a Web Map operationalLayer `layerType` to an esri-gl service kind. */
+function kindFromLayerType(layerType) {
+  switch (layerType) {
+    case 'ArcGISFeatureLayer':
+      return 'feature';
+    case 'ArcGISMapServiceLayer':
+      return 'dynamic';
+    case 'ArcGISTiledMapServiceLayer':
+      return 'tiled';
+    case 'ArcGISImageServiceLayer':
+      return 'image';
+    case 'VectorTileLayer':
+      return 'vector-tile';
+    default:
+      return null;
+  }
+}
+/**
+ * Read a Web Map item's data and instantiate an esri-gl service for each
+ * supported operational layer (optionally including basemap layers).
+ * Unsupported layer types are skipped.
+ *
+ * @example
+ * const layers = await servicesFromWebMap(map, 'webmap-item-id', { token });
+ * layers.forEach(({ service, title }) => { ... });
+ */
+async function servicesFromWebMap(map, itemId, options) {
+  const data = await getItemData(itemId, requestOptions(options));
+  if (!data) {
+    throw new Error(`Web Map ${itemId} has no item data (is it shared / a Web Map?).`);
+  }
+  const prefix = options?.sourceIdPrefix ?? itemId;
+  const results = [];
+  const layers = [...(data.operationalLayers ?? [])];
+  if (options?.includeBasemap && data.baseMap?.baseMapLayers) {
+    layers.push(...data.baseMap.baseMapLayers);
+  }
+  layers.forEach((layer, index) => {
+    const kind = kindFromLayerType(layer.layerType);
+    const url = layer.url ?? layer.styleUrl;
+    if (!kind || !url) return; // skip unsupported / urlless layers
+    const sourceId = layer.id ? `${prefix}-${layer.id}` : `${prefix}-${index}`;
+    try {
+      const service = constructService(kind, sourceId, map, url, options);
+      results.push({
+        service,
+        kind,
+        sourceId,
+        url,
+        title: layer.title
+      });
+    } catch (error) {
+      console.warn(`Skipping web map layer "${layer.title ?? sourceId}":`, error);
+    }
+  });
+  return results;
+}
+// -----------------------------
+// Portal item search
+// -----------------------------
+/**
+ * Search an ArcGIS portal for items, e.g. to discover services to load.
+ * Thin wrapper over `searchItems` from `@esri/arcgis-rest-portal`; accepts a
+ * query string, a {@link SearchQueryBuilder}, or a full `ISearchOptions`.
+ *
+ * @example
+ * const { results } = await searchPortalItems('type:"Feature Service" AND owner:esri');
+ * // or with auth / paging:
+ * await searchPortalItems({ q: 'wildfire', num: 20, authentication }, { token });
+ */
+async function searchPortalItems(search, options) {
+  if (typeof search === 'string' || search instanceof SearchQueryBuilder) {
+    const {
+      authentication
+    } = requestOptions(options);
+    return searchItems({
+      q: search,
+      authentication
+    });
+  }
+  // Full ISearchOptions: merge in resolved auth/portal unless already provided.
+  const {
+    authentication
+  } = requestOptions(options);
+  return searchItems({
+    authentication,
+    ...search
+  });
+}
+
+export { DynamicMapService as D, FeatureService as F, IdentifyFeatures as I, Query as Q, Service as S, Task as T, VectorBasemapStyle as V, Find as a, IdentifyImage as b, ImageService as c, TiledMapService as d, VectorTileService as e, cleanTrailingSlash as f, esriRequest as g, find as h, getServiceDetails as i, identifyImage as j, serviceFromPortalItem as k, servicesFromWebMap as l, query as q, resolveAuthentication as r, searchPortalItems as s, updateAttribution as u };
+//# sourceMappingURL=index-DsY1_0df.js.map