@rtsdk/topia 0.3.9 → 0.5.0

package/README.md

@@ -50,12 +50,12 @@ await DroppedAsset.get(assetId, urlSlug, {
 
 ### Need an API Key to test locally? This is how you can create one:
 
-- While logged in to [topia.io](https://topia.io/), click on your image (or gray circle) in the top left of the screen to open My Account
-- In the side menu, select Integrations
+- Navigate directly to your [integrations page](https://topia.io/t/dashboard/integrations) or follow the steps below from within a world.
+  - Click on your image (or circle) at the top left of the left hand navbar.
+  - Click Edit Profile. This will bring you to a separate dashboard.
+  - Click Integrations on the left nav
 - Click Generate New API Key and copy the API Key to be used in your .env and while using https://sdk-examples.metaversecloud.com
 
-<br>
-
 Alternatively, visitors of a [topia.io](https://topia.io/) world interact with each other and the interactively configured assets in your world without the need for an API Key. This is all made possible through Interactive Session credentials passed to the SDK with every request, when applicable. What does this mean for you? Not much, actually! All of the magic happens behind the scenes and all you have to do is make sure that new class constructors include an options object like this: `options: WorldOptionalInterface = { attributes: {}, credentials: {} }` and all calls to `this.topia.axios` include the inherited `this.requestOptions` parameter.
 
 ![Interactive Application Development Diagram](./InteractiveApplicationDevelopment.png)

package/dist/index.cjs

@@ -39637,14 +39637,14 @@ const {
  */
 class SDKController {
     constructor(topia, credentials = {}) {
-        const { apiKey = null, assetId = null, interactiveNonce = null, profileId = null, visitorId = null } = credentials;
+        const { apiKey = null, assetId = null, interactiveNonce = null, profileId = null, urlSlug = null, visitorId = null, } = credentials;
         this.topia = topia;
         this.credentials = credentials;
         this.requestOptions = {};
         let payload = {};
         const headers = {};
         try {
-            if (topia.interactiveSecret && (profileId || assetId)) {
+            if (topia.interactiveSecret && (profileId || assetId || urlSlug)) {
                 payload = {
                     interactiveNonce,
                     visitorId,
@@ -39742,7 +39742,7 @@ var _DroppedAsset_updateDroppedAsset;
 class DroppedAsset extends Asset {
     constructor(topia, id, urlSlug, options = { attributes: { text: "" }, credentials: {} }) {
         var _a;
-        super(topia, id, options);
+        super(topia, id, { attributes: options.attributes, credentials: Object.assign(Object.assign({}, options.credentials), { urlSlug }) });
         // private methods
         _DroppedAsset_updateDroppedAsset.set(this, (payload, updateType) => __awaiter(this, void 0, void 0, function* () {
             try {
@@ -40197,6 +40197,40 @@ class DroppedAsset extends Asset {
             }
         });
     }
+    ////////// analytics
+    /**
+     * @summary
+     * Retrieve analytics for a dropped asset by day, week, month, quarter, or year
+     *
+     * @usage
+     * ```ts
+     * const analytics = await droppedAsset.fetchDroppedAssetAnalytics({
+     *   periodType: "quarter",
+     *   dateValue: 3,
+     *   year: 2023,
+     * });
+     * ```
+     */
+    fetchDroppedAssetAnalytics({ periodType, dateValue, year, }) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                let query = "";
+                switch (periodType) {
+                    case "week":
+                        query = `&week=W${dateValue}`;
+                    case "month":
+                        query = `&month=${dateValue}`;
+                    case "quarter":
+                        query = `&quarter=Q${dateValue}`;
+                }
+                const response = yield this.topiaPublicApi().get(`/world/${this.urlSlug}/dropped-asset-analytics/${this.id}?year=${year}${query}`, this.requestOptions);
+                return response.data;
+            }
+            catch (error) {
+                throw this.errorHandler({ error });
+            }
+        });
+    }
 }
 _DroppedAsset_updateDroppedAsset = new WeakMap();
 
@@ -40267,7 +40301,7 @@ var _World_droppedAssetsMap;
  */
 class World extends SDKController {
     constructor(topia, urlSlug, options = { attributes: {}, credentials: {} }) {
-        super(topia, options.credentials);
+        super(topia, Object.assign({ urlSlug }, options.credentials));
         _World_droppedAssetsMap.set(this, void 0);
         ////////// data objects
         /**
@@ -40534,6 +40568,8 @@ class World extends SDKController {
         });
     }
     /**
+     * @deprecated Use {@link fetchScenes} instead.
+     *
      * @summary
      * Fetch a list of all scene drop ids in a world that include at least one asset with an interactivePublicKey
      *
@@ -40559,6 +40595,46 @@ class World extends SDKController {
             }
         });
     }
+    /**
+     * @summary
+     * Fetch a list of all scene drop ids and dropped assets in a world
+     *
+     * @usage
+     * ```ts
+     * await world.fetchScenes();
+     * ```
+     *
+     * @result
+     * ```ts
+     * { "scenes": {
+     *     "sceneDropId_1": {
+     *         "droppedAssets": {
+     *             "droppedAssetId_1": {
+     *                 "metaName": "hello"
+     *                 "metaNameReversed": "olleh"
+     *             },
+     *             "droppedAssetId_2": {
+     *                 "metaName": "world"
+     *                 "metaNameReversed": "dlorw"
+     *             }
+     *         }
+     *     },
+     *   }
+     * }
+     * ```
+     */
+    fetchScenes() {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const response = yield this.topiaPublicApi().get(`/world/${this.urlSlug}/scenes-with-dropped-assets`, this.requestOptions);
+                this.scenes = response.data;
+                return response.data;
+            }
+            catch (error) {
+                throw this.errorHandler({ error });
+            }
+        });
+    }
     /**
      * @summary
      * Drops a scene in a world and returns sceneDropId.
@@ -40665,6 +40741,40 @@ class World extends SDKController {
             }
         });
     }
+    ////////// analytics
+    /**
+     * @summary
+     * Retrieve world analytics by day, week, month, quarter, or year
+     *
+     * @usage
+     * ```ts
+     * const analytics = await world.fetchWorldAnalytics({
+     *   periodType: "week",
+     *   dateValue: 40,
+     *   year: 2023,
+     * });
+     * ```
+     */
+    fetchWorldAnalytics({ periodType, dateValue, year, }) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                let query = "";
+                switch (periodType) {
+                    case "week":
+                        query = `&week=W${dateValue}`;
+                    case "month":
+                        query = `&month=${dateValue}`;
+                    case "quarter":
+                        query = `&quarter=Q${dateValue}`;
+                }
+                const response = yield this.topiaPublicApi().get(`/world/${this.urlSlug}/world-analytics?year=${year}${query}`, this.requestOptions);
+                return response.data;
+            }
+            catch (error) {
+                throw this.errorHandler({ error });
+            }
+        });
+    }
 }
 _World_droppedAssetsMap = new WeakMap();
 
@@ -40954,7 +41064,7 @@ _User_adminWorldsMap = new WeakMap(), _User_assetsMap = new WeakMap(), _User_sce
  */
 class Visitor extends User {
     constructor(topia, id, urlSlug, options = { attributes: {}, credentials: {} }) {
-        super(topia, { credentials: options.credentials });
+        super(topia, { credentials: Object.assign(Object.assign({}, options.credentials), { urlSlug }) });
         Object.assign(this, options.attributes);
         this.id = id;
         this.urlSlug = urlSlug;
@@ -41098,6 +41208,32 @@ class Visitor extends User {
             }
         });
     }
+    /**
+     * @summary
+     * Grant expression to a visitor by id or name.
+     *
+     * @usage
+     * ```ts
+     * await visitor.grantExpression({ name: "Eyes" });
+     * ```
+     */
+    grantExpression({ id, name }) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!id && !name)
+                throw "An expression id or name is required.";
+            try {
+                let expressionId = id;
+                if (name) {
+                    expressionId = yield this.topiaPublicApi().get(`/expressions?name=${name}`, this.requestOptions);
+                }
+                const result = yield this.topiaPublicApi().put(`/world/${this.urlSlug}/visitors/${this.id}/grant-expression/${expressionId}`, {}, this.requestOptions);
+                return result;
+            }
+            catch (error) {
+                throw this.errorHandler({ error });
+            }
+        });
+    }
     /**
      * @summary
      * Retrieves the data object for a visitor.
@@ -41393,6 +41529,19 @@ class DroppedAssetFactory extends SDKController {
             return droppedAsset;
         });
     }
+    getWithUniqueName(uniqueName, urlSlug, interactivePublicKey, interactiveSecret) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const interactiveJWT = jwt.sign(interactivePublicKey, interactiveSecret);
+            try {
+                const response = yield this.topiaPublicApi().get(`/world/${urlSlug}/asset-by-unique-name/${uniqueName}`, { headers: { interactiveJWT, publickey: interactivePublicKey } });
+                const { id } = response.data;
+                return new DroppedAsset(this.topia, id, urlSlug, { attributes: response.data });
+            }
+            catch (error) {
+                throw this.errorHandler({ error });
+            }
+        });
+    }
     drop(asset, { interactivePublicKey, position: { x, y }, sceneDropId, uniqueName, urlSlug, yOrderAdjust, }) {
         return __awaiter(this, void 0, void 0, function* () {
             try {

package/dist/index.d.ts

@@ -270,7 +270,7 @@ declare class DroppedAsset extends Asset implements DroppedAssetInterface {
      * await droppedAsset.updatePosition(100,200);
      * ```
      */
