@athenaintel/react 0.57.2 → 0.60.0

package/dist/composer/useFileUpload.js.map

@@ -1 +1 @@
-{"version":3,"file":"useFileUpload.js","sources":["../../src/composer/useFileUpload.ts"],"sourcesContent":["import { useCallback, useEffect, useRef, useState } from 'react';\nimport { useAthenaConfig } from '../provider/AthenaContext';\n\nexport interface UploadedAsset {\n  id: string;\n  title: string;\n  fileName: string;\n  fileSize: number;\n  mediaType: string;\n  /**\n   * The position, in the batch `upload` was given, of the file this asset was\n   * uploaded from (the upload's `success_file_indexes`; absent from a server\n   * that does not send them).\n   */\n  fileIndex?: number;\n  /**\n   * A local `blob:` URL of the picture this attachment was uploaded from, for\n   * the composer's thumbnail and full-screen viewer. Set by the composer's\n   * intake for image files, and revoked when the draft lets the attachment go.\n   */\n  previewUrl?: string;\n}\n\nexport interface UploadProgress {\n  current: number;\n  total: number;\n  fileName: string;\n  /** 0–1 normalized progress for the current file */\n  percent: number;\n}\n\nexport interface UseFileUploadReturn {\n  /** Upload one or more files to Athena. Returns the created asset(s). */\n  upload: (files: File[]) => Promise<UploadedAsset[]>;\n  /** Whether an upload is currently in progress. */\n  isUploading: boolean;\n  /** Upload progress info (null when idle). */\n  progress: UploadProgress | null;\n  /** Last upload error (null when no error). */\n  error: string | null;\n  /** Clear the error state. */\n  clearError: () => void;\n}\n\nconst MAX_FILE_SIZE = 5 * 1024 * 1024 * 1024; // 5 GB\n\n/**\n * Hook for uploading files to the Athena platform via the Athena upload endpoint.\n * Files become Athena assets (documents, spreadsheets, PDFs, images, etc.).\n *\n * Usage:\n *   const { upload, isUploading, progress, error } = useFileUpload();\n *   const assets = await upload(fileList);\n */\nexport function useFileUpload(): UseFileUploadReturn {\n  const config = useAthenaConfig();\n  // Keep config in a ref so upload() always reads the latest token at call\n  // time. AthenaConfig's token is a getter that returns the current value\n  // from PropelAuth, and reading via the ref avoids capturing stale\n  // destructured values in the useCallback closure.\n  const configRef = useRef(config);\n  configRef.current = config;\n  const { backendUrl, apiKey } = config;\n  const [isUploading, setIsUploading] = useState(false);\n  const [progress, setProgress] = useState<UploadProgress | null>(null);\n  const [error, setError] = useState<string | null>(null);\n  const xhrRef = useRef<XMLHttpRequest | null>(null);\n\n  // Abort any in-flight upload when the component unmounts\n  useEffect(() => {\n    return () => {\n      xhrRef.current?.abort();\n    };\n  }, []);\n\n  const clearError = useCallback(() => setError(null), []);\n\n  const upload = useCallback(\n    async (files: File[]): Promise<UploadedAsset[]> => {\n      if (files.length === 0) return [];\n\n      // Validate file sizes\n      for (const file of files) {\n        if (file.size > MAX_FILE_SIZE) {\n          const msg = `File \"${file.name}\" exceeds the maximum size of 5 GB.`;\n          setError(msg);\n          throw new Error(msg);\n        }\n      }\n\n      setIsUploading(true);\n      setError(null);\n      setProgress({ current: 0, total: files.length, fileName: files[0]?.name ?? '', percent: 0 });\n\n      try {\n        const formData = new FormData();\n        for (const file of files) {\n          formData.append('files', file, file.name);\n        }\n\n        // Derive the upload URL from the configured Athena backend URL.\n        // If backendUrl points at a nested Athena endpoint, trim it back to the API base first.\n        const baseUrl = backendUrl.replace(/\\/api\\/assistant-ui\\/?$/, '');\n        const uploadUrl = `${baseUrl}/api/upload/`;\n\n        // Read the current token at call time so rotated tokens are picked up.\n        const currentToken = configRef.current.token;\n        const headers: Record<string, string> = {};\n        if (currentToken) {\n          headers['Authorization'] = `Bearer ${currentToken}`;\n        } else if (apiKey) {\n          headers['X-API-KEY'] = apiKey;\n        }\n\n        const xhr = new XMLHttpRequest();\n        xhrRef.current = xhr;\n\n        const result = await new Promise<{ success: UploadedAsset[]; errors: Array<{ file: { filename: string }; error: string }> }>((resolve, reject) => {\n          xhr.upload.addEventListener('progress', (e) => {\n            if (e.lengthComputable) {\n              const percent = e.loaded / e.total;\n              // Estimate which file we're on based on progress\n              const fileIndex = Math.min(\n                Math.floor(percent * files.length),\n                files.length - 1,\n              );\n              setProgress({\n                current: fileIndex + 1,\n                total: files.length,\n                fileName: files[fileIndex]?.name ?? '',\n                percent,\n              });\n            }\n          });\n\n          xhr.addEventListener('load', () => {\n            if (xhr.status >= 200 && xhr.status < 300) {\n              try {\n                const data = JSON.parse(xhr.responseText);\n                const fileIndexes: unknown = data.success_file_indexes;\n                const assets: UploadedAsset[] = (data.success ?? []).map((a: Record<string, unknown>, at: number) => {\n                  const fileIndex = Array.isArray(fileIndexes) ? fileIndexes[at] : undefined;\n                  return {\n                    id: a.id as string,\n                    title: (a.title ?? a.file_name) as string,\n                    fileName: a.file_name as string,\n                    fileSize: a.file_size as number,\n                    mediaType: a.media_type as string,\n                    ...(typeof fileIndex === 'number' && { fileIndex }),\n                  };\n                });\n                resolve({ success: assets, errors: data.errors ?? [] });\n              } catch {\n                reject(new Error('Failed to parse upload response'));\n              }\n            } else if (xhr.status === 401 || xhr.status === 403) {\n              reject(new Error('Authentication failed. Check your API key or token.'));\n            } else {\n              reject(new Error(`Upload failed with status ${xhr.status}`));\n            }\n          });\n\n          xhr.addEventListener('error', () => reject(new Error('Network error during upload')));\n          xhr.addEventListener('abort', () => reject(new Error('Upload was cancelled')));\n\n          xhr.open('POST', uploadUrl);\n          for (const [key, value] of Object.entries(headers)) {\n            xhr.setRequestHeader(key, value);\n          }\n          xhr.withCredentials = !currentToken && !apiKey;\n          xhr.send(formData);\n        });\n\n        if (result.errors.length > 0) {\n          const errMsg = result.errors.map((e) => `${e.file.filename}: ${e.error}`).join('; ');\n          if (result.success.length === 0) {\n            setError(errMsg);\n            throw new Error(errMsg);\n          }\n          // Partial success — set error but still return successful uploads\n          setError(errMsg);\n        }\n\n        return result.success;\n      } catch (err) {\n        const msg = err instanceof Error ? err.message : 'Upload failed';\n        setError(msg);\n        throw err;\n      } finally {\n        xhrRef.current = null;\n        setIsUploading(false);\n        setProgress(null);\n      }\n    },\n    [backendUrl, apiKey],\n  );\n\n  return { upload, isUploading, progress, error, clearError };\n}\n"],"names":["_a"],"mappings":"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"}
+{"version":3,"file":"useFileUpload.js","sources":["../../src/composer/useFileUpload.ts"],"sourcesContent":["import { useCallback, useEffect, useRef, useState } from 'react';\nimport type { MentionAuthContext } from '../chat-ui/mentions/suggestions/data/api-client';\nimport { useAthenaConfig } from '../provider/AthenaContext';\nimport {\n  FOLDER_UPLOAD_PATH,\n  folderUploadResultOf,\n  startFolderUpload,\n  waitForFolderUploadTask,\n} from './folder-upload';\n\nexport interface UploadedAsset {\n  id: string;\n  title: string;\n  fileName: string;\n  fileSize: number;\n  mediaType: string;\n  /**\n   * The position, in the batch `upload` was given, of the file this asset was\n   * uploaded from (the upload's `success_file_indexes`; absent from a server\n   * that does not send them).\n   */\n  fileIndex?: number;\n  /**\n   * A local `blob:` URL of the picture this attachment was uploaded from, for\n   * the composer's thumbnail and full-screen viewer. Set by the composer's\n   * intake for image files, and revoked when the draft lets the attachment go.\n   */\n  previewUrl?: string;\n}\n\nexport interface UploadProgress {\n  current: number;\n  total: number;\n  fileName: string;\n  /** 0–1 normalized progress for the current file */\n  percent: number;\n}\n\n/** A file Athena refused while it took others from the same upload, with its reason. */\nexport interface UploadRefusal {\n  fileName: string;\n  error: string;\n}\n\nexport interface UploadOptions {\n  /**\n   * The folder the files go into. agora's async upload takes them there, and refuses the whole\n   * upload, before it takes any file, unless the person may edit that folder. Without one they are\n   * filed at the workspace's root, as before.\n   */\n  parentFolderId?: string | null;\n  /**\n   * Hears the files Athena refused when it took others from the same upload, before `upload`\n   * resolves with the ones it took (the hook's `error` says the same, as one line). An upload that\n   * took none rejects instead.\n   */\n  onFilesRefused?: (refused: readonly UploadRefusal[]) => void;\n}\n\nexport interface UseFileUploadReturn {\n  /** Upload one or more files to Athena (into a folder, `parentFolderId`). Returns the created asset(s). */\n  upload: (files: File[], options?: UploadOptions) => Promise<UploadedAsset[]>;\n  /** Whether an upload is currently in progress. */\n  isUploading: boolean;\n  /** Upload progress info (null when idle). */\n  progress: UploadProgress | null;\n  /** Last upload error (null when no error). */\n  error: string | null;\n  /** Clear the error state. */\n  clearError: () => void;\n}\n\nconst MAX_FILE_SIZE = 5 * 1024 * 1024 * 1024; // 5 GB\n\n/**\n * Hook for uploading files to the Athena platform via the Athena upload endpoint.\n * Files become Athena assets (documents, spreadsheets, PDFs, images, etc.).\n *\n * Usage:\n *   const { upload, isUploading, progress, error } = useFileUpload();\n *   const assets = await upload(fileList);\n */\nexport function useFileUpload(): UseFileUploadReturn {\n  const config = useAthenaConfig();\n  // Keep config in a ref so upload() always reads the latest token at call\n  // time. AthenaConfig's token is a getter that returns the current value\n  // from PropelAuth, and reading via the ref avoids capturing stale\n  // destructured values in the useCallback closure.\n  const configRef = useRef(config);\n  configRef.current = config;\n  const { backendUrl, apiKey } = config;\n  const [isUploading, setIsUploading] = useState(false);\n  const [progress, setProgress] = useState<UploadProgress | null>(null);\n  const [error, setError] = useState<string | null>(null);\n  const xhrRef = useRef<XMLHttpRequest | null>(null);\n  // An upload into a folder reads its task until it ends: let go of it when the component goes.\n  const taskWaitRef = useRef<AbortController | null>(null);\n\n  // Abort any in-flight upload when the component unmounts\n  useEffect(() => {\n    return () => {\n      xhrRef.current?.abort();\n      taskWaitRef.current?.abort();\n    };\n  }, []);\n\n  const clearError = useCallback(() => setError(null), []);\n\n  /**\n   * Into a folder: agora's async upload (`POST /api/upload/async` with `parent_folder_id`, which\n   * authorizes EDIT on the folder before it takes a file), its bytes' progress reported as the\n   * quick upload's is, then its task read until it ends (`folder-upload.ts`).\n   */\n  const uploadIntoFolder = useCallback(\n    async ({\n      files,\n      parentFolderId,\n      baseUrl,\n      headers,\n      currentToken,\n    }: {\n      files: File[];\n      parentFolderId: string;\n      baseUrl: string;\n      headers: Record<string, string>;\n      currentToken: string | null | undefined;\n    }): Promise<{ uploaded: UploadedAsset[]; refused: UploadRefusal[] }> => {\n      const send = (form: FormData) =>\n        new Promise<Response>((resolve, reject) => {\n          const xhr = new XMLHttpRequest();\n          xhrRef.current = xhr;\n          xhr.upload.addEventListener('progress', (e) => {\n            if (!e.lengthComputable) return;\n            const percent = e.loaded / e.total;\n            const fileIndex = Math.min(Math.floor(percent * files.length), files.length - 1);\n            setProgress({\n              current: fileIndex + 1,\n              total: files.length,\n              fileName: files[fileIndex]?.name ?? '',\n              percent,\n            });\n          });\n          xhr.addEventListener('load', () =>\n            resolve(new Response(xhr.responseText, { status: xhr.status })),\n          );\n          xhr.addEventListener('error', () => reject(new Error('Network error during upload')));\n          xhr.addEventListener('abort', () => reject(new Error('Upload was cancelled')));\n          xhr.open('POST', `${baseUrl}${FOLDER_UPLOAD_PATH}`);\n          for (const [key, value] of Object.entries(headers)) xhr.setRequestHeader(key, value);\n          xhr.withCredentials = !currentToken && !configRef.current.apiKey;\n          xhr.send(form);\n        });\n      const taskId = await startFolderUpload({ send, files, parentFolderId });\n      const config = configRef.current;\n      const auth: MentionAuthContext = {\n        backendUrl: baseUrl,\n        appUrl: config.appUrl,\n        apiKey: config.apiKey,\n        credentials: 'include',\n        get accessToken() {\n          return configRef.current.token ?? undefined;\n        },\n        getAccessToken: async () => (await configRef.current.getToken?.()) ?? undefined,\n        renewAccessToken: async () =>\n          (await configRef.current.getToken?.({ force: true })) ?? undefined,\n      };\n      const waiting = new AbortController();\n      taskWaitRef.current = waiting;\n      try {\n        const task = await waitForFolderUploadTask({ auth, taskId, signal: waiting.signal });\n        const { uploaded, failed } = folderUploadResultOf({ task, files });\n        if (failed.length > 0) {\n          const errMsg = failed.map((entry) => `${entry.fileName}: ${entry.error}`).join('; ');\n          setError(errMsg);\n          if (uploaded.length === 0) throw new Error(errMsg);\n        }\n        return { uploaded, refused: failed };\n      } finally {\n        if (taskWaitRef.current === waiting) taskWaitRef.current = null;\n      }\n    },\n    [],\n  );\n\n  const upload = useCallback(\n    async (files: File[], options: UploadOptions = {}): Promise<UploadedAsset[]> => {\n      if (files.length === 0) return [];\n\n      // Validate file sizes\n      for (const file of files) {\n        if (file.size > MAX_FILE_SIZE) {\n          const msg = `File \"${file.name}\" exceeds the maximum size of 5 GB.`;\n          setError(msg);\n          throw new Error(msg);\n        }\n      }\n\n      setIsUploading(true);\n      setError(null);\n      setProgress({ current: 0, total: files.length, fileName: files[0]?.name ?? '', percent: 0 });\n\n      try {\n        // Derive the upload URL from the configured Athena backend URL.\n        // If backendUrl points at a nested Athena endpoint, trim it back to the API base first.\n        const baseUrl = backendUrl.replace(/\\/api\\/assistant-ui\\/?$/, '');\n        const uploadUrl = `${baseUrl}/api/upload/`;\n\n        // Read the current token at call time so rotated tokens are picked up.\n        const currentToken = configRef.current.token;\n        const headers: Record<string, string> = {};\n        if (currentToken) {\n          headers['Authorization'] = `Bearer ${currentToken}`;\n        } else if (apiKey) {\n          headers['X-API-KEY'] = apiKey;\n        }\n\n        const { parentFolderId, onFilesRefused } = options;\n        if (parentFolderId) {\n          const { uploaded, refused } = await uploadIntoFolder({\n            files,\n            parentFolderId,\n            baseUrl,\n            headers,\n            currentToken,\n          });\n          if (refused.length > 0) onFilesRefused?.(refused);\n          return uploaded;\n        }\n\n        const formData = new FormData();\n        for (const file of files) {\n          formData.append('files', file, file.name);\n        }\n\n        const xhr = new XMLHttpRequest();\n        xhrRef.current = xhr;\n\n        const result = await new Promise<{ success: UploadedAsset[]; errors: Array<{ file: { filename: string }; error: string }> }>((resolve, reject) => {\n          xhr.upload.addEventListener('progress', (e) => {\n            if (e.lengthComputable) {\n              const percent = e.loaded / e.total;\n              // Estimate which file we're on based on progress\n              const fileIndex = Math.min(\n                Math.floor(percent * files.length),\n                files.length - 1,\n              );\n              setProgress({\n                current: fileIndex + 1,\n                total: files.length,\n                fileName: files[fileIndex]?.name ?? '',\n                percent,\n              });\n            }\n          });\n\n          xhr.addEventListener('load', () => {\n            if (xhr.status >= 200 && xhr.status < 300) {\n              try {\n                const data = JSON.parse(xhr.responseText);\n                const fileIndexes: unknown = data.success_file_indexes;\n                const assets: UploadedAsset[] = (data.success ?? []).map((a: Record<string, unknown>, at: number) => {\n                  const fileIndex = Array.isArray(fileIndexes) ? fileIndexes[at] : undefined;\n                  return {\n                    id: a.id as string,\n                    title: (a.title ?? a.file_name) as string,\n                    fileName: a.file_name as string,\n                    fileSize: a.file_size as number,\n                    mediaType: a.media_type as string,\n                    ...(typeof fileIndex === 'number' && { fileIndex }),\n                  };\n                });\n                resolve({ success: assets, errors: data.errors ?? [] });\n              } catch {\n                reject(new Error('Failed to parse upload response'));\n              }\n            } else if (xhr.status === 401 || xhr.status === 403) {\n              reject(new Error('Authentication failed. Check your API key or token.'));\n            } else {\n              reject(new Error(`Upload failed with status ${xhr.status}`));\n            }\n          });\n\n          xhr.addEventListener('error', () => reject(new Error('Network error during upload')));\n          xhr.addEventListener('abort', () => reject(new Error('Upload was cancelled')));\n\n          xhr.open('POST', uploadUrl);\n          for (const [key, value] of Object.entries(headers)) {\n            xhr.setRequestHeader(key, value);\n          }\n          xhr.withCredentials = !currentToken && !apiKey;\n          xhr.send(formData);\n        });\n\n        if (result.errors.length > 0) {\n          const errMsg = result.errors.map((e) => `${e.file.filename}: ${e.error}`).join('; ');\n          if (result.success.length === 0) {\n            setError(errMsg);\n            throw new Error(errMsg);\n          }\n          // Partial success — set error but still return successful uploads\n          setError(errMsg);\n          onFilesRefused?.(\n            result.errors.map((e) => ({ fileName: e.file.filename, error: e.error })),\n          );\n        }\n\n        return result.success;\n      } catch (err) {\n        const msg = err instanceof Error ? err.message : 'Upload failed';\n        setError(msg);\n        throw err;\n      } finally {\n        xhrRef.current = null;\n        setIsUploading(false);\n        setProgress(null);\n      }\n    },\n    [backendUrl, apiKey, uploadIntoFolder],\n  );\n\n  return { upload, isUploading, progress, error, clearError };\n}\n"],"names":["config","_a"],"mappings":"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"}

