@runwayml/avatars 0.16.0-beta.0

package/README.md

@@ -0,0 +1,103 @@
+# @runwayml/avatars
+
+Framework-agnostic SDK for real-time AI avatar interactions. Works with any JavaScript framework or none at all.
+
+## Quick start
+
+```javascript
+import { streamTo } from '@runwayml/avatars';
+
+// Fetch credentials from your server
+const res = await fetch('/api/avatar/connect', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ avatarId: 'influencer' }),
+});
+const credentials = await res.json();
+
+// Start streaming to a video element
+const session = await streamTo({ credentials, target: document.getElementById('avatar') });
+
+// Control the session
+session.mic.toggle();
+session.end();
+```
+
+## API
+
+### Entry points
+
+- **`streamTo({ credentials, target })`** -- Start a session and stream video to an element. Handles the consume call, LiveKit connection, and media setup. Returns an `AvatarSession`.
+- **`connect({ credentials })`** -- Start a session without a video element (headless). Use `session.streamTo(element)` later to attach video.
+
+### `AvatarSession`
+
+Returned by `streamTo` and `connect`. Provides:
+
+- **`session.state`** -- `'idle' | 'connecting' | 'active' | 'ending' | 'ended' | 'error'`
+- **`session.sessionId`** -- The session identifier
+- **`session.mic`** -- `{ isEnabled, enable(), disable(), toggle() }`
+- **`session.camera`** -- `{ isEnabled, enable(), disable(), toggle() }`
+- **`session.screenShare`** -- `{ isActive, start(), stop(), toggle() }`
+- **`session.end()`** -- End the session
+- **`session.transcript(options?)`** -- Create a transcript accumulator
+- **`session.onClientEvent(tool, handler)`** -- Listen for typed client events
+- **`session.on(event, handler)`** / **`session.off(event, handler)`** -- Event emitter
+
+### Events
+
+```javascript
+import { AvatarEvent } from '@runwayml/avatars';
+
+session.on(AvatarEvent.StateChanged, (state) => {});
+session.on(AvatarEvent.Transcript, (entry) => {});
+session.on(AvatarEvent.ClientEvent, (event) => {});
+session.on(AvatarEvent.Error, (error) => {});
+session.on(AvatarEvent.AvatarVideoReady, (track) => {});
+session.on(AvatarEvent.AvatarAudioReady, (track) => {});
+session.on(AvatarEvent.MediaChanged, () => {});
+```
+
+### Error handling
+
+All errors are instances of `AvatarError` with a typed `code` and optional `cause`:
+
+```javascript
+import { AvatarError } from '@runwayml/avatars';
+
+try {
+  const session = await streamTo({ credentials, target: el });
+} catch (err) {
+  if (err instanceof AvatarError) {
+    console.log(err.code, err.message, err.cause);
+  }
+}
+
+session.on(AvatarEvent.Error, (err) => {
+  if (err instanceof AvatarError && err.code === 'MEDIA_PERMISSION_DENIED') {
+    showPermissionPrompt();
+  }
+});
+```
+
+| Code | When |
+|------|------|
+| `CONSUME_FAILED` | Session consume HTTP request failed |
+| `CONNECTION_FAILED` | LiveKit room connection failed |
+| `MEDIA_PERMISSION_DENIED` | Mic or camera permission denied on connect |
+| `MEDIA_DEVICE_ERROR` | Mic or camera toggle failed |
+| `SCREEN_SHARE_FAILED` | Screen share toggle failed |
+| `PUBLISH_FAILED` | Track publish failed |
+| `UNKNOWN` | Unexpected error |
+
+### Server subpath
+
+```javascript
+import { consumeSession, clientTool, pageActionTools } from '@runwayml/avatars/api';
+```
+
+Server-safe utilities with no browser APIs. Use in Next.js API routes, Express handlers, etc.
+
+## React
+
+For React apps, use [`@runwayml/avatars-react`](../react/) which provides components and hooks on top of this package.

package/dist/api.cjs

