Class User

Create an instance of User class with optional session credentials.

Example

import { User } from "utils/topiaInit.ts";

const user = await User.create({
  profileId: "exampleProfileId",
  credentials: { interactivePublicKey: "examplePublicKey", interactiveNonce: "exampleNonce", assetId: "exampleDroppedAssetId", profileId: "exampleProfileId", visitorId: 1, urlSlug: "exampleUrlSlug" }
});

Hierarchy (View Summary)

SDKController
- User
  - Visitor

Implements

UserInterface

Assets

fetchAssets

fetchAssets(): Promise<void | ResponseType>
Returns all assets owned by User when an email address is provided.

Returns Promise<void | ResponseType>
Keywords
get, fetch, retrieve, list, user assets, objects
Example
```
await user.fetchAssets();
const userAssets = user.assets;
```
Implementation of UserInterface.fetchAssets
- Defined in controllers/User.ts:384

fetchPlatformAssets

fetchPlatformAssets(): Promise<object | ResponseType>
Returns all platform assets.

Returns Promise<object | ResponseType>
Returns the platform assets or an error response.
Keywords
get, fetch, retrieve, list, platform assets, objects
Example
```
const assets = await user.fetchPlatformAssets();
```
Implementation of UserInterface.fetchPlatformAssets
- Defined in controllers/User.ts:415

Avatars

addAvatar

addAvatar(formData: FormData): Promise<void | ResponseType>

Add a new avatar

Parameters

formData: FormData

Returns Promise<void | ResponseType>

Keywords

add, create, upload, avatar, character

Example

const animationMeta = {
  "emote": { "loop": false, "x": 0, "y": 0, "hideLoop": true }
}

const spriteSheetJSON = {
  "animations": {
    "emote": [
      "emote/1.png"
    ]
  },
  "frames": {
    "emote/1.png": {
      "frame": {
       "x": 1911,
       "y": 778,
       "w": 58,
       "h": 91
     },
     "rotated": true,
     "trimmed": true,
     "spriteSourceSize": {
       "x": 50,
       "y": 33,
       "w": 58,
       "h": 91
     },
     "sourceSize": {
       "w": 159,
       "h": 159
     }
   }
 },
 "spriteSheetTypeMeta": {
   "nameplate": {
     "x": 0,
     "y": -70
   }
 },
 "meta": {
   "image": "spriteSheets%2FTvHNjgoMkiErDNSrVqHU%2FspriteSheet.png?alt=media",
   "format": "RGBA8888",
   "size": {
     "w": 2006,
     "h": 1099
   },
   "scale": "1"
 }
}

const formData = new FormData();
formData.append('animationMeta', animationMeta);
formData.append('name', "ExampleAvatarName");
formData.append('spriteSheetJSON', spriteSheetJSON);
formData.append('expression_dance', expression_dance);
formData.append('expression_emote', expression_emote);
formData.append('expression_sit', expression_sit);
formData.append('expression_stand', expression_stand);
formData.append('expression_transport', expression_transport);
formData.append('preview', preview);
formData.append('spriteSheet', spriteSheet);
formData.append('unityPackage', unityPackage);
await user.uploadAvatarFiles("exampleAvatarId", formData);

deleteAvatar

deleteAvatar(avatarId: string): Promise<void | ResponseType>
Update avatar and sprite sheet records and upload files to existing sprite sheet and avatar storage buckets
Parameters
- avatarId: string
Returns Promise<void | ResponseType>
Keywords
delete, remove, erase, destroy, eliminate, avatar
Example
```
await user.deleteAvatar("exampleAvatarId");
```
Implementation of UserInterface.deleteAvatar
- Defined in controllers/User.ts:359

fetchAvatars

fetchAvatars(): Promise<void | ResponseType>
Returns all avatars owned by User

Returns Promise<void | ResponseType>
Returns the avatars or an error.
Keywords
get, fetch, retrieve, list, avatars, characters
Example
```
const avatars = await user.fetchAvatars();
```
Implementation of UserInterface.fetchAvatars
- Defined in controllers/User.ts:163