package/dist/data/athena-api-error.cjs

@@ -0,0 +1,125 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+var _a, _b;
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const AthenaApiErrorKind = {
+  /** Agora answered with an error status (4xx or 5xx). */
+  Http: "http",
+  /** Agora answered a GraphQL operation with errors (a refused read, an invalid query), or with no data. */
+  GraphQL: "graphql",
+  /** No answer came: offline, a refused CORS preflight, a dropped connection. */
+  Network: "network",
+  /** No answer came within the request's `timeoutMs`, so the SDK abandoned it. */
+  Timeout: "timeout",
+  /** The provider could not resolve a credential: its `getToken` threw. */
+  Credential: "credential",
+  /** The answer could not be read: not the JSON it said it was, or cut off. */
+  Response: "response",
+  /** The SDK refused to send the request (the message says why). */
+  Request: "request"
+};
+const ATHENA_API_ERROR = Symbol.for("athena-sdk.AthenaApiError");
+class AthenaApiError extends (_b = Error, _a = ATHENA_API_ERROR, _b) {
+  constructor(options) {
+    super(options.message, options.cause === void 0 ? void 0 : { cause: options.cause });
+    __publicField(this, _a, true);
+    __publicField(this, "kind");
+    /**
+     * The HTTP status agora answered with: a GraphQL error answered with 200 says
+     * 200. `0` when no answer came (`network`, `timeout`, `credential`,
+     * `request`).
+     */
+    __publicField(this, "status");
+    /**
+     * Agora's machine-readable code: the first GraphQL error's
+     * `extensions.code`, or a REST error's `detail.code`. `null` when it gave
+     * none.
+     */
+    __publicField(this, "code");
+    /** Every GraphQL error of the answer; empty for other failures. */
+    __publicField(this, "errors");
+    /** A REST error's `detail` (FastAPI's envelope), else its body as read; `undefined` when there was none. */
+    __publicField(this, "detail");
+    /**
+     * How long agora asked the caller to wait before trying again (`Retry-After`,
+     * or the `retryAfterSeconds` of a rate-limit refusal), in ms; `null` when it
+     * did not say.
+     */
+    __publicField(this, "retryAfterMs");
+    /** The request's method. */
+    __publicField(this, "method");
+    /** The request's path, without its query string. */
+    __publicField(this, "path");
+    this.name = "AthenaApiError";
+    this.kind = options.kind;
+    this.status = options.status ?? 0;
+    this.code = options.code ?? null;
+    this.errors = options.errors ?? [];
+    this.detail = options.detail;
+    this.retryAfterMs = options.retryAfterMs ?? null;
+    this.method = options.method;
+    this.path = options.path;
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      kind: this.kind,
+      status: this.status,
+      code: this.code,
+      message: this.message,
+      errors: this.errors,
+      detail: this.detail,
+      retryAfterMs: this.retryAfterMs,
+      method: this.method,
+      path: this.path
+    };
+  }
+}
+function isAthenaApiError(value) {
+  return value instanceof AthenaApiError || typeof value === "object" && value !== null && Reflect.get(value, ATHENA_API_ERROR) === true;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function graphQLErrorEntries(body) {
+  const errors = isRecord(body) ? body.errors : void 0;
+  if (!Array.isArray(errors)) return [];
+  return errors.flatMap((entry) => {
+    if (!isRecord(entry) || typeof entry.message !== "string") return [];
+    const path = Array.isArray(entry.path) ? entry.path.filter((part) => typeof part === "string" || typeof part === "number") : void 0;
+    return [
+      {
+        message: entry.message,
+        ...path ? { path } : {},
+        ...isRecord(entry.extensions) ? { extensions: entry.extensions } : {}
+      }
+    ];
+  });
+}
+function graphQLErrorCode(entry) {
+  var _a2;
+  const code = (_a2 = entry == null ? void 0 : entry.extensions) == null ? void 0 : _a2.code;
+  return typeof code === "string" ? code : null;
+}
+function restErrorDetail(body) {
+  const detail = isRecord(body) && "detail" in body ? body.detail : body;
+  if (typeof detail === "string") {
+    return { detail, code: null, message: detail || null, retryAfterSeconds: null };
+  }
+  if (!isRecord(detail)) return { detail, code: null, message: null, retryAfterSeconds: null };
+  return {
+    detail,
+    code: typeof detail.code === "string" ? detail.code : null,
+    message: typeof detail.message === "string" ? detail.message : null,
+    retryAfterSeconds: typeof detail.retryAfterSeconds === "number" && Number.isFinite(detail.retryAfterSeconds) ? detail.retryAfterSeconds : null
+  };
+}
+exports.AthenaApiError = AthenaApiError;
+exports.AthenaApiErrorKind = AthenaApiErrorKind;
+exports.graphQLErrorCode = graphQLErrorCode;
+exports.graphQLErrorEntries = graphQLErrorEntries;
+exports.isAthenaApiError = isAthenaApiError;
+exports.restErrorDetail = restErrorDetail;
+//# sourceMappingURL=athena-api-error.cjs.map

package/dist/data/athena-api-error.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"athena-api-error.cjs","sources":["../../src/data/athena-api-error.ts"],"sourcesContent":["/**\n * What the SDK's data layer throws (`useAthenaFetch`, `useAthenaGraphQL`,\n * `useAthenaGraphQLMutation`, `useAthenaRest`, `useSemanticQuery`): one typed\n * error that says how a request failed (`kind`), with the HTTP status, agora's\n * machine-readable code and its message. A request its caller cancelled is the\n * one exception: it rejects with the abort's own reason, as `fetch` does.\n */\n\n/** How a request failed. */\nexport const AthenaApiErrorKind = {\n  /** Agora answered with an error status (4xx or 5xx). */\n  Http: 'http',\n  /** Agora answered a GraphQL operation with errors (a refused read, an invalid query), or with no data. */\n  GraphQL: 'graphql',\n  /** No answer came: offline, a refused CORS preflight, a dropped connection. */\n  Network: 'network',\n  /** No answer came within the request's `timeoutMs`, so the SDK abandoned it. */\n  Timeout: 'timeout',\n  /** The provider could not resolve a credential: its `getToken` threw. */\n  Credential: 'credential',\n  /** The answer could not be read: not the JSON it said it was, or cut off. */\n  Response: 'response',\n  /** The SDK refused to send the request (the message says why). */\n  Request: 'request',\n} as const;\nexport type AthenaApiErrorKind = (typeof AthenaApiErrorKind)[keyof typeof AthenaApiErrorKind];\n\n/** One entry of a GraphQL answer's `errors`. */\nexport interface AthenaGraphQLErrorEntry {\n  message: string;\n  path?: readonly (string | number)[];\n  /** Agora puts its `code` here (`UNAUTHORIZED`, `BAD_USER_INPUT`, `RATE_LIMITED`…). */\n  extensions?: Readonly<Record<string, unknown>>;\n}\n\nexport interface AthenaApiErrorOptions {\n  kind: AthenaApiErrorKind;\n  message: string;\n  /** The HTTP status agora answered with; `0` (the default) when no answer came. */\n  status?: number;\n  code?: string | null;\n  errors?: readonly AthenaGraphQLErrorEntry[];\n  detail?: unknown;\n  retryAfterMs?: number | null;\n  method: string;\n  path: string;\n  cause?: unknown;\n}\n\n/** Marks an `AthenaApiError` across copies of the SDK (a host bundling two builds). */\nconst ATHENA_API_ERROR: unique symbol = Symbol.for('athena-sdk.AthenaApiError');\n\nexport class AthenaApiError extends Error {\n  readonly [ATHENA_API_ERROR] = true;\n  readonly kind: AthenaApiErrorKind;\n  /**\n   * The HTTP status agora answered with: a GraphQL error answered with 200 says\n   * 200. `0` when no answer came (`network`, `timeout`, `credential`,\n   * `request`).\n   */\n  readonly status: number;\n  /**\n   * Agora's machine-readable code: the first GraphQL error's\n   * `extensions.code`, or a REST error's `detail.code`. `null` when it gave\n   * none.\n   */\n  readonly code: string | null;\n  /** Every GraphQL error of the answer; empty for other failures. */\n  readonly errors: readonly AthenaGraphQLErrorEntry[];\n  /** A REST error's `detail` (FastAPI's envelope), else its body as read; `undefined` when there was none. */\n  readonly detail: unknown;\n  /**\n   * How long agora asked the caller to wait before trying again (`Retry-After`,\n   * or the `retryAfterSeconds` of a rate-limit refusal), in ms; `null` when it\n   * did not say.\n   */\n  readonly retryAfterMs: number | null;\n  /** The request's method. */\n  readonly method: string;\n  /** The request's path, without its query string. */\n  readonly path: string;\n\n  constructor(options: AthenaApiErrorOptions) {\n    super(options.message, options.cause === undefined ? undefined : { cause: options.cause });\n    this.name = 'AthenaApiError';\n    this.kind = options.kind;\n    this.status = options.status ?? 0;\n    this.code = options.code ?? null;\n    this.errors = options.errors ?? [];\n    this.detail = options.detail;\n    this.retryAfterMs = options.retryAfterMs ?? null;\n    this.method = options.method;\n    this.path = options.path;\n  }\n\n  toJSON(): Record<string, unknown> {\n    return {\n      name: this.name,\n      kind: this.kind,\n      status: this.status,\n      code: this.code,\n      message: this.message,\n      errors: this.errors,\n      detail: this.detail,\n      retryAfterMs: this.retryAfterMs,\n      method: this.method,\n      path: this.path,\n    };\n  }\n}\n\n/** Whether `value` is an `AthenaApiError`, from this copy of the SDK or another. */\nexport function isAthenaApiError(value: unknown): value is AthenaApiError {\n  return (\n    value instanceof AthenaApiError ||\n    (typeof value === 'object' && value !== null && Reflect.get(value, ATHENA_API_ERROR) === true)\n  );\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\n/** The `errors` of a GraphQL answer, read leniently: entries without a string message are dropped. */\nexport function graphQLErrorEntries(body: unknown): AthenaGraphQLErrorEntry[] {\n  const errors = isRecord(body) ? body.errors : undefined;\n  if (!Array.isArray(errors)) return [];\n  return errors.flatMap((entry): AthenaGraphQLErrorEntry[] => {\n    if (!isRecord(entry) || typeof entry.message !== 'string') return [];\n    const path = Array.isArray(entry.path)\n      ? entry.path.filter((part): part is string | number => typeof part === 'string' || typeof part === 'number')\n      : undefined;\n    return [\n      {\n        message: entry.message,\n        ...(path ? { path } : {}),\n        ...(isRecord(entry.extensions) ? { extensions: entry.extensions } : {}),\n      },\n    ];\n  });\n}\n\n/** The string `extensions.code` of a GraphQL error, if it has one. */\nexport function graphQLErrorCode(entry: AthenaGraphQLErrorEntry | undefined): string | null {\n  const code = entry?.extensions?.code;\n  return typeof code === 'string' ? code : null;\n}\n\n/**\n * What a REST error body says: FastAPI's `{ detail }` envelope, whose detail\n * is a string or agora's structured `{ code, message, retryAfterSeconds }`.\n */\nexport function restErrorDetail(body: unknown): {\n  detail: unknown;\n  code: string | null;\n  message: string | null;\n  retryAfterSeconds: number | null;\n} {\n  const detail = isRecord(body) && 'detail' in body ? body.detail : body;\n  if (typeof detail === 'string') {\n    return { detail, code: null, message: detail || null, retryAfterSeconds: null };\n  }\n  if (!isRecord(detail)) return { detail, code: null, message: null, retryAfterSeconds: null };\n  return {\n    detail,\n    code: typeof detail.code === 'string' ? detail.code : null,\n    message: typeof detail.message === 'string' ? detail.message : null,\n    retryAfterSeconds:\n      typeof detail.retryAfterSeconds === 'number' && Number.isFinite(detail.retryAfterSeconds)\n        ? detail.retryAfterSeconds\n        : null,\n  };\n}\n"],"names":["_a"],"mappings":";;;;;;AASO,MAAM,qBAAqB;AAAA;AAAA,EAEhC,MAAM;AAAA;AAAA,EAEN,SAAS;AAAA;AAAA,EAET,SAAS;AAAA;AAAA,EAET,SAAS;AAAA;AAAA,EAET,YAAY;AAAA;AAAA,EAEZ,UAAU;AAAA;AAAA,EAEV,SAAS;AACX;AA0BA,MAAM,mBAAkC,OAAO,IAAI,2BAA2B;AAEvE,MAAM,wBAAuB,YACxB,uBADwB,IAAM;AAAA,EA8BxC,YAAY,SAAgC;AAC1C,UAAM,QAAQ,SAAS,QAAQ,UAAU,SAAY,SAAY,EAAE,OAAO,QAAQ,MAAA,CAAO;AA9B3F,wBAAU,IAAoB;AACrB;AAMA;AAAA;AAAA;AAAA;AAAA;AAAA;AAMA;AAAA;AAAA;AAAA;AAAA;AAAA;AAEA;AAAA;AAEA;AAAA;AAMA;AAAA;AAAA;AAAA;AAAA;AAAA;AAEA;AAAA;AAEA;AAAA;AAIP,SAAK,OAAO;AACZ,SAAK,OAAO,QAAQ;AACpB,SAAK,SAAS,QAAQ,UAAU;AAChC,SAAK,OAAO,QAAQ,QAAQ;AAC5B,SAAK,SAAS,QAAQ,UAAU,CAAA;AAChC,SAAK,SAAS,QAAQ;AACtB,SAAK,eAAe,QAAQ,gBAAgB;AAC5C,SAAK,SAAS,QAAQ;AACtB,SAAK,OAAO,QAAQ;AAAA,EACtB;AAAA,EAEA,SAAkC;AAChC,WAAO;AAAA,MACL,MAAM,KAAK;AAAA,MACX,MAAM,KAAK;AAAA,MACX,QAAQ,KAAK;AAAA,MACb,MAAM,KAAK;AAAA,MACX,SAAS,KAAK;AAAA,MACd,QAAQ,KAAK;AAAA,MACb,QAAQ,KAAK;AAAA,MACb,cAAc,KAAK;AAAA,MACnB,QAAQ,KAAK;AAAA,MACb,MAAM,KAAK;AAAA,IAAA;AAAA,EAEf;AACF;AAGO,SAAS,iBAAiB,OAAyC;AACxE,SACE,iBAAiB,kBAChB,OAAO,UAAU,YAAY,UAAU,QAAQ,QAAQ,IAAI,OAAO,gBAAgB,MAAM;AAE7F;AAEA,SAAS,SAAS,OAAkD;AAClE,SAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC5E;AAGO,SAAS,oBAAoB,MAA0C;AAC5E,QAAM,SAAS,SAAS,IAAI,IAAI,KAAK,SAAS;AAC9C,MAAI,CAAC,MAAM,QAAQ,MAAM,UAAU,CAAA;AACnC,SAAO,OAAO,QAAQ,CAAC,UAAqC;AAC1D,QAAI,CAAC,SAAS,KAAK,KAAK,OAAO,MAAM,YAAY,SAAU,QAAO,CAAA;AAClE,UAAM,OAAO,MAAM,QAAQ,MAAM,IAAI,IACjC,MAAM,KAAK,OAAO,CAAC,SAAkC,OAAO,SAAS,YAAY,OAAO,SAAS,QAAQ,IACzG;AACJ,WAAO;AAAA,MACL;AAAA,QACE,SAAS,MAAM;AAAA,QACf,GAAI,OAAO,EAAE,KAAA,IAAS,CAAA;AAAA,QACtB,GAAI,SAAS,MAAM,UAAU,IAAI,EAAE,YAAY,MAAM,eAAe,CAAA;AAAA,MAAC;AAAA,IACvE;AAAA,EAEJ,CAAC;AACH;AAGO,SAAS,iBAAiB,OAA2D;;AAC1F,QAAM,QAAOA,MAAA,+BAAO,eAAP,gBAAAA,IAAmB;AAChC,SAAO,OAAO,SAAS,WAAW,OAAO;AAC3C;AAMO,SAAS,gBAAgB,MAK9B;AACA,QAAM,SAAS,SAAS,IAAI,KAAK,YAAY,OAAO,KAAK,SAAS;AAClE,MAAI,OAAO,WAAW,UAAU;AAC9B,WAAO,EAAE,QAAQ,MAAM,MAAM,SAAS,UAAU,MAAM,mBAAmB,KAAA;AAAA,EAC3E;AACA,MAAI,CAAC,SAAS,MAAM,EAAG,QAAO,EAAE,QAAQ,MAAM,MAAM,SAAS,MAAM,mBAAmB,KAAA;AACtF,SAAO;AAAA,IACL;AAAA,IACA,MAAM,OAAO,OAAO,SAAS,WAAW,OAAO,OAAO;AAAA,IACtD,SAAS,OAAO,OAAO,YAAY,WAAW,OAAO,UAAU;AAAA,IAC/D,mBACE,OAAO,OAAO,sBAAsB,YAAY,OAAO,SAAS,OAAO,iBAAiB,IACpF,OAAO,oBACP;AAAA,EAAA;AAEV;;;;;;;"}

