Asset Functions

To create functionality that manages assets, leverage the Asset adapter.

Importing the adapter

To use the functions of the Asset adapter, import it as shown:

import { assetAdapter } from 'epicenter-libs';

The assetAdapter namespace exports functions that make calls to the Asset API.

learn more

For descriptions of the objects used by the asset adapter functions, read Asset entities.

---

Create

Create an upload URL

The create() function returns a presigned URL for uploading a file to S3.

Permissions

Requires a role of PARTICIPANT or higher.

Function description

• Sends a POST request to the /asset endpoint.
• Creates an asset ticket containing a presigned upload URL.
• Takes an AssetScope object that implements user-specific scope.
• Optionally, sets an expiration time limit.

Note

If you omit the permit, the readLock and writeLock values default to USER.

Function signature

export async function create(
    file: string,
    scope: AssetScope,
    optionals: {
        readLock?: keyof typeof ROLE;
        writeLock?: keyof typeof ROLE;
        ttlSeconds?: number;
        tokenAccessSeconds?: number;
    } & RoutingOptions = {},
): Promise<AssetTicket>

Parameters

• file (string): File path or name for the asset being uploaded.
• scope (AssetScope): User-specific scope associated with the asset.
  • scopeBoundary (SCOPE_BOUNDARY): Scope boundary that defines the type of scope.
  • scopeKey (string): Unique identifier tied to the scope. For example, if scopeBoundary is GROUP, the scopeKey should be the corresponding groupKey.
  • userKey? (string): Optional user key to further scope the asset to a specific user.
• optionals (Type: { readLock?: keyof typeof ROLE; writeLock?: keyof typeof ROLE; ttlSeconds?: number; tokenAccessSeconds?: number } & RoutingOptions):
  • readLock? (ROLE): Role allowed to read the asset. Defaults to USER.
  • writeLock? (ROLE): Role allowed to write the asset. Defaults to USER.
  • ttlSeconds? (number): Time to live in seconds for the stored asset.
  • tokenAccessSeconds? (number): Number of seconds the presigned URL remains valid.
  • RoutingOptions: Additional routing options.

Return value

A promise that resolves to an object of type AssetTicket. This ticket contains the presigned upload URL and metadata required to upload the file.

Usage example

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

const ticket = await assetAdapter.create('myfile.pdf', {
    scopeBoundary: SCOPE_BOUNDARY.GROUP,
    scopeKey: '0000017dd3bf540e5ada5b1e058f08e56783',
});

---

Upload an asset to storage

The store() function stores a file directly to S3. It obtains a presigned URL from the Epicenter server and uploads the file to S3.

Important

If the asset already exists and overwrite is true, it updates the existing asset.

Permissions

Requires a role of PARTICIPANT or higher.

Function description

• Takes an AssetScope object that implements user-specific scope.
• Obtains a presigned URL by calling the create() function.
• Optionally, creates a permit for the asset and sets an expiration time limit.
• If the asset already exists and overwrite is true, obtains a presigned URL by calling the update() function.
• Uploads the file to S3 using the presigned URL with a PUT request.

Function signature

export async function store(
    file: File,
    scope: AssetScope,
    optionals: {
        readLock?: keyof typeof ROLE;
        writeLock?: keyof typeof ROLE;
        ttlSeconds?: number;
        overwrite?: boolean;
        fileName?: string;
        tokenAccessSeconds?: number;
    } & RoutingOptions = {},
): Promise<void>

Parameters

• file (File): File object to store.
• scope (AssetScope): User-specific scope for the asset.
  • scopeBoundary (SCOPE_BOUNDARY): Scope boundary that defines the type of scope.
  • scopeKey (string): Unique identifier tied to the scope. For example, if scopeBoundary is GROUP, the scopeKey should be the corresponding groupKey.
  • userKey? (string): Optional user key to further scope the asset to a specific user.
• optionals (Type: { readLock?: keyof typeof ROLE; writeLock?: keyof typeof ROLE; ttlSeconds?: number; overwrite?: boolean; fileName?: string; tokenAccessSeconds?: number } & RoutingOptions):
  • readLock? (ROLE): Role allowed to read the asset. Defaults to USER.
  • writeLock? (ROLE): Role allowed to write the asset. Defaults to USER.
  • ttlSeconds? (number): Time to live in seconds for the stored asset.
  • overwrite? (boolean): If true, updates the asset if it already exists. If false, throws an error if the asset exists.
  • fileName? (string): Optional file name to use instead of the file’s name property.
  • tokenAccessSeconds? (number): Number of seconds the presigned URL remains valid.
  • RoutingOptions: Additional routing options.