-    updatePosition(x: number, y: number, yOrderAdjust: number): Promise<void | ResponseType>;
+    updatePosition(x: number, y: number, yOrderAdjust?: number): Promise<void | ResponseType>;
     /**
      * @summary
      * Updates private zone options for a dropped asset.
@@ -358,6 +358,24 @@ declare class DroppedAsset extends Asset implements DroppedAssetInterface {
         isInteractive?: boolean;
         interactivePublicKey: string;
     }): Promise<void | ResponseType>;
+    /**
+     * @summary
+     * Retrieve analytics for a dropped asset by day, week, month, quarter, or year
+     *
+     * @usage
+     * ```ts
+     * const analytics = await droppedAsset.fetchDroppedAssetAnalytics({
+     *   periodType: "quarter",
+     *   dateValue: 3,
+     *   year: 2023,
+     * });
+     * ```
+     */
+    fetchDroppedAssetAnalytics({ periodType, dateValue, year, }: {
+        periodType: "week" | "month" | "quarter" | "year";
+        dateValue: number;
+        year: number;
+    }): Promise<void | ResponseType>;
 }
 
 /**
@@ -374,6 +392,7 @@ declare class World extends SDKController implements WorldInterface {
     urlSlug: string;
     dataObject?: object | null | undefined;
     sceneDropIds?: [string] | null | undefined;
+    scenes?: [string] | null | undefined;
     webhooks?: WorldWebhooksInterface | null | undefined;
     constructor(topia: Topia, urlSlug: string, options?: WorldOptionalInterface);
     get droppedAssets(): {
@@ -478,6 +497,8 @@ declare class World extends SDKController implements WorldInterface {
      */
     updateCustomTextDroppedAssets(droppedAssetsToUpdate: Array<DroppedAsset>, style: object): Promise<object>;
     /**
+     * @deprecated Use {@link fetchScenes} instead.
+     *
      * @summary
      * Fetch a list of all scene drop ids in a world that include at least one asset with an interactivePublicKey
      *
@@ -492,6 +513,35 @@ declare class World extends SDKController implements WorldInterface {
      * ```
      */
     fetchSceneDropIds(): Promise<object | ResponseType>;
