epicenter-libs 3.11.0

package/src/adapters/cometd.ts

@@ -0,0 +1,297 @@
+import type { CometD, Message, SubscribeMessage, SubscriptionHandle } from 'cometd';
+import type Channel from './channel';
+
+import { EpicenterError, Fault, identification, isBrowser, errorManager, config } from '../utils';
+import { channelsEnabled } from './project';
+
+const AUTH_TOKEN_KEY = 'com.forio.epicenter.token';
+
+const DISCONNECTED = 'disconnected';
+const CONNECTED = 'connected';
+const UNAUTHORIZED = 401;
+
+interface ChannelUpdate {
+    data: string | Record<string, unknown>,
+}
+
+let cometdInstance: CometD | undefined;
+class CometdAdapter {
+
+    url = '';
+    initialization = false;
+    subscriptions = new Map();
+
+    get cometd() {
+        if (!cometdInstance) {
+            throw new EpicenterError('Tried to get non-existent cometd');
+        }
+        return cometdInstance;
+    }
+    set cometd(instance) {
+        cometdInstance = instance;
+    }
+
+    async startup() {
+        const enabled = await channelsEnabled();
+        if (!enabled) throw new EpicenterError('Push Channels are not enabled on this project');
+
+        const { CometD } = await import('cometd');
+        const AckExtension = (await import('cometd/AckExtension')).default;
+        const ReloadExtension = (await import('cometd/ReloadExtension')).default;
+
+        this.cometd = new CometD();
+        const { apiProtocol, apiHost, apiVersion, accountShortName, projectShortName } = config;
+        const accountProject = (accountShortName && projectShortName) ?
+            `/${accountShortName}/${projectShortName}` :
+            '/epicenter/manager';
+        this.url = `${apiProtocol}://${apiHost}/push/v${apiVersion}${accountProject}/cometd`;
+
+        this.cometd.registerExtension('ack', new AckExtension());
+        if (isBrowser()) {
+            this.cometd.registerExtension('reload', new ReloadExtension());
+
+            window.onunload = () => {
+                if (this.cometd.getStatus() === CONNECTED) {
+                    if (this.cometd.reload) this.cometd.reload();
+                    const transport = this.cometd.getTransport();
+                    if (transport) transport.abort();
+                }
+            };
+        }
+
+        // Current don't want to support CometD on node servers
+        // if (isNode()) {
+        //     const { adapt } = await import('cometd-nodejs-client');
+        //     adapt();
+        // }
+
+        this.cometd.configure({
+            url: this.url,
+            logLevel: 'debug',
+        });
+        return true;
+    }
+
+    async init() {
+        if (!this.initialization) {
+            this.initialization = await this.startup();
+        }
+        return this.initialization;
+    }
+
+    // Connects to CometD server
+    async handshake(options: { inert?: boolean } = {}) {
+        await this.init();
+
+        if (this.cometd.getStatus() !== DISCONNECTED) {
+            return Promise.resolve();
+        }
+
+        let handshakeProps = {};
+        const { session } = identification;
+
+        if (session) {
+            handshakeProps = {
+                ext: {
+                    [AUTH_TOKEN_KEY]: session.token,
+                    ack: true,
+                },
+            };
+        }
+
+        // TODO -- this was line in the old libs, don't know why; probably not needed so commenting out for now.
+        // this.cometd.ackEnabled = true;
+        this.cometd.websocketEnabled = true;
+        return new Promise((resolve, reject) => this.cometd.handshake(handshakeProps, (handshakeReply) => {
+            if (handshakeReply.successful) {
+                resolve(handshakeReply);
+                return;
+            }
+
+            const errorMessage = handshakeReply.error ?? '';
+            const error = new Fault({
+                status: errorMessage.includes('403') ? UNAUTHORIZED : undefined,
+                message: errorMessage,
+                information: {
+                    code: 'COMETD_ERROR',
+                    ...handshakeReply,
+                },
+            });
+
+            if (options.inert) {
+                reject(error);
+                return;
+            }
+
+            const retry = () => this.handshake({ inert: true });
+            try {
+                const result = errorManager.handle(error, retry);
+                resolve(result);
+            } catch (e) {
+                reject(e);
+            }
+        }));
+    }
+
+    async disconnect() {
+        if (!this.initialization) return Promise.resolve();
+
+        await this.init();
+        await this.empty();
+        if (this.cometd.getStatus() !== CONNECTED) return Promise.resolve();
+
+        return new Promise((resolve, reject) => this.cometd.disconnect((disconnectReply: Message) => {
+            if (!disconnectReply.successful) {
+                reject(new EpicenterError('Unable to disconnect from CometD server'));
+            } else {
+                resolve(undefined);
+            }
+        }));
+    }
+
+    async add(
+        channel: Channel | Channel[],
+        update: (data: unknown) => unknown,
+        options: { inert?: boolean } = {}
+    ): Promise<SubscriptionHandle | SubscriptionHandle[]> {
+        await this.init();
+        const channels = ([] as Channel[]).concat(channel);
+
+        if (this.cometd?.getStatus() !== CONNECTED) {
+            await this.handshake();
+        }
+        const { session } = identification;
+        const subscriptionProps = !session ? {} :
+            { ext: { [AUTH_TOKEN_KEY]: session.token } };
+
+        const handleCometdUpdate = ({ data }: ChannelUpdate) => {
+            // TODO -- figure out why there's ambiguity here and try to remove it
+            data = typeof data === 'string' ? JSON.parse(data) : data;
+            return update(data);
+        };
+
+        const promises: Promise<SubscriptionHandle>[] = [];
+        this.cometd.batch(() => channels.forEach(({ path }) => promises.push(new Promise((resolve, reject) => {
+            const subscription = this.cometd.subscribe(path, handleCometdUpdate, subscriptionProps, (subscribeReply: SubscribeMessage) => {
+                if (subscribeReply.successful) {
+                    this.subscriptions.set(subscription.channel, subscription);
+                    resolve(subscription);
+                    return;
+                }
+
+                const errorMessage = subscribeReply.error ?? '';
+                const error = new Fault({
+                    status: errorMessage.includes('403') ? UNAUTHORIZED : undefined,
+                    message: errorMessage,
+                    information: {
+                        code: 'COMETD_ERROR',
+                        ...subscribeReply,
+                    },
+                });
+
+                if (options.inert) {
+                    reject(error);
+                    return;
+                }
+
+                const retry = () => this.add(channel, update, { inert: true });
+                try {
+                    const result = errorManager.handle<SubscriptionHandle | SubscriptionHandle[]>(error, retry);
+                    const sub = Array.isArray(result) ? result[0] : result;
+                    resolve(sub);
+                } catch (e) {
+                    reject(e);
+                }
+            });
+        }))));
+        return promises.length === 1 ?
+            Promise.all(promises).then(([res]) => res) :
+            Promise.all(promises);
+    }
+
+    async publish(
+        channel: Channel | Channel[],
+        content: Record<string, unknown>,
+        options: { inert?: boolean } = {}
+    ) {
+        await this.init();
+        const channels = ([] as Channel[]).concat(channel);
+
+        if (this.cometd.getStatus() !== CONNECTED) {
+            await this.handshake();
+        }
+        const { session } = identification;
+        const publishProps = {
+            ext: session ? { [AUTH_TOKEN_KEY]: session.token } : undefined,
+        };
+        const promises: Promise<Message>[] = [];
+        this.cometd.batch(() => channels.forEach(({ path }) => promises.push(new Promise((resolve, reject) => {
+            this.cometd.publish(path, content, publishProps, (publishReply: Message) => {
+                if (publishReply.successful) {
+                    resolve(publishReply);
+                    return;
+                }
+
+                const errorMessage = publishReply.error ?? '';
+                const error = new Fault({
+                    status: errorMessage.includes('403') ? UNAUTHORIZED : undefined,
+                    message: errorMessage,
+                    information: {
+                        code: 'COMETD_ERROR',
+                        ...publishReply,
+                    },
+                });
+
+                if (options.inert) {
+                    reject(error);
+                    return;
+                }
+
+                const retry = () => this.publish(channel, content, { inert: true });
+                try {
+                    const result = errorManager.handle<Message | Message[]>(error, retry);
+                    const message = Array.isArray(result) ? result[0] : result;
+                    resolve(message);
+                } catch (e) {
+                    reject(e);
+                }
+            });
+        }))));
+        return promises.length === 1 ?
+            Promise.all(promises).then(([res]) => res) :
+            Promise.all(promises);
+    }
+
+    async remove(subscription: SubscriptionHandle) {
+        await this.init();
+        this.subscriptions.delete(subscription.channel);
+        return new Promise((resolve, reject) => this.cometd.unsubscribe(subscription, (unsubscribeReply: Message) => {
+            if (unsubscribeReply.successful) {
+                resolve(unsubscribeReply);
+            }
+            const errorMessage = unsubscribeReply.error ?? '';
+            const error = new Fault({
+                status: errorMessage.includes('403') ? UNAUTHORIZED : undefined,
+                message: errorMessage,
+                information: {
+                    code: 'COMETD_ERROR',
+                    ...unsubscribeReply,
+                },
+            });
+            reject(error);
+            /* Not using error handling here yet -- should we? */
+        }));
+    }
+
+    async empty() {
+        await this.init();
+        const promises: Promise<unknown>[] = [];
+        this.cometd.batch(() => this.subscriptions.forEach((subscription) => {
+            promises.push(this.remove(subscription));
+        }));
+        return Promise.all(promises);
+    }
+}
+const cometdAdapter = new CometdAdapter();
+export default cometdAdapter;
+

