@athenaintel/react 0.57.2 → 0.59.0

package/dist/data/athena-member.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Bundle member names: `support-desk/support_agent` resolved to this place's
+ * own asset (Bundle Phase 2; docs/plans/2026-11-09-bundle-phase-2-plan.md §6.3).
+ *
+ * A bundle names each member by a permanent key, and each workspace or
+ * deployment that holds the bundle (the source and every copy) has its own
+ * asset behind that key. Code that names `<bundle key>/<member key>` keeps
+ * working in every place, where a raw `asset_…` id names one place's asset only.
+ * Agora resolves a name through one route,
+ * `GET /api/v0/bundles/{bundle_key}/members/{member_key}`, in the caller's
+ * workspace: it answers only a member the caller may open, and every refusal is
+ * the same 404 a name that doesn't exist gets.
+ *
+ * - {@link resolveAthenaMember}: one read, outside React (a script holding an
+ *   API key, a server).
+ * - {@link useAthenaMember}: the same read as a cached query, as the provider's
+ *   signed-in person.
+ */
+import type { UseQueryResult } from '@tanstack/react-query';
+import { AthenaApiError } from './athena-api-error';
+import { type AthenaRequestConfig } from './athena-request';
+import { type UseAthenaRestOptions } from './use-athena-rest';
+/** A bundle key: lowercase words joined by single hyphens, at most 63 characters (`support-desk`). */
+export declare const ATHENA_BUNDLE_KEY_PATTERN: RegExp;
+/** The longest bundle key. */
+export declare const ATHENA_BUNDLE_KEY_MAX_LENGTH = 63;
+/** A member key: a lowercase letter, then letters, digits and underscores, 63 at most (`support_agent`). */
+export declare const ATHENA_MEMBER_KEY_PATTERN: RegExp;
+/** A parsed `<bundle key>/<member key>`. */
+export interface AthenaMemberName {
+    bundleKey: string;
+    memberKey: string;
+}
+/** The revision a track serves of a member: its version id and content digest. */
+export interface AthenaMemberRevision {
+    version_id: string;
+    /** `sha256:…`, the same in every place holding this revision; `null` for a version cut before digests. */
+    digest: string | null;
+    digest_alg: string | null;
+}
+/** A member name resolved in the caller's place, as agora answers it. */
+export interface AthenaMember {
+    bundle_key: string;
+    member_key: string;
+    /** This place's asset for the member. */
+    asset_id: string;
+    /** The member asset's type (`collab_agent`, `user_interface`…). */
+    type: string;
+    /** How the member joins the bundle: `ships`, `pin`, `pin+notify` or `follow`. */
+    link: string;
+    /** The track the answer read; `null` when none was asked for. */
+    track: string | null;
+    /** With a track, the revision it serves of the member (`null` when followed); `null` without a track. */
+    revision: AthenaMemberRevision | null;
+}
+/**
+ * A member name that doesn't resolve for the caller: no such bundle or member in
+ * the caller's workspace, or one the caller can't open. Agora answers the two
+ * alike, so this error doesn't tell them apart either.
+ */
+export declare class AthenaMemberNotFoundError extends Error {
+    /** The name that didn't resolve (`support-desk/support_agent`). */
+    readonly memberName: string;
+    constructor(memberName: string, options?: {
+        cause?: unknown;
+    });
+}
+/** `value` as `<bundle key>/<member key>`, or `null`. An `asset_…` id never parses: it holds no `/`. */
+export declare function parseAthenaMemberName(value: unknown): AthenaMemberName | null;
+/** Whether `value` is a member name (`<bundle key>/<member key>`). */
+export declare function isAthenaMemberName(value: unknown): value is string;
+/** The members route's path for a parsed name. */
+export declare function athenaMemberPath({ bundleKey, memberKey }: AthenaMemberName): string;
+export interface ResolveAthenaMemberOptions extends AthenaRequestConfig {
+    /** `<bundle key>/<member key>`, e.g. `support-desk/support_agent`. */
+    name: string;
+    /** A track's key (`production`, `pilot`…): also answer the revision it serves. The caller must be on the track. */
+    track?: string;
+    /**
+     * The workspace to resolve in. Optional for a person in one workspace and for a credential bound to
+     * one; a person in several names it (else agora answers `400 workspace_required`).
+     */
+    workspaceId?: string;
+    /** Cancels the read; it then rejects with the abort's reason. */
+    signal?: AbortSignal;
+}
+/**
+ * Resolve a member name to this place's asset, as the credential's person, in
+ * the workspace `workspaceId` names (or their only one). Sent as every SDK request is (the token from `getToken` or
+ * `token`, else `apiKey`; under `backendUrl` only).
+ *
+ * Throws {@link AthenaMemberNotFoundError} when the name doesn't resolve for
+ * the caller, an `AthenaApiError` of kind `request` for a string that isn't a
+ * member name (nothing is sent), and an `AthenaApiError` for any other failure.
+ *
+ * ```ts
+ * const agent = await resolveAthenaMember({
+ *   backendUrl: 'https://api.athenaintel.com',
+ *   apiKey: process.env.ATHENA_API_KEY,
+ *   name: 'support-desk/support_agent',
+ * });
+ * agent.asset_id; // this workspace's own agent
+ * ```
+ */
+export declare function resolveAthenaMember({ name, track, workspaceId, signal, ...config }: ResolveAthenaMemberOptions): Promise<AthenaMember>;
+/** `useAthenaMember`'s options: a track, and TanStack Query's (`enabled`, `select`…). */
+export type UseAthenaMemberOptions = Omit<UseAthenaRestOptions<AthenaMember>, 'params'> & {
+    /** A track's key: also answer the revision it serves (part of the cache key). */
+    track?: string;
+    /** The workspace to resolve in, for a person in several (part of the cache key). */
+    workspaceId?: string;
+};
+/**
+ * The asset a member name resolves to, as the provider's signed-in person: a
+ * cached query on the SDK's QueryClient (`useAthenaRest` on the members route).
+ * `null`, or a string that isn't a member name, holds the read idle (check with
+ * {@link isAthenaMemberName}). A name that doesn't resolve for the person fails
+ * with an `AthenaApiError` whose `status` is 404 and `code` `member_not_found`.
+ *
+ * ```tsx
+ * const agent = useAthenaMember('support-desk/support_agent');
+ * if (agent.data) startChat({ agentId: agent.data.asset_id });
+ * ```
+ */
+export declare function useAthenaMember(name: string | null, { track, workspaceId, ...options }?: UseAthenaMemberOptions): UseQueryResult<AthenaMember, AthenaApiError>;

