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

package/dist/sdk-identify-kit.d.ts

@@ -0,0 +1,500 @@
+/**
+ * Handles user authentication and identity management.
+ *
+ * @packageDocumentation
+ */
+
+import { Emitter } from '@monterosa/sdk-util';
+import { MonterosaSdk } from '@monterosa/sdk-core';
+import { Unsubscribe } from '@monterosa/sdk-util';
+
+/**
+ * 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 { clearCredentials } from '@monterosa/sdk-identify-kit';
+ *
+ * configure({ host: '...', projectId: '...' });
+ *
+ * await clearCredentials();
+ * ```
+ *
+ * @returns A Promise that resolves once the credentials have been
+ *   cleared.
+ */
+export declare function clearCredentials(): Promise<void>;
+
+/**
+ * Represents user authentication credentials.
+ *
+ * @remarks
+ * The `token` property can be either the literal `'cookie'` for cookie-based
+ * authentication or a string value for bearer token authentication.
+ *
+ * @example
+ * ```javascript
+ * // Bearer token authentication
+ * const credentials: Credentials = { token: "abc123" };
+ *
+ * // Cookie-based authentication
+ * const credentials: Credentials = { token: "cookie" };
+ * ```
+ */
+export declare type Credentials = {
+    token: 'cookie' | string;
+};
+
+/**
+ * Read the current credentials.
+ *
+ * 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 getCredentials(): Promise<Credentials | null>;
+
+/**
+ * Get the IdentifyKit instance for the given SDK / project.
+ *
+ * The IdentifyKit instance is used to authenticate users and read
+ * user data.
+ *
+ * @example
+ * ```javascript
+ * import { configure } from '@monterosa/sdk-core';
+ * import { getIdentify } from '@monterosa/sdk-identify-kit';
+ *
+ * configure({ host: '...', projectId: '...' });
+ *
+ * const identify = getIdentify();
+ * ```
+ *
+ * @remarks
+ * First-call-wins: subsequent calls for the same project return the
+ * cached instance and ignore the `options` argument.
+ *
+ * @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;
+
+/**
+ * Get the IdentifyKit instance for the configured SDK.
+ *
+ * The IdentifyKit instance is used to authenticate users and read
+ * user data.
+ *
+ * @example
+ * ```javascript
+ * import { configure } from '@monterosa/sdk-core';
+ * import { getIdentify } from '@monterosa/sdk-identify-kit';
+ *
+ * configure({ host: '...', projectId: '...' });
+ *
+ * const identify = getIdentify();
+ * ```
+ *
+ * @remarks
+ * First-call-wins: subsequent calls for the same project return the
+ * cached instance and ignore the `options` argument.
+ *
+ * @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;
+
+/**
+ * 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,
+ *   getCredentials,
+ * } from '@monterosa/sdk-identify-kit';
+ *
+ * configure({ host: '...', projectId: '...' });
+ *
+ * const identify = getIdentify();
+ * const credentials = await getCredentials();
+ *
+ * if (credentials !== null) {
+ *   const userData = await getUserData(identify, credentials);
+ *   console.log('User data:', userData);
+ * }
+ * ```
+ *
+ * @remarks
+ * 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>;
+
+/**
+ * Defines a set of error codes that may be encountered when using the
+ * Identify kit of the Monterosa SDK.
+ *
+ * @example
+ * ```javascript
+ * try {
+ *   // some code that uses the IdentifyKit
+ * } catch (err) {
+ *   if (err.code === IdentifyError.NoCredentials) {
+ *     // handle missing credentials error
+ *   } else {
+ *     // handle other error types
+ *   }
+ * }
+ * ```
+ *
+ * @remarks
+ * - The `IdentifyError` enum provides a convenient way to handle errors
+ *   encountered when using the `IdentifyKit` module. By checking the code
+ *   property of the caught error against the values of the enum, the error
+ *   type can be determined and appropriate action taken.
+ *
+ * - The `IdentifyError` enum is not intended to be instantiated or extended.
+ */
+export declare enum IdentifyError {
+    /**
+     * Indicates an error occurred during the call to the extension API.
+     */
+    ExtensionApiError = "extension_api_error",
+    /**
+     * Indicates the extension required by the IdentifyKit is not set up properly.
+     */
+    ExtensionNotSetup = "extension_not_setup",
+    /**
+     * Indicates the user's authentication credentials are not available
+     * or have expired.
+     */
+    NoCredentials = "no_credentials",
+    /**
+     * Indicates an error occurred in the parent app.
+     */
+    ParentAppError = "parent_app_error",
+    /**
+     * Indicates an unexpected or invalid login state was encountered.
+     */
+    UnexpectedState = "unexpected_state",
+    /**
+     * Indicates there is no parent application to delegate to.
+     */
+    NoParentApplication = "no_parent_application",
+    /**
+     * Indicates a timeout occurred when communicating with the parent app.
+     */
+    ParentTimeoutError = "parent_timeout_error"
+}
+
+/**
+ * Represents an Identify Kit instance. Obtain one via {@link getIdentify}.
+ *
+ * @remarks
+ * This interface is opaque. Interact with it through the standalone
+ * functions such as {@link setCredentials}, {@link clearCredentials},
+ * and {@link getUserData}.
+ */
+export declare interface IdentifyKit extends Emitter {
+    /**
+     * Resolved identity options. `loginPolicy` is not on the instance —
+     * see {@link setLoginPolicy}. Credentials are root-owned, accessed
+     * via {@link getCredentials}.
+     *
+     * @internal
+     */
+    options: IdentifyOptions;
+    /**
+     * @internal
+     */
+    sdk: MonterosaSdk;
+    /**
+     * @internal
+     */
+    signature: Signature | null;
+    /**
+     * @internal
+     */
+    userData: UserData | null;
+    /**
+     * @internal
+     */
+    wasLoggedIn: boolean;
+    state: LoginState;
+    /**
+     * @internal
+     */
+    getUrl(path?: string): Promise<string>;
+}
+
+/**
+ * Resolved configuration options for an `Identify` instance. Public APIs
+ * that accept user-supplied options (such as {@link getIdentify}) take
+ * `Partial<IdentifyOptions>` and apply defaults for any field not
+ * supplied.
+ *
+ * `loginPolicy` is set separately via {@link setLoginPolicy}.
+ */
+export declare interface IdentifyOptions {
+    /**
+     * Authentication strategy. Default: `'email'`.
+     */
+    readonly strategy: string;
+    /**
+     * Identity provider name (e.g. `'aws'` for Cognito).
+     */
+    readonly provider?: string;
+    /**
+     * Identify API version. Default: `1`.
+     */
+    readonly version: number;
+}
+
+export declare type LoginPolicy = 'disabled' | 'auto';
+
+export declare type LoginState = {
+    state: 'logged_out' | 'logged_in' | 'pending' | 'error';
+    error?: string;
+    errorType?: 'login' | 'logout';
+};
+
+/**
+ * Register a callback for updates to the current credentials.
+ *
+ * @example
+ * ```javascript
+ * import { configure } from '@monterosa/sdk-core';
+ * import { onCredentialsUpdated } from '@monterosa/sdk-identify-kit';
+ *
+ * configure({ host: '...', projectId: '...' });
+ *
+ * const unsubscribe = onCredentialsUpdated((credentials) => {
+ *   if (credentials !== null) {
+ *     console.log("Credentials updated:", credentials);
+ *   } else {
+ *     console.log("Credentials cleared.");
+ *   }
+ * });
+ * ```
+ *
+ * @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;
+
+/**
+ * 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
+ * import { configure } from '@monterosa/sdk-core';
+ * import { onLoginRequestedByExperience } from '@monterosa/sdk-identify-kit';
+ *
+ * configure({ host: '...', projectId: '...' });
+ *
+ * const unsubscribe = onLoginRequestedByExperience(() => {
+ *   showLoginForm();
+ * });
+ * ```
+ *
+ * @param callback - Called when a login is requested.
+ * @returns An `Unsubscribe` function.
+ */
+export declare function onLoginRequestedByExperience(callback: () => void): Unsubscribe;
+
+/**
+ * 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 { onLogoutRequestedByExperience } from '@monterosa/sdk-identify-kit';
+ *
+ * configure({ host: '...', projectId: '...' });
+ *
+ * const unsubscribe = onLogoutRequestedByExperience(() => {
+ *   // perform logout from auth service
+ * });
+ * ```
+ *
+ * @param callback - Called when a logout is requested.
+ * @returns An `Unsubscribe` function.
+ */
+export declare function onLogoutRequestedByExperience(callback: () => void): Unsubscribe;
+
+/**
+ * Register a callback for `LoginState` updates on the given identify.
+ *
+ * @example
+ * ```javascript
+ * import { configure } from '@monterosa/sdk-core';
+ * import { getIdentify, onStateUpdated } from '@monterosa/sdk-identify-kit';
+ *
+ * configure({ host: '...', projectId: '...' });
+ *
+ * const identify = getIdentify();
+ *
+ * const unsubscribe = onStateUpdated(identify, (state) => {
+ *   console.log("State updated:", state);
+ * });
+ * ```
+ *
+ * @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;
+
+/**
+ * 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 { requestLogin } from '@monterosa/sdk-identify-kit';
+ *
+ * configure({ host: '...', projectId: '...' });
+ *
+ * try {
+ *   await requestLogin();
+ *   console.log('Login request successful');
+ * } catch (err) {
+ *   console.error('Error requesting login:', err.message)
+ * }
+ * ```
+ *
+ * @returns A Promise that resolves once the login request has been
+ *   delivered.
+ */
+export declare function requestLogin(): Promise<void>;
+
+/**
+ * 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 { configure } from '@monterosa/sdk-core';
+ * import { requestLogout } from '@monterosa/sdk-identify-kit';
+ *
+ * configure({ host: '...', projectId: '...' });
+ *
+ * try {
+ *   await requestLogout();
+ *   console.log('Logout request successful');
+ * } catch (err) {
+ *   console.error('Error requesting logout:', err.message)
+ * }
+ * ```
+ *
+ * @returns A Promise that resolves once the logout request has been
+ *   delivered.
+ */
+export declare function requestLogout(): Promise<void>;
+
+/**
+ * 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 { setCredentials } from '@monterosa/sdk-identify-kit';
+ *
+ * configure({ host: '...', projectId: '...' });
+ *
+ * await setCredentials({ token: 'abc123' });
+ * ```
+ *
+ * @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>;
+
+/**
+ * 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;
+
+/**
+ * A tuple representing a digital signature: `[userId, timestamp, signature]`.
+ *
+ * @example
+ * ```javascript
+ * const signature: Signature = ["user123", 1646956195, "abc123"];
+ * ```
+ */
+export declare type Signature = [userId: string, timestamp: number, signature: string];
+
+/**
+ * A key-value object representing user profile data.
+ *
+ * @remarks
+ * Contains `userId`, `timestamp`, and `signature` alongside any
+ * additional custom properties.
+ *
+ * @example
+ * ```javascript
+ * const userData: UserData = {
+ *   userId: "user123",
+ *   timeStamp: 1646956195,
+ *   signature: "abc123",
+ *   name: "John Doe",
+ *   age: 30,
+ *   email: "john.doe@example.com"
+ * };
+ * ```
+ */
+export declare type UserData = {
+    [key: string]: any;
+};
+
+export { }