package/dist/data/athena-api-error.d.ts

@@ -0,0 +1,96 @@
+/**
+ * What the SDK's data layer throws (`useAthenaFetch`, `useAthenaGraphQL`,
+ * `useAthenaGraphQLMutation`, `useAthenaRest`, `useSemanticQuery`): one typed
+ * error that says how a request failed (`kind`), with the HTTP status, agora's
+ * machine-readable code and its message. A request its caller cancelled is the
+ * one exception: it rejects with the abort's own reason, as `fetch` does.
+ */
+/** How a request failed. */
+export declare const AthenaApiErrorKind: {
+    /** Agora answered with an error status (4xx or 5xx). */
+    readonly Http: 'http';
+    /** Agora answered a GraphQL operation with errors (a refused read, an invalid query), or with no data. */
+    readonly GraphQL: 'graphql';
+    /** No answer came: offline, a refused CORS preflight, a dropped connection. */
+    readonly Network: 'network';
+    /** No answer came within the request's `timeoutMs`, so the SDK abandoned it. */
+    readonly Timeout: 'timeout';
+    /** The provider could not resolve a credential: its `getToken` threw. */
+    readonly Credential: 'credential';
+    /** The answer could not be read: not the JSON it said it was, or cut off. */
+    readonly Response: 'response';
+    /** The SDK refused to send the request (the message says why). */
+    readonly Request: 'request';
+};
+export type AthenaApiErrorKind = (typeof AthenaApiErrorKind)[keyof typeof AthenaApiErrorKind];
+/** One entry of a GraphQL answer's `errors`. */
+export interface AthenaGraphQLErrorEntry {
+    message: string;
+    path?: readonly (string | number)[];
+    /** Agora puts its `code` here (`UNAUTHORIZED`, `BAD_USER_INPUT`, `RATE_LIMITED`…). */
+    extensions?: Readonly<Record<string, unknown>>;
+}
+export interface AthenaApiErrorOptions {
+    kind: AthenaApiErrorKind;
+    message: string;
+    /** The HTTP status agora answered with; `0` (the default) when no answer came. */
+    status?: number;
+    code?: string | null;
+    errors?: readonly AthenaGraphQLErrorEntry[];
+    detail?: unknown;
+    retryAfterMs?: number | null;
+    method: string;
+    path: string;
+    cause?: unknown;
+}
+/** Marks an `AthenaApiError` across copies of the SDK (a host bundling two builds). */
+declare const ATHENA_API_ERROR: unique symbol;
+export declare class AthenaApiError extends Error {
+    readonly [ATHENA_API_ERROR] = true;
+    readonly kind: AthenaApiErrorKind;
+    /**
+     * The HTTP status agora answered with: a GraphQL error answered with 200 says
+     * 200. `0` when no answer came (`network`, `timeout`, `credential`,
+     * `request`).
+     */
+    readonly status: number;
+    /**
+     * Agora's machine-readable code: the first GraphQL error's
+     * `extensions.code`, or a REST error's `detail.code`. `null` when it gave
+     * none.
+     */
+    readonly code: string | null;
+    /** Every GraphQL error of the answer; empty for other failures. */
+    readonly errors: readonly AthenaGraphQLErrorEntry[];
+    /** A REST error's `detail` (FastAPI's envelope), else its body as read; `undefined` when there was none. */
+    readonly detail: unknown;
+    /**
+     * How long agora asked the caller to wait before trying again (`Retry-After`,
+     * or the `retryAfterSeconds` of a rate-limit refusal), in ms; `null` when it
+     * did not say.
+     */
+    readonly retryAfterMs: number | null;
+    /** The request's method. */
+    readonly method: string;
+    /** The request's path, without its query string. */
+    readonly path: string;
+    constructor(options: AthenaApiErrorOptions);
+    toJSON(): Record<string, unknown>;
+}
+/** Whether `value` is an `AthenaApiError`, from this copy of the SDK or another. */
+export declare function isAthenaApiError(value: unknown): value is AthenaApiError;
+/** The `errors` of a GraphQL answer, read leniently: entries without a string message are dropped. */
+export declare function graphQLErrorEntries(body: unknown): AthenaGraphQLErrorEntry[];
+/** The string `extensions.code` of a GraphQL error, if it has one. */
+export declare function graphQLErrorCode(entry: AthenaGraphQLErrorEntry | undefined): string | null;
+/**
+ * What a REST error body says: FastAPI's `{ detail }` envelope, whose detail
+ * is a string or agora's structured `{ code, message, retryAfterSeconds }`.
+ */
+export declare function restErrorDetail(body: unknown): {
+    detail: unknown;
+    code: string | null;
+    message: string | null;
+    retryAfterSeconds: number | null;
+};
+export {};