package/dist/data/athena-member.js

@@ -0,0 +1,93 @@
+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);
+import { AthenaApiError, AthenaApiErrorKind, isAthenaApiError } from "./athena-api-error.js";
+import { athenaFetchJson } from "./athena-request.js";
+import { useAthenaRest } from "./use-athena-rest.js";
+const ATHENA_BUNDLE_KEY_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const ATHENA_BUNDLE_KEY_MAX_LENGTH = 63;
+const ATHENA_MEMBER_KEY_PATTERN = /^[a-z][a-z0-9_]{0,62}$/;
+class AthenaMemberNotFoundError extends Error {
+  constructor(memberName, options) {
+    super(`No member named ${memberName} here, or you can't open it.`, options);
+    /** The name that didn't resolve (`support-desk/support_agent`). */
+    __publicField(this, "memberName");
+    this.name = "AthenaMemberNotFoundError";
+    this.memberName = memberName;
+  }
+}
+function parseAthenaMemberName(value) {
+  if (typeof value !== "string") return null;
+  const slash = value.indexOf("/");
+  if (slash < 0) return null;
+  const bundleKey = value.slice(0, slash);
+  const memberKey = value.slice(slash + 1);
+  if (bundleKey.length > ATHENA_BUNDLE_KEY_MAX_LENGTH || !ATHENA_BUNDLE_KEY_PATTERN.test(bundleKey) || !ATHENA_MEMBER_KEY_PATTERN.test(memberKey)) {
+    return null;
+  }
+  return { bundleKey, memberKey };
+}
+function isAthenaMemberName(value) {
+  return parseAthenaMemberName(value) !== null;
+}
+function athenaMemberPath({ bundleKey, memberKey }) {
+  return `/api/v0/bundles/${encodeURIComponent(bundleKey)}/members/${encodeURIComponent(memberKey)}`;
+}
+function memberParams({
+  track,
+  workspaceId
+}) {
+  const params = {};
+  if (track) params.track = track;
+  if (workspaceId) params.workspace_id = workspaceId;
+  return Object.keys(params).length > 0 ? params : void 0;
+}
+async function resolveAthenaMember({
+  name,
+  track,
+  workspaceId,
+  signal,
+  ...config
+}) {
+  const parsed = parseAthenaMemberName(name);
+  const path = parsed ? athenaMemberPath(parsed) : "/api/v0/bundles";
+  if (parsed === null) {
+    throw new AthenaApiError({
+      kind: AthenaApiErrorKind.Request,
+      message: `${JSON.stringify(name)} isn't a member name: write <bundle key>/<member key>, e.g. support-desk/support_agent.`,
+      method: "GET",
+      path
+    });
+  }
+  try {
+    return await athenaFetchJson(config, path, {
+      method: "GET",
+      params: memberParams({ track, workspaceId }),
+      signal
+    });
+  } catch (error) {
+    if (isAthenaApiError(error) && error.status === 404) {
+      throw new AthenaMemberNotFoundError(name, { cause: error });
+    }
+    throw error;
+  }
+}
+function useAthenaMember(name, { track, workspaceId, ...options } = {}) {
+  const parsed = name === null ? null : parseAthenaMemberName(name);
+  return useAthenaRest(parsed ? athenaMemberPath(parsed) : null, {
+    ...options,
+    params: memberParams({ track, workspaceId })
+  });
+}
+export {
+  ATHENA_BUNDLE_KEY_MAX_LENGTH,
+  ATHENA_BUNDLE_KEY_PATTERN,
+  ATHENA_MEMBER_KEY_PATTERN,
+  AthenaMemberNotFoundError,
+  athenaMemberPath,
+  isAthenaMemberName,
+  parseAthenaMemberName,
+  resolveAthenaMember,
+  useAthenaMember
+};
+//# sourceMappingURL=athena-member.js.map