package/dist/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.23.0"
+    }
+  ]
+}

package/dist/types.d.ts

@@ -7,7 +7,7 @@
  * More details on the license can be found at https://www.monterosa.co/sdk/license
  */
 import { MonterosaSdk } from '@monterosa/sdk-core';
-import { Emitter, Unsubscribe } from '@monterosa/sdk-util';
+import { Emitter } from '@monterosa/sdk-util';
 /**
  * Represents user authentication credentials.
  *
@@ -62,10 +62,6 @@ export type ResponsePayload<T> = {
     data: T;
     error?: string;
 };
-/**
- * @internal
- */
-export type IdentifyHook = (identify: IdentifyKit) => Unsubscribe;
 export type LoginState = {
     state: 'logged_out' | 'logged_in' | 'pending' | 'error';
     error?: string;
@@ -73,18 +69,18 @@ export type LoginState = {
 };
 export type LoginPolicy = 'disabled' | 'auto';
 /**
- * Configuration options for Identify Kit.
+ * Resolved configuration options for an `Identify` instance. Public APIs
+ * that accept user-supplied options (such as {@link getIdentify}) take
+ * `Partial<IdentifyOptions>` and apply defaults for any field not
+ * supplied.
+ *
+ * `loginPolicy` is set separately via {@link setLoginPolicy}.
  */
 export interface IdentifyOptions {
-    /**
-     * Unique device identifier. Must be persisted and reused across sessions
-     * to avoid duplicate user records.
-     */
-    readonly deviceId?: string;
     /**
      * Authentication strategy. Default: `'email'`.
      */
-    readonly strategy?: string;
+    readonly strategy: string;
     /**
      * Identity provider name (e.g. `'aws'` for Cognito).
      */
@@ -92,8 +88,7 @@ export interface IdentifyOptions {
     /**
      * Identify API version. Default: `1`.
      */
-    readonly version?: number;
-    readonly loginPolicy?: LoginPolicy;
+    readonly version: number;
 }
 /**
  * Represents an Identify Kit instance. Obtain one via {@link getIdentify}.
@@ -105,7 +100,9 @@ export interface IdentifyOptions {
  */
 export interface IdentifyKit extends Emitter {
     /**
-     * The identify options.
+     * Resolved identity options. `loginPolicy` is not on the instance —
+     * see {@link setLoginPolicy}. Credentials are root-owned, accessed
+     * via {@link getCredentials}.
      *
      * @internal
      */
@@ -114,10 +111,6 @@ export interface IdentifyKit extends Emitter {
      * @internal
      */
     sdk: MonterosaSdk;
-    /**
-     * @internal
-     */
-    credentials: Credentials | null;
     /**
      * @internal
      */
@@ -127,15 +120,9 @@ export interface IdentifyKit extends Emitter {
      */
     userData: UserData | null;
     /**
-     * Whether the user should be automatically logged in when connection is
-     * restored. This is true when:
-     * - The user was previously logged in successfully
-     * - Auto-login is enabled
-     * - Credentials are available
-     *
      * @internal
      */
-    shouldLoginOnReconnect: boolean;
+    wasLoggedIn: boolean;
     state: LoginState;
     /**
      * @internal
@@ -166,10 +153,8 @@ export declare enum IdentifyEvent {
     StateUpdated = "state_updated",
     LoginRequested = "login_requested",
     LogoutRequested = "logout_requested",
-    SignatureUpdated = "signature_updated",
-    UserdataUpdated = "userdata_updated",
     CredentialsUpdated = "credentials_updated",
-    EnmasseLogin = "enmasse_login"
+    LoginPolicyUpdated = "login_policy_updated"
 }
 /**
  * Defines a set of error codes that may be encountered when using the
@@ -182,8 +167,6 @@ export declare enum IdentifyEvent {
  * } catch (err) {
  *   if (err.code === IdentifyError.NoCredentials) {
  *     // handle missing credentials error
- *   } else if (err.code === IdentifyError.NotInitialised) {
- *     // handle initialization error
  *   } else {
  *     // handle other error types
  *   }
@@ -212,10 +195,6 @@ export declare enum IdentifyError {
      * or have expired.
      */
     NoCredentials = "no_credentials",
-    /**
-     * Indicates the IdentifyKit has not been initialised properly.
-     */
-    NotInitialised = "not_initialised",
     /**
      * Indicates an error occurred in the parent app.
      */
@@ -240,7 +219,6 @@ export declare const IdentifyErrorMessages: {
     extension_api_error: (error: string) => string;
     extension_not_setup: () => string;
     no_credentials: () => string;
-    not_initialised: () => string;
     parent_app_error: (error: string) => string;
     unexpected_state: (state: string) => string;
     no_parent_application: () => string;
@@ -251,12 +229,7 @@ export declare enum IdentifyAction {
     Logout = "identifyLogout",
     RequestLogin = "identifyRequestLogin",
     RequestLogout = "identifyRequestLogout",
-    GetUserData = "identifyGetUserData",
-    GetSessionSignature = "identifyGetSessionSignature",
+    GetCredentials = "identifyGetCredentials",
     SetCredentials = "identifySetCredentials",
-    ClearCredentials = "identifyClearCredentials",
-    OnStateUpdated = "identifyOnStateUpdated",
-    OnCredentialsUpdated = "identifyOnCredentialsUpdated",
-    OnUserDataUpdated = "identifyOnUserDataUpdated",
-    OnSessionSignatureUpdated = "identifyOnSessionSignatureUpdated"
+    ClearCredentials = "identifyClearCredentials"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monterosa/sdk-identify-kit",
-  "version": "2.0.0-rc.3",
+  "version": "2.0.0-rc.5",
   "description": "Identify Kit for the Monterosa JS SDK",
   "author": "Monterosa Productions Limited <hello@monterosa.co.uk> (https://www.monterosa.co/)",
   "main": "./dist/index.cjs",
@@ -33,12 +33,12 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@monterosa/sdk-connect-kit": "2.0.0-rc.3",
-    "@monterosa/sdk-core": "2.0.0-rc.3",
-    "@monterosa/sdk-interact-interop": "2.0.0-rc.3",
-    "@monterosa/sdk-interact-kit": "2.0.0-rc.3",
-    "@monterosa/sdk-launcher-kit": "2.0.0-rc.3",
-    "@monterosa/sdk-util": "2.0.0-rc.3"
+    "@monterosa/sdk-connect-kit": "2.0.0-rc.5",
+    "@monterosa/sdk-core": "2.0.0-rc.5",
+    "@monterosa/sdk-interact-interop": "2.0.0-rc.5",
+    "@monterosa/sdk-interact-kit": "2.0.0-rc.5",
+    "@monterosa/sdk-launcher-kit": "2.0.0-rc.5",
+    "@monterosa/sdk-util": "2.0.0-rc.5"
   },
   "devDependencies": {
     "@rollup/plugin-json": "^4.1.0",
@@ -59,5 +59,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "d692ad26af0b5ea7cd7b664168bffa069f9ab911"
+  "gitHead": "4f697a9733d36fb689a35b8e1dd6d589a9ae284c"
 }