@honua/react 0.0.20-alpha.0 → 0.1.1-beta.0

package/esri-compat/oauth-info.js

@@ -86,6 +86,33 @@ export class OAuthInfoCompat {
             this.notifyWatchers("preserveUrlHash", this.preserveUrlHash);
         }
     }
+    /**
+     * Derive an {@link OAuth2Config} from this Esri-style OAuth info so it can back
+     * a real `oauth2(...)` provider from `@honua/sdk-js/auth`. Endpoints default to
+     * the ArcGIS Portal shape (`<portalUrl>/sharing/rest/oauth2/authorize` and
+     * `/token`); pass explicit endpoints or a `redirectUri` via `overrides`.
+     */
+    toOAuth2Config(overrides = {}) {
+        const clientId = overrides.clientId ?? this.appId;
+        if (!clientId) {
+            throw new Error("OAuthInfoCompat.toOAuth2Config requires an appId (or an explicit clientId override).");
+        }
+        const redirectUri = overrides.redirectUri;
+        if (!redirectUri) {
+            throw new Error("OAuthInfoCompat.toOAuth2Config requires a redirectUri override.");
+        }
+        const portalBase = this.portalUrl.replace(/\/+$/, "");
+        const { redirectUri: _redirectUri, clientId: _clientId, ...rest } = overrides;
+        return {
+            authorizationEndpoint: `${portalBase}/sharing/rest/oauth2/authorize`,
+            tokenEndpoint: `${portalBase}/sharing/rest/oauth2/token`,
+            clientId,
+            redirectUri,
+            mode: this.popup ? "popup" : "redirect",
+            ...(this.expiration !== undefined ? { extraAuthorizationParams: { expiration: String(this.expiration) } } : {}),
+            ...rest,
+        };
+    }
     clone() {
         return new OAuthInfoCompat(this.toJSON());
     }

package/esri-compat/portal.d.ts