package/dist/data/athena-api-error.js

@@ -0,0 +1,125 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+var _a, _b;
+const AthenaApiErrorKind = {
+  /** Agora answered with an error status (4xx or 5xx). */
+  Http: "http",
+  /** Agora answered a GraphQL operation with errors (a refused read, an invalid query), or with no data. */
+  GraphQL: "graphql",
+  /** No answer came: offline, a refused CORS preflight, a dropped connection. */
+  Network: "network",
+  /** No answer came within the request's `timeoutMs`, so the SDK abandoned it. */
+  Timeout: "timeout",
+  /** The provider could not resolve a credential: its `getToken` threw. */
+  Credential: "credential",
+  /** The answer could not be read: not the JSON it said it was, or cut off. */
+  Response: "response",
+  /** The SDK refused to send the request (the message says why). */
+  Request: "request"
+};
+const ATHENA_API_ERROR = Symbol.for("athena-sdk.AthenaApiError");
+class AthenaApiError extends (_b = Error, _a = ATHENA_API_ERROR, _b) {
+  constructor(options) {
+    super(options.message, options.cause === void 0 ? void 0 : { cause: options.cause });
+    __publicField(this, _a, true);
+    __publicField(this, "kind");
+    /**
+     * The HTTP status agora answered with: a GraphQL error answered with 200 says
+     * 200. `0` when no answer came (`network`, `timeout`, `credential`,
+     * `request`).
+     */
+    __publicField(this, "status");
+    /**
+     * Agora's machine-readable code: the first GraphQL error's
+     * `extensions.code`, or a REST error's `detail.code`. `null` when it gave
+     * none.
+     */
+    __publicField(this, "code");
+    /** Every GraphQL error of the answer; empty for other failures. */
+    __publicField(this, "errors");
+    /** A REST error's `detail` (FastAPI's envelope), else its body as read; `undefined` when there was none. */
+    __publicField(this, "detail");
+    /**
+     * How long agora asked the caller to wait before trying again (`Retry-After`,
+     * or the `retryAfterSeconds` of a rate-limit refusal), in ms; `null` when it
+     * did not say.
+     */
+    __publicField(this, "retryAfterMs");
+    /** The request's method. */
+    __publicField(this, "method");
+    /** The request's path, without its query string. */
+    __publicField(this, "path");
+    this.name = "AthenaApiError";
+    this.kind = options.kind;
+    this.status = options.status ?? 0;
+    this.code = options.code ?? null;
+    this.errors = options.errors ?? [];
+    this.detail = options.detail;
+    this.retryAfterMs = options.retryAfterMs ?? null;
+    this.method = options.method;
+    this.path = options.path;
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      kind: this.kind,
+      status: this.status,
+      code: this.code,
+      message: this.message,
+      errors: this.errors,
+      detail: this.detail,
+      retryAfterMs: this.retryAfterMs,
+      method: this.method,
+      path: this.path
+    };
+  }
+}
+function isAthenaApiError(value) {
+  return value instanceof AthenaApiError || typeof value === "object" && value !== null && Reflect.get(value, ATHENA_API_ERROR) === true;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function graphQLErrorEntries(body) {
+  const errors = isRecord(body) ? body.errors : void 0;
+  if (!Array.isArray(errors)) return [];
+  return errors.flatMap((entry) => {
+    if (!isRecord(entry) || typeof entry.message !== "string") return [];
+    const path = Array.isArray(entry.path) ? entry.path.filter((part) => typeof part === "string" || typeof part === "number") : void 0;
+    return [
+      {
+        message: entry.message,
+        ...path ? { path } : {},
+        ...isRecord(entry.extensions) ? { extensions: entry.extensions } : {}
+      }
+    ];
+  });
+}
+function graphQLErrorCode(entry) {
+  var _a2;
+  const code = (_a2 = entry == null ? void 0 : entry.extensions) == null ? void 0 : _a2.code;
+  return typeof code === "string" ? code : null;
+}
+function restErrorDetail(body) {
+  const detail = isRecord(body) && "detail" in body ? body.detail : body;
+  if (typeof detail === "string") {
+    return { detail, code: null, message: detail || null, retryAfterSeconds: null };
+  }
+  if (!isRecord(detail)) return { detail, code: null, message: null, retryAfterSeconds: null };
+  return {
+    detail,
+    code: typeof detail.code === "string" ? detail.code : null,
+    message: typeof detail.message === "string" ? detail.message : null,
+    retryAfterSeconds: typeof detail.retryAfterSeconds === "number" && Number.isFinite(detail.retryAfterSeconds) ? detail.retryAfterSeconds : null
+  };
+}
+export {
+  AthenaApiError,
+  AthenaApiErrorKind,
+  graphQLErrorCode,
+  graphQLErrorEntries,
+  isAthenaApiError,
+  restErrorDetail
+};
+//# sourceMappingURL=athena-api-error.js.map

package/dist/data/athena-api-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"athena-api-error.js","sources":["../../src/data/athena-api-error.ts"],"sourcesContent":["/**\n * What the SDK's data layer throws (`useAthenaFetch`, `useAthenaGraphQL`,\n * `useAthenaGraphQLMutation`, `useAthenaRest`, `useSemanticQuery`): one typed\n * error that says how a request failed (`kind`), with the HTTP status, agora's\n * machine-readable code and its message. A request its caller cancelled is the\n * one exception: it rejects with the abort's own reason, as `fetch` does.\n */\n\n/** How a request failed. */\nexport const AthenaApiErrorKind = {\n  /** Agora answered with an error status (4xx or 5xx). */\n  Http: 'http',\n  /** Agora answered a GraphQL operation with errors (a refused read, an invalid query), or with no data. */\n  GraphQL: 'graphql',\n  /** No answer came: offline, a refused CORS preflight, a dropped connection. */\n  Network: 'network',\n  /** No answer came within the request's `timeoutMs`, so the SDK abandoned it. */\n  Timeout: 'timeout',\n  /** The provider could not resolve a credential: its `getToken` threw. */\n  Credential: 'credential',\n  /** The answer could not be read: not the JSON it said it was, or cut off. */\n  Response: 'response',\n  /** The SDK refused to send the request (the message says why). */\n  Request: 'request',\n} as const;\nexport type AthenaApiErrorKind = (typeof AthenaApiErrorKind)[keyof typeof AthenaApiErrorKind];\n\n/** One entry of a GraphQL answer's `errors`. */\nexport interface AthenaGraphQLErrorEntry {\n  message: string;\n  path?: readonly (string | number)[];\n  /** Agora puts its `code` here (`UNAUTHORIZED`, `BAD_USER_INPUT`, `RATE_LIMITED`…). */\n  extensions?: Readonly<Record<string, unknown>>;\n}\n\nexport interface AthenaApiErrorOptions {\n  kind: AthenaApiErrorKind;\n  message: string;\n  /** The HTTP status agora answered with; `0` (the default) when no answer came. */\n  status?: number;\n  code?: string | null;\n  errors?: readonly AthenaGraphQLErrorEntry[];\n  detail?: unknown;\n  retryAfterMs?: number | null;\n  method: string;\n  path: string;\n  cause?: unknown;\n}\n\n/** Marks an `AthenaApiError` across copies of the SDK (a host bundling two builds). */\nconst ATHENA_API_ERROR: unique symbol = Symbol.for('athena-sdk.AthenaApiError');\n\nexport class AthenaApiError extends Error {\n  readonly [ATHENA_API_ERROR] = true;\n  readonly kind: AthenaApiErrorKind;\n  /**\n   * The HTTP status agora answered with: a GraphQL error answered with 200 says\n   * 200. `0` when no answer came (`network`, `timeout`, `credential`,\n   * `request`).\n   */\n  readonly status: number;\n  /**\n   * Agora's machine-readable code: the first GraphQL error's\n   * `extensions.code`, or a REST error's `detail.code`. `null` when it gave\n   * none.\n   */\n  readonly code: string | null;\n  /** Every GraphQL error of the answer; empty for other failures. */\n  readonly errors: readonly AthenaGraphQLErrorEntry[];\n  /** A REST error's `detail` (FastAPI's envelope), else its body as read; `undefined` when there was none. */\n  readonly detail: unknown;\n  /**\n   * How long agora asked the caller to wait before trying again (`Retry-After`,\n   * or the `retryAfterSeconds` of a rate-limit refusal), in ms; `null` when it\n   * did not say.\n   */\n  readonly retryAfterMs: number | null;\n  /** The request's method. */\n  readonly method: string;\n  /** The request's path, without its query string. */\n  readonly path: string;\n\n  constructor(options: AthenaApiErrorOptions) {\n    super(options.message, options.cause === undefined ? undefined : { cause: options.cause });\n    this.name = 'AthenaApiError';\n    this.kind = options.kind;\n    this.status = options.status ?? 0;\n    this.code = options.code ?? null;\n    this.errors = options.errors ?? [];\n    this.detail = options.detail;\n    this.retryAfterMs = options.retryAfterMs ?? null;\n    this.method = options.method;\n    this.path = options.path;\n  }\n\n  toJSON(): Record<string, unknown> {\n    return {\n      name: this.name,\n      kind: this.kind,\n      status: this.status,\n      code: this.code,\n      message: this.message,\n      errors: this.errors,\n      detail: this.detail,\n      retryAfterMs: this.retryAfterMs,\n      method: this.method,\n      path: this.path,\n    };\n  }\n}\n\n/** Whether `value` is an `AthenaApiError`, from this copy of the SDK or another. */\nexport function isAthenaApiError(value: unknown): value is AthenaApiError {\n  return (\n    value instanceof AthenaApiError ||\n    (typeof value === 'object' && value !== null && Reflect.get(value, ATHENA_API_ERROR) === true)\n  );\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\n/** The `errors` of a GraphQL answer, read leniently: entries without a string message are dropped. */\nexport function graphQLErrorEntries(body: unknown): AthenaGraphQLErrorEntry[] {\n  const errors = isRecord(body) ? body.errors : undefined;\n  if (!Array.isArray(errors)) return [];\n  return errors.flatMap((entry): AthenaGraphQLErrorEntry[] => {\n    if (!isRecord(entry) || typeof entry.message !== 'string') return [];\n    const path = Array.isArray(entry.path)\n      ? entry.path.filter((part): part is string | number => typeof part === 'string' || typeof part === 'number')\n      : undefined;\n    return [\n      {\n        message: entry.message,\n        ...(path ? { path } : {}),\n        ...(isRecord(entry.extensions) ? { extensions: entry.extensions } : {}),\n      },\n    ];\n  });\n}\n\n/** The string `extensions.code` of a GraphQL error, if it has one. */\nexport function graphQLErrorCode(entry: AthenaGraphQLErrorEntry | undefined): string | null {\n  const code = entry?.extensions?.code;\n  return typeof code === 'string' ? code : null;\n}\n\n/**\n * What a REST error body says: FastAPI's `{ detail }` envelope, whose detail\n * is a string or agora's structured `{ code, message, retryAfterSeconds }`.\n */\nexport function restErrorDetail(body: unknown): {\n  detail: unknown;\n  code: string | null;\n  message: string | null;\n  retryAfterSeconds: number | null;\n} {\n  const detail = isRecord(body) && 'detail' in body ? body.detail : body;\n  if (typeof detail === 'string') {\n    return { detail, code: null, message: detail || null, retryAfterSeconds: null };\n  }\n  if (!isRecord(detail)) return { detail, code: null, message: null, retryAfterSeconds: null };\n  return {\n    detail,\n    code: typeof detail.code === 'string' ? detail.code : null,\n    message: typeof detail.message === 'string' ? detail.message : null,\n    retryAfterSeconds:\n      typeof detail.retryAfterSeconds === 'number' && Number.isFinite(detail.retryAfterSeconds)\n        ? detail.retryAfterSeconds\n        : null,\n  };\n}\n"],"names":["_a"],"mappings":"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"}