+    /**
+     * @summary
+     * Fetch a list of all scene drop ids and dropped assets in a world
+     *
+     * @usage
+     * ```ts
+     * await world.fetchScenes();
+     * ```
+     *
+     * @result
+     * ```ts
+     * { "scenes": {
+     *     "sceneDropId_1": {
+     *         "droppedAssets": {
+     *             "droppedAssetId_1": {
+     *                 "metaName": "hello"
+     *                 "metaNameReversed": "olleh"
+     *             },
+     *             "droppedAssetId_2": {
+     *                 "metaName": "world"
+     *                 "metaNameReversed": "dlorw"
+     *             }
+     *         }
+     *     },
+     *   }
+     * }
+     * ```
+     */
+    fetchScenes(): Promise<object | ResponseType>;
     /**
      * @summary
      * Drops a scene in a world and returns sceneDropId.
@@ -618,6 +668,24 @@ declare class World extends SDKController implements WorldInterface {
      * ```
      */
     fetchWebhooks(): Promise<void | ResponseType>;
+    /**
+     * @summary
+     * Retrieve world analytics by day, week, month, quarter, or year
+     *
+     * @usage
+     * ```ts
+     * const analytics = await world.fetchWorldAnalytics({
+     *   periodType: "week",
+     *   dateValue: 40,
+     *   year: 2023,
+     * });
+     * ```
+     */
+    fetchWorldAnalytics({ periodType, dateValue, year, }: {
+        periodType: "week" | "month" | "quarter" | "year";
+        dateValue: number;
+        year: number;
+    }): Promise<void | ResponseType>;
 }
 
 /**
@@ -851,6 +919,19 @@ declare class Visitor extends User implements VisitorInterface {
      * ```
      */
     turnAVOff(): Promise<void | ResponseType>;
