@rtsdk/topia 0.19.4 → 0.19.5

package/README.md

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

package/dist/index.cjs

@@ -39727,11 +39727,6 @@ class SDKController {
      *
      * @keywords error, exception, handler, debugging, api error, http error
      *
-     * @param error - The error object from the failed operation (AxiosError, Error, or unknown)
-     * @param message - Optional custom error message (defaults to generic message)
-     * @param params - Optional parameters that were passed to the failed method
-     * @param sdkMethod - Optional name of the SDK method that failed (e.g., "World.fetchDetails")
-     *
      * @returns {object} Standardized error object with properties: data, message, method, params, sdkMethod, stack, status, success, url
      */
     errorHandler({ error, message = "Something went wrong. Please try again or contact support.", params = {}, sdkMethod, }) {

package/dist/index.d.ts

@@ -74,7 +74,7 @@ type DroppedAssetLinkType = {
     linkSamlQueryParams?: string;
 };
 
-type InteractiveCredentials = {
+type InteractiveCredentials$1 = {
     apiKey?: string;
     assetId?: string;
     interactiveNonce?: string;
@@ -88,22 +88,22 @@ type InteractiveCredentials = {
 
 type AssetOptions = {
     attributes?: AssetInterface | undefined;
-    credentials?: InteractiveCredentials | undefined;
+    credentials?: InteractiveCredentials$1 | undefined;
 };
 type DroppedAssetOptions = {
     attributes?: DroppedAssetInterface | undefined;
-    credentials?: InteractiveCredentials | undefined;
+    credentials?: InteractiveCredentials$1 | undefined;
 };
 type UserOptions = {
-    credentials?: InteractiveCredentials | undefined;
+    credentials?: InteractiveCredentials$1 | undefined;
 };
 type VisitorOptions = {
     attributes?: VisitorInterface | undefined;
-    credentials?: InteractiveCredentials | undefined;
+    credentials?: InteractiveCredentials$1 | undefined;
 };
 type WorldOptions = {
     attributes?: WorldDetailsInterface | undefined;
-    credentials?: InteractiveCredentials | undefined;
+    credentials?: InteractiveCredentials$1 | undefined;
 };
 
 type ResponseType = {
@@ -2294,7 +2294,7 @@ declare enum WorldActivityType {
 }
 
 interface SDKInterface {
-    credentials?: InteractiveCredentials;
+    credentials?: InteractiveCredentials$1;
     jwt?: string;
     requestOptions: object;
     topia: Topia;
@@ -2331,7 +2331,7 @@ interface AssetInterface extends SDKInterface {
 }
 type AssetOptionalInterface = {
     attributes?: AssetInterface | object;
-    credentials?: InteractiveCredentials;
+    credentials?: InteractiveCredentials$1;
 };
 
 interface DroppedAssetInterface extends AssetInterface {
@@ -2453,7 +2453,7 @@ interface DroppedAssetOptionalInterface {
         text?: string;
         urlSlug?: string;
     };
-    credentials?: InteractiveCredentials | object;
+    credentials?: InteractiveCredentials$1 | object;
 }
 interface UpdateBroadcastInterface {
     assetBroadcast?: boolean;
@@ -2545,7 +2545,7 @@ interface EcosystemInterface extends SDKInterface {
     incrementDataObjectValue(path: string, amount: number, options: object): Promise<void | ResponseType>;
 }
 interface EcosystemOptionalInterface {
-    credentials?: InteractiveCredentials;
+    credentials?: InteractiveCredentials$1;
 }
 
 interface SceneInterface {
@@ -2573,7 +2573,7 @@ interface SceneInterface {
 }
 type SceneOptionalInterface = {
     attributes?: SceneInterface | object;
-    credentials?: InteractiveCredentials;
+    credentials?: InteractiveCredentials$1;
 };
 
 interface FireToastInterface {
@@ -2621,7 +2621,7 @@ interface UserInterface {
     dataObject?: object | null;
 }
 interface UserOptionalInterface {
-    credentials?: InteractiveCredentials;
+    credentials?: InteractiveCredentials$1;
     profileId?: string | null;
     visitorId?: number | null;
     urlSlug?: string;
@@ -2697,7 +2697,7 @@ interface VisitorInterface extends SDKInterface {
 }
 interface VisitorOptionalInterface {
     attributes?: VisitorInterface | object;
-    credentials?: InteractiveCredentials;
+    credentials?: InteractiveCredentials$1;
 }
 interface MoveVisitorInterface {
     shouldTeleportVisitor: boolean;
@@ -2730,12 +2730,12 @@ interface WebRTCConnectorInterface {
     getTwilioConfig(): Promise<void | ResponseType>;
 }
 interface WebRTCConnectorOptionalInterface {
-    credentials?: InteractiveCredentials;
+    credentials?: InteractiveCredentials$1;
     twilioConfig?: object;
 }
 
 interface WorldActivityOptionalInterface {
-    credentials?: InteractiveCredentials;
+    credentials?: InteractiveCredentials$1;
 }
 interface MoveAllVisitorsInterface {
     shouldFetchVisitors?: boolean;
@@ -2825,13 +2825,13 @@ interface WorldInterface extends SDKInterface, WorldDetailsInterface {
 }
 interface WorldOptionalInterface {
     attributes?: WorldDetailsInterface | object;
-    credentials?: InteractiveCredentials;
+    credentials?: InteractiveCredentials$1;
 }
 interface WorldWebhooksInterface {
     webhooks: Array<WebhookInterface>;
 }
 
-type InteractiveCredentials$1 = {
+type InteractiveCredentials = {
     apiKey?: string;
     assetId?: string;
     interactiveNonce?: string;
@@ -2862,7 +2862,7 @@ interface InventoryItemInterface extends SDKInterface {
 }
 type InventoryItemOptionalInterface = {
     attributes?: InventoryItemInterface | object;
-    credentials?: InteractiveCredentials$1;
+    credentials?: InteractiveCredentials;
 };
 
 /**
@@ -2880,7 +2880,7 @@ interface UserInventoryItemInterface extends InventoryItemInterface {
 }
 type UserInventoryItemOptionalInterface = {
     attributes?: UserInventoryItemInterface | object;
-    credentials?: InteractiveCredentials$1;
+    credentials?: InteractiveCredentials;
 };
 type UserInventoryItemMetadataType = {
     id: string;
@@ -2959,11 +2959,11 @@ declare class Topia implements TopiaInterface {
  * ```
  */
 declare abstract class SDKController implements SDKInterface {
-    credentials: InteractiveCredentials | undefined;
+    credentials: InteractiveCredentials$1 | undefined;
     jwt?: string;
     requestOptions: object;
     topia: Topia;
-    constructor(topia: Topia, credentials?: InteractiveCredentials);
+    constructor(topia: Topia, credentials?: InteractiveCredentials$1);
     /**
      * Returns the configured Axios instance for making API calls to Topia's Public API.
      *
@@ -2991,11 +2991,6 @@ declare abstract class SDKController implements SDKInterface {
      *
      * @keywords error, exception, handler, debugging, api error, http error
      *
-     * @param error - The error object from the failed operation (AxiosError, Error, or unknown)
-     * @param message - Optional custom error message (defaults to generic message)
-     * @param params - Optional parameters that were passed to the failed method
-     * @param sdkMethod - Optional name of the SDK method that failed (e.g., "World.fetchDetails")
-     *
      * @returns {object} Standardized error object with properties: data, message, method, params, sdkMethod, stack, status, success, url
      */
     errorHandler({ error, message, params, sdkMethod, }: {
@@ -3608,7 +3603,7 @@ declare class DroppedAssetFactory extends SDKController {
      *
      * @returns {Promise<DroppedAsset>} Returns a new DroppedAsset object with all properties already fetched.
      */
-    getWithUniqueName(uniqueName: string, urlSlug: string, interactiveSecret: string, credentials: InteractiveCredentials): Promise<DroppedAsset>;
+    getWithUniqueName(uniqueName: string, urlSlug: string, interactiveSecret: string, credentials: InteractiveCredentials$1): Promise<DroppedAsset>;
     /**
      * Drops an asset in a world and returns a new instance of DroppedAsset class with all properties.
      *
@@ -4190,4 +4185,4 @@ declare class WorldFactory extends SDKController {
     }>;
 }
 
-export { AnalyticType, AnimationMetaType, Asset, AssetFactory, AssetInterface, AssetOptionalInterface, AssetOptions, AssetType, DroppedAsset, DroppedAssetClickType, DroppedAssetFactory, DroppedAssetInterface, DroppedAssetLinkType, DroppedAssetMediaType, DroppedAssetMediaVolumeRadius, DroppedAssetOptionalInterface, DroppedAssetOptions, Ecosystem, EcosystemFactory, EcosystemInterface, EcosystemOptionalInterface, FireToastInterface, FrameType, InteractiveCredentials, InventoryItemInterface, InventoryItemOptionalInterface, MoveAllVisitorsInterface, MoveVisitorInterface, OpenIframeInterface, RemoveClickableLinkInterface, ResponseType, SDKController, SDKInterface, Scene, SceneFactory, SceneInterface, SceneOptionalInterface, SetClickableLinkMultiInterface, Topia, TopiaInterface, UpdateBroadcastInterface, UpdateClickTypeInterface, UpdateClickableLinkMultiInterface, UpdateDroppedAssetInterface, UpdateMediaTypeInterface, UpdatePrivateZoneInterface, User, UserFactory, UserInterface, UserInventoryItemInterface, UserInventoryItemMetadataType, UserInventoryItemOptionalInterface, UserOptionalInterface, UserOptions, Visitor, VisitorFactory, VisitorInterface, VisitorOptionalInterface, VisitorOptions, VisitorType, VisitorsToMoveArrayType, VisitorsToMoveType, WebRTCConnector, WebRTCConnectorFactory, WebRTCConnectorInterface, WebRTCConnectorOptionalInterface, WebhookInterface, World, WorldActivity, WorldActivityFactory, WorldActivityOptionalInterface, WorldActivityType, WorldDetailsInterface, WorldFactory, WorldInterface, WorldOptionalInterface, WorldOptions, WorldWebhooksInterface };
+export { AnalyticType, AnimationMetaType, Asset, AssetFactory, AssetInterface, AssetOptionalInterface, AssetOptions, AssetType, 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 };

package/dist/index.js

@@ -39725,11 +39725,6 @@ class SDKController {
      *
      * @keywords error, exception, handler, debugging, api error, http error
      *
-     * @param error - The error object from the failed operation (AxiosError, Error, or unknown)
-     * @param message - Optional custom error message (defaults to generic message)
-     * @param params - Optional parameters that were passed to the failed method
-     * @param sdkMethod - Optional name of the SDK method that failed (e.g., "World.fetchDetails")
-     *
      * @returns {object} Standardized error object with properties: data, message, method, params, sdkMethod, stack, status, success, url
      */
     errorHandler({ error, message = "Something went wrong. Please try again or contact support.", params = {}, sdkMethod, }) {

package/package.json

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