@@ -0,0 +1,189 @@
+'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);
+
+// src/tools.ts
+var toolSchemas = /* @__PURE__ */ new WeakMap();
+var asyncSchemaWarned = /* @__PURE__ */ new WeakSet();
+function getClientToolSchema(tool) {
+  return toolSchemas.get(tool);
+}
+function validateClientToolArgs(tool, args) {
+  const schema = toolSchemas.get(tool);
+  if (!schema) {
+    return args;
+  }
+  const result = schema["~standard"].validate(args);
+  if (result instanceof Promise) {
+    if (!asyncSchemaWarned.has(tool) && typeof console !== "undefined") {
+      asyncSchemaWarned.add(tool);
+      console.warn(
+        `[@runwayml/avatars-react] Async Standard Schema validation is not supported for client events (tool "${tool.name}"); subsequent events for this tool will be dropped silently.`
+      );
+    }
+    return null;
+  }
+  return isSuccess(result) ? result.value : null;
+}
+function isSuccess(result) {
+  return result.issues == null;
+}
+function clientTool(name, config) {
+  const tool = {
+    type: "client_event",
+    name,
+    description: config.description
+  };
+  if ("schema" in config) {
+    toolSchemas.set(tool, config.schema);
+  }
+  return tool;
+}
+
+// src/error.ts
+var AvatarError = class extends Error {
+  constructor(code, message, cause) {
+    super(message);
+    __publicField(this, "code");
+    __publicField(this, "cause");
+    this.name = "AvatarError";
+    this.code = code;
+    this.cause = cause;
+  }
+};
+
+// src/api/config.ts
+var DEFAULT_BASE_URL = "https://api.dev.runwayml.com";
+
+// src/api/consume.ts
+async function consumeSession(options) {
+  const { sessionId, sessionKey, baseUrl = DEFAULT_BASE_URL } = options;
+  const url = `${baseUrl}/v1/realtime_sessions/${sessionId}/consume`;
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${sessionKey}`
+    }
+  });
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new AvatarError(
+      "CONSUME_FAILED",
+      `Failed to consume session: ${response.status} ${errorText}`
+    );
+  }
+  return response.json();
+}
+
+// src/api/page-actions.ts
+var clickTool = clientTool("click", {
+  description: "Clicks an interactive element on the page by its target ID",
+  args: {}
+});
+var scrollToTool = clientTool("scroll_to", {
+  description: "Scrolls the page to an element by its target ID",
+  args: {}
+});
+var highlightTool = clientTool("highlight", {
+  description: "Highlights an element on the page to draw attention to it by its target ID",
+  args: {}
+});
+var pageActionTools = [
+  {
+    ...clickTool,
+    parameters: [
+      {
+        name: "target",
+        type: "string",
+        description: "The ID or data-avatar-target value of the element to click"
+      }
+    ]
+  },
+  {
+    ...scrollToTool,
+    parameters: [
+      {
+        name: "target",
+        type: "string",
+        description: "The ID or data-avatar-target value of the element to scroll to"
+      }
+    ]
+  },
+  {
+    ...highlightTool,
+    parameters: [
+      {
+        name: "target",
+        type: "string",
+        description: "The ID or data-avatar-target value of the element to highlight"
+      },
+      {
+        name: "duration",
+        type: "number",
+        description: "How long to highlight in milliseconds. Defaults to 2000"
+      }
+    ]
+  }
+];
+
+// src/api/poll.ts
+var DEFAULT_BASE_URL2 = "https://api.dev.runwayml.com";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_INTERVAL_MS = 1e3;
+var TERMINAL_STATUSES = ["COMPLETED", "FAILED", "CANCELLED"];
+async function pollUntilReady(options) {
+  const {
+    sessionId,
+    apiKey,
+    baseUrl = DEFAULT_BASE_URL2,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    intervalMs = DEFAULT_INTERVAL_MS
+  } = options;
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const url = `${baseUrl}/v1/realtime_sessions/${sessionId}`;
+    const response = await fetch(url, {
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "X-Runway-Version": "2024-11-06"
+      }
+    });
+    if (!response.ok) {
+      const text = await response.text();
+      throw new AvatarError(
+        "CONSUME_FAILED",
+        `Failed to retrieve session: ${response.status} ${text}`
+      );
+    }
+    const session = await response.json();
+    if (session.status === "READY") {
+      if (!session.sessionKey) {
+        throw new AvatarError(
+          "CONSUME_FAILED",
+          "Session is READY but sessionKey is missing"
+        );
+      }
+      return { sessionId, sessionKey: session.sessionKey };
+    }
+    if (TERMINAL_STATUSES.includes(session.status)) {
+      throw new AvatarError(
+        "CONNECTION_FAILED",
+        `Session ${session.status.toLowerCase()} before becoming ready`
+      );
+    }
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+  throw new AvatarError("CONNECTION_FAILED", "Session creation timed out");
+}
+
+exports.clientTool = clientTool;
+exports.consumeSession = consumeSession;
+exports.getClientToolSchema = getClientToolSchema;
+exports.pageActionTools = pageActionTools;
+exports.pollUntilReady = pollUntilReady;
+exports.validateClientToolArgs = validateClientToolArgs;
+//# sourceMappingURL=api.cjs.map
+//# sourceMappingURL=api.cjs.map

package/dist/api.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/tools.ts","../src/error.ts","../src/api/config.ts","../src/api/consume.ts","../src/api/page-actions.ts","../src/api/poll.ts"],"names":["DEFAULT_BASE_URL"],"mappings":"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","file":"api.cjs","sourcesContent":["import type {\n  InferSchemaOutput,\n  StandardSchemaResult,\n  StandardSchemaV1,\n} from './standard-schema';\nimport type { ClientEvent } from './types';\n\n/**\n * A standalone client tool definition. Composable — combine into arrays\n * and derive event types with `ClientEventsFrom`.\n *\n * At runtime this is just `{ type, name, description }` (exactly what the\n * Runway session create payload expects). The `Args` generic is phantom —\n * it only exists at the TypeScript level for type narrowing.\n *\n * When the tool is defined with a `schema` ([Standard Schema](https://standardschema.dev/)),\n * the schema is attached internally (not serialized) for runtime validation\n * and to infer `Args` from the schema output type.\n */\nexport interface ClientToolDef<Name extends string = string, Args = unknown> {\n  readonly type: 'client_event';\n  readonly name: Name;\n  readonly description: string;\n  /** @internal phantom field — always `undefined` at runtime */\n  readonly _args?: Args;\n}\n\nexport type ClientToolArgs<Tool extends ClientToolDef> =\n  Tool extends ClientToolDef<string, infer Args> ? Args : never;\n\nexport type ClientEventFromTool<Tool extends ClientToolDef> =\n  Tool extends ClientToolDef<infer Name, infer Args>\n    ? ClientEvent<Name, Args>\n    : never;\n\n/**\n * Derive a discriminated union of ClientEvent types from an array of tools.\n *\n * @example\n * ```typescript\n * const tools = [showQuestion, playSound];\n * type MyEvent = ClientEventsFrom<typeof tools>;\n * ```\n */\nexport type ClientEventsFrom<T extends ReadonlyArray<ClientToolDef>> =\n  T[number] extends infer U\n    ? U extends ClientToolDef<infer Name, infer Args>\n      ? ClientEvent<Name, Args>\n      : never\n    : never;\n\n// Schemas live in a WeakMap so the tool def itself stays a clean\n// `{ type, name, description }` object — safe to spread into the API\n// payload and JSON.stringify without leaking schema internals.\nconst toolSchemas = new WeakMap<ClientToolDef, StandardSchemaV1>();\n\n// Tracks tools that have already emitted the async-schema warning so a\n// misconfigured schema doesn't spam the console on every incoming event.\nconst asyncSchemaWarned = new WeakSet<ClientToolDef>();\n\n/**\n * Return the Standard Schema associated with a tool, if any.\n * Useful when composing validation outside of the SDK hooks.\n */\nexport function getClientToolSchema(\n  tool: ClientToolDef,\n): StandardSchemaV1 | undefined {\n  return toolSchemas.get(tool);\n}\n\n/**\n * Validate parsed client event args against a tool's schema.\n *\n * Returns the typed args on success, or `null` when the schema fails or\n * when the schema would need to resolve asynchronously (Standard Schema\n * allows async `validate`, but for fire-and-forget client events we only\n * accept sync results here).\n *\n * Tools defined without a schema always validate successfully — the\n * incoming args are returned as-is.\n */\nexport function validateClientToolArgs<Tool extends ClientToolDef>(\n  tool: Tool,\n  args: unknown,\n): ClientToolArgs<Tool> | null {\n  const schema = toolSchemas.get(tool);\n  if (!schema) {\n    return args as ClientToolArgs<Tool>;\n  }\n\n  const result = schema['~standard'].validate(args);\n  if (result instanceof Promise) {\n    if (!asyncSchemaWarned.has(tool) && typeof console !== 'undefined') {\n      asyncSchemaWarned.add(tool);\n      console.warn(\n        `[@runwayml/avatars-react] Async Standard Schema validation is not supported for client events (tool \"${tool.name}\"); subsequent events for this tool will be dropped silently.`,\n      );\n    }\n    return null;\n  }\n\n  return isSuccess(result) ? (result.value as ClientToolArgs<Tool>) : null;\n}\n\nfunction isSuccess<Output>(\n  result: StandardSchemaResult<Output>,\n): result is { readonly value: Output; readonly issues?: undefined } {\n  return result.issues == null;\n}\n\n/**\n * Define a single client tool.\n *\n * Returns a standalone object that can be composed into arrays and passed\n * to `realtimeSessions.create({ tools })`.\n *\n * Two forms are supported:\n *\n * 1. **Schema-driven** (recommended) — pass a\n *    [Standard Schema](https://standardschema.dev/) (Zod, Valibot, ArkType, …)\n *    to infer `args` types and enable runtime validation of incoming events:\n *\n *    ```typescript\n *    import { z } from 'zod';\n *    const showCaption = clientTool('show_caption', {\n *      description: 'Display a caption',\n *      schema: z.object({ text: z.string() }),\n *    });\n *    ```\n *\n * 2. **Type-only** — pass an `args` type via a cast when you don't need\n *    runtime validation:\n *\n *    ```typescript\n *    const showCaption = clientTool('show_caption', {\n *      description: 'Display a caption',\n *      args: {} as { text: string },\n *    });\n *    ```\n *\n * Combine tools and derive event types with `ClientEventsFrom`:\n *\n * ```typescript\n * const tools = [showCaption, playSound];\n * type MyEvent = ClientEventsFrom<typeof tools>;\n * ```\n */\nexport function clientTool<\n  Name extends string,\n  Schema extends StandardSchemaV1,\n>(\n  name: Name,\n  config: { description: string; schema: Schema },\n): ClientToolDef<Name, InferSchemaOutput<Schema>>;\nexport function clientTool<Name extends string, Args>(\n  name: Name,\n  config: { description: string; args: Args },\n): ClientToolDef<Name, Args>;\nexport function clientTool<Name extends string>(\n  name: Name,\n  config:\n    | { description: string; schema: StandardSchemaV1 }\n    | { description: string; args: unknown },\n): ClientToolDef<Name> {\n  const tool: ClientToolDef<Name> = {\n    type: 'client_event',\n    name,\n    description: config.description,\n  };\n\n  if ('schema' in config) {\n    toolSchemas.set(tool, config.schema);\n  }\n\n  return tool;\n}\n","export type AvatarErrorCode =\n  | 'CONSUME_FAILED'\n  | 'CONNECTION_FAILED'\n  | 'MEDIA_PERMISSION_DENIED'\n  | 'MEDIA_DEVICE_ERROR'\n  | 'SCREEN_SHARE_FAILED'\n  | 'PUBLISH_FAILED'\n  | 'UNKNOWN';\n\nexport class AvatarError extends Error {\n  readonly code: AvatarErrorCode;\n  readonly cause?: Error;\n\n  constructor(code: AvatarErrorCode, message: string, cause?: Error) {\n    super(message);\n    this.name = 'AvatarError';\n    this.code = code;\n    this.cause = cause;\n  }\n}\n\nexport function toAvatarError(\n  code: AvatarErrorCode,\n  fallbackMessage: string,\n  err: unknown,\n): AvatarError {\n  if (err instanceof AvatarError) return err;\n  const cause = err instanceof Error ? err : undefined;\n  const message = cause?.message ?? fallbackMessage;\n  return new AvatarError(code, message, cause);\n}\n","export const DEFAULT_BASE_URL = 'https://api.dev.runwayml.com';\n","import { AvatarError } from '../error';\nimport type { ConsumeSessionOptions, ConsumeSessionResponse } from '../types';\nimport { DEFAULT_BASE_URL } from './config';\n\nexport async function consumeSession(\n  options: ConsumeSessionOptions,\n): Promise<ConsumeSessionResponse> {\n  const { sessionId, sessionKey, baseUrl = DEFAULT_BASE_URL } = options;\n\n  const url = `${baseUrl}/v1/realtime_sessions/${sessionId}/consume`;\n  const response = await fetch(url, {\n    method: 'POST',\n    headers: {\n      'Content-Type': 'application/json',\n      Authorization: `Bearer ${sessionKey}`,\n    },\n  });\n\n  if (!response.ok) {\n    const errorText = await response.text();\n    throw new AvatarError(\n      'CONSUME_FAILED',\n      `Failed to consume session: ${response.status} ${errorText}`,\n    );\n  }\n\n  return response.json();\n}\n","import { clientTool, type ClientEventsFrom } from '../tools';\n\nexport const clickTool = clientTool('click', {\n  description: 'Clicks an interactive element on the page by its target ID',\n  args: {} as { target: string },\n});\n\nexport const scrollToTool = clientTool('scroll_to', {\n  description: 'Scrolls the page to an element by its target ID',\n  args: {} as { target: string },\n});\n\nexport const highlightTool = clientTool('highlight', {\n  description:\n    'Highlights an element on the page to draw attention to it by its target ID',\n  args: {} as { target: string; duration?: number },\n});\n\nconst toolDefs = [clickTool, scrollToTool, highlightTool] as const;\n\nexport type PageActionEvent = ClientEventsFrom<typeof toolDefs>;\n\n/**\n * Pre-built tool definitions with `parameters` arrays, ready to spread\n * into `realtimeSessions.create({ tools })`.\n *\n * @example\n * ```ts\n * import { pageActionTools } from '@runwayml/avatars-react/api';\n *\n * await client.realtimeSessions.create({\n *   model: 'gwm1_avatars',\n *   avatar: { type: 'runway-preset', presetId: 'music-superstar' },\n *   tools: [...pageActionTools, ...myCustomTools],\n * });\n * ```\n */\nexport const pageActionTools = [\n  {\n    ...clickTool,\n    parameters: [\n      {\n        name: 'target',\n        type: 'string',\n        description:\n          'The ID or data-avatar-target value of the element to click',\n      },\n    ],\n  },\n  {\n    ...scrollToTool,\n    parameters: [\n      {\n        name: 'target',\n        type: 'string',\n        description:\n          'The ID or data-avatar-target value of the element to scroll to',\n      },\n    ],\n  },\n  {\n    ...highlightTool,\n    parameters: [\n      {\n        name: 'target',\n        type: 'string',\n        description:\n          'The ID or data-avatar-target value of the element to highlight',\n      },\n      {\n        name: 'duration',\n        type: 'number',\n        description: 'How long to highlight in milliseconds. Defaults to 2000',\n      },\n    ],\n  },\n];\n","import { AvatarError } from '../error';\n\nexport interface PollUntilReadyOptions {\n  sessionId: string;\n  apiKey: string;\n  baseUrl?: string;\n  timeoutMs?: number;\n  intervalMs?: number;\n}\n\ninterface SessionResponse {\n  id: string;\n  status: string;\n  sessionKey?: string;\n  [key: string]: unknown;\n}\n\nconst DEFAULT_BASE_URL = 'https://api.dev.runwayml.com';\nconst DEFAULT_TIMEOUT_MS = 30_000;\nconst DEFAULT_INTERVAL_MS = 1_000;\nconst TERMINAL_STATUSES = ['COMPLETED', 'FAILED', 'CANCELLED'];\n\n/**\n * Poll a realtime session until it reaches READY status.\n *\n * Returns `{ sessionId, sessionKey }` — ready to pass to `streamTo` or `connect`.\n *\n * This is a server-side utility (requires your API key). Use it in\n * Next.js API routes, Express handlers, etc.\n *\n * @example\n * ```ts\n * import Runway from '@runwayml/sdk';\n * import { pollUntilReady } from '@runwayml/avatars/api';\n *\n * const runway = new Runway();\n * const { id: sessionId } = await runway.realtimeSessions.create({ ... });\n * const { sessionKey } = await pollUntilReady({ sessionId, apiKey: process.env.RUNWAYML_API_SECRET });\n *\n * return Response.json({ sessionId, sessionKey });\n * ```\n */\nexport async function pollUntilReady(\n  options: PollUntilReadyOptions,\n): Promise<{ sessionId: string; sessionKey: string }> {\n  const {\n    sessionId,\n    apiKey,\n    baseUrl = DEFAULT_BASE_URL,\n    timeoutMs = DEFAULT_TIMEOUT_MS,\n    intervalMs = DEFAULT_INTERVAL_MS,\n  } = options;\n\n  const deadline = Date.now() + timeoutMs;\n\n  while (Date.now() < deadline) {\n    const url = `${baseUrl}/v1/realtime_sessions/${sessionId}`;\n    const response = await fetch(url, {\n      headers: {\n        Authorization: `Bearer ${apiKey}`,\n        'X-Runway-Version': '2024-11-06',\n      },\n    });\n\n    if (!response.ok) {\n      const text = await response.text();\n      throw new AvatarError(\n        'CONSUME_FAILED',\n        `Failed to retrieve session: ${response.status} ${text}`,\n      );\n    }\n\n    const session: SessionResponse = await response.json();\n\n    if (session.status === 'READY') {\n      if (!session.sessionKey) {\n        throw new AvatarError(\n          'CONSUME_FAILED',\n          'Session is READY but sessionKey is missing',\n        );\n      }\n      return { sessionId, sessionKey: session.sessionKey };\n    }\n\n    if (TERMINAL_STATUSES.includes(session.status)) {\n      throw new AvatarError(\n        'CONNECTION_FAILED',\n        `Session ${session.status.toLowerCase()} before becoming ready`,\n      );\n    }\n\n    await new Promise((resolve) => setTimeout(resolve, intervalMs));\n  }\n\n  throw new AvatarError('CONNECTION_FAILED', 'Session creation timed out');\n}\n"]}