@@ -0,0 +1,197 @@
+import { HonuaClient } from "../core/client.js";
+import { FeatureLayerCompat } from "./feature-layer.js";
+/**
+ * A single item as returned by the Honua Portal facade
+ * (`/sharing/rest/search` and `/sharing/rest/content/items/{id}`). Mirrors the
+ * ArcGIS Portal item shape so a repointed app reads the same fields.
+ */
+export interface PortalItem {
+    id: string;
+    owner: string;
+    created: number;
+    modified: number;
+    type: string;
+    typeKeywords: string[];
+    title: string;
+    snippet: string | null;
+    description: string | null;
+    tags: string[];
+    /** Absolute service URL, e.g. `.../rest/services/{name}/FeatureServer`. */
+    url: string | null;
+    access: "public" | "org" | "private" | string;
+    extent: number[][] | null;
+    spatialReference: string | null;
+    culture: string | null;
+    numComments: number;
+    numViews: number;
+    [key: string]: unknown;
+}
+/** Parsed `/sharing/rest/search` response. */
+export interface PortalSearchResult {
+    query: string;
+    total: number;
+    /** 1-based index of the first result in this page. */
+    start: number;
+    num: number;
+    /** Index of the next page's first result, or `-1` on the last page. */
+    nextStart: number;
+    results: PortalItem[];
+}
+/** `/sharing/rest/info` response (subset the client relies on). */
+export interface PortalInfo {
+    authInfo?: {
+        isTokenBasedSecurity?: boolean;
+        tokenServicesUrl?: string;
+    };
+    [key: string]: unknown;
+}
+/** `/sharing/rest/portals/self` response (subset the client relies on). */
+export interface PortalSelf {
+    id?: string;
+    isPortal?: boolean;
+    name?: string;
+    portalName?: string;
+    user?: {
+        username: string;
+        fullName?: string;
+        role?: string;
+    } | null;
+    [key: string]: unknown;
+}
+/** Options accepted by {@link PortalCompat}. */
+export interface PortalCompatOptions {
+    /**
+     * Portal base URL. Accepts either a portal root (`https://portal.example`) or
+     * a `/sharing/rest` base; both normalize to the `.../sharing/rest` endpoint
+     * base. Defaults to {@link esriConfig.portalUrl}.
+     */
+    portalUrl?: string;
+    /** Pre-obtained token to attach to authenticated calls. */
+    token?: string;
+    /** Static API key (falls back to {@link esriConfig.apiKey}). */
+    apiKey?: string;
+    /** Override the global `fetch` implementation (useful in tests). */
+    fetchFn?: typeof fetch;
+}
+/** Options for {@link PortalCompat.generateToken}. */
+export interface PortalGenerateTokenOptions {
+    username: string;
+    password: string;
+    /** Referer registered with the token. Defaults to the portal origin. */
+    referer?: string;
+    /** Esri `client` param (`"referer"` | `"requestip"` | `"ip"`). Defaults to `"referer"`. */
+    client?: string;
+    /** Token lifetime in minutes. */
+    expirationMinutes?: number;
+}
+/** Result of {@link PortalCompat.generateToken}. */
+export interface PortalTokenCredential {
+    token: string;
+    /** Absolute expiry as a unix-millisecond timestamp. */
+    expiresAtMs: number;
+    ssl: boolean;
+}
+/** Options for {@link PortalCompat.search}. */
+export interface PortalSearchOptions {
+    q?: string;
+    start?: number;
+    num?: number;
+    token?: string;
+}
+/** Options for {@link PortalCompat.getItem}. */
+export interface PortalGetItemOptions {
+    token?: string;
+}
+/** Options for {@link PortalCompat.openFeatureLayer}. */
+export interface PortalOpenOptions {
+    /** Layer id to open for Feature Service items. Defaults to the service's first advertised layer. */
+    layerId?: number;
+}
+interface PortalOpenResultBase {
+    /** Resolved portal item. */
+    item: PortalItem;
+    /** Service base (`.../rest/services`-prefixed origin/prefix) without the service segment. */
+    baseUrl: string;
+    /** Service (folder/name) id parsed from the item URL. */
+    serviceId: string;
+    /** Authenticated client bound to `baseUrl`, carrying the portal credential. */
+    client: HonuaClient;
+}
+/** Feature Service open result: includes a ready-to-use {@link FeatureLayerCompat}. */
+export interface PortalFeatureServiceOpenResult extends PortalOpenResultBase {
+    type: "feature-service";
+    layerId: number;
+    layer: FeatureLayerCompat;
+}
+/** Map/Image Service open result: the resolved, authenticated service handle. */
+export interface PortalServiceOpenResult extends PortalOpenResultBase {
+    type: "map-service" | "image-service";
+}
+export type PortalOpenResult = PortalFeatureServiceOpenResult | PortalServiceOpenResult;
+/** Error thrown when the Portal facade returns an Esri error envelope. */
+export declare class PortalError extends Error {
+    readonly code: number | string | undefined;
+    readonly details: unknown;
+    constructor(message: string, code?: number | string, details?: unknown);
+}
+/**
+ * Client for a Honua `/sharing/rest` Portal facade. Lets a repointed ArcGIS app
+ * authenticate, search for items, and open an item that resolves to a
+ * `/rest/services` URL — carrying the portal token through to the opened layer
+ * so the whole flow authenticates end to end.
+ *
+ * @example
+ * ```ts
+ * import { PortalCompat } from "@honua/sdk-js/esri-compat";
+ *
+ * const portal = new PortalCompat({ portalUrl: "https://honua.example" });
+ * await portal.generateToken({ username: "u", password: "p" });
+ * const { results } = await portal.search({ q: "roads" });
+ * const opened = await portal.openFeatureLayer(results[0]);
+ * if (opened.type === "feature-service") {
+ *   await opened.layer.queryFeatures({ where: "1=1" });
+ * }
+ * ```
+ */
+export declare class PortalCompat {
+    /** Normalized `.../sharing/rest` base for this portal. */
+    readonly sharingRestBase: string;
+    private token;
+    private tokenExpiresAtMs;
+    private readonly apiKey;
+    private readonly fetchFn;
+    constructor(options?: PortalCompatOptions);
+    /** The currently held portal token, if any. */
+    getToken(): string | undefined;
+    /**
+     * Exchange username/password for a portal token via
+     * `POST /sharing/rest/generateToken`. Stores the token on this instance and
+     * returns the credential (`expires` ms → `expiresAtMs`).
+     */
+    generateToken(options: PortalGenerateTokenOptions): Promise<PortalTokenCredential>;
+    /** `GET /sharing/rest/info`. */
+    getInfo(): Promise<PortalInfo>;
+    /** `GET /sharing/rest/portals/self` (attaches the token when present). */
+    getPortalSelf(): Promise<PortalSelf>;
+    /** `GET /sharing/rest/search`. */
+    search(options?: PortalSearchOptions): Promise<PortalSearchResult>;
+    /** `GET /sharing/rest/content/items/{id}`. */
+    getItem(itemId: string, options?: PortalGetItemOptions): Promise<PortalItem>;
+    /**
+     * Resolve an item (fetching it when given an id), parse its service `url`, and
+     * return an authenticated handle. Feature Service items yield a
+     * {@link FeatureLayerCompat} bound to a client carrying the portal token;
+     * Map/Image Service items yield the resolved `{ baseUrl, serviceId, client }`.
+     */
+    openFeatureLayer(itemOrId: string | PortalItem, options?: PortalOpenOptions): Promise<PortalOpenResult>;
+    /**
+     * Register the currently held token with the shared {@link identityManager}
+     * under this portal's `/sharing/rest` server, so subsequent esri-compat calls
+     * resolve the same credential.
+     */
+    registerWithIdentityManager(): void;
+    private buildAuthenticatedClient;
+    private getJson;
+}
+export {};
+//# sourceMappingURL=portal.d.ts.map