package/dist/data/athena-data-client.cjs

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const jsxRuntime = require("react/jsx-runtime");
+const reactQuery = require("@tanstack/react-query");
+const require$$0 = require("react");
+const accountIdentity = require("../auth/account-identity.cjs");
+const AthenaAuthContext = require("../auth/AthenaAuthContext.cjs");
+const AthenaCredentialSourceContext = require("../auth/AthenaCredentialSourceContext.cjs");
+const AthenaContext = require("../provider/AthenaContext.cjs");
+const athenaApiError = require("./athena-api-error.cjs");
+const athenaRequest = require("./athena-request.cjs");
+const AthenaDataQueryClientContext = require$$0.createContext(null);
+function AthenaDataQueryClientProvider({ children }) {
+  const [client] = require$$0.useState(() => new reactQuery.QueryClient());
+  require$$0.useEffect(() => {
+    client.mount();
+    return () => client.unmount();
+  }, [client]);
+  return /* @__PURE__ */ jsxRuntime.jsx(AthenaDataQueryClientContext.Provider, { value: client, children });
+}
+function useAthenaDataQueryClient() {
+  const own = require$$0.useContext(AthenaDataQueryClientContext);
+  const inContext = require$$0.useContext(reactQuery.QueryClientContext);
+  const fallback = require$$0.useRef(null);
+  if (own) return own;
+  if (inContext) return inContext;
+  fallback.current ?? (fallback.current = new reactQuery.QueryClient());
+  return fallback.current;
+}
+const AthenaDataKind = {
+  GraphQL: "graphql",
+  Rest: "rest",
+  SemanticQuery: "semantic-query"
+};
+function useAthenaDataScope() {
+  var _a, _b;
+  const { backendUrl, apiKey, token } = AthenaContext.useAthenaConfig();
+  const principal = ((_b = (_a = require$$0.useContext(AthenaAuthContext.AthenaAuthContext)) == null ? void 0 : _a.user) == null ? void 0 : _b.userId) ?? "";
+  const scopeEpoch = AthenaCredentialSourceContext.useAthenaCredentialScopeEpoch();
+  const [apiKeyPart, heldTokenPart] = accountIdentity.credentialKeyParts({ apiKey, heldToken: token });
+  return require$$0.useMemo(
+    () => ["athena-sdk", "data", backendUrl, principal, apiKeyPart, heldTokenPart, scopeEpoch],
+    [backendUrl, principal, apiKeyPart, heldTokenPart, scopeEpoch]
+  );
+}
+const ATHENA_DATA_STALE_MS = 3e4;
+const MAX_TRANSIENT_RETRIES = 2;
+const MAX_RETRY_DELAY_MS = 3e4;
+const MAX_HINTED_RETRY_DELAY_MS = 6e4;
+function retryAthenaRead(failureCount, error) {
+  if (!athenaApiError.isAthenaApiError(error) || failureCount >= MAX_TRANSIENT_RETRIES) return false;
+  if (error.kind === athenaApiError.AthenaApiErrorKind.Network) return true;
+  return error.kind === athenaApiError.AthenaApiErrorKind.Http && error.status >= 500;
+}
+function athenaRetryDelay(failureCount, error) {
+  if (athenaApiError.isAthenaApiError(error) && error.retryAfterMs !== null) {
+    return Math.min(error.retryAfterMs, MAX_HINTED_RETRY_DELAY_MS);
+  }
+  return Math.min(1e3 * 2 ** failureCount, MAX_RETRY_DELAY_MS);
+}
+function enabledAnd(enabled, ready) {
+  if (typeof enabled === "function") return (query) => ready && enabled(query);
+  return ready && (enabled ?? true);
+}
+function inScope(queryKey, scope) {
+  return scope.every((part, at) => Object.is(queryKey[at], part));
+}
+function matchesFilter(queryKey, scope, filter) {
+  var _a;
+  if (!filter) return true;
+  const kind = queryKey[scope.length];
+  const subject = queryKey[scope.length + 1];
+  if (typeof subject !== "string") return false;
+  if (kind === AthenaDataKind.GraphQL) {
+    const operationName = queryKey[scope.length + 3];
+    const name = (_a = athenaRequest.selectedGraphQLOperation(subject, typeof operationName === "string" ? operationName : null)) == null ? void 0 : _a.name;
+    return typeof name === "string" && (filter.operationNames ?? []).includes(name);
+  }
+  if (kind === AthenaDataKind.Rest) {
+    return (filter.paths ?? []).some((prefix) => subject.startsWith(prefix));
+  }
+  if (kind === AthenaDataKind.SemanticQuery) {
+    return (filter.semanticModelIds ?? []).includes(subject);
+  }
+  return false;
+}
+function useInvalidateAthenaQueries() {
+  const client = useAthenaDataQueryClient();
+  const scope = useAthenaDataScope();
+  return require$$0.useCallback(
+    (filter) => client.invalidateQueries({
+      predicate: ({ queryKey }) => inScope(queryKey, scope) && matchesFilter(queryKey, scope, filter)
+    }),
+    [client, scope]
+  );
+}
+exports.ATHENA_DATA_STALE_MS = ATHENA_DATA_STALE_MS;
+exports.AthenaDataKind = AthenaDataKind;
+exports.AthenaDataQueryClientProvider = AthenaDataQueryClientProvider;
+exports.athenaRetryDelay = athenaRetryDelay;
+exports.enabledAnd = enabledAnd;
+exports.retryAthenaRead = retryAthenaRead;
+exports.useAthenaDataQueryClient = useAthenaDataQueryClient;
+exports.useAthenaDataScope = useAthenaDataScope;
+exports.useInvalidateAthenaQueries = useInvalidateAthenaQueries;
+//# sourceMappingURL=athena-data-client.cjs.map

