@rtsdk/topia 0.17.6 → 0.17.8

package/dist/index.js

@@ -39708,14 +39708,44 @@ class SDKController {
     }
 }
 
+/* ============================================================================
+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).
+
+  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.
+
+  CANONICAL USAGE (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, AssetFactory } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const Asset = new AssetFactory(topia);
+
+    // controllers/myController.ts (consumer app)
+    import { Asset } from "utils/topiaInit.ts";
+    const asset = await Asset.create(assetId, { credentials });
+    await asset.fetchAssetById();
+
+============================================================================ */
 /**
  * Create an instance of Asset class with a given asset id and optional attributes and session credentials.
  *
  * @example
  * ```ts
- * const asset = await new Asset(topia, "id", {
+ * import { Asset } from "utils/topiaInit.ts";
+ *
+ * const asset = await Asset.create(assetId, {
  *   attributes: { assetName: "My Asset", isPublic: false },
- *   credentials: { interactiveNonce: "exampleNonce", assetId: "droppedAssetId", visitorId: 1, urlSlug: "exampleWorld" }
+ *   credentials: { interactivePublicKey: "examplePublicKey", interactiveNonce: "exampleNonce", assetId: "exampleDroppedAssetId", visitorId: 1, urlSlug: "exampleUrlSlug" }
  * });
  * ```
  */
