epicenter-libs 3.11.0

package/src/adapters/asset.ts

@@ -0,0 +1,195 @@
+import type { RoutingOptions } from '../utils/router';
+import type { GenericScope } from '../utils/constants';
+
+import fetch from 'cross-fetch';
+import { Fault, Router, ROLE } from '../utils';
+
+interface AssetScope extends GenericScope {
+    userKey?: string,
+}
+
+interface Asset {
+    file: string,
+    address: {
+        projectShortName: string,
+        groupName: string,
+        accountShortName: string,
+        worldKey: string,
+        episodeName: string,
+    },
+    scope: AssetScope,
+}
+
+interface AssetTicket {
+    url: string,
+}
+
+
+export async function create(
+    file: string,
+    scope: AssetScope,
+    optionals: {
+        readLock?: keyof typeof ROLE,
+        writeLock?: keyof typeof ROLE,
+        ttlSeconds?: number,
+    } & RoutingOptions = {}
+): Promise<AssetTicket> {
+    const { scopeBoundary, scopeKey, userKey } = scope;
+    const {
+        readLock, writeLock, ttlSeconds,
+        ...routingOptions
+    } = optionals;
+    return await new Router()
+        .post('/asset', {
+            body: {
+                file,
+                scope: {
+                    scopeBoundary,
+                    scopeKey,
+                    userKey,
+                },
+                permit: {
+                    readLock: readLock ?? ROLE.USER,
+                    writeLock: writeLock ?? ROLE.USER,
+                },
+                ttlSeconds,
+            },
+            ...routingOptions,
+        }).then(({ body }) => body);
+}
+
+export async function update(
+    file: string,
+    scope: AssetScope,
+    optionals: {
+        readLock?: keyof typeof ROLE,
+        writeLock?: keyof typeof ROLE,
+        ttlSeconds?: number,
+    } & RoutingOptions = {}
+): Promise<AssetTicket> {
+    const { scopeBoundary, scopeKey, userKey } = scope;
+    const {
+        readLock, writeLock, ttlSeconds,
+        ...routingOptions
+    } = optionals;
+    return await new Router()
+        .patch('/asset', {
+            body: {
+                file,
+                scope: {
+                    scopeBoundary,
+                    scopeKey,
+                    userKey,
+                },
+                permit: {
+                    readLock: readLock ?? ROLE.USER,
+                    writeLock: writeLock ?? ROLE.USER,
+                },
+                ttlSeconds,
+            },
+            ...routingOptions,
+        }).then(({ body }) => body);
+}
+
+export async function remove(
+    assetKey: string,
+    optionals: RoutingOptions = {}
+): Promise<void> {
+    return await new Router()
+        .delete(`/asset/${assetKey}`, optionals)
+        .then(({ body }) => body);
+}
+
+export async function removeFromScope(
+    scope: AssetScope,
+    optionals: RoutingOptions = {}
+): Promise<void> {
+    const { scopeBoundary, scopeKey, userKey } = scope;
+    const uriComponent = userKey ? `/${userKey}` : '';
+    return await new Router()
+        .delete(`/asset/in/${scopeBoundary}/${scopeKey}${uriComponent}`, optionals)
+        .then(({ body }) => body);
+}
+
+export async function get(
+    assetKey: string,
+    optionals: RoutingOptions = {}
+): Promise<Asset> {
+    const { server, accountShortName, projectShortName } = optionals;
+    return await new Router()
+        .withServer(server)
+        .withAccountShortName(accountShortName)
+        .withProjectShortName(projectShortName)
+        .get(`/asset/${assetKey}`)
+        .then(({ body }) => body);
+}
+
+export async function list(
+    scope: AssetScope,
+    optionals: {
+        filter?: string,
+    } & RoutingOptions = {}
+): Promise<Asset[]> {
+    const { scopeBoundary, scopeKey, userKey } = scope;
+    const {
+        filter,
+        ...routingOptions
+    } = optionals;
+    const uriComponent = userKey ? `/${userKey}` : '';
+    return await new Router()
+        .get(`/asset/in/${scopeBoundary}/${scopeKey}${uriComponent}/${filter ?? '*'}`, routingOptions)
+        .then(({ body }) => body);
+}
+
+export async function getURL(
+    assetKey: string,
+    optionals: RoutingOptions = {}
+): Promise<string> {
+    return await new Router()
+        .get(`/asset/url/${assetKey}`, optionals)
+        .then(({ body }) => body);
+}
+
+export async function getURLWithScope(
+    file: string,
+    scope: AssetScope,
+    optionals: RoutingOptions = {}
+): Promise<string> {
+    const { scopeBoundary, scopeKey, userKey } = scope;
+    const uriComponent = userKey ? `/${userKey}` : '';
+    return await new Router()
+        .get(`/asset/url/with/${scopeBoundary}/${scopeKey}${uriComponent}/${file}`, optionals)
+        .then(({ body }) => body);
+}
+
+const CONFLICT = 409;
+export async function store(
+    file: File,
+    scope: AssetScope,
+    optionals: {
+        readLock?: keyof typeof ROLE,
+        writeLock?: keyof typeof ROLE,
+        ttlSeconds?: number,
+        overwrite?: boolean,
+        fileName?: string,
+    } & RoutingOptions = {}
+): Promise<void> {
+    const { overwrite, fileName, ...remaining } = optionals;
+    const name = fileName ?? file.name;
+    let presignedUrl = '';
+    try {
+        const response = await create(name, scope, remaining);
+        presignedUrl = response.url;
+    } catch (error) {
+        if (error instanceof Fault) {
+            const shouldUpdate = error.status === CONFLICT && overwrite;
+            if (!shouldUpdate) throw error;
+            const response = await update(name, scope, remaining);
+            presignedUrl = response.url;
+        } else {
+            throw error;
+        }
+    }
+    await fetch(presignedUrl, { method: 'PUT', body: file });
+    return;
+}

