@schibsted/account-sdk-browser 6.0.0-alpha.5 → 6.0.0-alpha.7

package/dist/sdk-error.d.ts

@@ -2,6 +2,8 @@
  * Custom error class thrown by all SDK methods on failure.
  *
  * All rejected promises from API calls reject with an instance of this class.
+ *
+ * @group Errors
  */
 export default class SDKError extends Error {
     /** HTTP status code from the server error payload;

package/dist/types/account.d.ts

@@ -1,5 +1,10 @@
 import { AccountBaseConfig, LogFunction } from './common';
 import { IdentityBeforeRedirectCallback, VarnishCookieOptions } from './identity';
+/**
+ * Configuration used to create an {@link Account} instance.
+ *
+ * @group Configuration
+ */
 export type AccountConfig = AccountBaseConfig & {
     /** Receives debug log information. If not set, no logging will be done. */
     log?: LogFunction;
@@ -8,14 +13,31 @@ export type AccountConfig = AccountBaseConfig & {
     /** Optional Varnish cookie setup applied during Account initialization. */
     varnish?: VarnishCookieOptions;
 };
+type LoginEventDetail = {
+    url: string;
+    method: 'popup' | 'default';
+};
+type LogoutEventDetail = {
+    url: string;
+};
+export type AccountEventMap = {
+    /** Emitted with the login URL and method when `login()` initiates a login flow. */
+    login: CustomEvent<LoginEventDetail>;
+    /** Emitted with the logout URL when `logout()` is called. */
+    logout: CustomEvent<LogoutEventDetail>;
+    /** Emitted when the simplified login widget is displayed. */
+    simplifiedLoginOpened: Event;
+    /** Emitted when the simplified login widget is closed. */
+    simplifiedLoginCancelled: Event;
+};
+/** Account event names emitted by the SDK. */
+export type AccountEventName = keyof AccountEventMap;
 /**
- * Identity events emitted by the SDK.
+ * Native event listener used by Account event subscriptions.
+ *
+ * Payload-bearing events are `CustomEvent` instances and expose their payload through `detail`.
  *
- * - `login`: emitted when `hasSession()` resolves with a logged-in user payload.
- * - `logout`: emitted when a previously logged-in user is no longer logged in, or when
- *   `logout()` is called.
- * - `simplifiedLoginOpened`: emitted when the simplified login widget is displayed.
- * - `simplifiedLoginCancelled`: emitted when the simplified login widget is closed.
+ * @group Events
  */
-export type AccountEventName = 'login' | 'logout' | 'simplifiedLoginOpened' | 'simplifiedLoginCancelled';
-export type AccountEventHandler = (...args: unknown[]) => void;
+export type AccountEventListener<EventName extends AccountEventName = AccountEventName> = (event: AccountEventMap[EventName]) => void;
+export {};

package/dist/types/common.d.ts

@@ -1,13 +1,19 @@
 /**
  * Log callback used by the SDK for debug output.
  * Receives a pre-formatted log line.
- * @internal
+ *
+ * @group Configuration
  */
 export type LogFunction = (message: string) => void;
 /**
  * Supported Schibsted account environment keys.
+ *
+ * @group Configuration
  */
 export type AccountEnvironment = 'LOCAL' | 'DEV' | 'PRE' | 'PRO' | 'PRO_NO' | 'PRO_FI' | 'PRO_DK';
+/**
+ * Shared Account configuration fields.
+ */
 export type AccountBaseConfig = {
     /** Mandatory client id. Example: "1234567890abcdef12345678" */
     clientId: string;

package/dist/types/login.d.ts

@@ -1,5 +1,7 @@
 /**
- * Options accepted by {@link Identity#login} and related login URL helpers.
+ * Options accepted by {@link Account#login} and related login URL helpers.
+ *
+ * @group Login & Widget
  */
 export type LoginOptions = {
     /**
@@ -8,14 +10,11 @@ export type LoginOptions = {
      */
     state: string;
     /**
-     * Authentication Context Class Reference Values. If omitted, the user will be asked to
-     * authenticate using username+password. For 2FA (Two-Factor Authentication) possible values
-     * are `sms`, `otp` (one time password), `password` (will force password confirmation, even if
-     * user is already logged in), `eid`. Those values might be mixed as space-separated string.
-     * To make sure that user has authenticated with 2FA you need to verify AMR (Authentication
-     * Methods References) claim in ID token. Might also be used to ensure additional acr
-     * (sms, otp, eid) for already logged in users. Supported value is also 'otp-email' means one
-     * time password using email.
+     * Authentication Context Class Reference values. If omitted, the default account flow is used.
+     * Supported values include `password`, `otp`, `sms`, `otp-email`, `eid`, `eid-no`, `eid-se`,
+     * `eid-fi`, and `eid-dk`. Values other than `otp-email` may be combined as a space-separated
+     * string. Verify the AMR (Authentication Methods References) claim in the ID token on your
+     * backend if you need to enforce a completed authentication method.
      */
     acrValues?: 'password' | 'otp' | 'sms' | 'eid-dk' | 'eid-no' | 'eid-se' | 'eid-fi' | 'eid' | 'otp-email' | (string & {});
     /**
@@ -70,6 +69,8 @@ export type LoginOptions = {
 /**
  * Identical to {@link LoginOptions} except that `state` may also be a (possibly async) function;
  * all other fields reuse the `LoginOptions` documentation.
+ *
+ * @group Login & Widget
  */
 export type SimplifiedLoginWidgetLoginOptions = Omit<LoginOptions, 'state'> & {
     /**
@@ -80,9 +81,11 @@ export type SimplifiedLoginWidgetLoginOptions = Omit<LoginOptions, 'state'> & {
 };
 /**
  * Minimal user information used by the simplified login widget flow.
+ *
+ * @group Login & Widget
  */
 export type SimplifiedLoginData = {
-    /** Deprecated: User UUID, to be be used as `loginHint` for {@link Identity#login} */
+    /** Deprecated: User UUID used as `loginHint` for {@link Account#login}. */
     identifier: string;
     /** Human-readable user identifier */
     display_text: string;
@@ -92,7 +95,9 @@ export type SimplifiedLoginData = {
     provider_id?: string;
 };
 /**
- * Configuration options for {@link Identity#showSimplifiedLoginWidget}.
+ * Configuration options for {@link Account#showSimplifiedLoginWidget}.
+ *
+ * @group Login & Widget
  */
 export type SimplifiedLoginWidgetOptions = {
     /** expected encoding of simplified login widget. Could be utf-8 (default), iso-8859-1 or iso-8859-15 */

package/dist/types/monetization.d.ts

@@ -3,16 +3,21 @@ import { SessionUserId } from './session';
 /**
  * Result returned by the Session Service `/hasAccess` endpoint, describing whether the user
  * is entitled to a requested set of products/features.
- * @internal
+ *
+ * @group Access Checks
  */
 export interface HasAccessResult {
     /** Whether the user is entitled to at least one of the requested products/features. */
     entitled: boolean;
     /** How long this result stays valid, in seconds, before the cache entry expires. */
     ttl: number;
+    /** Feature ids the user is allowed to access. */
     allowedFeatures: string[];
+    /** User id the access result belongs to. */
     userId: SessionUserId;
+    /** Globally unique user id the access result belongs to. */
     uuid: string;
+    /** Signed response payload. */
     sig: string;
 }
 /**

package/dist/types/session.d.ts

@@ -3,14 +3,18 @@
  *
  * Session Service historically returned numeric ids, while some integrations and tests use
  * string ids. SDK convenience methods normalize this where they promise a string.
+ *
+ * @group Session
  */
 export type SessionUserId = number | string;
 /**
- * Successful response returned from {@link Identity#hasSession}.
+ * Successful response returned from {@link Account#hasSession}.
  *
  * `result` means the has-session call itself succeeded. `result: true` means the user is
  * connected to the merchant; `result: false` means a session may exist, but the user is not
  * connected to this client.
+ *
+ * @group Session
  */
 export type SessionSuccessResponse = {
     /** Response status code. Example: 200. */
@@ -24,7 +28,7 @@ export type SessionSuccessResponse = {
      * merchants connected to this user.
      */
     result: boolean;
-    /** Connection status string. Deprecated; use `Identity.isConnected()`. Example: 'connected'. */
+    /** Connection status string. Deprecated; use `Account.isConnected()`. Example: 'connected'. */
     userStatus?: string;
     /** Cookie base domain used as the `SP_ID` cookie domain fallback. Example: 'spid.no'. */
     baseDomain?: string;
@@ -69,12 +73,16 @@ export type SessionSuccessResponse = {
 };
 /**
  * Successful has-session response for a user connected to the merchant.
+ *
+ * @group Session
  */
 export type ConnectedSessionResponse = SessionSuccessResponse & {
     result: true;
 };
 /**
  * Connected session response that also carries a usable user id.
+ *
+ * @group Session
  */
 export type ConnectedSessionWithUserIdResponse = ConnectedSessionResponse & {
     userId: SessionUserId;
@@ -84,6 +92,8 @@ export type ConnectedSessionWithUserIdResponse = ConnectedSessionResponse & {
  *
  * API and network failures usually reject with {@link SDKError}; this shape represents a failure
  * payload when one is returned by Session Service and reaches the has-session flow.
+ *
+ * @group Session
  */
 export type SessionFailureResponse = {
     /** Failure payload returned by Session Service. Usually an object, but tests also pass strings. */
@@ -110,15 +120,30 @@ export type SessionFailureResponse = {
  *
  * This intentionally includes `{}`. Historically `hasSession()` could resolve an empty object or
  * other object payloads that callers inspected themselves, so the SDK preserves those responses.
+ *
+ * @group Session
  */
 export type UnrecognizedSessionResponse = object;
+/**
+ * Redirect URL returned by `hasSession()` when Session Service needs a full-page session refresh.
+ *
+ * @group Session
+ */
 export type RedirectSessionResponse = string;
 export type SessionObjectResponse = SessionSuccessResponse | SessionFailureResponse | UnrecognizedSessionResponse;
 export type RedirectSessionPayload = {
     redirectURL: string;
 };
+/**
+ * Internal shape returned by `normalizeSessionResponse()` before `hasSession()` post-processing.
+ *
+ * It includes regular Session Service object responses and redirect responses used for full-page
+ * session refresh.
+ */
 export type NormalizedSessionPayload = SessionObjectResponse | RedirectSessionPayload;
 /**
- * Public response union returned from {@link Identity#hasSession}.
+ * Public response union returned from {@link Account#hasSession}.
+ *
+ * @group Session
  */
 export type SessionResponse = SessionSuccessResponse | SessionFailureResponse | UnrecognizedSessionResponse | RedirectSessionResponse;

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-declare const version = "6.0.0-alpha.5";
+declare const version = "6.0.0-alpha.7";
 export default version;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schibsted/account-sdk-browser",
-  "version": "6.0.0-alpha.5",
+  "version": "6.0.0-alpha.7",
   "description": "Schibsted account SDK for browsers",
   "main": "dist/index.js",
   "type": "module",
@@ -28,9 +28,6 @@
   },
   "author": "",
   "license": "MIT",
-  "dependencies": {
-    "tiny-emitter": "^2.1.0"
-  },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",
     "@vitest/coverage-v8": "^4.1.7",

package/src/account-sdk.ts

@@ -17,10 +17,28 @@ const createUnavailableError = (): Error =>
 const createTimeoutError = (): Error =>
     new Error(`Schibsted Account SDK was not initialized within ${GET_ACCOUNT_SDK_TIMEOUT_MS} ms`);
 
+/**
+ * Creates and registers the single Account SDK instance for the current browser window.
+ *
+ * The created instance is stored on `window.schAccount` and the SDK emits
+ * `schAccount:ready` with the instance in `event.detail.instance`.
+ *
+ * @param config - Client, redirect, environment, and Session Service configuration.
+ * @throws {SDKError} If the SDK cannot run in the current browser context, if an Account instance
+ * has already been initialized, or if configuration validation fails.
+ * @group Core API
+ */
 export function createAccountSdk(config: AccountConfig): Account {
     return new Account(config);
 }
 
+/**
+ * Resolves the Account SDK instance registered by `createAccountSdk()`.
+ *
+ * If the instance already exists, the promise resolves immediately. Otherwise it waits for
+ * `schAccount:ready` and rejects if initialization does not happen within the SDK timeout.
+ * @group Core API
+ */
 export function getAccountSdk(): Promise<Account> {
     const browserWindow = resolveBrowserWindow();
 

package/src/account.ts

@@ -6,7 +6,7 @@ import Identity from './identity.js';
 import Monetization from './monetization.js';
 import { resolveBrowserWindow } from './resolve-browser-window.js';
 import SDKError from './sdk-error.js';
-import type { AccountConfig, AccountEventHandler, AccountEventName } from './types/account.js';
+import type { AccountConfig, AccountEventListener, AccountEventName } from './types/account.js';
 import type {
     LoginOptions,
     SimplifiedLoginData,
@@ -18,6 +18,12 @@ import type { ConnectedSessionResponse, SessionResponse, SessionUserId } from '.
 
 /**
  * Unified client-side interface for a configured Schibsted Account integration.
+ *
+ * Create an instance with `createAccountSdk()` unless you explicitly need to construct it
+ * yourself. The instance coordinates identity, login, session, and access-check features for one
+ * configured client.
+ *
+ * @group Core API
  */
 export class Account {
     #identity: Identity;
@@ -64,58 +70,150 @@ export class Account {
         );
     }
 
+    /**
+     * Queries Session Service and returns the current browser session state.
+     *
+     * This call may trigger a full-page session refresh redirect. Configure
+     * `callbackBeforeRedirect` if your app needs to persist state before that navigation.
+     *
+     * @throws {SDKError} If the Session Service call fails.
+     */
     hasSession(): Promise<SessionResponse> {
         return this.#identity.hasSession();
     }
 
+    /**
+     * Checks whether the browser currently has a Schibsted Account session.
+     *
+     * Returns `false` instead of throwing when the session lookup fails.
+     */
     isLoggedIn(): Promise<boolean> {
         return this.#identity.isLoggedIn();
     }
 
+    /**
+     * Checks whether the current user is connected to the configured client.
+     *
+     * A user can be logged in to Schibsted Account without being connected to your client, for
+     * example before accepting required terms.
+     */
     isConnected(): Promise<boolean> {
         return this.#identity.isConnected();
     }
 
+    /**
+     * Returns the connected user session data.
+     *
+     * @throws {SDKError} If the user is not connected to the configured client.
+     */
     getUser(): Promise<ConnectedSessionResponse> {
         return this.#identity.getUser();
     }
 
+    /**
+     * Returns the realm-specific Schibsted Account user id as a string.
+     *
+     * Use `getUserUuid()` when you need the globally unique user id.
+     *
+     * @throws {SDKError} If the user is not connected to the configured client.
+     */
     getUserId(): Promise<string> {
         return this.#identity.getUserId();
     }
 
+    /**
+     * Returns the globally unique user id from the current session.
+     *
+     * @throws {SDKError} If the user is not connected to the configured client.
+     */
     getUserUuid(): Promise<string> {
         return this.#identity.getUserUuid();
     }
 
+    /**
+     * Returns the user SDRN from the current session.
+     *
+     * @throws {SDKError} If the SDRN is missing from the session response.
+     */
     getUserSDRN(): Promise<string> {
         return this.#identity.getUserSDRN();
     }
 
+    /**
+     * Returns minimal user context for simplified login prompts.
+     *
+     * Returns `null` if the global account session cannot be read.
+     */
     getUserContextData(): Promise<SimplifiedLoginData | null> {
         return this.#identity.getUserContextData();
     }
 
+    /**
+     * Returns the Varnish `sp_id` value from the current session when present.
+     */
     getSpId(): Promise<string | null> {
         return this.#identity.getSpId();
     }
 
+    /**
+     * Starts the login flow with either a full-page redirect or a popup.
+     *
+     * Call this from a user gesture when `preferPopup` is enabled, otherwise browser popup blockers
+     * may block the popup and the SDK will fall back to redirect navigation.
+     *
+     * @param options - Login URL parameters.
+     * @returns A popup window reference when a popup is opened; otherwise `null`.
+     */
     login(options: LoginOptions): Window | null {
         return this.#identity.login(options);
     }
 
+    /**
+     * Logs the user out from the brand Session Service session and redirects the browser.
+     *
+     * @param redirectUri - Where Session Service should redirect the browser after logout.
+     */
     logout(redirectUri?: string): void {
         this.#identity.logout(redirectUri);
     }
 
+    /**
+     * Builds the login URL without navigating the browser.
+     *
+     * @param options - Login URL parameters.
+     */
     loginUrl(options: LoginOptions): string {
         return this.#identity.loginUrl(options);
     }
 
+    /**
+     * Builds the logout URL without navigating the browser.
+     *
+     * @param redirectUri - Where Session Service should redirect the browser after logout.
+     */
+    logoutUrl(redirectUri?: string): string {
+        return this.#identity.logoutUrl(redirectUri);
+    }
+
+    /**
+     * Builds the Schibsted Account profile page URL.
+     *
+     * @param redirectUri - Where the account page should redirect the browser afterwards.
+     */
     accountUrl(redirectUri?: string): string {
         return this.#identity.accountUrl(redirectUri);
     }
 
+    /**
+     * Loads and displays the simplified login widget when user context is available.
+     *
+     * Your application decides how often to call this method. The `state` field in `loginParams`
+     * may be a string or a function that resolves to a string.
+     * Widget open and cancel events can be observed with `on()`.
+     *
+     * @returns `true` when the widget was displayed.
+     * @throws {SDKError} If user context data is missing or the widget script cannot be loaded.
+     */
     showSimplifiedLoginWidget(
         loginParams: SimplifiedLoginWidgetLoginOptions,
         options?: SimplifiedLoginWidgetOptions,
@@ -123,26 +221,78 @@ export class Account {
         return this.#identity.showSimplifiedLoginWidget(loginParams, options);
     }
 
+    /**
+     * Enables or disables caching for subsequent session lookups.
+     *
+     * Changing this setting does not remove an existing cached session.
+     */
+    setSessionCachingEnabled(enabled: boolean): void {
+        this.#identity.setSessionCachingEnabled(enabled);
+    }
+
+    /**
+     * Removes the cached Session Service user session response.
+     */
     clearCachedUserSession(): void {
         this.#identity.clearCachedUserSession();
     }
 
+    /**
+     * Checks whether a user has access to any of the requested products or features.
+     *
+     * Results are cached according to the TTL returned by Session Service.
+     *
+     * @param productIds - Product or feature ids to check.
+     * @param userId - Current user id, usually from `getUserId()`.
+     * @returns Access data, or `null` when the user is not entitled.
+     * @throws {SDKError} If `sessionDomain` is missing, input is invalid, or the request fails.
+     */
     hasAccess(productIds: string[], userId: SessionUserId): Promise<HasAccessResult | null> {
         return this.#monetization.hasAccess(productIds, userId);
     }
 
+    /**
+     * Removes a cached access-check result.
+     *
+     * @param productIds - Product or feature ids used for the cached lookup.
+     * @param userId - User id used for the cached lookup.
+     */
     clearCachedAccessResult(productIds: string[], userId: SessionUserId): void {
         this.#monetization.clearCachedAccessResult(productIds, userId);
     }
 
-    on(event: AccountEventName, callback: AccountEventHandler, ctx?: unknown): this {
-        this.#identity.on(event, callback, ctx);
+    /**
+     * Subscribes to Account events.
+     *
+     * Supported event names are defined by {@link AccountEventName}.
+     *
+     * @param event - Event name.
+     * @param listener - Listener that receives an `Event` or `CustomEvent`.
+     */
+    on<EventName extends AccountEventName>(
+        event: EventName,
+        listener: AccountEventListener<EventName>,
+    ): this;
+    on(event: AccountEventName, listener: EventListener): this {
+        this.#identity.addEventListener(event, listener);
 
         return this;
     }
 
-    off(event: AccountEventName, callback?: AccountEventHandler): this {
-        this.#identity.off(event, callback);
+    /**
+     * Unsubscribes from Account events.
+     *
+     * Supported event names are defined by {@link AccountEventName}.
+     *
+     * @param event - Event name.
+     * @param listener - Listener to remove.
+     */
+    off<EventName extends AccountEventName>(
+        event: EventName,
+        listener: AccountEventListener<EventName>,
+    ): this;
+    off(event: AccountEventName, listener: EventListener): this {
+        this.#identity.removeEventListener(event, listener);
 
         return this;
     }