@rtsdk/topia 0.19.5 → 0.19.6

package/dist/index.cjs

@@ -43665,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,
@@ -43710,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

@@ -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

@@ -43663,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,
@@ -43708,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.05"
+  "version": "0.19.06"
 }