package/dist/api.d.cts

@@ -0,0 +1,247 @@
+/**
+ * Standard Schema v1 — a tiny cross-library validation interface implemented
+ * by Zod, Valibot, ArkType, and others. Anything matching this shape plugs
+ * into `clientTool({ schema })`.
+ *
+ * @see https://standardschema.dev/
+ *
+ * We re-declare the spec here (instead of depending on `@standard-schema/spec`)
+ * so the SDK stays dependency-free and server-safe.
+ */
+/** The schema itself — what a `z.object(...)` etc. resolves to. */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly '~standard': {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        };
+    };
+}
+/** Result of calling `schema['~standard'].validate(value)`. */
+type StandardSchemaResult<Output> = {
+    readonly value: Output;
+    readonly issues?: undefined;
+} | {
+    readonly issues: ReadonlyArray<StandardSchemaIssue>;
+};
+/** A single validation failure — part of the error path. */
+interface StandardSchemaIssue {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PropertyKey | {
+        readonly key: PropertyKey;
+    }>;
+}
+type InferSchemaInput<Schema extends StandardSchemaV1> = Schema extends StandardSchemaV1<infer Input, unknown> ? Input : never;
+type InferSchemaOutput<Schema extends StandardSchemaV1> = Schema extends StandardSchemaV1<unknown, infer Output> ? Output : never;
+
+interface ConsumeSessionResponse {
+    url: string;
+    token: string;
+    roomName: string;
+}
+interface ConsumeSessionOptions {
+    sessionId: string;
+    sessionKey: string;
+    baseUrl?: string;
+}
+interface ClientEvent<T extends string = string, A = Record<string, unknown>> {
+    type: 'client_event';
+    tool: T;
+    args: A;
+}
+
+/**
+ * A standalone client tool definition. Composable — combine into arrays
+ * and derive event types with `ClientEventsFrom`.
+ *
+ * At runtime this is just `{ type, name, description }` (exactly what the
+ * Runway session create payload expects). The `Args` generic is phantom —
+ * it only exists at the TypeScript level for type narrowing.
+ *
+ * When the tool is defined with a `schema` ([Standard Schema](https://standardschema.dev/)),
+ * the schema is attached internally (not serialized) for runtime validation
+ * and to infer `Args` from the schema output type.
+ */
+interface ClientToolDef<Name extends string = string, Args = unknown> {
+    readonly type: 'client_event';
+    readonly name: Name;
+    readonly description: string;
+    /** @internal phantom field — always `undefined` at runtime */
+    readonly _args?: Args;
+}
+type ClientToolArgs<Tool extends ClientToolDef> = Tool extends ClientToolDef<string, infer Args> ? Args : never;
+type ClientEventFromTool<Tool extends ClientToolDef> = Tool extends ClientToolDef<infer Name, infer Args> ? ClientEvent<Name, Args> : never;
+/**
+ * Derive a discriminated union of ClientEvent types from an array of tools.
+ *
+ * @example
+ * ```typescript
+ * const tools = [showQuestion, playSound];
+ * type MyEvent = ClientEventsFrom<typeof tools>;
+ * ```
+ */
+type ClientEventsFrom<T extends ReadonlyArray<ClientToolDef>> = T[number] extends infer U ? U extends ClientToolDef<infer Name, infer Args> ? ClientEvent<Name, Args> : never : never;
+/**
+ * Return the Standard Schema associated with a tool, if any.
+ * Useful when composing validation outside of the SDK hooks.
+ */
+declare function getClientToolSchema(tool: ClientToolDef): StandardSchemaV1 | undefined;
+/**
+ * Validate parsed client event args against a tool's schema.
+ *
+ * Returns the typed args on success, or `null` when the schema fails or
+ * when the schema would need to resolve asynchronously (Standard Schema
+ * allows async `validate`, but for fire-and-forget client events we only
+ * accept sync results here).
+ *
+ * Tools defined without a schema always validate successfully — the
+ * incoming args are returned as-is.
+ */
+declare function validateClientToolArgs<Tool extends ClientToolDef>(tool: Tool, args: unknown): ClientToolArgs<Tool> | null;
+/**
+ * Define a single client tool.
+ *
+ * Returns a standalone object that can be composed into arrays and passed
+ * to `realtimeSessions.create({ tools })`.
+ *
+ * Two forms are supported:
+ *
+ * 1. **Schema-driven** (recommended) — pass a
+ *    [Standard Schema](https://standardschema.dev/) (Zod, Valibot, ArkType, …)
+ *    to infer `args` types and enable runtime validation of incoming events:
+ *
+ *    ```typescript
+ *    import { z } from 'zod';
+ *    const showCaption = clientTool('show_caption', {
+ *      description: 'Display a caption',
+ *      schema: z.object({ text: z.string() }),
+ *    });
+ *    ```
+ *
+ * 2. **Type-only** — pass an `args` type via a cast when you don't need
+ *    runtime validation:
+ *
+ *    ```typescript
+ *    const showCaption = clientTool('show_caption', {
+ *      description: 'Display a caption',
+ *      args: {} as { text: string },
+ *    });
+ *    ```
+ *
+ * Combine tools and derive event types with `ClientEventsFrom`:
+ *
+ * ```typescript
+ * const tools = [showCaption, playSound];
+ * type MyEvent = ClientEventsFrom<typeof tools>;
+ * ```
+ */
+declare function clientTool<Name extends string, Schema extends StandardSchemaV1>(name: Name, config: {
+    description: string;
+    schema: Schema;
+}): ClientToolDef<Name, InferSchemaOutput<Schema>>;
+declare function clientTool<Name extends string, Args>(name: Name, config: {
+    description: string;
+    args: Args;
+}): ClientToolDef<Name, Args>;
+
+declare function consumeSession(options: ConsumeSessionOptions): Promise<ConsumeSessionResponse>;
+
+declare const toolDefs: readonly [ClientToolDef<"click", {
+    target: string;
+}>, ClientToolDef<"scroll_to", {
+    target: string;
+}>, ClientToolDef<"highlight", {
+    target: string;
+    duration?: number;
+}>];
+type PageActionEvent = ClientEventsFrom<typeof toolDefs>;
+/**
+ * Pre-built tool definitions with `parameters` arrays, ready to spread
+ * into `realtimeSessions.create({ tools })`.
+ *
+ * @example
+ * ```ts
+ * import { pageActionTools } from '@runwayml/avatars-react/api';
+ *
+ * await client.realtimeSessions.create({
+ *   model: 'gwm1_avatars',
+ *   avatar: { type: 'runway-preset', presetId: 'music-superstar' },
+ *   tools: [...pageActionTools, ...myCustomTools],
+ * });
+ * ```
+ */
+declare const pageActionTools: ({
+    parameters: {
+        name: string;
+        type: string;
+        description: string;
+    }[];
+    type: "client_event";
+    name: "click";
+    description: string;
+    _args?: {
+        target: string;
+    } | undefined;
+} | {
+    parameters: {
+        name: string;
+        type: string;
+        description: string;
+    }[];
+    type: "client_event";
+    name: "scroll_to";
+    description: string;
+    _args?: {
+        target: string;
+    } | undefined;
+} | {
+    parameters: {
+        name: string;
+        type: string;
+        description: string;
+    }[];
+    type: "client_event";
+    name: "highlight";
+    description: string;
+    _args?: {
+        target: string;
+        duration?: number;
+    } | undefined;
+})[];
+
+interface PollUntilReadyOptions {
+    sessionId: string;
+    apiKey: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    intervalMs?: number;
+}
+/**
+ * Poll a realtime session until it reaches READY status.
+ *
+ * Returns `{ sessionId, sessionKey }` — ready to pass to `streamTo` or `connect`.
+ *
+ * This is a server-side utility (requires your API key). Use it in
+ * Next.js API routes, Express handlers, etc.
+ *
+ * @example
+ * ```ts
+ * import Runway from '@runwayml/sdk';
+ * import { pollUntilReady } from '@runwayml/avatars/api';
+ *
+ * const runway = new Runway();
+ * const { id: sessionId } = await runway.realtimeSessions.create({ ... });
+ * const { sessionKey } = await pollUntilReady({ sessionId, apiKey: process.env.RUNWAYML_API_SECRET });
+ *
+ * return Response.json({ sessionId, sessionKey });
+ * ```
+ */
+declare function pollUntilReady(options: PollUntilReadyOptions): Promise<{
+    sessionId: string;
+    sessionKey: string;
+}>;
+
+export { type ClientEvent, type ClientEventFromTool, type ClientEventsFrom, type ClientToolArgs, type ClientToolDef, type ConsumeSessionOptions, type ConsumeSessionResponse, type InferSchemaInput, type InferSchemaOutput, type PageActionEvent, type PollUntilReadyOptions, type StandardSchemaIssue, type StandardSchemaResult, type StandardSchemaV1, clientTool, consumeSession, getClientToolSchema, pageActionTools, pollUntilReady, validateClientToolArgs };