package/dist/data/athena-member.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"athena-member.js","sources":["../../src/data/athena-member.ts"],"sourcesContent":["/**\n * Bundle member names: `support-desk/support_agent` resolved to this place's\n * own asset (Bundle Phase 2; docs/plans/2026-11-09-bundle-phase-2-plan.md §6.3).\n *\n * A bundle names each member by a permanent key, and each workspace or\n * deployment that holds the bundle (the source and every copy) has its own\n * asset behind that key. Code that names `<bundle key>/<member key>` keeps\n * working in every place, where a raw `asset_…` id names one place's asset only.\n * Agora resolves a name through one route,\n * `GET /api/v0/bundles/{bundle_key}/members/{member_key}`, in the caller's\n * workspace: it answers only a member the caller may open, and every refusal is\n * the same 404 a name that doesn't exist gets.\n *\n * - {@link resolveAthenaMember}: one read, outside React (a script holding an\n *   API key, a server).\n * - {@link useAthenaMember}: the same read as a cached query, as the provider's\n *   signed-in person.\n */\nimport type { UseQueryResult } from '@tanstack/react-query';\nimport { AthenaApiError, AthenaApiErrorKind, isAthenaApiError } from './athena-api-error';\nimport { type AthenaRequestConfig, athenaFetchJson } from './athena-request';\nimport { type UseAthenaRestOptions, useAthenaRest } from './use-athena-rest';\n\n/** A bundle key: lowercase words joined by single hyphens, at most 63 characters (`support-desk`). */\nexport const ATHENA_BUNDLE_KEY_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;\n/** The longest bundle key. */\nexport const ATHENA_BUNDLE_KEY_MAX_LENGTH = 63;\n/** A member key: a lowercase letter, then letters, digits and underscores, 63 at most (`support_agent`). */\nexport const ATHENA_MEMBER_KEY_PATTERN = /^[a-z][a-z0-9_]{0,62}$/;\n\n/** A parsed `<bundle key>/<member key>`. */\nexport interface AthenaMemberName {\n  bundleKey: string;\n  memberKey: string;\n}\n\n/** The revision a track serves of a member: its version id and content digest. */\nexport interface AthenaMemberRevision {\n  version_id: string;\n  /** `sha256:…`, the same in every place holding this revision; `null` for a version cut before digests. */\n  digest: string | null;\n  digest_alg: string | null;\n}\n\n/** A member name resolved in the caller's place, as agora answers it. */\nexport interface AthenaMember {\n  bundle_key: string;\n  member_key: string;\n  /** This place's asset for the member. */\n  asset_id: string;\n  /** The member asset's type (`collab_agent`, `user_interface`…). */\n  type: string;\n  /** How the member joins the bundle: `ships`, `pin`, `pin+notify` or `follow`. */\n  link: string;\n  /** The track the answer read; `null` when none was asked for. */\n  track: string | null;\n  /** With a track, the revision it serves of the member (`null` when followed); `null` without a track. */\n  revision: AthenaMemberRevision | null;\n}\n\n/**\n * A member name that doesn't resolve for the caller: no such bundle or member in\n * the caller's workspace, or one the caller can't open. Agora answers the two\n * alike, so this error doesn't tell them apart either.\n */\nexport class AthenaMemberNotFoundError extends Error {\n  /** The name that didn't resolve (`support-desk/support_agent`). */\n  readonly memberName: string;\n\n  constructor(memberName: string, options?: { cause?: unknown }) {\n    super(`No member named ${memberName} here, or you can't open it.`, options);\n    this.name = 'AthenaMemberNotFoundError';\n    this.memberName = memberName;\n  }\n}\n\n/** `value` as `<bundle key>/<member key>`, or `null`. An `asset_…` id never parses: it holds no `/`. */\nexport function parseAthenaMemberName(value: unknown): AthenaMemberName | null {\n  if (typeof value !== 'string') return null;\n  const slash = value.indexOf('/');\n  if (slash < 0) return null;\n  const bundleKey = value.slice(0, slash);\n  const memberKey = value.slice(slash + 1);\n  if (\n    bundleKey.length > ATHENA_BUNDLE_KEY_MAX_LENGTH ||\n    !ATHENA_BUNDLE_KEY_PATTERN.test(bundleKey) ||\n    !ATHENA_MEMBER_KEY_PATTERN.test(memberKey)\n  ) {\n    return null;\n  }\n  return { bundleKey, memberKey };\n}\n\n/** Whether `value` is a member name (`<bundle key>/<member key>`). */\nexport function isAthenaMemberName(value: unknown): value is string {\n  return parseAthenaMemberName(value) !== null;\n}\n\n/** The members route's path for a parsed name. */\nexport function athenaMemberPath({ bundleKey, memberKey }: AthenaMemberName): string {\n  return `/api/v0/bundles/${encodeURIComponent(bundleKey)}/members/${encodeURIComponent(memberKey)}`;\n}\n\nexport interface ResolveAthenaMemberOptions extends AthenaRequestConfig {\n  /** `<bundle key>/<member key>`, e.g. `support-desk/support_agent`. */\n  name: string;\n  /** A track's key (`production`, `pilot`…): also answer the revision it serves. The caller must be on the track. */\n  track?: string;\n  /**\n   * The workspace to resolve in. Optional for a person in one workspace and for a credential bound to\n   * one; a person in several names it (else agora answers `400 workspace_required`).\n   */\n  workspaceId?: string;\n  /** Cancels the read; it then rejects with the abort's reason. */\n  signal?: AbortSignal;\n}\n\nfunction memberParams({\n  track,\n  workspaceId,\n}: {\n  track?: string;\n  workspaceId?: string;\n}): Record<string, string> | undefined {\n  const params: Record<string, string> = {};\n  if (track) params.track = track;\n  if (workspaceId) params.workspace_id = workspaceId;\n  return Object.keys(params).length > 0 ? params : undefined;\n}\n\n/**\n * Resolve a member name to this place's asset, as the credential's person, in\n * the workspace `workspaceId` names (or their only one). Sent as every SDK request is (the token from `getToken` or\n * `token`, else `apiKey`; under `backendUrl` only).\n *\n * Throws {@link AthenaMemberNotFoundError} when the name doesn't resolve for\n * the caller, an `AthenaApiError` of kind `request` for a string that isn't a\n * member name (nothing is sent), and an `AthenaApiError` for any other failure.\n *\n * ```ts\n * const agent = await resolveAthenaMember({\n *   backendUrl: 'https://api.athenaintel.com',\n *   apiKey: process.env.ATHENA_API_KEY,\n *   name: 'support-desk/support_agent',\n * });\n * agent.asset_id; // this workspace's own agent\n * ```\n */\nexport async function resolveAthenaMember({\n  name,\n  track,\n  workspaceId,\n  signal,\n  ...config\n}: ResolveAthenaMemberOptions): Promise<AthenaMember> {\n  const parsed = parseAthenaMemberName(name);\n  const path = parsed ? athenaMemberPath(parsed) : '/api/v0/bundles';\n  if (parsed === null) {\n    throw new AthenaApiError({\n      kind: AthenaApiErrorKind.Request,\n      message: `${JSON.stringify(name)} isn't a member name: write <bundle key>/<member key>, e.g. support-desk/support_agent.`,\n      method: 'GET',\n      path,\n    });\n  }\n  try {\n    return await athenaFetchJson<AthenaMember>(config, path, {\n      method: 'GET',\n      params: memberParams({ track, workspaceId }),\n      signal,\n    });\n  } catch (error) {\n    if (isAthenaApiError(error) && error.status === 404) {\n      throw new AthenaMemberNotFoundError(name, { cause: error });\n    }\n    throw error;\n  }\n}\n\n/** `useAthenaMember`'s options: a track, and TanStack Query's (`enabled`, `select`…). */\nexport type UseAthenaMemberOptions = Omit<UseAthenaRestOptions<AthenaMember>, 'params'> & {\n  /** A track's key: also answer the revision it serves (part of the cache key). */\n  track?: string;\n  /** The workspace to resolve in, for a person in several (part of the cache key). */\n  workspaceId?: string;\n};\n\n/**\n * The asset a member name resolves to, as the provider's signed-in person: a\n * cached query on the SDK's QueryClient (`useAthenaRest` on the members route).\n * `null`, or a string that isn't a member name, holds the read idle (check with\n * {@link isAthenaMemberName}). A name that doesn't resolve for the person fails\n * with an `AthenaApiError` whose `status` is 404 and `code` `member_not_found`.\n *\n * ```tsx\n * const agent = useAthenaMember('support-desk/support_agent');\n * if (agent.data) startChat({ agentId: agent.data.asset_id });\n * ```\n */\nexport function useAthenaMember(\n  name: string | null,\n  { track, workspaceId, ...options }: UseAthenaMemberOptions = {},\n): UseQueryResult<AthenaMember, AthenaApiError> {\n  const parsed = name === null ? null : parseAthenaMemberName(name);\n  return useAthenaRest<AthenaMember>(parsed ? athenaMemberPath(parsed) : null, {\n    ...options,\n    params: memberParams({ track, workspaceId }),\n  });\n}\n"],"names":[],"mappings":";;;;;;AAwBO,MAAM,4BAA4B;AAElC,MAAM,+BAA+B;AAErC,MAAM,4BAA4B;AAqClC,MAAM,kCAAkC,MAAM;AAAA,EAInD,YAAY,YAAoB,SAA+B;AAC7D,UAAM,mBAAmB,UAAU,gCAAgC,OAAO;AAHnE;AAAA;AAIP,SAAK,OAAO;AACZ,SAAK,aAAa;AAAA,EACpB;AACF;AAGO,SAAS,sBAAsB,OAAyC;AAC7E,MAAI,OAAO,UAAU,SAAU,QAAO;AACtC,QAAM,QAAQ,MAAM,QAAQ,GAAG;AAC/B,MAAI,QAAQ,EAAG,QAAO;AACtB,QAAM,YAAY,MAAM,MAAM,GAAG,KAAK;AACtC,QAAM,YAAY,MAAM,MAAM,QAAQ,CAAC;AACvC,MACE,UAAU,SAAS,gCACnB,CAAC,0BAA0B,KAAK,SAAS,KACzC,CAAC,0BAA0B,KAAK,SAAS,GACzC;AACA,WAAO;AAAA,EACT;AACA,SAAO,EAAE,WAAW,UAAA;AACtB;AAGO,SAAS,mBAAmB,OAAiC;AAClE,SAAO,sBAAsB,KAAK,MAAM;AAC1C;AAGO,SAAS,iBAAiB,EAAE,WAAW,aAAuC;AACnF,SAAO,mBAAmB,mBAAmB,SAAS,CAAC,YAAY,mBAAmB,SAAS,CAAC;AAClG;AAgBA,SAAS,aAAa;AAAA,EACpB;AAAA,EACA;AACF,GAGuC;AACrC,QAAM,SAAiC,CAAA;AACvC,MAAI,cAAc,QAAQ;AAC1B,MAAI,oBAAoB,eAAe;AACvC,SAAO,OAAO,KAAK,MAAM,EAAE,SAAS,IAAI,SAAS;AACnD;AAoBA,eAAsB,oBAAoB;AAAA,EACxC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,GAAG;AACL,GAAsD;AACpD,QAAM,SAAS,sBAAsB,IAAI;AACzC,QAAM,OAAO,SAAS,iBAAiB,MAAM,IAAI;AACjD,MAAI,WAAW,MAAM;AACnB,UAAM,IAAI,eAAe;AAAA,MACvB,MAAM,mBAAmB;AAAA,MACzB,SAAS,GAAG,KAAK,UAAU,IAAI,CAAC;AAAA,MAChC,QAAQ;AAAA,MACR;AAAA,IAAA,CACD;AAAA,EACH;AACA,MAAI;AACF,WAAO,MAAM,gBAA8B,QAAQ,MAAM;AAAA,MACvD,QAAQ;AAAA,MACR,QAAQ,aAAa,EAAE,OAAO,aAAa;AAAA,MAC3C;AAAA,IAAA,CACD;AAAA,EACH,SAAS,OAAO;AACd,QAAI,iBAAiB,KAAK,KAAK,MAAM,WAAW,KAAK;AACnD,YAAM,IAAI,0BAA0B,MAAM,EAAE,OAAO,OAAO;AAAA,IAC5D;AACA,UAAM;AAAA,EACR;AACF;AAsBO,SAAS,gBACd,MACA,EAAE,OAAO,aAAa,GAAG,QAAA,IAAoC,IACf;AAC9C,QAAM,SAAS,SAAS,OAAO,OAAO,sBAAsB,IAAI;AAChE,SAAO,cAA4B,SAAS,iBAAiB,MAAM,IAAI,MAAM;AAAA,IAC3E,GAAG;AAAA,IACH,QAAQ,aAAa,EAAE,OAAO,aAAa;AAAA,EAAA,CAC5C;AACH;"}