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

package/dist/api.d.ts

@@ -9,19 +9,52 @@
 import { MonterosaSdk } from '@monterosa/sdk-core';
 import { Unsubscribe, TaskQueue } from '@monterosa/sdk-util';
 import { Payload } from '@monterosa/sdk-launcher-kit';
-import { IdentifyKit, LoginState, Credentials, Signature, UserData, IdentifyOptions, IdentifyAction, IdentifyHook } from './types';
+import { IdentifyKit, LoginState, Credentials, Signature, UserData, IdentifyOptions, IdentifyAction, LoginPolicy } from './types';
+import { Identify } from './identify';
 /**
  * @internal
  */
-export declare const taskQueue: TaskQueue;
+export declare const identifyKits: Map<string, Identify>;
 /**
+ * Read the current locally-owned login policy.
+ *
+ * Returns `'disabled'` by default.
+ *
  * @internal
  */
-export declare function parentAppRequest<T>(identify: IdentifyKit, action: IdentifyAction, payload?: Payload): Promise<T>;
+export declare function getLoginPolicy(): LoginPolicy;
+/**
+ * Set the login policy.
+ *
+ * - `'auto'`: the SDK automatically logs the user in whenever
+ *   credentials are available.
+ * - `'disabled'`: credentials are tracked but no automatic login is
+ *   attempted.
+ *
+ * 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.
+ *
+ * @param policy - `'auto'` or `'disabled'`.
+ */
+export declare function setLoginPolicy(policy: LoginPolicy): void;
 /**
+ * Whether the user should be auto-logged in on reconnect.
+ *
+ * True when the user was previously logged in, the policy is `'auto'`,
+ * and credentials are available on the identify instance.
+ *
  * @internal
  */
-export declare function registerIdentifyHook(hook: IdentifyHook): void;
+export declare function shouldLoginOnReconnect(identify: IdentifyKit): boolean;
+/**
+ * @internal
+ */
+export declare const taskQueue: TaskQueue;
+/**
+ * @internal
+ */
+export declare function sendParentRequest<T>(action: IdentifyAction, payload?: Payload): Promise<T>;
 /**
  * @internal
  */
