@monterosa/sdk-identify-kit 2.0.0-rc.4 → 2.0.0-rc.5

package/dist/index.js

@@ -301,7 +301,7 @@ class LoginPolicyStore extends Emitter {
  * More details on the license can be found at https://www.monterosa.co/sdk/license
  */
 /**
- * Root-owned credentials slot.
+ * Root-owned credentials store.
  *
  * Single source of truth at the root of an integration; an internal
  * mirror at every other level, kept in sync via `Login` / `Logout`
@@ -373,26 +373,18 @@ function getLoginPolicy() {
     return loginPolicyStore.policy;
 }
 /**
- * Set the locally-owned login policy.
+ * Set the login policy.
  *
- * All `Identify` instances at this level honour the same policy; the
- * value is never propagated across the wire (each level of a multi-level
- * integration owns its own policy).
+ * - `'auto'`: the SDK automatically logs the user in whenever
+ *   credentials are available.
+ * - `'disabled'`: credentials are tracked but no automatic login is
+ *   attempted.
  *
- * Policy gates the Enmasse `loginTask` only — credentials always mirror
- * from upstream regardless of policy. A `'disabled'` level still
- * receives credentials via the module-load pull and the cascading
- * `Login` / `Logout` broadcasts; it just doesn't attempt Enmasse
- * validation against them.
+ * Each level of a multi-level integration owns its own policy; the
+ * value is never propagated to embedded experiences. Idempotent:
+ * setting the same policy is a no-op.
  *
- * When the policy transitions to `'auto'`, enqueues a sync-state task
- * for every existing identify so that any in-flight session is picked
- * up.
- *
- * Idempotent: setting the same policy that's already in effect is a
- * no-op.
- *
- * @param policy - `'auto'` to enable auto-login, `'disabled'` to opt out.
+ * @param policy - `'auto'` or `'disabled'`.
  */
 function setLoginPolicy(policy) {
     if (loginPolicyStore.policy === policy) {
@@ -402,13 +394,12 @@ function setLoginPolicy(policy) {
     if (policy !== 'auto') {
         return;
     }
-    // On transition to 'auto': if the local credentials slot already
-    // has a value (typical after the non-root module-load pull, or after
-    // a setCredentials at the root, or after an upstream Login broadcast
-    // has cascaded down), enqueue a login task for each existing
-    // identify. If the slot is empty, do nothing — a future credentials
-    // arrival via `applyLogin` will trigger the login under this new
-    // policy.
+    // On transition to 'auto': if credentials are currently set (typical
+    // after the non-root module-load pull, or after a setCredentials at
+    // the root, or after an upstream Login broadcast has cascaded down),
+    // enqueue a login task for each existing identify. If no credentials
+    // are set, do nothing — a future credentials arrival via `applyLogin`
+    // will trigger the login under this new policy.
     const { credentials } = credentialsStore;
     if (credentials === null) {
         return;
@@ -602,13 +593,15 @@ function enqueueLogout(identify) {
     taskQueue.enqueue(() => logoutTask(identify));
 }
 /**
- * Apply new credentials at this level: update the slot, enqueue a
- * `loginTask` for every existing identify on the null-to-set transition,
- * and broadcast `Login` downstream to every embedded experience.
+ * Apply new credentials at this level: update the current credentials,
+ * enqueue a `loginTask` for every existing identify on the null-to-set
+ * transition, and broadcast `Login` downstream to every embedded
+ * experience.
  *
- * Idempotent on token refresh: re-setting an already-set slot updates
- * the value and broadcasts, but does not re-enqueue logins (their
- * `loginTask` would short-circuit on `state === 'logged_in'` anyway).
+ * Idempotent on token refresh: re-setting when credentials are already
+ * present updates the value and broadcasts, but does not re-enqueue
+ * logins (their `loginTask` would short-circuit on
+ * `state === 'logged_in'` anyway).
  *
  * @internal
  */
@@ -625,10 +618,10 @@ function applyLogin(credentials) {
     }
 }
 /**
- * Clear credentials at this level: null out the slot, enqueue a
- * `logoutTask` for every existing identify on the set-to-null
- * transition, and broadcast `Logout` downstream to every embedded
- * experience.
+ * Clear credentials at this level: clear the current credentials,
+ * enqueue a `logoutTask` for every existing identify on the
+ * set-to-null transition, and broadcast `Logout` downstream to every
+ * embedded experience.
  *
  * @internal
  */
@@ -651,11 +644,11 @@ function applyLogout() {
  * `loginPolicy` — token presence is the customer-side sign-in state and
  * must mirror upstream whether or not we choose to validate against
  * Enmasse. Best-effort: a missing or non-identify-kit parent silently
- * resolves with no slot change.
+ * resolves with no change to the current credentials.
  *
- * Uses {@link applyLogin} so the slot update cascades downstream to
- * this level's own embedded experiences and per-identify loginTasks
- * are enqueued under `loginPolicy === 'auto'`.
+ * Uses {@link applyLogin} so the update cascades downstream to this
+ * level's own embedded experiences and per-identify loginTasks are
+ * enqueued under `loginPolicy === 'auto'`.
  *
  * @internal
  */
@@ -710,7 +703,10 @@ function getIdentify(sdkOrOptions, options) {
     return identify;
 }
 /**
- * Requests a user login.
+ * Request a user login.
+ *
+ * When called from an embedded experience, the request is relayed to
+ * the parent application — the host that owns the auth UI handles it.
  *
  * @example
  * ```javascript
@@ -721,20 +717,14 @@ function getIdentify(sdkOrOptions, options) {
  *
  * try {
  *   await requestLogin();
- *
  *   console.log('Login request successful');
  * } catch (err) {
  *   console.error('Error requesting login:', err.message)
  * }
  * ```
  *
- * @remarks
- * - If the app is running within a third-party application that uses
- *   the Monterosa SDK, the function delegates to the parent app
- *   to handle the login process.
- *
- * @returns A Promise that resolves with `void` when the login request
- *   is completed.
+ * @returns A Promise that resolves once the login request has been
+ *   delivered.
  */
 async function requestLogin() {
     if (getParentApplication() !== null) {
@@ -744,16 +734,14 @@ async function requestLogin() {
     requestsEmitter.emit(IdentifyEvent.LoginRequested);
 }
 /**
- * Read the current credentials, pulling from the parent application when
- * called from an embedded experience.
+ * Read the current credentials.
  *
- * At the root this returns the canonical slot value. At a non-root
- * experience this dispatches a `GetCredentials` request upstream and
- * resolves with the response, ensuring the caller always sees the
- * authoritative value rather than a possibly-stale local mirror.
+ * When called from an embedded experience, fetches the credentials
+ * from the parent application so the caller always sees the
+ * authoritative value.
  *
- * @returns A Promise that resolves to the current credentials, or `null`
- *   if none are set.
+ * @returns A Promise that resolves to the current credentials, or
+ *   `null` if none are set.
  */
 async function getCredentials() {
     if (getParentApplication() === null) {
@@ -762,7 +750,10 @@ async function getCredentials() {
     return sendParentRequest(IdentifyAction.GetCredentials);
 }
 /**
- * Requests a user logout.
+ * Request a user logout.
+ *
+ * When called from an embedded experience, the request is relayed to
+ * the parent application — the host that owns the auth UI handles it.
  *
  * @example
  * ```javascript
@@ -773,20 +764,14 @@ async function getCredentials() {
  *
  * try {
  *   await requestLogout();
- *
  *   console.log('Logout request successful');
  * } catch (err) {
  *   console.error('Error requesting logout:', err.message)
  * }
  * ```
  *
- * @remarks
- * - If the app is running within a third-party application that uses
- *   the Monterosa SDK, the function delegates to the parent app
- *   to handle the logout process.
- *
- * @returns A Promise that resolves with `void` when the logout request
- *   is completed.
+ * @returns A Promise that resolves once the logout request has been
+ *   delivered.
  */
 async function requestLogout() {
     if (getParentApplication() !== null) {
@@ -822,6 +807,8 @@ async function getSessionSignature(identify, credentials) {
     return signature;
 }
 /**
+ * @internal
+ *
  * A memoized version of the `getSessionSignature` function. Memo key is
  * the credentials token, so both leaf-side and bridge-side callers share
  * the same cache for the same token.
@@ -831,12 +818,10 @@ const getSessionSignatureMemoized = memoizePromise(getSessionSignature, (identif
     clearOnReject: true,
 });
 /**
- * Fetches user data for the given credentials.
+ * Fetch user data for the given credentials.
  *
- * Credentials are required explicitly so the precondition is visible at
- * the call site — without them the function cannot be called. Obtain a
- * `Credentials` value via {@link getCredentials} or the
- * {@link onCredentialsUpdated} callback.
+ * Credentials are required explicitly. Obtain a value via
+ * {@link getCredentials} or the {@link onCredentialsUpdated} callback.
  *
  * @example
  * ```javascript
@@ -859,16 +844,13 @@ const getSessionSignatureMemoized = memoizePromise(getSessionSignature, (identif
  * ```
  *
  * @remarks
- * Cached on the identify instance after the first successful fetch.
- * Cleared on {@link clearCredentials} via the logout path.
- *
- * @param identify - An instance of `IdentifyKit` that provides the user
- *   identification functionality.
- * @param credentials - The user's authentication credentials. The
- *   request authorises against the value's token.
- * @returns A Promise that resolves to a key-value object representing
- *   user data. The structure and content of the user data object depend
- *   on the identify service provider and may vary.
+ * Cached after the first successful fetch and reset when credentials
+ * are cleared.
+ *
+ * @param identify - The IdentifyKit instance.
+ * @param credentials - The user's authentication credentials.
+ * @returns A Promise that resolves to a key-value object of user data.
+ *   The structure depends on the identify service provider.
  */
 async function getUserData(identify, credentials) {
     if (identify.userData !== null) {
@@ -880,7 +862,12 @@ async function getUserData(identify, credentials) {
     return data;
 }
 /**
- * Sets the user's authentication credentials.
+ * Set the user's authentication credentials.
+ *
+ * The credentials become the active credentials for the entire
+ * integration. When called from an embedded experience, the call is
+ * relayed to the parent application so that every level of the
+ * integration sees the new value.
  *
  * @example
  * ```javascript
@@ -892,18 +879,9 @@ async function getUserData(identify, credentials) {
  * await setCredentials({ token: 'abc123' });
  * ```
  *
- * @remarks
- * - At the root of an integration, the credentials are stored locally
- *   and a `Login` broadcast is sent to every embedded experience.
- * - When called from an embedded experience, the call is relayed
- *   upstream via the `SetCredentials` wire action. The credentials are
- *   ultimately applied at the root and propagate back down via the
- *   cascading `Login` broadcast.
- *
- * @param credentials - An object representing the user's authentication
- *   credentials.
- * @returns A Promise that resolves to `void` once the credentials have
- *   been written (root) or the upstream relay has completed (non-root).
+ * @param credentials - The user's authentication credentials.
+ * @returns A Promise that resolves once the credentials have been
+ *   applied.
  */
 async function setCredentials(credentials) {
     if (getParentApplication() !== null) {
@@ -913,7 +891,11 @@ async function setCredentials(credentials) {
     applyLogin(credentials);
 }
 /**
- * Clears the user's authentication credentials.
+ * Clear the user's authentication credentials.
+ *
+ * When called from an embedded experience, the call is relayed to the
+ * parent application so that every level of the integration is
+ * cleared.
  *
  * @example
  * ```javascript
@@ -925,16 +907,8 @@ async function setCredentials(credentials) {
  * await clearCredentials();
  * ```
  *
- * @remarks
- * - At the root of an integration, the credentials slot is cleared and
- *   a `Logout` broadcast is sent to every embedded experience.
- * - When called from an embedded experience, the call is relayed
- *   upstream via the `ClearCredentials` wire action. The slot is
- *   cleared at the root and the cascading `Logout` broadcast propagates
- *   back down.
- *
- * @returns A Promise that resolves to `void` once the slot has been
- *   cleared (root) or the upstream relay has completed (non-root).
+ * @returns A Promise that resolves once the credentials have been
+ *   cleared.
  */
 async function clearCredentials() {
     if (getParentApplication() !== null) {
@@ -944,8 +918,7 @@ async function clearCredentials() {
     applyLogout();
 }
 /**
- * Registers a callback function that will be called whenever the `LoginState`
- * object associated with the `IdentifyKit` instance is updated.
+ * Register a callback for `LoginState` updates on the given identify.
  *
  * @example
  * ```javascript
@@ -959,24 +932,17 @@ async function clearCredentials() {
  * const unsubscribe = onStateUpdated(identify, (state) => {
  *   console.log("State updated:", state);
  * });
- *
- * // Call unsubscribe() to unregister the callback function
- * // unsubscribe();
  * ```
  *
- * @param identify - An instance of `IdentifyKit` that provides the user
- *   identification functionality.
- * @param callback - The callback function to register. This function will be
- *   called with the updated `LoginState` object as its only argument.
- * @returns An `Unsubscribe` function that can be called to unregister
- *   the callback function.
+ * @param identify - The IdentifyKit instance.
+ * @param callback - Called with the updated `LoginState`.
+ * @returns An `Unsubscribe` function.
  */
 function onStateUpdated(identify, callback) {
     return subscribe(identify, IdentifyEvent.StateUpdated, callback);
 }
 /**
- * Registers a callback function that will be called whenever the
- * credentials slot is updated.
+ * Register a callback for updates to the current credentials.
  *
  * @example
  * ```javascript
@@ -992,24 +958,20 @@ function onStateUpdated(identify, callback) {
  *     console.log("Credentials cleared.");
  *   }
  * });
- *
- * // Call unsubscribe() to unregister the callback function
- * // unsubscribe();
  * ```
  *
- * @param callback - The callback function to register. This function will be
- *   called with the updated `Credentials` object as its only argument.
- *   If the value `null` is received, it indicates that the credentials have
- *   been cleared.
- * @returns An `Unsubscribe` function that can be called to unregister
- *   the callback function.
+ * @param callback - Called with the updated `Credentials`, or `null`
+ *   when credentials are cleared.
+ * @returns An `Unsubscribe` function.
  */
 function onCredentialsUpdated(callback) {
     return credentialsStore.subscribe(callback);
 }
 /**
- * Registers a callback function that will be called when a login is requested
- * by an Experience.
+ * Register a callback for login requests.
+ *
+ * Fires when {@link requestLogin} is called at this level — whether by
+ * local code or relayed up from an embedded experience.
  *
  * @example
  * ```javascript
@@ -1021,22 +983,19 @@ function onCredentialsUpdated(callback) {
  * const unsubscribe = onLoginRequestedByExperience(() => {
  *   showLoginForm();
  * });
- *
- * // Call unsubscribe() to unregister the callback function
- * // unsubscribe();
  * ```
  *
- * @param callback - The callback function to register. This function will
- *   be called when a login is requested by an Experience.
- * @returns An `Unsubscribe` function that can be called to unregister
- *   the callback function.
+ * @param callback - Called when a login is requested.
+ * @returns An `Unsubscribe` function.
  */
 function onLoginRequestedByExperience(callback) {
     return subscribe(requestsEmitter, IdentifyEvent.LoginRequested, callback);
 }
 /**
- * Registers a callback function that will be called when a logout is requested
- * by an Experience.
+ * Register a callback for logout requests.
+ *
+ * Fires when {@link requestLogout} is called at this level — whether
+ * by local code or relayed up from an embedded experience.
  *
  * @example
  * ```javascript
@@ -1046,24 +1005,17 @@ function onLoginRequestedByExperience(callback) {
  * configure({ host: '...', projectId: '...' });
  *
  * const unsubscribe = onLogoutRequestedByExperience(() => {
- *   // logout requested by experience
- *   // perform logout from Auth service
+ *   // perform logout from auth service
  * });
- *
- * // Call unsubscribe() to unregister the callback function
- * // unsubscribe();
  * ```
  *
- * @param callback - The callback function to register. This function will
- *   be called when a logout is requested by an Experience.
- * @returns An `Unsubscribe` function that can be called to unregister
- *   the callback function.
+ * @param callback - Called when a logout is requested.
+ * @returns An `Unsubscribe` function.
  */
 function onLogoutRequestedByExperience(callback) {
     return subscribe(requestsEmitter, IdentifyEvent.LogoutRequested, callback);
 }
 /**
- *
  * @internal
  */
 async function watchConnectionStatus(identify) {
@@ -1108,7 +1060,7 @@ async function watchConnectionStatus(identify) {
  */
 /**
  * Process an incoming `Login` / `Logout` broadcast from the parent
- * application. Updates the local credentials slot, enqueues login/logout
+ * application. Updates the local current credentials, enqueues login/logout
  * for every existing identify, and forwards the broadcast downstream to
  * this level's own embedded experiences — the mechanism that cascades a
  * root-level `setCredentials` through every nested experience.