package/src/adapters/authentication.ts

@@ -0,0 +1,173 @@
+import type { RoutingOptions } from '../utils/router';
+import type { Session } from '../utils/identification';
+
+import { Router, identification } from '../utils';
+import cometdAdapter from './cometd';
+
+
+interface UserCredentials {
+    handle: string,
+    password: string,
+    groupKey?: string,
+}
+interface AppCredentials {
+    secretKey: string,
+}
+
+/**
+ * Run API adapters -- use this to create, update, delete, and manage your runs
+ * @namespace authAdapter
+ */
+
+/**
+ * Logs out of current Epicenter session.
+ * @example
+ * epicenter.authAdapter.logout()
+ * @returns promise resolving to successful logout
+ */
+export async function logout(): Promise<void> {
+    identification.session = undefined;
+    await cometdAdapter.disconnect();
+}
+
+export async function login(
+    credentials: UserCredentials | AppCredentials,
+    optionals: { objectType?: string } & RoutingOptions = {}
+): Promise<Session> {
+    const { objectType, ...routingOptions } = optionals;
+    let payload;
+    if (Object.prototype.hasOwnProperty.call(credentials, 'handle')) {
+        const { handle, password, groupKey } = credentials as UserCredentials;
+        payload = { objectType: objectType ?? 'user', handle, password, groupKey: groupKey || undefined };
+    }
+    if (Object.prototype.hasOwnProperty.call(credentials, 'secretKey')) {
+        const { secretKey } = credentials as AppCredentials;
+        payload = { objectType: objectType ?? 'account', secretKey };
+    }
+    const session = await new Router()
+        .post('/authentication', {
+            inert: true,
+            includeAuthorization: false,
+            body: payload,
+            ...routingOptions,
+        }).then(({ body }) => body);
+    await logout();
+    identification.session = session;
+    return session;
+}
+
+/**
+ * Regenerates your epicenter session with the appropriate context. Allows users to update their session to the correct group, and admins to update their session with the correct account name. Will fail if the user/admin does not already belong to the group/account.
+ * @example
+ * // Changes the current user session to have a group context associated with the provided key
+ * epicenter.authAdapter.regenerate('00000165ad4e6a3cd22b993340b963820239');
+ * // Changes the current admin session to use the account context for the 'acme' account.
+ * epicenter.authAdapter.regenerate('acme', { objectType: 'admin' });
+ * @param groupOrAccount            Group key or account name
+ * @param [optionals]               Optional parameters
+ * @param [optionals.objectType]    The object type to regenerate for. Uses objectType: 'user' by default.
+ * @returns promise resolving to the new session object
+ */
+export async function regenerate(
+    groupOrAccount: string,
+    optionals: {
+        objectType?: string,
+    } & RoutingOptions = {}
+): Promise<Session> {
+    const {
+        objectType = 'user',
+        accountShortName,
+        ...routingOptions
+    } = optionals;
+
+    const session = await new Router()
+        .patch('/authentication', {
+            accountShortName: objectType === 'admin' ?
+                groupOrAccount :
+                accountShortName,
+            body: {
+                objectType,
+                groupKey: objectType === 'user' ?
+                    groupOrAccount :
+                    undefined,
+            },
+            ...routingOptions,
+        }).then(({ body }) => body);
+
+    await logout();
+    identification.session = session;
+    return session;
+}
+
+export async function sso(
+    optionals: RoutingOptions = {},
+): Promise<Session> {
+    const session = await new Router()
+        .get('/registration/sso', optionals)
+        .then(({ body }) => body);
+
+    identification.session = session;
+    return session;
+}
+
+export async function getSession(): Promise<Session> {
+    const { body } = await new Router().get('/authentication');
+    identification.session = body;
+    return body;
+}
+
+export function getLocalSession(): Session | undefined {
+    return identification.session;
+}
+
+export function setLocalSession(session: Session): Session {
+    return identification.session = session;
+}
+
+/**
+ * Sends a link to reset a user's password to their email
+ * @example
+ * const subject = 'Please reset your password for the Acme simulation';
+ * const url = 'https://forio.com/app/acme/simulations';
+ * const handle = 'testUser@test.com'
+ * epicenter.authAdapter.resetPassword(handle, { redirectURL, subject });
+ * @param  handle                   Handle that user would use to login
+ * @param  [optionals]              Optional arguments; pass network call options overrides here. Special arguments specific to this method are listed below if they exist.
+ * @param  [optionals.redirectURL]  Url to redirect to after password reset is completed. Must be in the forio domain otherwise an error will be thrown
+ * @param  [optionals.subject]      The subject of the email that will be sent
+ * @returns promise that resolves to undefined (indicating success)
+ */
+export async function resetPassword(
+    handle: string,
+    optionals: {
+        redirectURL?: string,
+        subject?: string,
+    } & RoutingOptions = {}
+): Promise<void> {
+    const {
+        redirectURL, subject,
+        ...routingOptions
+    } = optionals;
+
+    return await new Router()
+        .post(`/authentication/password/user/${handle}`, {
+            ...routingOptions,
+            body: {
+                redirectUrl: redirectURL,
+                subject,
+            },
+        })
+        .then(({ body }) => body);
+}
+
+export async function verify(
+    token: string,
+    optionals: RoutingOptions = {},
+): Promise<Session> {
+    return await new Router()
+        .get('/verification', {
+            authorization: `Bearer ${token}`,
+            ...optionals,
+        })
+        .then(({ body }) => body);
+}