@@ -31,16 +64,63 @@ export declare function loginTask(identify: IdentifyKit, credentials: Credential
  */
 export declare function logoutTask(identify: IdentifyKit): Promise<void>;
 /**
+ * Enqueue a `loginTask` for the given identify when `policy === 'auto'`.
+ * The downstream `Login` broadcast is emitted by {@link applyLogin}.
+ *
  * @internal
  */
 export declare function enqueueLogin(identify: IdentifyKit, credentials: Credentials, prioritise?: boolean): void;
 /**
+ * Reset the identify's identity-derived caches and enqueue a `logoutTask`
+ * when `policy === 'auto'`.
+ *
  * @internal
  */
 export declare function enqueueLogout(identify: IdentifyKit): 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.
+ * 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 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: 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
+ */
+export declare function applyLogout(): void;
+/**
+ * Pull state from the parent application and apply locally.
+ *
+ * Fires once at non-root bridge module load, regardless of
+ * `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 change to the current credentials.
+ *
+ * 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>;
+/**
+ * Get the IdentifyKit instance for the given SDK / project.
+ *
+ * The IdentifyKit instance is used to authenticate users and read
+ * user data.
  *
  * @example
  * ```javascript
@@ -53,24 +133,19 @@ export declare function enqueueLogout(identify: IdentifyKit): 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.
- *
- * - Subsequent calls to getIdentify with the same MonterosaSdk instance will return
- *   the same `IdentifyKit` instance.
+ * First-call-wins: subsequent calls for the same project return the
+ * cached instance and ignore the `options` argument.
  *
- * @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?: IdentifyOptions): IdentifyKit;
+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
@@ -83,83 +158,74 @@ export declare function getIdentify(sdk?: MonterosaSdk, options?: IdentifyOption
  * ```
  *
  * @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 to getIdentify with the same MonterosaSdk instance will return
- *   the same `IdentifyKit` instance.
- *
- * @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?: IdentifyOptions): IdentifyKit;
+export declare function getIdentify(options?: Partial<IdentifyOptions>): IdentifyKit;
 /**
- * A function that requests a user login via the `IdentifyKit` of the Monterosa SDK.
+ * 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
  * import { configure } from '@monterosa/sdk-core';
- * import { getIdentify, requestLogin } from '@monterosa/sdk-identify-kit';
+ * import { requestLogin } from '@monterosa/sdk-identify-kit';
  *
  * configure({ host: '...', projectId: '...' });
  *
  * try {
- *   const identify = getIdentify();
- *
- *   await requestLogin(identify);
- *
+ *   await requestLogin();
  *   console.log('Login request successful');
  * } catch (err) {
- *   console.error('Error requesting login:', error.message)
+ *   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 once the login request has been
+ *   delivered.
+ */
+export declare function requestLogin(): Promise<void>;
+/**
+ * Read the current credentials.
  *
- * @param identify - An instance of the `IdentifyKit` class used for user
- *   identification.
- * @returns A Promise that resolves with `void` when the login request
- *   is completed.
+ * 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.
  */
-export declare function requestLogin(identify: IdentifyKit): Promise<void>;
+export declare function getCredentials(): Promise<Credentials | null>;
 /**
- * A function that requests a user login via the `IdentifyKit` of the Space.
+ * 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
- * import { getSpace } from '@monterosa/sdk-core';
- * import { getIdentify, requestLogout } from '@monterosa/sdk-identify-kit';
+ * import { configure } from '@monterosa/sdk-core';
+ * import { requestLogout } from '@monterosa/sdk-identify-kit';
  *
- * const space = getSpace('host', 'space-id');
- * const identify = getIdentify(space);
+ * configure({ host: '...', projectId: '...' });
  *
  * try {
- *   await requestLogout(identify);
- *
+ *   await requestLogout();
  *   console.log('Logout request successful');
  * } catch (err) {
- *   console.error('Error requesting logout:', error.message)
+ *   console.error('Error requesting logout:', err.message)
  * }
  * ```
  *
- * @remarks
- * - If the app is running within a third-party application that uses
- *   the Space, the function delegates to the parent app
- *   to handle the logout process.
- *
- * @param identify - An instance of the `IdentifyKit` class used for user
- *   identification.
- * @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(identify: IdentifyKit): Promise<void>;
+export declare function requestLogout(): Promise<void>;
 /**
  * @internal
  *
@@ -178,104 +244,95 @@ export declare function requestLogout(identify: IdentifyKit): Promise<void>;
  */
 export declare function getSessionSignature(identify: IdentifyKit, credentials: Credentials): Promise<Signature>;
 /**
- * A memoized version of the `getSessionSignature` function.
+ * @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>;
 /**
- * The function that takes an instance of `IdentifyKit` as its argument and
- * returns a Promise that resolves to a key-value object representing user data.
+ * Fetch user data for the given credentials.
+ *
+ * Credentials are required explicitly. Obtain a value via
+ * {@link getCredentials} or the {@link onCredentialsUpdated} callback.
  *
  * @example
  * ```javascript
  * import { configure } from '@monterosa/sdk-core';
- * import { getIdentify, getUserData } from '@monterosa/sdk-identify-kit';
+ * import {
+ *   getIdentify,
+ *   getUserData,
+ *   getCredentials,
+ * } from '@monterosa/sdk-identify-kit';
  *
  * configure({ host: '...', projectId: '...' });
  *
  * const identify = getIdentify();
- * const userData = await getUserData(identify);
+ * const credentials = await getCredentials();
  *
- * console.log('User data:', userData);
+ * if (credentials !== null) {
+ *   const userData = await getUserData(identify, credentials);
+ *   console.log('User data:', userData);
+ * }
  * ```
  *
  * @remarks
- * - If the app is running within a third-party application that uses
- *   the Monterosa SDK, the function delegates to the parent app
- *   to get user data.
- *
- * - If the request is successful, the function resolves with a key-value object
- *   representing user data. If not, a `MonterosaError` is thrown.
- *
- * @param identify - An instance of `IdentifyKit` that provides the user
- *   identification functionality.
- * @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. It typically contains information about the user,
- *   but the specific fields are determined by the Identify service provider.
+ * 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): Promise<UserData>;
+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
  * import { configure } from '@monterosa/sdk-core';
- * import { getIdentify, setCredentials } from '@monterosa/sdk-identify-kit';
+ * import { setCredentials } from '@monterosa/sdk-identify-kit';
  *
  * configure({ host: '...', projectId: '...' });
  *
- * const credentials = { token: 'abc123' };
- * const identify = getIdentify();
- *
- * await setCredentials(identify, credentials)
+ * await setCredentials({ token: 'abc123' });
  * ```
  *
- * @remarks
- * - If the app is running within a third-party application that uses
- *   the Monterosa SDK, the function delegates to the parent app
- *   to set user credentials.
- *
- * - If the request is successful, the function resolves to `void`.
- *   If not, a `MonterosaError` is thrown.
- *
- * @param identify - An instance of `IdentifyKit` that provides the user
- *   identification functionality.
- * @param credentials - An object representing the user's authentication
- *   credentials.
- * @returns A Promise that resolves to `void`.
+ * @param credentials - The user's authentication credentials.
+ * @returns A Promise that resolves once the credentials have been
+ *   applied.
  */
-export declare function setCredentials(identify: IdentifyKit, credentials: Credentials): Promise<void>;
+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
  * import { configure } from '@monterosa/sdk-core';
- * import { getIdentify, clearCredentials } from '@monterosa/sdk-identify-kit';
+ * import { clearCredentials } from '@monterosa/sdk-identify-kit';
  *
  * configure({ host: '...', projectId: '...' });
  *
- * const identify = getIdentify();
- *
- * await clearCredentials(identify);
+ * await clearCredentials();
  * ```
  *
- * @remarks
- * - If the app is running within a third-party application that uses
- *   the Monterosa SDK, the function delegates to the parent app
- *   to clear user credentials.
- *
- * - If the request is successful, the function resolves to `void`.
- *   If not, a `MonterosaError` is thrown.
- *
- * @param identify - An instance of `IdentifyKit` that provides the user
- *   identification functionality.
- * @returns A Promise that resolves to `void`.
+ * @returns A Promise that resolves once the credentials have been
+ *   cleared.
  */
-export declare function clearCredentials(identify: IdentifyKit): Promise<void>;
+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
@@ -289,184 +346,82 @@ export declare function clearCredentials(identify: IdentifyKit): 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`
- * object associated with the `IdentifyKit` instance is updated.
+ * Register a callback for updates to the current credentials.
  *
  * @example
  * ```javascript
  * import { configure } from '@monterosa/sdk-core';
- * import { getIdentify, onCredentialsUpdated } from '@monterosa/sdk-identify-kit';
+ * import { onCredentialsUpdated } from '@monterosa/sdk-identify-kit';
  *
  * configure({ host: '...', projectId: '...' });
  *
- * const identify = getIdentify();
- *
- * const unsubscribe = onCredentialsUpdated(identify, (credentials) => {
+ * const unsubscribe = onCredentialsUpdated((credentials) => {
  *   if (credentials !== null) {
  *     console.log("Credentials updated:", credentials);
  *   } else {
  *     console.log("Credentials cleared.");
  *   }
  * });
- *
- * // 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 `Credentials` object as its only argument.
- *   If the value `null` is received, it indicates that the signature has
- *   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(identify: IdentifyKit, callback: (credentials: Credentials | null) => void): Unsubscribe;
+export declare function onCredentialsUpdated(callback: (credentials: Credentials | null) => void): Unsubscribe;
 /**
- * Registers a callback function that will be called whenever the `Signature`
- * object associated with the `IdentifyKit` instance is updated.
- *
- * @example
- * ```javascript
- * import { configure } from '@monterosa/sdk-core';
- * import { getIdentify, onSignatureUpdated } from '@monterosa/sdk-identify-kit';
+ * Register a callback for login requests.
  *
- * configure({ host: '...', projectId: '...' });
- *
- * const identify = getIdentify();
- *
- * const unsubscribe = onSignatureUpdated(identify, (signature) => {
- *   if (signature !== null) {
- *     console.log("Signature updated:", signature);
- *   } else {
- *     console.log("Signature cleared.");
- *   }
- * });
- *
- * // 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 `Signature` object as its only argument.
- *   If the value `null` is received, it indicates that the signature has
- *   been cleared
- * @returns An `Unsubscribe` function that can be called to unregister
- *   the callback function.
- */
-export declare function onSignatureUpdated(identify: IdentifyKit, callback: (signature: Signature | null) => void): Unsubscribe;
-/**
- * Registers a callback function that will be called whenever the `UserData`
- * object associated with the `IdentifyKit` instance is updated.
+ * Fires when {@link requestLogin} is called at this level — whether by
+ * local code or relayed up from an embedded experience.
  *
  * @example
  * ```javascript
  * import { configure } from '@monterosa/sdk-core';
- * import { getIdentify, onUserDataUpdated } from '@monterosa/sdk-identify-kit';
+ * import { onLoginRequestedByExperience } from '@monterosa/sdk-identify-kit';
  *
  * configure({ host: '...', projectId: '...' });
  *
- * const identify = getIdentify();
- *
- * const unsubscribe = onUserDataUpdated(identify, (userData) => {
- *   if (userData !== null) {
- *     console.log("User's data updated:", userData);
- *   } else {
- *     console.log("User's data cleared.");
- *   }
+ * const unsubscribe = onLoginRequestedByExperience(() => {
+ *   showLoginForm();
  * });
- *
- * // 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 `UserData` object as its only argument.
- *   If the value `null` is received, it indicates that the user's data has
- *   been cleared
- * @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 onUserDataUpdated(identify: IdentifyKit, callback: (userData: UserData | null) => void): Unsubscribe;
+export declare function onLoginRequestedByExperience(callback: () => void): Unsubscribe;
 /**
- * Registers a callback function that will be called when a login 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
  * import { configure } from '@monterosa/sdk-core';
- * import { getIdentify, onLoginRequestedByExperience } from '@monterosa/sdk-identify-kit';
+ * import { onLogoutRequestedByExperience } from '@monterosa/sdk-identify-kit';
  *
  * configure({ host: '...', projectId: '...' });
  *
- * const identify = getIdentify();
- *
- * const unsubscribe = onLoginRequestedByExperience(identify, () => {
- *   showLoginForm();
- * });
- *
- * // 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 when a login is requested by an Experience.
- * @returns An `Unsubscribe` function that can be called to unregister
- *   the callback function.
- */
-export declare function onLoginRequestedByExperience(identify: IdentifyKit, callback: () => void): Unsubscribe;
-/**
- * Registers a callback function that will be called when a logout is requested
- * by an Experience.
- *
- * @example
- * ```javascript
- * import { getSpace } from '@monterosa/sdk-core';
- * import { getIdentify, onLogoutRequestedByExperience } from '@monterosa/sdk-identify-kit';
- *
- * const space = getSpace('host', 'space-id');
- * const identify = getIdentify(space);
- *
- * const unsubscribe = onLogoutRequestedByExperience(identify, () => {
- *   // logout requested by experience
- *   // perform logout from Auth service
+ * const unsubscribe = onLogoutRequestedByExperience(() => {
+ *   // perform logout from auth service
  * });
- *
- * // 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 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(identify: IdentifyKit, callback: () => void): Unsubscribe;
+export declare function onLogoutRequestedByExperience(callback: () => void): Unsubscribe;
 /**
- *
  * @internal
  */
 export declare function watchConnectionStatus(identify: IdentifyKit): Promise<void>;