Return value

A promise that resolves to void when the file has been uploaded to S3.

Usage example

import { assetAdapter, SCOPE_BOUNDARY, ROLE } from 'epicenter-libs';

const file = new File(['content'], 'myfile.pdf');

await assetAdapter.store(
    file,
    {
        scopeBoundary: SCOPE_BOUNDARY.GROUP,
        scopeKey: '0000017dd3bf540e5ada5b1e058f08e56783',
    },
    {
        overwrite: true,
        readLock: ROLE.USER,
    }
);

---

Update

Update an asset upload URL

The update() function updates an existing asset and returns a presigned URL for uploading the new file to S3.

Permissions

Requires a role of PARTICIPANT or higher.

Function description

• Sends a PATCH request to the /asset endpoint.
• Updates an existing asset and creates an asset ticket containing a presigned upload URL.
• Takes an AssetScope object that implements user-specific scope.
• Optionally, creates a permit for the asset and sets an expiration time limit.

Function signature

export async function update(
    file: string,
    scope: AssetScope,
    optionals: {
        readLock?: keyof typeof ROLE;
        writeLock?: keyof typeof ROLE;
        ttlSeconds?: number;
        tokenAccessSeconds?: number;
    } & RoutingOptions = {},
): Promise<AssetTicket>

Parameters

• file (string): File path or name for the asset being uploaded.
• scope (AssetScope): User-specific scope associated with the asset.
  • scopeBoundary (SCOPE_BOUNDARY): Scope boundary that defines the type of scope.
  • scopeKey (string): Unique identifier tied to the scope. For example, if scopeBoundary is GROUP, the scopeKey should be the corresponding groupKey.
  • userKey? (string): Optional user key to further scope the asset to a specific user.
• optionals (Type: { readLock?: keyof typeof ROLE; writeLock?: keyof typeof ROLE; ttlSeconds?: number; tokenAccessSeconds?: number } & RoutingOptions):
  • readLock? (ROLE): Role allowed to read the asset. Defaults to USER.
  • writeLock? (ROLE): Role allowed to write the asset. Defaults to USER.
  • ttlSeconds? (number): Time to live in seconds for the stored asset.
  • tokenAccessSeconds? (number): Number of seconds the presigned URL remains valid.
  • RoutingOptions: Additional routing options.

Return value

A promise that resolves to an object of type AssetTicket. This ticket contains the presigned upload URL and metadata required to upload the file.

Usage example

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

const ticket = await assetAdapter.update('myfile.pdf', {
    scopeBoundary: SCOPE_BOUNDARY.GROUP,
    scopeKey: '0000017dd3bf540e5ada5b1e058f08e56783',
});

---

Delete

Delete an asset

The remove() function deletes an existing asset by its asset key.

Permissions

Requires a role of PARTICIPANT or higher.

Function description

• Sends a DELETE request to the /asset/{ASSET_KEY} endpoint.
• Deletes the specified asset from storage.
• Returns no response body when the deletion is successful.

Function signature

export async function remove(
    assetKey: string,
    optionals: RoutingOptions = {},
): Promise<void>

Parameters

• assetKey (string): The unique identifier of the asset to delete.
• optionals (RoutingOptions): Optional network and routing overrides.

Return value

A promise that resolves to void when the asset has been successfully deleted.

Usage example

import { assetAdapter } from 'epicenter-libs';

await assetAdapter.remove('0000017dd3bf540e5ada5b1e058f08e56783');

---

Delete assets from a scope

The removeFromScope() function deletes all assets within a given scope.

Permissions

Requires a role of PARTICIPANT or higher.

Function description

• Sends a DELETE request to the /asset/in/{SCOPE_BOUNDARY}/{SCOPE_KEY} endpoint.
• Deletes all assets associated with the specified scope boundary and scope key.
• Optionally, deletes only assets scoped to a specific user when a userKey is provided.
• Returns no response body when the deletion is successful.

Function signature

export async function removeFromScope(
    scope: AssetScope,
    optionals: RoutingOptions = {},
): Promise<void>

Parameters

