@monterosa/sdk-identify-kit 2.0.0-rc.4 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monterosa/sdk-identify-kit",
-  "version": "2.0.0-rc.4",
+  "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.4",
-    "@monterosa/sdk-core": "2.0.0-rc.4",
-    "@monterosa/sdk-interact-interop": "2.0.0-rc.4",
-    "@monterosa/sdk-interact-kit": "2.0.0-rc.4",
-    "@monterosa/sdk-launcher-kit": "2.0.0-rc.4",
-    "@monterosa/sdk-util": "2.0.0-rc.4"
+    "@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": "1c7b10a4da9d2b85a20a67cc4dac61c7aa8e692d"
+  "gitHead": "4f697a9733d36fb689a35b8e1dd6d589a9ae284c"
 }