updateAvatar

updateAvatar(avatarId: string, formData: FormData): Promise<void | ResponseType>

Update avatar and sprite sheet records and upload files to existing sprite sheet and avatar storage buckets

Parameters

avatarId: string
formData: FormData

Returns Promise<void | ResponseType>

Keywords

update, modify, change, edit, avatar, character

Example

const animationMeta = {
  "emote": { "loop": false, "x": 0, "y": 0, "hideLoop": true }
}

const spriteSheetJSON = {
  "animations": {
    "emote": [
      "emote/1.png"
    ]
  },
  "frames": {
    "emote/1.png": {
      "frame": {
       "x": 1911,
       "y": 778,
       "w": 58,
       "h": 91
     },
     "rotated": true,
     "trimmed": true,
     "spriteSourceSize": {
       "x": 50,
       "y": 33,
       "w": 58,
       "h": 91
     },
     "sourceSize": {
       "w": 159,
       "h": 159
     }
   }
 },
 "spriteSheetTypeMeta": {
   "nameplate": {
     "x": 0,
     "y": -70
   }
 },
 "meta": {
   "image": "spriteSheets%2FTvHNjgoMkiErDNSrVqHU%2FspriteSheet.png?alt=media",
   "format": "RGBA8888",
   "size": {
     "w": 2006,
     "h": 1099
   },
   "scale": "1"
 }
}

const formData = new FormData();
formData.append('animationMeta', animationMeta);
formData.append('name', "ExampleAvatarName");
formData.append('spriteSheetJSON', spriteSheetJSON);
formData.append('expression_dance', expression_dance);
formData.append('expression_emote', expression_emote);
formData.append('expression_sit', expression_sit);
formData.append('expression_stand', expression_stand);
formData.append('expression_transport', expression_transport);
formData.append('preview', preview);
formData.append('spriteSheet', spriteSheet);
formData.append('unityPackage', unityPackage);
await user.uploadAvatarFiles("exampleAvatarId", formData);

Data Objects

fetchDataObject

fetchDataObject(
appPublicKey?: string,
appJWT?: string,
): Promise<void | ResponseType>
Retrieves the data object for a user.
Parameters
- OptionalappPublicKey: string
- OptionalappJWT: string
Returns Promise<void | ResponseType>
Returns the data object or an error response.
Keywords
get, fetch, retrieve, load, data, object, state
Example
```
const dataObject = await user.fetchDataObject();
```
Implementation of UserInterface.fetchDataObject
- Defined in controllers/User.ts:626

incrementDataObjectValue

incrementDataObjectValue(
 path: string,
 amount: number,
 options?: {
 analytics?: AnalyticType[];
 appJWT?: string;
 appPublicKey?: string;
 lock?: { lockId: string; releaseLock?: boolean };
 sharedAppJWT?: string;
 sharedAppPublicKey?: string;
 },
): Promise<void | ResponseType>
Increments a specific value in the data object for a user by the amount specified. Must have valid interactive credentials from a visitor in the world.
Parameters
- path: string
- amount: number
- options: {
 analytics?: AnalyticType[];
 appJWT?: string;
 appPublicKey?: string;
 lock?: { lockId: string; releaseLock?: boolean };
 sharedAppJWT?: string;
 sharedAppPublicKey?: string;
 } = {}
Returns Promise<void | ResponseType>
Keywords
increment, increase, add, count, data, object, state

Remarks
Optionally, a lock can be provided with this request to ensure only one update happens at a time between all updates that share the same lock id
Example
```
await user.incrementDataObjectValue("key", 1);
```
Implementation of UserInterface.incrementDataObjectValue
- Defined in controllers/User.ts:753

setDataObject

