stream-chat-react-native-core 9.12.1 → 9.14.0

package/src/ai-components/message-parts/parseMessageParts.ts

@@ -0,0 +1,195 @@
+import type {
+  AIMessagePartData,
+  AIReasoningPart,
+  AIToolApprovalData,
+  AIToolAuthorizationData,
+  AIToolCallPart,
+  AIToolCallStatus,
+} from './types';
+
+/** The attachment type prefix every AI step uses. */
+export const AI_MESSAGE_PART_TYPE_PREFIX = 'ai_';
+/** The newest format version of the built-in kinds this SDK understands. */
+export const AI_MESSAGE_PART_SUPPORTED_VERSION = 1;
+
+type JSONObject = Record<string, unknown>;
+
+// Lenient reads: a field of the wrong type reads as missing, and an empty string as absent.
+const isObject = (value: unknown): value is JSONObject =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const string = (object: JSONObject, key: string) => {
+  const value = object[key];
+  return typeof value === 'string' && value !== '' ? value : undefined;
+};
+
+const int = (object: JSONObject, key: string) => {
+  const value = object[key];
+  return typeof value === 'number' && Number.isFinite(value) ? Math.trunc(value) : undefined;
+};
+
+const date = (object: JSONObject, key: string) => {
+  const value = string(object, key);
+  if (value === undefined) return undefined;
+  const time = Date.parse(value);
+  return Number.isNaN(time) ? undefined : time;
+};
+
+const parseApproval = (object: JSONObject): AIToolApprovalData | undefined => {
+  // A question with no title asks nothing.
+  const title = string(object, 'title');
+  if (!title) return undefined;
+  return {
+    allowTitle: string(object, 'allow_title'),
+    decision: string(object, 'decision'),
+    declineTitle: string(object, 'decline_title'),
+    message: string(object, 'message'),
+    reason: string(object, 'reason'),
+    title,
+  };
+};
+
+// An http(s) URL with a host. Matched rather than read through `URL`, whose `protocol` and
+// `host` throw "not implemented" on React Native before 0.80.
+const WEB_URL = /^https?:\/\/[^\s/?#@]+(?:@[^\s/?#@]+)?(?:[/?#]|$)/i;
+
+const isWebURL = (value: string) => WEB_URL.test(value);
+
+const parseAuthorization = (object: JSONObject): AIToolAuthorizationData | undefined => {
+  // A sign-in with no title, or no web page to open, asks nothing.
+  const title = string(object, 'title');
+  const url = string(object, 'url');
+  if (!title || !url || !isWebURL(url)) return undefined;
+  return {
+    expiresAt: date(object, 'expires_at'),
+    handoffToken: string(object, 'handoff_token'),
+    message: string(object, 'message'),
+    provider: string(object, 'provider') ?? '',
+    providerName: string(object, 'provider_name'),
+    status: string(object, 'status'),
+    title,
+    type: string(object, 'type') ?? 'oauth',
+    url,
+  };
+};
+
+const parseReasoning = (id: string, object: JSONObject): AIReasoningPart => ({
+  durationMs: int(object, 'duration_ms'),
+  id,
+  preview: string(object, 'preview'),
+  status: string(object, 'status') ?? 'completed',
+  summary: string(object, 'summary'),
+});
+
+const parseToolCall = (id: string, object: JSONObject): AIToolCallPart => {
+  const approval = object.approval;
+  const authorization = object.authorization;
+  const args = object.arguments;
+  return {
+    approval: isObject(approval) ? parseApproval(approval) : undefined,
+    arguments: args === null ? undefined : args,
+    authorization: isObject(authorization) ? parseAuthorization(authorization) : undefined,
+    displayTitle: string(object, 'display_title'),
+    durationMs: int(object, 'duration_ms'),
+    executor: string(object, 'executor') ?? 'server',
+    id,
+    name: string(object, 'name') ?? '',
+    status: string(object, 'status') ?? 'running',
+    summary: string(object, 'summary'),
+    targetClientId: string(object, 'target_client_id'),
+    targetUserId: string(object, 'target_user_id'),
+  };
+};
+
+/**
+ * Decodes one attachment, or returns `undefined` when it is not an AI step.
+ *
+ * @param attachment The attachment, as it is on the message (with its `type`).
+ * @param position The attachment's index, used as the identity of a step with no ID of its own.
+ */
+export const parseMessagePart = (
+  attachment: unknown,
+  position = 0,
+): AIMessagePartData | undefined => {
+  if (!isObject(attachment)) return undefined;
+  const type = attachment.type;
+  if (typeof type !== 'string' || !type.startsWith(AI_MESSAGE_PART_TYPE_PREFIX)) {
+    return undefined;
+  }
+  const id = string(attachment, 'id') ?? `${type}-${position}`;
+  const version = int(attachment, 'v') ?? 1;
+  const known = version <= AI_MESSAGE_PART_SUPPORTED_VERSION;
+  return {
+    id,
+    kind: type,
+    payload: attachment,
+    reasoning: known && type === 'ai_reasoning' ? parseReasoning(id, attachment) : undefined,
+    toolCall: known && type === 'ai_tool_call' ? parseToolCall(id, attachment) : undefined,
+    version,
+  };
+};
+
+/**
+ * Decodes the AI steps among a message's attachments, in order. Attachments that are not AI
+ * steps (images, files and so on) are skipped. Decoding is lenient: missing fields get
+ * defaults, and a step newer than this SDK understands keeps its payload but has no typed
+ * view.
+ *
+ * ```ts
+ * const parts = parseMessageParts(message.attachments);
+ * ```
+ */
+export const parseMessageParts = (attachments: readonly unknown[] | null | undefined) =>
+  (attachments ?? []).reduce<AIMessagePartData[]>((parts, attachment, position) => {
+    const part = parseMessagePart(attachment, position);
+    if (part) parts.push(part);
+    return parts;
+  }, []);
+
+/** Whether this SDK has a typed view of the step. */
+export const isSupportedPart = (part: AIMessagePartData) =>
+  part.reasoning !== undefined || part.toolCall !== undefined;
+
+/** Whether the call has finished, one way or another. */
+export const isToolCallFinished = (status: AIToolCallStatus) =>
+  status === 'completed' || status === 'failed' || status === 'cancelled';
+
+/**
+ * Whether the person declined the call, or the sign-in it waited for, so it never ran.
+ */
+export const isDeclined = (call: AIToolCallPart) =>
+  call.approval?.decision === 'declined' || call.authorization?.status === 'declined';
+
+/**
+ * Whether this call is waiting for this device: a client tool, still awaiting its result,
+ * targeted at this person and this install.
+ */
+export const isAwaitingClient = (call: AIToolCallPart, userId: string, clientId: string) =>
+  call.executor === 'client' &&
+  call.status === 'awaiting_client' &&
+  call.targetUserId === userId &&
+  call.targetClientId === clientId;
+
+/**
+ * Whether this call is waiting for this person to allow it, on this device: still awaiting
+ * approval, targeted at this person, and at this install when it names one (a client tool
+ * does; a server tool's question may be answered from any of their devices).
+ */
+export const isAwaitingApproval = (call: AIToolCallPart, userId: string, clientId: string) =>
+  call.status === 'awaiting_approval' &&
+  call.approval !== undefined &&
+  call.targetUserId === userId &&
+  (call.targetClientId === undefined || call.targetClientId === clientId);
+
+/** Whether this call is waiting for this person to sign in, from any of their devices. */
+export const isAwaitingAuthorization = (call: AIToolCallPart, userId: string) =>
+  call.status === 'awaiting_authorization' &&
+  call.authorization !== undefined &&
+  call.targetUserId === userId;
+
+/** Whether a sign-in that is still asked for has passed its `expiresAt`. */
+export const isAuthorizationExpired = (authorization: AIToolAuthorizationData, now = Date.now()) =>
+  authorization.status === 'expired' ||
+  (authorization.status === undefined &&
+    authorization.expiresAt !== undefined &&
+    authorization.expiresAt <= now);

package/src/ai-components/message-parts/types.ts

@@ -0,0 +1,157 @@
+/**
+ * The steps an AI agent took while replying, such as a round of reasoning or a tool call.
+ *
+ * The agent writes each step as a custom attachment on its reply (`ai_reasoning`,
+ * `ai_tool_call`), and the order of the attachments is the order of the steps. The final
+ * answer stays in the message text and is shown after them.
+ *
+ * The kinds, statuses and decisions are open sets: compare against the values you know and
+ * give the rest a fallback. A step newer than this SDK understands keeps its payload but has
+ * no typed view.
+ */
+
+// Keeps autocompletion for the known values while accepting any string.
+type Open<T extends string> = T | (string & {});
+
+export type AIMessagePartKind = Open<'ai_reasoning' | 'ai_tool_call'>;
+
+/** Where a round of reasoning is. Defaults to `completed` when the agent sends none. */
+export type AIReasoningStatus = Open<'streaming' | 'completed'>;
+
+/** A round of the model's reasoning (`ai_reasoning`). */
+export type AIReasoningPart = {
+  id: string;
+  status: AIReasoningStatus;
+  /** How long the model thought, in milliseconds. */
+  durationMs?: number;
+  /**
+   * A capped excerpt: the latest thoughts while streaming, the opening once done. The full
+   * reasoning, when an app has it, arrives separately.
+   */
+  preview?: string;
+  /** A one-line summary of the reasoning, once it is done. */
+  summary?: string;
+};
+
+/**
+ * Where a tool call is. Treat a status this SDK doesn't know as still in progress.
+ *
+ * - `running`: the agent's backend or a device is running it.
+ * - `awaiting_client`: waiting for the targeted device to run the tool and send its result.
+ * - `awaiting_approval`: waiting for the targeted person to allow or decline it.
+ * - `awaiting_authorization`: waiting for the targeted person to sign in at a provider.
+ * - `completed`, `failed`, `cancelled`: finished, one way or another.
+ */
+export type AIToolCallStatus = Open<
+  | 'running'
+  | 'awaiting_client'
+  | 'awaiting_approval'
+  | 'awaiting_authorization'
+  | 'completed'
+  | 'failed'
+  | 'cancelled'
+>;
+
+/** Who runs a tool: the agent's backend (`server`) or a person's device (`client`). */
+export type AIToolExecutor = Open<'server' | 'client'>;
+
+export type AIToolApprovalDecision = Open<'allowed' | 'declined'>;
+
+/**
+ * What a tool call asks the person it waits for before it runs, such as "Share your
+ * location?", and how they answered. Allowed, the call goes on; declined, it is cancelled
+ * and never runs.
+ */
+export type AIToolApprovalData = {
+  /** The question, such as "Share your location?". */
+  title: string;
+  /** The label of the button that allows the call. Defaults to "Allow" when the agent sends none. */
+  allowTitle?: string;
+  /** How the person answered, once they did. */
+  decision?: AIToolApprovalDecision;
+  /** The label of the button that declines the call. Defaults to "Don't Allow". */
+  declineTitle?: string;
+  /** What allowing it shares or does, such as "Only your city is shared." */
+  message?: string;
+  /** The agent's own words for why it wants the call, such as "to check the local weather". */
+  reason?: string;
+};
+
+/** How a person signs in: `oauth` is a consent at the provider, in a browser. */
+export type AIToolAuthorizationType = Open<'oauth'>;
+
+/**
+ * How a sign-in ended. `failed` is one the provider or the agent's backend ended without
+ * connecting, such as when the person came back as another account.
+ */
+export type AIToolAuthorizationStatus = Open<'connected' | 'declined' | 'expired' | 'failed'>;
+
+/**
+ * A sign-in a tool call waits for, such as "Connect Linear", and how it ended. It holds no
+ * credential: `url` is the agent's own sign-in page, and the provider hands what it grants to
+ * the agent's backend, never to the app.
+ */
+export type AIToolAuthorizationData = {
+  /** The provider, such as `linear`. */
+  provider: string;
+  /** The question, such as "Connect Linear". */
+  title: string;
+  type: AIToolAuthorizationType;
+  /** The sign-in page to open (the router's launch page). An `http(s)` URL. */
+  url: string;
+  /** When the sign-in ends, in milliseconds since the epoch. */
+  expiresAt?: number;
+  /**
+   * What binds the sign-in to the first browser that opens it. The launch page reads it from its
+   * URL's fragment. Gone once the sign-in is over.
+   */
+  handoffToken?: string;
+  /** What signing in means for the person. */
+  message?: string;
+  /** What people call the provider, such as "Linear". */
+  providerName?: string;
+  /** How it ended, once it did. */
+  status?: AIToolAuthorizationStatus;
+};
+
+/** A tool the agent called, run by the agent's backend or by a person's device. */
+export type AIToolCallPart = {
+  /** The model provider's tool-call ID. A device's result is matched against it. */
+  id: string;
+  name: string;
+  /** Defaults to `server` when the agent sends none. */
+  executor: AIToolExecutor;
+  /** Defaults to `running` when the agent sends none. */
+  status: AIToolCallStatus;
+  /** What the call asks the person it waits for, and how they answered, when its tool asks first. */
+  approval?: AIToolApprovalData;
+  /** The call's arguments, present for client tools, which need them to run. */
+  arguments?: unknown;
+  /** The sign-in the call waits for, and how it ended, when it needs the person's account at a provider. */
+  authorization?: AIToolAuthorizationData;
+  /** What the call is doing, in words for people, such as "Checking your location". */
+  displayTitle?: string;
+  durationMs?: number;
+  /** A short, shareable outcome, such as "Found your location". */
+  summary?: string;
+  /** The install that must run a client tool. */
+  targetClientId?: string;
+  /** The person the call waits for. */
+  targetUserId?: string;
+};
+
+/** One step of a reply, decoded from one `ai_*` attachment. */
+export type AIMessagePartData = {
+  /** The step's stable identity, for keys and animation. Tool calls use the provider's tool-call ID. */
+  id: string;
+  /** The attachment type, such as `ai_reasoning`. */
+  kind: AIMessagePartKind;
+  /** The attachment as it came, for kinds of your own or fields this SDK does not read. */
+  payload: Record<string, unknown>;
+  /** The step's format version (`v`). It changes only when a kind changes incompatibly. */
+  version: number;
+  /** The step as a round of reasoning, when it is one this SDK can read. */
+  reasoning?: AIReasoningPart;
+  /** The step as a tool call, when it is one this SDK can read. */
+  toolCall?: AIToolCallPart;
+};

package/src/ai-components/native-specs/NativeAIAgent.ts

@@ -0,0 +1,25 @@
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+/**
+ * Codegen spec of the native module behind the agent components: this install's identifier and
+ * the sign-ins of tool calls.
+ *
+ * This file is duplicated (byte for byte) in `package/native-package/src/native/NativeAIAgent.ts`
+ * and `package/expo-package/src/native/NativeAIAgent.ts`, which are the copies codegen reads.
+ * `yarn validate-entry-isolation` fails if they drift apart.
+ */
+export interface Spec extends TurboModule {
+  /** This install's identifier, created on first use and kept in storage that isn't backed up. */
+  installId(): string;
+  /**
+   * Opens `url` in the platform's web authentication session and resolves with the URL the page
+   * handed back to `callbackScheme`, or an empty string when the person closed it. Rejects when
+   * the session couldn't be opened.
+   */
+  openAuthSession(url: string, callbackScheme: string): Promise<string>;
+}
+
+// `get` rather than `getEnforcing`, so importing the AI entry point never throws in an app built
+// without the module, such as one on an older version of the SDK's native code.
+export default TurboModuleRegistry.get<Spec>('AIAgent');