epicenter-libs 3.33.0 → 3.34.1

package/dist/test/adapters/authentication.js

@@ -1,349 +0,0 @@
-import '../utils/helpers.js';
-import '../utils/config.js';
-import identification from '../utils/identification.js';
-import '../utils/error-manager.js';
-import Router from '../utils/router.js';
-import cometdAdapter from './cometd.js';
-
-/**
- * Logs out of current Epicenter session. Also disconnects from CometD and removes user presence.
- * Priorities:
- * 1. Delete local session (even if 2 and 3 fail)
- * 2. Delete remote session (even if 3 fails)
- * 3. Other cleanup (disconnect CometD, delete presence)
- * Cleanup operations require authentication, so await cleanup before delete.
- * Base URL: DELETE `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/verification`
- *
- * @example
- * import { authAdapter } from 'epicenter-libs';
- * await authAdapter.logout();
- *
- * @param [verificationOptionals]   Optional arguments; pass network call options overrides here.
- * @param [presenceOptionals]       Optional arguments; pass network call options overrides here.
- * @returns promise that resolves when logout is complete
- */
-async function logout(verificationOptionals = {}, presenceOptionals = verificationOptionals) {
-  var _identification$sessi;
-  const cleanup = [cometdAdapter.disconnect()];
-  const groupKey = identification === null || identification === void 0 || (_identification$sessi = identification.session) === null || _identification$sessi === void 0 ? void 0 : _identification$sessi.groupKey;
-  if (groupKey) {
-    cleanup.push(new Router().delete(`/presence/group/${groupKey}`, presenceOptionals));
-  }
-  await Promise.allSettled(cleanup);
-  await new Router().delete('/verification', verificationOptionals).finally(() => identification.session = undefined);
-}
-
-/**
- * Retrieves the current session from the server
- * Base URL: GET `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/verification`
- *
- * @example
- * import { authAdapter } from 'epicenter-libs';
- * const session = await authAdapter.getSession();
- *
- * @param [optionals]   Optional arguments; pass network call options overrides here.
- * @returns promise that resolves to the session object
- */
-async function getSession(optionals = {}) {
-  const {
-    body
-  } = await new Router().get('/verification', optionals);
-  identification.session = body;
-  return body;
-}
-
-/**
- * Retrieves the session stored in memory
- *
- * @example
- * import { authAdapter } from 'epicenter-libs';
- * const session = authAdapter.getLocalSession();
- *
- * @returns the session object if it exists, undefined otherwise
- */
-function getLocalSession() {
-  return identification.session;
-}
-
-/**
- * Stores a session in memory
- *
- * @example
- * import { authAdapter } from 'epicenter-libs';
- * authAdapter.setLocalSession(session);
- *
- * @param session   The session object to store
- * @returns the stored session object
- */
-function setLocalSession(session) {
-  return identification.session = session;
-}
-
-/**
- * Removes the session stored in memory and disconnects from CometD
- *
- * @example
- * import { authAdapter } from 'epicenter-libs';
- * await authAdapter.removeLocalSession();
- *
- * @returns promise that resolves when the session is removed and CometD is disconnected
- */
-async function removeLocalSession() {
-  identification.session = undefined;
-  await cometdAdapter.disconnect();
-}
-
-/**
- * Logs in a user or app and stores the session
- * Base URL: POST `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/authentication`
- *
- * @example
- * import { authAdapter } from 'epicenter-libs';
- * // User login
- * const session = await authAdapter.login({
- *     handle: 'user@example.com',
- *     password: 'myPassword',
- *     groupKey: '00000165ad4e6a3cd22b993340b963820239',
- * });
- * // App login
- * const session = await authAdapter.login({
- *     secretKey: 'my-secret-key',
- * });
- *
- * @param credentials                           User or app credentials
- * @param credentials.handle                    User handle (email or username)
- * @param credentials.password                  User password
- * @param [credentials.groupKey]                Group key for user login
- * @param credentials.secretKey                 Secret key for app 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.objectType]                Object type for authentication (defaults to 'user' or 'account' based on credentials)
- * @param [optionals.forcePathInclusion]        Controls cookie path behavior: `true` forces project-specific path (even on custom domains), `false` forces root path (even for users/admins on Epicenter domain), `undefined` uses defaults (project-specific for users/admins on Epicenter domain, root for custom domains)
- * @returns promise that resolves to the session object
- */
-async function login(credentials, optionals = {}) {
-  const {
-    objectType,
-    forcePathInclusion,
-    ...routingOptions
-  } = optionals;
-  let payload;
-  if (Object.prototype.hasOwnProperty.call(credentials, 'handle')) {
-    const {
-      handle,
-      password,
-      groupKey
-    } = credentials;
-    payload = {
-      objectType: objectType !== null && objectType !== void 0 ? objectType : 'user',
-      handle,
-      password,
-      groupKey: groupKey || undefined
-    };
-  }
-  if (Object.prototype.hasOwnProperty.call(credentials, 'secretKey')) {
-    const {
-      secretKey
-    } = credentials;
-    payload = {
-      objectType: objectType !== null && objectType !== void 0 ? objectType : 'account',
-      secretKey
-    };
-  }
-  const session = await new Router().post('/authentication', {
-    inert: true,
-    includeAuthorization: false,
-    body: payload,
-    ...routingOptions
-  }).then(({
-    body
-  }) => body);
-  await removeLocalSession();
-  identification.setSessionWithOptions(session, forcePathInclusion);
-  return session;
-}
-
-/**
- * Regenerates your Epicenter session with the appropriate context.
- * Base URL: PATCH `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/authentication`
- *
- * - For users: Updates session to the specified group context
- * - For admins: Updates session to the specified account/project context (uses platform's focus API)
- *
- * This is automatically called when switching between projects/groups if the session cookie
- * is scoped to a specific project path.
- *
- * Will fail if the user/admin does not already belong to the group/account.
- *
- * @example
- * import { authAdapter } from 'epicenter-libs';
- * // Changes the current user session to have a group context associated with the provided key
- * await authAdapter.regenerate('00000165ad4e6a3cd22b993340b963820239');
- * // Changes the current admin session to use the account context for the 'acme' account
- * await authAdapter.regenerate('acme', { objectType: 'admin' });
- *
- * @param groupOrAccount                    Group key or account 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.objectType]            The object type to regenerate for (defaults to 'user')
- * @param [optionals.forcePathInclusion]    Controls cookie path behavior: `true` forces project-specific path (even on custom domains), `false` forces root path (even for users/admins on Epicenter domain), `undefined` uses defaults (project-specific for users/admins on Epicenter domain, root for custom domains)
- * @returns promise that resolves to the new session object
- */
-async function regenerate(groupOrAccount, optionals = {}) {
-  const {
-    objectType = 'user',
-    accountShortName,
-    forcePathInclusion,
-    ...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 removeLocalSession();
-  identification.setSessionWithOptions(session, forcePathInclusion);
-  return session;
-}
-
-/**
- * Authenticates using Single Sign-On (SSO)
- * Base URL: GET `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/registration/sso/user`
- *
- * @example
- * import { authAdapter } from 'epicenter-libs';
- * const session = await authAdapter.sso();
- *
- * @param [optionals]   Optional arguments; pass network call options overrides here.
- * @returns promise that resolves to the session object
- */
-async function sso(optionals = {}) {
-  const session = await new Router().get('/registration/sso/user', optionals).then(({
-    body
-  }) => body);
-  identification.session = session;
-  return session;
-}
-
-/**
- * Retrieves the SAML link from the SSO configuration
- * Base URL: GET `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/registration/sso/user/saml`
- *
- * @example
- * import { authAdapter } from 'epicenter-libs';
- * const samlLink = await authAdapter.getSAMLLink();
- *
- * @param [optionals]   Optional arguments; pass network call options overrides here.
- * @returns promise that resolves to the SAML link
- */
-async function getSAMLLink(optionals = {}) {
-  return await new Router().get('/registration/sso/user/saml', optionals).then(({
-    body
-  }) => body);
-}
-
-/**
- * Generates and returns an epicenter URL that will redirect to the SAML url
- *
- * @example
- * import { authAdapter } from 'epicenter-libs';
- * const samlURL = authAdapter.generateSAMLLINK();
- *
- * @param [optionals]   Optional arguments; pass network call options overrides here.
- * @returns the generated SAML URL string
- */
-function generateSAMLLINK(optionals = {}) {
-  return new Router().getURL('/registration/sso/user/saml', optionals).toString();
-}
-
-/**
- * Sends an outcome to an external link specified in project config. For example, sending a grade back to a third party platform.
- * Base URL: POST `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/lti/{LTI_VERSION}/outcome`
- *
- * @example
- * import { authAdapter } from 'epicenter-libs';
- * await authAdapter.ssoOutcome('1.3', {
- *     value: 95,
- *     sourcedId: 'student-assignment-123',
- *     outcomeServiceUrl: 'https://lms.example.com/outcome',
- * });
- *
- * @param ltiVersion                                The version of LTI to use (valid versions: 1.1, 1.2, 1.3)
- * @param outcomeInformation                        Outcome information to send
- * @param outcomeInformation.value                  The value to pass back to the outcomeServiceUrl (e.g., the grade a student received)
- * @param outcomeInformation.sourcedId              The id of the current assignment/student as provided by the client using the SSO service
- * @param outcomeInformation.outcomeServiceUrl      The url called for passing back the outcome
- * @param [optionals]                               Optional arguments; pass network call options overrides here.
- * @returns promise that resolves to the response object
- */
-async function ssoOutcome(ltiVersion, outcomeInformation, optionals = {}) {
-  const {
-    ...routingOptions
-  } = optionals;
-  return await new Router().post(`/lti/${ltiVersion}/outcome`, {
-    body: outcomeInformation,
-    ...routingOptions
-  }).then(({
-    body
-  }) => body);
-}
-
-/**
- * Sends a link to reset a user's password to their email
- * Base URL: POST `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/verification/password/user/{HANDLE}`
- *
- * @example
- * import { authAdapter } from 'epicenter-libs';
- * const subject = 'Please reset your password for the Acme simulation';
- * const redirectURL = 'https://forio.com/app/acme/simulations';
- * const handle = 'testUser@test.com';
- * await 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)
- * @param [optionals.subject]           The subject of the email that will be sent
- * @returns promise that resolves when the reset email is sent
- */
-async function resetPassword(handle, optionals = {}) {
-  const {
-    redirectURL,
-    subject,
-    ...routingOptions
-  } = optionals;
-  return await new Router().post(`/verification/password/user/${handle}`, {
-    ...routingOptions,
-    body: {
-      redirectUrl: redirectURL,
-      subject
-    }
-  }).then(({
-    body
-  }) => body);
-}
-
-/**
- * Verifies a token and retrieves the associated session
- * Base URL: GET `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/verification`
- *
- * @example
- * import { authAdapter } from 'epicenter-libs';
- * const session = await authAdapter.verify('my-auth-token');
- *
- * @param token         Authorization token to verify
- * @param [optionals]   Optional arguments; pass network call options overrides here.
- * @returns promise that resolves to the session object
- */
-async function verify(token, optionals = {}) {
-  return await new Router().get('/verification', {
-    authorization: `Bearer ${token}`,
-    ...optionals
-  }).then(({
-    body
-  }) => body);
-}
-
-export { generateSAMLLINK, getLocalSession, getSAMLLink, getSession, login, logout, regenerate, removeLocalSession, resetPassword, setLocalSession, sso, ssoOutcome, verify };

package/dist/test/adapters/channel.js

@@ -1,201 +0,0 @@
-import _defineProperty from '../node_modules/@babel/runtime/helpers/esm/defineProperty.js';
-import { SCOPE_BOUNDARY, PUSH_CATEGORY } from '../utils/constants.js';
-import '../utils/helpers.js';
-import EpicenterError from '../utils/error.js';
-import '../utils/config.js';
-import '../utils/identification.js';
-import '../utils/error-manager.js';
-import 'cross-fetch';
-import cometdAdapter from './cometd.js';
-
-// Generic type for push channel message custom data
-
-// Base structure for channel push messages
-
-const validateScope = scope => {
-  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.
- *
- * @example
- * import { Channel, authAdapter, SCOPE_BOUNDARY, PUSH_CATEGORY } from 'epicenter-libs';
- * const session = authAdapter.getLocalSession();
- * const channel = new Channel({
- *     scopeBoundary: SCOPE_BOUNDARY.GROUP,
- *     scopeKey: session.groupKey,
- *     pushCategory: PUSH_CATEGORY.CHAT,
- * });
- * await channel.subscribe((data) => {
- *     console.log('Received message:', data);
- * });
- */
-class Channel {
-  /**
-   * Channel constructor
-   *
-   * @param scope                     Object with the scope boundary, scope key, and push category; defines the namespace for the channel
-   * @param scope.scopeBoundary       Scope boundary, defines the type of scope; See [scope boundary](#SCOPE_BOUNDARY) for all types
-   * @param scope.scopeKey            Scope key, a unique identifier tied to the scope. E.g., if your `scopeBoundary` is `GROUP`, your `scopeKey` will be your `groupKey`; for `EPISODE`, `episodeKey`, etc.
-   * @param scope.pushCategory        Push category, defines the type of channel; See [push category](#PUSH_CATEGORY) for all types
-   */
-  constructor(scope) {
-    _defineProperty(this, "path", void 0);
-    _defineProperty(this, "update", void 0);
-    _defineProperty(this, "subscription", null);
-    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) || null;
-    }
-  }
-
-  /**
-   * Publishes content to the CometD channel
-   *
-   * @example
-   * import { Channel, authAdapter, SCOPE_BOUNDARY, PUSH_CATEGORY } from 'epicenter-libs';
-   * const session = authAdapter.getLocalSession();
-   * const channel = new Channel({
-   *     scopeBoundary: SCOPE_BOUNDARY.GROUP,
-   *     scopeKey: session.groupKey,
-   *     pushCategory: PUSH_CATEGORY.CHAT,
-   * });
-   * await channel.publish({ message: 'Hello!' });
-   *
-   * @param content   Content to publish to the channel
-   * @returns promise that resolves to the CometD message response
-   */
-  publish(content) {
-    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-libs';
-   * const session = authAdapter.getLocalSession();
-   * const channel = new Channel({
-   *     scopeBoundary: SCOPE_BOUNDARY.GROUP,
-   *     scopeKey: session.groupKey,
-   *     pushCategory: PUSH_CATEGORY.CHAT,
-   * });
-   * await channel.subscribe((data) => {
-   *      console.log(data.content);
-   * });
-   *
-   * @param update                Function that is called whenever a channel update occurs
-   * @param [options]             Optional arguments
-   * @param [options.inert]       If true, creates an inert subscription that doesn't trigger reconnection
-   * @returns promise that resolves to the subscription object returned by CometD after a successful subscribe
-   */
-  // eslint-disable-next-line complexity
-  async subscribe(update, options = {}) {
-    if (this.subscription) {
-      try {
-        await cometdAdapter.remove(this.subscription);
-      } catch (error) {
-        var _errorObj$information;
-        const errorObj = error;
-        const errorMessage = (errorObj === null || errorObj === void 0 ? void 0 : errorObj.message) || (errorObj === null || errorObj === void 0 || (_errorObj$information = errorObj.information) === null || _errorObj$information === void 0 ? void 0 : _errorObj$information.error) || '';
-        if (errorMessage.includes('session_unknown') || errorMessage.includes('402')) ; else {
-          // Re-throw other errors
-          throw error;
-        }
-      }
-    }
-    this.update = update;
-    let retryCount = 0;
-    const maxRetries = 3;
-    while (retryCount < maxRetries) {
-      try {
-        this.subscription = await cometdAdapter.add(this, update, options);
-        return this.subscription;
-      } catch (error) {
-        var _errorObj$information2;
-        const errorObj = error;
-        const errorMessage = (errorObj === null || errorObj === void 0 ? void 0 : errorObj.message) || (errorObj === null || errorObj === void 0 || (_errorObj$information2 = errorObj.information) === null || _errorObj$information2 === void 0 ? void 0 : _errorObj$information2.error) || '';
-        if ((errorMessage.includes('session_unknown') || errorMessage.includes('402')) && retryCount < maxRetries - 1) {
-          retryCount++;
-          // Force fresh handshake
-          cometdAdapter.handshakeState = 'idle';
-          cometdAdapter.handshakePromise = undefined;
-
-          // Wait a moment before retrying
-          const retryDelay = 1000;
-          const currentRetry = retryCount;
-          await new Promise(resolve => setTimeout(resolve, retryDelay * currentRetry));
-          continue;
-        }
-
-        // Re-throw if not session_unknown or max retries exceeded
-        throw error;
-      }
-    }
-    throw new Error(`Failed to subscribe to ${this.path} after ${maxRetries} attempts`);
-  }
-
-  /**
-   * Unsubscribes from the CometD channel
-   *
-   * @example
-   * import { Channel, authAdapter, SCOPE_BOUNDARY, PUSH_CATEGORY } from 'epicenter-libs';
-   * const session = authAdapter.getLocalSession();
-   * const channel = new Channel({
-   *     scopeBoundary: SCOPE_BOUNDARY.GROUP,
-   *     scopeKey: session.groupKey,
-   *     pushCategory: PUSH_CATEGORY.CHAT,
-   * });
-   * await channel.subscribe((data) => console.log(data));
-   * // Later...
-   * await channel.unsubscribe();
-   *
-   * @returns promise that resolves when unsubscribed
-   */
-  async unsubscribe() {
-    if (this.subscription) {
-      await cometdAdapter.remove(this.subscription);
-      this.subscription = null;
-    }
-  }
-
-  /**
-   * Unsubscribes from all CometD channels
-   *
-   * @example
-   * import { Channel, authAdapter, SCOPE_BOUNDARY, PUSH_CATEGORY } from 'epicenter-libs';
-   * const session = authAdapter.getLocalSession();
-   * const channel = new Channel({
-   *     scopeBoundary: SCOPE_BOUNDARY.GROUP,
-   *     scopeKey: session.groupKey,
-   *     pushCategory: PUSH_CATEGORY.CHAT,
-   * });
-   * await channel.subscribe((data) => console.log(data));
-   * // Later, unsubscribe from all channels...
-   * await channel.unsubscribeAll();
-   *
-   * @returns promise that resolves when all channels are unsubscribed
-   */
-  async unsubscribeAll() {
-    await cometdAdapter.empty();
-  }
-}
-
-export { Channel as default };