setDataObject(
 dataObject: undefined | null | object,
 options?: {
 analytics?: AnalyticType[];
 appJWT?: string;
 appPublicKey?: string;
 lock?: { lockId: string; releaseLock?: boolean };
 sharedAppJWT?: string;
 sharedAppPublicKey?: string;
 },
): Promise<void | ResponseType>
Sets the data object for a user.
Parameters
- dataObject: undefined | null | object
- options: {
 analytics?: AnalyticType[];
 appJWT?: string;
 appPublicKey?: string;
 lock?: { lockId: string; releaseLock?: boolean };
 sharedAppJWT?: string;
 sharedAppPublicKey?: string;
 } = {}
Returns Promise<void | ResponseType>
Keywords
set, assign, store, save, data, object, state

Remarks
Optionally, a lock can be provided with this request to ensure only one update happens at a time between all updates that share the same lock id
Example
```
await user.setDataObject(
 { itemsCollected: 0 },
 {
 analytics: [{ analyticName: "resets"} ],
 lock: { lockId: `${assetId}-${itemsCollected}-${new Date(Math.round(new Date().getTime() / 10000) * 10000)}` },
 },
);

const { itemsCollected } = user.dataObject;
```
Implementation of UserInterface.setDataObject
- Defined in controllers/User.ts:666

updateDataObject

updateDataObject(
 dataObject: object,
 options?: {
 analytics?: AnalyticType[];
 appJWT?: string;
 appPublicKey?: string;
 lock?: { lockId: string; releaseLock?: boolean };
 sharedAppJWT?: string;
 sharedAppPublicKey?: string;
 },
): Promise<void | ResponseType>
Updates the data object for a user.
Parameters
- dataObject: object
- options: {
 analytics?: AnalyticType[];
 appJWT?: string;
 appPublicKey?: string;
 lock?: { lockId: string; releaseLock?: boolean };
 sharedAppJWT?: string;
 sharedAppPublicKey?: string;
 } = {}
Returns Promise<void | ResponseType>
Keywords
update, modify, change, edit, alter, data, object, state

Remarks
Optionally, a lock can be provided with this request to ensure only one update happens at a time between all updates that share the same lock id
Example
```
const theme = "exampleTheme";

await user.updateDataObject({
 [`${theme}.itemsCollectedByUser`]: { [dateKey]: { count: 1 }, total: 1 },
});

const { exampleTheme } = user.dataObject;
```
Implementation of UserInterface.updateDataObject
- Defined in controllers/User.ts:713

Dropped Assets

fetchInteractiveWorldsByKey

fetchInteractiveWorldsByKey(
interactivePublicKey: string,
): Promise<object | ResponseType>
Retrieves ids of all dropped assets in all worlds with a matching interactivePublicKey.
Parameters
- interactivePublicKey: string
Returns Promise<object | ResponseType>
Returns the urlSlugs of worlds where the Public Key is found or an error response.
Keywords
get, fetch, retrieve, list, interactive worlds, public key
Example
```
await user.fetchInteractiveWorldsByKey("interactivePublicKeyExample");
const interactiveWorlds = user.interactiveWorlds;
```
- Defined in controllers/User.ts:533

Expressions

getExpressions

getExpressions(
__namedParameters: { getUnlockablesOnly?: boolean; name?: string },
): Promise<ResponseType>
Get expressions
Parameters
- __namedParameters: { getUnlockablesOnly?: boolean; name?: string }
Returns Promise<ResponseType>
Returns an array of expressions or an error response.
Keywords
get, fetch, retrieve, list, expressions, emotes
Example
```
await user.getExpressions({ getUnlockablesOnly: true, });
```
Implementation of UserInterface.getExpressions
- Defined in controllers/User.ts:594

Other

constructor

new User(topia: Topia, options?: UserOptionalInterface): User
Parameters
- topia: Topia
- options: UserOptionalInterface = ...
Returns User
Overrides SDKController.constructor
- Defined in controllers/User.ts:95

credentials

credentials: undefined | InteractiveCredentials

`Optional`dataObject

dataObject?: null | object

`Optional`jwt

jwt?: string

`Optional`profile

profile?: Record<string, any>

`Optional`profileId

profileId?: null | string

requestOptions

requestOptions: object

topia