package/src/adapters/channel.ts

@@ -0,0 +1,83 @@
+import type { Callback, SubscriptionHandle, Message } from 'cometd';
+import type { GenericScope } from '../utils/constants';
+
+import { EpicenterError, SCOPE_BOUNDARY, PUSH_CATEGORY } from '../utils';
+import cometdAdapter from './cometd';
+
+interface ChannelScope extends GenericScope {
+    pushCategory: string,
+}
+
+const validateScope = (scope: ChannelScope) => {
+    if (!scope) throw new EpicenterError('No scope found where one was required');
+    const { scopeBoundary, scopeKey, pushCategory } = scope;
+    if (!scopeBoundary) throw new EpicenterError('Missing scope component: scopeBoundary');
+    if (!scopeKey) throw new EpicenterError('Missing scope component: scopeKey');
+    if (!pushCategory) throw new EpicenterError('Missing scope component: pushCategory');
+    if (!Object.prototype.hasOwnProperty.call(SCOPE_BOUNDARY, scopeBoundary)) throw new EpicenterError(`Invalid scope boundary: ${scopeBoundary}`);
+    if (!Object.prototype.hasOwnProperty.call(PUSH_CATEGORY, pushCategory)) throw new EpicenterError(`Invalid push category: ${pushCategory}`);
+};
+
+/**
+ * Used to subscribe to CometD channels. Pass in a channel scope to instantiate, if a subscription to that scope already exists it will use it.
+ * */
+export default class Channel {
+
+    path: string;
+    update: Callback | undefined;
+    subscription: SubscriptionHandle | null = null;
+
+    /**
+     * Channel constructor
+     * @param scope object with the scope boundary, scope key, and push category. Defines the namespace for the channel
+     */
+    constructor(scope: ChannelScope) {
+        const { scopeBoundary, scopeKey, pushCategory } = scope;
+        validateScope(scope);
+        this.path = `/${scopeBoundary.toLowerCase()}/${scopeKey}/${pushCategory.toLowerCase()}`;
+        if (cometdAdapter.subscriptions.has(this.path)) {
+            this.subscription = cometdAdapter.subscriptions.get(this.path);
+        }
+    }
+
+    publish(content: FIXME): Promise<Message | Message[]> {
+        return cometdAdapter.publish(this, content);
+    }
+
+    /**
+     * Subscribes to the CometD channel, attaching a handler for any channel updates. If a subscription already exists it will first unsubscribe, ensuring that only one subscription is ever attached to the channel.
+     * @example
+     * import { Channel, authAdapter, SCOPE_BOUNDARY, PUSH_CATEGORY } from 'epicenter';
+     * const session = authAdapter.getLocalSession();
+     * const channel = new Channel({
+     *     scopeBoundary: SCOPE_BOUNDARY.GROUP,
+     *     scopeKey: session.groupKey,
+     *     pushCategory: PUSH_CATEGORY.CHAT,
+     * }).subscribe((data) => {
+     *      console.log(data.content);
+     * })
+     * @param update function that is called whenever a channel update occurs.
+     * @returns the subscription object returned by CometD after a sucessful subscribe.
+     */
+    async subscribe(
+        update: (data: unknown) => unknown,
+        options: { inert?: boolean } = {},
+    ): Promise<SubscriptionHandle> {
+        if (this.subscription) await this.unsubscribe();
+        this.update = update;
+        return cometdAdapter.add(this, update, options).then((subscription) => {
+            if (Array.isArray(subscription)) subscription = subscription[0];
+            this.subscription = subscription;
+            return subscription;
+        });
+    }
+
+    async unsubscribe(): Promise<void> {
+        if (this.subscription) {
+            await cometdAdapter.remove(this.subscription);
+            this.subscription = null;
+        }
+    }
+}
+
+

