@schibsted/account-sdk-browser 5.2.6 → 5.3.0

package/README.md

@@ -1,6 +1,4 @@
-[![logo](https://www.schibsted.com/Global/LogoTypes/Logos%202014/SMG_Small_2014_RGB.png)](https://github.com/schibsted/account-sdk-browser)
-
-![Build Status](https://github.com/schibsted/account-sdk-browser/actions/workflows/pr.yml/badge.svg)
+![Build Status](https://schibsted.ghe.com/user-identity/account-sdk-browser/actions/workflows/pr.yml/badge.svg)
 [![Code coverage](https://codecov.io/gh/schibsted/account-sdk-browser/branch/master/graph/badge.svg)](https://codecov.io/gh/schibsted/account-sdk-browser)
 [![Snyk](https://snyk.io/test/github/schibsted/account-sdk-browser/badge.svg?targetFile=package.json)](https://snyk.io/test/github/schibsted/account-sdk-browser)
 
@@ -53,9 +51,9 @@ Follow the [migration guide](./MIGRATION.md).
 ## Example project
 
 There is an example that demonstrates how the SDK can be used. The code is
-[here](https://github.com/schibsted/sdk-example), and you can see it live
+[here](https://schibsted.ghe.com/user-identity/sdk-example), and you can see it live
 [here](https://pro.sdk-example.com). You have a use-case that we haven't thought of? Ask us to add
-it by creating an [issue](https://github.com/schibsted/sdk-example/issues/new).
+it by creating an [issue](https://schibsted.ghe.com/user-identity/sdk-example/issues/new).
 
 You can use that code as inspiration or just fork and play with it. The account-sdk-browser NPM
 module is used for authenticating the user with Schibsted account. Take a look at how the SDK is
@@ -126,6 +124,84 @@ function userClicksLogIn() {
 }
 ```
 
+#### Forward consents to Account
+
+The SDK forwards the user's current consents to Schibsted account in every login URL. The consents are
+read by a `getConsents` reader, which returns them serialized as `URLSearchParams`; the SDK appends them
+to the login URL as they are. The reader is called synchronously every time a login URL is created, so it
+must return the current state immediately instead of waiting for the consent dialog.
+`login()` and `loginUrl()` stay synchronous; a login started before the user answers the dialog
+(e.g. from the dialog itself) continues without consents.
+
+Login links rendered before the user answered the consent dialog are refreshed when they are clicked:
+the SDK listens to clicks on the document and updates the consents of `<a>` elements that point to its
+own login URL. Links inside iframes and URLs opened with `window.open()` are not refreshed;
+create the URL at the time of the user's action if that matters.
+
+##### Schibsted sites
+
+By default, consents are read from the Schibsted Sourcepoint integration (`window._tcf_` or
+`window._scc_`), so Schibsted sites forward consents out of the box, without any configuration:
+
+```javascript
+const identity = new Identity({
+    clientId: '56e9a5d1eee0000000000000',
+    redirectUri: 'https://awesomenews.site',
+    sessionDomain: 'https://id.awesomenews.site',
+    // Optional: opt out of refreshing rendered login links
+    refreshLoginLinks: false,
+});
+```
+
+##### Other CMPs
+
+Sites without the Schibsted Sourcepoint integration pass their own reader:
+
+```javascript
+const identity = new Identity({
+    clientId: '56e9a5d1eee0000000000000',
+    redirectUri: 'https://awesomenews.site',
+    sessionDomain: 'https://id.awesomenews.site',
+    // Reads the decision of your CMP, see the interface below
+    getConsents: readConsentsFromMyCmp,
+});
+```
+
+Use `getConsents: () => null` to forward no consents.
+
+##### The `getConsents` interface
+
+```typescript
+type ConsentReader = () => URLSearchParams | null;
+```
+
+A reader must:
+
+- **Be synchronous.** Return the decision the CMP already has, e.g. from its in-memory state or its
+  stored consent cookie. Do not return a `Promise` or wait for the consent dialog.
+- **Return `URLSearchParams` or `null`.** `null` or empty params mean the decision is unknown, and no consent
+  parameters are added. The SDK logs any other return value and any thrown error, and the login continues
+  without consents.
+- **Return only consent parameters.** Every key it returns is added to the login URL. When a rendered
+  link is refreshed, those keys replace the values already on it, so do not return OAuth parameters such
+  as `state` or `redirect_uri`. Repeated keys (e.g. `purpose=a&purpose=b`) are kept.
+
+Return these parameters (format `v1`, the only supported version):
+
+| Parameter         | Value                                                                                  |
+|-------------------|----------------------------------------------------------------------------------------|
+| `consents`        | Alphabetically sorted, comma-separated purposes the user granted, or `rejected` if the user rejected all of them. Purposes: `advertising`, `analytics`, `marketing`, `personalisation` |
+| `consent_version` | Version of this parameter format; always `v1`                                          |
+
+Examples of serialized params returned by a reader:
+
+| User's decision                       | Returned `URLSearchParams` (serialized)             |
+|---------------------------------------|-----------------------------------------------------|
+| Granted advertising and analytics     | `consents=advertising%2Canalytics&consent_version=v1` |
+| Granted analytics only                | `consents=analytics&consent_version=v1`             |
+| Rejected all purposes                 | `consents=rejected&consent_version=v1`              |
+| Not answered yet                      | `null` (or empty `URLSearchParams`)                 |
+
 #### Regarding `state`
 
 This parameter is an OpenID Connect parameter (described in [this paragraph in the
@@ -184,7 +260,7 @@ signal to your main page — using
 [postMessage](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) or something
 similar — to indicate that the user is logged in. If the popup window fails to open, it'll
 automatically fall back to the redirect flow. The SDK Example project mentioned above demonstrates
-how it can work. Again, you can see [sdk-example](https://github.com/schibsted/sdk-example) if you
+how it can work. Again, you can see [sdk-example](https://schibsted.ghe.com/user-identity/sdk-example) if you
 want a working example.
 
 #### Is the user logged in?
@@ -312,23 +388,30 @@ browser side. Nevertheless, here is a short description of them.
     * `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
+## Development
 
-Tags are pushed to NPM via Travis. To release a new version, run in master
+Dependencies are installed from [Schibsted Artifactory](https://artifactory.schibsted.io) (see [`.npmrc`](./.npmrc)),
+so npm must be authenticated to it before `npm install`. The private `@schibsted/consent-url-utils` package is
+bundled into `src/vendor/` on install (`npm run vendor`), so the published SDK does not depend on it.
 
-```bash
-$ npm version <major|minor|patch>
-```
+## Publishing
+
+Versioning and changelog are handled by [Release Please (GitHub Action)](https://github.com/googleapis/release-please). Publishing to [npmjs.org](https://www.npmjs.com/package/@schibsted/account-sdk-browser) is handled by the [npm-publish workflow](./.github/workflows/npm-publish.yml). See the [Release Please workflow](./.github/workflows/release-please.yml) and [`release-please-config.json`](./release-please-config.json).
+
+When publishable changes have been merged to `master`, Release Please will create (or update) a release pull request.
+The suggested version is based on the commit messages in accordance with the [Conventional Commits](https://www.conventionalcommits.org/) specification — `fix:` bumps the patch version, `feat:` bumps the minor version, and `feat!:` or a `BREAKING CHANGE:` footer bumps the major version.
+Other prefixes (`chore:`, `docs:`, `test:`, `refactor:`, `ci:`, `build:`, `style:`) do not trigger a release and are hidden from the changelog.
+
+To release/publish the changes simply merge the corresponding pull request and wait for the publish workflow to finish.
+Release-please will create a git tag (e.g. `v5.2.7`) and a GitHub Release, and the [publish workflow](./.github/workflows/npm-publish.yml) will push the package to npmjs.org.
 
-which will run the test, update version in package.json, commit, tag the commit
-and push.
 
 ## LICENSE
 
 Copyright (c) 2026 Schibsted Products & Technology AS
 
 Licensed under the [MIT
-License](https://github.com/schibsted/account-sdk-browser/blob/master/LICENSE.md)
+License](https://schibsted.ghe.com/user-identity/account-sdk-browser/blob/master/LICENSE.md)
 
 Unless required by applicable law or agreed to in writing, software distributed under the License is
 distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or