topia: Topia

adminWorlds

get adminWorlds(): { [key: string]: World }
Returns { [key: string]: World }
- Defined in controllers/User.ts:109

assets

get assets(): { [key: string]: Asset }
Returns { [key: string]: Asset }
- Defined in controllers/User.ts:113

inventoryItems

get inventoryItems(): UserInventoryItem[]
Returns UserInventoryItem[]
Implementation of UserInterface.inventoryItems
- Defined in controllers/User.ts:812

scenes

get scenes(): { [key: string]: Scene }
Returns { [key: string]: Scene }
- Defined in controllers/User.ts:117

worlds

get worlds(): { [key: string]: World }
Returns { [key: string]: World }
- Defined in controllers/User.ts:121

checkInteractiveCredentials

checkInteractiveCredentials(): Promise<void | ResponseType>
Returns Promise<void | ResponseType>
Implementation of UserInterface.checkInteractiveCredentials
- Defined in controllers/User.ts:137

errorHandler

errorHandler(
    __namedParameters: {
        error?: unknown;
        message?: string;
        params?: object;
        sdkMethod?: string;
    },
): {
    data: {};
    message: string;
    method: string;
    params: object;
    sdkMethod: undefined
    | string;
    stack: string;
    stackTrace: Error;
    status: number;
    success: boolean;
    url: string;
}
Standardized error handler for all SDK operations.
Parameters
- __namedParameters: { error?: unknown; message?: string; params?: object; sdkMethod?: string }
Returns {
    data: {};
    message: string;
    method: string;
    params: object;
    sdkMethod: undefined | string;
    stack: string;
    stackTrace: Error;
    status: number;
    success: boolean;
    url: string;
}
Standardized error object with properties: data, message, method, params, sdkMethod, stack, status, success, url
Remarks
This method processes errors from API calls and formats them consistently across the SDK. It extracts relevant error information including:
- HTTP status codes and response data
- Error messages from API responses
- Stack traces for debugging
- Request details (URL, method, parameters)
All errors thrown by SDK methods flow through this handler to ensure consistent error format.
Keywords
error, exception, handler, debugging, api error, http error
Inherited from SDKController.errorHandler
- Defined in controllers/SDKController.ts:159

fetchInventoryItems

fetchInventoryItems(): Promise<void>
Retrieves all inventory items owned by this user and app's key.

Returns Promise<void>
Returns an array of InventoryItem objects.
Keywords
get, fetch, retrieve, list, inventory, items, user
Example
```
const items = await user.fetchInventoryItems();
```
Implementation of UserInterface.fetchInventoryItems
- Defined in controllers/User.ts:788

grantInventoryItem

grantInventoryItem(
item: InventoryItemInterface,
quantity?: number,
): Promise<UserInventoryItem>
Grants an inventory item to this user.
Parameters
- item: InventoryItemInterface
 The InventoryItem to modify.
- quantity: number = 1
 The new quantity to set.
Returns Promise<UserInventoryItem>
Returns the UserInventoryItem granted.
Example
```
const items = await user.grantInventoryItem("item-id-123", 2);
```
Implementation of UserInterface.grantInventoryItem
- Defined in controllers/User.ts:829

modifyInventoryItemQuantity

modifyInventoryItemQuantity(
item: UserInventoryItemInterface,
quantity: number,
): Promise<UserInventoryItem>
Modifies the quantity of an inventory item in this user's inventory.
Parameters
- item: UserInventoryItemInterface
 The UserInventoryItem to modify.
- quantity: number
 The new quantity to set.
Returns Promise<UserInventoryItem>
Returns the updated inventory item or a response object.
Example
```
await user.modifyInventoryItemQuantity("item-id-123", 5);
```
Implementation of UserInterface.modifyInventoryItemQuantity
- Defined in controllers/User.ts:862

sendEmail

