Skip to main content

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​

Creates or updates a vault with the specified name and 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, the default behavior is ALLOW.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The define() function:

  • Constructs a POST request to the endpoint /vault/{name}.
  • Defines a new vault or updates an existing one using the provided scope and optional configuration.
  • Vault names are unique within their scope.
  • Returns a Vault object representing the created or updated vault.
Function signature
export async function define(
    name: string,
    scope: { userKey?: string } & GenericScope,
    optionals: {
        items?: Items,
        readLock?: keyof typeof ROLE,
        writeLock?: keyof typeof ROLE,
        ttlSeconds?: number,
        mutationStrategy?: string,
        allowChannel?: boolean,
    } & RoutingOptions = {}
): Promise<Vault<unknown>>

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 newly created or updated vault.

Usage example​

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

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

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 endpoint /vault/{vaultKey}.
  • Attempts to retrieve the vault identified by the vaultKey.
  • If vault is not found, returns undefined.
  • Returns a Vault object if the vault exists.
Function signature
export async function get(
    vaultKey: string,
    optionals: RoutingOptions = {}
): Promise<Vault<unknown>>

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 a Vault object if found, or undefined if 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 and sends a GET request to the endpoint /vault/with/{scopeBoundary}/{scopeKey}/{userKey}/{name}.
  • Returns a Vault object, or undefined if the vault is not found.
Function signature
export async function withScope(
    name: string,
    scope: { userKey?: string } & GenericScope,
    optionals: RoutingOptions = {}
): Promise<Vault<unknown>>

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 a Vault object containing the vault data or undefined if 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 endpoint /vault/in/{groupName}/{episodeName}/{name}.
  • Accepts a vault name and optional parameters such as group name, episode name, user key, and whether to include vaults from related episodes.
  • Returns a list of Vault objects matching the criteria.
Function signature
export async function byName(
    name: string,
    optionals: {
        groupName?: string,
        episodeName?: string,
        userKey?: string,
        includeEpisodes?: boolean,
    } & RoutingOptions = {}
): Promise<Vault<unknown>[]>

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 objects 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​

Retrieves a list of vaults matching the specified search filters.

learn more

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

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The list() function:

  • Constructs a GET request to the /vault/search endpoint.
  • Accepts filtering and pagination options defined by the GenericSearchOptions interface.
  • Accepts an optional parameter optionals which can contain:
    • A group name to list vaults scoped to a group.
    • Additional routing options to override network call defaults.
  • Returns a list of Vault objects that match the criteria.
Function signature
export async function list(
    searchOptions: GenericSearchOptions,
    optionals: { groupName?: string } & RoutingOptions = {}
): Promise<Vault<unknown>[]>

Parameters​

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.
  • Accepts a GenericSearchOptions object to filter the results.
  • Accepts an optional parameter optionals which can contain:
    • A group name to count vaults scoped to a group.
    • Additional routing options to override network call defaults.
  • Returns the number of Vault objects` that match the provided criteria.
Function signature
export async function count(
    searchOptions: GenericSearchOptions,
    optionals: { groupName?: string } & RoutingOptions = {}
): Promise<Vault<unknown>[]>

Parameters​

Return value​

A promise that resolves to the number of Vault objects` matching the search filters.

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 endpoint /vault/{vaultKey}.
  • Accepts an items object with optional set, push, and pop operations as defined by the Items interface.
  • Optionally includes a mutationKey and other routing options.
  • Returns an updated Vault object.
Function signature
export async function update(
    vaultKey: string,
    items: Items,
    optionals: { mutationKey?: string } & RoutingOptions = {}
): Promise<Vault<unknown>>

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 an 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 endpoint /vault/{vaultKey}.
  • Accepts an update object with optional fields like allowChannel, permit, ttlSeconds, and mutationKey.
  • Optionally includes routing options.
  • Returns an updated Vault object.
Function signature
export async function updateProperties(
    vaultKey: string,
    update: {
        mutationKey?: string,
        allowChannel?: boolean,
        permit?: Permit,
        ttlSeconds?: number,
    },
    optionals: RoutingOptions = {}
): Promise<Vault<unknown>>

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 an 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 endpoint /vault/{vaultKey}.
  • Optionally includes a mutationKey and other routing options.
  • Returns a Promise<void> indicating the operation has completed.
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'
);