@schibsted/account-sdk-browser 5.2.3 → 5.2.6

package/LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2024 Schibsted Products & Technology AS
+Copyright (c) 2026 Schibsted Products & Technology AS
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
 associated documentation files (the "Software"), to deal in the Software without restriction,

package/README.md

@@ -61,23 +61,38 @@ You can use that code as inspiration or just fork and play with it. The account-
 module is used for authenticating the user with Schibsted account. Take a look at how the SDK is
 initialized.
 
-When a user wants to log in to your site, you direct them to a UI flow hosted by **Schibsted Account**. 
-We authenticate the user and redirect them back to your site. This final redirect back to your site is performed in accordance with the OAuth2 specification. 
+When a user wants to log in to your site, you direct them to a UI flow hosted by **Schibsted Account**.
+We authenticate the user and redirect them back to your site. This final redirect back to your site is performed in accordance with the OAuth2 specification.
 This means we pass a `code` in the query string of that redirect URI.
-You can use that `code` on your site's backend, along with your client credentials (client ID and secret), to obtain an *Access Token* (AT) and a *Refresh Token* (RT). 
-You should not send the AT (and **never** the RT!) to the browser. Instead, keep them on the server side and associate them with the specific user session. 
+You can use that `code` on your site's backend, along with your client credentials (client ID and secret), to obtain an *Access Token* (AT) and a *Refresh Token* (RT).
+You should not send the AT (and **never** the RT!) to the browser. Instead, keep them on the server side and associate them with the specific user session.
 This allows you to call Schibsted Account APIs on behalf of that user.
 
-
 ## Events
 