• scope (AssetScope): User-specific scope associated with the assets to delete.
  • scopeBoundary (SCOPE_BOUNDARY): Scope boundary that defines the type of scope.
  • scopeKey (string): Unique identifier tied to the scope. For example, if scopeBoundary is GROUP, the scopeKey should be the corresponding groupKey.
  • userKey? (string): Optional user key to further scope the deletion to a specific user.
• optionals (RoutingOptions): Optional network and routing overrides.

Return value

A promise that resolves to void when all assets in the scope have been successfully deleted.

Usage example

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

await assetAdapter.removeFromScope({
    scopeBoundary: SCOPE_BOUNDARY.GROUP,
    scopeKey: '0000017dd3bf540e5ada5b1e058f08e56783',
});

---

Retrieve

Get asset metadata

The get() function retrieves the metadata for an existing asset by asset key.

Permissions

Requires a role of PARTICIPANT or higher.

Function description

• Sends a GET request to the /asset/{ASSET_KEY} endpoint.
• Returns metadata for the specified asset, including its file name, address, and scope.
• Takes optional routing overrides for server, account, and project context.

Function signature

export async function get(
    assetKey: string,
    optionals: RoutingOptions = {},
): Promise<Asset>

Parameters

• assetKey (string): The unique identifier of the asset to retrieve.
• optionals (RoutingOptions): Optional network and routing overrides.

Return value

A promise that resolves to an object of type Asset. This object contains the asset metadata.

Usage example

import { assetAdapter } from 'epicenter-libs';

const asset = await assetAdapter.get('0000017dd3bf540e5ada5b1e058f08e56783');

---

List assets by scope

The list() function retrieves metadata for assets within a given scope, optionally filtered by file pattern.

Permissions

Requires a role of PARTICIPANT or higher.

Function description

• Returns a list of assets associated with the specified scope boundary and scope key.
• Optionally, lists only assets scoped to a specific user when a userKey is provided.
• Supports filtering assets by file pattern (for example, *.pdf).

Function signature

export async function list(
    scope: AssetScope,
    optionals: {
        filter?: string;
    } & RoutingOptions = {},
): Promise<Asset[]>

Parameters

• scope (AssetScope):
  • scopeBoundary (SCOPE_BOUNDARY): Scope boundary that defines the type of scope.
  • scopeKey (string): Unique identifier tied to the scope. For example, if scopeBoundary is GROUP, the scopeKey should be the corresponding groupKey.
  • userKey? (string): Optional user key for user-specific scope.
• optionals (Type: { filter?: string } & RoutingOptions):
  • filter? (string): File pattern to filter assets (for example, *.pdf). Defaults to * (all files).
  • RoutingOptions: Additional routing options.

Return value

A promise that resolves to an array of Asset objects. Each object contains metadata for an asset in the scope.

Usage example

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

// List all assets in the scope
const assets = await assetAdapter.list({
    scopeBoundary: SCOPE_BOUNDARY.GROUP,
    scopeKey: '0000017dd3bf540e5ada5b1e058f08e56783',
});

// List only PDF files
const pdfs = await assetAdapter.list(
    {
        scopeBoundary: SCOPE_BOUNDARY.GROUP,
        scopeKey: '0000017dd3bf540e5ada5b1e058f08e56783',
    },
    { filter: '*.pdf' }
);

---

Get an asset URL

The getURL() function generates a presigned URL for accessing an existing asset.

Permissions

Requires a role of PARTICIPANT or higher.

Function description

• Sends a GET request to the /asset/url/{ASSET_KEY} endpoint.
• Returns a presigned URL that can be used to access the asset.
• Optionally, limits how long the URL remains valid using the tokenAccessSeconds parameter.

Function signature

export async function getURL(
    assetKey: string,
    optionals: {
        tokenAccessSeconds?: number;
    } & RoutingOptions = {},
): Promise<string>

Parameters

• assetKey (string): The unique identifier of the asset.
• optionals (Type: { tokenAccessSeconds?: number } & RoutingOptions):
  • tokenAccessSeconds? (number): Number of seconds the presigned URL remains valid.
  • RoutingOptions: Additional routing options.

Return value

A promise that resolves to a presigned URL string that can be used to access the asset.

Usage example

import { assetAdapter } from 'epicenter-libs';

const url = await assetAdapter.getURL('0000017dd3bf540e5ada5b1e058f08e56783');

---

Get an asset URL by scope and file name

The getURLWithScope() function generates a presigned URL for accessing an asset with specified scope and file name.

