Vault Functions

To manage vaults, use the functions exported by the Vault adapter.

Importing the adapter

To use the functions of the Vault adapter, import it as shown:
import { vaultAdapter } from 'epicenter-libs';

The vaultAdapter namespace exports functions that make calls to the Vault API.

learn more

For descriptions of the objects used by the Vault adapter functions, read Vault Entities.

Create

Define vault

The define() function creates or updates a vault with the specified name and scope. Vault names must be unique within the scope.

Vault permit

If you don't provide a permit, the following value is used as the default for both readLock and writeLock:

PARTICIPANT if the vault is scoped to a world.
USER otherwise.

Mutation strategy

The optionals.mutationStrategy parameter determines how an existing vault is affected by an update:

ALLOW - An upsert. If the vault exists, it is updated with the values you pass to the function.
DISALLOW - An insert. If the vault exists, no changes are made. The changed flag is set to false.
ERROR - If the vault exists, no changes are made, and a conflict exception is thrown.

If optionals.mutationStrategy is omitted, it defaults to ERROR.

Permissions

Requires a role of PARTICIPANT or higher.

Function description

Constructs a POST request to the /vault/{name} endpoint.
Creates a new vault or updates an existing one, depending on the mutationStrategy.
Returns a promise that resolves to a Vault object representing the created or updated vault.

Function signature
export async function define<I extends object = VaultItems>(
    name: string,
    scope: { userKey?: string } & GenericScope,
    optionals: {
        items?: Items<I>;
        readLock?: keyof typeof ROLE;
        writeLock?: keyof typeof ROLE;
        ttlSeconds?: number;
        mutationStrategy?: string;
        allowChannel?: boolean;
    } & RoutingOptions = {},
): Promise<Vault<I>>

Parameters

Important

The vault name must be unique within the vault's scope.

name (string): Name of the vault to be created or updated.
scope ({ userKey?: string } & GenericScope): Defines the vault's scope. See the GenericScope interface.
- scope.scopeBoundary (string): Defines the type of scope boundary. Pass a value of the SCOPE_BOUNDARY enum.
- scope.scopeKey (string): Unique identifier for the scope.
- scope.userKey? (string, optional): Optional user key for a user-specific scope.
optionals (Type: { ... } & RoutingOptions = {}):
- items? (Items): Data items for updating vault contents. To learn how to use this parameter, read about the Items interface.
 - set: Key-value pairs setting and deleting items.
 - push: Key-value pairs to append to arrays within an item.
 - pop: Indicate which elements to remove from arrays.
- readLock? (keyof typeof ROLE): Role allowed to view the vault.
- writeLock? (keyof typeof ROLE): Role allowed to update to the vault.
- ttlSeconds? (number): Vault lifespan in seconds. Can be null. The minimum lifespan you can set is 1800 seconds (30 minutes).
- mutationStrategy? (string): Determines behavior if vault already exists. For details, see Mutation strategy.
- allowChannel? (boolean): If true, send out push notifications for this vault. Applicable in projects with phylogeny >= SILENT.
- RoutingOptions: Additional routing options. Pass network call options overrides here.

Return value

A promise that resolves to a Vault object representing the created or updated vault.

Usage example

import { vaultAdapter, SCOPE_BOUNDARY } from 'epicenter-libs';

await vaultAdapter.define('my-vault-name', {
  scopeBoundary: SCOPE_BOUNDARY.GROUP,
  scopeKey: '0000017dd3bf540e5ada5b1e058f08f86432'
});

Retrieve

Get vault

Retrieves a specific vault by its key.

Permissions

Requires a role of PARTICIPANT or higher.

Function description

The get() function:

Constructs a GET request to the /vault/{VAULT_KEY} endpoint.
Returns the corresponding Vault object.
If the vault does not exist, resolves to undefined.

Function signature
export async function get<I extends object = VaultItems>(
    vaultKey: string,
    optionals: RoutingOptions = {},
): Promise<Vault<I>>

Parameters

vaultKey (string): The unique key identifying the vault to retrieve.
optionals (Type: RoutingOptions = {}): Optional routing options to override default behavior.

Return value

A promise that resolves to the retrieved Vault object, or undefined if the vault is not found.

