@d-id/client-sdk 3.0.0-staging.415 → 3.0.0-staging.417

package/README.md

@@ -1,148 +1,75 @@
 # D-ID Client SDK
 
-**Version 3.0 is a breaking release.** Upgrading from 2.x? Read the [migration guide](https://sdk.d-id.com/documents/Migration_guide.html).
+[![npm version](https://img.shields.io/npm/v/@d-id/client-sdk)](https://www.npmjs.com/package/@d-id/client-sdk)
+[![license](https://img.shields.io/npm/l/@d-id/client-sdk)](https://github.com/de-id/agents-sdk/blob/main/LICENSE)
+[![docs coverage](https://sdk.d-id.com/coverage.svg)](https://sdk.d-id.com/)
 
-<div style="display: flex; flex-direction: row; align-items: center; justify-content: space-evenly; min-height: 1px; font-size: 16px;">
-  <img style="width: auto; height: 200px; object-fit: contain;" src="https://create-images-results.d-id.com/api_docs/assets/agents_sdk_cover_v2.png" alt="Agents SDK Cover" />
-  <span style="width: 67%; text-align: justify;">
-    <br> This guide covers installing the SDK, connecting to an agent and where to find the full API reference.
-  </span>
-</div>
+![D-ID Agents SDK](https://create-images-results.d-id.com/api_docs/assets/agents_sdk_cover_v2.png)
 
-## Introduction
-
-The D-ID Agents SDK embeds your created Agents or real-time streaming avatars into web applications.
-
-It wraps the D-ID Agents and Streams APIs.
-
-The SDK supports three avatar types:
-
-- **Talks (V2)** — Photo-based presenters using WebRTC streaming.
-- **Clips (V3)** — Pre-built presenter avatars using WebRTC streaming.
-- **Expressive (V4)** — Next-generation avatars using LiveKit-based streaming, supporting microphone input and always-on fluent mode.
+The D-ID Agents SDK embeds an agent you built in D-ID Studio — or a real-time streaming avatar — into a web application. It wraps the D-ID Agents and Streams APIs behind one object: create an `AgentManager` for an agent, `connect()`, then `chat()` to have the agent answer with its own LLM or `speak()` to have it say exactly what you give it. The SDK handles the WebRTC or LiveKit session, the chat transcript and the reconnects.
 
 **Please note:** This SDK is designed for front-end development only. The creation of Agents and Knowledge bases should be handled through the [Agents API](https://docs.d-id.com/docs/agent-quickstart) or directly within the [D-ID Studio](https://studio.d-id.com/agents).
 
-> 📚 **Full API reference:** [sdk.d-id.com](https://sdk.d-id.com/) — every method, callback, option and type, generated from the source on each release. ![Docs coverage](https://sdk.d-id.com/coverage.svg)
-
-## Getting Started
+> **Version 3.0 is a breaking release.** Upgrading from 2.x? Read the [migration guide](https://sdk.d-id.com/documents/Migration_guide.html).
 
-### Prerequisites
-
-Follow these steps:
-
-1. Log in to the [D-ID Studio](https://studio.d-id.com)
-2. Create a new Agent with the required options - Image, voice, etc.
-3. In the [Agents gallery](https://studio.d-id.com/agents), hover with your mouse over the created Agent, then click on the `[...]` button
-4. Click on `</> Embed` button
-5. Set the list of allowed domains for your Agent, for example: `http://localhost`
-   This is an additional security measurement: your Agent can be accessed only from the domains allowed by you.
-6. In the code snippet section, fetch the `data-client-key` and the `data-agent-id`, these will be used later to access your Agent.
-
-### Installation
-
-In your front-end application folder, install the Agents SDK library using `npm`.
+## Install
 
 ```shell
 npm i @d-id/client-sdk
 ```
 
-Alternatively, you can clone the SDK from its [GitHub repository](https://github.com/de-id/agents-sdk).
+You need an agent id and a client key. Both come from the agent's `</> Embed` snippet in the [D-ID Studio agents gallery](https://studio.d-id.com/agents), which is also where you list the domains the agent may be used from — see [Getting started](https://sdk.d-id.com/documents/Getting_started.html).
 
-### Initialization
+## Quick start
 
-In your front-end application,
-
-1. Import the Agents SDK library
-2. Paste the `data-agent-id` obtained in the prerequisites step in the `agentId` variable
-3. Paste the `data-client-key` obtained in the prerequisites step in the `auth.clientKey` variable
-4. Define an object called `callbacks`. `onSrcObjectReady` is mandatory: it hands you the media stream to render, so without it the agent has nowhere to play.
-   See [`AgentManagerCallbacks`](https://sdk.d-id.com/interfaces/AgentManagerCallbacks.html) in the API reference.
-5. Define an object called `streamOptions` [optional — Talks (V2) and Clips (V3) agents only]
-   See [`StreamOptions`](https://sdk.d-id.com/interfaces/StreamOptions.html) in the API reference.
-6. Create an instance of the `createAgentManager` object called `agentManager` with the values created above.
-   See [`AgentManager`](https://sdk.d-id.com/interfaces/AgentManager.html) in the API reference.
-7. Open the session with `connect()`, and wait for it to resolve before speaking to the agent.
-8. Make the agent talk: `speak()` says exactly what you give it, `chat()` has the agent answer with its own LLM.
-
-Example:
-
-```javascript
-// 1. Import the Agents SDK library
+```ts
 import * as sdk from '@d-id/client-sdk';
 
-// 2. Paste the `data-agent-id' in the 'agentId' variable
-let agentId = 'agt_fumf1234';
-
-// 3. Paste the 'data-client-key' in the 'auth.clientKey' variable
-let auth = { type: 'key', clientKey: 'Z3123asdaczxSXSAasdcxzcashDY6MGSASFsafxSDdfASY2k0TUhPcEVsTnBR' };
-
-// 4. Define the SDK callbacks functions in this object
-const videoElement = document.getElementById('agent-video');
-
-const callbacks = {
-    onSrcObjectReady(value) {
-        videoElement.srcObject = value;
-    },
-    onConnectionStateChange(state) {
-        console.log('connection:', state);
-    },
-    onNewMessage(messages, type) {
-        if (type === 'answer') {
-            console.log(messages[messages.length - 1].content);
-        }
+const videoElement = document.getElementById('agent-video') as HTMLVideoElement;
+const agentManager = await sdk.createAgentManager('agt_fumf1234', {
+    auth: { type: 'key', clientKey: 'YOUR_CLIENT_KEY' },
+    callbacks: {
+        onSrcObjectReady: stream => (videoElement.srcObject = stream),
+        onNewMessage: messages => console.log(messages[messages.length - 1].content),
     },
-};
+});
 
-// 5. Define the Stream Options object (Optional — Talks (V2) and Clips (V3) agents only)
-let streamOptions = { compatibilityMode: 'auto', streamWarmup: true };
-
-//....Rest of the APP's code here....//
-//...................................//
-
-// 6. Create the 'agentManager' instance with the values created above
-let agentManager = await sdk.createAgentManager(agentId, { auth, callbacks, streamOptions });
-
-// 7. Open the session
 await agentManager.connect();
-
-// 8. Make the agent talk
 await agentManager.speak({ type: 'text', input: "Hi! I'm Alice!" });
 await agentManager.chat('What is the distance to the moon?');
+
+// Both resolve when the request is accepted, not when the agent has spoken.
+window.addEventListener('beforeunload', () => void agentManager.disconnect());
 ```
 
-## Usage
+## Next steps
+
+The full API reference — every method, callback, option and type, generated from the source on each release — is at **[sdk.d-id.com](https://sdk.d-id.com/)**. Start with [`createAgentManager()`](https://sdk.d-id.com/functions/createAgentManager.html), [`AgentManager`](https://sdk.d-id.com/interfaces/AgentManager.html), [`AgentManagerCallbacks`](https://sdk.d-id.com/interfaces/AgentManagerCallbacks.html) and, on Talks (V2) and Clips (V3) agents, [`StreamOptions`](https://sdk.d-id.com/interfaces/StreamOptions.html).
+
+The guides:
+
+- [Getting started](https://sdk.d-id.com/documents/Getting_started.html) — credentials, the first connection, `chat()` and `speak()`, disconnecting.
+- [Chat modes](https://sdk.d-id.com/documents/Chat_modes.html) — video, text-only or speak-only, and what each one creates on the wire.
+- [Client tools](https://sdk.d-id.com/documents/Client_tools.html) — running your own functions when the agent's LLM calls them.
+- [Expressive media](https://sdk.d-id.com/documents/Expressive_media.html) — microphone, camera, speech-to-text, interrupts and data-channel messages.
+- [Handling errors](https://sdk.d-id.com/documents/Handling_errors.html) — which failures reject, which reach `onError`, and what to log.
+- [Migration guide](https://sdk.d-id.com/documents/Migration_guide.html) — every breaking change from 2.x.
 
-Everything the `agentManager` exposes — methods, callbacks, stream options and every type — is documented in the **[API reference](https://sdk.d-id.com/)**, generated from the source on each release. Start with:
+A working sample project in Vanilla JavaScript and Vite is in the [demo repository](https://github.com/de-id/Agents-SDK-Demo).
 
-- [`createAgentManager()`](https://sdk.d-id.com/functions/createAgentManager.html) — initialization and options
-- [`AgentManager`](https://sdk.d-id.com/interfaces/AgentManager.html) — `connect()`, `speak()`, `chat()`, `interrupt()`, microphone and camera publishing, client tools
-- [`AgentManagerCallbacks`](https://sdk.d-id.com/interfaces/AgentManagerCallbacks.html) — `onSrcObjectReady` (mandatory), `onVideoStateChange`, `onConnectionStateChange`, `onNewMessage`, …
-- [`StreamOptions`](https://sdk.d-id.com/interfaces/StreamOptions.html) — Talks (V2) and Clips (V3) transport options
+## Requirements
 
-## See it in Action
+- **A modern browser with WebRTC.** The SDK streams the agent's video over WebRTC (Talks and Clips) or LiveKit (Expressive), and renders it into a `<video>` element you provide.
+- **ESM and UMD builds.** `import` resolves to the ES module; `require` and a `<script>` tag resolve to the UMD bundle.
+- **TypeScript types included.** They ship with the package; there is no separate `@types` to install.
+- **Node is not a runtime target**, but importing the package on a server is safe: the module graph touches no browser globals at import time, so server-rendered frameworks (Next.js, Remix, SvelteKit, Astro) can evaluate it. Everything past `createAgentManager()` needs a browser.
 
-Explore our demo repository on GitHub to see the Agents SDK in action!
-This repository features a sample project crafted in Vanilla JavaScript and Vite, utilizing the Agents SDK to help you get started swiftly.
+## Avatar types
 
-[GitHub Demo Repository](https://github.com/de-id/Agents-SDK-Demo)
+- **Talks (V2)** — Photo-based presenters using WebRTC streaming.
+- **Clips (V3)** — Pre-built presenter avatars using WebRTC streaming.
+- **Expressive (V4)** — Next-generation avatars using LiveKit-based streaming, supporting microphone input and always-on fluent mode.
 
 ## Support
 
-<div style="display: flex; flex-direction: row; justify-content: space-evenly; min-height: 1px">
-  <img style="width: 37%; border-radius: 5px; object-fit: cover;" src="https://create-images-results.d-id.com/api_docs/assets/questions.png" alt="Support Image" />
-  <span style="width: 3%"><br/></span>
-  <span style="width: 60%; text-align: left;">
-    Have any questions? We are here to help! Please open an issue on GitHub and we will be happy to answer shortly.<br/><br/>
-    <a href="https://github.com/de-id/agents-sdk/issues">
-      <span style="width: 30%; text-align: center; background: #ff882eff; color: #fff; display: inline-block; padding: 6px; border-radius: 5px;">
-        Ask a question
-      </span>
-    </a>
-  </span>
-</div>
-
-<div style="display: flex; flex-direction: row; justify-content: space-evenly; min-height: 1px">
-  <span style="width: 100%; text-align: center; background: linear-gradient(to right, #ff882eff , #fff); color: #fff; display: inline-block; padding: 6px; border-radius: 3px;">
-  </span>
-</div>
+Questions, bug reports and documentation issues are welcome as [GitHub issues](https://github.com/de-id/agents-sdk/issues). The product documentation lives at [docs.d-id.com](https://docs.d-id.com).