package/src/adapters/email.ts

@@ -0,0 +1,146 @@
+import type { RoutingOptions } from '../utils/router';
+import { Router } from 'utils/index';
+
+enum ENCODING {
+    HEX = 'HEX',
+    BASE_64 = 'BASE_64',
+}
+
+/**
+ * Sends an email to an individual user; available to participants
+ * @example
+ * //Sends an email with a smiley face png attachment
+ * const groupKey = epicenter.authAdapter.getLocalSession().groupKey;
+ * const subject = "check out this drawing!"
+ * const body = "I hope you enjoy this smiley face!"
+ * const attachements = [{
+ *      encoding: 'BASE_64',
+ *      name: 'testPic',
+ *      contentType: 'image/png',
+ *      data: 'iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAAAXNSR0IArs4c6QAAAIxJREFUWEdjZBhgwDjA9jMQ5YAvzmb/efaewquWGDXYPDvqgNEQGA2B0RAYGiFAy+KaqBAYdcDICgFQtQryMaHql1qhgjURklu3IzuKWDNwOoCSUCAlFHFmQ2J9gB4VpFgO0kvVZhaplhPlAJgPCSVKciwn6ACY5TDD8aV8Qg7EpXe0KB4NgdEQGA0BAF7VgCFTeobfAAAAAElFTkSuQmCC',
+ * }];
+ *
+ * // Sends an email to the address associated with the provided user key, sender will be seen as "System"
+ * epicenter.emailAdapter.sendEmail(groupKey, '000001796733eef0842f4d6d960997018a3b', subject, body, { attachments });
+ * // Sends an email to the address associated with the provided user key, sender will be seen as be the address provided by the "from" field
+ * epicenter.emailAdapter.sendEmail(groupKey, '000001796733eef0842f4d6d960997018a3b', subject, body, { attachments, from: 'sender@test.com' });
+ * // Sends an email to the address defined at "replyTo", sender will be seen as be the address provided by the "from" field
+ * epicenter.emailAdapter.sendEmail(groupKey, '000001796733eef0842f4d6d960997018a3b', subject, body, { attachments, from: 'sender@test.com', replyTo: 'receiver@test.com' });
+ * // Sends an email to the address associated with the provided user key, sender will be seen as the user associated with the "fromUserKey"
+ * epicenter.emailAdapter.sendEmail(groupKey, '000001796733eef0842f4d6d960997018a3b', subject, body, { attachments, fromUserKey: '000001796733eef0842f4d6d960997018a33' });
+ * @param groupKey                              The groupKey in which the email target user exists
+ * @param userKey                               The unique userKey for the email target user
+ * @param subject                               The subject line for the email.
+ * @param emailBody                             The body for the email
+ * @param [optionals]                           Optional parameters
+ * @param [optionals.familyNameFirst]           Specifies whether email target's family name will come before their given name. Defaults to false.
+ * @param [optionals.html]                      Whether to treat the body as HTML (true) or as plain text (false). Defaults to false.
+ * @param [optionals.body]                      The content of the email.
+ * @param [optionals.from]                      The email address from which the message will appear to have been sent from. Will be overriden by fromUserKey.
+ * @param [optionals.replyTo]                   The email address that will be replyed to by the recipient. Must be used in conjunction with optionals.from.
+ * @param [optionals.fromUserKey]               The userKey from which the email will appear to have been sent. The default response address will also be this email.
+ * @param [optionals.attachments]               An array of (binary) objects to include as attachments. All four properties must be included.
+ * @param [optionals.attachments[].encoding]    A string specifying the encoding method. See ENCODING for possible values.
+ * @param [optionals.attachments[].data]        A string containing the data for the attachment.
+ * @param [optionals.attachments[].name]        A string containing the name of the attachment.
+ * @param [optionals.attachments[].contentType] A string specifying the attachment MIME Type.
+ * @returns undefined indicating success
+ */
+export async function sendEmail(
+    groupKey: string,
+    userKey: string,
+    subject: string,
+    emailBody: string,
+    optionals: {
+        familyNameFirst?: string,
+        html?: boolean,
+        body?: string,
+        from?: string,
+        replyTo?: string,
+        fromUserKey?: string,
+        attachments?: {
+            encoding: keyof typeof ENCODING,
+            data: string,
+            name: string,
+            contentType: string,
+        }[]
+    } & RoutingOptions = {}
+): Promise<void> {
+    const { accountShortName, projectShortName, server, familyNameFirst, html, attachments, from, replyTo, fromUserKey } =
+        optionals;
+
+    let fromString = '';
+    if (fromUserKey) {
+        fromString += `/as/${fromUserKey}`;
+    } else if (from) {
+        fromString += `/from/${from}`;
+        if (replyTo) {
+            fromString += `/${replyTo}`;
+        }
+    }
+
+    return await new Router()
+        .withServer(server)
+        .withAccountShortName(accountShortName)
+        .withProjectShortName(projectShortName)
+        .post(`/email/user/${groupKey}/${userKey}${fromString}`, {
+            body: {
+                subject,
+                body: emailBody,
+                familyNameFirst,
+                html,
+                attachments,
+            },
+        })
+        .then(({ body }) => body);
+}
+
+/**
+ * Sends an email to an individual admin (someone with epicenter account); Requires support level authentication
+ * @param adminKey                              The unique adminKey for the email target
+ * @param subject                               The subject line for the email.
+ * @param [optionals]                           Optional parameter
+ * @param [optionals.familyNameFirst]           Specifies whether email target's family name will come before their given name. Defaults to false.
+ * @param [optionals.html]                      Whether to treat the body as HTML (true) or as plain text (false). Defaults to false.
+ * @param [optionals.body]                      The content of the email.
+ * @param [optionals.attachments]               An array of (binary) objects to include as attachments. All four properties must be included.
+ * @param [optionals.attachments[].encoding]    A string specifying the encoding method. See ENCODING for possible values.
+ * @param [optionals.attachments[].data]        A string containing the data for the attachment.
+ * @param [optionals.attachments[].name]        A string containing the name of the attachment.
+ * @param [optionals.attachments[].contentType] A string specifying the attachment MIME Type.
+ * @returns undefined indicating success
+ */
+export async function sendEmailToAdmin(
+    adminKey: string,
+    subject: string,
+    emailBody: string,
+    optionals: {
+        familyNameFirst?: string,
+        html?: boolean,
+        body?: string,
+        attachments?: {
+            encoding: keyof typeof ENCODING,
+            data: string,
+            name: string,
+            contentType: string,
+        }
+    } & RoutingOptions = {}
+): Promise<void> {
+    const { accountShortName, projectShortName, server, familyNameFirst, html, attachments } =
+        optionals;
+
+    return await new Router()
+        .withServer(server)
+        .withAccountShortName(accountShortName)
+        .withProjectShortName(projectShortName)
+        .post(`/email/admin/${adminKey}`, {
+            body: {
+                subject,
+                body: emailBody,
+                familyNameFirst,
+                html,
+                attachments,
+            },
+        })
+        .then(({ body }) => body);
+}

