esri-gl 1.0.5 → 2.0.0

package/README.md

@@ -6,6 +6,7 @@ A TypeScript library that bridges Esri ArcGIS REST services with MapLibre GL JS
 [![CI](https://github.com/muimsd/esri-gl/actions/workflows/ci.yml/badge.svg)](https://github.com/muimsd/esri-gl/actions/workflows/ci.yml)
 [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 **[Documentation](https://esri-gl.pages.dev/)** · **[Live Demos](https://esri-gl-demo.pages.dev/)** · **[npm](https://www.npmjs.com/package/esri-gl)**
 
 ## Features
@@ -28,6 +29,14 @@ A TypeScript library that bridges Esri ArcGIS REST services with MapLibre GL JS
 - **react-map-gl** — Declarative `<EsriDynamicLayer>`, `<EsriFeatureLayer>`, etc.
 - **TypeScript** — Full type safety with comprehensive interfaces
 
+### Built on ArcGIS REST JS
+- **Official client** — requests, authentication, and feature editing run on
+  [`@esri/arcgis-rest-js`](https://github.com/Esri/arcgis-rest-js)
+  (`-request`, `-feature-service`, `-portal`, `-basemap-sessions`)
+- **Flexible auth** — `token`, `apiKey`, or any `IAuthenticationManager`
+  (`ApiKeyManager`, `ArcGISIdentityManager`, …) on every service and task
+- **Portal item resolution** — turn a portal item id or Web Map into ready-to-render services
+
 ## Installation
 
 ```bash
@@ -132,6 +141,47 @@ const all = await query({ url: 'https://.../FeatureServer/0' })
   .runAll();
 ```
 
+## Authentication
+
+Every service and task accepts `token`, `apiKey`, or an `authentication` manager
+(precedence: `authentication` → `apiKey` → `token`). esri-gl uses ArcGIS REST JS's
+authentication managers under the hood.
+
+```typescript
+import { DynamicMapService, ArcGISIdentityManager, ApiKeyManager } from 'esri-gl';
+
+// API key or static token
+new DynamicMapService('source', map, { url, apiKey: 'AAPK…' });
+new DynamicMapService('source', map, { url, token: 'eyJ…' });
+
+// Named-user session with auto-refreshing token
+const session = await ArcGISIdentityManager.signIn({ username, password });
+new FeatureService('source', map, { url, authentication: session });
+```
+
+See the [Authentication guide](https://esri-gl.pages.dev/docs/guides/authentication) for
+the `authenticationrequired` event, the `esriRequest`/`resolveAuthentication` helpers, and
+migration notes.
+
+## Portal Items & Web Maps
+
+Resolve an ArcGIS portal item id — or a whole Web Map — straight to esri-gl services
+(powered by `@esri/arcgis-rest-portal`):
+
+```typescript
+import { serviceFromPortalItem, servicesFromWebMap } from 'esri-gl';
+
+// Single item → the matching service (Feature/Map/Image/Vector Tile)
+const { service, kind } = await serviceFromPortalItem('my-source', map, itemId, { apiKey });
+map.addLayer({ id: 'my-layer', type: 'raster', source: 'my-source' });
+
+// Web Map → a service per operational layer
+const layers = await servicesFromWebMap(map, webMapItemId, { token });
+```
+
+See the [Portal Items guide](https://esri-gl.pages.dev/docs/guides/portal-items) for the
+item-type/layer-type mappings and options.
+
 ## React Integration
 
 ### Hooks
@@ -160,6 +210,7 @@ import { EsriDynamicLayer, EsriFeatureLayer } from 'esri-gl/react-map-gl';
     url="https://.../Census/MapServer"
     layers={[0, 1]}
     opacity={0.8}
+    token="YOUR_TOKEN"
   />
   <EsriFeatureLayer
     id="states"
@@ -169,6 +220,8 @@ import { EsriDynamicLayer, EsriFeatureLayer } from 'esri-gl/react-map-gl';
 </Map>
 ```
 
+All layer components accept `token`, `apiKey`, `authentication`, `getAttributionFromService`, and `requestParams` for authenticated services and custom request behavior.
+
 ## Examples
 
 Working examples in [`examples/`](examples/):
@@ -188,7 +241,7 @@ cd examples/maplibre-esm && npm install && npm run dev
 ```bash
 npm run dev          # Start demo dev server
 npm run build        # Build library (ESM + UMD)
-npm run test         # Run tests (727 tests, 31 suites)
+npm run test         # Run tests (733 tests, 31 suites)
 npm run type-check   # TypeScript check
 npm run lint         # ESLint
 npm run build:docs   # Build documentation site
@@ -214,6 +267,7 @@ MIT — see [LICENSE](LICENSE)
 
 ## Acknowledgements
 
+- **[ArcGIS REST JS](https://github.com/Esri/arcgis-rest-js)** — official client powering requests, auth, feature editing, and portal access
 - **[Esri Leaflet](https://esri.github.io/esri-leaflet/)** — API design inspiration
 - **[mapbox-gl-esri-sources](https://github.com/frontiersi/mapbox-gl-esri-sources/)** — Foundational integration patterns (this project originated as a fork)
 - **[mapbox-gl-arcgis-featureserver](https://github.com/rowanwins/mapbox-gl-arcgis-featureserver)** by Rowan Winsemius — FeatureService PBF implementation

package/dist/{index-DczUYC4z.d.ts → index-Doq93o-G.d.ts}

@@ -1,4 +1,62 @@
+import { IAuthenticationManager, IFeatureSet, IField, IExtent } from '@esri/arcgis-rest-request';
+import * as _esri_arcgis_rest_feature_service from '@esri/arcgis-rest-feature-service';
+import { IApplyEditsResult, IAttachmentInfo, IEditFeatureResult } from '@esri/arcgis-rest-feature-service';
 import { Map } from 'maplibre-gl';
+import { BasemapStyleSession } from '@esri/arcgis-rest-basemap-sessions';
+import { IItem, SearchQueryBuilder, ISearchOptions, ISearchResult } from '@esri/arcgis-rest-portal';
+
+/**
+ * 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.
+ */
+
+/**
+ * Authentication accepted throughout esri-gl. Either an ArcGIS REST JS
+ * authentication manager (`ApiKeyManager`, `ArcGISIdentityManager`, …) or a
+ * raw token/API-key string for convenience.
+ */
+type EsriAuthentication = IAuthenticationManager | string;
+/**
+ * Options every service/task accepts for authenticating ArcGIS REST requests.
+ * `authentication` takes precedence, then `apiKey`, then `token`.
+ */
+interface EsriAuthOptions {
+    /** An ArcGIS REST JS authentication manager. */
+    authentication?: EsriAuthentication;
+    /** A static API key (ArcGIS Location Platform). */
+    apiKey?: string;
+    /** A static, pre-generated token. */
+    token?: string;
+}
+/**
+ * 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.
+ */
+declare function resolveAuthentication(options: EsriAuthOptions | undefined): IAuthenticationManager | undefined;
+interface EsriRequestOptions extends EsriAuthOptions {
+    /** Query/body parameters. `f: 'json'` is supplied by default. */
+    params?: Record<string, unknown>;
+    /** HTTP method. ArcGIS REST JS defaults to POST; most reads use GET. */
+    httpMethod?: 'GET' | 'POST';
+    /** Return the raw `Response` instead of the parsed body (e.g. for PBF). */
+    rawResponse?: boolean;
+    /** Abort signal for cancellation/timeout support. */
+    signal?: AbortSignal;
+    /** Additional request headers. */
+    headers?: Record<string, string>;
+}
+/**
+ * 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.
+ */
+declare function esriRequest<T = unknown>(url: string, options?: EsriRequestOptions): Promise<T>;
 
 interface ServiceMetadata {
     attribution?: string;
@@ -21,6 +79,12 @@ interface EsriServiceOptions {
     transparent?: boolean;
     getAttributionFromService?: boolean;
     time?: number[] | false;
+    /** Static token sent as the `token` parameter. */
+    token?: string;
+    /** ArcGIS Location Platform API key. */
+    apiKey?: string;
+    /** An ArcGIS REST JS authentication manager (takes precedence over token/apiKey). */
+    authentication?: EsriAuthentication;
 }
 interface RasterSourceOptions {
     attribution?: string;
@@ -71,11 +135,15 @@ interface FeatureServiceOptions {
     useVectorTiles?: boolean;
     token?: string;
     apiKey?: string;
+    authentication?: EsriAuthentication;
     layers?: number[] | number;
 }
 interface VectorTileServiceOptions {
     url: string;
     getAttributionFromService?: boolean;
+    token?: string;
+    apiKey?: string;
+    authentication?: EsriAuthentication;
 }
 interface VectorBasemapStyleOptions {
     basemapEnum: string;
@@ -192,23 +260,12 @@ interface LayerLabelingInfo {
 interface StatisticResult {
     attributes: Record<string, unknown>;
 }
-interface FieldInfo {
-    name: string;
-    type: 'esriFieldTypeOID' | 'esriFieldTypeString' | 'esriFieldTypeInteger' | 'esriFieldTypeSmallInteger' | 'esriFieldTypeDouble' | 'esriFieldTypeSingle' | 'esriFieldTypeDate' | 'esriFieldTypeGeometry' | 'esriFieldTypeBlob' | 'esriFieldTypeRaster' | 'esriFieldTypeGUID' | 'esriFieldTypeGlobalID' | 'esriFieldTypeXML';
-    alias?: string;
+/** Layer field metadata. Alias of `IField` (@esri/arcgis-rest-request). */
+type FieldInfo = IField & {
     length?: number;
     nullable?: boolean;
     defaultValue?: unknown;
-    domain?: {
-        type: 'codedValue' | 'range';
-        name?: string;
-        codedValues?: Array<{
-            name: string;
-            code: unknown;
-        }>;
-        range?: [number, number];
-    };
-}
+};
 interface LayerInfo {
     id: number;
     name: string;
@@ -244,29 +301,10 @@ interface LayerMetadata extends LayerInfo {
         cardinality: 'esriRelCardinalityOneToOne' | 'esriRelCardinalityOneToMany' | 'esriRelCardinalityManyToMany';
     }>;
 }
-interface Extent {
-    xmin: number;
-    ymin: number;
-    xmax: number;
-    ymax: number;
-    spatialReference?: {
-        wkid?: number;
-        latestWkid?: number;
-    };
-}
-interface FeatureSet {
-    features: Array<{
-        attributes: Record<string, unknown>;
-        geometry?: Record<string, unknown>;
-    }>;
-    geometryType?: string;
-    spatialReference?: {
-        wkid?: number;
-        latestWkid?: number;
-    };
-    fields?: FieldInfo[];
+type Extent = IExtent;
+type FeatureSet = IFeatureSet & {
     exceededTransferLimit?: boolean;
-}
+};
 interface LayerQueryOptions {
     where?: string;
     geometry?: GeoJSON.Geometry;
@@ -346,31 +384,23 @@ interface AGOLServiceError {
     message: string;
     details?: string[];
 }
-interface EditResult {
-    objectId: number;
+/** Result of a single add/update/delete. Alias of `IEditFeatureResult`. */
+type EditResult = IEditFeatureResult;
+/** Result of an applyEdits transaction. Alias of `IApplyEditsResult`. */
+type ApplyEditsResult = IApplyEditsResult;
+/** Feature attachment metadata. Alias of `IAttachmentInfo` plus optional extras. */
+type AttachmentInfo = IAttachmentInfo & {
     globalId?: string;
-    success: boolean;
-    error?: AGOLServiceError;
-}
-interface ApplyEditsResult {
-    addResults?: EditResult[];
-    updateResults?: EditResult[];
-    deleteResults?: EditResult[];
-}
-interface AttachmentInfo {
-    id: number;
-    globalId?: string;
-    name: string;
-    contentType: string;
-    size: number;
     keywords?: string;
-}
+};
 interface PaginatedFeatureCollection extends GeoJSON.FeatureCollection {
     exceededTransferLimit?: boolean;
 }
 
 interface ServiceOptions {
     url: string;
+    /** @deprecated The leaflet-style proxy string is no longer applied; configure
+     * a proxy through your `authentication` manager or a global fetch override. */
     proxy?: string | boolean;
     useCors?: boolean;
     timeout?: number;
@@ -378,6 +408,8 @@ interface ServiceOptions {
     requestParams?: Record<string, unknown>;
     getAttributionFromService?: boolean;
     apiKey?: string;
+    /** An ArcGIS REST JS authentication manager (takes precedence over token/apiKey). */
+    authentication?: EsriAuthentication;
 }
 type ServiceCallback<T = unknown> = (error?: Error, response?: T) => void;
 interface ServiceEvents {
@@ -536,6 +568,9 @@ declare class DynamicMapService {
     setLayerDefinition(layerId: number, definitionExpression: string): void;
     setLayerFilter(layerId: number, filter: LayerFilter): void;
     private _appendTokenIfExists;
+    private _auth;
+    /** Resolved ArcGIS REST JS auth manager for the typed feature-service helpers. */
+    private _authentication;
     private _escapeValue;
     private _isGroupFilter;
     private _isBetweenFilter;
@@ -670,6 +705,7 @@ declare class ImageService {
  * Note: MapLibre GL v5+ may show vector tile parsing warnings with some Esri tiles.
  * These warnings are expected and do not affect map rendering functionality.
  */
+
 type EsriBasemapStyleName = 'arcgis/streets' | 'arcgis/topographic' | 'arcgis/navigation' | 'arcgis/streets-relief' | 'arcgis/dark-gray' | 'arcgis/light-gray' | 'arcgis/oceans' | 'arcgis/imagery' | 'arcgis/streets-night' | 'arcgis:streets' | 'arcgis:topographic' | 'arcgis:navigation' | 'arcgis:streetsrelief' | 'arcgis:darkgray' | 'arcgis:lightgray' | 'arcgis:oceans' | 'arcgis:imagery' | 'arcgis:streetsnight' | string;
 interface VectorBasemapStyleAuthOptions {
     apiKey?: string;
@@ -681,6 +717,8 @@ interface VectorBasemapStyleAuthOptions {
     language?: string;
     worldview?: string;
     itemId?: string;
+    useSession?: boolean;
+    sessionDuration?: number;
 }
 declare class VectorBasemapStyle {
     styleName: string;
@@ -693,6 +731,9 @@ declare class VectorBasemapStyle {
     private _language?;
     private _worldview?;
     private _itemId?;
+    private _useSession;
+    private _sessionDuration?;
+    private _session?;
     private static readonly COLON_TO_SLASH;
     constructor(styleName?: EsriBasemapStyleName, auth?: string | VectorBasemapStyleAuthOptions);
     get styleUrl(): string;
@@ -716,6 +757,35 @@ declare class VectorBasemapStyle {
     static applyStyle(map: {
         setStyle: (style: string) => void;
     }, styleName: EsriBasemapStyleName, auth: VectorBasemapStyleAuthOptions): void;
+    /**
+     * The style family for the official basemap sessions API, derived from the
+     * canonical style id. esri-gl styles are all in the `arcgis` family.
+     */
+    private get _styleFamily();
+    /**
+     * The token from the active session, if a session has been started. Useful
+     * for inspection / debugging. Returns `undefined` until `startSession()` runs.
+     */
+    get sessionToken(): string | undefined;
+    /**
+     * 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.
+     */
+    startSession(): Promise<BasemapStyleSession>;
+    /**
+     * 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`.
+     */
+    getStyleUrl(): Promise<string>;
+    /**
+     * 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 applyStyleWithSession(map: {
+        setStyle: (style: string) => void;
+    }, styleName: EsriBasemapStyleName, auth: VectorBasemapStyleAuthOptions): Promise<void>;
     private static _toCanonical;
 }
 
@@ -759,20 +829,6 @@ declare class VectorTileService {
     remove(): void;
 }
 
-/**
- * FeatureService - Tile-based feature loading from ArcGIS FeatureServers
- *
- * This implementation is based on mapbox-gl-arcgis-featureserver by Rowan Winsemius
- * @see https://github.com/rowanwins/mapbox-gl-arcgis-featureserver
- *
- * Key features:
- * - Prioritizes PBF format for minimal payload size (requires ArcGIS Server 10.7+)
- * - Falls back to GeoJSON if PBF is not supported
- * - Uses tiled requests for efficient data loading
- * - Client-side feature deduplication
- * - Service bounds detection and coordinate projection
- */
-
 interface FeatureServiceExtendedOptions extends FeatureServiceOptions {
     fetchOptions?: RequestInit;
     /** Use a static zoom level for tile requests instead of dynamic */
@@ -793,7 +849,7 @@ interface FeatureServiceExtendedOptions extends FeatureServiceOptions {
     useServiceBounds?: boolean;
     /** Custom projection endpoint URL */
     projectionEndpoint?: string;
-    /** API key sent via X-Esri-Authorization header */
+    /** ArcGIS Location Platform API key (sent as the `token` parameter) */
     apiKey?: string;
 }
 interface GeoJSONSourceOptions {
@@ -841,6 +897,7 @@ declare class FeatureService {
     private _serviceMetadata;
     private _maxExtent;
     private _boundEvent;
+    private _removed;
     private _format;
     private _sourceReadyResolve;
     private _sourceReadyReject;
@@ -934,9 +991,14 @@ declare class FeatureService {
     private _projectBounds;
     private _projectionEndpointIsFallback;
     private _setAttribution;
-    private _appendTokenIfExists;
-    private _getFetchHeaders;
-    private _checkAgolError;
+    /**
+     * 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}.
+     */
+    private _authOptions;
+    /** Build an ArcGIS REST JS authentication manager from the service options. */
+    private _authentication;
     private _handleAuthError;
     private _fireEvent;
     /**
@@ -947,6 +1009,26 @@ declare class FeatureService {
      * Remove event listener
      */
     off(event: string, callback: (event: unknown) => void): FeatureService;
+    /**
+     * Query records related to this layer's features through a relationship
+     * class. Wraps `queryRelated` from `@esri/arcgis-rest-feature-service`.
+     */
+    queryRelatedRecords(options: {
+        relationshipId?: number;
+        objectIds?: number[];
+        outFields?: string | string[];
+        definitionExpression?: string;
+        returnGeometry?: boolean;
+    }): Promise<_esri_arcgis_rest_feature_service.IQueryRelatedResponse>;
+    /**
+     * 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).
+     */
+    decodeValues(queryResponse: unknown, fields?: string[]): Promise<_esri_arcgis_rest_feature_service.IQueryFeaturesResponse>;
     /**
      * Add features to the service
      */
@@ -1006,11 +1088,14 @@ declare class FeatureService {
 
 interface TaskOptions {
     url?: string;
+    /** @deprecated No longer applied; use `authentication` or a global fetch override. */
     proxy?: string | boolean;
     useCors?: boolean;
     requestParams?: Record<string, unknown>;
     token?: string;
     apikey?: string;
+    /** An ArcGIS REST JS authentication manager (takes precedence over token/apikey). */
+    authentication?: EsriAuthentication;
 }
 /**
  * Base Task class for ArcGIS REST API operations
@@ -1048,7 +1133,10 @@ declare class Task {
      */
     request<T = unknown>(): Promise<T>;
     /**
-     * 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.
      */
     private _request;
 }
@@ -1528,9 +1616,98 @@ declare class IdentifyImage extends Task {
 }
 declare function identifyImage(options: string | IdentifyImageOptions): IdentifyImage;
 
+/**
+ * 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.
+ */
+
+/** Any esri-gl service instance a portal item can resolve to. */
+type PortalResolvedService = DynamicMapService | TiledMapService | ImageService | VectorTileService | FeatureService;
+/** esri-gl service kinds, used to label resolution results. */
+type PortalServiceKind = 'dynamic' | 'tiled' | 'image' | 'vector-tile' | 'feature';
+interface PortalRequestOptions extends EsriAuthOptions {
+    /** Portal sharing REST URL. Defaults to ArcGIS Online. */
+    portal?: string;
+}
+interface PortalItemServiceOptions extends PortalRequestOptions {
+    /** For multi-layer Feature Services, which sublayer to load (default 0). */
+    layerId?: number;
+    /** Extra options merged into the constructed service's options object. */
+    serviceOptions?: Record<string, unknown>;
+    /** Raster source options (Dynamic / Tiled / Image services). */
+    rasterSrcOptions?: Record<string, unknown>;
+    /** Vector source options (Vector Tile service). */
+    vectorSrcOptions?: Record<string, unknown>;
+    /** GeoJSON source options (Feature service). */
+    geojsonSourceOptions?: Record<string, unknown>;
+}
+interface PortalServiceResult {
+    /** The instantiated esri-gl service. */
+    service: PortalResolvedService;
+    /** Which kind of service was created. */
+    kind: PortalServiceKind;
+    /** The source id registered on the map. */
+    sourceId: string;
+    /** The service URL the item resolved to. */
+    url: string;
+    /** The portal item (single-item resolution only). */
+    item?: IItem;
+    /** Human-readable title (item title or web map layer title). */
+    title?: string;
+}
+/**
+ * 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 });
+ */
+declare function serviceFromPortalItem(sourceId: string, map: Map, itemId: string, options?: PortalItemServiceOptions): Promise<PortalServiceResult>;
+interface WebMapOptions extends PortalItemServiceOptions {
+    /** Also instantiate the web map's basemap layers (default false). */
+    includeBasemap?: boolean;
+    /** Prefix for generated source ids (default the web map item id). */
+    sourceIdPrefix?: string;
+}
+/**
+ * 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 }) => { ... });
+ */
+declare function servicesFromWebMap(map: Map, itemId: string, options?: WebMapOptions): Promise<PortalServiceResult[]>;
+/**
+ * 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 });
+ */
+declare function searchPortalItems(search: string | SearchQueryBuilder | ISearchOptions, options?: PortalRequestOptions): Promise<ISearchResult<IItem>>;
+
 declare function cleanTrailingSlash(url: string): string;
-declare function getServiceDetails(url: string, fetchOptions?: RequestInit, token?: string): Promise<ServiceMetadata>;
+/**
+ * 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`).
+ */
+declare function getServiceDetails(url: string, options?: EsriRequestOptions): Promise<ServiceMetadata>;
 declare function updateAttribution(newAttribution: string, sourceId: string, map: Map): void;
 
-export { DynamicMapService as D, TiledMapService as T, Query as X, Service as Z, Task as a3, cleanTrailingSlash as a6, find as a7, getServiceDetails as a8, identifyImage as a9, query as aa, updateAttribution as ab, ImageService as e, VectorTileService as f, FeatureService as g, VectorBasemapStyle as h, IdentifyImage as i, Find as v, IdentifyFeatures as w };
-export type { ServiceEventType as $, ApplyEditsResult as A, BatchLayerOperation as B, ComparisonFilter as C, EsriServiceOptions as E, FeatureServiceOptions as F, GroupFilter as G, LayerMetadata as H, IdentifyImageOptions as I, LayerQueryOptions as J, LayerScaleRange as K, LayerFilter as L, LayerSpecification as M, LayerTimeOptions as N, LayerUpdateEvent as O, LayerUpdateType as P, LegendInfo as Q, LogicalOp as R, MapExportOptions as S, NullFilter as U, VectorBasemapStyleOptions as V, PaginatedFeatureCollection as W, RasterSourceOptions as Y, ServiceErrorEvent as _, EditResult as a, ServiceMetadata as a0, SourceSpecification as a1, StatisticResult as a2, TimeAnimationOptions as a4, VectorSourceOptions as a5, FindOptions as b, ImageServiceOptions as c, VectorTileServiceOptions as d, AGOLServiceError as j, AttachmentInfo as k, BetweenFilter as l, ComparisonOp as m, DynamicLayer as n, EsriDrawingInfo as o, EsriDynamicMapLayerSource as p, EsriRenderer as q, EsriTextSymbol as r, Extent as s, FeatureSet as t, FieldInfo as u, InFilter as x, LayerInfo as y, LayerLabelingInfo as z };
+export { DynamicMapService as D, Find as G, IdentifyFeatures as J, TiledMapService as T, Query as a3, Service as a5, Task as ab, cleanTrailingSlash as af, esriRequest as ag, find as ah, getServiceDetails as ai, identifyImage as aj, query as ak, resolveAuthentication as al, searchPortalItems as am, serviceFromPortalItem as an, servicesFromWebMap as ao, updateAttribution as ap, ImageService as g, VectorTileService as h, FeatureService as i, VectorBasemapStyle as j, IdentifyImage as k };
+export type { NullFilter as $, ApplyEditsResult as A, BatchLayerOperation as B, ComparisonFilter as C, EsriServiceOptions as E, FeatureServiceOptions as F, GroupFilter as H, IdentifyImageOptions as I, InFilter as K, LayerFilter as L, LayerInfo as M, LayerLabelingInfo as N, LayerMetadata as O, PortalItemServiceOptions as P, LayerQueryOptions as Q, LayerScaleRange as R, LayerSpecification as S, LayerTimeOptions as U, VectorBasemapStyleOptions as V, LayerUpdateEvent as W, LayerUpdateType as X, LegendInfo as Y, LogicalOp as Z, MapExportOptions as _, EditResult as a, PaginatedFeatureCollection as a0, PortalRequestOptions as a1, PortalServiceResult as a2, RasterSourceOptions as a4, ServiceErrorEvent as a6, ServiceEventType as a7, ServiceMetadata as a8, SourceSpecification as a9, StatisticResult as aa, TimeAnimationOptions as ac, VectorSourceOptions as ad, WebMapOptions as ae, FindOptions as b, ImageServiceOptions as c, PortalResolvedService as d, PortalServiceKind as e, VectorTileServiceOptions as f, AGOLServiceError as l, AttachmentInfo as m, BetweenFilter as n, ComparisonOp as o, DynamicLayer as p, EsriAuthOptions as q, EsriAuthentication as r, EsriDrawingInfo as s, EsriDynamicMapLayerSource as t, EsriRenderer as u, EsriRequestOptions as v, EsriTextSymbol as w, Extent as x, FeatureSet as y, FieldInfo as z };