@equos/node-sdk 2.2.3 → 3.0.2-rc.0

package/README.md

@@ -1,106 +1,430 @@
 # @equos/node-sdk
-[Equos.ai](https://www.equos.ai) official node js SDK.
+
+[Equos.ai](https://www.equos.ai) official Node.js SDK - Build AI-powered avatars with lifelike faces, voices, and brains.
+
+## Features
+
+- ✅ **Full TypeScript Support** - Auto-generated types from OpenAPI specification
+- ✅ **Automatic API Key Management** - API key automatically added to all requests
+- ✅ **Character Management** - Create and manage AI characters with faces, voices, and brains
+- ✅ **Resource Management** - Manage faces, voices, brains, and knowledge bases
+- ✅ **Health & Limits** - Monitor API health and organization limits
 
 ## Prerequisites
-- Go to [Equos Studio](https://studio.equos.ai).
-- Create an organization.
-- Create an API Key.
 
+1. Go to [Equos Studio](https://studio.equos.ai)
+2. Create an organization
+3. Create an API Key
 
 ## Installation
+
 ```bash
 npm install @equos/node-sdk
 ```
 
-## Usage
+## Quick Start
 
-### Setup Equos Client
-```ts
-import { Equos } from '@equos/node-sdk';
+```typescript
+import { EquosClient } from '@equos/node-sdk';
 
-const  client = Equos.client(process.env.EQUOS_API_KEY!);
+// Create client with your API key
+const client = EquosClient.create(process.env.EQUOS_API_KEY!);
+
+// List all characters
+const characters = await client.characters.characterControllerListV3({
+  take: 10,
+  skip: 0,
+});
+
+console.log(`Found ${characters.total} characters`);
 ```
 
-You don't have an api key ? [Create one here](https://studio.equos.ai)
+Don't have an API key? [Create one here](https://studio.equos.ai)
 
-### Create Avatar
-```ts
-import { EquosAvatar, CreateEquosAvatarRequest } from '@equos/node-sdk';
+## Configuration
 
+### Default Configuration
 
-const data: CreateEquosAvatarRequest = {
-  identity: "equos-avatar-jeremy",
-  name: "Jeremy"
-  refImage: "<base64 data url of the reference image>" // 5Mo max.
-}
+```typescript
+const client = EquosClient.create('your-api-key');
+// Uses: https://api.equos.ai
+```
+
+## API Reference
+
+### Character Management
+
+Characters are the main entities that combine faces, voices, brains, and knowledge bases.
+
+#### Create a Character
+
+```typescript
+import { CreateEquosCharacterRequest, EquosCharacter } from '@equos/node-sdk';
+
+const characterData: CreateEquosCharacterRequest = {
+  name: 'AI Assistant',
+  livekitIdentity: 'ai-assistant-001',
+  faceId: 'face-id-here', // Optional
+  voiceId: 'voice-id-here', // Optional
+  brainId: 'brain-id-here', // Optional
+  knowledgeBaseId: 'kb-id', // Optional
+  search: false, // Enable web search
+};
 
-// Create an avatar.
-const avatar: EquosAvatar = await client.avatars.create(data);
+const character: EquosCharacter =
+  await client.characters.characterControllerCreateV3({
+    createEquosCharacterRequest: characterData,
+  });
 
-console.log(avatar);
+console.log('Created character:', character.id);
 ```
 
-### Create Agent
+#### List Characters
 
-```ts
-import { 
-    EquosAgent, 
-    CreateEquosAgentRequest, 
-    AgentProvider, 
-    OpenaiRealtimeVoices, 
-    OpenaiRealtimeModels 
-} from '@equos/node-sdk';
+```typescript
+const response = await client.characters.characterControllerListV3({
+  take: 20, // Number of items to return (max 50)
+  skip: 0, // Number of items to skip
+  client: 'my-app', // Optional: filter by client identifier
+});
+
+console.log(`Total: ${response.total}`);
+response.characters.forEach((char) => {
+  console.log(`- ${char.name} (${char.id})`);
+});
+```
+
+#### Get Character by ID
+
+```typescript
+const character = await client.characters.characterControllerGetByIdV3({
+  id: 'character-id',
+});
+
+console.log('Character:', character);
+// Includes populated face, voice, brain, and knowledgeBase objects
+```
+
+#### Update a Character
+
+```typescript
+import { UpdateEquosCharacterRequest } from '@equos/node-sdk';
+
+const updates: UpdateEquosCharacterRequest = {
+  name: 'Updated Name',
+  voiceId: 'new-voice-id',
+  brainId: 'new-brain-id',
+};
+
+const updated = await client.characters.characterControllerUpdateV3({
+  id: 'character-id',
+  updateEquosCharacterRequest: updates,
+});
+```
+
+#### Delete a Character
+
+```typescript
+const deleted = await client.characters.characterControllerSoftDeleteV3({
+  id: 'character-id',
+});
+```
+
+### Face Management
+
+Faces define the visual appearance of your AI characters.
+
+#### Create a Face
+
+```typescript
+import { CreateEquosFaceRequest } from '@equos/node-sdk';
+
+const faceData: CreateEquosFaceRequest = {
+  identity: 'byron', // or 'emily' - from Equos Gallery
+  client: 'my-app', // Optional: client identifier
+};
+
+const face = await client.faces.faceControllerCreateV3({
+  createEquosFaceRequest: faceData,
+});
 
+console.log('Face ID:', face.id);
+console.log('Status:', face.status); // 'processing', 'ready', or 'error'
+```
+
+#### List Faces
 
-const data: CreateEquosAgentRequest = {
-  name: "My Agent",
-  provider: AgentProvider.openai,
-  config: {
-    instructions: "You are a Korean teacher...",
-    voice: OpenaiRealtimeVoices.ash,
-    model: OpenaiRealtimeModels.gpt_realtime
+```typescript
+const faces = await client.faces.faceControllerListV3({
+  take: 10,
+  skip: 0,
+});
+
+faces.faces.forEach((face) => {
+  console.log(`${face.id}: ${face.status}`);
+  if (face.thumbnailUrl) {
+    console.log(`  Thumbnail: ${face.thumbnailUrl}`);
   }
-}
+});
+```
+
+#### Get Face by ID
+
+```typescript
+const face = await client.faces.faceControllerGetByIdV3({
+  id: 'face-id',
+});
+```
+
+#### Delete a Face
+
+```typescript
+await client.faces.faceControllerSoftDeleteV3({
+  id: 'face-id',
+});
+```
+
+### Voice Management
+
+Voices define how your AI characters sound.
+
+#### Create a Voice
 
-const agent: EquosAgent = await client.agents.create(data);
-console.log(agent);
+```typescript
+import { CreateEquosVoiceRequest } from '@equos/node-sdk';
+
+const voiceData: CreateEquosVoiceRequest = {
+  name: 'Professional Voice',
+  description: 'Clear and professional tone',
+  voiceId: 'elevenlabs-voice-id',
+  sampleUrl: 'https://example.com/sample.mp3',
+  client: 'my-app', // Optional
+};
+
+const voice = await client.voices.voiceControllerCreateV3({
+  createEquosVoiceRequest: voiceData,
+});
 ```
 
+#### List Voices
+
+```typescript
+const voices = await client.voices.voiceControllerListV3({
+  take: 10,
+  skip: 0,
+});
+```
+
+#### Get Voice by ID
+
+```typescript
+const voice = await client.voices.voiceControllerGetByIdV3({
+  id: 'voice-id',
+});
+```
 
-### Start a Session
-This will create and start a session. The avatar will join the room as soon as possible.
+#### Delete a Voice
 
-```ts
-const sessionOptions: CreateEquosSessionRequest = {
-    name: 'Equos Session',
-    agent: {
-        id: "<your agent id>"
-    }, // agent accepts either an object with id of existing agent, or CreateEquosAgent object.
-    avatar: {
-        id: "<your avatar id>"
-    }, // avatar accepts either an object with id of existing avatar, or CreateEquosAvatar object.
-    consumerIdentity: {
-        identity: 'client-identity',
-        name: 'Client Name'
-    }
+```typescript
+await client.voices.voiceControllerSoftDeleteV3({
+  id: 'voice-id',
+});
+```
+
+### Brain Management
+
+Brains define the personality and behavior of your AI characters.
+
+#### Create a Brain
+
+```typescript
+import { CreateEquosBrainRequest } from '@equos/node-sdk';
+
+const brainData: CreateEquosBrainRequest = {
+  name: 'Customer Support Brain',
+  instructions:
+    'You are a helpful customer support agent. Be friendly and professional.',
+  greetingMessage: 'Hello! How can I help you today?',
+  model: 'gemini-2.5-flash-native-audio-preview-09-2025',
+  client: 'my-app', // Optional
+};
+
+const brain = await client.brains.brainControllerCreateV3({
+  createEquosBrainRequest: brainData,
+});
+```
+
+#### List Brains
+
+```typescript
+const brains = await client.brains.brainControllerListV3({
+  take: 10,
+  skip: 0,
+});
+```
+
+#### Get Brain by ID
+
+```typescript
+const brain = await client.brains.brainControllerGetByIdV3({
+  id: 'brain-id',
+});
+
+console.log('Instructions:', brain.instructions);
+console.log('Greeting:', brain.greetingMessage);
+```
+
+#### Delete a Brain
+
+```typescript
+await client.brains.brainControllerSoftDeleteV3({
+  id: 'brain-id',
+});
+```
+
+### Health & Limits
+
+#### Check API Health
+
+```typescript
+const health = await client.health.healthControllerCheckV3();
+console.log('Status:', health.status);
+console.log('Version:', health.version);
+```
+
+#### Get Organization Limits
+
+```typescript
+const limits = await client.limits.limitsControllerLimitV3();
+
+if (limits) {
+  console.log('Concurrent sessions:', limits.concurrent);
+  console.log('Max duration:', limits.duration);
+  console.log('Suspended:', limits.suspended);
+  if (limits.reason) {
+    console.log('Reason:', limits.reason);
+  }
 }
+```
+
+## Complete Example
 
-const result = await client.sessions.create(sessionOptions);
+```typescript
+import { EquosClient } from '@equos/node-sdk';
 
-console.log(result.session);
-console.log(result.consumerAccessToken);
+async function main() {
+  const client = EquosClient.create(process.env.EQUOS_API_KEY!);
+
+  // Create a face
+  const face = await client.faces.faceControllerCreateV3({
+    createEquosFaceRequest: {
+      identity: 'byron',
+    },
+  });
+
+  // Create a voice
+  const voice = await client.voices.voiceControllerCreateV3({
+    createEquosVoiceRequest: {
+      name: 'Professional Voice',
+      description: 'Clear professional tone',
+      voiceId: 'elevenlabs-voice-id',
+      sampleUrl: 'https://example.com/sample.mp3',
+    },
+  });
+
+  // Create a brain
+  const brain = await client.brains.brainControllerCreateV3({
+    createEquosBrainRequest: {
+      name: 'Support Agent',
+      instructions: 'You are a helpful support agent.',
+      greetingMessage: 'Hello! How can I help?',
+      model: 'gemini-2.5-flash-native-audio-preview-09-2025',
+    },
+  });
+
+  // Create a character with all components
+  const character = await client.characters.characterControllerCreateV3({
+    createEquosCharacterRequest: {
+      name: 'AI Support Agent',
+      livekitIdentity: 'support-agent-001',
+      faceId: face.id,
+      voiceId: voice.id,
+      brainId: brain.id,
+      search: false,
+    },
+  });
+
+  console.log('Created character:', character.id);
+  console.log('Face:', character.face?.status);
+  console.log('Voice:', character.voice?.name);
+  console.log('Brain:', character.brain?.name);
+}
+
+main().catch(console.error);
 ```
 
-### Stop a Session
-```ts
-const session = await client.sessions.stop("<session id>");
+## Error Handling
+
+```typescript
+try {
+  const character = await client.characters.characterControllerGetByIdV3({
+    id: 'non-existent-id',
+  });
+} catch (error) {
+  if (error instanceof Error) {
+    console.error('Error:', error.message);
+  }
+}
 ```
 
-## Reach Us
-- Equos Slack Community: [Join Equos Community Slack](https://join.slack.com/t/equosaicommunity/shared_invite/zt-3d8oy19au-jZpsJB0i~gdL0jbDswdzzQ)
-- Support: [Support Form](https://docs.google.com/forms/d/e/1FAIpQLSdoK7LvORdQf7KOQKvhhlESStJcKc3bDB9HPsEet6LuOmVUfQ/viewform)
+## TypeScript Support
 
-## Documentation
+All types are automatically generated from the OpenAPI specification:
+
+```typescript
+import {
+  EquosClient,
+  EquosCharacter,
+  EquosFace,
+  EquosVoice,
+  EquosBrain,
+  CreateEquosCharacterRequest,
+  UpdateEquosCharacterRequest,
+  ListEquosCharactersResponse,
+} from '@equos/node-sdk';
+```
+
+## Deprecated APIs
+
+> ⚠️ **Note**: The following APIs are deprecated and will be removed in a future version. Please migrate to the Character-based APIs above.
+>
+> - **Avatars API** (`client.avatars.*`) - Use Characters API instead
+> - **Agents API** (`client.agents.*`) - Use Brains API instead
+> - **Sessions API** (`client.sessions.*`) - Deprecated
+> - **Session Passes API** (`client.sessionPasses.*`) - Deprecated
+>
+> These APIs are marked as `deprecated: true` in the OpenAPI specification.
+
+## Regenerating the Client
+
+The SDK is auto-generated from the OpenAPI specification. To regenerate after API changes:
+
+1. Ensure your backend API is running on `http://localhost:3001`
+2. Run:
+
+```bash
+npm run generate
+```
+
+This fetches the latest OpenAPI spec and regenerates all TypeScript code.
+
+## Resources
 
 - Official Documentation: [https://docs.equos.ai](https://docs.equos.ai)
-- Equos NodeJS Usage Examples: [https://github.com/EquosAI/equos-examples/tree/main/examples/equos-nextjs-integration](https://github.com/EquosAI/equos-examples/tree/main/examples/equos-nextjs-integration)
+- Equos NodeJS Examples: [GitHub Examples](https://github.com/EquosAI/equos-examples/tree/main/examples/equos-nextjs-integration)
+- Equos Slack Community: [Join Slack](https://join.slack.com/t/equosaicommunity/shared_invite/zt-3d8oy19au-jZpsJB0i~gdL0jbDswdzzQ)
+- Support: [Support Form](https://docs.google.com/forms/d/e/1FAIpQLSdoK7LvORdQf7KOQKvhhlESStJcKc3bDB9HPsEet6LuOmVUfQ/viewform)
+
+## License
+
+See [LICENSE](./LICENSE) for details.

package/dist/api/apis/AgentApi.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Equos.ai API
+ * API documentation for Equos.ai live platform.
+ *
+ * The version of the OpenAPI document: 3.0
+ *
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+import * as runtime from '../runtime';
+import type { CreateEquosAgentRequest, EquosAgent, ListEquosAgentsResponse, UpdateEquosAgentRequest } from '../models/index';
+export interface AgentControllerArchiveV3Request {
+    id: string;
+}
+export interface AgentControllerCreateV3Request {
+    createEquosAgentRequest: CreateEquosAgentRequest;
+}
+export interface AgentControllerGetByIdV3Request {
+    id: string;
+}
+export interface AgentControllerListV3Request {
+    take?: number;
+    skip?: number;
+    client?: string;
+}
+export interface AgentControllerUpdateV3Request {
+    id: string;
+    updateEquosAgentRequest: UpdateEquosAgentRequest;
+}
+/**
+ *
+ */
+export declare class AgentApi extends runtime.BaseAPI {
+    /**
+     * Delete an Equos Agent. This action is irreversible.
+     * @deprecated
+     */
+    agentControllerArchiveV3Raw(requestParameters: AgentControllerArchiveV3Request, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<EquosAgent>>;
+    /**
+     * Delete an Equos Agent. This action is irreversible.
+     * @deprecated
+     */
+    agentControllerArchiveV3(requestParameters: AgentControllerArchiveV3Request, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<EquosAgent>;
+    /**
+     * Create a new Equos Agent.
+     * @deprecated
+     */
+    agentControllerCreateV3Raw(requestParameters: AgentControllerCreateV3Request, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<EquosAgent>>;
+    /**
+     * Create a new Equos Agent.
+     * @deprecated
+     */
+    agentControllerCreateV3(requestParameters: AgentControllerCreateV3Request, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<EquosAgent>;
+    /**
+     * Get Equos Agent by ID.
+     * @deprecated
+     */
+    agentControllerGetByIdV3Raw(requestParameters: AgentControllerGetByIdV3Request, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<EquosAgent>>;
+    /**
+     * Get Equos Agent by ID.
+     * @deprecated
+     */
+    agentControllerGetByIdV3(requestParameters: AgentControllerGetByIdV3Request, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<EquosAgent>;
+    /**
+     * List Equos Agents.
+     * @deprecated
+     */
+    agentControllerListV3Raw(requestParameters: AgentControllerListV3Request, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<ListEquosAgentsResponse>>;
+    /**
+     * List Equos Agents.
+     * @deprecated
+     */
+    agentControllerListV3(requestParameters?: AgentControllerListV3Request, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<ListEquosAgentsResponse>;
+    /**
+     * Update an Equos Agent.
+     * @deprecated
+     */
+    agentControllerUpdateV3Raw(requestParameters: AgentControllerUpdateV3Request, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<EquosAgent>>;
+    /**
+     * Update an Equos Agent.
+     * @deprecated
+     */
+    agentControllerUpdateV3(requestParameters: AgentControllerUpdateV3Request, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<EquosAgent>;
+}