Usage example

import { vaultAdapter } from 'epicenter-libs';

const vault = await vaultAdapter.get('00000166d59adcb0f497ddc1aad0270s7u45');

if (!vault) {
  console.log('Vault not found');
}

Get vault with scope

Retrieves a specific vault using its name and scope.

Permissions

Requires a role of PARTICIPANT or higher.

Function description

The withScope() function:

Constructs a GET request to the /vault/with/{SCOPE_BOUNDARY}/{SCOPE_KEY}/{USER_KEY?}/{VAULT_NAME} endpoint.
Supports optional user‑scoped vault lookup when userKey is provided.
Returns the matching Vault object.
If the vault does not exist, resolves to undefined instead of throwing a 404.

Function signature
export async function withScope<I extends object = VaultItems>(
    name: string,
    scope: { userKey?: string } & GenericScope,
    optionals: RoutingOptions = {},
): Promise<Vault<I>>

Parameters

name (string): The name of the vault to retrieve.
scope (Type: { userKey?: string } & GenericScope): The scope of the vault.
- scopeBoundary (string): Pass a value of the SCOPE_BOUNDARY enum.
- scopeKey (string): A unique identifier of the scope.
- userKey (string, optional): Optional user key for a user-specific scope.
optionals (Type: RoutingOptions = {}): Additional routing options. Pass network overrides here.

Return value

A promise that resolves to the retrieved Vault object, or undefined if the vault is not found.

Usage example

import { vaultAdapter } from 'epicenter-libs';

const vault = await vaultAdapter.withScope('my-vault', {
  scopeBoundary: 'GROUP',
  scopeKey: '0000017a445032dc38cb2cecd5fc56361946',
  userKey: '0000018d61f1217b22ce0ae605ff00329w5y'
});

Get vaults by name

Retrieves one or more vaults that match the specified name.

Permissions

Requires a role of PARTICIPANT or higher.

Function description

The byName() function:

Constructs a GET request to the /vault/in/{GROUP_NAME}/{EPISODE_NAME?}/{VAULT_NAME} endpoint.
Searches for vaults by name within a group, optionally narrowed to an episode.
Supports filtering by userKey and including episode‑scoped vaults.
Returns an array of matching Vault object.

Function signature
export async function byName<I extends object = VaultItems>(
    name: string,
    optionals: {
        groupName?: string;
        episodeName?: string;
        userKey?: string;
        includeEpisodes?: boolean;
    } & RoutingOptions = {},
): Promise<Vault<I>[]>

Parameters

name (string): The name of the vault to look up.
optionals (Type: { groupName?: string, episodeName?: string, userKey?: string, includeEpisodes?: boolean } & RoutingOptions = {}): Additional filtering and routing options.
- groupName (string, optional): The group name to search within. Defaults to the current session's group name.
- episodeName (string, optional): The episode name to further scope the search.
- userKey (string, optional): User key.
- includeEpisodes (boolean, optional): If true, includes vaults from related episodes in the result.
- RoutingOptions: Additional routing options. Pass network call options overrides here.

Return value

A promise that resolves to an array of Vault object that match the specified name and scope.

Usage example

import { vaultAdapter } from 'epicenter-libs';

// Retrieve vaults by name within a specific group and episode
const vaults = await vaultAdapter.byName('progress-tracker', {
  groupName: 'group-123',
  episodeName: 'episode-abc',
  userKey: '0000018d61f1217b22ce0ae605ff00329w5y',
  includeEpisodes: true
});

Search for vaults

The list() function retrieves a list of vaults matching the specified search filters.

learn more

For reference on search filters, read Filter and sort syntax.

Note

This method is NOT paginated.

Permissions

Requires a role of PARTICIPANT or higher.

Function description

Constructs a GET request to the /vault/search endpoint.
Supports filtering, sorting, and limiting results through GenericSearchOptions.
Optionally restricts the search to a specific group.
Returns an array of matching Vault object.

Function signature
export async function list<I extends object = VaultItems>(
    searchOptions: GenericSearchOptions,
    optionals: { groupName?: string } & RoutingOptions = {},
): Promise<Vault<I>[]>

