@esri/hub-web-components 0.0.5

package/dist/components/arcgis-hub-ai-assistant/util/api.d.ts

@@ -0,0 +1,25 @@
+import { CivicApiResponse } from '../../../types';
+/**
+ * Call the Esri-managed GeoAI civic agent
+ * This currently handles the intent response.
+ * TODO: Move API to internally do both intent & actions
+ * */
+/**
+ * Old method for fetching data from the AI model. Moving to fetchCivicInference
+ * @param message
+ * @param context
+ * @param history
+ * @returns
+ */
+export declare function fetchIntent(message: string, context: string, history: string[]): Promise<CivicApiResponse>;
+/**
+ * Call the Esri-managed GeoAI civic agent
+ * */
+export declare function fetchInformation(message: string, history: string[], location: string, hub: string, informationSources: string[], allowChat: boolean, context?: string, language?: string): Promise<CivicApiResponse>;
+/**
+ * Call the Esri-managed GeoAI civic agent
+ * */
+export declare function fetchCivicInference(message: string, history: string[], location: string, hub: string, tools?: string[], language?: string): Promise<CivicApiResponse>;
+/**
+ * Deprecated method for fetching data from the AI model. Moving to fetchCivicInference
+ * */

package/dist/components/arcgis-hub-ai-assistant/util/customElement.d.ts

@@ -0,0 +1,18 @@
+/// <reference types="../../index.d.ts" />
+import { ChatSource } from '../../arcgis-chat-ui/util/types';
+import { FinderSource, FinderResponseContext } from './framework';
+/**
+ * When the "sources" come back from the AI, they do not have all the item properties. This function "enriches" them
+ * so they have all their item properties so we can display them down the component tree.
+ */
+export declare const enrichSources: (sources: FinderSource[]) => Promise<ChatSource[]>;
+export declare const getLocationCenter: (extent?: number[][]) => number[];
+export declare const calculateZoom: (extent?: number[][]) => number;
+/**
+ * Checks if the provided object is a FinderResponseContext by verifying its "kind" property.
+ * Returns true if the object matches the FinderResponseContext type, otherwise false.
+ *
+ * @param obj - The object to evaluate.
+ * @returns boolean indicating whether the object is a FinderResponseContext.
+ */
+export declare function isFinderResponseContext(obj: unknown): obj is FinderResponseContext;

package/dist/components/arcgis-hub-ai-assistant/util/customElement.js

@@ -0,0 +1,33 @@
+import { getItem as u } from "@esri/arcgis-rest-portal";
+/*! All material copyright Esri, All Rights Reserved, unless otherwise specified.
+See https://js.arcgis.com/0.0/esri/copyright.txt for details.
+v0.0.5 */
+const m = async (o) => await Promise.all(o.map(h)), h = async (o) => {
+  const t = structuredClone(o);
+  try {
+    const n = await u(o.id);
+    return console.debug("Enriching source:", o.id, n), t.thumbnail = n.thumbnail, t.url = n.url, t.type = n.type, t;
+  } catch {
+    console.error("Could not enrich:", o);
+  }
+  return t;
+}, g = (o) => {
+  if (!o)
+    return [0, 0];
+  const t = o[0][0], n = o[0][1], r = o[1][0], s = (o[1][1] + n) / 2;
+  return [(r + t) / 2, s];
+}, p = (o) => {
+  if (!o)
+    return 5;
+  const t = o[0][0], n = o[0][1], r = o[1][0], c = o[1][1], s = Math.abs(r - t), e = Math.abs(c - n), i = Math.log2(360 / s), a = Math.log2(180 / e);
+  return Math.floor(Math.min(i, a)) + 2;
+};
+function f(o) {
+  return !!o && typeof o == "object" && "kind" in o && o.kind === "FinderResponse";
+}
+export {
+  p as calculateZoom,
+  m as enrichSources,
+  g as getLocationCenter,
+  f as isFinderResponseContext
+};

package/dist/components/arcgis-hub-ai-assistant/util/framework.d.ts