+    /**
+     * @summary
+     * Grant expression to a visitor by id or name.
+     *
+     * @usage
+     * ```ts
+     * await visitor.grantExpression({ name: "Eyes" });
+     * ```
+     */
+    grantExpression({ id, name }: {
+        id?: string;
+        name?: string;
+    }): Promise<object | ResponseType>;
     /**
      * @summary
      * Retrieves the data object for a visitor.
@@ -1485,6 +1566,7 @@ declare class DroppedAssetFactory extends SDKController {
     constructor(topia: Topia);
     create(id: string, urlSlug: string, options?: DroppedAssetOptionalInterface): DroppedAsset;
     get(id: string, urlSlug: string, options?: DroppedAssetOptionalInterface): Promise<DroppedAsset>;
+    getWithUniqueName(uniqueName: string, urlSlug: string, interactivePublicKey: string, interactiveSecret: string): Promise<DroppedAsset>;
     drop(asset: Asset, { interactivePublicKey, position: { x, y }, sceneDropId, uniqueName, urlSlug, yOrderAdjust, }: {
         interactivePublicKey?: string;
         position: {

package/dist/index.js

@@ -39635,14 +39635,14 @@ const {
  */
 class SDKController {
     constructor(topia, credentials = {}) {
-        const { apiKey = null, assetId = null, interactiveNonce = null, profileId = null, visitorId = null } = credentials;
+        const { apiKey = null, assetId = null, interactiveNonce = null, profileId = null, urlSlug = null, visitorId = null, } = credentials;
         this.topia = topia;
         this.credentials = credentials;
         this.requestOptions = {};
         let payload = {};
         const headers = {};
         try {
-            if (topia.interactiveSecret && (profileId || assetId)) {
+            if (topia.interactiveSecret && (profileId || assetId || urlSlug)) {
                 payload = {
                     interactiveNonce,
                     visitorId,
@@ -39740,7 +39740,7 @@ var _DroppedAsset_updateDroppedAsset;
 class DroppedAsset extends Asset {
     constructor(topia, id, urlSlug, options = { attributes: { text: "" }, credentials: {} }) {
         var _a;
-        super(topia, id, options);
+        super(topia, id, { attributes: options.attributes, credentials: Object.assign(Object.assign({}, options.credentials), { urlSlug }) });
         // private methods
         _DroppedAsset_updateDroppedAsset.set(this, (payload, updateType) => __awaiter(this, void 0, void 0, function* () {
             try {
@@ -40195,6 +40195,40 @@ class DroppedAsset extends Asset {
             }
         });
     }
+    ////////// analytics
+    /**
+     * @summary
+     * Retrieve analytics for a dropped asset by day, week, month, quarter, or year
+     *
+     * @usage
+     * ```ts
+     * const analytics = await droppedAsset.fetchDroppedAssetAnalytics({
+     *   periodType: "quarter",
+     *   dateValue: 3,
+     *   year: 2023,
+     * });
+     * ```
+     */
+    fetchDroppedAssetAnalytics({ periodType, dateValue, year, }) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                let query = "";
+                switch (periodType) {
+                    case "week":
+                        query = `&week=W${dateValue}`;
+                    case "month":
+                        query = `&month=${dateValue}`;
+                    case "quarter":
+                        query = `&quarter=Q${dateValue}`;
+                }
+                const response = yield this.topiaPublicApi().get(`/world/${this.urlSlug}/dropped-asset-analytics/${this.id}?year=${year}${query}`, this.requestOptions);
+                return response.data;
+            }
+            catch (error) {
+                throw this.errorHandler({ error });
+            }
+        });
+    }
 }
 _DroppedAsset_updateDroppedAsset = new WeakMap();
 
@@ -40265,7 +40299,7 @@ var _World_droppedAssetsMap;
  */
 class World extends SDKController {
     constructor(topia, urlSlug, options = { attributes: {}, credentials: {} }) {
-        super(topia, options.credentials);
+        super(topia, Object.assign({ urlSlug }, options.credentials));
         _World_droppedAssetsMap.set(this, void 0);
         ////////// data objects
         /**
@@ -40532,6 +40566,8 @@ class World extends SDKController {
         });
     }
     /**
+     * @deprecated Use {@link fetchScenes} instead.
+     *
      * @summary
      * Fetch a list of all scene drop ids in a world that include at least one asset with an interactivePublicKey
      *
@@ -40557,6 +40593,46 @@ class World extends SDKController {
             }
         });
     }
+    /**
+     * @summary
+     * Fetch a list of all scene drop ids and dropped assets in a world
+     *
+     * @usage
+     * ```ts
+     * await world.fetchScenes();
+     * ```
+     *
+     * @result
+     * ```ts
+     * { "scenes": {
+     *     "sceneDropId_1": {
+     *         "droppedAssets": {
+     *             "droppedAssetId_1": {
+     *                 "metaName": "hello"
+     *                 "metaNameReversed": "olleh"
+     *             },
+     *             "droppedAssetId_2": {
+     *                 "metaName": "world"
+     *                 "metaNameReversed": "dlorw"
+     *             }
+     *         }
+     *     },
+     *   }
+     * }
+     * ```
+     */
+    fetchScenes() {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const response = yield this.topiaPublicApi().get(`/world/${this.urlSlug}/scenes-with-dropped-assets`, this.requestOptions);
+                this.scenes = response.data;
+                return response.data;
+            }
+            catch (error) {
+                throw this.errorHandler({ error });
+            }
+        });
+    }
     /**
      * @summary
      * Drops a scene in a world and returns sceneDropId.
@@ -40663,6 +40739,40 @@ class World extends SDKController {
             }
         });
     }
+    ////////// analytics
+    /**
+     * @summary
+     * Retrieve world analytics by day, week, month, quarter, or year
+     *
+     * @usage
+     * ```ts
+     * const analytics = await world.fetchWorldAnalytics({
+     *   periodType: "week",
+     *   dateValue: 40,
+     *   year: 2023,
+     * });
+     * ```
+     */
+    fetchWorldAnalytics({ periodType, dateValue, year, }) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                let query = "";
+                switch (periodType) {
+                    case "week":
+                        query = `&week=W${dateValue}`;
+                    case "month":
+                        query = `&month=${dateValue}`;
+                    case "quarter":
+                        query = `&quarter=Q${dateValue}`;
+                }
+                const response = yield this.topiaPublicApi().get(`/world/${this.urlSlug}/world-analytics?year=${year}${query}`, this.requestOptions);
+                return response.data;
+            }
+            catch (error) {
+                throw this.errorHandler({ error });
+            }
+        });
+    }
 }
 _World_droppedAssetsMap = new WeakMap();
 