Parameters

searchOptions (Type: GenericSearchOptions): Search parameters, including filter and sort.
optionals (Type: { groupName?: string } & RoutingOptions = {}): An optional parameter containing:
- groupName (string): A group name to list vaults scoped to a group.
- RoutingOptions: Additional routing options. Pass network overrides here.

Return value

A promise that resolves to an array of Vault objects matching the search criteria.

Usage example

import { vaultAdapter } from 'epicenter-libs';

const results = await vaultAdapter.list({// Pass a GenericSearchOptions object containing
  filter: ['name=my-vault', 'scopeBoundary=GROUP'], // two filter strings and
  first: 0,                                         // pagination parameters
  max: 20
});

Get count

Counts the number of vaults that match the specified search criteria.

learn more

For reference on search criteria, read Filter and sort syntax.

Permissions

Requires a role of PARTICIPANT or higher.

Function description

The count() function:

Constructs a GET request to the /vault/count endpoint.
Supports filtering and limiting results through GenericSearchOptions.
Optionally restricts the count to a specific group.
Returns the number of vaults that match the criteria.

Function signature
export async function count(
    searchOptions: GenericSearchOptions,
    optionals: { groupName?: string } & RoutingOptions = {},
): Promise<number>

Parameters

searchOptions (GenericSearchOptions): Criteria used to filter the vaults.
optionals (Type: { groupName?: string } & RoutingOptions = {}): Group name and additional routing options.

Return value

A promise that resolves to the number of vaults matching the search criteria.

Usage example

import { vaultAdapter } from 'epicenter-libs';

// Count how many vaults match a specific filter
const vaultCount = await vaultAdapter.count({ // Pass a GenericSearchOptions object containing
  filter: ['type:progress'],                  // a filter string and
  first: 0,                                   // pagination parameters
  max: 100
});

Update

Update contents

Updates the contents of a vault with new values.

tip

The update() function modifies the data stored in a vault. To modify the vault (i.e., the container), there are two options:

The define() function updates both the properties and the data.
The updateProperties() function updates only the properties of the vault.

Mutation key

To avoid conflicts from simultaneous data updates, use the mutationKey parameter. For details, read Updating the data.

Permissions

Requires a role of PARTICIPANT or higher.

Function description

The update() function:

Constructs a PUT request to the /vault/{VAULT_KEY} endpoint.
Applies item mutations using the Items structure:
- set — overwrite or delete fields
- push — append to array fields
- pop — remove from array fields
Supports optimistic concurrency control via an optional mutationKey.
Returns the updated Vault object.

Function signature
export async function update<I extends object = VaultItems>(
    vaultKey: string,
    items: Items<I>,
    optionals: {
        mutationKey?: string;
    } & RoutingOptions = {},
): Promise<Vault<I>>

Parameters

vaultKey (string): The unique key identifying the vault to be updated.
items (Items): An object specifying the updates to be made. To learn how to use this parameter, read about the Items interface.
- set: Key-value pairs setting and deleting items.
- push: Key-value pairs to append to arrays within an item.
- pop: Indicate which elements to remove from arrays.
optionals (Type: { mutationKey?: string } & RoutingOptions = {}): Additional options.
- mutationKey (string, optional): Use this parameter to ensure you are updating the latest copy of the vault's data. For details, read Updating the data.
- RoutingOptions: Additional routing options. Pass network call options overrides here.

Return value

A promise that resolves to the updated Vault object.

Usage example

import { vaultAdapter } from 'epicenter-libs';

// Change the name of the first student in the vault to "Bob"
await vaultAdapter.update(
  '00000166d59adcb0f497ddc1aad0270f6e89',
  { set: { 'students.0.name': 'Bob' } }
);

Update properties

Updates the properties of a vault.

tip

To update the vault's contents, use the update() function.

Permissions

Requires a role of PARTICIPANT or higher.

Function description

The updateProperties() function:

Constructs a PATCH request to the /vault/{VAULT_KEY} endpoint.
Accepts an update object with optional fields like allowChannel, permit, ttlSeconds, and mutationKey.
Returns the updated Vault object.