package/src/adapters/episode.ts

@@ -0,0 +1,163 @@
+import type { UserSession } from 'utils/identification';
+import type { RoutingOptions, Page, GenericSearchOptions } from 'utils/router';
+import { identification, Router } from 'utils';
+
+
+interface Episode {
+    name: string,
+    episodeKey: string,
+}
+
+/**
+ * Create an episode.
+ * @example
+ * epicenter.episodeAdapter.create('myEpisode', 'myGroupName', {
+ *      runLimit: 20,
+ *      draft: true,
+ * });
+ * @param name                  Episode name
+ * @param groupName             Group to make the episode under
+ * @param [optionals]           Optional arguments; pass network call options overrides here. Special arguments specific to this method are listed below if they exist.
+ * @param [optionals.draft]     Flag to indicate the episode is a draft (intended when used for settings scoping)
+ * @param [optionals.runLimit]  Optional argument to define the number of runs that can be made using this episode as the scope
+ * @returns promise that resolves to the newly created episode
+ */
+export async function create(
+    name: string,
+    groupName: string,
+    optionals: {
+        draft?: boolean,
+        runLimit?: number,
+    } & RoutingOptions = {}
+): Promise<Episode> {
+    const {
+        draft, runLimit,
+        ...routingOptions
+    } = optionals;
+    return await new Router()
+        .post(`/episode/${groupName}`, {
+            body: { name, draft, runLimit },
+            ...routingOptions,
+        }).then(({ body }) => body);
+}
+
+/**
+ * Gets a specific episode.
+ * @example
+ * epicenter.episodeAdapter.get('000001796733eef0842f4d6d960997018a37');
+ *
+ * @param episodeKey    The episode key
+ * @param [optionals]   Optional arguments; pass network call options overrides here.
+ * @returns promise that resolves to an episode
+ */
+export async function get(
+    episodeKey: string,
+    optionals: RoutingOptions = {}
+): Promise<Episode> {
+    return await new Router()
+        .get(`/episode/${episodeKey}`, optionals)
+        .then(({ body }) => body);
+}
+
+/**
+ * Gets episodes.
+ * @example
+ * const filter = [
+ *      'name|=one|two',                                            // searches only for episodes named 'one' or 'two'
+ *      'draft=false',                                              // searches only for episodes that aren't drafts
+ *      'created>=2022-01-03T20:30:53.054Z',                        // looks for any episodes created after Jan 3rd 2022
+ *      // 'account.shortName=acme'                                 // specifies the account, intended for admin use
+ *      // 'project.shortName=simulations'                          // specifies the project, intended for admin use
+ *      // 'group.name=my-group-name',                              // specifies a group name, intended for admin use
+ *      // 'group.groupKey=0000017dd3bf540e5ada5b1e058f08f20461',   // specifies a group key, intended for admin use
+ * ];
+ * epicenter.episodeAdapter.query({
+ *      filter,
+ *      sort: ['+episode.created'],     // sort all findings by the 'created' field (ascending)
+ *      first: 3,                       // page should start with the 4th item found (will default to 0)
+ *      max: 10,                        // page should only include the first 10 items
+ * });
+ * @param searchOptions             Search options for the query
+ * @param [searchOptions.filter]    Filters for searching
+ * @param [searchOptions.sort]      Sorting criteria
+ * @param [searchOptions.first]     The starting index of the page returned
+ * @param [searchOptions.max]       The number of entries per page
+ * @param [optionals]               Optional arguments; pass network call options overrides here.
+ * @returns promise that resolves to a page of episodes
+ */
+export async function query(
+    searchOptions: GenericSearchOptions,
+    optionals: RoutingOptions = {}
+): Promise<Page<Episode>> {
+    const { filter = [], sort = [], first = 0, max } = searchOptions;
+
+    return await new Router()
+        .withSearchParams({
+            filter: filter.join(';') || undefined,
+            sort: sort.join(';') || undefined,
+            first, max,
+        })
+        .get('/episode/search', {
+            paginated: true,
+            ...optionals,
+        })
+        .then(({ body }) => body);
+}
+
+/**
+ * Gets episodes based on a group key
+ * @example
+ * epicenter.episodeAdapter.withGroup('0000017dd3bf540e5ada5b1e058f08f20461');
+ *
+ * @param groupKey      The group key
+ * @param [optionals]   Optional arguments; pass network call options overrides here.
+ * @returns promise resolving to a list of episodes
+ */
+export async function forGroup(
+    groupKey: string,
+    optionals: RoutingOptions = {}
+): Promise<Episode[]> {
+    return await new Router()
+        .get(`/episode/in/${groupKey}`, optionals)
+        .then(({ body }) => body);
+}
+
+/**
+ * Gets episode based on group name and episode name
+ * @example
+ * epicenter.episodeAdapter.withName('myEpisodeName');
+ * @param name                  The episode name
+ * @param [optionals]           Optional arguments; pass network call options overrides here. Special arguments specific to this method are listed below if they exist.
+ * @param [optionals.groupName] Name of the group, if omitted will use the group name associated with the current session
+ * @returns promise that resolves to an episode
+ */
+export async function withName(
+    name: string,
+    optionals: { groupName?: string } & RoutingOptions = {}
+): Promise<Episode> {
+    const {
+        groupName,
+        ...routingOptions
+    } = optionals;
+
+    const session = identification.session as UserSession;
+    return await new Router()
+        .get(`/episode/with/${groupName ?? session?.groupName}/${name}`, routingOptions)
+        .then(({ body }) => body);
+}
+
+/**
+ * Deletes an episode
+ * @example
+ * epicenter.episodeAdapter.remove('000001796733eef0842f4d6d960997018a3b');
+ * @param [optionals]   Optional arguments; pass network call options overrides here.
+ * @returns promise that resolves to undefined if successful
+ */
+export async function remove(
+    episodeKey: string,
+    optionals: RoutingOptions = {}
+): Promise<void> {
+    return await new Router()
+        .delete(`/episode/${episodeKey}`, optionals)
+        .then(({ body }) => body);
+}