@rtsdk/topia 0.19.3 → 0.19.4

package/dist/index.cjs

@@ -39613,25 +39613,53 @@ const {
 } = axios;
 
 // utils
+/* ============================================================================
+AI RULES for code assistants
+
+  CONTEXT
+    - SDKController is the abstract base class for all SDK controllers.
+    - All controllers (World, Visitor, User, etc.) extend this class.
+    - This class provides common functionality: authentication, API access, and error handling.
+    - This SDK is installed as an NPM package (@rtsdk/topia) in consumer applications.
+
+  DO
+    - Understand that all controllers inherit these base methods and properties.
+    - Use the error handling pattern defined in errorHandler() for all SDK errors.
+    - Access the Topia Public API through topiaPublicApi() method.
+
+  DO NOT
+    - Do NOT instantiate SDKController directly; it's an abstract class.
+    - Do NOT bypass the error handler; all errors should flow through errorHandler().
+    - Do NOT access this.topia.axios directly; use topiaPublicApi() instead.
+
+  AVAILABLE METHODS:
+    - topiaPublicApi(): Returns configured Axios instance for API calls
+    - errorHandler(options): Standardized error handling for all SDK operations
+
+  INHERITED BY:
+    All controllers inherit from this base class, including:
+    - World, Visitor, User, Asset, DroppedAsset, Scene, WorldActivity, Ecosystem
+
+============================================================================ */
 /**
- * Create an instance of SDKController class with credentials.
+ * Abstract base controller that provides common functionality for all SDK controllers.
+ *
+ * @remarks
+ * This class should NOT be instantiated directly. It serves as the base class for all
+ * SDK controllers (World, Visitor, User, etc.) and provides:
+ * - Authentication and credential management
+ * - Axios instance configuration for API calls
+ * - Standardized error handling
+ * - JWT token generation for interactive credentials
+ *
+ * @keywords base, controller, sdk, authentication, api, abstract
  *
  * @example
  * ```ts
- * const credentials = {
- *   assetId: "exampleAsset",
- *   interactiveNonce: "exampleNonce"
- *   interactivePublicKey: "examplePublicKey",
- *   visitorId: 1,
- *   url: "https://topia.io",
- * }
- * const topia = await new Topia({
- *   apiDomain: "api.topia.io",
- *   apiKey: "exampleKey",
- *   interactiveKey: "key",
- *   interactiveSecret: "secret",
+ * // This class is extended by all controllers
+ * export class World extends SDKController implements WorldInterface {
+ *   // World-specific implementation
  * }
- * await new SDKController({ credentials, topia });
  * ```
  */
 class SDKController {
@@ -39670,9 +39698,42 @@ class SDKController {
             this.errorHandler({ error });
         }
     }
+    /**
+     * Returns the configured Axios instance for making API calls to Topia's Public API.
+     *
+     * @remarks
+     * All HTTP requests to the Topia API should use this method to ensure proper
+     * authentication headers and base URL configuration are applied.
+     *
+     * @keywords api, axios, http, request, client, public api
+     *
+     * @returns {AxiosInstance} The configured Axios client instance with authentication headers.
+     */
     topiaPublicApi() {
         return this.topia.axios;
     }
