@rtsdk/topia 0.19.5 → 0.19.7

package/dist/index.cjs

@@ -39751,6 +39751,11 @@ class SDKController {
             errorMessage = (error === null || error === void 0 ? void 0 : error.message) || message;
             stack = `${error.stack}\n${stackTrace.stack}`;
         }
+        else if (error !== undefined && error !== null) {
+            // Handle bare string throws and other non-Error types
+            errorMessage = typeof error === "string" ? error : JSON.stringify(error);
+            stack = stackTrace.stack || "empty";
+        }
         return {
             data,
             message: errorMessage,
@@ -42258,6 +42263,7 @@ AI RULES for code assistants
  */
 class User extends SDKController {
     constructor(topia, options = { profileId: null, credentials: {} }) {
+        var _a;
         super(topia, Object.assign({ profileId: options === null || options === void 0 ? void 0 : options.profileId }, options.credentials));
         _User_userInventoryItems.set(this, void 0);
         _User_adminWorldsMap.set(this, void 0);
@@ -42265,6 +42271,13 @@ class User extends SDKController {
         _User_scenesMap.set(this, void 0);
         _User_worldsMap.set(this, void 0);
         this.profileId = options === null || options === void 0 ? void 0 : options.profileId;
+        // Warn devs about common mistake: passing profileId only inside credentials
+        if (!this.profileId && ((_a = options === null || options === void 0 ? void 0 : options.credentials) === null || _a === void 0 ? void 0 : _a.profileId)) {
+            console.warn(`[@rtsdk/topia] User created without top-level profileId. ` +
+                `You passed profileId inside credentials but not in options. ` +
+                `Methods like grantInventoryItem will fail. ` +
+                `Fix: User.create({ profileId: "${options.credentials.profileId}", credentials: { ... } })`);
+        }
         this.dataObject = {};
         this.profile = {};
         __classPrivateFieldSet(this, _User_adminWorldsMap, {}, "f");
@@ -42778,7 +42791,7 @@ class User extends SDKController {
         return __awaiter(this, void 0, void 0, function* () {
             try {
                 if (!this.profileId)
-                    throw "This method requires the use of a profileId";
+                    throw new Error("This method requires the use of a profileId. Pass profileId as a top-level option: User.create({ profileId, credentials: { ... } })");
                 let query = "";
                 if (appPublicKey)
                     query = `?appPublicKey=${appPublicKey}&appJWT=${appJWT}`;
@@ -42818,7 +42831,7 @@ class User extends SDKController {
         return __awaiter(this, void 0, void 0, function* () {
             try {
                 if (!this.profileId)
-                    throw "This method requires the use of a profileId";
+                    throw new Error("This method requires the use of a profileId. Pass profileId as a top-level option: User.create({ profileId, credentials: { ... } })");
                 yield this.topiaPublicApi().put(`/user/dataObjects/${this.profileId}/set-data-object`, Object.assign(Object.assign({}, options), { dataObject: dataObject || this.dataObject }), this.requestOptions);
                 this.dataObject = dataObject || this.dataObject;
             }
@@ -42852,7 +42865,7 @@ class User extends SDKController {
         return __awaiter(this, void 0, void 0, function* () {
             try {
                 if (!this.profileId)
-                    throw "This method requires the use of a profileId";
+                    throw new Error("This method requires the use of a profileId. Pass profileId as a top-level option: User.create({ profileId, credentials: { ... } })");
                 yield this.topiaPublicApi().put(`/user/dataObjects/${this.profileId}/update-data-object`, Object.assign(Object.assign({}, options), { dataObject: dataObject || this.dataObject }), this.requestOptions);
                 this.dataObject = Object.assign(Object.assign({}, (this.dataObject || {})), (dataObject || {}));
             }
@@ -42902,7 +42915,7 @@ class User extends SDKController {
         return __awaiter(this, void 0, void 0, function* () {
             try {
                 if (!this.profileId)
-                    throw "This method requires the use of a profileId";
+                    throw new Error("This method requires the use of a profileId. Pass profileId as a top-level option: User.create({ profileId, credentials: { ... } })");
                 const response = yield this.topiaPublicApi().get(`/user/inventory/${this.profileId}/get-user-inventory-items`, this.requestOptions);
                 // TODO: Replace 'object' with InventoryItem and instantiate InventoryItem objects if needed
                 const tempItems = [];
@@ -42915,7 +42928,7 @@ class User extends SDKController {
                 __classPrivateFieldSet(this, _User_userInventoryItems, tempItems, "f");
             }
             catch (error) {
-                throw this.errorHandler({ error, sdkMethod: "Visitor.fetchInventoryItems" });
+                throw this.errorHandler({ error, sdkMethod: "User.fetchInventoryItems" });
             }
         });
     }
@@ -42939,7 +42952,7 @@ class User extends SDKController {
         return __awaiter(this, void 0, void 0, function* () {
             try {
                 if (!this.profileId)
-                    throw "This method requires the use of a profileId";
+                    throw new Error("This method requires the use of a profileId. Pass profileId as a top-level option: User.create({ profileId, credentials: { ... } })");
                 const response = yield this.topiaPublicApi().put(`/user/inventory/${this.profileId}/grant-user-inventory-item`, { itemId: item.id, quantity }, this.requestOptions);
                 const userInventoryItemFactory = new UserInventoryItemFactory(this.topia);
                 const { inventoryItem, user_id, quantity: newQuantity } = response.data;
@@ -42949,7 +42962,7 @@ class User extends SDKController {
                 });
             }
             catch (error) {
-                throw this.errorHandler({ error, sdkMethod: "Visitor.grantInventoryItem" });
+                throw this.errorHandler({ error, sdkMethod: "User.grantInventoryItem" });
             }
         });
     }
@@ -42970,7 +42983,7 @@ class User extends SDKController {
         return __awaiter(this, void 0, void 0, function* () {
             try {
                 if (!this.profileId)
-                    throw "This method requires the use of a profileId";
+                    throw new Error("This method requires the use of a profileId. Pass profileId as a top-level option: User.create({ profileId, credentials: { ... } })");
                 const response = yield this.topiaPublicApi().put(`/user/inventory/${this.profileId}/update-user-inventory-item-quantity`, { userItemId: item.id, itemId: item.item_id, quantity }, this.requestOptions);
                 const userInventoryItemFactory = new UserInventoryItemFactory(this.topia);
                 const { inventoryItem, user_id, quantity: newQuantity } = response.data;
@@ -42980,7 +42993,7 @@ class User extends SDKController {
                 });
             }
             catch (error) {
-                throw this.errorHandler({ error, sdkMethod: "Visitor.modifyInventoryItemQuantity" });
+                throw this.errorHandler({ error, sdkMethod: "User.modifyInventoryItemQuantity" });
             }
         });
     }
@@ -43665,7 +43678,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,
@@ -43710,6 +43729,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

@@ -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.
      *
@@ -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;
@@ -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;
@@ -4185,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$1 as 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

@@ -39749,6 +39749,11 @@ class SDKController {
             errorMessage = (error === null || error === void 0 ? void 0 : error.message) || message;
             stack = `${error.stack}\n${stackTrace.stack}`;
         }
+        else if (error !== undefined && error !== null) {
+            // Handle bare string throws and other non-Error types
+            errorMessage = typeof error === "string" ? error : JSON.stringify(error);
+            stack = stackTrace.stack || "empty";
+        }
         return {
             data,
             message: errorMessage,
@@ -42256,6 +42261,7 @@ AI RULES for code assistants
  */
 class User extends SDKController {
     constructor(topia, options = { profileId: null, credentials: {} }) {
+        var _a;
         super(topia, Object.assign({ profileId: options === null || options === void 0 ? void 0 : options.profileId }, options.credentials));
         _User_userInventoryItems.set(this, void 0);
         _User_adminWorldsMap.set(this, void 0);
@@ -42263,6 +42269,13 @@ class User extends SDKController {
         _User_scenesMap.set(this, void 0);
         _User_worldsMap.set(this, void 0);
         this.profileId = options === null || options === void 0 ? void 0 : options.profileId;
+        // Warn devs about common mistake: passing profileId only inside credentials
+        if (!this.profileId && ((_a = options === null || options === void 0 ? void 0 : options.credentials) === null || _a === void 0 ? void 0 : _a.profileId)) {
+            console.warn(`[@rtsdk/topia] User created without top-level profileId. ` +
+                `You passed profileId inside credentials but not in options. ` +
+                `Methods like grantInventoryItem will fail. ` +
+                `Fix: User.create({ profileId: "${options.credentials.profileId}", credentials: { ... } })`);
+        }
         this.dataObject = {};
         this.profile = {};
         __classPrivateFieldSet(this, _User_adminWorldsMap, {}, "f");
@@ -42776,7 +42789,7 @@ class User extends SDKController {
         return __awaiter(this, void 0, void 0, function* () {
             try {
                 if (!this.profileId)
-                    throw "This method requires the use of a profileId";
+                    throw new Error("This method requires the use of a profileId. Pass profileId as a top-level option: User.create({ profileId, credentials: { ... } })");
                 let query = "";
                 if (appPublicKey)
                     query = `?appPublicKey=${appPublicKey}&appJWT=${appJWT}`;
@@ -42816,7 +42829,7 @@ class User extends SDKController {
         return __awaiter(this, void 0, void 0, function* () {
             try {
                 if (!this.profileId)
-                    throw "This method requires the use of a profileId";
+                    throw new Error("This method requires the use of a profileId. Pass profileId as a top-level option: User.create({ profileId, credentials: { ... } })");
                 yield this.topiaPublicApi().put(`/user/dataObjects/${this.profileId}/set-data-object`, Object.assign(Object.assign({}, options), { dataObject: dataObject || this.dataObject }), this.requestOptions);
                 this.dataObject = dataObject || this.dataObject;
             }
@@ -42850,7 +42863,7 @@ class User extends SDKController {
         return __awaiter(this, void 0, void 0, function* () {
             try {
                 if (!this.profileId)
-                    throw "This method requires the use of a profileId";
+                    throw new Error("This method requires the use of a profileId. Pass profileId as a top-level option: User.create({ profileId, credentials: { ... } })");
                 yield this.topiaPublicApi().put(`/user/dataObjects/${this.profileId}/update-data-object`, Object.assign(Object.assign({}, options), { dataObject: dataObject || this.dataObject }), this.requestOptions);
                 this.dataObject = Object.assign(Object.assign({}, (this.dataObject || {})), (dataObject || {}));
             }
@@ -42900,7 +42913,7 @@ class User extends SDKController {
         return __awaiter(this, void 0, void 0, function* () {
             try {
                 if (!this.profileId)
-                    throw "This method requires the use of a profileId";
+                    throw new Error("This method requires the use of a profileId. Pass profileId as a top-level option: User.create({ profileId, credentials: { ... } })");
                 const response = yield this.topiaPublicApi().get(`/user/inventory/${this.profileId}/get-user-inventory-items`, this.requestOptions);
                 // TODO: Replace 'object' with InventoryItem and instantiate InventoryItem objects if needed
                 const tempItems = [];
@@ -42913,7 +42926,7 @@ class User extends SDKController {
                 __classPrivateFieldSet(this, _User_userInventoryItems, tempItems, "f");
             }
             catch (error) {
-                throw this.errorHandler({ error, sdkMethod: "Visitor.fetchInventoryItems" });
+                throw this.errorHandler({ error, sdkMethod: "User.fetchInventoryItems" });
             }
         });
     }
@@ -42937,7 +42950,7 @@ class User extends SDKController {
         return __awaiter(this, void 0, void 0, function* () {
             try {
                 if (!this.profileId)
-                    throw "This method requires the use of a profileId";
+                    throw new Error("This method requires the use of a profileId. Pass profileId as a top-level option: User.create({ profileId, credentials: { ... } })");
                 const response = yield this.topiaPublicApi().put(`/user/inventory/${this.profileId}/grant-user-inventory-item`, { itemId: item.id, quantity }, this.requestOptions);
                 const userInventoryItemFactory = new UserInventoryItemFactory(this.topia);
                 const { inventoryItem, user_id, quantity: newQuantity } = response.data;
@@ -42947,7 +42960,7 @@ class User extends SDKController {
                 });
             }
             catch (error) {
-                throw this.errorHandler({ error, sdkMethod: "Visitor.grantInventoryItem" });
+                throw this.errorHandler({ error, sdkMethod: "User.grantInventoryItem" });
             }
         });
     }
@@ -42968,7 +42981,7 @@ class User extends SDKController {
         return __awaiter(this, void 0, void 0, function* () {
             try {
                 if (!this.profileId)
-                    throw "This method requires the use of a profileId";
+                    throw new Error("This method requires the use of a profileId. Pass profileId as a top-level option: User.create({ profileId, credentials: { ... } })");
                 const response = yield this.topiaPublicApi().put(`/user/inventory/${this.profileId}/update-user-inventory-item-quantity`, { userItemId: item.id, itemId: item.item_id, quantity }, this.requestOptions);
                 const userInventoryItemFactory = new UserInventoryItemFactory(this.topia);
                 const { inventoryItem, user_id, quantity: newQuantity } = response.data;
@@ -42978,7 +42991,7 @@ class User extends SDKController {
                 });
             }
             catch (error) {
-                throw this.errorHandler({ error, sdkMethod: "Visitor.modifyInventoryItemQuantity" });
+                throw this.errorHandler({ error, sdkMethod: "User.modifyInventoryItemQuantity" });
             }
         });
     }
@@ -43663,7 +43676,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,
@@ -43708,6 +43727,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.05"
+  "version": "0.19.07"
 }