package/esri-compat/portal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"portal.d.ts","sourceRoot":"","sources":["../../../src/esri-compat/portal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAKxD;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,2EAA2E;IAC3E,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,MAAM,EAAE,QAAQ,GAAG,KAAK,GAAG,SAAS,GAAG,MAAM,CAAC;IAC9C,MAAM,EAAE,MAAM,EAAE,EAAE,GAAG,IAAI,CAAC;IAC1B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,8CAA8C;AAC9C,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,UAAU,EAAE,CAAC;CACvB;AAED,mEAAmE;AACnE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE;QACT,oBAAoB,CAAC,EAAE,OAAO,CAAC;QAC/B,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC3B,CAAC;IACF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,2EAA2E;AAC3E,MAAM,WAAW,UAAU;IACzB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE;QACL,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,GAAG,IAAI,CAAC;IACT,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,gDAAgD;AAChD,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACxB;AAED,sDAAsD;AACtD,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2FAA2F;IAC3F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,oDAAoD;AACpD,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,OAAO,CAAC;CACd;AAED,+CAA+C;AAC/C,MAAM,WAAW,mBAAmB;IAClC,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,gDAAgD;AAChD,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,yDAAyD;AACzD,MAAM,WAAW,iBAAiB;IAChC,oGAAoG;IACpG,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,oBAAoB;IAC5B,4BAA4B;IAC5B,IAAI,EAAE,UAAU,CAAC;IACjB,6FAA6F;IAC7F,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,MAAM,EAAE,WAAW,CAAC;CACrB;AAED,uFAAuF;AACvF,MAAM,WAAW,8BAA+B,SAAQ,oBAAoB;IAC1E,IAAI,EAAE,iBAAiB,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,kBAAkB,CAAC;CAC3B;AAED,iFAAiF;AACjF,MAAM,WAAW,uBAAwB,SAAQ,oBAAoB;IACnE,IAAI,EAAE,aAAa,GAAG,eAAe,CAAC;CACvC;AAED,MAAM,MAAM,gBAAgB,GAAG,8BAA8B,GAAG,uBAAuB,CAAC;AAExF,0EAA0E;AAC1E,qBAAa,WAAY,SAAQ,KAAK;IACpC,SAAgB,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAClD,SAAgB,OAAO,EAAE,OAAO,CAAC;gBAEd,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAM9E;AAUD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,YAAY;IACvB,0DAA0D;IAC1D,SAAgB,eAAe,EAAE,MAAM,CAAC;IACxC,OAAO,CAAC,KAAK,CAAqB;IAClC,OAAO,CAAC,gBAAgB,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;gBAEpB,OAAO,GAAE,mBAAwB;IAUpD,+CAA+C;IACxC,QAAQ,IAAI,MAAM,GAAG,SAAS;IAIrC;;;;OAIG;IACU,aAAa,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAmC/F,gCAAgC;IACnB,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC;IAI3C,0EAA0E;IAC7D,aAAa,IAAI,OAAO,CAAC,UAAU,CAAC;IAIjD,kCAAkC;IACrB,MAAM,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAiBnF,8CAA8C;IACjC,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,UAAU,CAAC;IAI7F;;;;;OAKG;IACU,gBAAgB,CAC3B,QAAQ,EAAE,MAAM,GAAG,UAAU,EAC7B,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,gBAAgB,CAAC;IAiD5B;;;;OAIG;IACI,2BAA2B,IAAI,IAAI;IAW1C,OAAO,CAAC,wBAAwB;YAalB,OAAO;CAoBtB"}