-The SDK fires events when something we deem interesting is happening. For example the
+The SDK fires events on the instances when something we deem interesting is happening. For example the
 [Identity](https://schibsted.github.io/account-sdk-browser/Identity.html) class
 emits some events when the user is logged in or logged out. This SDK uses a familar interface that's
 very similar to Node's [EventEmitter](https://nodejs.org/api/events.html). The most important
 methods are `.on(eventName, listener)` (to subscribe to an event) and `.off(eventName, listener)`
 (to unsubscribe to an event).
 
+The SDK also emits global events on the `window` when a new instance is created.
+Events are emitted for:
+
+| Class        | event name              |
+| ------------ | ----------------------- |
+| Identity     | `schIdentity:ready`     |
+| Monetization | `schMonetization:ready` |
+| Payment      | `schPayment:ready`      |
+
+```js
+window.addEventListener('schIdentity:ready', e => {
+    // The event contains the initialized instance (e.detail.instance);
+}
+
+```
+
 ## Identity
 
 Let's start with a bit of example code:
@@ -85,29 +100,29 @@ Let's start with a bit of example code:
 #### Example
 
 ```javascript
-import { Identity } from '@schibsted/account-sdk-browser'
+import { Identity } from '@schibsted/account-sdk-browser';
 
 const identity = new Identity({
     clientId: '56e9a5d1eee0000000000000',
     redirectUri: 'https://awesomenews.site', // ensure it's listed in selfservice
     env: 'PRE', // Schibsted account env. A url or a special key: 'PRE', 'PRO', 'PRO_NO', 'PRO_FI' or 'PRO_DK'
     sessionDomain: 'https://id.awesomenews.site', // client-configured session-service domain
-})
+});
 
 async function whenSiteLoaded() {
-    const loginContainer = document.getElementById('login-container')
+    const loginContainer = document.getElementById('login-container');
     if (await identity.isLoggedIn()) {
-        const user = await identity.getUser()
-        const span = document.createElement('span')
-        span.textContent = `Hello ${user.givenName}`
-        loginContainer.appendChild(span)
+        const user = await identity.getUser();
+        const span = document.createElement('span');
+        span.textContent = `Hello ${user.givenName}`;
+        loginContainer.appendChild(span);
     } else {
-        loginContainer.innerHTML = '<button class="login-button">Log in</button>'
+        loginContainer.innerHTML = '<button class="login-button">Log in</button>';
     }
 }
 
 function userClicksLogIn() {
-    identity.login({ state: 'some-random-string-1234-foobar-wonky-pig' })
+    identity.login({ state: 'some-random-string-1234-foobar-wonky-pig' });
 }
 ```
 
@@ -126,10 +141,11 @@ with the auth `code` parameter.
 
 It is recommended that you provide a unique identifier as part of the state, to prevent CSRF
 attacks. For example this can be accomplished by:
+
 1. Your backend generates random token: `1234abcd`, saves it in some tokenCache, and forwards to
    your browser frontend
 1. Your frontend calls `Identity.login` with `state = base64Urlencode({ token: '1234abcd', article:
-   '1234', ... })`
+'1234', ... })`
 1. When auth flow completes, the user is redirected back to your site. Then, your backend sees the
    query parameters `code` (which it can exchange for OAuth tokens for the user) and `state`
 1. Your backend can do `decodedState = base64Urldecode(query.state)` and then verify that its
@@ -143,21 +159,22 @@ Although Schibsted account abstracts away the details of how the users sign up o
 mentioning that your end users have a few ways to log in:
 
 * Username & password: pretty self-explanatory; users register using an email address and a
-  self-chosen password
-* Passwordless - email: here, the users enter their email address and receive a one-time code that
-  they can use to log in
-* Multifactor authentication: first client indicates which methods should be preferred, later these
-  will be included (if fulfilled) in `AMR` claim of IDToken
+    self-chosen password
+*  Passwordless - email: here, the users enter their email address and receive a one-time code that
+    they can use to log in
+*  Multifactor authentication: first client indicates which methods should be preferred, later these
+    will be included (if fulfilled) in `AMR` claim of IDToken
 
 The default is username & password. If you wish to use one of the passwordless login methods, the
 `login()` function takes an optional parameter called `acrValues` (Authentication Context Class Reference).
 The `acrValues` parameter with multifactor authentication can take following values:
- - `eid` - authentication using BankID (for DEV and PRE environments you can choose between country specific solution by specifying `eid-no` or `eid-se` instead)
- - `otp-email` - passwordless authentication using code sent to registered email
- - `password` - force password authentication (even if user is already logged in)
- - `otp` - authentication using registered one time code generator (https://tools.ietf.org/html/rfc6238)
- - `sms` - authentication using SMS code sent to phone number
- - `password otp sms` - those authentication methods might be combined
+
+*  `eid` - authentication using BankID (for DEV and PRE environments you can choose between country specific solution by specifying `eid-no` or `eid-se` instead)
+*  `otp-email` - passwordless authentication using code sent to registered email
+*  `password` - force password authentication (even if user is already logged in)
+*  `otp` - authentication using registered one time code generator (https://tools.ietf.org/html/rfc6238)
+*  `sms` - authentication using SMS code sent to phone number
+*  `password otp sms` - those authentication methods might be combined
 
 The classic way to authenticate a user, is to send them from your site to the Schibsted account
 domain, let the user authenticate there, and then have us redirect them back to your site. If you
@@ -176,12 +193,13 @@ Schibsted account relies on browser cookies to determine whether a user is recog
 The SDK provides functions that can be used to check if the user that's visiting your site is
 already a Schibsted user or not.
 
-* [Identity#isLoggedIn](https://schibsted.github.io/account-sdk-browser/Identity.html#isLoggedIn)
-  tells you if the user that is visiting your site is already logged in to Schibsted account or not.
-* [Identity#isConnected](https://schibsted.github.io/account-sdk-browser/Identity.html#isConnected)
-  tells you if the user is connected to your client. A user might have `isLoggedIn=true` and at the
-  same time `isConnected=false` if they have logged in to Schibsted account, but not accepted terms
-  and privacy policy for your site.
+*  [Identity#isLoggedIn](https://schibsted.github.io/account-sdk-browser/Identity.html#isLoggedIn)
+    tells you if the user that is visiting your site is already logged in to Schibsted account or not.
+
+*  [Identity#isConnected](https://schibsted.github.io/account-sdk-browser/Identity.html#isConnected)
+    tells you if the user is connected to your client. A user might have `isLoggedIn=true` and at the
+    same time `isConnected=false` if they have logged in to Schibsted account, but not accepted terms
+    and privacy policy for your site.
 
 If you've lately changed your terms & conditions, maybe the user still hasn't accepted them. In that
 case they are considered *not connected*. In that case, if they click "Log in" from your site, we
@@ -201,8 +219,9 @@ It requires using Session Service, and supports both Schibsted account productId
 feature id's.
 
 #### Example
+
 ```javascript
