@rtsdk/topia 0.18.3 → 0.19.1

package/README.md

@@ -317,8 +317,6 @@ Once complete be sure to also call `await keyAsset.updateDataObject({ turnCount:
 
 You can leverage the data object methods for all types to track analytics unique to your Public Key by passing `analytics` as an optional array along with `profileId`, `urlSlug`, and/or `uniqueKey` to all calls that set, update, or increment data objects!
 
-**World** and **Dropped Asset** classes will automatically include `urlSlug`. In addition to `analytics` you can also pass `profileId` if you want to track event per user and/or a `uniqueKey` to additionally track uniqueness of the event for all time, per user (if `profileId` is included), and per world.
-
 Examples leveraging World data objects calls:
 
 ```ts
@@ -329,8 +327,6 @@ await world.updateDataObject({}, { analytics: [ {analyticName: "matches", unique
 await world.incrementDataObjectValue(`keyAssets.${assetId}.completions`, 1, { analytics: [{ analyticName:"completions", incrementBy: 2, profileId, uniqueKey: profileId, urlSlug }] });
 ```
 
-**Visitor** and **User** classes will automatically include `profileId`. In addition to `analytics` you can also pass `urlSlug` if you want to track event per world and/or a `uniqueKey` to additionally track uniqueness of the event for all time, per user, and per world (if `urlSlug` is included).
-
 Examples leveraging Visitor data objects calls:
 
 ```ts
@@ -349,7 +345,7 @@ await visitor.incrementDataObjectValue(`completions`, 1, {
 });
 ```
 
-Note: This 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 (incremented by 1) across all instances of your application with a given Public Key.
 
 <br>
 

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.
@@ -42701,7 +42728,7 @@ class User extends SDKController {
      * await user.modifyInventoryItemQuantity("item-id-123", 5);
      * ```
      *
-     * @returns {Promise<UserInventoryItem>} Returns the updated inventory or a response object.
+     * @returns {Promise<UserInventoryItem>} Returns the updated inventory item or a response object.
      */
     modifyInventoryItemQuantity(item, quantity) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -43287,7 +43314,7 @@ class Visitor extends User {
      * const items = await visitor.fetchInventoryItems();
      * ```
      *
-     * @returns {Promise<void>} Returns an array of InventoryItem objects.
+     * @returns {Promise<void>} Returns a new instance of InventoryItem.
      */
     fetchInventoryItem(item) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -43303,6 +43330,88 @@ class Visitor extends User {
             }
         });
     }
+    /**
+     * Gets an NPC for this visitor, if one exists.
+     *
+     * @example
+     * ```ts
+     * await visitor.getNpc();
+     * ```
+     *
+     * @returns {Promise<Visitor | null>} Returns a Visitor object representing the NPC.
+     */
+    getNpc() {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const visitorResponse = yield this.topiaPublicApi().get(`/world/${this.urlSlug}/visitors/${this.id}/get-npc`, this.requestOptions);
+                if (visitorResponse.data)
+                    return new Visitor(this.topia, visitorResponse.data.playerId, this.urlSlug, {
+                        attributes: visitorResponse.data,
+                        credentials: this.credentials,
+                    });
+                return null;
+            }
+            catch (error) {
+                throw this.errorHandler({ error, sdkMethod: "Visitor.getNpc" });
+            }
+        });
+    }
+    /**
+     * Creates an NPC that follows this visitor using an inventory item the visitor owns.
+     * One NPC is allowed per visitor, per application public key.
+     *
+     * @param userInventoryItemId The ID of the user's inventory item (must be an NPC type item owned by this visitor).
+     * @param options Optional configuration for the NPC.
+     * @param options.showNameplate Whether to display a nameplate above the NPC (default: true).
+     *
+     * @example
+     * ```ts
+     * // First, grant the NPC item to the visitor
+     * const userItem = await visitor.grantInventoryItem(npcInventoryItem, 1);
+     *
+     * // Then create the NPC using the granted item
+     * const npc = await visitor.createNpc(userItem.id);
+     *
+     * // Or create without a nameplate
+     * const npc = await visitor.createNpc(userItem.id, { showNameplate: false });
+     * ```
+     *
+     * @returns {Promise<Visitor>} Returns a Visitor object representing the created NPC.
+     */
+    createNpc(userInventoryItemId, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const response = yield this.topiaPublicApi().post(`/world/${this.urlSlug}/visitors/${this.id}/create-npc`, { userInventoryItemId, showNameplate: options === null || options === void 0 ? void 0 : options.showNameplate }, this.requestOptions);
+                return new Visitor(this.topia, response.data.player.playerId, this.urlSlug, {
+                    attributes: response.data,
+                    credentials: this.credentials,
+                });
+            }
+            catch (error) {
+                throw this.errorHandler({ error, sdkMethod: "Visitor.createNpc" });
+            }
+        });
+    }
+    /**
+     * Deletes the NPC this app has assigned to this visitor.
+     *
+     * @example
+     * ```ts
+     * await visitor.deleteNpc();
+     * ```
+     *
+     * @returns {Promise<void>} Returns nothing if successful.
+     */
+    deleteNpc() {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                yield this.topiaPublicApi().delete(`/world/${this.urlSlug}/visitors/${this.id}/delete-npc`, this.requestOptions);
+            }
+            catch (error) {
+                throw this.errorHandler({ error, sdkMethod: "Visitor.deleteNpc" });
+            }
+        });
+    }
     /**
      * Retrieves all inventory items owned by this visitor and app's key.
      *
@@ -43348,7 +43457,7 @@ class Visitor extends User {
      * await visitor.grantInventoryItem("item-id-123", 2);
      * ```
      *
-     * @returns {Promise<UserInventoryItem>} Returns the updated inventory or a response object.
+     * @returns {Promise<UserInventoryItem>} Returns the updated inventory item or a response object.
      */
     grantInventoryItem(item, quantity = 1) {
         var _a;
@@ -43374,27 +43483,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 or a response object.
+     * @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, {
@@ -44811,7 +44924,7 @@ class WorldFactory extends SDKController {
                         headers,
                     }));
                 }
-                yield Promise.all(promiseArray);
+                yield Promise.allSettled(promiseArray);
                 return { success: true };
             }
             catch (error) {

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$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.
@@ -1719,7 +1735,7 @@ declare class User extends SDKController implements UserInterface {
      * await user.modifyInventoryItemQuantity("item-id-123", 5);
      * ```
      *
-     * @returns {Promise<UserInventoryItem>} Returns the updated inventory or a response object.
+     * @returns {Promise<UserInventoryItem>} Returns the updated inventory item or a response object.
      */
     modifyInventoryItemQuantity(item: UserInventoryItem, quantity: number): Promise<UserInventoryItem>;
 }
@@ -2063,9 +2079,56 @@ declare class Visitor extends User implements VisitorInterface {
      * const items = await visitor.fetchInventoryItems();
      * ```
      *
-     * @returns {Promise<void>} Returns an array of InventoryItem objects.
+     * @returns {Promise<void>} Returns a new instance of InventoryItem.
      */
     fetchInventoryItem(item: InventoryItem): Promise<UserInventoryItem>;
+    /**
+     * Gets an NPC for this visitor, if one exists.
+     *
+     * @example
+     * ```ts
+     * await visitor.getNpc();
+     * ```
+     *
+     * @returns {Promise<Visitor | null>} Returns a Visitor object representing the NPC.
+     */
+    getNpc(): Promise<Visitor | null>;
+    /**
+     * Creates an NPC that follows this visitor using an inventory item the visitor owns.
+     * One NPC is allowed per visitor, per application public key.
+     *
+     * @param userInventoryItemId The ID of the user's inventory item (must be an NPC type item owned by this visitor).
+     * @param options Optional configuration for the NPC.
+     * @param options.showNameplate Whether to display a nameplate above the NPC (default: true).
+     *
+     * @example
+     * ```ts
+     * // First, grant the NPC item to the visitor
+     * const userItem = await visitor.grantInventoryItem(npcInventoryItem, 1);
+     *
+     * // Then create the NPC using the granted item
+     * const npc = await visitor.createNpc(userItem.id);
+     *
+     * // Or create without a nameplate
+     * const npc = await visitor.createNpc(userItem.id, { showNameplate: false });
+     * ```
+     *
+     * @returns {Promise<Visitor>} Returns a Visitor object representing the created NPC.
+     */
+    createNpc(userInventoryItemId: string, options?: {
+        showNameplate?: boolean;
+    }): Promise<Visitor>;
+    /**
+     * Deletes the NPC this app has assigned to this visitor.
+     *
+     * @example
+     * ```ts
+     * await visitor.deleteNpc();
+     * ```
+     *
+     * @returns {Promise<void>} Returns nothing if successful.
+     */
+    deleteNpc(): Promise<void>;
     /**
      * Retrieves all inventory items owned by this visitor and app's key.
      *
@@ -2091,23 +2154,28 @@ declare class Visitor extends User implements VisitorInterface {
      * await visitor.grantInventoryItem("item-id-123", 2);
      * ```
      *
-     * @returns {Promise<UserInventoryItem>} Returns the updated inventory or a response object.
+     * @returns {Promise<UserInventoryItem>} Returns the updated inventory item or a response object.
      */
     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 or a response object.
+     * @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 = {
@@ -2150,7 +2218,7 @@ declare enum WorldActivityType {
 }
 
 interface SDKInterface {
-    credentials?: InteractiveCredentials;
+    credentials?: InteractiveCredentials$1;
     jwt?: string;
     requestOptions: object;
     topia: Topia;
@@ -2187,7 +2255,7 @@ interface AssetInterface extends SDKInterface {
 }
 type AssetOptionalInterface = {
     attributes?: AssetInterface | object;
-    credentials?: InteractiveCredentials;
+    credentials?: InteractiveCredentials$1;
 };
 
 interface DroppedAssetInterface extends AssetInterface {
@@ -2309,7 +2377,7 @@ interface DroppedAssetOptionalInterface {
         text?: string;
         urlSlug?: string;
     };
-    credentials?: InteractiveCredentials | object;
+    credentials?: InteractiveCredentials$1 | object;
 }
 interface UpdateBroadcastInterface {
     assetBroadcast?: boolean;
@@ -2401,7 +2469,7 @@ interface EcosystemInterface {
     incrementDataObjectValue(path: string, amount: number, options: object): Promise<void | ResponseType$1>;
 }
 interface EcosystemOptionalInterface {
-    credentials?: InteractiveCredentials;
+    credentials?: InteractiveCredentials$1;
 }
 
 interface SceneInterface {
@@ -2429,7 +2497,7 @@ interface SceneInterface {
 }
 type SceneOptionalInterface = {
     attributes?: SceneInterface | object;
-    credentials?: InteractiveCredentials;
+    credentials?: InteractiveCredentials$1;
 };
 
 interface FireToastInterface {
@@ -2468,6 +2536,7 @@ interface UserInterface {
     }): Promise<ResponseType$1>;
     fetchDataObject(appPublicKey?: string, appJWT?: string): Promise<void | ResponseType$1>;
     setDataObject(dataObject: object | null | undefined, options: object): Promise<void | ResponseType$1>;
+    updateDataObject(dataObject: object, options: object): Promise<void | ResponseType$1>;
     incrementDataObjectValue(path: string, amount: number, options: object): Promise<void | ResponseType$1>;
     fetchInventoryItems(): Promise<void>;
     inventoryItems: UserInventoryItem[];
@@ -2476,7 +2545,7 @@ interface UserInterface {
     dataObject?: object | null;
 }
 interface UserOptionalInterface {
-    credentials?: InteractiveCredentials;
+    credentials?: InteractiveCredentials$1;
     profileId?: string | null;
     visitorId?: number | null;
     urlSlug?: string;
@@ -2504,6 +2573,11 @@ interface VisitorInterface extends SDKInterface {
     grantInventoryItem(item: InventoryItem, quantity: number): Promise<UserInventoryItem>;
     modifyInventoryItemQuantity(item: UserInventoryItem, quantity: number): Promise<UserInventoryItem>;
     fetchInventoryItem(item: InventoryItem): Promise<UserInventoryItem>;
+    createNpc(userInventoryItemId: string, options?: {
+        showNameplate?: boolean;
+    }): Promise<Visitor>;
+    deleteNpc(): Promise<void>;
+    getNpc(): Promise<Visitor | null>;
     triggerParticle({ id, name, duration, }: {
         id?: string;
         name?: string;
@@ -2547,7 +2621,7 @@ interface VisitorInterface extends SDKInterface {
 }
 interface VisitorOptionalInterface {
     attributes?: VisitorInterface | object;
-    credentials?: InteractiveCredentials;
+    credentials?: InteractiveCredentials$1;
 }
 interface MoveVisitorInterface {
     shouldTeleportVisitor: boolean;
@@ -2580,12 +2654,12 @@ interface WebRTCConnectorInterface {
     getTwilioConfig(): Promise<void | ResponseType$1>;
 }
 interface WebRTCConnectorOptionalInterface {
-    credentials?: InteractiveCredentials;
+    credentials?: InteractiveCredentials$1;
     twilioConfig?: object;
 }
 
 interface WorldActivityOptionalInterface {
-    credentials?: InteractiveCredentials;
+    credentials?: InteractiveCredentials$1;
 }
 interface MoveAllVisitorsInterface {
     shouldFetchVisitors?: boolean;
@@ -2675,13 +2749,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;
@@ -2710,7 +2784,7 @@ interface InventoryItemInterface extends SDKInterface {
 }
 type InventoryItemOptionalInterface = {
     attributes?: InventoryItemInterface | object;
-    credentials?: InteractiveCredentials$1;
+    credentials?: InteractiveCredentials;
 };
 
 /**
@@ -2725,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$1;
+    credentials?: InteractiveCredentials;
 };
 
 /**
@@ -2784,11 +2859,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);
     topiaPublicApi(): axios.AxiosInstance;
     errorHandler({ error, message, params, sdkMethod, }: {
         error?: Error | AxiosError | unknown;
@@ -3368,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): 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.
      *
@@ -3950,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, 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$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 };

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.
@@ -42699,7 +42726,7 @@ class User extends SDKController {
      * await user.modifyInventoryItemQuantity("item-id-123", 5);
      * ```
      *
-     * @returns {Promise<UserInventoryItem>} Returns the updated inventory or a response object.
+     * @returns {Promise<UserInventoryItem>} Returns the updated inventory item or a response object.
      */
     modifyInventoryItemQuantity(item, quantity) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -43285,7 +43312,7 @@ class Visitor extends User {
      * const items = await visitor.fetchInventoryItems();
      * ```
      *
-     * @returns {Promise<void>} Returns an array of InventoryItem objects.
+     * @returns {Promise<void>} Returns a new instance of InventoryItem.
      */
     fetchInventoryItem(item) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -43301,6 +43328,88 @@ class Visitor extends User {
             }
         });
     }
+    /**
+     * Gets an NPC for this visitor, if one exists.
+     *
+     * @example
+     * ```ts
+     * await visitor.getNpc();
+     * ```
+     *
+     * @returns {Promise<Visitor | null>} Returns a Visitor object representing the NPC.
+     */
+    getNpc() {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const visitorResponse = yield this.topiaPublicApi().get(`/world/${this.urlSlug}/visitors/${this.id}/get-npc`, this.requestOptions);
+                if (visitorResponse.data)
+                    return new Visitor(this.topia, visitorResponse.data.playerId, this.urlSlug, {
+                        attributes: visitorResponse.data,
+                        credentials: this.credentials,
+                    });
+                return null;
+            }
+            catch (error) {
+                throw this.errorHandler({ error, sdkMethod: "Visitor.getNpc" });
+            }
+        });
+    }
+    /**
+     * Creates an NPC that follows this visitor using an inventory item the visitor owns.
+     * One NPC is allowed per visitor, per application public key.
+     *
+     * @param userInventoryItemId The ID of the user's inventory item (must be an NPC type item owned by this visitor).
+     * @param options Optional configuration for the NPC.
+     * @param options.showNameplate Whether to display a nameplate above the NPC (default: true).
+     *
+     * @example
+     * ```ts
+     * // First, grant the NPC item to the visitor
+     * const userItem = await visitor.grantInventoryItem(npcInventoryItem, 1);
+     *
+     * // Then create the NPC using the granted item
+     * const npc = await visitor.createNpc(userItem.id);
+     *
+     * // Or create without a nameplate
+     * const npc = await visitor.createNpc(userItem.id, { showNameplate: false });
+     * ```
+     *
+     * @returns {Promise<Visitor>} Returns a Visitor object representing the created NPC.
+     */
+    createNpc(userInventoryItemId, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const response = yield this.topiaPublicApi().post(`/world/${this.urlSlug}/visitors/${this.id}/create-npc`, { userInventoryItemId, showNameplate: options === null || options === void 0 ? void 0 : options.showNameplate }, this.requestOptions);
+                return new Visitor(this.topia, response.data.player.playerId, this.urlSlug, {
+                    attributes: response.data,
+                    credentials: this.credentials,
+                });
+            }
+            catch (error) {
+                throw this.errorHandler({ error, sdkMethod: "Visitor.createNpc" });
+            }
+        });
+    }
+    /**
+     * Deletes the NPC this app has assigned to this visitor.
+     *
+     * @example
+     * ```ts
+     * await visitor.deleteNpc();
+     * ```
+     *
+     * @returns {Promise<void>} Returns nothing if successful.
+     */
+    deleteNpc() {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                yield this.topiaPublicApi().delete(`/world/${this.urlSlug}/visitors/${this.id}/delete-npc`, this.requestOptions);
+            }
+            catch (error) {
+                throw this.errorHandler({ error, sdkMethod: "Visitor.deleteNpc" });
+            }
+        });
+    }
     /**
      * Retrieves all inventory items owned by this visitor and app's key.
      *
@@ -43346,7 +43455,7 @@ class Visitor extends User {
      * await visitor.grantInventoryItem("item-id-123", 2);
      * ```
      *
-     * @returns {Promise<UserInventoryItem>} Returns the updated inventory or a response object.
+     * @returns {Promise<UserInventoryItem>} Returns the updated inventory item or a response object.
      */
     grantInventoryItem(item, quantity = 1) {
         var _a;
@@ -43372,27 +43481,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 or a response object.
+     * @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, {
@@ -44809,7 +44922,7 @@ class WorldFactory extends SDKController {
                         headers,
                     }));
                 }
-                yield Promise.all(promiseArray);
+                yield Promise.allSettled(promiseArray);
                 return { success: true };
             }
             catch (error) {

package/package.json

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