+    /**
+     * Standardized error handler for all SDK operations.
+     *
+     * @remarks
+     * This method processes errors from API calls and formats them consistently across the SDK.
+     * It extracts relevant error information including:
+     * - HTTP status codes and response data
+     * - Error messages from API responses
+     * - Stack traces for debugging
+     * - Request details (URL, method, parameters)
+     *
+     * All errors thrown by SDK methods flow through this handler to ensure consistent error format.
+     *
+     * @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, }) {
         var _a, _b;
         const stackTrace = new Error("Thrown here:");
@@ -39716,6 +39777,7 @@ AI RULES for code assistants
   CONTEXT
     - "Controllers" expose operations on domain objects (e.g., Asset).
     - Consumers obtain controller instances via factory methods (e.g., AssetFactory.get).
+    - This SDK is installed as an NPM package (@rtsdk/topia) in consumer applications.
 
   DO
     - Expect consumers to import a pre-instantiated factory from their app (e.g., utils/topiaInit.ts).
@@ -39726,6 +39788,10 @@ AI RULES for code assistants
     - Do NOT suggest non-existent methods: getById, fetch, find
     - Do NOT mutate controller shape or return ad-hoc fields.
 
+  AVAILABLE METHODS:
+    - fetchAssetById(): Retrieves platform asset details
+    - updateAsset(options): Updates asset properties (name, layers, tags, visibility)
+
   CANONICAL USAGE (consumer app):
     // utils/topiaInit.ts
     import { Topia, AssetFactory } from "@rtsdk/topia";
@@ -39887,6 +39953,7 @@ AI RULES for code assistants
   CONTEXT
     - "Controllers" expose operations on domain objects (e.g., DroppedAsset).
     - Consumers obtain controller instances via factory methods (e.g., DroppedAssetFactory.get).
+    - This SDK is installed as an NPM package (@rtsdk/topia) in consumer applications.
 
   DO
     - Expect consumers to import a pre-instantiated factory from their app (e.g., utils/topiaInit.ts).
@@ -39897,6 +39964,35 @@ AI RULES for code assistants
     - Do NOT suggest non-existent methods: getById, fetch, find
     - Do NOT mutate controller shape or return ad-hoc fields.
 
+  AVAILABLE METHODS:
+    - fetchDroppedAssetById(): Retrieves dropped asset details
+    - updateDroppedAsset(options): Updates dropped asset properties
+    - deleteDroppedAsset(): Removes the dropped asset from the world
+    - fetchDataObject(appPublicKey?, appJWT?, sharedAppPublicKey?, sharedAppJWT?): Gets asset's data object
+    - setDataObject(dataObject, options?): Sets asset's entire data object
+    - updateDataObject(dataObject, options?): Updates specific fields in data object
+    - incrementDataObjectValue(path, amount, options?): Increments numeric value
+    - updateBroadcast(options): Updates broadcast settings
+    - updateClickType(options): Updates click behavior and link settings
+    - setClickableLinkMulti(options): Adds multiple links to asset
+    - updateClickableLinkMulti(options): Updates specific clickable link
+    - removeClickableLink(options): Removes a clickable link
+    - updateCustomTextAsset(style, text): Updates text and styling
+    - updateMediaType(options): Updates media (video/audio) settings
+    - updateMuteZone(isMutezone): Toggles mute zone
+    - updateLandmarkZone(options): Updates landmark zone settings
+    - updateWebhookZone(isEnabled): Toggles webhook zone
+    - updatePosition(x, y, yOrderAdjust?): Moves the asset
+    - updatePrivateZone(options): Updates private zone settings
+    - updateScale(assetScale): Changes asset size
+    - flip(): Flips the asset horizontally
+    - updateUploadedMediaSelected(mediaId): Changes embedded media
+    - updateWebImageLayers(bottom, top): Updates image layers
+    - addWebhook(options): Adds a webhook to the asset
+    - setInteractiveSettings(options): Configures interactive settings
+    - checkExists(): Verifies asset exists with app's public key
+    - fetchDroppedAssetAnalytics(options): Gets analytics data for the asset
+
   CANONICAL USAGE (consumer app):
     // utils/topiaInit.ts
     import { Topia, DroppedAssetFactory } from "@rtsdk/topia";
@@ -40786,12 +40882,17 @@ class InventoryItem extends SDKController {
     /**
      * Fetches the inventory item details from the platform and assigns them to this instance.
      *
+     * @keywords get, fetch, retrieve, load, inventory, item, details
+     *
+     * @category Inventory
+     *
      * @example
      * ```ts
      * await item.fetchInventoryItemById();
+     * const { name, description, type } = item;
      * ```
      *
-     * @returns {Promise<InventoryItem>} Returns when the item has been fetched and assigned.
+     * @returns {Promise<InventoryItem>} Returns this InventoryItem instance with all properties populated from the platform.
      */
     fetchInventoryItemById() {
         return __awaiter(this, void 0, void 0, function* () {
@@ -40819,6 +40920,13 @@ AI RULES for code assistants
     - Do NOT suggest non-existent methods: getById, fetch, find
     - Do NOT mutate controller shape or return ad-hoc fields.
 
+  AVAILABLE METHODS:
+    - fetchDataObject(appPublicKey?, appJWT?, sharedAppPublicKey?, sharedAppJWT?): Retrieves ecosystem-wide data object
+    - setDataObject(dataObject, options?): Sets entire ecosystem data object
+    - updateDataObject(dataObject, options?): Updates specific fields in ecosystem data object
+    - incrementDataObjectValue(path, amount, options?): Increments a numeric value in ecosystem data
+    - fetchInventoryItems(): Retrieves all inventory items for the app's keyholder
+
   CANONICAL USAGE (consumer app):
     // utils/topiaInit.ts
     import { Topia, Ecosystem } from "@rtsdk/topia";
@@ -40853,7 +40961,7 @@ class Ecosystem extends SDKController {
     /**
      * Retrieves the data object for a Topia ecosystem. Requires canUpdateEcosystemDataObjects permission to be set to true for the public key.
      *
-     * @keywords get, fetch, retrieve, load, data, object, state
+     * @keywords get, fetch, retrieve, load, ecosystem, data, object, state, global, platform
      *
      * @category Data Objects
      *
@@ -40862,7 +40970,7 @@ class Ecosystem extends SDKController {
      * const dataObject = await ecosystem.fetchDataObject("exampleAppPublicKey", "exampleAppPublicKeyJWT");
      * ```
      *
-     * @returns {Promise<object | ResponseType>} Returns the data object or an error response.
+     * @returns {Promise<void | ResponseType>} Populates the dataObject property with ecosystem-wide data, or returns an error response.
      */
     fetchDataObject(appPublicKey, appJWT, sharedAppPublicKey, sharedAppJWT) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -40889,7 +40997,7 @@ class Ecosystem extends SDKController {
      *
      * Optionally, a lock can be provided with this request to ensure only one update happens at a time between all updates that share the same lock id
      *
-     * @keywords set, assign, store, save, data, object, state
+     * @keywords set, assign, store, save, ecosystem, data, object, state, global, platform
      *
      * @category Data Objects
      *
@@ -40901,6 +41009,8 @@ class Ecosystem extends SDKController {
      * });
      * const { exampleKey } = ecosystem.dataObject;
      * ```
+     *
+     * @returns {Promise<void | ResponseType>} Returns success or an error response.
      */
     setDataObject(dataObject, options = {}) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -40921,7 +41031,7 @@ class Ecosystem extends SDKController {
      *
      * Optionally, a lock can be provided with this request to ensure only one update happens at a time between all updates that share the same lock id
      *
-     * @keywords update, modify, change, edit, alter, data, object, state
+     * @keywords update, modify, change, edit, alter, ecosystem, data, object, state, global, platform
      *
      * @category Data Objects
      *
@@ -40939,6 +41049,8 @@ class Ecosystem extends SDKController {
      * });
      * const { exampleKey } = ecosystem.dataObject;
      * ```
+     *
+     * @returns {Promise<void | ResponseType>} Returns success or an error response.
      */
     updateDataObject(dataObject, options = {}) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -40959,7 +41071,7 @@ class Ecosystem extends SDKController {
      *
      * Optionally, a lock can be provided with this request to ensure only one update happens at a time between all updates that share the same lock id
      *
-     * @keywords increment, increase, add, count, data, object, state
+     * @keywords increment, increase, add, count, ecosystem, data, object, state, global, platform
      *
      * @category Data Objects
      *
@@ -40970,6 +41082,8 @@ class Ecosystem extends SDKController {
      *   sharedAppJWT: "exampleAppPublicKeyJWT",}
      * });
      * ```
+     *
+     * @returns {Promise<void | ResponseType>} Returns success or an error response.
      */
     incrementDataObjectValue(path, amount, options = {}) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -40988,14 +41102,17 @@ class Ecosystem extends SDKController {
     /**
      * Retrieves all inventory items for a given keyholder (app public key).
      *
-     * @keywords get, fetch, retrieve, list, inventory, items, keyholder
+     * @keywords get, fetch, retrieve, list, inventory, items, keyholder, ecosystem, catalog
+     *
+     * @category Inventory
      *
      * @example
      * ```ts
-     * const items = await ecosystem.fetchInventoryItems("appPublicKey", "appJWT");
+     * await ecosystem.fetchInventoryItems();
+     * const items = ecosystem.inventoryItems;
      * ```
      *
-     * @returns {Promise<object[]>} Returns an array of InventoryItem objects.
+     * @returns {Promise<void>} Populates the inventoryItems property with an array of InventoryItem objects.
      */
     fetchInventoryItems() {
         return __awaiter(this, void 0, void 0, function* () {
@@ -41029,6 +41146,10 @@ _Ecosystem_inventoryItems = new WeakMap();
  *
  * @remarks
  * This class should be instantiated via UserInventoryItemFactory only.
+ * UserInventoryItem represents an instance of an InventoryItem owned by a specific user or visitor.
+ * It includes ownership details like quantity, grant_source, and user-specific metadata.
+ *
+ * @keywords inventory, item, user, visitor, owned, granted
  *
  * @property inventoryItemId - The root inventory item's id
  */
@@ -41039,12 +41160,13 @@ class UserInventoryItem extends InventoryItem {
         super(topia, item_id, { attributes: options.attributes, credentials: options.credentials });
         Object.assign(this, options.attributes);
         this.userItemId = id;
-        const { user_id = "", quantity = 0, grant_source = "unknown", type = "unknown", metadata = {}, created_at = new Date(), updated_at = new Date(), profile_id = null, item = { id: "", name: "", description: "", type: "", metadata: null, image_url: "" }, } = options.attributes;
+        const { user_id = "", quantity = 0, grant_source = "unknown", type = "unknown", image_url = "", metadata = {}, created_at = new Date(), updated_at = new Date(), profile_id = null, item = { id: "", name: "", description: "", type: "", metadata: null, image_url: "" }, } = options.attributes;
         this.item_id = item_id;
         this.quantity = quantity;
         this.grant_source = grant_source;
         this.user_id = user_id;
         this.type = type;
+        this.image_url = image_url;
         this.metadata = metadata;
         this.created_at = created_at;
         this.updated_at = updated_at;
@@ -41054,12 +41176,17 @@ class UserInventoryItem extends InventoryItem {
     /**
      * Fetches the user inventory item details from the platform and assigns them to this instance.
      *
+     * @keywords get, fetch, retrieve, load, user, inventory, item, details, owned
+     *
+     * @category Inventory
+     *
      * @example
      * ```ts
      * await userInventoryItem.fetchUserInventoryItemById();
+     * const { quantity, grant_source, item } = userInventoryItem;
      * ```
      *
-     * @returns {Promise<void>} Returns when the item has been fetched and assigned.
+     * @returns {Promise<void>} Populates this UserInventoryItem instance with all properties from the platform.
      */
     fetchUserInventoryItemById() {
         return __awaiter(this, void 0, void 0, function* () {
@@ -41077,6 +41204,7 @@ AI RULES for code assistants
   CONTEXT
     - "Controllers" expose operations on domain objects (e.g., Scene).
     - Consumers obtain controller instances via factory methods (e.g., SceneFactory.get).
+    - This SDK is installed as an NPM package (@rtsdk/topia) in consumer applications.
 
   DO
     - Expect consumers to import a pre-instantiated factory from their app (e.g., utils/topiaInit.ts).
@@ -41087,6 +41215,9 @@ AI RULES for code assistants
     - Do NOT suggest non-existent methods: getById, fetch, find
     - Do NOT mutate controller shape or return ad-hoc fields.
 
+  AVAILABLE METHODS:
+    - fetchSceneById(): Retrieves scene details and configuration
+
   CANONICAL USAGE (consumer app):
     // utils/topiaInit.ts
     import { Topia, SceneFactory } from "@rtsdk/topia";
@@ -41096,6 +41227,7 @@ AI RULES for code assistants
     // controllers/myController.ts (consumer app)
     import { Scene } from "utils/topiaInit.ts";
     const scene = await Scene.get(sceneId, { credentials });
+    await scene.fetchSceneById();
 
 ============================================================================ */
 /**
@@ -41141,16 +41273,68 @@ class Scene extends SDKController {
     }
 }
 
+/* ============================================================================
+AI RULES for code assistants
+
+  CONTEXT
+    - Topia is the main client class that initializes the SDK.
+    - This class should be instantiated ONCE in the consumer app (e.g., utils/topiaInit.ts).
+    - The Topia instance is passed to all factory classes to create controllers.
+    - This SDK is installed as an NPM package (@rtsdk/topia) in consumer applications.
+
+  DO
+    - Expect consumers to create ONE Topia instance at app initialization.
+    - This instance is then used to instantiate all factories (WorldFactory, VisitorFactory, etc.).
+    - The Topia class configures the Axios client with proper authentication.
+
+  DO NOT
+    - Do NOT suggest creating multiple Topia instances; one per app is sufficient.
+    - Do NOT suggest instantiating controllers directly; always use factories.
+    - Do NOT modify the Axios instance after creation; configure it through constructor.
+
+  AVAILABLE METHODS:
+    - constructor(config): Initializes the Topia client with API credentials
+
+  CANONICAL USAGE (consumer app):
+    // utils/topiaInit.ts - Create ONE instance
+    import { Topia, WorldFactory, VisitorFactory } from "@rtsdk/topia";
+
+    const topia = new Topia({
+      apiKey: "your-api-key",
+      apiDomain: "api.topia.io",
+      interactiveKey: "your-public-key",
+      interactiveSecret: "your-secret-key",
+    });
+
+    export const World = new WorldFactory(topia);
+    export const Visitor = new VisitorFactory(topia);
+
+============================================================================ */
 /**
- * Create a single instance of Topia axios used for all calls to the public API in all classes
+ * Main Topia SDK client for configuring API access and authentication.
+ *
+ * @remarks
+ * This class should be instantiated ONCE per application at initialization time.
+ * The instance configures the Axios HTTP client with proper authentication headers
+ * and base URL, and is passed to all factory classes to create controllers.
+ *
+ * Configuration options:
+ * - apiKey: Your Topia API key for server-side authentication
+ * - interactiveKey/interactiveSecret: For interactive iframe applications
+ * - apiDomain: API endpoint domain (defaults to "api.topia.io")
+ * - apiProtocol: HTTP protocol (defaults to "https")
+ *
+ * @keywords topia, client, sdk, initialization, config, setup, api
  *
  * @example
  * ```ts
- * const topia = await new Topia({
+ * import { Topia } from "@rtsdk/topia";
+ *
+ * const topia = new Topia({
+ *   apiKey: "your-api-key",
  *   apiDomain: "api.topia.io",
- *   apiKey: "exampleKey",
- *   interactiveKey: "key",
- *   interactiveSecret: "secret",
+ *   interactiveKey: "your-public-key",
+ *   interactiveSecret: "your-secret-key",
  * });
  * ```
  */
@@ -41185,6 +41369,7 @@ AI RULES for code assistants
   CONTEXT
     - "Controllers" expose operations on domain objects (e.g., World).
     - Consumers obtain controller instances via factory methods (e.g., WorldFactory.get).
+    - This SDK is installed as an NPM package (@rtsdk/topia) in consumer applications.
 
   DO
     - Expect consumers to import a pre-instantiated factory from their app (e.g., utils/topiaInit.ts).
@@ -41195,6 +41380,30 @@ AI RULES for code assistants
     - Do NOT suggest non-existent methods: getById, fetch, find
     - Do NOT mutate controller shape or return ad-hoc fields.
 
+  AVAILABLE METHODS:
+    - fetchDetails(): Retrieves world details and settings
+    - updateDetails(options): Updates world settings (name, description, size, spawn position, controls)
+    - updateCloseWorldSettings(options): Updates world close/open settings
+    - fetchDroppedAssets(): Gets all dropped assets in the world
+    - fetchDroppedAssetsWithUniqueName(uniqueName): Gets dropped assets by unique name
+    - fetchDroppedAssetsBySceneDropId(sceneDropId): Gets dropped assets by scene drop ID
+    - updateCustomTextDroppedAssets(assets, style): Bulk updates text styling for assets
+    - fetchLandmarkZones(landmarkZoneName?, sceneDropId?): Gets landmark zones in the world
+    - fetchSceneDropIds(): Retrieves all scene drop IDs in the world
+    - fetchScenes(): Gets all scenes used in the world
+    - dropScene(options): Drops a scene into the world
+    - replaceScene(sceneId): Replaces entire world with a scene
+    - getAllParticles(): Gets all particle effects in the world
+    - triggerParticle(options): Triggers a particle effect
+    - triggerActivity(options): Triggers a world activity event
+    - fireToast(options): Shows toast notification to all visitors
+    - fetchDataObject(): Gets world's data object
+    - setDataObject(dataObject, options?): Sets world's entire data object
+    - updateDataObject(dataObject, options?): Updates specific fields in world data
+    - incrementDataObjectValue(path, amount, options?): Increments numeric value
+    - fetchWebhooks(): Gets all webhooks configured for the world
+    - fetchWorldAnalytics(options): Retrieves analytics data for the world
+
   CANONICAL USAGE (consumer app):
     // utils/topiaInit.ts
     import { Topia, WorldFactory } from "@rtsdk/topia";
@@ -41994,6 +42203,7 @@ AI RULES for code assistants
   CONTEXT
     - "Controllers" expose operations on domain objects (e.g., User).
     - Consumers obtain controller instances via factory methods (e.g., UserFactory.get).
+    - This SDK is installed as an NPM package (@rtsdk/topia) in consumer applications.
 
   DO
     - Expect consumers to import a pre-instantiated factory from their app (e.g., utils/topiaInit.ts).
@@ -42004,6 +42214,28 @@ AI RULES for code assistants
     - Do NOT suggest non-existent methods: getById, fetch, find
     - Do NOT mutate controller shape or return ad-hoc fields.
 
+  AVAILABLE METHODS:
+    - checkInteractiveCredentials(): Validates interactive credentials
+    - fetchAvatars(): Gets all avatars owned by the user
+    - addAvatar(formData): Uploads and creates a new avatar
+    - updateAvatar(avatarId, formData): Updates an existing avatar
+    - deleteAvatar(avatarId): Deletes an avatar
+    - fetchAssets(): Gets all assets owned by the user
+    - fetchPlatformAssets(): Gets platform-provided assets
+    - fetchScenes(): Gets all scenes owned by the user
+    - fetchWorldsByKey(): Gets worlds owned by the user
+    - fetchAdminWorldsByKey(): Gets worlds where user has admin access
+    - fetchInteractiveWorldsByKey(interactivePublicKey): Gets worlds with specific interactive key
+    - sendEmail(options): Sends an email through Topia's email service
+    - getExpressions(options): Gets avatar expressions/emotes
+    - fetchDataObject(appPublicKey?, appJWT?): Gets user's data object
+    - setDataObject(dataObject, options?): Sets user's entire data object
+    - updateDataObject(dataObject, options?): Updates specific fields in user data
+    - incrementDataObjectValue(path, amount, options?): Increments numeric value
+    - fetchInventoryItems(): Gets all inventory items owned by user
+    - grantInventoryItem(item, quantity?): Grants inventory item to user
+    - modifyInventoryItemQuantity(item, quantity): Updates inventory item quantity
+
   CANONICAL USAGE (consumer app):
     // utils/topiaInit.ts
     import { Topia, UserFactory } from "@rtsdk/topia";
@@ -42767,6 +42999,7 @@ AI RULES for code assistants
   CONTEXT
     - "Controllers" expose operations on domain objects (e.g., Visitor).
     - Consumers obtain controller instances via factory methods (e.g., VisitorFactory.get).
+    - This SDK is installed as an NPM package (@rtsdk/topia) in consumer applications.
 
   DO
     - Expect consumers to import a pre-instantiated factory from their app (e.g., utils/topiaInit.ts).
@@ -42775,7 +43008,25 @@ AI RULES for code assistants
   DO NOT
     - Do NOT suggest creating Topia clients or factories inside controllers.
     - Do NOT suggest non-existent methods: getById, fetch, find
-    - Do NOT mutate controller shape or return ad-hoc fields.
+    - DO NOT mutate controller shape or return ad-hoc fields.
+
+  AVAILABLE METHODS:
+    - fetchVisitor(): Retrieves visitor details from the world
+    - fetchDataObject(): Gets visitor's data object
+    - setDataObject(dataObject, options?): Sets visitor's entire data object
+    - updateDataObject(dataObject, options?): Updates specific fields in visitor data
+    - incrementDataObjectValue(path, amount, options?): Increments numeric value
+    - moveVisitor(options): Moves or teleports visitor to coordinates
+    - sendMessage(message): Sends chat message as the visitor
+    - openIframe(options): Opens iframe for this visitor
+    - closeIframe(): Closes visitor's open iframe
+    - fireToast(options): Shows toast notification to visitor
+    - getNpc(): Gets visitor's NPC if one exists
+    - createNpc(userInventoryItemId, options?): Creates NPC follower
+    - deleteNpc(): Removes visitor's NPC
+    - fetchInventoryItems(): Gets all inventory items owned by visitor
+    - grantInventoryItem(item, quantity?): Grants inventory item to visitor
+    - modifyInventoryItemQuantity(item, quantity): Updates inventory item quantity
 
   CANONICAL USAGE (consumer app):
     // utils/topiaInit.ts
@@ -43340,14 +43591,30 @@ class Visitor extends User {
         });
     }
     /**
-     * Gets an NPC for this visitor, if one exists.
+     * Retrieves the NPC (Non-Player Character) associated with this visitor, if one exists.
+     *
+     * @remarks
+     * Each visitor can have one NPC per application public key. NPCs are AI-controlled
+     * characters that follow the visitor around the world. They are created using inventory
+     * items of type "npc" and appear as additional avatars that track the visitor's position.
+     * If no NPC exists for this visitor and app, returns null.
+     *
+     * @keywords get, fetch, retrieve, npc, bot, follower, character, assistant, companion
+     *
+     * @category NPCs
      *
      * @example
      * ```ts
-     * await visitor.getNpc();
+     * const npc = await visitor.getNpc();
+     * if (npc) {
+     *   console.log(`NPC position: ${npc.position}`);
+     *   console.log(`NPC ID: ${npc.id}`);
+     * } else {
+     *   console.log('No NPC found for this visitor');
+     * }
      * ```
      *
-     * @returns {Promise<Visitor | null>} Returns a Visitor object representing the NPC.
+     * @returns {Promise<Visitor | null>} Returns a Visitor object representing the NPC, or null if none exists.
      */
     getNpc() {
         return __awaiter(this, void 0, void 0, function* () {
@@ -43366,12 +43633,25 @@ class Visitor extends User {
         });
     }
     /**
-     * Creates an NPC that follows this visitor using an inventory item the visitor owns.
-     * One NPC is allowed per visitor, per application public key.
+     * Creates an NPC (Non-Player Character) that follows this visitor using an inventory item the visitor owns.
+     *
+     * @remarks
+     * One NPC is allowed per visitor, per application public key. NPCs are AI-controlled
+     * characters that automatically follow the visitor around the world. They appear as
+     * additional avatars and can be useful for companions, guides, or assistant characters.
+     *
+     * Requirements:
+     * - The visitor must own a user inventory item of type "npc"
+     * - The item must have been granted to the visitor before calling this method
+     * - Only one NPC can exist per visitor per app at a time
+     *
+     * @keywords create, spawn, add, npc, bot, follower, character, assistant, companion
+     *
+     * @category NPCs
      *
-     * @param userInventoryItemId The ID of the user's inventory item (must be an NPC type item owned by this visitor).
-     * @param options Optional configuration for the NPC.
-     * @param options.showNameplate Whether to display a nameplate above the NPC (default: true).
+     * @param userInventoryItemId - The ID of the user's inventory item (must be an NPC type item owned by this visitor)
+     * @param options - Optional configuration for the NPC
+     * @param options.showNameplate - Whether to display a nameplate above the NPC (default: true)
      *
      * @example
      * ```ts
@@ -43385,7 +43665,7 @@ class Visitor extends User {
      * const npc = await visitor.createNpc(userItem.id, { showNameplate: false });
      * ```
      *
-     * @returns {Promise<Visitor>} Returns a Visitor object representing the created NPC.
+     * @returns {Promise<Visitor>} Returns a Visitor object representing the created NPC. The NPC will automatically follow the visitor.
      */
     createNpc(userInventoryItemId, options) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -43402,11 +43682,25 @@ class Visitor extends User {
         });
     }
     /**
-     * Deletes the NPC this app has assigned to this visitor.
+     * Deletes the NPC (Non-Player Character) this app has assigned to this visitor.
+     *
+     * @remarks
+     * This method removes the NPC associated with this visitor for the current application.
+     * The NPC will immediately disappear from the world. The underlying inventory item
+     * is not consumed and can be used to create a new NPC later.
+     *
+     * @keywords delete, remove, destroy, dismiss, despawn, npc, bot, follower, character
+     *
+     * @category NPCs
      *
      * @example
      * ```ts
-     * await visitor.deleteNpc();
+     * // Check if NPC exists before deleting
+     * const npc = await visitor.getNpc();
+     * if (npc) {
+     *   await visitor.deleteNpc();
+     *   console.log('NPC removed successfully');
+     * }
      * ```
      *
      * @returns {Promise<void>} Returns nothing if successful.
@@ -43458,15 +43752,32 @@ class Visitor extends User {
     /**
      * Grants an inventory item to this visitor.
      *
-     * @param item The InventoryItem to modify.
-     * @param quantity The new quantity to set.
+     * @remarks
+     * This method requires that the inventory item is already defined in your application's inventory system.
+     * Each visitor can only be granted an item once. Use modifyInventoryItemQuantity() to adjust quantities
+     * for items the visitor already owns. The grant_source will be set to track where the item came from.
+     *
+     * Important: This method will throw an error if the visitor already owns this inventory item.
+     * Check visitorInventoryItems first or use modifyInventoryItemQuantity() to update existing items.
+     *
+     * @keywords grant, give, add, inventory, item, visitor, award, reward
+     *
+     * @category Inventory
+     *
+     * @param item - The InventoryItem to grant to the visitor
+     * @param quantity - The quantity to grant (default: 1)
      *
      * @example
      * ```ts
-     * await visitor.grantInventoryItem("item-id-123", 2);
+     * // First create or fetch the inventory item
+     * const item = await InventoryItem.get("item-id-123");
+     *
+     * // Grant it to the visitor
+     * const userItem = await visitor.grantInventoryItem(item, 2);
+     * console.log(`Granted ${userItem.quantity} items to visitor`);
      * ```
      *
-     * @returns {Promise<UserInventoryItem>} Returns the updated inventory item or a response object.
+     * @returns {Promise<UserInventoryItem>} Returns the granted UserInventoryItem with quantity and metadata.
      */
     grantInventoryItem(item, quantity = 1) {
         var _a;
@@ -43532,14 +43843,56 @@ class Visitor extends User {
 }
 _Visitor_visitorInventoryItems = new WeakMap();
 
+/* ============================================================================
+AI RULES for code assistants
+
+  CONTEXT
+    - "Controllers" expose operations on domain objects (e.g., WebRTCConnector).
+    - Consumers obtain controller instances via factory methods (e.g., WebRTCConnectorFactory.create).
+    - This SDK is installed as an NPM package (@rtsdk/topia) in consumer applications.
+
+  DO
+    - Expect consumers to import a pre-instantiated factory from their app (e.g., utils/topiaInit.ts).
+    - Use ONLY the methods defined & documented in this file's types/TSDoc.
+
+  DO NOT
+    - Do NOT suggest creating Topia clients or factories inside controllers.
+    - Do NOT suggest non-existent methods: getById, fetch, find
+    - Do NOT mutate controller shape or return ad-hoc fields.
+
+  AVAILABLE METHODS:
+    - getTwilioConfig(): Retrieves Twilio configuration for WebRTC video/audio
+
+  CANONICAL USAGE (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, WebRTCConnectorFactory } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const WebRTC = new WebRTCConnectorFactory(topia);
+
+    // controllers/myController.ts (consumer app)
+    import { WebRTC } from "utils/topiaInit.ts";
+    const webrtc = await WebRTC.create(urlSlug, { credentials });
+    await webrtc.getTwilioConfig();
+
+============================================================================ */
 /**
- * Create an instance of WebRTCConnector class with optional session credentials.
+ * WebRTC connector for managing real-time video and audio connections in Topia worlds.
+ *
+ * @remarks
+ * This class should NOT be instantiated directly. Use WebRTCConnectorFactory to create instances.
+ * The WebRTCConnector provides access to Twilio configuration needed for establishing
+ * peer-to-peer video and audio connections between visitors in a world.
+ *
+ * @see WebRTCConnectorFactory for proper instantiation
+ *
+ * @keywords webrtc, video, audio, twilio, real-time, communication, voice, peer
  *
  * @example
  * ```ts
- * const webRTC = await new WebRTCConnector(topia, {
- *   credentials: { interactivePublicKey: "examplePublicKey", interactiveNonce: "exampleNonce", assetId: "exampleDroppedAssetId", profileId: "exampleProfileId", visitorId: 1, urlSlug: "exampleUrlSlug" }
- * });
+ * import { WebRTC } from "utils/topiaInit.ts";
+ *
+ * const webrtc = await WebRTC.create(urlSlug, { credentials });
+ * const config = await webrtc.getTwilioConfig();
  * ```
  */
 class WebRTCConnector extends SDKController {
@@ -43550,12 +43903,25 @@ class WebRTCConnector extends SDKController {
         this.urlSlug = urlSlug;
     }
     /**
-     * Get twilio
+     * Retrieves the Twilio configuration for WebRTC connections in a world.
+     *
+     * @remarks
+     * This method fetches the Twilio room configuration needed to establish peer-to-peer
+     * video and audio connections between visitors. The configuration includes authentication
+     * tokens and room settings. Call this before initializing WebRTC connections.
+     *
+     * @keywords get, fetch, retrieve, webrtc, twilio, configuration, video, audio, connection
+     *
+     * @category WebRTC
      *
      * @example
      * ```ts
      * await webRTCConnector.getTwilioConfig();
+     * const { twilioConfig } = webRTCConnector;
+     * console.log(twilioConfig); // Use for WebRTC setup
      * ```
+     *
+     * @returns {Promise<void | ResponseType>} Populates twilioConfig property with Twilio room configuration, or returns an error response.
      */
     getTwilioConfig() {
         return __awaiter(this, void 0, void 0, function* () {
@@ -43578,6 +43944,7 @@ AI RULES for code assistants
   CONTEXT
     - "Controllers" expose operations on domain objects (e.g., WorldActivity).
     - Consumers obtain controller instances via factory methods (e.g., WorldActivityFactory.get).
+    - This SDK is installed as an NPM package (@rtsdk/topia) in consumer applications.
 
   DO
     - Expect consumers to import a pre-instantiated factory from their app (e.g., utils/topiaInit.ts).
@@ -43588,6 +43955,12 @@ AI RULES for code assistants
     - Do NOT suggest non-existent methods: getById, fetch, find
     - Do NOT mutate controller shape or return ad-hoc fields.
 
+  AVAILABLE METHODS:
+    - currentVisitors(shouldIncludeAdminPermissions?): Retrieves all visitors currently in the world
+    - fetchVisitorsInZone(options): Gets visitors in a specific landmark zone
+    - moveAllVisitors(options): Moves all visitors to specified coordinates
+    - moveVisitors(visitorsToMove): Moves specific visitors to various coordinates
+
   CANONICAL USAGE (consumer app):
     // utils/topiaInit.ts
     import { Topia, WorldActivityFactory } from "@rtsdk/topia";