-import { Monetization } from '@schibsted/account-sdk-browser'
+import { Monetization } from '@schibsted/account-sdk-browser';
 
 const monetization = new Monetization({
     clientId: '56e9a5d1eee0000000000000',
@@ -215,9 +234,9 @@ try {
     // Check if the user has access to a a particular product
     const userId = await identity.getUserId();
     const data = await monetization.hasAccess([productId], userId);
-    alert(`User has access to ${productId}? ${data.entitled}`)
+    alert(`User has access to ${productId}? ${data.entitled}`);
 } catch (err) {
-    alert(`Could not query if the user has access to ${productId} because ${err}`)
+    alert(`Could not query if the user has access to ${productId} because ${err}`);
 }
 ```
 
@@ -229,20 +248,20 @@ pages for redeeming voucher codes, reviewing payment history, and more.
 #### Example
 
 ```javascript
-import { Payment } from '@schibsted/account-sdk-browser'
+import { Payment } from '@schibsted/account-sdk-browser';
 
 const paymentSDK = new Payment({
     clientId: '56e9a5d1eee0000000000000',
     redirectUri: 'https://awesomenews.site', // ensure it's listed in selfservice
     env: 'PRE', // Schibsted account env. A url or a special key: 'PRE', 'PRO' or 'PRO_NO'
-})
+});
 
 // Get the url to paymentSDK with paylink
-const paylink = '...'
-const paylinkUrl = paymentSDK.purchasePaylinkUrl(paylink)
+const paylink = '...';
+const paylinkUrl = paymentSDK.purchasePaylinkUrl(paylink);
 
 // Or another example --- pay with paylink in a popup
-paymentSDK.payWithPaylink(paylink)
+paymentSDK.payWithPaylink(paylink);
 ```
 
 ## Appendix
@@ -273,27 +292,28 @@ browser side. Nevertheless, here is a short description of them.
    production environments is `vgs_email`, because reasons (on PRE, it is called `spid-pre-data`).
    It's a JSON string that's encoded using the standard `encodeURIComponent()` function and is an
    object that contains two pieces of information that's important:
-   * `remember`: if set to `true`, the user chose to be remembered and this means we usually support
-     auto-login (that is, if you call the Schibsted account hassession service, and no session can
-     be found in the session database, it will automatically create a new one for the user so that
-     they don't have to authenticate again. If it is `false`, it should be interpreted as the user
-     does not want to be automatically logged in to any site when their session expires
-   * `v`: the version number
+    * `remember`: if set to `true`, the user chose to be remembered and this means we usually support
+      auto-login (that is, if you call the Schibsted account hassession service, and no session can
+      be found in the session database, it will automatically create a new one for the user so that
+      they don't have to authenticate again. If it is `false`, it should be interpreted as the user
+      does not want to be automatically logged in to any site when their session expires
+    * `v`: the version number
 1. The **session** cookies: Cookie names in production environments are `identity`, and `SPID_SE` or
    `SPID_NO`. It contains:
-   * `user`: an object (if it's missing, a call to hassession will return a `401` with a
-     `UserException` that says `No session found`)
-     * `userId` identifies the user. We use this property to compare "old" user with "new" user and
-       fire events that indicate that the user has changed
-     * `is_logged_in` indicates if the user is logged in
-   * `user_tags`: a map that contains some flags about the user; namely:
-     * `is_logged_in` indicates if the user is logged in (this seems to be a duplicate of a
-       property with a similar name in the parent `user` object)
-     * `terms`: a map of term ids that indicate if they've been accepted by the user.
-   * `referer` (yep, missing the double "rr"..): If this is missing, a call to hassession will
-     return a `401` with a `UserException` that says `No session found`.
+    * `user`: an object (if it's missing, a call to hassession will return a `401` with a
+      `UserException` that says `No session found`)
+        * `userId` identifies the user. We use this property to compare "old" user with "new" user and
+          fire events that indicate that the user has changed
+        * `is_logged_in` indicates if the user is logged in
+    * `user_tags`: a map that contains some flags about the user; namely:
+        * `is_logged_in` indicates if the user is logged in (this seems to be a duplicate of a
+          property with a similar name in the parent `user` object)
+        * `terms`: a map of term ids that indicate if they've been accepted by the user.
+    * `referer` (yep, missing the double "rr"..): If this is missing, a call to hassession will
+      return a `401` with a `UserException` that says `No session found`.
 
 ## Releasing
+
 Tags are pushed to NPM via Travis. To release a new version, run in master
 
 ```bash
@@ -305,7 +325,7 @@ and push.
 
 ## LICENSE
 
-Copyright (c) 2024 Schibsted Products & Technology AS
+Copyright (c) 2026 Schibsted Products & Technology AS
 
 Licensed under the [MIT
 License](https://github.com/schibsted/account-sdk-browser/blob/master/LICENSE.md)