@@ -40952,7 +41062,7 @@ _User_adminWorldsMap = new WeakMap(), _User_assetsMap = new WeakMap(), _User_sce
  */
 class Visitor extends User {
     constructor(topia, id, urlSlug, options = { attributes: {}, credentials: {} }) {
-        super(topia, { credentials: options.credentials });
+        super(topia, { credentials: Object.assign(Object.assign({}, options.credentials), { urlSlug }) });
         Object.assign(this, options.attributes);
         this.id = id;
         this.urlSlug = urlSlug;
@@ -41096,6 +41206,32 @@ class Visitor extends User {
             }
         });
     }
+    /**
+     * @summary
+     * Grant expression to a visitor by id or name.
+     *
+     * @usage
+     * ```ts
+     * await visitor.grantExpression({ name: "Eyes" });
+     * ```
+     */
+    grantExpression({ id, name }) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!id && !name)
+                throw "An expression id or name is required.";
+            try {
+                let expressionId = id;
+                if (name) {
+                    expressionId = yield this.topiaPublicApi().get(`/expressions?name=${name}`, this.requestOptions);
+                }
+                const result = yield this.topiaPublicApi().put(`/world/${this.urlSlug}/visitors/${this.id}/grant-expression/${expressionId}`, {}, this.requestOptions);
+                return result;
+            }
+            catch (error) {
+                throw this.errorHandler({ error });
+            }
+        });
+    }
     /**
      * @summary
      * Retrieves the data object for a visitor.
@@ -41391,6 +41527,19 @@ class DroppedAssetFactory extends SDKController {
             return droppedAsset;
         });
     }
+    getWithUniqueName(uniqueName, urlSlug, interactivePublicKey, interactiveSecret) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const interactiveJWT = jwt.sign(interactivePublicKey, interactiveSecret);
+            try {
+                const response = yield this.topiaPublicApi().get(`/world/${urlSlug}/asset-by-unique-name/${uniqueName}`, { headers: { interactiveJWT, publickey: interactivePublicKey } });
+                const { id } = response.data;
+                return new DroppedAsset(this.topia, id, urlSlug, { attributes: response.data });
+            }
+            catch (error) {
+                throw this.errorHandler({ error });
+            }
+        });
+    }
     drop(asset, { interactivePublicKey, position: { x, y }, sceneDropId, uniqueName, urlSlug, yOrderAdjust, }) {
         return __awaiter(this, void 0, void 0, function* () {
             try {

package/package.json

@@ -59,5 +59,5 @@
     "local-publish": "yarn build && yalc publish --push --no-scripts"
   },
   "type": "module",
-  "version": "0.3.9"
+  "version": "0.5.0"
 }