@schibsted/account-sdk-browser 6.0.0-alpha.1 → 6.0.0-alpha.2

package/package.json

@@ -1,23 +1,38 @@
 {
   "name": "@schibsted/account-sdk-browser",
-  "version": "6.0.0-alpha.1",
+  "version": "6.0.0-alpha.2",
   "description": "Schibsted account SDK for browsers",
-  "main": "index.js",
+  "main": "dist/index.js",
   "type": "module",
   "exports": {
-    ".": "./index.js",
-    "./identity": "./identity.js",
-    "./monetization": "./monetization.js",
-    "./payment": "./payment.js"
+    ".": {
+      "default": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./identity": {
+      "default": "./dist/identity.js",
+      "types": "./dist/identity.d.ts"
+    },
+    "./monetization": {
+      "default": "./dist/monetization.js",
+      "types": "./dist/monetization.d.ts"
+    }
   },
   "scripts": {
-    "clean": "rimraf .cache coverage docs && npm run clean:legacy",
+    "clean": "rimraf .cache coverage docs dist && npm run clean:legacy",
     "clean:legacy": "rimraf es5",
-    "docs": "rimraf docs && jsdoc -c ./jsdoc.conf.json --verbose",
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
+    "docs:build": "typedoc",
+    "docs:watch": "typedoc --watch",
+    "docs:open": "node scripts/open-docs.mjs",
+    "lint": "biome check",
+    "lint:fix": "biome check --fix",
+    "build": "vite build",
+    "typecheck": "tsc --noEmit",
+    "pretest": "npm run build",
     "test": "vitest run",
-    "cover": "vitest run --coverage"
+    "precover": "npm run build",
+    "cover": "vitest run --coverage",
+    "prepublishOnly": "npm run build"
   },
   "author": "",
   "license": "MIT",
@@ -25,19 +40,20 @@
     "tiny-emitter": "^2.1.0"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "^2.1.9",
-    "docdash": "git+https://github.com/torarvid/docdash.git#v0.5.0",
-    "eslint": "^6.8.0",
-    "eslint-plugin-import": "^2.20.2",
-    "jsdoc": "^3.6.11",
-    "jsdom": "^25.0.1",
-    "node-fetch": "^2.6.0",
-    "vitest": "^2.1.9",
-    "whatwg-url": "^8.0.0"
+    "@biomejs/biome": "2.4.15",
+    "@vitest/coverage-v8": "^4.1.7",
+    "jsdom": "^29.1.1",
+    "open": "^11.0.0",
+    "rimraf": "^6.1.3",
+    "typedoc": "^0.28.19",
+    "typedoc-plugin-mdn-links": "^5.1.1",
+    "typescript": "^6.0.3",
+    "unplugin-dts": "^1.0.1",
+    "vite": "^8.0.14",
+    "vitest": "^4.1.7"
   },
   "repository": {
     "type": "git",
     "url": "git://schibsted.ghe.com/user-identity/account-sdk-browser.git"
-  },
-  "typings": "index.d.ts"
+  }
 }

package/src/RESTClient.ts

