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

package/dist/api.d.ts

@@ -24,26 +24,18 @@ export declare const identifyKits: Map<string, Identify>;
  */
 export declare function getLoginPolicy(): LoginPolicy;
 /**
- * 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'`.
  */
 export declare function setLoginPolicy(policy: LoginPolicy): void;
 /**
@@ -86,22 +78,24 @@ export declare function enqueueLogin(identify: IdentifyKit, credentials: Credent
  */
 export declare function enqueueLogout(identify: IdentifyKit): void;
 /**
- * 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
  */
 export declare function applyLogin(credentials: Credentials): void;
 /**
- * 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
  */
@@ -113,18 +107,20 @@ export declare function applyLogout(): void;
  * `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
  */
 export declare function pullStateFromParent(): Promise<void>;
 /**
- * A factory function that creates a new instance of the `IdentifyKit` class,
- * which is a kit of the Monterosa SDK used for user identification.
+ * Get the IdentifyKit instance for the given SDK / project.
+ *
+ * The IdentifyKit instance is used to authenticate users and read
+ * user data.
  *
  * @example
  * ```javascript
@@ -137,25 +133,19 @@ export declare function pullStateFromParent(): Promise<void>;
  * ```
  *
  * @remarks
- * - The `getIdentify` function returns an instance of the `IdentifyKit` class
- *   using optional MonterosaSdk instance as a parameter.
- *
- * - The `IdentifyKit` instance returned by `getIdentify` can be used to authenticate
- *   users and perform other user identification-related operations.
+ * First-call-wins: subsequent calls for the same project return the
+ * cached instance and ignore the `options` argument.
  *
- * - Subsequent calls return the cached `IdentifyKit` instance for the same
- *   project. The `options` argument is honoured only on the first call;
- *   later calls ignore it and return the instance configured by the first.
- *
- * @param sdk - An instance of the MonterosaSdk class.
- * @param options - List of `IdentifyKit` options
- * @returns An instance of the `IdentifyKit` class, which is used for user
- * identification.
+ * @param sdk - The Monterosa SDK instance.
+ * @param options - IdentifyKit options (applied only on the first call).
+ * @returns The IdentifyKit instance for the project.
  */
 export declare function getIdentify(sdk?: MonterosaSdk, options?: Partial<IdentifyOptions>): IdentifyKit;
 /**
- * A factory function that creates a new instance of the `IdentifyKit` class,
- * which is a kit of the Monterosa SDK used for user identification.
+ * Get the IdentifyKit instance for the configured SDK.
+ *
+ * The IdentifyKit instance is used to authenticate users and read
+ * user data.
  *
  * @example
  * ```javascript
@@ -168,23 +158,18 @@ export declare function getIdentify(sdk?: MonterosaSdk, options?: Partial<Identi
  * ```
  *
  * @remarks
- * - The `getIdentify` function returns an instance of the `IdentifyKit` class
- *   using optional MonterosaSdk instance as a parameter.
+ * First-call-wins: subsequent calls for the same project return the
+ * cached instance and ignore the `options` argument.
  *
- * - The `IdentifyKit` instance returned by `getIdentify` can be used to authenticate
- *   users and perform other user identification-related operations.
- *
- * - Subsequent calls return the cached `IdentifyKit` instance for the same
- *   project. The `options` argument is honoured only on the first call;
- *   later calls ignore it and return the instance configured by the first.
- *
- * @param options - List of `IdentifyKit` options
- * @returns An instance of the `IdentifyKit` class, which is used for user
- * identification.
+ * @param options - IdentifyKit options (applied only on the first call).
+ * @returns The IdentifyKit instance for the project.
  */
 export declare function getIdentify(options?: Partial<IdentifyOptions>): IdentifyKit;
 /**
- * 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
@@ -195,37 +180,32 @@ export declare function getIdentify(options?: Partial<IdentifyOptions>): Identif
  *
  * 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.
  */
 export declare function requestLogin(): Promise<void>;
 /**
- * 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.
  */
 export declare function getCredentials(): Promise<Credentials | null>;
 /**
- * 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
@@ -236,20 +216,14 @@ export declare function getCredentials(): Promise<Credentials | null>;
  *
  * 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.
  */
 export declare function requestLogout(): Promise<void>;
 /**
@@ -270,18 +244,18 @@ export declare function requestLogout(): Promise<void>;
  */
 export declare function getSessionSignature(identify: IdentifyKit, credentials: Credentials): Promise<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.
  */
 export declare const getSessionSignatureMemoized: (...args: any[]) => Promise<Signature>;
 /**
- * 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
@@ -304,20 +278,22 @@ export declare const getSessionSignatureMemoized: (...args: any[]) => Promise<Si
  * ```
  *
  * @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.
  */
 export declare function getUserData(identify: IdentifyKit, credentials: Credentials): Promise<UserData>;
 /**
- * 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
@@ -329,22 +305,17 @@ export declare function getUserData(identify: IdentifyKit, credentials: Credenti
  * 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.
  */
 export declare function setCredentials(credentials: Credentials): Promise<void>;
 /**
- * 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
@@ -356,21 +327,12 @@ export declare function setCredentials(credentials: Credentials): Promise<void>;
  * 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.
  */
 export declare function clearCredentials(): Promise<void>;
 /**
- * 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
@@ -384,22 +346,15 @@ export declare function clearCredentials(): Promise<void>;
  * 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.
  */
 export declare function onStateUpdated(identify: IdentifyKit, callback: (state: LoginState) => void): Unsubscribe;
 /**
- * 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
@@ -415,22 +370,18 @@ export declare function onStateUpdated(identify: IdentifyKit, callback: (state:
  *     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.
  */
 export declare function onCredentialsUpdated(callback: (credentials: Credentials | null) => void): Unsubscribe;
 /**
- * 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
@@ -442,20 +393,17 @@ export declare function onCredentialsUpdated(callback: (credentials: Credentials
  * 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.
  */
 export declare function onLoginRequestedByExperience(callback: () => void): Unsubscribe;
 /**
- * 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
@@ -465,22 +413,15 @@ export declare function onLoginRequestedByExperience(callback: () => void): Unsu
  * 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.
  */
 export declare function onLogoutRequestedByExperience(callback: () => void): Unsubscribe;
 /**
- *
  * @internal
  */
 export declare function watchConnectionStatus(identify: IdentifyKit): Promise<void>;

package/dist/bridge.d.ts

@@ -9,7 +9,7 @@
 import { Experience, ExperienceState, Message } from '@monterosa/sdk-launcher-kit';
 /**
  * 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.

package/dist/credentials_store.d.ts

@@ -9,7 +9,7 @@
 import { Emitter, Unsubscribe } from '@monterosa/sdk-util';
 import { Credentials } from './types';
 /**
- * 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`