package/dist/data/athena-data-client.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"athena-data-client.cjs","sources":["../../src/data/athena-data-client.tsx"],"sourcesContent":["/**\n * What every data hook shares: the SDK's own `QueryClient` (one per\n * `AthenaProvider`, so a host needs no `QueryClientProvider` and the hooks\n * never write into a host's cache), the identity every cache key starts with,\n * and the retry rule.\n *\n * Cache isolation: every key starts with the backend, the signed-in person,\n * the credential's fingerprint (the API key's, and who the held token acts as\n * and in which workspace, never the secret) and the provider's credential\n * scope epoch, which moves once a host's `getToken` hands out a token that\n * acts as someone else or is scoped to another workspace or org. A switch of\n * person, key or workspace therefore reads under new keys and never serves the\n * previous identity's answers.\n */\nimport {\n  QueryClient,\n  QueryClientContext,\n  type QueryKey,\n} from '@tanstack/react-query';\nimport {\n  createContext,\n  type ReactNode,\n  useCallback,\n  useContext,\n  useEffect,\n  useMemo,\n  useRef,\n  useState,\n} from 'react';\nimport { credentialKeyParts } from '../auth/account-identity';\nimport { AthenaAuthContext } from '../auth/AthenaAuthContext';\nimport { useAthenaCredentialScopeEpoch } from '../auth/AthenaCredentialSourceContext';\nimport { useAthenaConfig } from '../provider/AthenaContext';\nimport { AthenaApiErrorKind, isAthenaApiError } from './athena-api-error';\nimport { selectedGraphQLOperation } from './athena-request';\n\nconst AthenaDataQueryClientContext = createContext<QueryClient | null>(null);\n\n/**\n * Gives the data hooks under it one `QueryClient` of their own for as long as\n * it is mounted (`AthenaProvider` mounts it). Mounted as `QueryClientProvider`\n * mounts a client, so reads refetch on reconnect and, when asked, on focus.\n */\nexport function AthenaDataQueryClientProvider({ children }: { children: ReactNode }) {\n  const [client] = useState(() => new QueryClient());\n  useEffect(() => {\n    client.mount();\n    return () => client.unmount();\n  }, [client]);\n  return (\n    <AthenaDataQueryClientContext.Provider value={client}>{children}</AthenaDataQueryClientContext.Provider>\n  );\n}\n\n/**\n * The data hooks' client: the provider's own, else (a provider-less tree, as in\n * a host's tests) a `QueryClient` in context, else one of the calling hook's.\n */\nexport function useAthenaDataQueryClient(): QueryClient {\n  const own = useContext(AthenaDataQueryClientContext);\n  const inContext = useContext(QueryClientContext);\n  const fallback = useRef<QueryClient | null>(null);\n  if (own) return own;\n  if (inContext) return inContext;\n  fallback.current ??= new QueryClient();\n  return fallback.current;\n}\n\n/**\n * The first parts of every data key: whose reads they are. After the two tags:\n * the backend, the signed-in person (`''` when the provider knows none), the\n * API key's fingerprint, who the held token acts as and where, and the scope\n * epoch.\n */\nexport type AthenaDataScope = readonly ['athena-sdk', 'data', string, string, string, string, number];\n\n/** What a data key holds after its scope. */\nexport const AthenaDataKind = {\n  GraphQL: 'graphql',\n  Rest: 'rest',\n  SemanticQuery: 'semantic-query',\n} as const;\nexport type AthenaDataKind = (typeof AthenaDataKind)[keyof typeof AthenaDataKind];\n\n/** The scope the provider's reads are cached under now (see the module comment). */\nexport function useAthenaDataScope(): AthenaDataScope {\n  const { backendUrl, apiKey, token } = useAthenaConfig();\n  const principal = useContext(AthenaAuthContext)?.user?.userId ?? '';\n  const scopeEpoch = useAthenaCredentialScopeEpoch();\n  const [apiKeyPart, heldTokenPart] = credentialKeyParts({ apiKey, heldToken: token });\n  return useMemo(\n    () => ['athena-sdk', 'data', backendUrl, principal, apiKeyPart, heldTokenPart, scopeEpoch] as const,\n    [backendUrl, principal, apiKeyPart, heldTokenPart, scopeEpoch],\n  );\n}\n\n/** How long an answer serves another read of the same thing before agora is asked again. */\nexport const ATHENA_DATA_STALE_MS = 30_000;\n\nconst MAX_TRANSIENT_RETRIES = 2;\nconst MAX_RETRY_DELAY_MS = 30_000;\nconst MAX_HINTED_RETRY_DELAY_MS = 60_000;\n\n/**\n * Whether a failed read is asked again: only what may answer differently a\n * moment later (no answer at all, or a 5xx), twice at most. A 4xx (a 429 the\n * transport already waited out included), a GraphQL error, a timeout, a\n * credential that could not be resolved and an unreadable answer are not.\n */\nexport function retryAthenaRead(failureCount: number, error: unknown): boolean {\n  if (!isAthenaApiError(error) || failureCount >= MAX_TRANSIENT_RETRIES) return false;\n  if (error.kind === AthenaApiErrorKind.Network) return true;\n  return error.kind === AthenaApiErrorKind.Http && error.status >= 500;\n}\n\n/** The wait before asking again: what agora asked for (`Retry-After`), else 1 s, 2 s, 4 s… */\nexport function athenaRetryDelay(failureCount: number, error: unknown): number {\n  if (isAthenaApiError(error) && error.retryAfterMs !== null) {\n    return Math.min(error.retryAfterMs, MAX_HINTED_RETRY_DELAY_MS);\n  }\n  return Math.min(1_000 * 2 ** failureCount, MAX_RETRY_DELAY_MS);\n}\n\n/** `enabled` as a host passed it, and also `ready`. */\nexport function enabledAnd<TQuery>(\n  enabled: boolean | ((query: TQuery) => boolean) | undefined,\n  ready: boolean,\n): boolean | ((query: TQuery) => boolean) {\n  if (typeof enabled === 'function') return (query: TQuery) => ready && enabled(query);\n  return ready && (enabled ?? true);\n}\n\n/** Which of the current identity's reads to read again; every field is optional, and none means all. */\nexport interface AthenaDataQueryFilter {\n  /** GraphQL reads whose operation has one of these names. */\n  operationNames?: readonly string[];\n  /** REST reads whose path starts with one of these. */\n  paths?: readonly string[];\n  /** Semantic queries of these models. */\n  semanticModelIds?: readonly string[];\n}\n\nfunction inScope(queryKey: QueryKey, scope: AthenaDataScope): boolean {\n  return scope.every((part, at) => Object.is(queryKey[at], part));\n}\n\nfunction matchesFilter(\n  queryKey: QueryKey,\n  scope: AthenaDataScope,\n  filter: AthenaDataQueryFilter | undefined,\n): boolean {\n  if (!filter) return true;\n  const kind = queryKey[scope.length];\n  const subject = queryKey[scope.length + 1];\n  if (typeof subject !== 'string') return false;\n  if (kind === AthenaDataKind.GraphQL) {\n    // The operation the read runs: the one its `operationName` names, else its document's only one.\n    const operationName = queryKey[scope.length + 3];\n    const name = selectedGraphQLOperation(subject, typeof operationName === 'string' ? operationName : null)?.name;\n    return typeof name === 'string' && (filter.operationNames ?? []).includes(name);\n  }\n  if (kind === AthenaDataKind.Rest) {\n    return (filter.paths ?? []).some((prefix) => subject.startsWith(prefix));\n  }\n  if (kind === AthenaDataKind.SemanticQuery) {\n    return (filter.semanticModelIds ?? []).includes(subject);\n  }\n  return false;\n}\n\n/**\n * Answers a function that has the current identity's data reads read again:\n * those `filter` names, or every one without it. Reads on screen are sent at\n * once; the rest read again when next shown. Call it after a write that\n * changes what they answer.\n */\nexport function useInvalidateAthenaQueries(): (filter?: AthenaDataQueryFilter) => Promise<void> {\n  const client = useAthenaDataQueryClient();\n  const scope = useAthenaDataScope();\n  return useCallback(\n    (filter?: AthenaDataQueryFilter) =>\n      client.invalidateQueries({\n        predicate: ({ queryKey }) => inScope(queryKey, scope) && matchesFilter(queryKey, scope, filter),\n      }),\n    [client, scope],\n  );\n}\n"],"names":["createContext","useState","QueryClient","useEffect","useContext","QueryClientContext","useRef","useAthenaConfig","AthenaAuthContext","useAthenaCredentialScopeEpoch","credentialKeyParts","useMemo","isAthenaApiError","AthenaApiErrorKind","selectedGraphQLOperation","useCallback"],"mappings":"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"}