@@ -0,0 +1,184 @@
+/**
+* Developer interface to the ArcGIS AI framework and Hub skills
+* "finder" is the Hub search assistant skill.
+* In the future there will be more skills for content creation, moderation, and newsletter generation.
+*
+* Example usage:
+*
+* ```ts
+*   const response = await getFinderResponse({
+*     message: 'How many trees are in Ward 6?',
+*     conversationId: null // to use previous history include conversationId
+*     context: {
+*       kind: 'FinderRequest',
+*       item: '4ef...', // the item id of the Item with the assistant configuration (e.g. a Hub Site)
+*     },
+*     token: token, // Use the ArcGIS user token if available
+*     apiUrl: 'https://hub.arcgis.com/api/assistants/v1', // or your custom API URL
+*  });
+* ```
+*
+* The API sequence looks like this:
+* 1. Call getSkillResponse with the skillId, message, and context to get the initial response.
+* 2. If the response has more messages (hasMore is true),
+*    continue calling getSkillResponse with the conversationId and inquiryId until hasMore is false.
+* 3. The response will include the conversationId, inquiryId, and sequenceNumber for tracking the conversation.
+* 4. The context can be used to pass additional information to the skill
+*
+* The ArcGIS AI API works by calling
+* /api/skills/{skillId}/chat
+*  with a POST request containing the message and context.
+*
+*   context is specific to a skill and must include the `kind` which is the skill-specific context type. (e.g. FinderRequestContext)
+*     and the additional properties required by the skill.
+*
+*  The response will include the conversationId, inquiryId, and sequenceNumber for tracking the conversation.
+*  If hasMore is true, you can continue to call the same endpoint with the conversationId and inquiryId
+*  to get more messages until hasMore is false.
+*
+*  Authentication is required and is done using a Bearer token in the Authorization header.
+*/
+/**
+ * General Skill API response type (excluding context)
+ */
+export interface SkillApiResponse<TContext = unknown> {
+    conversationId: string | null;
+    inquiryId: string;
+    hasMore: boolean;
+    sequenceNumber: number;
+    message?: string;
+    context: TContext;
+}
+/**
+ * FinderActionProperties defines the properties for actions in the Finder skill.
+ */
+export interface FinderActionProperties {
+    kind: string;
+    topic: string;
+    datasets: string[] | null;
+    latitude: number | null;
+    longitude: number | null;
+    zoom: number | null;
+}
+/**
+ * FinderAction defines an action that is recommended as a follow-up user query
+ */
+export interface FinderAction {
+    kind: string;
+    action: string;
+    text: string;
+    properties: FinderActionProperties;
+}
+/**
+ * FinderSource defines a source of information in a response such as a dataset, document, or app.
+ */
+export interface FinderSource {
+    kind: string;
+    id: string;
+    type: string;
+    title: string;
+    description: string;
+    source: string;
+}
+/**
+ * FinderLocation defines the location of a response or source
+ */
+export interface FinderLocation {
+    kind: string;
+    name: string;
+    latitude: number;
+    longitude: number;
+    zoom: number | null;
+}
+export declare enum FinderResponseContextKind {
+    RESPONSE = "FinderResponse",
+    WORKFLOW = "FinderWorkflow"
+}
+/**
+ * FinderTool defines a tool that can be used in the Finder skill, such as a search or geocode.
+ */
+export interface FinderTool {
+    name: string;
+    parameters: Record<string, unknown>;
+}
+/**
+ * FinderRequestContext defines the information sent to the Finder skill API
+ */
+export interface FinderRequestContext {
+    kind: string;
+    domain?: string;
+    location?: string;
+    item?: string;
+}
+/**
+ * FinderResponseContext defines the information sent back from the Finder skill API
+ */
+export interface FinderResponseContext {
+    kind: string;
+    text: string;
+    actions: FinderAction[];
+    sources: FinderSource[];
+    location: FinderLocation;
+    features: unknown;
+    tools: FinderTool[];
+}
+export interface ArcgisErrorAsContext {
+    error: {
+        code: number;
+        messageCode: string;
+        details?: unknown[];
+        message: string;
+        subCode?: unknown;
+    };
+    kind: string;
+}
+export type SkillResponse = SkillApiResponse;
+export type FinderSkillResponse = SkillApiResponse<FinderResponseContext>;
+export type ArcgisErrorResponse = SkillApiResponse<ArcgisErrorAsContext>;
+/**
+ * Calls a skill API endpoint with support for retries and pause between attempts.
+ *
+ * @template TContext - The type of the context object expected in the API response.
+ * @param apiUrl - The base API URL to the AI framework.
+ * @param payload - The request payload to send to the skill API.
+ * @param headers - The HTTP headers to include in the request.
+ * @param retries - The number of retry attempts if the request fails (default: 3).
+ * @param pauseMs - The pause duration in milliseconds between retry attempts (default: 1000).
+ * @returns A promise that resolves to the skill API response with the specified context type.
+ * @throws Will throw an error if all retry attempts fail.
+ */
+export declare function getSkillResponse<TContext = unknown>(params: {
+    skillId: string;
+    message: string;
+    context: object;
+    token: string;
+    conversationId?: string;
+    apiUrl?: string;
+    pauseMs?: number;
+    retries?: number;
+}): Promise<SkillApiResponse<TContext>[]>;
+/**
+ * Parameters for the getFinderResponse function.
+ *
+ * @param message The user message/question.
+ * @param context The FinderRequest context object.
+ * @param token The bearer token for authentication.
+ * @param apiUrl The base API URL (default: 'https://api.example.com').
+ * @param pauseMs Pause in ms between retries (default: 1000).
+ * @param retries Number of retries for API calls (default: 50).
+ */
+export interface GetFinderResponseParams {
+    message: string;
+    context: FinderRequestContext;
+    token: string;
+    conversationId?: string | null;
+    apiUrl?: string;
+    pauseMs?: number;
+    retries?: number;
+}
+/**
+ * Get a response from the 'finder' skill for a FinderRequest.
+ *
+ * @returns Array of SkillResponse objects from the skill API.
+ */
+export declare function getFinderResponse({ message, context, token, conversationId, apiUrl, pauseMs, retries, }: GetFinderResponseParams): Promise<ArcgisErrorResponse[] | FinderSkillResponse[]>;

package/dist/components/arcgis-hub-ai-assistant/util/index.d.ts

@@ -0,0 +1 @@
+export * from "./customElement.js";

package/dist/components/arcgis-hub-ai-assistant/util/index.js

@@ -0,0 +1 @@
+export * from "./customElement.js";