@rtsdk/topia 0.19.4 → 0.19.6

package/README.md

@@ -240,44 +240,70 @@ export const getDroppedAssetAndVisitor = async (req: Request, res: Response) =>
 };
 ```
 
-<br/><br/>
-
 ## Data Objects
 
 Data Objects can be used to store information such as game state, configurations, themes, and analytics.
 There are three types of Data Objects:
 
-- **World:** The World data object should be used to store information unique to your app in a given world but not necessarily specific details about an instance or an active game. This information would persist even if the app was removed from the world.
-  - **Example - Update two specific data points:**
-    ```ts
-    await world.updateDataObject({
-      [`keyAssets.${keyAssetId}.itemsCollectedByUser.${profileId}`]: { [dateKey]: { count: 1 }, total: 1 },
-      [`profileMapper.${profileId}`]: username,
-    });
-    ```
-  - **Example - Increment a specific value within the data object by 1:**
-    ```ts
-    await world.incrementDataObjectValue([`keyAssets.${keyAssetId}.totalItemsCollected.count`], 1);
-    ```
-- **Dropped Asset:** The Dropped Asset data object should only store what is unique to the specific instance of the app in the world such as game state. If the Dropped Asset is deleted, the data object would be lost as well so be sure to only store information here the doesn't need to persist!
-  - **Example - Initialize data object with default data and keyAssetId:**
-    ```ts
-    await droppedAsset.setDataObject(
-      {
-        ...defaultGameData,
-        keyAssetId: droppedAsset.id,
-      },
-      { lock: { lockId, releaseLock: true } },
-    );
-    ```
-  - **Example - Update lastInteraction date and playerCount:**
-    ```ts
-    await droppedAsset.updateDataObject({ lastInteraction: new Date(), playerCount: playerCount + 1 });
-    ```
-- **User:** The User data object should be used to store information unique to a user that is NOT unique to a world or instance (dropped asset) of an app.
-  - **Example - Update totalMessagesSentCount by a user across all worlds:**
-    `` js await world.incrementDataObjectValue([`totalMessagesSentCount`], 1);  ``
-    <br/>
+### World:
+
+The data object attached to the world will store information for every instance of the app in a given world by keyAssetId or sceneDropId and will persist even if a specific instance is removed from world. Data stored in the World data object should be minimal to avoid running into limits.
+
+#### Example - Update two specific data points:
+
+```ts
+await world.updateDataObject({
+  [sceneDropId]: { keyAssetId: droppedAsset.id, themeId: "custom", totalInteractions: 1 },
+});
+```
+
+#### Example - Increment a specific value within the data object by 1:
+
+```ts
+await world.incrementDataObjectValue([`${sceneDropId}.totalInteractions`], 1);
+```
+
+### Dropped Asset:
+
+The Dropped Asset data object should only store what is unique to the specific instance of the app in the world such as game state. If the Dropped Asset is deleted, the data object would be lost as well so be sure to only store information here the doesn't need to persist!
+
+#### Example - Initialize data object with default data and keyAssetId:
+
+```ts
+await droppedAsset.setDataObject(
+  {
+    ...defaultGameData,
+    keyAssetId: droppedAsset.id,
+  },
+  { lock: { lockId, releaseLock: true } },
+);
+```
+
+#### Example - Update lastInteraction date and playerCount:
+
+```ts
+await droppedAsset.updateDataObject({ lastInteraction: new Date(), playerCount: playerCount + 1 });
+```
+
+### User:
+
+The data object attached to the visitor should store information related specifically to the visitor i.e. progress. For tracking across multiple world/instances use `${urlSlug}_${sceneDropId}` as a unique key.
+
+#### Example - Initialize data object with default data and keyAssetId:
+
+```ts
+await visitor.setDataObject(
+  {
+    [`${urlSlug}_${sceneDropId}`]: {
+      currentStreak: 0,
+      lastCollectedDate: null,
+      longestStreak: 0,
+      totalCollected: 0,
+    },
+  },
+  { lock: { lockId, releaseLock: true } },
+);
+```
 
 ### Data Object Locking
 
@@ -324,7 +350,7 @@ await world.setDataObject({ hello: "world" }, { analytics: [{ analyticName: "res
 
 await world.updateDataObject({}, { analytics: [ {analyticName: "matches", uniqueKey: `${playerOneProfileId}-${playerTwoProfileId}`, urlSlug }], });
 
-await world.incrementDataObjectValue(`keyAssets.${assetId}.completions`, 1, { analytics: [{ analyticName:"completions", incrementBy: 2, profileId, uniqueKey: profileId, urlSlug }] });
+await world.incrementDataObjectValue(`${sceneDropId}.completions`, 1, { analytics: [{ analyticName:"completions", incrementBy: 2, profileId, uniqueKey: profileId, urlSlug }] });
 ```
 
 Examples leveraging Visitor data objects calls:
@@ -345,7 +371,7 @@ await visitor.incrementDataObjectValue(`completions`, 1, {
 });
 ```
 
-Note: passing an empty object does NOT impact the data objects themselves but rather allows you to track custom analytics (incremented by 1) across all instances of your application with a given Public Key.
+Note: passing an empty object does NOT impact the data objects themselves but rather allows you to track custom analytics across all instances of your application with a given Public Key.
 
 <br>
 
@@ -353,26 +379,18 @@ Note: passing an empty object does NOT impact the data objects themselves but ra
 
 <hr/>
 
-<br>
-
 ## Get Started
 
 Run `gh repo clone metaversecloud-com/mc-sdk-js`
 
-<br>
-
 ## Issues
 
 We've added an Issue template to help standardize Issues and ensure they have enough detail for a developer to start work and help prevent contributors from forgetting to add an important piece of information.
 
-<br>
-
 ## Pull Requests
 
 We've added a Pull Request template to help make it easier for developers to clarify what the proposed changes will do. This helps facilitate clear communication between all contributors of the SDK and ensures that we are all on the same page!
 
-<br>
-
 ## Documentation
 
 ### Styles

package/dist/index.cjs

@@ -39727,11 +39727,6 @@ class SDKController {
      *
      * @keywords error, exception, handler, debugging, api error, http error
      *
-     * @param error - The error object from the failed operation (AxiosError, Error, or unknown)
-     * @param message - Optional custom error message (defaults to generic message)
-     * @param params - Optional parameters that were passed to the failed method
-     * @param sdkMethod - Optional name of the SDK method that failed (e.g., "World.fetchDetails")
-     *
      * @returns {object} Standardized error object with properties: data, message, method, params, sdkMethod, stack, status, success, url
      */
     errorHandler({ error, message = "Something went wrong. Please try again or contact support.", params = {}, sdkMethod, }) {
@@ -43670,7 +43665,13 @@ class Visitor extends User {
     createNpc(userInventoryItemId, options) {
         return __awaiter(this, void 0, void 0, function* () {
             try {
-                const response = yield this.topiaPublicApi().post(`/world/${this.urlSlug}/visitors/${this.id}/create-npc`, { userInventoryItemId, showNameplate: options === null || options === void 0 ? void 0 : options.showNameplate }, this.requestOptions);
+                const response = yield this.topiaPublicApi().post(`/world/${this.urlSlug}/visitors/${this.id}/create-npc`, {
+                    userInventoryItemId,
+                    showNameplate: options === null || options === void 0 ? void 0 : options.showNameplate,
+                    stationary: options === null || options === void 0 ? void 0 : options.stationary,
+                    replace: options === null || options === void 0 ? void 0 : options.replace,
+                    spawnEffect: options === null || options === void 0 ? void 0 : options.spawnEffect,
+                }, this.requestOptions);
                 return new Visitor(this.topia, response.data.player.playerId, this.urlSlug, {
                     attributes: response.data,
                     credentials: this.credentials,
@@ -43715,6 +43716,77 @@ class Visitor extends User {
             }
         });
     }
+    /**
+     * Start an AI voice session for this visitor's NPC.
+     *
+     * @remarks
+     * Establishes a real-time voice connection between the visitor and an AI backend
+     * (currently OpenAI Realtime API) through the NPC. The NPC must already be spawned
+     * via `createNpc()` before calling this method.
+     *
+     * The voice session occupies a video slot in the visitor's peer video grid, showing
+     * the NPC's avatar image. Audio streams bidirectionally between the visitor's microphone
+     * and the AI model. Only the NPC's owner hears the AI audio.
+     *
+     * Topia automatically prepends non-removable child safety guardrails to the instructions.
+     * Only one voice session is allowed per visitor per world at a time.
+     *
+     * @keywords voice, npc, ai, chat, audio, realtime, session, start, speech
+     *
+     * @category NPCs
+     *
+     * @param config - Voice session configuration including ephemeral key and AI instructions
+     *
+     * @example
+     * ```ts
+     * const ephemeralKey = await generateOpenAIEphemeralKey();
+     *
+     * await visitor.startNpcVoiceSession({
+     *   ephemeralKey,
+     *   voice: "alloy",
+     *   instructions: "You are a friendly science tutor helping with photosynthesis.",
+     *   model: "gpt-4o-realtime-preview",
+     * });
+     * ```
+     *
+     * @returns {Promise<void | ResponseType>} Returns `{ success: true }` or an error.
+     */
+    startNpcVoiceSession(config) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const response = yield this.topiaPublicApi().put(`/world/${this.urlSlug}/visitors/${this.id}/start-npc-voice-session`, { voiceConfig: config }, this.requestOptions);
+                return response.data;
+            }
+            catch (error) {
+                throw this.errorHandler({ error, params: config, sdkMethod: "Visitor.startNpcVoiceSession" });
+            }
+        });
+    }
+    /**
+     * Stop the active AI voice session for this visitor's NPC.
+     *
+     * @keywords voice, npc, ai, chat, audio, realtime, session, stop, end
+     *
+     * @category NPCs
+     *
+     * @example
+     * ```ts
+     * await visitor.stopNpcVoiceSession();
+     * ```
+     *
+     * @returns {Promise<void | ResponseType>} Returns `{ success: true }` or an error.
+     */
+    stopNpcVoiceSession() {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const response = yield this.topiaPublicApi().put(`/world/${this.urlSlug}/visitors/${this.id}/stop-npc-voice-session`, {}, this.requestOptions);
+                return response.data;
+            }
+            catch (error) {
+                throw this.errorHandler({ error, sdkMethod: "Visitor.stopNpcVoiceSession" });
+            }
+        });
+    }
     /**
      * Retrieves all inventory items owned by this visitor and app's key.
      *

package/dist/index.d.ts

@@ -74,7 +74,7 @@ type DroppedAssetLinkType = {
     linkSamlQueryParams?: string;
 };
 
-type InteractiveCredentials = {
+type InteractiveCredentials$1 = {
     apiKey?: string;
     assetId?: string;
     interactiveNonce?: string;
@@ -88,22 +88,22 @@ type InteractiveCredentials = {
 
 type AssetOptions = {
     attributes?: AssetInterface | undefined;
-    credentials?: InteractiveCredentials | undefined;
+    credentials?: InteractiveCredentials$1 | undefined;
 };
 type DroppedAssetOptions = {
     attributes?: DroppedAssetInterface | undefined;
-    credentials?: InteractiveCredentials | undefined;
+    credentials?: InteractiveCredentials$1 | undefined;
 };
 type UserOptions = {
-    credentials?: InteractiveCredentials | undefined;
+    credentials?: InteractiveCredentials$1 | undefined;
 };
 type VisitorOptions = {
     attributes?: VisitorInterface | undefined;
-    credentials?: InteractiveCredentials | undefined;
+    credentials?: InteractiveCredentials$1 | undefined;
 };
 type WorldOptions = {
     attributes?: WorldDetailsInterface | undefined;
-    credentials?: InteractiveCredentials | undefined;
+    credentials?: InteractiveCredentials$1 | undefined;
 };
 
 type ResponseType = {
@@ -2160,9 +2160,7 @@ declare class Visitor extends User implements VisitorInterface {
      *
      * @returns {Promise<Visitor>} Returns a Visitor object representing the created NPC. The NPC will automatically follow the visitor.
      */
-    createNpc(userInventoryItemId: string, options?: {
-        showNameplate?: boolean;
-    }): Promise<Visitor>;
+    createNpc(userInventoryItemId: string, options?: CreateNpcOptions): Promise<Visitor>;
     /**
      * Deletes the NPC (Non-Player Character) this app has assigned to this visitor.
      *
@@ -2188,6 +2186,57 @@ declare class Visitor extends User implements VisitorInterface {
      * @returns {Promise<void>} Returns nothing if successful.
      */
     deleteNpc(): Promise<void>;
+    /**
+     * Start an AI voice session for this visitor's NPC.
+     *
+     * @remarks
+     * Establishes a real-time voice connection between the visitor and an AI backend
+     * (currently OpenAI Realtime API) through the NPC. The NPC must already be spawned
+     * via `createNpc()` before calling this method.
+     *
+     * The voice session occupies a video slot in the visitor's peer video grid, showing
+     * the NPC's avatar image. Audio streams bidirectionally between the visitor's microphone
+     * and the AI model. Only the NPC's owner hears the AI audio.
+     *
+     * Topia automatically prepends non-removable child safety guardrails to the instructions.
+     * Only one voice session is allowed per visitor per world at a time.
+     *
+     * @keywords voice, npc, ai, chat, audio, realtime, session, start, speech
+     *
+     * @category NPCs
+     *
+     * @param config - Voice session configuration including ephemeral key and AI instructions
+     *
+     * @example
+     * ```ts
+     * const ephemeralKey = await generateOpenAIEphemeralKey();
+     *
+     * await visitor.startNpcVoiceSession({
+     *   ephemeralKey,
+     *   voice: "alloy",
+     *   instructions: "You are a friendly science tutor helping with photosynthesis.",
+     *   model: "gpt-4o-realtime-preview",
+     * });
+     * ```
+     *
+     * @returns {Promise<void | ResponseType>} Returns `{ success: true }` or an error.
+     */
+    startNpcVoiceSession(config: NpcVoiceConfigInterface): Promise<void | ResponseType>;
+    /**
+     * Stop the active AI voice session for this visitor's NPC.
+     *
+     * @keywords voice, npc, ai, chat, audio, realtime, session, stop, end
+     *
+     * @category NPCs
+     *
+     * @example
+     * ```ts
+     * await visitor.stopNpcVoiceSession();
+     * ```
+     *
+     * @returns {Promise<void | ResponseType>} Returns `{ success: true }` or an error.
+     */
+    stopNpcVoiceSession(): Promise<void | ResponseType>;
     /**
      * Retrieves all inventory items owned by this visitor and app's key.
      *
@@ -2294,7 +2343,7 @@ declare enum WorldActivityType {
 }
 
 interface SDKInterface {
-    credentials?: InteractiveCredentials;
+    credentials?: InteractiveCredentials$1;
     jwt?: string;
     requestOptions: object;
     topia: Topia;
@@ -2331,7 +2380,7 @@ interface AssetInterface extends SDKInterface {
 }
 type AssetOptionalInterface = {
     attributes?: AssetInterface | object;
-    credentials?: InteractiveCredentials;
+    credentials?: InteractiveCredentials$1;
 };
 
 interface DroppedAssetInterface extends AssetInterface {
@@ -2453,7 +2502,7 @@ interface DroppedAssetOptionalInterface {
         text?: string;
         urlSlug?: string;
     };
-    credentials?: InteractiveCredentials | object;
+    credentials?: InteractiveCredentials$1 | object;
 }
 interface UpdateBroadcastInterface {
     assetBroadcast?: boolean;
@@ -2545,7 +2594,7 @@ interface EcosystemInterface extends SDKInterface {
     incrementDataObjectValue(path: string, amount: number, options: object): Promise<void | ResponseType>;
 }
 interface EcosystemOptionalInterface {
-    credentials?: InteractiveCredentials;
+    credentials?: InteractiveCredentials$1;
 }
 
 interface SceneInterface {
@@ -2573,7 +2622,7 @@ interface SceneInterface {
 }
 type SceneOptionalInterface = {
     attributes?: SceneInterface | object;
-    credentials?: InteractiveCredentials;
+    credentials?: InteractiveCredentials$1;
 };
 
 interface FireToastInterface {
@@ -2621,7 +2670,7 @@ interface UserInterface {
     dataObject?: object | null;
 }
 interface UserOptionalInterface {
-    credentials?: InteractiveCredentials;
+    credentials?: InteractiveCredentials$1;
     profileId?: string | null;
     visitorId?: number | null;
     urlSlug?: string;
@@ -2649,11 +2698,11 @@ interface VisitorInterface extends SDKInterface {
     grantInventoryItem(item: InventoryItemInterface, quantity: number): Promise<UserInventoryItem>;
     modifyInventoryItemQuantity(item: UserInventoryItemInterface | InventoryItemInterface, quantity: number): Promise<UserInventoryItem>;
     fetchInventoryItem(item: InventoryItemInterface): Promise<UserInventoryItem>;
-    createNpc(userInventoryItemId: string, options?: {
-        showNameplate?: boolean;
-    }): Promise<Visitor>;
+    createNpc(userInventoryItemId: string, options?: CreateNpcOptions): Promise<Visitor>;
     deleteNpc(): Promise<void>;
     getNpc(): Promise<Visitor | null>;
+    startNpcVoiceSession(config: NpcVoiceConfigInterface): Promise<void | ResponseType>;
+    stopNpcVoiceSession(): Promise<void | ResponseType>;
     triggerParticle({ id, name, duration, }: {
         id?: string;
         name?: string;
@@ -2697,7 +2746,7 @@ interface VisitorInterface extends SDKInterface {
 }
 interface VisitorOptionalInterface {
     attributes?: VisitorInterface | object;
-    credentials?: InteractiveCredentials;
+    credentials?: InteractiveCredentials$1;
 }
 interface MoveVisitorInterface {
     shouldTeleportVisitor: boolean;
@@ -2710,6 +2759,39 @@ interface OpenIframeInterface {
     shouldOpenInDrawer?: boolean;
     title?: string;
 }
+interface SpawnEffectConfig {
+    type?: "portal" | "none";
+    colors?: number[];
+    glowColor?: number;
+    glowOpacity?: number;
+    centerColor?: number;
+    duration?: number;
+    sectorCount?: number;
+    gridSize?: number;
+}
+interface CreateNpcOptions {
+    showNameplate?: boolean;
+    stationary?: boolean;
+    replace?: boolean;
+    spawnEffect?: SpawnEffectConfig;
+}
+interface NpcVoiceConfigInterface {
+    /** OpenAI ephemeral key (ek_*). Generated server-side, used once to establish WebRTC connection. */
+    ephemeralKey: string;
+    /** OpenAI voice ID (e.g., "alloy", "echo", "shimmer"). */
+    voice: string;
+    /** System prompt including curriculum context and behavioral instructions. */
+    instructions: string;
+    /** OpenAI model ID. Defaults to "gpt-4o-realtime-preview". */
+    model?: string;
+    /** Voice activity detection configuration. */
+    turnDetection?: {
+        type: "server_vad";
+        threshold?: number;
+        prefix_padding_ms?: number;
+        silence_duration_ms?: number;
+    };
+}
 
 interface WebhookInterface {
     webhookId?: string;
@@ -2730,12 +2812,12 @@ interface WebRTCConnectorInterface {
     getTwilioConfig(): Promise<void | ResponseType>;
 }
 interface WebRTCConnectorOptionalInterface {
-    credentials?: InteractiveCredentials;
+    credentials?: InteractiveCredentials$1;
     twilioConfig?: object;
 }
 
 interface WorldActivityOptionalInterface {
-    credentials?: InteractiveCredentials;
+    credentials?: InteractiveCredentials$1;
 }
 interface MoveAllVisitorsInterface {
     shouldFetchVisitors?: boolean;
@@ -2825,13 +2907,13 @@ interface WorldInterface extends SDKInterface, WorldDetailsInterface {
 }
 interface WorldOptionalInterface {
     attributes?: WorldDetailsInterface | object;
-    credentials?: InteractiveCredentials;
+    credentials?: InteractiveCredentials$1;
 }
 interface WorldWebhooksInterface {
     webhooks: Array<WebhookInterface>;
 }
 
-type InteractiveCredentials$1 = {
+type InteractiveCredentials = {
     apiKey?: string;
     assetId?: string;
     interactiveNonce?: string;
@@ -2862,7 +2944,7 @@ interface InventoryItemInterface extends SDKInterface {
 }
 type InventoryItemOptionalInterface = {
     attributes?: InventoryItemInterface | object;
-    credentials?: InteractiveCredentials$1;
+    credentials?: InteractiveCredentials;
 };
 
 /**
@@ -2880,7 +2962,7 @@ interface UserInventoryItemInterface extends InventoryItemInterface {
 }
 type UserInventoryItemOptionalInterface = {
     attributes?: UserInventoryItemInterface | object;
-    credentials?: InteractiveCredentials$1;
+    credentials?: InteractiveCredentials;
 };
 type UserInventoryItemMetadataType = {
     id: string;
@@ -2959,11 +3041,11 @@ declare class Topia implements TopiaInterface {
  * ```
  */
 declare abstract class SDKController implements SDKInterface {
-    credentials: InteractiveCredentials | undefined;
+    credentials: InteractiveCredentials$1 | undefined;
     jwt?: string;
     requestOptions: object;
     topia: Topia;
-    constructor(topia: Topia, credentials?: InteractiveCredentials);
+    constructor(topia: Topia, credentials?: InteractiveCredentials$1);
     /**
      * Returns the configured Axios instance for making API calls to Topia's Public API.
      *
@@ -2991,11 +3073,6 @@ declare abstract class SDKController implements SDKInterface {
      *
      * @keywords error, exception, handler, debugging, api error, http error
      *
-     * @param error - The error object from the failed operation (AxiosError, Error, or unknown)
-     * @param message - Optional custom error message (defaults to generic message)
-     * @param params - Optional parameters that were passed to the failed method
-     * @param sdkMethod - Optional name of the SDK method that failed (e.g., "World.fetchDetails")
-     *
      * @returns {object} Standardized error object with properties: data, message, method, params, sdkMethod, stack, status, success, url
      */
     errorHandler({ error, message, params, sdkMethod, }: {
@@ -3608,7 +3685,7 @@ declare class DroppedAssetFactory extends SDKController {
      *
      * @returns {Promise<DroppedAsset>} Returns a new DroppedAsset object with all properties already fetched.
      */
-    getWithUniqueName(uniqueName: string, urlSlug: string, interactiveSecret: string, credentials: InteractiveCredentials): Promise<DroppedAsset>;
+    getWithUniqueName(uniqueName: string, urlSlug: string, interactiveSecret: string, credentials: InteractiveCredentials$1): Promise<DroppedAsset>;
     /**
      * Drops an asset in a world and returns a new instance of DroppedAsset class with all properties.
      *
@@ -4190,4 +4267,4 @@ declare class WorldFactory extends SDKController {
     }>;
 }
 
-export { AnalyticType, AnimationMetaType, Asset, AssetFactory, AssetInterface, AssetOptionalInterface, AssetOptions, AssetType, DroppedAsset, DroppedAssetClickType, DroppedAssetFactory, DroppedAssetInterface, DroppedAssetLinkType, DroppedAssetMediaType, DroppedAssetMediaVolumeRadius, DroppedAssetOptionalInterface, DroppedAssetOptions, Ecosystem, EcosystemFactory, EcosystemInterface, EcosystemOptionalInterface, FireToastInterface, FrameType, InteractiveCredentials, InventoryItemInterface, InventoryItemOptionalInterface, MoveAllVisitorsInterface, MoveVisitorInterface, OpenIframeInterface, RemoveClickableLinkInterface, ResponseType, SDKController, SDKInterface, Scene, SceneFactory, SceneInterface, SceneOptionalInterface, SetClickableLinkMultiInterface, Topia, TopiaInterface, UpdateBroadcastInterface, UpdateClickTypeInterface, UpdateClickableLinkMultiInterface, UpdateDroppedAssetInterface, UpdateMediaTypeInterface, UpdatePrivateZoneInterface, User, UserFactory, UserInterface, UserInventoryItemInterface, UserInventoryItemMetadataType, UserInventoryItemOptionalInterface, UserOptionalInterface, UserOptions, Visitor, VisitorFactory, VisitorInterface, VisitorOptionalInterface, VisitorOptions, VisitorType, VisitorsToMoveArrayType, VisitorsToMoveType, WebRTCConnector, WebRTCConnectorFactory, WebRTCConnectorInterface, WebRTCConnectorOptionalInterface, WebhookInterface, World, WorldActivity, WorldActivityFactory, WorldActivityOptionalInterface, WorldActivityType, WorldDetailsInterface, WorldFactory, WorldInterface, WorldOptionalInterface, WorldOptions, WorldWebhooksInterface };
+export { AnalyticType, AnimationMetaType, Asset, AssetFactory, AssetInterface, AssetOptionalInterface, AssetOptions, AssetType, CreateNpcOptions, DroppedAsset, DroppedAssetClickType, DroppedAssetFactory, DroppedAssetInterface, DroppedAssetLinkType, DroppedAssetMediaType, DroppedAssetMediaVolumeRadius, DroppedAssetOptionalInterface, DroppedAssetOptions, Ecosystem, EcosystemFactory, EcosystemInterface, EcosystemOptionalInterface, FireToastInterface, FrameType, InteractiveCredentials$1 as InteractiveCredentials, InventoryItemInterface, InventoryItemOptionalInterface, MoveAllVisitorsInterface, MoveVisitorInterface, NpcVoiceConfigInterface, OpenIframeInterface, RemoveClickableLinkInterface, ResponseType, SDKController, SDKInterface, Scene, SceneFactory, SceneInterface, SceneOptionalInterface, SetClickableLinkMultiInterface, SpawnEffectConfig, Topia, TopiaInterface, UpdateBroadcastInterface, UpdateClickTypeInterface, UpdateClickableLinkMultiInterface, UpdateDroppedAssetInterface, UpdateMediaTypeInterface, UpdatePrivateZoneInterface, User, UserFactory, UserInterface, UserInventoryItemInterface, UserInventoryItemMetadataType, UserInventoryItemOptionalInterface, UserOptionalInterface, UserOptions, Visitor, VisitorFactory, VisitorInterface, VisitorOptionalInterface, VisitorOptions, VisitorType, VisitorsToMoveArrayType, VisitorsToMoveType, WebRTCConnector, WebRTCConnectorFactory, WebRTCConnectorInterface, WebRTCConnectorOptionalInterface, WebhookInterface, World, WorldActivity, WorldActivityFactory, WorldActivityOptionalInterface, WorldActivityType, WorldDetailsInterface, WorldFactory, WorldInterface, WorldOptionalInterface, WorldOptions, WorldWebhooksInterface };

package/dist/index.js

@@ -39725,11 +39725,6 @@ class SDKController {
      *
      * @keywords error, exception, handler, debugging, api error, http error
      *
-     * @param error - The error object from the failed operation (AxiosError, Error, or unknown)
-     * @param message - Optional custom error message (defaults to generic message)
-     * @param params - Optional parameters that were passed to the failed method
-     * @param sdkMethod - Optional name of the SDK method that failed (e.g., "World.fetchDetails")
-     *
      * @returns {object} Standardized error object with properties: data, message, method, params, sdkMethod, stack, status, success, url
      */
     errorHandler({ error, message = "Something went wrong. Please try again or contact support.", params = {}, sdkMethod, }) {
@@ -43668,7 +43663,13 @@ class Visitor extends User {
     createNpc(userInventoryItemId, options) {
         return __awaiter(this, void 0, void 0, function* () {
             try {
-                const response = yield this.topiaPublicApi().post(`/world/${this.urlSlug}/visitors/${this.id}/create-npc`, { userInventoryItemId, showNameplate: options === null || options === void 0 ? void 0 : options.showNameplate }, this.requestOptions);
+                const response = yield this.topiaPublicApi().post(`/world/${this.urlSlug}/visitors/${this.id}/create-npc`, {
+                    userInventoryItemId,
+                    showNameplate: options === null || options === void 0 ? void 0 : options.showNameplate,
+                    stationary: options === null || options === void 0 ? void 0 : options.stationary,
+                    replace: options === null || options === void 0 ? void 0 : options.replace,
+                    spawnEffect: options === null || options === void 0 ? void 0 : options.spawnEffect,
+                }, this.requestOptions);
                 return new Visitor(this.topia, response.data.player.playerId, this.urlSlug, {
                     attributes: response.data,
                     credentials: this.credentials,
@@ -43713,6 +43714,77 @@ class Visitor extends User {
             }
         });
     }
+    /**
+     * Start an AI voice session for this visitor's NPC.
+     *
+     * @remarks
+     * Establishes a real-time voice connection between the visitor and an AI backend
+     * (currently OpenAI Realtime API) through the NPC. The NPC must already be spawned
+     * via `createNpc()` before calling this method.
+     *
+     * The voice session occupies a video slot in the visitor's peer video grid, showing
+     * the NPC's avatar image. Audio streams bidirectionally between the visitor's microphone
+     * and the AI model. Only the NPC's owner hears the AI audio.
+     *
+     * Topia automatically prepends non-removable child safety guardrails to the instructions.
+     * Only one voice session is allowed per visitor per world at a time.
+     *
+     * @keywords voice, npc, ai, chat, audio, realtime, session, start, speech
+     *
+     * @category NPCs
+     *
+     * @param config - Voice session configuration including ephemeral key and AI instructions
+     *
+     * @example
+     * ```ts
+     * const ephemeralKey = await generateOpenAIEphemeralKey();
+     *
+     * await visitor.startNpcVoiceSession({
+     *   ephemeralKey,
+     *   voice: "alloy",
+     *   instructions: "You are a friendly science tutor helping with photosynthesis.",
+     *   model: "gpt-4o-realtime-preview",
+     * });
+     * ```
+     *
+     * @returns {Promise<void | ResponseType>} Returns `{ success: true }` or an error.
+     */
+    startNpcVoiceSession(config) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const response = yield this.topiaPublicApi().put(`/world/${this.urlSlug}/visitors/${this.id}/start-npc-voice-session`, { voiceConfig: config }, this.requestOptions);
+                return response.data;
+            }
+            catch (error) {
+                throw this.errorHandler({ error, params: config, sdkMethod: "Visitor.startNpcVoiceSession" });
+            }
+        });
+    }
+    /**
+     * Stop the active AI voice session for this visitor's NPC.
+     *
+     * @keywords voice, npc, ai, chat, audio, realtime, session, stop, end
+     *
+     * @category NPCs
+     *
+     * @example
+     * ```ts
+     * await visitor.stopNpcVoiceSession();
+     * ```
+     *
+     * @returns {Promise<void | ResponseType>} Returns `{ success: true }` or an error.
+     */
+    stopNpcVoiceSession() {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const response = yield this.topiaPublicApi().put(`/world/${this.urlSlug}/visitors/${this.id}/stop-npc-voice-session`, {}, this.requestOptions);
+                return response.data;
+            }
+            catch (error) {
+                throw this.errorHandler({ error, sdkMethod: "Visitor.stopNpcVoiceSession" });
+            }
+        });
+    }
     /**
      * Retrieves all inventory items owned by this visitor and app's key.
      *

package/package.json

@@ -61,5 +61,5 @@
     "yalc-push": "yarn build && yalc publish --push --dev --no-scripts"
   },
   "type": "module",
-  "version": "0.19.04"
+  "version": "0.19.06"
 }