package/esri-compat/portal.js

@@ -0,0 +1,251 @@
+import { HonuaClient } from "../core/client.js";
+import { esriConfig } from "./esri-config.js";
+import { FeatureLayerCompat } from "./feature-layer.js";
+import { identityManager } from "./identity-manager.js";
+import { createArcGisTokenInterceptor } from "./request.js";
+import { parseFeatureLayerUrl, parseImageServiceUrl, parseMapServiceUrl } from "./url.js";
+/** Error thrown when the Portal facade returns an Esri error envelope. */
+export class PortalError extends Error {
+    code;
+    details;
+    constructor(message, code, details) {
+        super(message);
+        this.name = "PortalError";
+        this.code = code;
+        this.details = details;
+    }
+}
+/**
+ * Client for a Honua `/sharing/rest` Portal facade. Lets a repointed ArcGIS app
+ * authenticate, search for items, and open an item that resolves to a
+ * `/rest/services` URL — carrying the portal token through to the opened layer
+ * so the whole flow authenticates end to end.
+ *
+ * @example
+ * ```ts
+ * import { PortalCompat } from "@honua/sdk-js/esri-compat";
+ *
+ * const portal = new PortalCompat({ portalUrl: "https://honua.example" });
+ * await portal.generateToken({ username: "u", password: "p" });
+ * const { results } = await portal.search({ q: "roads" });
+ * const opened = await portal.openFeatureLayer(results[0]);
+ * if (opened.type === "feature-service") {
+ *   await opened.layer.queryFeatures({ where: "1=1" });
+ * }
+ * ```
+ */
+export class PortalCompat {
+    /** Normalized `.../sharing/rest` base for this portal. */
+    sharingRestBase;
+    token;
+    tokenExpiresAtMs;
+    apiKey;
+    fetchFn;
+    constructor(options = {}) {
+        this.sharingRestBase = normalizeSharingRestBase(options.portalUrl ?? esriConfig.portalUrl);
+        this.token = options.token;
+        this.tokenExpiresAtMs = undefined;
+        this.apiKey = options.apiKey ?? esriConfig.apiKey;
+        // Bind so passing a bare `window.fetch`/`globalThis.fetch` cannot throw an
+        // "Illegal invocation" when called as `this.fetchFn(...)`.
+        this.fetchFn = (options.fetchFn ?? fetch).bind(globalThis);
+    }
+    /** The currently held portal token, if any. */
+    getToken() {
+        return this.token;
+    }
+    /**
+     * Exchange username/password for a portal token via
+     * `POST /sharing/rest/generateToken`. Stores the token on this instance and
+     * returns the credential (`expires` ms → `expiresAtMs`).
+     */
+    async generateToken(options) {
+        const referer = options.referer ?? defaultReferer(this.sharingRestBase);
+        const body = new URLSearchParams();
+        body.set("username", options.username);
+        body.set("password", options.password);
+        body.set("client", options.client ?? "referer");
+        if (referer) {
+            body.set("referer", referer);
+        }
+        if (typeof options.expirationMinutes === "number" && Number.isFinite(options.expirationMinutes)) {
+            body.set("expiration", String(options.expirationMinutes));
+        }
+        body.set("f", "json");
+        const response = await this.fetchFn(`${this.sharingRestBase}/generateToken`, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: body.toString(),
+        });
+        const json = (await response.json());
+        throwIfEsriError(json, "Portal generateToken failed.");
+        if (typeof json.token !== "string" || json.token.length === 0) {
+            throw new PortalError("Portal generateToken response did not include a token.");
+        }
+        const expiresAtMs = typeof json.expires === "number" && Number.isFinite(json.expires) ? json.expires : 0;
+        this.token = json.token;
+        this.tokenExpiresAtMs = expiresAtMs || undefined;
+        return { token: json.token, expiresAtMs, ssl: json.ssl ?? true };
+    }
+    /** `GET /sharing/rest/info`. */
+    async getInfo() {
+        return this.getJson("/info", {}, undefined);
+    }
+    /** `GET /sharing/rest/portals/self` (attaches the token when present). */
+    async getPortalSelf() {
+        return this.getJson("/portals/self", {}, this.token);
+    }
+    /** `GET /sharing/rest/search`. */
+    async search(options = {}) {
+        const params = {
+            q: options.q,
+            start: options.start,
+            num: options.num,
+        };
+        const raw = await this.getJson("/search", params, options.token ?? this.token);
+        return {
+            query: raw.query ?? options.q ?? "",
+            total: raw.total ?? 0,
+            start: raw.start ?? options.start ?? 1,
+            num: raw.num ?? options.num ?? 0,
+            nextStart: raw.nextStart ?? -1,
+            results: Array.isArray(raw.results) ? raw.results : [],
+        };
+    }
+    /** `GET /sharing/rest/content/items/{id}`. */
+    async getItem(itemId, options = {}) {
+        return this.getJson(`/content/items/${encodeURIComponent(itemId)}`, {}, options.token ?? this.token);
+    }
+    /**
+     * Resolve an item (fetching it when given an id), parse its service `url`, and
+     * return an authenticated handle. Feature Service items yield a
+     * {@link FeatureLayerCompat} bound to a client carrying the portal token;
+     * Map/Image Service items yield the resolved `{ baseUrl, serviceId, client }`.
+     */
+    async openFeatureLayer(itemOrId, options = {}) {
+        const item = typeof itemOrId === "string" ? await this.getItem(itemOrId) : itemOrId;
+        if (!item.url) {
+            throw new PortalError(`Portal item ${item.id} has no service URL to open.`);
+        }
+        const serviceUrl = trimTrailingSlashes(item.url);
+        if (isFeatureService(item.type, serviceUrl)) {
+            const hasLayerId = /\/FeatureServer\/\d+$/i.test(serviceUrl);
+            const service = parseFeatureLayerUrl(hasLayerId ? serviceUrl : `${serviceUrl}/0`);
+            const client = this.buildAuthenticatedClient(service.baseUrl);
+            let layerId = service.layerId;
+            if (!hasLayerId) {
+                if (options.layerId !== undefined) {
+                    layerId = options.layerId;
+                }
+                else {
+                    const metadata = await client.getFeatureServiceMetadata(service.serviceId);
+                    const firstLayerId = metadata.layers?.[0]?.id;
+                    if (typeof firstLayerId !== "number" || !Number.isSafeInteger(firstLayerId)) {
+                        throw new PortalError(`Portal Feature Service item ${item.id} does not advertise a layer to open.`);
+                    }
+                    layerId = firstLayerId;
+                }
+            }
+            const layerUrl = hasLayerId ? serviceUrl : `${serviceUrl}/${layerId}`;
+            const parsed = parseFeatureLayerUrl(layerUrl);
+            const layer = new FeatureLayerCompat({ url: layerUrl, client, title: item.title, id: item.id });
+            return {
+                type: "feature-service",
+                item,
+                baseUrl: parsed.baseUrl,
+                serviceId: parsed.serviceId,
+                layerId: parsed.layerId,
+                client,
+                layer,
+            };
+        }
+        if (isImageService(item.type, serviceUrl)) {
+            const parsed = parseImageServiceUrl(serviceUrl);
+            const client = this.buildAuthenticatedClient(parsed.baseUrl);
+            return { type: "image-service", item, baseUrl: parsed.baseUrl, serviceId: parsed.serviceId, client };
+        }
+        const parsed = parseMapServiceUrl(serviceUrl);
+        const client = this.buildAuthenticatedClient(parsed.baseUrl);
+        return { type: "map-service", item, baseUrl: parsed.baseUrl, serviceId: parsed.serviceId, client };
+    }
+    /**
+     * Register the currently held token with the shared {@link identityManager}
+     * under this portal's `/sharing/rest` server, so subsequent esri-compat calls
+     * resolve the same credential.
+     */
+    registerWithIdentityManager() {
+        if (!this.token) {
+            throw new PortalError("PortalCompat has no token to register; call generateToken first.");
+        }
+        identityManager.registerToken({
+            server: this.sharingRestBase,
+            token: this.token,
+            ...(this.tokenExpiresAtMs !== undefined ? { expires: this.tokenExpiresAtMs } : {}),
+        });
+    }
+    buildAuthenticatedClient(baseUrl) {
+        const interceptors = [];
+        if (this.token) {
+            interceptors.push(createArcGisTokenInterceptor({ getToken: () => this.token }));
+        }
+        return new HonuaClient({
+            baseUrl,
+            fetchFn: this.fetchFn,
+            ...(this.apiKey ? { apiKey: this.apiKey } : {}),
+            ...(interceptors.length > 0 ? { interceptors } : {}),
+        });
+    }
+    async getJson(path, params, token) {
+        const query = new URLSearchParams();
+        query.set("f", "json");
+        for (const [key, value] of Object.entries(params)) {
+            if (value !== undefined && value !== null && value !== "") {
+                query.set(key, String(value));
+            }
+        }
+        if (token) {
+            query.set("token", token);
+        }
+        const response = await this.fetchFn(`${this.sharingRestBase}${path}?${query.toString()}`);
+        const json = (await response.json());
+        throwIfEsriError(json, `Portal request to ${path} failed.`);
+        return json;
+    }
+}
+function normalizeSharingRestBase(portalUrl) {
+    const trimmed = trimTrailingSlashes(portalUrl);
+    if (/\/sharing\/rest$/i.test(trimmed)) {
+        return trimmed;
+    }
+    return `${trimmed}/sharing/rest`;
+}
+function trimTrailingSlashes(value) {
+    let end = value.length;
+    while (end > 0 && value.charCodeAt(end - 1) === 47) {
+        end--;
+    }
+    return value.slice(0, end);
+}
+function defaultReferer(sharingRestBase) {
+    if (globalThis.location?.origin) {
+        return globalThis.location.origin;
+    }
+    try {
+        return new URL(sharingRestBase).origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isFeatureService(type, serviceUrl) {
+    return /feature\s*service/i.test(type) || /\/FeatureServer(\/\d+)?$/i.test(serviceUrl);
+}
+function isImageService(type, serviceUrl) {
+    return /image\s*service/i.test(type) || /\/ImageServer(\/\d+)?$/i.test(serviceUrl);
+}
+function throwIfEsriError(json, fallbackMessage) {
+    if (json && typeof json === "object" && json.error) {
+        const { code, message, details } = json.error;
+        throw new PortalError(message ?? fallbackMessage, code, details);
+    }
+}

package/esri-compat/renderer-objects.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Bridges the esri-compat renderer shims to the first-class renderer objects
+ * in `@honua/sdk-js/style` (issue #497 REQ-002). The compat classes stay
+ * pure state holders; these helpers project their state through the same
+ * WebMap symbol/renderer conversion path the WebMap converter uses, so the
+ * SDK has exactly one class-breaks/unique-value implementation.
+ *
+ * Kept out of the compat classes themselves so consumers who never emit
+ * renderer objects do not pay for the conversion pipeline.
+ *
+ * @module
+ */
+import type { ClassBreaksRenderer, UniqueValueRenderer } from "../style/renderers.js";
+import type { WarningCollector } from "../webmap/warnings.js";
+import type { ClassBreaksRendererCompat } from "./class-breaks-renderer.js";
+import type { UniqueValueRendererCompat } from "./unique-value-renderer.js";
+/** Result of projecting a compat renderer to a renderer object. @experimental */
+export interface CompatRendererProjection<R> {
+    /** The emitted renderer object, or `undefined` when nothing was convertible. */
+    readonly renderer: R | undefined;
+    /** Symbol/renderer conversion warnings collected during projection. */
+    readonly warnings: WarningCollector["warnings"];
+}
+/**
+ * Emit a first-class {@link ClassBreaksRenderer} from a
+ * `ClassBreaksRendererCompat` shim. Compat `minValue`/`maxValue` map to the
+ * WebMap `classMinValue`/`classMaxValue` fields and symbols convert through
+ * the shared WebMap symbol pipeline.
+ *
+ * @experimental
+ */
+export declare function rendererObjectFromClassBreaksCompat(compat: ClassBreaksRendererCompat): CompatRendererProjection<ClassBreaksRenderer>;
+/**
+ * Emit a first-class {@link UniqueValueRenderer} from a
+ * `UniqueValueRendererCompat` shim.
+ *
+ * @experimental
+ */
+export declare function rendererObjectFromUniqueValueCompat(compat: UniqueValueRendererCompat): CompatRendererProjection<UniqueValueRenderer>;
+//# sourceMappingURL=renderer-objects.d.ts.map

package/esri-compat/renderer-objects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer-objects.d.ts","sourceRoot":"","sources":["../../../src/esri-compat/renderer-objects.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAGtF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAC5E,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAE5E,iFAAiF;AACjF,MAAM,WAAW,wBAAwB,CAAC,CAAC;IACzC,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,SAAS,CAAC;IACjC,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC,UAAU,CAAC,CAAC;CACjD;AAED;;;;;;;GAOG;AACH,wBAAgB,mCAAmC,CACjD,MAAM,EAAE,yBAAyB,GAChC,wBAAwB,CAAC,mBAAmB,CAAC,CAmB/C;AAED;;;;;GAKG;AACH,wBAAgB,mCAAmC,CACjD,MAAM,EAAE,yBAAyB,GAChC,wBAAwB,CAAC,mBAAmB,CAAC,CAmB/C"}

package/esri-compat/renderer-objects.js

@@ -0,0 +1,62 @@
+/**
+ * Bridges the esri-compat renderer shims to the first-class renderer objects
+ * in `@honua/sdk-js/style` (issue #497 REQ-002). The compat classes stay
+ * pure state holders; these helpers project their state through the same
+ * WebMap symbol/renderer conversion path the WebMap converter uses, so the
+ * SDK has exactly one class-breaks/unique-value implementation.
+ *
+ * Kept out of the compat classes themselves so consumers who never emit
+ * renderer objects do not pay for the conversion pipeline.
+ *
+ * @module
+ */
+import { classBreaksRendererFromWebMap, uniqueValueRendererFromWebMap } from "../webmap/convert-renderer.js";
+import { createWarningCollector } from "../webmap/warnings.js";
+/**
+ * Emit a first-class {@link ClassBreaksRenderer} from a
+ * `ClassBreaksRendererCompat` shim. Compat `minValue`/`maxValue` map to the
+ * WebMap `classMinValue`/`classMaxValue` fields and symbols convert through
+ * the shared WebMap symbol pipeline.
+ *
+ * @experimental
+ */
+export function rendererObjectFromClassBreaksCompat(compat) {
+    const warn = createWarningCollector();
+    const renderer = classBreaksRendererFromWebMap({
+        type: "classBreaks",
+        field: compat.field,
+        minValue: compat.minValue,
+        defaultSymbol: compat.defaultSymbol,
+        defaultLabel: compat.defaultLabel,
+        classBreakInfos: compat.classBreakInfos.map((info) => ({
+            classMinValue: info.minValue,
+            classMaxValue: info.maxValue,
+            label: info.label,
+            symbol: info.symbol,
+        })),
+    }, warn);
+    return { renderer, warnings: warn.warnings };
+}
+/**
+ * Emit a first-class {@link UniqueValueRenderer} from a
+ * `UniqueValueRendererCompat` shim.
+ *
+ * @experimental
+ */
+export function rendererObjectFromUniqueValueCompat(compat) {
+    const warn = createWarningCollector();
+    const renderer = uniqueValueRendererFromWebMap({
+        type: "uniqueValue",
+        field1: compat.field,
+        field2: compat.field2,
+        field3: compat.field3,
+        defaultSymbol: compat.defaultSymbol,
+        defaultLabel: compat.defaultLabel,
+        uniqueValueInfos: compat.uniqueValueInfos.map((info) => ({
+            value: info.value,
+            label: info.label,
+            symbol: info.symbol,
+        })),
+    }, warn);
+    return { renderer, warnings: warn.warnings };
+}

package/esri-compat/sketch.d.ts

@@ -1,6 +1,32 @@
+import type { EditSketchTool } from "../contract/edit-sketch.js";
+import type { SnappingConfig } from "../contract/edit-snapping.js";
 import { CompatEventBus } from "./event-bus.js";
+import { type SnappingOptionsCompat } from "./snapping.js";
 export type SketchCreationModeCompat = "single" | "update" | "continuous";
 export type SketchToolCompat = "point" | "polyline" | "polygon" | "rectangle" | "circle";
+/**
+ * Duck-typed subset of the runtime terra-draw sketch handle
+ * (`bindTerraDrawSketch` / `createTerraDrawSketch` from
+ * `@honua/sdk-js/runtime`) that the Sketch shim can delegate tool modes to.
+ * Structural on purpose: the compat layer never imports the optional
+ * terra-draw peer, it only feature-detects a binding the app wired up.
+ *
+ * @experimental
+ */
+export interface SketchToolBindingCompat {
+    setTool(tool: EditSketchTool): unknown;
+    select?(): void;
+    cancel?(): void;
+}
+/**
+ * Feature-detect a terra-draw sketch binding: any object exposing a callable
+ * `setTool` qualifies; anything else (including `undefined` when terra-draw
+ * is not installed) resolves to `undefined` and the shim keeps its current
+ * headless behavior.
+ *
+ * @experimental
+ */
+export declare function resolveSketchToolBindingCompat(value: unknown): SketchToolBindingCompat | undefined;
 export interface SketchCreateOptionsCompat {
     mode?: "click" | "freehand" | "hybrid";
 }
@@ -20,6 +46,15 @@ export interface SketchCompatOptions {
     creationMode?: SketchCreationModeCompat;
     defaultCreateOptions?: Partial<SketchCreateOptionsCompat>;
     defaultUpdateOptions?: Partial<SketchUpdateOptionsCompat>;
+    snappingOptions?: SnappingOptionsCompat;
+    /**
+     * Optional terra-draw sketch binding (see {@link SketchToolBindingCompat}).
+     * When present, `create`/`update`/`cancel`/`reset` delegate tool-mode
+     * changes to the binding; otherwise the shim keeps its headless behavior.
+     *
+     * @experimental
+     */
+    sketchBinding?: unknown;
 }
 export interface SketchCreateResultCompat {
     state: "complete" | "cancel";
@@ -46,8 +81,16 @@ export declare class SketchCompat {
     activeCreateOptions: Partial<SketchCreateOptionsCompat> | undefined;
     activeUpdateGraphics: Record<string, unknown>[];
     activeUpdateOptions: Partial<SketchUpdateOptionsCompat> | undefined;
+    snappingOptions: SnappingOptionsCompat;
     private readonly watchListeners;
+    private readonly sketchBinding;
     constructor(options?: SketchCompatOptions);
+    /** Whether tool modes delegate to a terra-draw sketch binding. @experimental */
+    delegatesToSketchBinding(): boolean;
+    /** Replace the ArcGIS-shaped snapping options and notify watchers. */
+    setSnappingOptions(options: SnappingOptionsCompat): void;
+    /** The snapping options mapped onto the contract `SnappingConfig`. */
+    snappingConfig(): SnappingConfig;
     load(): Promise<SketchCompat>;
     when(callback?: (widget: SketchCompat) => void): Promise<SketchCompat>;
     watch(propertyName: string, listener: (value: unknown) => void): SketchHandleCompat;