@rtsdk/topia 0.19.0 → 0.19.2

package/dist/index.cjs

@@ -40683,6 +40683,32 @@ class DroppedAsset extends Asset {
             }
         });
     }
+    /**
+     * Checks if this dropped asset exists with the current app's public key installed.
+     *
+     * @keywords check, exists, verify, validate, lookup
+     *
+     * @example
+     * ```ts
+     * const { exists } = await droppedAsset.checkExists();
+     * ```
+     *
+     * @returns {Promise<{ exists: boolean }>} Returns whether the asset exists with the app's public key.
+     */
+    checkExists() {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const response = yield this.topiaPublicApi().get(`/world/${this.urlSlug}/dropped-asset/${this.id}/exists`, this.requestOptions);
+                return response.data;
+            }
+            catch (error) {
+                throw this.errorHandler({
+                    error,
+                    sdkMethod: "DroppedAsset.checkExists",
+                });
+            }
+        });
+    }
     /**
      * Retrieve analytics for a dropped asset by day, week, month, quarter, or year
      *
@@ -41013,7 +41039,7 @@ 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(), } = options.attributes;
+        const { user_id = "", quantity = 0, grant_source = "unknown", type = "unknown", metadata = {}, created_at = new Date(), updated_at = new Date(), profile_id = null, } = options.attributes;
         this.item_id = item_id;
         this.quantity = quantity;
         this.grant_source = grant_source;
@@ -41022,6 +41048,7 @@ class UserInventoryItem extends InventoryItem {
         this.metadata = metadata;
         this.created_at = created_at;
         this.updated_at = updated_at;
+        this.profile_id = profile_id;
     }
     /**
      * Fetches the user inventory item details from the platform and assigns them to this instance.
@@ -41490,8 +41517,16 @@ class World extends SDKController {
     fetchDroppedAssetsBySceneDropId({ sceneDropId, uniqueName, }) {
         return __awaiter(this, void 0, void 0, function* () {
             try {
-                if (!sceneDropId)
-                    throw this.errorHandler({ message: "A sceneDropId is required." });
+                // Validate sceneDropId to prevent dangerous queries that could match unintended assets
+                if (!sceneDropId ||
+                    typeof sceneDropId !== "string" ||
+                    sceneDropId.trim() === "" ||
+                    sceneDropId === "undefined" ||
+                    sceneDropId === "null") {
+                    throw this.errorHandler({
+                        message: "A valid sceneDropId is required. Received an empty, undefined, or invalid sceneDropId which could match unintended assets.",
+                    });
+                }
                 const response = yield this.topiaPublicApi().get(`/world/${this.urlSlug}/assets-with-scene-drop-id/${sceneDropId}${uniqueName ? `?uniqueName=${uniqueName}` : ""}`, this.requestOptions);
                 // create temp map and then update private property only once
                 const droppedAssets = [];
@@ -43456,27 +43491,31 @@ class Visitor extends User {
     }
     /**
      * Modifies the quantity of an inventory item in this visitor's inventory.
+     * Supports upsert behavior - if the visitor doesn't own the item yet, it will be granted first.
      *
-     * @param item The UserInventoryItem to modify.
-     * @param quantity The new quantity to set.
+     * @param item Either a UserInventoryItem (for owned items) or an InventoryItem (for upsert).
+     * @param quantity The quantity delta to apply (positive to add, negative to subtract).
      *
      * @example
      * ```ts
-     * await visitor.modifyInventoryItemQuantity("item-id-123", 5);
+     * // Modify an existing user inventory item
+     * await visitor.modifyInventoryItemQuantity(userItem, 5);
+     *
+     * // Upsert: grant if not owned, or modify if already owned
+     * await visitor.modifyInventoryItemQuantity(inventoryItem, 1);
      * ```
      *
      * @returns {Promise<UserInventoryItem>} Returns the updated inventory item or a response object.
      */
     modifyInventoryItemQuantity(item, quantity) {
-        var _a;
         return __awaiter(this, void 0, void 0, function* () {
-            // Check for existence in #visitorInventoryItems
-            const found = (_a = __classPrivateFieldGet(this, _Visitor_visitorInventoryItems, "f")) === null || _a === void 0 ? void 0 : _a.some((visitorItem) => visitorItem.id === item.userItemId);
-            if (!found) {
-                throw new Error(`Inventory item with id '${item.userItemId}' does not exist in visitorInventoryItems.`);
-            }
             try {
-                const response = yield this.topiaPublicApi().put(`/world/${this.urlSlug}/visitors/${this.id}/update-visitor-inventory-item-quantity`, { userItemId: item.id, itemId: item.item_id, quantity }, this.requestOptions);
+                // Determine if item is a UserInventoryItem (has userItemId) or InventoryItem (only has id)
+                const isUserItem = "userItemId" in item && item.userItemId;
+                const body = isUserItem
+                    ? { userItemId: item.userItemId, itemId: item.item_id, quantity }
+                    : { itemId: item.id, quantity };
+                const response = yield this.topiaPublicApi().put(`/world/${this.urlSlug}/visitors/${this.id}/update-visitor-inventory-item-quantity`, body, this.requestOptions);
                 const userInventoryItemFactory = new UserInventoryItemFactory(this.topia);
                 const { inventoryItem, user_id, quantity: newQuantity } = response.data;
                 return userInventoryItemFactory.create(inventoryItem, user_id, newQuantity, {

package/dist/index.d.ts

@@ -74,7 +74,7 @@ type DroppedAssetLinkType = {
     linkSamlQueryParams?: string;
 };
 
-type InteractiveCredentials$1 = {
+type InteractiveCredentials = {
     apiKey?: string;
     assetId?: string;
     interactiveNonce?: string;
@@ -88,22 +88,22 @@ type InteractiveCredentials$1 = {
 
 type AssetOptions = {
     attributes?: AssetInterface | undefined;
-    credentials?: InteractiveCredentials$1 | undefined;
+    credentials?: InteractiveCredentials | undefined;
 };
 type DroppedAssetOptions = {
     attributes?: DroppedAssetInterface | undefined;
-    credentials?: InteractiveCredentials$1 | undefined;
+    credentials?: InteractiveCredentials | undefined;
 };
 type UserOptions = {
-    credentials?: InteractiveCredentials$1 | undefined;
+    credentials?: InteractiveCredentials | undefined;
 };
 type VisitorOptions = {
     attributes?: VisitorInterface | undefined;
-    credentials?: InteractiveCredentials$1 | undefined;
+    credentials?: InteractiveCredentials | undefined;
 };
 type WorldOptions = {
     attributes?: WorldDetailsInterface | undefined;
-    credentials?: InteractiveCredentials$1 | undefined;
+    credentials?: InteractiveCredentials | undefined;
 };
 
 type ResponseType$1 = {
@@ -651,6 +651,21 @@ declare class DroppedAsset extends Asset implements DroppedAssetInterface {
         isInteractive?: boolean;
         interactivePublicKey: string;
     }): Promise<void | ResponseType$1>;
+    /**
+     * Checks if this dropped asset exists with the current app's public key installed.
+     *
+     * @keywords check, exists, verify, validate, lookup
+     *
+     * @example
+     * ```ts
+     * const { exists } = await droppedAsset.checkExists();
+     * ```
+     *
+     * @returns {Promise<{ exists: boolean }>} Returns whether the asset exists with the app's public key.
+     */
+    checkExists(): Promise<{
+        exists: boolean;
+    }>;
     /**
      * Retrieve analytics for a dropped asset by day, week, month, quarter, or year
      *
@@ -1190,6 +1205,7 @@ declare class UserInventoryItem extends InventoryItem implements UserInventoryIt
     metadata?: object | null;
     grant_source: string;
     type: string;
+    profile_id?: string | null;
     constructor(topia: Topia, id: string, options?: UserInventoryItemOptionalInterface);
     /**
      * Fetches the user inventory item details from the platform and assigns them to this instance.
@@ -2143,18 +2159,23 @@ declare class Visitor extends User implements VisitorInterface {
     grantInventoryItem(item: InventoryItem, quantity?: number): Promise<UserInventoryItem>;
     /**
      * Modifies the quantity of an inventory item in this visitor's inventory.
+     * Supports upsert behavior - if the visitor doesn't own the item yet, it will be granted first.
      *
-     * @param item The UserInventoryItem to modify.
-     * @param quantity The new quantity to set.
+     * @param item Either a UserInventoryItem (for owned items) or an InventoryItem (for upsert).
+     * @param quantity The quantity delta to apply (positive to add, negative to subtract).
      *
      * @example
      * ```ts
-     * await visitor.modifyInventoryItemQuantity("item-id-123", 5);
+     * // Modify an existing user inventory item
+     * await visitor.modifyInventoryItemQuantity(userItem, 5);
+     *
+     * // Upsert: grant if not owned, or modify if already owned
+     * await visitor.modifyInventoryItemQuantity(inventoryItem, 1);
      * ```
      *
      * @returns {Promise<UserInventoryItem>} Returns the updated inventory item or a response object.
      */
-    modifyInventoryItemQuantity(item: UserInventoryItem, quantity: number): Promise<UserInventoryItem>;
+    modifyInventoryItemQuantity(item: UserInventoryItem | InventoryItem, quantity: number): Promise<UserInventoryItem>;
 }
 
 type VisitorType = {
@@ -2197,7 +2218,7 @@ declare enum WorldActivityType {
 }
 
 interface SDKInterface {
-    credentials?: InteractiveCredentials$1;
+    credentials?: InteractiveCredentials;
     jwt?: string;
     requestOptions: object;
     topia: Topia;
@@ -2234,7 +2255,7 @@ interface AssetInterface extends SDKInterface {
 }
 type AssetOptionalInterface = {
     attributes?: AssetInterface | object;
-    credentials?: InteractiveCredentials$1;
+    credentials?: InteractiveCredentials;
 };
 
 interface DroppedAssetInterface extends AssetInterface {
@@ -2356,7 +2377,7 @@ interface DroppedAssetOptionalInterface {
         text?: string;
         urlSlug?: string;
     };
-    credentials?: InteractiveCredentials$1 | object;
+    credentials?: InteractiveCredentials | object;
 }
 interface UpdateBroadcastInterface {
     assetBroadcast?: boolean;
@@ -2448,7 +2469,7 @@ interface EcosystemInterface {
     incrementDataObjectValue(path: string, amount: number, options: object): Promise<void | ResponseType$1>;
 }
 interface EcosystemOptionalInterface {
-    credentials?: InteractiveCredentials$1;
+    credentials?: InteractiveCredentials;
 }
 
 interface SceneInterface {
@@ -2476,7 +2497,7 @@ interface SceneInterface {
 }
 type SceneOptionalInterface = {
     attributes?: SceneInterface | object;
-    credentials?: InteractiveCredentials$1;
+    credentials?: InteractiveCredentials;
 };
 
 interface FireToastInterface {
@@ -2524,7 +2545,7 @@ interface UserInterface {
     dataObject?: object | null;
 }
 interface UserOptionalInterface {
-    credentials?: InteractiveCredentials$1;
+    credentials?: InteractiveCredentials;
     profileId?: string | null;
     visitorId?: number | null;
     urlSlug?: string;
@@ -2600,7 +2621,7 @@ interface VisitorInterface extends SDKInterface {
 }
 interface VisitorOptionalInterface {
     attributes?: VisitorInterface | object;
-    credentials?: InteractiveCredentials$1;
+    credentials?: InteractiveCredentials;
 }
 interface MoveVisitorInterface {
     shouldTeleportVisitor: boolean;
@@ -2633,12 +2654,12 @@ interface WebRTCConnectorInterface {
     getTwilioConfig(): Promise<void | ResponseType$1>;
 }
 interface WebRTCConnectorOptionalInterface {
-    credentials?: InteractiveCredentials$1;
+    credentials?: InteractiveCredentials;
     twilioConfig?: object;
 }
 
 interface WorldActivityOptionalInterface {
-    credentials?: InteractiveCredentials$1;
+    credentials?: InteractiveCredentials;
 }
 interface MoveAllVisitorsInterface {
     shouldFetchVisitors?: boolean;
@@ -2728,13 +2749,13 @@ interface WorldInterface extends SDKInterface, WorldDetailsInterface {
 }
 interface WorldOptionalInterface {
     attributes?: WorldDetailsInterface | object;
-    credentials?: InteractiveCredentials$1;
+    credentials?: InteractiveCredentials;
 }
 interface WorldWebhooksInterface {
     webhooks: Array<WebhookInterface>;
 }
 
-type InteractiveCredentials = {
+type InteractiveCredentials$1 = {
     apiKey?: string;
     assetId?: string;
     interactiveNonce?: string;
@@ -2763,7 +2784,7 @@ interface InventoryItemInterface extends SDKInterface {
 }
 type InventoryItemOptionalInterface = {
     attributes?: InventoryItemInterface | object;
-    credentials?: InteractiveCredentials;
+    credentials?: InteractiveCredentials$1;
 };
 
 /**
@@ -2778,10 +2799,11 @@ interface UserInventoryItemInterface extends InventoryItemInterface {
     updated_at?: Date;
     metadata?: object | null;
     grant_source: string;
+    profile_id?: string | null;
 }
 type UserInventoryItemOptionalInterface = {
     attributes?: UserInventoryItemInterface | object;
-    credentials?: InteractiveCredentials;
+    credentials?: InteractiveCredentials$1;
 };
 
 /**
@@ -2837,11 +2859,11 @@ declare class Topia implements TopiaInterface {
  * ```
  */
 declare abstract class SDKController implements SDKInterface {
-    credentials: InteractiveCredentials$1 | undefined;
+    credentials: InteractiveCredentials | undefined;
     jwt?: string;
     requestOptions: object;
     topia: Topia;
-    constructor(topia: Topia, credentials?: InteractiveCredentials$1);
+    constructor(topia: Topia, credentials?: InteractiveCredentials);
     topiaPublicApi(): axios.AxiosInstance;
     errorHandler({ error, message, params, sdkMethod, }: {
         error?: Error | AxiosError | unknown;
@@ -3421,7 +3443,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$1): Promise<DroppedAsset>;
+    getWithUniqueName(uniqueName: string, urlSlug: string, interactiveSecret: string, credentials: InteractiveCredentials): Promise<DroppedAsset>;
     /**
      * Drops an asset in a world and returns a new instance of DroppedAsset class with all properties.
      *
@@ -4003,4 +4025,4 @@ declare class WorldFactory extends SDKController {
     }>;
 }
 
-export { AnalyticType, AnimationMetaType, Asset, AssetFactory, AssetInterface, AssetOptionalInterface, AssetOptions, AssetType, DroppedAsset, DroppedAssetClickType, DroppedAssetFactory, DroppedAssetInterface, DroppedAssetLinkType, DroppedAssetMediaType, DroppedAssetMediaVolumeRadius, DroppedAssetOptionalInterface, DroppedAssetOptions, Ecosystem, EcosystemFactory, EcosystemInterface, EcosystemOptionalInterface, FireToastInterface, FrameType, InteractiveCredentials$1 as InteractiveCredentials, InventoryItemInterface, InventoryItemOptionalInterface, MoveAllVisitorsInterface, MoveVisitorInterface, OpenIframeInterface, RemoveClickableLinkInterface, ResponseType$1 as ResponseType, SDKController, SDKInterface, Scene, SceneFactory, SceneInterface, SceneOptionalInterface, SetClickableLinkMultiInterface, Topia, TopiaInterface, UpdateBroadcastInterface, UpdateClickTypeInterface, UpdateClickableLinkMultiInterface, UpdateDroppedAssetInterface, UpdateMediaTypeInterface, UpdatePrivateZoneInterface, User, UserFactory, UserInterface, UserInventoryItemInterface, 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, InventoryItemInterface, InventoryItemOptionalInterface, MoveAllVisitorsInterface, MoveVisitorInterface, OpenIframeInterface, RemoveClickableLinkInterface, ResponseType$1 as ResponseType, SDKController, SDKInterface, Scene, SceneFactory, SceneInterface, SceneOptionalInterface, SetClickableLinkMultiInterface, Topia, TopiaInterface, UpdateBroadcastInterface, UpdateClickTypeInterface, UpdateClickableLinkMultiInterface, UpdateDroppedAssetInterface, UpdateMediaTypeInterface, UpdatePrivateZoneInterface, User, UserFactory, UserInterface, UserInventoryItemInterface, 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

@@ -40681,6 +40681,32 @@ class DroppedAsset extends Asset {
             }
         });
     }
+    /**
+     * Checks if this dropped asset exists with the current app's public key installed.
+     *
+     * @keywords check, exists, verify, validate, lookup
+     *
+     * @example
+     * ```ts
+     * const { exists } = await droppedAsset.checkExists();
+     * ```
+     *
+     * @returns {Promise<{ exists: boolean }>} Returns whether the asset exists with the app's public key.
+     */
+    checkExists() {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const response = yield this.topiaPublicApi().get(`/world/${this.urlSlug}/dropped-asset/${this.id}/exists`, this.requestOptions);
+                return response.data;
+            }
+            catch (error) {
+                throw this.errorHandler({
+                    error,
+                    sdkMethod: "DroppedAsset.checkExists",
+                });
+            }
+        });
+    }
     /**
      * Retrieve analytics for a dropped asset by day, week, month, quarter, or year
      *
@@ -41011,7 +41037,7 @@ 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(), } = options.attributes;
+        const { user_id = "", quantity = 0, grant_source = "unknown", type = "unknown", metadata = {}, created_at = new Date(), updated_at = new Date(), profile_id = null, } = options.attributes;
         this.item_id = item_id;
         this.quantity = quantity;
         this.grant_source = grant_source;
@@ -41020,6 +41046,7 @@ class UserInventoryItem extends InventoryItem {
         this.metadata = metadata;
         this.created_at = created_at;
         this.updated_at = updated_at;
+        this.profile_id = profile_id;
     }
     /**
      * Fetches the user inventory item details from the platform and assigns them to this instance.
@@ -41488,8 +41515,16 @@ class World extends SDKController {
     fetchDroppedAssetsBySceneDropId({ sceneDropId, uniqueName, }) {
         return __awaiter(this, void 0, void 0, function* () {
             try {
-                if (!sceneDropId)
-                    throw this.errorHandler({ message: "A sceneDropId is required." });
+                // Validate sceneDropId to prevent dangerous queries that could match unintended assets
+                if (!sceneDropId ||
+                    typeof sceneDropId !== "string" ||
+                    sceneDropId.trim() === "" ||
+                    sceneDropId === "undefined" ||
+                    sceneDropId === "null") {
+                    throw this.errorHandler({
+                        message: "A valid sceneDropId is required. Received an empty, undefined, or invalid sceneDropId which could match unintended assets.",
+                    });
+                }
                 const response = yield this.topiaPublicApi().get(`/world/${this.urlSlug}/assets-with-scene-drop-id/${sceneDropId}${uniqueName ? `?uniqueName=${uniqueName}` : ""}`, this.requestOptions);
                 // create temp map and then update private property only once
                 const droppedAssets = [];
@@ -43454,27 +43489,31 @@ class Visitor extends User {
     }
     /**
      * Modifies the quantity of an inventory item in this visitor's inventory.
+     * Supports upsert behavior - if the visitor doesn't own the item yet, it will be granted first.
      *
-     * @param item The UserInventoryItem to modify.
-     * @param quantity The new quantity to set.
+     * @param item Either a UserInventoryItem (for owned items) or an InventoryItem (for upsert).
+     * @param quantity The quantity delta to apply (positive to add, negative to subtract).
      *
      * @example
      * ```ts
-     * await visitor.modifyInventoryItemQuantity("item-id-123", 5);
+     * // Modify an existing user inventory item
+     * await visitor.modifyInventoryItemQuantity(userItem, 5);
+     *
+     * // Upsert: grant if not owned, or modify if already owned
+     * await visitor.modifyInventoryItemQuantity(inventoryItem, 1);
      * ```
      *
      * @returns {Promise<UserInventoryItem>} Returns the updated inventory item or a response object.
      */
     modifyInventoryItemQuantity(item, quantity) {
-        var _a;
         return __awaiter(this, void 0, void 0, function* () {
-            // Check for existence in #visitorInventoryItems
-            const found = (_a = __classPrivateFieldGet(this, _Visitor_visitorInventoryItems, "f")) === null || _a === void 0 ? void 0 : _a.some((visitorItem) => visitorItem.id === item.userItemId);
-            if (!found) {
-                throw new Error(`Inventory item with id '${item.userItemId}' does not exist in visitorInventoryItems.`);
-            }
             try {
-                const response = yield this.topiaPublicApi().put(`/world/${this.urlSlug}/visitors/${this.id}/update-visitor-inventory-item-quantity`, { userItemId: item.id, itemId: item.item_id, quantity }, this.requestOptions);
+                // Determine if item is a UserInventoryItem (has userItemId) or InventoryItem (only has id)
+                const isUserItem = "userItemId" in item && item.userItemId;
+                const body = isUserItem
+                    ? { userItemId: item.userItemId, itemId: item.item_id, quantity }
+                    : { itemId: item.id, quantity };
+                const response = yield this.topiaPublicApi().put(`/world/${this.urlSlug}/visitors/${this.id}/update-visitor-inventory-item-quantity`, body, this.requestOptions);
                 const userInventoryItemFactory = new UserInventoryItemFactory(this.topia);
                 const { inventoryItem, user_id, quantity: newQuantity } = response.data;
                 return userInventoryItemFactory.create(inventoryItem, user_id, newQuantity, {

package/package.json

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