@@ -39780,6 +39810,7 @@ class Asset extends SDKController {
             try {
                 const response = yield this.topiaPublicApi().put(`/assets/${this.id}`, params, this.requestOptions);
                 Object.assign(this, response.data);
+                return response.data;
             }
             catch (error) {
                 throw this.errorHandler({ error, params, sdkMethod: "Asset.updateAsset" });
@@ -39844,14 +39875,43 @@ const scatterVisitors = (original, scatterBy) => {
 };
 
 var _DroppedAsset_updateDroppedAsset;
+/* ============================================================================
+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).
+
+  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.
+
+  CANONICAL USAGE (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, DroppedAssetFactory } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const DroppedAsset = new DroppedAssetFactory(topia);
+
+    // controllers/myController.ts (consumer app)
+    import { DroppedAsset } from "utils/topiaInit.ts";
+    const da = await DroppedAsset.get(droppedAssetId, urlSlug, { credentials });
+    await da.fetchDataObject();
+
+============================================================================ */
 /**
  * Create an instance of Dropped Asset class with a given dropped asset id, url slug, and optional attributes and session credentials.
  *
  * @example
  * ```ts
- * const droppedAsset = await new DroppedAsset(topia, "1giFZb0sQ3X27L7uGyQX", "example", {
- *   attributes: { text: "My Dropped Asset" },
- *   credentials: { interactiveNonce: "exampleNonce", assetId: "droppedAssetId", visitorId: 1, urlSlug: "exampleWorld" }
+ * import { DroppedAsset } from "utils/topiaInit.ts";
+ *
+ * const droppedAsset = await DroppedAsset.get(exampleDroppedAssetId, exampleUrlSlug, {
+ *   credentials: { interactivePublicKey: "examplePublicKey", interactiveNonce: "exampleNonce", assetId: "exampleDroppedAssetId", visitorId: 1, urlSlug: "exampleUrlSlug" }
  * });
  * ```
  */
@@ -40613,13 +40673,43 @@ class DroppedAsset extends Asset {
 }
 _DroppedAsset_updateDroppedAsset = new WeakMap();
 
+/* ============================================================================
+AI RULES for code assistants
+
+  CONTEXT
+    - "Controllers" expose operations on domain objects (e.g., Ecosystem).
+    - Consumers obtain controller instances via factory methods (e.g., EcosystemFactory.get).
+
+  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.
+
+  CANONICAL USAGE (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, Ecosystem } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const Ecosystem = new EcosystemFactory(topia);
+
+    // controllers/myController.ts (consumer app)
+    import { Ecosystem } from "utils/topiaInit.ts";
+    const ecosystem = await Ecosystem.create({ credentials });
+    await ecosystem.fetchDataObject();
+
+============================================================================ */
 /**
  * Create an instance of Ecosystem class with optional session credentials
  *
  * @example
  * ```ts
- * const ecosystem =await new Ecosystem(topia, {
- *   credentials: { interactiveNonce: "exampleNonce", assetId: "droppedAssetId", visitorId: 1, urlSlug: "exampleWorld" }
+ * import { Ecosystem } from "utils/topiaInit.ts";
+ *
+ * const ecosystem = await Ecosystem.create({
+ *   credentials: { interactivePublicKey: "examplePublicKey", interactiveNonce: "exampleNonce", assetId: "exampleDroppedAssetId", visitorId: 1, urlSlug: "exampleUrlSlug" }
  * });
  * ```
  */
@@ -40757,14 +40847,43 @@ class Ecosystem extends SDKController {
     }
 }
 
+/* ============================================================================
+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).
+
+  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.
+
+  CANONICAL USAGE (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, SceneFactory } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const Scene = new SceneFactory(topia);
+
+    // controllers/myController.ts (consumer app)
+    import { Scene } from "utils/topiaInit.ts";
+    const scene = await Scene.get(sceneId, { credentials });
+
+============================================================================ */
 /**
  * Create an instance of Scene class with a given scene id and optional attributes and session credentials.
  *
  * @example
  * ```ts
- * const scene = await new Scene(topia, "sceneId", {
+ * import { Scene } from "utils/topiaInit.ts";
+ *
+ * const scene = await Scene.get(exampleSceneId, {
  *   attributes: { name: "My Scene" },
- *   credentials: { interactiveNonce: "exampleNonce", assetId: "droppedAssetId", visitorId: 1, urlSlug: "exampleWorld" }
+ *   credentials: { interactivePublicKey: "examplePublicKey", interactiveNonce: "exampleNonce", assetId: "exampleDroppedAssetId", visitorId: 1, urlSlug: "exampleUrlSlug" }
  * });
  * ```
  */
@@ -40834,14 +40953,44 @@ class Topia {
 }
 
 var _World_droppedAssetsMap;
+/* ============================================================================
+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).
+
+  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.
+
+  CANONICAL USAGE (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, WorldFactory } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const World = new WorldFactory(topia);
+
+    // controllers/myController.ts (consumer app)
+    import { World } from "utils/topiaInit.ts";
+    const world = await World.create(urlSlug, { credentials });
+    await world.fetchDetails();
+
+============================================================================ */
 /**
  * Create an instance of World class with a given url slug and optional attributes and session credentials.
  *
  * @example
  * ```ts
- * const world = await new World(topia, "exampleWorld", {
+ * import { World } from "utils/topiaInit.ts";
+ *
+ * const world = await World.create(exampleUrlSlug, {
  *   attributes: { name: "Example World" },
- *   credentials: { interactiveNonce: "exampleNonce", assetId: "droppedAssetId", visitorId: 1, urlSlug: "exampleWorld" }
+ *   credentials: { interactivePublicKey: "examplePublicKey", interactiveNonce: "exampleNonce", assetId: "exampleDroppedAssetId", visitorId: 1, urlSlug: "exampleUrlSlug" }
  * });
  * ```
  */
@@ -41563,14 +41712,44 @@ class World extends SDKController {
 _World_droppedAssetsMap = new WeakMap();
 
 var _User_adminWorldsMap, _User_assetsMap, _User_scenesMap, _User_worldsMap;
+/* ============================================================================
+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).
+
+  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.
+
+  CANONICAL USAGE (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, UserFactory } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const User = new UserFactory(topia);
+
+    // controllers/myController.ts (consumer app)
+    import { User } from "utils/topiaInit.ts";
+    const user = await User.create({ credentials });
+    await user.fetchDataObject();
+
+============================================================================ */
 /**
  * Create an instance of User class with optional session credentials.
  *
  * @example
  * ```ts
- * const user = await new User(topia, {
- *   profileId: 1,
- *   credentials: { interactiveNonce: "exampleNonce", assetId: "droppedAssetId", visitorId: 1, urlSlug: "exampleWorld" }
+ * import { User } from "utils/topiaInit.ts";
+ *
+ * const user = await User.create({
+ *   profileId: "exampleProfileId",
+ *   credentials: { interactivePublicKey: "examplePublicKey", interactiveNonce: "exampleNonce", assetId: "exampleDroppedAssetId", profileId: "exampleProfileId", visitorId: 1, urlSlug: "exampleUrlSlug" }
  * });
  * ```
  */
@@ -42171,12 +42350,42 @@ class User extends SDKController {
 }
 _User_adminWorldsMap = new WeakMap(), _User_assetsMap = new WeakMap(), _User_scenesMap = new WeakMap(), _User_worldsMap = new WeakMap();
 
+/* ============================================================================
+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).
+
+  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.
+
+  CANONICAL USAGE (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, VisitorFactory } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const Visitor = new VisitorFactory(topia);
+
+    // controllers/myController.ts (consumer app)
+    import { Visitor } from "utils/topiaInit.ts";
+    const visitor = await Visitor.get(visitorId, urlSlug, { credentials });
+    await visitor.fetchDataObject();
+
+============================================================================ */
 /**
  * Create an instance of Visitor class with a given id and optional attributes and session credentials.
  *
  * @example
  * ```ts
- * const visitor = await new Visitor(topia, id, urlSlug, { attributes: { moveTo: { x: 0, y: 0 } }, credentials: { interactiveNonce: "exampleNonce", assetId: "droppedAssetId", visitorId: 1, urlSlug: "exampleWorld" } });
+ * import { Visitor } from "utils/topiaInit.ts";
+ *
+ * const visitor = await Visitor.get(visitorId, urlSlug, { attributes: { moveTo: { x: 0, y: 0 } }, credentials: { interactivePublicKey: "examplePublicKey", interactiveNonce: "exampleNonce", assetId: "exampleDroppedAssetId", profileId: "exampleProfileId", visitorId: 1, urlSlug: "exampleUrlSlug" } });
  * ```
  */
 class Visitor extends User {
@@ -42665,7 +42874,7 @@ class Visitor extends User {
  * @example
  * ```ts
  * const webRTC = await new WebRTCConnector(topia, {
- *   credentials: { interactiveNonce: "exampleNonce", assetId: "droppedAssetId", visitorId: 1, urlSlug: "exampleWorld" }
+ *   credentials: { interactivePublicKey: "examplePublicKey", interactiveNonce: "exampleNonce", assetId: "exampleDroppedAssetId", profileId: "exampleProfileId", visitorId: 1, urlSlug: "exampleUrlSlug" }
  * });
  * ```
  */
@@ -42699,6 +42908,34 @@ class WebRTCConnector extends SDKController {
 }
 
 var _WorldActivity_visitorsMap;
+/* ============================================================================
+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).
+
+  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.
+
+  CANONICAL USAGE (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, WorldActivityFactory } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const WorldActivity = new WorldActivityFactory(topia);
+
+    // controllers/myController.ts (consumer app)
+    import { WorldActivity } from "utils/topiaInit.ts";
+    const activity = await WorldActivity.create(urlSlug, { credentials });
+    await activity.currentVisitors();
+
+============================================================================ */
 /**
  * Create an instance of WorldActivity class with a given url slug and optional attributes and session credentials.
  *
@@ -42707,9 +42944,11 @@ var _WorldActivity_visitorsMap;
  *
  * @example
  * ```ts
- * const activity = await new WorldActivity(topia, "exampleWorld", {
+ * import { WorldActivity } from "utils/topiaInit.ts";
+ *
+ * const activity = await WorldActivity.create(urlSlug, {
  *   attributes: { name: "Example World" },
- *   credentials: { interactiveNonce: "exampleNonce", assetId: "droppedAssetId", visitorId: 1, urlSlug: "exampleWorld" }
+ *   credentials: { interactivePublicKey: "examplePublicKey", interactiveNonce: "exampleNonce", assetId: "exampleDroppedAssetId", visitorId: 1, urlSlug: "exampleUrlSlug" }
  * });
  * ```
  */
@@ -42880,6 +43119,36 @@ class WorldActivity extends SDKController {
 }
 _WorldActivity_visitorsMap = new WeakMap();
 
+/* ============================================================================
+  AI RULES for code assistants
+
+  - Consumers MUST create a single Topia client in their app (e.g. utils/topiaInit.ts).
+  - Consumers MUST instantiate this factory ONCE using that client and RE-USE it.
+  - Controllers/services MUST import the app’s exported factory instance.
+  - Use ONLY methods defined in this file’s types and TSDoc.
+  - Methods that DO NOT exist and MUST NOT be suggested.
+
+  RIGHT ✅ Correct usage pattern (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, AssetFactory } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const Asset = new AssetFactory(topia);
+
+  RIGHT ✅ Correct usage pattern (controller):
+    // controllers/myController.ts
+    import { Asset } from "utils/topiaInit.ts";
+    const asset = await Asset.create(assetId, { credentials });
+    await asset.fetchAssetById();
+
+  WRONG ❌ Incorrect usage pattern (controller):
+    // controllers/myController.ts
+    import { AssetFactory, Topia } from "@rtsdk/topia";
+    const topia = new Topia(config); // ❌ new client per request
+    const Asset = new AssetFactory(topia); // ❌ ad-hoc factory
+    const asset = await Asset.getById(assetId); // ❌ method does not exist
+
+  Do NOT instantiate factories in controllers. Do NOT invent methods.
+============================================================================ */
 /**
  * @example
  * ```ts
@@ -42938,6 +43207,36 @@ class AssetFactory extends SDKController {
     }
 }
 
+/* ============================================================================
+  AI RULES for code assistants
+
+  - Consumers MUST create a single Topia client in their app (e.g. utils/topiaInit.ts).
+  - Consumers MUST instantiate this factory ONCE using that client and RE-USE it.
+  - Controllers/services MUST import the app’s exported factory instance.
+  - Use ONLY methods defined in this file’s types and TSDoc.
+  - Methods that DO NOT exist and MUST NOT be suggested.
+
+  RIGHT ✅ Correct usage pattern (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, DroppedAssetFactory } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const DroppedAsset = new DroppedAssetFactory(topia);
+
+  RIGHT ✅ Correct usage pattern (controller):
+    // controllers/myController.ts
+    import { DroppedAsset } from "utils/topiaInit.ts";
+    const da = await DroppedAsset.get(droppedAssetId, urlSlug, { credentials });
+    await da.fetchDataObject();
+
+  WRONG ❌ Incorrect usage pattern (controller):
+    // controllers/myController.ts
+    import { DroppedAssetFactory, Topia } from "@rtsdk/topia";
+    const topia = new Topia(config); // ❌ new client per request
+    const DroppedAsset = new DroppedAssetFactory(topia); // ❌ ad-hoc factory
+    const da = await DroppedAsset.getById(droppedAssetId); // ❌ method does not exist
+
+  Do NOT instantiate factories in controllers. Do NOT invent methods.
+============================================================================ */
 /**
  * @example
  * ```ts
@@ -43086,6 +43385,36 @@ class DroppedAssetFactory extends SDKController {
     }
 }
 
+/* ============================================================================
+  AI RULES for code assistants
+
+  - Consumers MUST create a single Topia client in their app (e.g. utils/topiaInit.ts).
+  - Consumers MUST instantiate this factory ONCE using that client and RE-USE it.
+  - Controllers/services MUST import the app’s exported factory instance.
+  - Use ONLY methods defined in this file’s types and TSDoc.
+  - Methods that DO NOT exist and MUST NOT be suggested.
+
+  RIGHT ✅ Correct usage pattern (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, Ecosystem } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const Ecosystem = new EcosystemFactory(topia);
+
+  RIGHT ✅ Correct usage pattern (controller):
+    // controllers/myController.ts
+    import { Ecosystem } from "utils/topiaInit.ts";
+    const ecosystem = await Ecosystem.create({ credentials });
+    await ecosystem.fetchDataObject();
+
+  WRONG ❌ Incorrect usage pattern (controller):
+    // controllers/myController.ts
+    import { Ecosystem, Topia } from "@rtsdk/topia";
+    const topia = new Topia(config); // ❌ new client per request
+    const Ecosystem = new EcosystemFactory(topia); // ❌ ad-hoc factory
+    const ecosystem = await Ecosystem.getById(id); // ❌ method does not exist
+
+  Do NOT instantiate factories in controllers. Do NOT invent methods.
+============================================================================ */
 /**
  * @example
  * ```ts
@@ -43111,6 +43440,35 @@ class EcosystemFactory {
     }
 }
 
+/* ============================================================================
+  AI RULES for code assistants
+
+  - Consumers MUST create a single Topia client in their app (e.g. utils/topiaInit.ts).
+  - Consumers MUST instantiate this factory ONCE using that client and RE-USE it.
+  - Controllers/services MUST import the app’s exported factory instance.
+  - Use ONLY methods defined in this file’s types and TSDoc.
+  - Methods that DO NOT exist and MUST NOT be suggested.
+
+  RIGHT ✅ Correct usage pattern (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, SceneFactory } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const Scene = new SceneFactory(topia);
+
+  RIGHT ✅ Correct usage pattern (controller):
+    // controllers/myController.ts
+    import { Scene } from "utils/topiaInit.ts";
+    const scene = await Scene.get(sceneId, { credentials });
+
+  WRONG ❌ Incorrect usage pattern (controller):
+    // controllers/myController.ts
+    import { SceneFactory, Topia } from "@rtsdk/topia";
+    const topia = new Topia(config); // ❌ new client per request
+    const Scene = new SceneFactory(topia); // ❌ ad-hoc factory
+    const scene = await Scene.getById(sceneId);  // ❌ method does not exist
+
+  Do NOT instantiate factories in controllers. Do NOT invent methods.
+============================================================================ */
 /**
  * @example
  * ```ts
@@ -43154,6 +43512,36 @@ class SceneFactory {
     }
 }
 
+/* ============================================================================
+  AI RULES for code assistants
+
+  - Consumers MUST create a single Topia client in their app (e.g. utils/topiaInit.ts).
+  - Consumers MUST instantiate this factory ONCE using that client and RE-USE it.
+  - Controllers/services MUST import the app’s exported factory instance.
+  - Use ONLY methods defined in this file’s types and TSDoc.
+  - Methods that DO NOT exist and MUST NOT be suggested.
+
+  RIGHT ✅ Correct usage pattern (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, UserFactory } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const User = new UserFactory(topia);
+
+  RIGHT ✅ Correct usage pattern (controller):
+    // controllers/myController.ts
+    import { User } from "utils/topiaInit.ts";
+    const user = await User.create({ credentials });
+    await user.fetchDataObject();
+
+  WRONG ❌ Incorrect usage pattern (controller):
+    // controllers/myController.ts
+    import { UserFactory, Topia } from "@rtsdk/topia";
+    const topia = new Topia(config); // ❌ new client per request
+    const User = new UserFactory(topia); // ❌ ad-hoc factory
+    const user = await User.getById(userId); // ❌ method does not exist
+
+  Do NOT instantiate factories in controllers. Do NOT invent methods.
+============================================================================ */
 /**
  * @example
  * ```ts
@@ -43179,6 +43567,36 @@ class UserFactory {
     }
 }
 
+/* ============================================================================
+  AI RULES for code assistants
+
+  - Consumers MUST create a single Topia client in their app (e.g. utils/topiaInit.ts).
+  - Consumers MUST instantiate this factory ONCE using that client and RE-USE it.
+  - Controllers/services MUST import the app’s exported factory instance.
+  - Use ONLY methods defined in this file’s types and TSDoc.
+  - Methods that DO NOT exist and MUST NOT be suggested.
+
+  RIGHT ✅ Correct usage pattern (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, VisitorFactory } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const Visitor = new VisitorFactory(topia);
+
+  RIGHT ✅ Correct usage pattern (controller):
+    // controllers/myController.ts
+    import { Visitor } from "utils/topiaInit.ts";
+    const visitor = await Visitor.get(visitorId, urlSlug, { credentials });
+    await visitor.fetchDataObject();
+
+  WRONG ❌ Incorrect usage pattern (controller):
+    // controllers/myController.ts
+    import { VisitorFactory, Topia } from "@rtsdk/topia";
+    const topia = new Topia(config); // ❌ new client per request
+    const Visitor = new VisitorFactory(topia); // ❌ ad-hoc factory
+    const visitor = await Visitor.getById(visitorId); // ❌ method does not exist
+
+  Do NOT instantiate factories in controllers. Do NOT invent methods.
+============================================================================ */
 /**
  * @example
  * ```ts
@@ -43246,6 +43664,36 @@ class WebRTCConnectorFactory {
     }
 }
 
+/* ============================================================================
+  AI RULES for code assistants
+
+  - Consumers MUST create a single Topia client in their app (e.g. utils/topiaInit.ts).
+  - Consumers MUST instantiate this factory ONCE using that client and RE-USE it.
+  - Controllers/services MUST import the app’s exported factory instance.
+  - Use ONLY methods defined in this file’s types and TSDoc.
+  - Methods that DO NOT exist and MUST NOT be suggested.
+
+  RIGHT ✅ Correct usage pattern (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, WorldActivityFactory } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const WorldActivity = new WorldActivityFactory(topia);
+
+  RIGHT ✅ Correct usage pattern (controller):
+    // controllers/myController.ts
+    import { WorldActivity } from "utils/topiaInit.ts";
+    const activity = await WorldActivity.create(urlSlug, { credentials });
+    await activity.currentVisitors();
+
+  WRONG ❌ Incorrect usage pattern (controller):
+    // controllers/myController.ts
+    import { WorldActivity, Topia } from "@rtsdk/topia";
+    const topia = new Topia(config); // ❌ new client per request
+    const WorldActivity = new WorldActivityFactory(topia); // ❌ ad-hoc factory
+    const activity = await WorldActivity.getAllVisitors(); // ❌ method does not exist
+
+  Do NOT instantiate factories in controllers. Do NOT invent methods.
+============================================================================ */
 /**
  * @example
  * ```ts
@@ -43271,6 +43719,36 @@ class WorldActivityFactory {
     }
 }
 
+/* ============================================================================
+  AI RULES for code assistants
+
+  - Consumers MUST create a single Topia client in their app (e.g. utils/topiaInit.ts).
+  - Consumers MUST instantiate this factory ONCE using that client and RE-USE it.
+  - Controllers/services MUST import the app’s exported factory instance.
+  - Use ONLY methods defined in this file’s types and TSDoc.
+  - Methods that DO NOT exist and MUST NOT be suggested.
+
+  RIGHT ✅ Correct usage pattern (consumer app):
+    // utils/topiaInit.ts
+    import { Topia, WorldFactory } from "@rtsdk/topia";
+    const topia = new Topia({ config });
+    export const World = new WorldFactory(topia);
+
+  RIGHT ✅ Correct usage pattern (controller):
+    // controllers/myController.ts
+    import { World } from "utils/topiaInit.ts";
+    const world = await World.create(urlSlug, { credentials });
+    await world.fetchDetails();
+
+  WRONG ❌ Incorrect usage pattern (controller):
+    // controllers/myController.ts
+    import { World, Topia } from "@rtsdk/topia";
+    const topia = new Topia(config); // ❌ new client per request
+    const World = new WorldFactory(topia); // ❌ ad-hoc factory
+    const world = await World.update({}); // ❌ method does not exist
+
+  Do NOT instantiate factories in controllers. Do NOT invent methods.
+============================================================================ */
 /**
  * @example
  * ```ts