Function signature
export async function updateProperties<I extends object = VaultItems>(
    vaultKey: string,
    update: {
        mutationKey?: string;
        allowChannel?: boolean;
        permit?: Permit;
        ttlSeconds?: number;
    },
    optionals: RoutingOptions = {},
): Promise<Vault<I>>

Parameters

vaultKey (string): The unique key identifying the vault to be updated.
update (object): An object specifying the vault properties to update.
- mutationKey? (string, optional): Ensures you're updating the latest version of the vault. See Updating the data.
- allowChannel? (boolean, optional): If true, allow push notifications for the vault. Applicable in projects with phylogeny >= SILENT.
- permit? (Permit, optional): Defines read/write access roles.
  - readLock: Role required to read the vault.
  - writeLock: Role required to modify the vault.
- ttlSeconds? (number, optional): Vault lifespan in seconds. The minimum lifespan you can set is 1800 seconds (30 minutes).
optionals (RoutingOptions = {}, optional): Additional network call options.

Return value

A promise that resolves to the updated Vault object.

Usage example

import { vaultAdapter, ROLE } from 'epicenter-libs';

// Update the vault's lifespan to 1 hour and restrict access to facilitators
await vaultAdapter.updateProperties(
  '00000166d59adcb0f497ddc1aad0270c0a62',
  {
    allowChannel: true,
    permit: {
      readLock: ROLE.FACILITATOR,
      writeLock: ROLE.FACILITATOR,
    },
    ttlSeconds: 3600,
  }
);

Delete

Remove vault

Deletes a specific vault by its unique key.

Permissions

Requires a role of PARTICIPANT or higher.

Function description

The remove() function:

Constructs a DELETE request to the /vault/{VAULT_KEY} endpoint.
Supports optimistic concurrency control via an optional mutationKey.
Returns undefined when the deletion is successful.

Function signature
export async function remove(
    vaultKey: string,
    optionals: { mutationKey?: string } & RoutingOptions = {},
): Promise<void>

Parameters

vaultKey (string): The unique key identifying the vault to be deleted.
optionals (Type: { mutationKey?: string } & RoutingOptions = {}): Additional options.
- mutationKey (string, optional): Mutation identifier to track the deletion.
- RoutingOptions: Additional routing options. Pass network call options overrides here.

Return value

A Promise<void> that resolves once the vault has been deleted.

Usage example

import { vaultAdapter } from 'epicenter-libs';

// Delete a vault by its key
await vaultAdapter.remove(
  '00000166d59adcb0f497ddc1aad0270f6e89'
);

Importing the adapter​

Create​

Define vault​

Vault permit​

Mutation strategy​

Permissions​

Function description​

Parameters​

Return value​

Usage example​

Retrieve​

Get vault​

Permissions​

Function description​

Parameters​

Return value​

Usage example​

Get vault with scope​

Permissions​

Function description​

Parameters​

Return value​

Usage example​

Get vaults by name​

Permissions​

Function description​

Parameters​

Return value​

Usage example​

Search for vaults​

Permissions​

Function description​

Parameters​

Return value​

Usage example​

Get count​

Permissions​

Function description​

Parameters​

Return value​

Usage example​

Update​

Update contents​

Mutation key​

Permissions​

Function description​

Parameters​

Return value​

Usage example​

Update properties​

Permissions​

Function description​

Parameters​

Return value​

Usage example​

Delete​

Remove vault​

Permissions​

Function description​

Parameters​

Return value​

Usage example​

Importing the adapter

Create

Define vault

Vault permit

Mutation strategy

Permissions

Function description

Parameters

Return value

Usage example

Retrieve

Get vault

Permissions

Function description

Parameters

Return value

Usage example

Get vault with scope

Permissions

Function description

Parameters

Return value

Usage example

Get vaults by name

Permissions

Function description

Parameters

Return value

Usage example

Search for vaults

Permissions

Function description

Parameters

Return value

Usage example

Get count

Permissions

Function description

Parameters

Return value

Usage example

Update

Update contents

Mutation key

Permissions

Function description

Parameters

Return value

Usage example

Update properties

Permissions

Function description

Parameters

Return value

Usage example

Delete

Remove vault

Permissions

Function description

Parameters

Return value

Usage example