Permissions

Requires a role of PARTICIPANT or higher.

Function description

• Sends a GET request to one of the following endpoints:
  • /asset/url/with/{SCOPE_BOUNDARY}/{SCOPE_KEY}/{FILE} for regular scope.
  • /asset/url/with/{SCOPE_BOUNDARY}/{SCOPE_KEY}/{USER_KEY}/{FILE} for user-specific scope.
• Optionally, limits how long the URL remains valid using the tokenAccessSeconds parameter.
• Returns a presigned URL.

Function signature

export async function getURLWithScope(
    file: string,
    scope: AssetScope,
    optionals: {
        tokenAccessSeconds?: number;
    } & RoutingOptions = {},
): Promise<string>

Parameters

• file (string): File path or name for the asset.
• scope (AssetScope):
  • scopeBoundary (SCOPE_BOUNDARY): Scope boundary that defines the type of scope.
  • scopeKey (string): Unique identifier tied to the scope. For example, if scopeBoundary is GROUP, the scopeKey should be the corresponding groupKey.
  • userKey? (string): Optional user key for user-specific scope.
• optionals (Type: { tokenAccessSeconds?: number } & RoutingOptions):
  • tokenAccessSeconds? (number): Number of seconds the presigned URL remains valid.
  • RoutingOptions: Additional routing options.

Return value

A promise that resolves to a presigned URL string that can be used to access the asset.

Usage example

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

const url = await assetAdapter.getURLWithScope('myfile.pdf', {
    scopeBoundary: SCOPE_BOUNDARY.GROUP,
    scopeKey: '0000017dd3bf540e5ada5b1e058f08e56783',
});

---

Download an asset

The download() function downloads an existing asset by its asset key.

Permissions

Requires a role of ANONYMOUS or higher.

Function description

• Sends a GET request to the /asset/download/{ASSET_KEY} endpoint.
• Downloads the specified asset from storage.
• Optionally, limits how long the download URL remains valid using the tokenAccessSeconds parameter.
• Resolves when the download request is complete.

Function signature

export async function download(
    assetKey: string,
    optionals: {
        tokenAccessSeconds?: number;
    } & RoutingOptions = {},
): Promise<void>

Parameters

• assetKey (string): The unique identifier of the asset to download.

• optionals (Type: { tokenAccessSeconds?: number } & RoutingOptions):

  • tokenAccessSeconds? (number): Number of seconds the presigned download URL remains valid.
  • RoutingOptions: Additional routing options.

Return value

A promise that resolves to void when the asset download request has completed.

Usage example

import { assetAdapter } from 'epicenter-libs';

await assetAdapter.download('0000017dd3bf540e5ada5b1e058f08e56783');

---

Download an asset by scope and file name

The downloadWithScope() function downloads an existing asset by scope and file name.

Permissions

Requires a role of ANONYMOUS or higher.

Function description

• Sends a GET request to the /asset/download/with/{SCOPE_BOUNDARY}/{SCOPE_KEY}/{FILE} endpoint.
• Downloads the specified asset within the given scope.
• Optionally, includes a userKey to further scope the asset lookup to a specific user.
• Optionally, limits how long the download URL remains valid using the tokenAccessSeconds parameter.
• Resolves when the download request is complete.

Function signature

export async function downloadWithScope(
    file: string,
    scope: AssetScope,
    optionals: {
        tokenAccessSeconds?: number;
    } & RoutingOptions = {},
): Promise<void>

Parameters

• file (string): File path or name for the asset being downloaded.
• scope (AssetScope): User-specific scope associated with the asset.
  • scopeBoundary (SCOPE_BOUNDARY): Scope boundary that defines the type of scope.
  • scopeKey (string): Unique identifier tied to the scope. For example, if scopeBoundary is GROUP, the scopeKey should be the corresponding groupKey.
  • userKey? (string): Optional user key to further scope the asset to a specific user.
• optionals (Type: { tokenAccessSeconds?: number } & RoutingOptions):
  • tokenAccessSeconds? (number): Number of seconds the presigned download URL remains valid.
  • RoutingOptions: Additional routing options.

Return value

A promise that resolves when the asset download request has completed.

Usage example

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

await assetAdapter.downloadWithScope('myfile.pdf', {
    scopeBoundary: SCOPE_BOUNDARY.GROUP,
    scopeKey: '0000017dd3bf540e5ada5b1e058f08e56783',
});

---