sendEmail(
__namedParameters: { html: string; subject: string; to: string },
): Promise<object | ResponseType>
Send an email
Parameters
- __namedParameters: { html: string; subject: string; to: string }
Returns Promise<object | ResponseType>
Returns { success: true } if the email is sent successfully or an error response.
Keywords
send, email, message, notify
Example
```
const html = `Hello World!This email is being sent from via SDK.`
await user.sendEmail({ html, subject: "Example", to: "example@email.io" });
```
Implementation of UserInterface.sendEmail
- Defined in controllers/User.ts:558

topiaPublicApi

topiaPublicApi(): AxiosInstance
Returns the configured Axios instance for making API calls to Topia's Public API.

Returns AxiosInstance
The configured Axios client instance with authentication headers.

Remarks
All HTTP requests to the Topia API should use this method to ensure proper authentication headers and base URL configuration are applied.

Keywords
api, axios, http, request, client, public api
Inherited from SDKController.topiaPublicApi
- Defined in controllers/SDKController.ts:133

Scenes

fetchScenes

fetchScenes(): Promise<void | ResponseType>
Returns all scenes owned by User.

Returns Promise<void | ResponseType>
Keywords
get, fetch, retrieve, list, user scenes
Example
```
await user.fetchScenes();
const userScenes = user.scenes;
```
Implementation of UserInterface.fetchScenes
- Defined in controllers/User.ts:437

Worlds

fetchAdminWorldsByKey

fetchAdminWorldsByKey(): Promise<void | ResponseType>
Retrieves all worlds a user with matching API Key is an admin in, creates a new World object for each, and creates new map of Worlds accessible via user.adminWorlds.

Returns Promise<void | ResponseType>
Keywords
get, fetch, retrieve, list, admin worlds, user worlds
Example
```
await user.fetchAdminWorldsByKey();
const adminWorlds = user.adminWorlds;
```
- Defined in controllers/User.ts:502

fetchWorldsByKey

fetchWorldsByKey(): Promise<void | ResponseType>
Retrieves all worlds owned by user with matching API Key, creates a new World object for each, and creates new map of Worlds accessible via user.worlds.

Returns Promise<void | ResponseType>
```
{ urlSlug: new World({ apiKey, worldArgs, urlSlug }) }
```
Keywords
get, fetch, retrieve, list, user worlds
Example
```
await user.fetchWorldsByKey();
const userWorlds = user.worlds;
```
Implementation of UserInterface.fetchWorldsByKey
- Defined in controllers/User.ts:472

Class User

Example

Hierarchy (View Summary)

Implements

Index

Assets

Avatars

Data Objects

Dropped Assets

Expressions

Other

Scenes

Worlds

Assets

fetchAssets

Returns Promise<void | ResponseType>

Keywords

Example

fetchPlatformAssets

Returns Promise<object | ResponseType>

Keywords

Example

Avatars

addAvatar

Parameters

Returns Promise<void | ResponseType>

Keywords

Example

deleteAvatar

Parameters

Returns Promise<void | ResponseType>

Keywords

Example

fetchAvatars

Returns Promise<void | ResponseType>

Keywords

Example

updateAvatar

Parameters

Returns Promise<void | ResponseType>

Keywords

Example

Data Objects

fetchDataObject

Parameters

Returns Promise<void | ResponseType>

Keywords

Example

incrementDataObjectValue

Parameters

Returns Promise<void | ResponseType>

Keywords

Remarks

Example

setDataObject

Parameters

Returns Promise<void | ResponseType>

Keywords

Remarks

Example

updateDataObject

Parameters

Returns Promise<void | ResponseType>

Keywords

Remarks

Example

Dropped Assets

fetchInteractiveWorldsByKey

Parameters

Returns Promise<object | ResponseType>

Keywords

Example

Expressions

getExpressions

Parameters

Returns Promise<ResponseType>

Keywords

Example

Other

constructor

`Optional`dataObject

`Optional`jwt

`Optional`profile

`Optional`profileId

Returns {
data: {};
message: string;
method: string;
params: object;
sdkMethod: undefined | string;
stack: string;
stackTrace: Error;
status: number;
success: boolean;
url: string;
}