package/src/adapters/chat.ts

@@ -0,0 +1,186 @@
+import type { GenericScope, Permit } from 'utils/constants';
+import type { RoutingOptions, Page, GenericSearchOptions } from 'utils/router';
+import Router from 'utils/router';
+
+interface ChatMessage {
+    senderKey: string,
+    receiverKey: string,
+    created: string,
+    id: string,
+    message: string,
+}
+
+interface Chat {
+    permit: Permit,
+    chatKey: string,
+    messages: ChatMessage[],
+    room: string,
+    scope: GenericScope,
+}
+
+/**
+ * Updates the permissions of a chat
+ * @param chatKey       Key associated with the chat
+ * @param permit        Permit object with the updated permissions
+ * @param [optionals]   Optional arguments; pass network call options overrides here. Special arguments specific to this method are listed below if they exist.
+ * @returns the newly updated chat
+ */
+export async function updatePermit(
+    chatKey: string,
+    permit: Permit,
+    optionals: RoutingOptions = {}
+): Promise<Chat> {
+    return new Router()
+        .patch(`/chat/${chatKey}`, {
+            ...optionals,
+            body: { permit },
+        }).then(({ body }) => body);
+}
+
+/**
+ * Creates a chat
+ * @example
+ * import { chatAdapter, SCOPE_BOUNDARY, ROLE } from 'epicenter';
+ * chatAdapter.create(
+ *      'my-chat-room',
+ *      { scopeBoundary: SCOPE_BOUNDARY.GROUP, scopeKey: '00000165ad4e6a3cd22b993340b963820239' },
+ *      { readLock: ROLE.PARTICIPANT, writeLock: ROLE.PARTICIPANT }
+ * );
+ * @param room          Name of the chat
+ * @param scope         Scope of the chat; will not accept user scope
+ * @param permit        Permissions for the chat
+ * @param [optionals]   Optional arguments; pass network call options overrides here. Special arguments specific to this method are listed below if they exist.
+ * @returns The chat created
+ */
+export async function create(
+    room: string,
+    scope: GenericScope,
+    permit: Permit,
+    optionals: RoutingOptions = {}
+): Promise<Chat> {
+    return new Router()
+        .post('/chat', {
+            body: {
+                scope: {
+                    scopeBoundary: scope.scopeBoundary,
+                    scopeKey: scope.scopeKey,
+                },
+                permit,
+                room,
+            },
+            ...optionals,
+        }).then(({ body }) => body);
+}
+
+
+/**
+ * Gets a chat
+ * @example
+ * epicenter.chatAdapter.get('00000165ad4e6a3cd22b993340b963820239');
+ * @param chatKey       Key of the associated chat
+ * @param [optionals]   Optional arguments; pass network call options overrides here. Special arguments specific to this method are listed below if they exist.
+ * @returns The chat corresponding with the provided key
+ */
+export async function get(
+    chatKey: string,
+    optionals: RoutingOptions = {}
+): Promise<Chat> {
+    return new Router()
+        .get(`/chat/${chatKey}`, optionals)
+        .then(({ body }) => body);
+}
+
+
+/**
+ * Open search for chats, returns a page
+ * @example
+ * epicenter.chatAdapter.query({
+ *      filter: [
+ *          'room|=my-chat-room|my-other-chat|room-three',      // looks for any rooms with the names provided
+ *          'scopeBoundary=GROUP',                              // keeps the search within the group scope
+ *          // 'scopeKey=00000165ad4e6a3cd22b993340b963820239', // used in conjunction with the scopeBoundary
+ *          // 'chatKey=0000017dd3bf540e5ada5b1e058f08f20461',  // searches for a specific chat
+ *          // 'accountShortName=acme',                         // specifies the account, typically unnecessary
+ *          // 'projectShortName=simulations',                  // specifies the project, typically unnecessary
+ *          // 'groupName=my-group-name',                       // search based on group name
+ *          // 'episodeName=my-episode-name',                   // search based on episode name
+ *          'created>=2022-01-03T20:30:53.054Z',                // looks for any chats created after Jan 3rd 2022
+ *      ],
+ *      sort: ['+chat.created'],    // sort all findings by the 'created' field (ascending)
+ *      first: 3,                   // page should start with the 4th item found (defaults to 0)
+ *      max: 10,                    // page should only include the first 10 items
+ * });
+ * @param searchOptions Search options -- for more on Epicenter search options go [here](NOOP link)
+ * @param [optionals]   Optional arguments; pass network call options overrides here. Special arguments specific to this method are listed below if they exist.
+ * @returns A page for the list of chats found
+ */
+export async function query(
+    searchOptions: GenericSearchOptions,
+    optionals: RoutingOptions = {}
+): Promise<Page<Chat>> {
+    const { filter = [], sort = [], first = 0, max } = searchOptions;
+    const searchParams = {
+        filter: filter.join(';') || undefined,
+        sort: sort.join(';') || undefined,
+        first, max,
+    };
+    return await new Router()
+        .withSearchParams(searchParams)
+        .get('/chat', {
+            paginated: true,
+            ...optionals,
+        })
+        .then(({ body }) => body);
+}
+
+/**
+ * Sends a message to a chat
+ * @example
+ * epicenter.chatAdapter.sendMessage('0000017dd3bf540e5ada5b1e058f08f20461', 'hello');
+ * epicenter.chatAdapter.sendMessage('0000017dd3bf540e5ada5b1e058f08f20461', 'hello, privately', { userKey: '000001796733eef0842f4d6d960997018a33' });
+ * @param chatKey               Key associated with the chat
+ * @param message               Message text to send
+ * @param [optionals]           Optional arguments; pass network call options overrides here. Special arguments specific to this method are listed below if they exist.
+ * @param [optionals.userKey]   Key of the user to send the message to. If omitted, will send as a public message
+ * @returns The chat message created
+ */
+export async function sendMessage(
+    chatKey: string,
+    message: string,
+    optionals: { userKey?: string } & RoutingOptions = {}
+): Promise<ChatMessage> {
+    const { userKey, ...routingOptions } = optionals;
+    const uriComponent = userKey ? `/${userKey}` : '';
+    return new Router()
+        .put(`/chat/message/${chatKey}${uriComponent}`, {
+            body: { message },
+            ...routingOptions,
+        }).then(({ body }) => body);
+}
+
+/**
+ * Retrieves messages from for a given chat
+ * @example
+ * // gets the chat message with id: 5
+ * epicenter.chatAdapter.getMessages('0000017dd3bf540e5ada5b1e058f08f20461', { horizon: 5, maxRecords: 1 });
+ * // gets the 10 chat messages starting from id 5 (inclusive)
+ * epicenter.chatAdapter.getMessages('0000017dd3bf540e5ada5b1e058f08f20461', { horizon: 5, maxRecords: 10 });
+ * @param chatKey                   Key associated with the chat
+ * @param [optionals]               Optional arguments; pass network call options overrides here. Special arguments specific to this method are listed below if they exist.
+ * @param [optionals.maxRecords]    Maximum number of messages to get
+ * @param [optionals.horizon]       The message ID from which to start with; works backwards so if `maxRecords=20` and `horizon=50`, it will get the 20 messages starting from message ID 50, working backwards (50, 49, 48..., etc.). If this value is omitted the platform assumes it is the most recent message in the chat
+ * @returns The list chat messages requested
+ */
+export async function getMessages(
+    chatKey: string,
+    optionals: {
+        maxRecords?: number,
+        horizon?: number,
+    } & RoutingOptions = {}
+): Promise<ChatMessage[]> {
+    const { maxRecords, horizon, ...routingOptions } = optionals;
+    return new Router()
+        .withSearchParams({ maxRecords, horizon })
+        .get(`/chat/message/${chatKey}`, routingOptions)
+        .then(({ body }) => body);
+}