@@ -0,0 +1,226 @@
+/* Copyright 2024 Schibsted Products & Technology AS. Licensed under the terms of the MIT license.
+ * See LICENSE.md in the project root.
+ */
+
+import { cloneDefined } from './object.js';
+import SDKError from './SDKError.js';
+import { urlMapper } from './url.js';
+import { assert, isFunction, isNonEmptyString, isObject, isStr } from './validate.js';
+
+/**
+ * Converts a series of parameters of various types to a string that's suitable for logging.
+ * @private
+ * @param msg - The values to format; objects are stringified to JSON
+ */
+const logString = (msg: unknown[]): string =>
+    msg.map((m) => (isObject(m) ? JSON.stringify(m, null, 2) : m)).join(' ');
+
+/**
+ * Calls a log function passing a string
+ * @private
+ * @param fn - The log function
+ * @param msg - The values to log
+ */
+const logFn = (fn: Function | undefined, ...msg: unknown[]): void => {
+    if (fn) {
+        fn(logString(msg));
+    }
+};
+
+/**
+ * Encode a string like URLSearchParams would do
+ * @private
+ * @param str - The input
+ */
+function encode(str: string): string {
+    const replace: Record<string, string> = {
+        '!': '%21',
+        "'": '%27',
+        '(': '%28',
+        ')': '%29',
+        '~': '%7E',
+        '%20': '+',
+        '%00': '\x00',
+    };
+    return encodeURIComponent(str).replace(/[!'()~]|%20|%00/g, (match) => replace[match]);
+}
+type FetchFunction = (input: RequestInfo, init?: RequestInit) => Promise<Response>;
+const globalFetch = () => window.fetch && window.fetch.bind(window);
+const noFetch: FetchFunction = () => {
+    throw new SDKError('fetch is not available in this environment');
+};
+
+/**
+ * The value of a single query parameter; `undefined` entries are skipped.
+ */
+type QueryValue = string | number | boolean | undefined;
+
+/**
+ * Query parameters appended to a request URL.
+ */
+type QueryParams = Record<string, QueryValue>;
+
+/**
+ * HTTP method used for a request.
+ */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+
+/**
+ * This class can be used for creating a wrapper around a server and all its endpoints.
+ * Its functionality is extended by {@link JSONPClient}
+ * Creates a client to a REST server. While useful stand-alone, it's also used for some other
+ * types of client that change some functionalities.
+ * @throws {SDKError} - If any of options are invalid
+ * @summary The simplest way to communicate to a REST endpoint without any
+ *          special authentication
+ * @private
+ */
+export class RESTClient {
+    url: URL;
+    defaultParams: QueryParams;
+    log?: Function;
+    fetch: FetchFunction;
+
+    /**
+     * @param options
+     * @param options.serverUrl - The URL to the server eg.
+     * https://login.schibsted.com or a URL key like 'DEV' in combination with {@link envDic}.
+     * @param options.envDic - A dictionary that will be used for looking up
+     * {@link serverUrl} keys. If serverUrl is always a URL, you don't need this.
+     * @param options.fetch - The fetch function to use. It can be native
+     * or a polyfill
+     * @param options.log - A function that will be called with log messages about
+     * request and response
+     * @param options.defaultParams - Query parameters added to every request
+     */
+    constructor({
+        serverUrl = 'PRE',
+        envDic,
+        fetch = globalFetch() ?? noFetch,
+        log,
+        defaultParams = {},
+    }: {
+        serverUrl?: string;
+        envDic?: Record<string, string>;
+        fetch?: FetchFunction;
+        log?: Function;
+        defaultParams?: QueryParams;
+    }) {
+        assert(isObject(defaultParams), `defaultParams should be a non-null object`);
+
+        const mappedUrl = urlMapper(serverUrl, envDic ?? {});
+        const handledServerUrl = mappedUrl.endsWith('/') ? mappedUrl : `${mappedUrl}/`;
+        this.url = new URL(handledServerUrl);
+
+        this.defaultParams = defaultParams;
+
+        if (log) {
+            assert(isFunction(log), `log must be a function but it is ${log}`);
+            this.log = log;
+        }
+
+        this.fetch = fetch;
+    }
+
+    /**
+     * Makes the actual call to the server and deals with headers, data objects and the edge cases.
+     * Please note that this method expects the response to be in JSON format. However, it'll not
+     * parse the response if its code is not in the 200 range.
+     * @param options - An obligatory options object
+     * @param options.method - The HTTP request method, e.g. 'GET' or 'POST'
+     * @param options.pathname - The path to the endpoint like 'api/2/endpoint-name'
+     * @param options.data - Query parameters added to the request URL
+     * @param options.headers - Request headers as a plain key/value map
+     * @param options.useDefaultParams - Should we add the defaultParams to the query?
+     * @param options.fetchOptions - Additional fetch options
+     * @throws {SDKError} - If the call can't be made for whatever reason.
+     */
+    async go({
+        method,
+        headers,
+        pathname,
+        data = {},
+        useDefaultParams = true,
+        fetchOptions = { method, credentials: 'include' },
+    }: {
+        method: HttpMethod;
+        pathname: string;
+        data?: QueryParams;
+        headers?: Record<string, string>;
+        useDefaultParams?: boolean;
+        fetchOptions?: RequestInit;
+    }): Promise<any> {
+        assert(isNonEmptyString(method), `Method must be a non empty string but it is "${method}"`);
+        assert(isNonEmptyString(pathname), `Pathname must be string but it is "${pathname}"`);
+        assert(isObject(data), `data must be a non-null object`);
+
+        fetchOptions.headers = isObject(headers) ? headers : {};
+        const fullUrl = this.makeUrl(pathname, data, useDefaultParams);
+
+        logFn(this.log, 'Request:', method.toUpperCase(), fullUrl);
+        logFn(this.log, 'Request Headers:', fetchOptions.headers);
+        logFn(this.log, 'Request Body:', fetchOptions.body);
+        try {
+            const response = await this.fetch(fullUrl, fetchOptions);
+            logFn(this.log, 'Response Code:', response.status, response.statusText);
+            if (!response.ok) {
+                // status code not in range 200-299
+                throw new SDKError(response.statusText, { code: response.status });
+            }
+            const responseObject = await response.json();
+            logFn(this.log, 'Response Parsed:', responseObject);
+            return responseObject;
+        } catch (err: unknown) {
+            let msg = isStr(err) ? err : 'Unknown RESTClient error';
+            if (isObject(err) && isStr(err.message)) {
+                msg = err.message;
+            }
+            const errorObject = isObject(err) ? err : undefined;
+            throw new SDKError(`Failed to '${method}' '${fullUrl}': '${msg}'`, errorObject);
+        }
+    }
+
+    /**
+     * Creates a url that points to an endpoint in the server
+     * @param pathname - WHATWG pathname ie. 'api/2/endpoint-name'
+     * @param query - Query parameters to serialize into the query string
+     * @param useDefaultParams - Should we add the defaultParams to the query?
+     */
+    makeUrl(pathname = '', query: QueryParams = {}, useDefaultParams = true): string {
+        const handledPathname = pathname.startsWith('/') ? pathname.slice(1) : pathname;
+
+        const url = new URL(handledPathname, this.url);
+        url.search = RESTClient.search(query, useDefaultParams, this.defaultParams);
+        return url.href;
+    }
+
+    /**
+     * Make a GET request
+     * @param pathname - WHATWG pathname ie. 'api/2/endpoint-name'
+     * @param data - Query parameters
+     */
+    get(pathname: string, data?: QueryParams): Promise<any> {
+        return this.go({ method: 'GET', pathname, data });
+    }
+
+    /**
+     * Construct query string for WHATWG urls
+     * @private
+     * @param query - Query parameters to generate the query string from
+     * @param useDefaultParams - Use defaultParams or not
+     * @param defaultParams - Default params
+     */
+    private static search(
+        query: QueryParams,
+        useDefaultParams: boolean,
+        defaultParams: QueryParams,
+    ): string {
+        const params = useDefaultParams ? cloneDefined(defaultParams, query) : cloneDefined(query);
+        return Object.keys(params)
+            .filter((p) => params[p] !== '')
+            .map((p) => `${encode(p)}=${encode(String(params[p]))}`)
+            .join('&');
+    }
+}
+
+export default RESTClient;

package/src/SDKError.ts

@@ -0,0 +1,59 @@
+/* Copyright 2024 Schibsted Products & Technology AS. Licensed under the terms of the MIT license.
+ * See LICENSE.md in the project root.
+ */
+
+/*
+ * Note: this module can't have any internal dependencies because it's used in ./validate which
+ * in turn is used as a dependency to a lot of other modules. Doing so may create a circular
+ * dependency that's hard to debug in Node.
+ */
+
+const STRINGIFY_TYPES = ['boolean', 'number', 'string'];
+
+/**
+ * Custom error class thrown by all SDK methods on failure.
+ *
+ * All rejected promises from API calls reject with an instance of this class.
+ */
+export default class SDKError extends Error {
+    /** HTTP status code from the server error payload;
+     * declared explicitly to allow numeric comparisons without type-casting.
+     */
+    code?: number;
+    /**
+     * Properties copied from the server error object.
+     * @internal
+     */
+    [key: string]: unknown;
+
+    /**
+     * @param message - Human-readable error message
+     * @param errorObject - Optional server error payload. All enumerable properties are
+     * shallow-copied onto this instance.
+     */
+    constructor(message: string, errorObject?: Record<string, unknown>) {
+        super(message);
+        this.name = 'SDKError';
+
+        if (errorObject) {
+            try {
+                Object.assign(this, errorObject);
+            } catch {
+                // silent
+            }
+        }
+    }
+
+    /**
+     * Returns a multi-line string with the error name, message, and any other properties copied
+     * from the server error payload.
+     */
+    toString(): string {
+        const ret = `${this.name}: ${this.message}`;
+        const additionalInfo = Object.keys(this)
+            .filter((key) => key !== 'name' && STRINGIFY_TYPES.includes(typeof this[key]))
+            .map((key) => `    ${key}: ${this[key]}`)
+            .join('\n');
+        return additionalInfo ? `${ret}\n${additionalInfo}` : ret;
+    }
+}

package/src/{cache.js → cache.ts}

@@ -2,45 +2,47 @@
  * See LICENSE.md in the project root.
  */
 
-'use strict';
-
 import SDKError from './SDKError.js';
 
 /**
  * Check whether we are able to use web storage
- * @param {Storage} storeProvider - A function to return a WebStorage instance (either
+ * @param storeProvider - A function to return a WebStorage instance (either
  * `sessionStorage` or `localStorage` from a `Window` object)
  * @private
- * @returns {boolean}
  */
-function webStorageWorks(storeProvider) {
+function webStorageWorks(storeProvider: (() => Storage) | undefined): boolean {
     if (!storeProvider) {
         return false;
     }
     try {
         const store = storeProvider();
-        const randomKey = 'x-x-x-x'.replace(/x/g, () => Math.random());
+        const randomKey = 'x-x-x-x'.replace(/x/g, () => String(Math.random()));
         const testValue = 'TEST-VALUE';
         store.setItem(randomKey, testValue);
         const val = store.getItem(randomKey);
         store.removeItem(randomKey);
-        return (val === testValue);
-    } catch (e) {
+        return val === testValue;
+    } catch {
         return false;
     }
 }
 
 /**
- * Will be used if web storage is available
+ * Cache implementation used when web storage is available. Wraps a `Storage` instance.
  * @private
  */
 class WebStorageCache {
+    store: Storage;
+    get: (key: string) => string | null;
+    set: (key: string, value: string) => void;
+    delete: (key: string) => void;
+
     /**
      * Create web storage cache object
-     * @param {Storage} store - A reference to either `sessionStorage` or `localStorage` from a
+     * @param store - A reference to either `sessionStorage` or `localStorage` from a
      * `Window` object
      */
-    constructor(store) {
+    constructor(store: Storage) {
         this.store = store;
         this.get = (key) => this.store.getItem(key);
         this.set = (key, value) => this.store.setItem(key, value);
@@ -49,35 +51,49 @@ class WebStorageCache {
 }
 
 /**
- * Will be used if session storage is not available
+ * Cache implementation used when web storage is not available. Stores entries in an in-memory object.
  * @private
  */
 class LiteralCache {
+    store: Record<string, string>;
+    get: (key: string) => string | undefined;
+    set: (key: string, value: string) => void;
+    delete: (key: string) => void;
+
     /**
      * Create JS object literal cache object
      */
     constructor() {
         this.store = {};
         this.get = (key) => this.store[key];
-        this.set = (key, value) => this.store[key] = value;
-        this.delete = (key) => delete this.store[key];
+        this.set = (key, value) => {
+            this.store[key] = value;
+        };
+        this.delete = (key) => {
+            delete this.store[key];
+        };
     }
 }
 
-const maxExpiresIn = Math.pow(2, 31) - 1;
+type CacheEntry = { expiresOn: number; value: unknown };
+
+const maxExpiresIn = 2 ** 31 - 1;
 
 /**
  * Cache class that attempts WebStorage (session/local storage), and falls back to JS object literal
  * @private
  */
 export default class Cache {
+    cache: WebStorageCache | LiteralCache;
+    type: string;
+
     /**
-     * @param {Storage} [storeProvider] - A function to return a WebStorage instance (either
+     * @param storeProvider - A function to return a WebStorage instance (either
      * `sessionStorage` or `localStorage` from a `Window` object)
      * @throws {SDKError} - If sessionStorage or localStorage are not accessible
      */
-    constructor(storeProvider) {
-        if (webStorageWorks(storeProvider)) {
+    constructor(storeProvider?: () => Storage) {
+        if (storeProvider && webStorageWorks(storeProvider)) {
             this.cache = new WebStorageCache(storeProvider());
             this.type = 'WebStorage';
         } else {
@@ -88,46 +104,46 @@ export default class Cache {
 
     /**
      * Get a value from cache (checks that the object has not expired)
-     * @param {string} key
+     * @param key
      * @private
-     * @returns {*} - The value if it exists, otherwise null
      */
-    get(key) {
+    get(key: string): unknown {
         /**
          * JSON.parse safe wrapper
-         * @param {string} raw
-         * @returns {*} parsed value or null if failed to parse
+         * @param raw
          */
-        function getObj(raw) {
+        function getObj(raw: string | null | undefined): CacheEntry | null {
+            if (raw == null) {
+                return null;
+            }
             try {
                 return JSON.parse(raw);
-            } catch (e) {
+            } catch {
                 return null;
             }
         }
 
         try {
             const raw = this.cache.get(key);
-            let obj = getObj(raw);
+            const obj = getObj(raw);
             if (obj && Number.isInteger(obj.expiresOn) && obj.expiresOn > Date.now()) {
                 return obj.value;
             }
             this.delete(key);
             return null;
         } catch (e) {
-            throw new SDKError(e);
+            throw new SDKError(String(e));
         }
     }
 
     /**
      * Set a cache entry
-     * @param {string} key
-     * @param {*} value
-     * @param {Number} expiresIn - Value in milliseconds until the entry expires
+     * @param key
+     * @param value
+     * @param expiresIn - Value in milliseconds until the entry expires
      * @private
-     * @returns {void}
      */
-    set(key, value, expiresIn = 0) {
+    set(key: string, value: unknown, expiresIn = 0): void {
         if (expiresIn <= 0) {
             return;
         }
@@ -138,21 +154,20 @@ export default class Cache {
             this.cache.set(key, JSON.stringify({ expiresOn, value }));
             setTimeout(() => this.delete(key), expiresIn);
         } catch (e) {
-            throw new SDKError(e);
+            throw new SDKError(String(e));
         }
     }
 
     /**
      * Delete a cache entry
-     * @param {string} key
+     * @param key
      * @private
-     * @returns {void}
      */
-    delete(key) {
+    delete(key: string): void {
         try {
             this.cache.delete(key);
         } catch (e) {
-            throw new SDKError(e);
+            throw new SDKError(String(e));
         }
     }
 }

package/src/{config.js → config.ts}

@@ -2,8 +2,6 @@
  * See LICENSE.md in the project root.
  */
 
-'use strict';
-
 /*
  * This file declares configs that are essentially part of how the SDK works and interacts with our
  * backend servers.
@@ -18,34 +16,11 @@
  */
 
 /**
- * Core configuration used by the SDK
- * @type {Object}
- * @memberof core
- * @prop {object} ENDPOINTS - URL to some of the services that users of this SDK may interact with
- * @prop {object} ENDPOINTS.SPiD - SPiD endpoints
- * @prop {string} ENDPOINTS.SPiD.LOCAL - Local endpoint (for Identity team)
- * @prop {string} ENDPOINTS.SPiD.DEV - Dev environment (for Identity team)
- * @prop {string} ENDPOINTS.SPiD.PRE - Staging environment
- * @prop {string} ENDPOINTS.SPiD.PRO - Production environment Sweden
- * @prop {string} ENDPOINTS.SPiD.PRO_NO - Production environment Norway
- * @prop {string} ENDPOINTS.SPiD.PRO_FI - Production environment Finland
- * @prop {string} ENDPOINTS.SPiD.PRO_DK - Production environment Denmark
- * @prop {object} ENDPOINTS.BFF - Endpoints used with new GDPR-compliant web flows
- * @prop {string} ENDPOINTS.BFF.LOCAL - Local endpoint (for Identity team)
- * @prop {string} ENDPOINTS.BFF.DEV - Dev environment (for Identity team)
- * @prop {string} ENDPOINTS.BFF.PRE - Staging environment
- * @prop {string} ENDPOINTS.BFF.PRO - Production environment Sweden
- * @prop {string} ENDPOINTS.BFF.PRO_NO - Production environment Norway
- * @prop {string} ENDPOINTS.BFF.PRO_FI - Production environment Finland
- * @prop {string} ENDPOINTS.BFF.PRO_DK - Production environment Denmark
- * @prop {object} ENDPOINTS.SESSION_SERVICE - Endpoints to check global user session data
- * @prop {string} ENDPOINTS.SESSION_SERVICE.LOCAL - Local endpoint (for Identity team)
- * @prop {string} ENDPOINTS.SESSION_SERVICE.DEV - Dev environment (for Identity team)
- * @prop {string} ENDPOINTS.SESSION_SERVICE.PRE - Staging environment
- * @prop {string} ENDPOINTS.SESSION_SERVICE.PRO - Production environment Sweden
- * @prop {string} ENDPOINTS.SESSION_SERVICE.PRO_NO - Production environment Norway
- * @prop {string} ENDPOINTS.SESSION_SERVICE.PRO_FI - Production environment Finland
- * @prop {string} ENDPOINTS.SESSION_SERVICE.PRO_DK - Production environment Denmark
+ * Core configuration used by the SDK.
+ * - `ENDPOINTS.SPiD` — SPiD endpoints per environment
+ * - `ENDPOINTS.BFF` — Endpoints used with new GDPR-compliant web flows
+ * - `ENDPOINTS.SESSION_SERVICE` — Endpoints to check global user session data
+ *
  */
 const config = {
     ENDPOINTS: {
@@ -85,8 +60,8 @@ const config = {
         PRO_NO: 'spid.no',
         PRO_FI: 'schibsted.fi',
         PRO_DK: 'schibsted.dk',
-    }
-};
+    },
+} as const;
 
 export default config;
 export const ENDPOINTS = config.ENDPOINTS;

package/src/global-registry.ts

@@ -0,0 +1,39 @@
+import './globals.js';
+
+/**
+ * Names of the SDK instance properties that can be registered on the global {@link Window} object.
+ */
+type Property = 'schIdentity' | 'schMonetization';
+
+/**
+ * Registers an SDK instance on the global {@link Window} object's given property and dispatches a ready event.
+ *
+ * The dispatched event is a {@link CustomEvent} fired on `global` (i.e. `window`) with:
+ * - name: `${property}:ready` (e.g. `"schIdentity:ready"` or `"schMonetization:ready"`)
+ * - `detail.instance`: the registered SDK instance
+ *
+ * @typeParam T - Constrained to {@link Property}; inferred from the `property` argument.
+ * @param global - The `Window` object to register on.
+ * @param property - The window property name to assign the instance to, 'schIdentity' or 'schMonetization'.
+ * @param instance - The SDK instance to register. Must be non-nullable.
+ *
+ * @example
+ * registerAndDispatchInGlobal(window, 'schIdentity', identityInstance);
+ * / window.schIdentity === identityInstance
+ * / CustomEvent 'schIdentity:ready' has been dispatched on window
+ */
+
+export const registerAndDispatchInGlobal = <T extends Property>(
+    global: Window,
+    property: T,
+    instance: NonNullable<Window[T]>,
+): void => {
+    if (!global[property]) {
+        global[property] = instance;
+    }
+
+    global.dispatchEvent(
+        //TODO -> https://schibsted.ghe.com/connect/team/issues/645
+        new CustomEvent(`${property}:ready`, { detail: { instance: global[property] } }),
+    );
+};

package/src/globals.ts

@@ -0,0 +1,10 @@
+import type { Identity } from './identity.js';
+import type { Monetization } from './monetization.js';
+
+declare global {
+    interface Window {
+        schIdentity?: Identity;
+        schMonetization?: Monetization;
+        SPiD?: { Talk?: { response?: (callbackName: string, data: unknown) => unknown } };
+    }
+}