@amedia/user 1.0.0 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/CHANGELOG.md +29 -0
  2. package/README.md +157 -184
  3. package/package.json +4 -3
package/CHANGELOG.md CHANGED
@@ -1,5 +1,34 @@
1
1
  # @amedia/user
2
2
 
3
+ ## 1.0.1
4
+
5
+ ### Patch Changes
6
+
7
+ - [#1126](https://github.com/amedia/amedia-user-js/pull/1126) [`b280880`](https://github.com/amedia/amedia-user-js/commit/b2808802cee1cfb539932fe081a70c5f74ac8dbc) Thanks [@emilhauk](https://github.com/emilhauk)! - Update readme, plus some package cleanup
8
+
9
+ ## 1.0.0
10
+
11
+ ### Major Changes
12
+
13
+ - [`31fd231`](https://github.com/amedia/amedia-user-js/commit/31fd23139e7d412d686c4c1ce2e0f5cf77564d72) Thanks [@emilhauk](https://github.com/emilhauk)! - From now @amedia/user package will include the following:
14
+ - index.js that wrap the relevant version alias.
15
+ - index.d.ts all typings to assist during development.
16
+ - README.md
17
+ - CHANGELOG.md
18
+
19
+ By "proxying" the version alias, developers no longer need to set up import maps rewrites for @amedia/user anymore!
20
+
21
+ **Upgrading**
22
+
23
+ Remove @amedia/user from import maps in the app. If this package was the only one using import maps, you can get rid of some extra config.
24
+
25
+ If you have made some additional setup to support SSR, you may need to rework this a bit. Node.js is not able to execute @amedia/user. It will just fail due to imports. We are looking into improving this, but at least for now, you need to ensure you don't try to execute the code during SSR. All frontend frameworks that support SSR should have built-in facilities for this case.
26
+
27
+ **Breaking changes**
28
+
29
+ With v1, @amedia/user will lose its built-in mocks.
30
+ We have some plans for achieving something similar later on, but at least the current implementation will go away.
31
+
3
32
  ## 0.14.152
4
33
 
5
34
  ### Patch Changes
package/README.md CHANGED
@@ -1,87 +1,70 @@
1
1
  # @amedia/user
2
2
 
3
- The goal of this module is to simplify the usage of aID data and services in Amedia frontend code. The module is designed to be used several places on a webpage independently, and the module will ensure that requests from different parts of the webpage are handled in an efficient manner.
3
+ The goal of this module is to simplify the usage of aID data and services in Amedia frontend code. The module is
4
+ designed to be used several places on a webpage independently, and the module will ensure that requests from different
5
+ parts of the webpage are handled efficiently.
4
6
 
5
7
  # TL;DR (details in the linked chapters)
6
8
 
7
9
  - [UserDataRequest](#getting-user-data)<br/>
8
- All current user data (including login state and access). Call it as much as you like, but only ask for what you actually need.
10
+ User data like name, access, KV-storage, etc. Call it as much as you like, but only ask for what you
11
+ actually need.
9
12
  - [PaywallUnlockRequest](#unlocking-the-paywall)<br/>
10
- When you need to actively verify login state and access. May perform redirects and expensive calls for subscription activation, and thus limited in how much it accepts to be called.
13
+ When you need to actively verify login state and access. May perform redirects and expensive calls for subscription
14
+ activation, and thus limited in how much it accepts to be called.
11
15
  - [SiteAccessRequest](#activating-subscriptions--finding-upgrade-path)<br/>
12
- When you need to actively verify access. Specify which access feature(s) you need. May attempt subscription activation.
16
+ When you need to actively verify access. Specify which access feature(s) you need. May attempt subscription
17
+ activation.
13
18
  - [User actions](#actions)<br/>
14
19
  Login, logout, that sort of thing.
15
20
 
16
21
  # Usage
17
22
 
18
- Please be advised that you are required to use ESM in order to use this module.
23
+ Please be advised that you are required to use ESM to use this module.
19
24
 
20
25
  ## Importing the module
21
26
 
22
- Add this module to your project by running `npm install -d @amedia/user`. This will allow for type-hinting, and will provide some mock-functionality. To get the actual implementation for production you must swap out `@amedia/user` with `https://assets.acdn.no/pkg/@amedia/user/v0/user.js`. This can be done easily with import-maps. For inspiration, see Ego, Bacchus or Saturn on how to use this module through an Eik plugin. You can read more about Eik on [Slite](https://amedia.slite.com/app/channels/hOlqx3Miez/notes/iexhL4MZn3).
23
-
24
- ## Mocking
25
-
26
- When working exclusively on a frontend app, it might be cumbersome to boot the entire aid rig locally for development. To make this easier, the npm package provides a mock for you to use.
27
-
28
- **To enable mocked data** you just comment out the import map translation. This will cause your bundler to include the mocks.
29
-
30
- Then mocked, you'll be logged in as a user with full access. Check the browser console for information about this persona, other personas available, and how to choose between them.
31
-
32
- ### Caveats of the mock
33
-
34
- This is not intended to be a complete mock as it would've soon required us to reimplement most of aID in the mock :)
35
-
36
- Supported actions:
37
-
38
- - **UserDataRequest** will return data based on current persona
39
- - **PaywallUnlockRequest** will only return state based on current persona (e.g. no reload/redirect)
40
-
41
- Unsupported (will throw Error):
42
-
43
- - goToLoginPage
44
- - logout
45
- - updateStorage
46
- - saveStorage
27
+ Add this module to your project by running `npm install -d @amedia/user`. This will allow for type-hinting. @amedia/user
28
+ requires a browser to run. If your app performs server-side rendering, consult framework documentation on how to do this.
47
29
 
48
30
  ## Getting user data
49
31
 
50
- The most common use case for aID on newspapers is to get some kind of data about a user, this could be the user's name, some stored preference, access or data that has been derived about the user.
51
-
52
- To get user data you first need to create a `new UserDataRequest()` instance, then specify what data you need and lastly decide if you want to wait until all data is available, or you want to get partial updates.
32
+ To get user data, you first need to create a `new UserDataRequest()` instance, then specify what data you need and
33
+ lastly decide if you want to wait until all data is available, or you want to get partial updates.
53
34
 
54
35
  ### Data model
55
36
 
56
37
  #### Attributes
57
38
 
58
- Attributes are data directly related to the user, with the exception of access. Supported attributes are:
39
+ | name | type | description |
40
+ | ------------------ | ------------- | ------------------------------------------------------- |
41
+ | uuid | string | The users unique ID. (NOT for tracking). |
42
+ | trackingKey | string | Unique ID of user that can be used for tracking. |
43
+ | sessionTrackingKey | string | Tracking key for the user session. |
44
+ | name | string | Users full name. |
45
+ | access | Array<string> | Users access on current site (list of access features). |
59
46
 
60
- | name | type | description |
61
- | ------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
62
- | uuid | string | The users unique ID. (NOT for tracking) |
63
- | name | string | Users full name |
64
- | trackingKey | string | Unique ID of user that can be used for tracking (pseudonym) This is also known as the legacy name user_key |
65
- | access | Array<string> | Users access on current site (list of access features) |
66
- | extraData | Record<string,unknown> | Data that has been modelled about the user (gender, ad segments etc. from Nebula) |
67
- | privacyPreferences (deprecated) | [PrivacyPreferences](https://github.com/amedia/amedia-user-js/blob/master/src/types.ts#L16) | Privacy preferences set on Min aID. (Deprecated - CMP is now used) |
68
- | sessionTrackingKey | string | Tracking key for the user session |
47
+ Attributes are requested by calling `.withAttributes(attributes: Array<string>)` on a `UserDataRequest` with a list of
48
+ the attributes you need.
69
49
 
70
- Attributes are requested by calling `.withAttributes(attributes: Array<string>)` on a `UserDataRequest` with a list of the attributes you need.
50
+ In the response, `attributes` is an object where each requested attribute is an attribute. So you can get the name by
51
+ accessing `attributes.name` for example.
71
52
 
72
- In the response, `attributes` is an object where each requested attribute is an attribute. So you can get the name by accessing `attributes.name` for example.
73
-
74
- NOTE: Don't request attributes you don't intend to use. This previously had a latency-cost attached to it. This is no longer the case. However, it's best not to keep user data around where it's not needed.
75
-
76
- NOTE2: ~If you need to know if the current user is an employee, you are encouraged to use data from `extraData` rather than `access` as `extraData` is quicker.~ This is not the case anymore. `access` is now quicker to use and more precise.
53
+ NOTE: Don't request attributes you don't intend to use. This previously had a latency-cost attached to it. This is no
54
+ longer the case. However, it's best not to keep user data around unnecessarily.
77
55
 
78
56
  #### Storage
79
57
 
80
- Storage contains namespaces stored in aID (Europa). A namespace is a named set of key value pairs stored for a specific user. An example could be favourite_teams, which could contain team_id as key and timestamp it was stored as favourite as value.
58
+ Storage contains namespaces stored in aID (Europa). A namespace is a named set of key value pairs stored for a user. An
59
+ example could be favourite_teams namespace, which could contain team_id as a key and timestamp it was stored as a value.
81
60
 
82
- Storage is requested by calling `.withStorage(namespaces: Array<string>)` on a `UserDataRequest`. If a namespace does not exist it will be "created" in that you'll get an empty object back. Saving data to it will perform the actual creation.
61
+ Storage is requested by calling `.withStorage(namespaces: Array<string>)` on a `UserDataRequest`. If a namespace does
62
+ not exist, it will be "created" in that you'll get an empty object back. Saving data to it will perform the actual
63
+ creation.
83
64
 
84
- In the response, `storage` is an object with each namespace as an attribute which leads to an object with attributes for each key in the namespace. So you can access `storage.favourite_teams.myteamid` and get the value stored for `teamid` in the `favourite_teams` namespace. This value will be whatever was saved there, but always a string.
65
+ In the response, `storage` is an object with each namespace as an attribute which leads to an object with attributes for
66
+ each key in the namespace. So you can access `storage.favourite_teams.myteamid` and get the value stored for `teamid` in
67
+ the `favourite_teams` namespace. This value will be whatever was saved there, but always a string.
85
68
 
86
69
  ```ts
87
70
  type Storage = { [namespace: string]: Record<string, string> };
@@ -91,9 +74,11 @@ type Storage = { [namespace: string]: Record<string, string> };
91
74
 
92
75
  This works just as [regular storage](#storage), but the namespaces are scoped to oauth clients.
93
76
 
94
- Client Storage is requested by calling `.withClientStorage(clientId: string, namespaces: Array<string>)` on a UserDataRequest.
77
+ Client Storage is requested by calling `.withClientStorage(clientId: string, namespaces: Array<string>)` on a
78
+ UserDataRequest.
95
79
 
96
- In the response, `clientStorage[clientId]` is an object with each namespace as en attribute that works as described above.
80
+ In the response, `clientStorage[clientId]` is an object with each namespace as en attribute that works as described
81
+ above.
97
82
 
98
83
  ```ts
99
84
  type ClientStorage = { [clientId: string]: Storage };
@@ -101,8 +86,8 @@ type ClientStorage = { [clientId: string]: Storage };
101
86
 
102
87
  #### Writing to storage namespaces
103
88
 
104
- A namespace is a proxied instance of `Namespace`.
105
- You access this as any old object, but it provides a save()-method for when to wish to persist this namespace for later use.
89
+ A namespace is a proxied instance of `Namespace`. You access this as any old object, but it provides a save()-method for
90
+ when you wish to persist this namespace for later use.
106
91
 
107
92
  ```ts
108
93
  import { UserDataRequest } from '@amedia/user';
@@ -117,11 +102,14 @@ delete storage.my_namespace.my_key;
117
102
  storage.my_namespace.save();
118
103
  ```
119
104
 
120
- In this example, `my_key` in `my_namespace` would be updated to `my data` (and then deleted). Other data would probably be left "untouched". **Meaning**, if this namespace sees a lot of changes outside this instance you may end up overwriting other changes if you delay a lot between reading av writing!
105
+ In this example, `my_key` in `my_namespace` would be updated to `my data` (and then deleted). Other data would probably
106
+ be left "untouched." **Meaning**, if this namespace sees a lot of changes outside this instance, you may end up
107
+ overwriting other changes if you delay a lot between reading and writing!
121
108
 
122
109
  #### State
123
110
 
124
- State is ment to describe the current context the user is in right now. It's not directly requested, but will always be a part of the response.
111
+ State is meant to describe the current context the user is in right now. It's not directly requested but will always be
112
+ a part of the response.
125
113
 
126
114
  Current attributes in `state`:
127
115
 
@@ -130,9 +118,9 @@ Current attributes in `state`:
130
118
  | isLoggedIn | boolean | Is the user currently logged in? If not, most attributes will be undefined |
131
119
  | emergencyMode | Array<string> | Current state of emergency mode in production environment (paywall, aid etc.) |
132
120
 
133
- #### Access not attached to a user
121
+ #### Access not directly attached to a user
134
122
 
135
- A visitor may have access through their IP address, or a specific token that we periodically enable for "avis i skolen".
123
+ A visitor may have access through their IP-address, or a specific token that we periodically enable for "avis i skolen".
136
124
 
137
125
  Current elements in the array `nonUserAccess`:
138
126
 
@@ -143,13 +131,19 @@ Current elements in the array `nonUserAccess`:
143
131
 
144
132
  ### Executing the request
145
133
 
146
- Once you have created a request and specified the data you need, the final step is to decide how you want to get the data once it's available. You can either choose to subscribe to data as they get loaded from the various backends or wait until all fetching is done and get everything in one package.
134
+ Once you have created a request and specified the data you need, the final step is to decide how you want to get the
135
+ data once it's available. You can either choose to subscribe to data as they get loaded from the various backends or
136
+ wait until all fetching is done and get everything in one package.
147
137
 
148
- The response to the request will be an object with attributes for state, attributes and storage. In the examples below these are unpacked for easier access.
138
+ The response to the request will be an object with attributes for state, attributes and storage. In the examples below
139
+ these are unpacked for easier access.
149
140
 
150
141
  #### Subscribing to updates
151
142
 
152
- The most flexible way to get userdata is by subscribing to updates. This is done by calling `.subscribe()` on the `UserDataRequest` with a callback function that can handle the updates once they arrive. This is especially useful when the time it can take to get the data can vary. Getting the user's name is very fast, so you can display the user's name before you have received storage for example.
143
+ The most flexible way to get userdata is by subscribing to updates. This is done by calling `.subscribe()` on the
144
+ `UserDataRequest` with a callback function that can handle the updates once they arrive. This is especially useful when
145
+ the time it can take to get the data can vary. Getting the user's name is quick, so you can display the user's name
146
+ before you have received storage, for example.
153
147
 
154
148
  Full usage example:
155
149
 
@@ -169,17 +163,21 @@ const unsubscribe = new UserDataRequest()
169
163
  unsubscribe();
170
164
  ```
171
165
 
172
- The callback you supplied to subscribe is called whenever there are any changes to the properties you have requested, so be prepared to re-render.
166
+ The callback you supplied to subscribe is called whenever there are any changes to the properties you have requested, so
167
+ be prepared to re-render.
173
168
 
174
- Also, your requested properties might not arrive all at once. This callback will be called whenever we get data in from the various services.
169
+ Also, your requested properties might not arrive all at once. This callback will be called whenever we get data in from
170
+ the various services.
175
171
 
176
172
  You should check the state object for potential emergency modes and act accordingly.
177
173
 
178
- Should you wish to end your subscription, just call the returned function from subscribe.
174
+ Should you wish to end your subscription, just call the returned function from `subscribe`.
179
175
 
180
- #### Fetching all the data once (no re-renders)
176
+ #### Fetching all the data at once (no re-renders)
181
177
 
182
- In many use-cases, it's more convenient to just wait until everything is ready, so you don't have to handle multiple callbacks. In these cases, it's easier to call `.fetch()`. This method will return a `Promise` that resolves the same object you would get in the `subscribe` callback.
178
+ In many use-cases, it's more convenient to just wait until everything is ready, so you don't have to handle multiple
179
+ callbacks. In these cases, it's easier to call `.fetch()`. This method will return a `Promise` that resolves the same
180
+ object you would get in the `subscribe` callback.
183
181
 
184
182
  Full usage example:
185
183
 
@@ -198,13 +196,18 @@ new UserDataRequest()
198
196
  });
199
197
  ```
200
198
 
201
- Fetch will wait until it has all the data you requested before resolving, unless the user is not currently logged in. Internally `.fetch()` will use `.subscribe()` and just wait until everything is ready before unsubscribing and then resolving the returned promise.
199
+ Fetch will wait until it has all the data you requested before resolving, unless the user is not currently logged in.
200
+ Internally `.fetch()` will use `.subscribe()` and just wait until everything is ready before unsubscribing and then
201
+ resolving the returned promise.
202
202
 
203
- If you really need to render the user's name or get their uuid etc. as fast as possible, use `.subscribe()`, if not, this is probably easier.
203
+ If you really need to render the user's name or get their uuid etc. as fast as possible, use `.subscribe()`, if not,
204
+ this is probably easier.
204
205
 
205
206
  ##### Timeouts when using fetch
206
207
 
207
- Especially poor connections may result in almost eternal wait times - which is no good if your app is locked while waiting on the data. Because of this we have introduced a timeout. A timeout will cause the fetch to reject with FetchTimeoutError.
208
+ Especially poor connections may result in almost eternal wait times - which is no good if your app is locked while
209
+ waiting on the data. Because of this we have introduced a timeout. A timeout will cause the fetch to reject with
210
+ FetchTimeoutError.
208
211
 
209
212
  _FetchTimeoutError will include any data we might have gotten before we timed out_
210
213
 
@@ -222,7 +225,8 @@ new UserDataRequest()
222
225
  });
223
226
  ```
224
227
 
225
- If you're running a background task and don't mind waiting longer than default (10 seconds), you may set a longer timeout in fetch:
228
+ If you're running a background task and don't mind waiting longer than default (10 seconds), you may set a longer
229
+ timeout in fetch:
226
230
 
227
231
  ```ts
228
232
  new UserDataRequest()
@@ -232,7 +236,8 @@ new UserDataRequest()
232
236
  .fetch({ timeout: 60000 /* milliseconds */ });
233
237
  ```
234
238
 
235
- This may also be lowered below the default, but network request do take some time, even on fast networks, so don't shoot your app in the foot by lowering it too much.
239
+ This may also be lowered below the default, but network request do take some time, even on fast networks, so don't shoot
240
+ your app in the foot by lowering it too much.
236
241
 
237
242
  ##### Emergency mode when using fetch
238
243
 
@@ -241,7 +246,7 @@ If you receive this error, there will be no user data available.
241
246
  Your app should act accordingly, eg:
242
247
 
243
248
  - Render non-personalized
244
- - Show placeholder with an error message
249
+ - Show a placeholder with an error message
245
250
  - Not rendering at all
246
251
 
247
252
  ```ts
@@ -254,7 +259,7 @@ new UserDataRequest()
254
259
  if (e instanceof FetchTimeoutError) {
255
260
  console.log(e.partialData);
256
261
  // Maybe you're able to render your app in a reduced state (using partialData).
257
- } else if (e instanceOf EmergencyModeError) {
262
+ } else if (e instanceof EmergencyModeError) {
258
263
  console.log(e.activeEmergencyModes);
259
264
  // Maybe you're able to render your app in a non-personalized way?
260
265
  }
@@ -269,19 +274,28 @@ Builds and return the aID login URL. See `goToLoginPage` for details
269
274
 
270
275
  ### `goToLoginPage({requestedUrl: string context: string}): void`
271
276
 
272
- Send the user to the aID login page. It will take care of building the correct URL, including your current site domain, so the login page is skinned correctly. By default, the user will be sent back to the current url after login has been completed. You may include a requestedUrl if you need to control where the user should end up.
277
+ Send the user to the aID login page. It will take care of building the correct URL, including your current site domain,
278
+ so the login page is skinned correctly. By default, the user will be sent back to the current url after login has been
279
+ completed. You may include a requestedUrl if you need to control where the user should end up.
273
280
 
274
- **Note**: We also support sending a context string when requesting a login. Please include your app-name or more recognizable string. If your app has multiple places for requesting login, it's nice to include that info as well. Eg: `goToLoginPage({context: my-app_switch-user})`. The context will help us understand where logins originate from to assist in debugging.
281
+ **Note**: We also support sending a context string when requesting a login. Please include your app-name or more
282
+ recognizable string. If your app has multiple places for requesting login, it's nice to include that info as well.
283
+ Eg: `goToLoginPage({context: my-app_switch-user})`. The context will help us understand where logins originate from to
284
+ assist in debugging.
275
285
 
276
286
  ### `requestDataRefresh(): void`
277
287
 
278
- If you need to ensure the latest data is available, you may request a data refresh. @amedia/user will look up all data it has in cache and contact various endponints to ensure they are up to date. If you're subscribing to updates, your callback will be executed if anything changes.
288
+ If you need to ensure the latest data is available, you may request a data refresh. @amedia/user will look up all data
289
+ it has in the cache and contact various endpoints to ensure they are up to date. If you're subscribing to updates, your
290
+ callback will be executed if anything changes.
279
291
 
280
292
  **Note**: A data refresh will be automatically performed every time the page regains focus (eg. user switches tabs)
281
293
 
282
294
  ### `logout(): Promise<void>`
283
295
 
284
- This action will log the user out of aID. The logout is global, meaning it will log the session out of all sites and aid.no. After logout has completed the promise will resolve, giving your app the opportunity to reset state / reload the page etc.
296
+ This action will log the user out of aID. The logout is global, meaning it will log the session out of all sites and
297
+ aid.no. After logout has completed the promise will resolve, giving your app the opportunity to reset state / reload the
298
+ page etc.
285
299
 
286
300
  ### `pollForAccess(requredAccessFeatures = ['pluss'], timeout_millis = 3000): Promise<true>`
287
301
 
@@ -290,74 +304,58 @@ features are attained, or TimeoutError.
290
304
 
291
305
  ### `aidUrls: Record<string, URL>`
292
306
 
293
- Get various, environment aware, URLs to pages often linked to from other apps. This includes pages like the aID profile page, Terms of Service, Privacy Statement, Privacy Preferences, Family Sharing and the like.
294
-
295
- ### DEPRECATED: `~updateStorage(storage: Storage): void~`
296
-
297
- [See: Writing-to-storage-namespaces](#writing-to-storage-namespaces)
298
- The safest way to update a value is to use `updateStorage()`. This will send a `PATCH` to aID (Europa) to only update the specified attributes of a namespace, and keep the rest as it is. This reduces concurrency issues where someone could have updated a different attribute after you read the namespace.
299
-
300
- Example of use:
301
-
302
- ```ts
303
- updateStorage({
304
- my_namespace: {
305
- my: 'data',
306
- },
307
- });
308
- ```
309
-
310
- ### DEPRECATED: `~saveStorage(storage: Storage): void~`
311
-
312
- [See: Writing-to-storage-namespaces](#writing-to-storage-namespaces)
313
- Will send a `PUT` to aID (Europa) to update the entire namespace/namespaces, deleting missing data in the process. Please be advised that you may be overwriting updates done by other apps to these namespaces, so it's best to save with a recent namespace if it sees heavy writes :)
314
-
315
- Example of use:
316
-
317
- ```ts
318
- saveStorage({
319
- my_namespace: {
320
- my: 'data',
321
- },
322
- });
323
- ```
307
+ Get various, environment-aware URLs to pages often linked to from other apps. This includes pages like the aID profile
308
+ page, Terms of Service, Privacy Statement, Privacy Preferences, Family Sharing and the like.
324
309
 
325
310
  ## Unlocking the paywall
326
311
 
327
- Amedia's sites use a Paywall that's based on a cookie called VSTOKEN that is read by Varnish and used by the content system to decide if the content should be shown to the user or not. If not, the content will load what we call an incentive, a dialogue above the content, that will allow the user to log in and/or buy subscription. The incentive will use `PaywallUnlockRequest` to see if it can somehow grant access to the user.
312
+ Sites hosted through Amedia may use a Paywall. This is based on a JWT-cookie called aid.jwt that is validated and parsed
313
+ by Varnish. When content is requested from a backend, it returns with header information used by varnish to decide if
314
+ the content is available to the reader, and a header telling varnish where to get the version that includes the paywall.
315
+ The paywall (incentive) will use `PaywallUnlockRequest` to see if it can somehow grant access to the user.
328
316
 
329
- In some cases it makes sense to create a different user interface for a paywall. If so we recommend that you use `PaywallUnlockRequest` in order to get the same functionality.
317
+ In some cases it makes sense to create a different user interface for a paywall. If so we recommend that you use
318
+ `PaywallUnlockRequest` in order to get the same functionality.
330
319
 
331
- More information about the paywall can be found here: [How the Paywall works](https://amedia.slite.com/app/channels/hOlqx3Miez/notes/UFqOFRV3g1)
320
+ More information about the paywall can be found here:
321
+ [How the Paywall works](https://amedia.slite.com/app/channels/hOlqx3Miez/notes/UFqOFRV3g1)
332
322
 
333
- Information about the incentive can also be useful, since you probably need to replicate this functionality if you create a new user interface: [How the Incentive works](https://amedia.slite.com/app/channels/hOlqx3Miez/notes/SroHksU9u)
323
+ Information about the incentive can also be useful, since you probably need to replicate this functionality if you
324
+ create a new user interface: [How the Incentive works](https://amedia.slite.com/app/channels/hOlqx3Miez/notes/SroHksU9u)
334
325
 
335
- To unlock the paywall, you first need to create a new `PaywallUnlockRequest`. Once created, you can set some options by calling methods on this request:
326
+ To unlock the paywall, you first need to create a new `PaywallUnlockRequest`. Once created, you can set some options by
327
+ calling methods on this request:
336
328
 
337
- - `reloadOnAccess()`: If the paywall unlocker finds sufficient access for the user it will reload the current page
338
- - `redirectOnAccess(requestedUrl: string)`: If the paywall unlocker finds sufficient access for the user, it will send the user
339
- to `requestedUrl`. (Provides more flexibility than `reloadOnAccess()`)
340
- - `withAccessFeatures(accessFeatures: string[])`: Specify what access features will give access to the current content.
341
- - `withSiteDomain(domain: string)`: Specify which site we to attempt activation against. The default is the current domain. This is mostly useful for alt.no which often knows what domain the user came from.
342
- - **DEPRECATED**: This will fail if you attempt to unlock a paywall on a page without a paywall or its own access features. Feature will be removed in the next major release. Use [SiteAccessRequest](#activating-subscriptions--finding-upgrade-path) instead.
329
+ - `reloadOnAccess()`: If the paywall unlocker finds sufficient access for the user, it will reload the current page
330
+ - `redirectOnAccess(requestedUrl: string)`: If the paywall unlocker finds sufficient access for the user, it will send
331
+ the user to `requestedUrl`. (Provides more flexibility than `reloadOnAccess()`)
332
+ - Deprecated (pass in constructor instead): `withAccessFeatures(accessFeatures: string[])`: Specify what access features
333
+ will give access to the current content.
343
334
 
344
- More details about the access model can be found here: [Access model](https://amedia.slite.com/app/channels/hOlqx3Miez/notes/nhG2Ok39BN)
335
+ More details about the access model can be found here:
336
+ [Access model](https://amedia.slite.com/app/channels/hOlqx3Miez/notes/nhG2Ok39BN)
345
337
 
346
- Once your options have been set up, you can call `tryUnlock()`. This is when all the magic happens. The unlocker will try to auto login the user on the current domain, check access, activate subscriptions in the subscription system, check for stuff like IP based access etc. When this is done, it will resolve the `Promise` that was returned by `tryUnlock()`.
338
+ Once your options have been set up, you can call `tryUnlock()`. This is when all the magic happens. The unlocker will
339
+ try to autologin the user on the current domain, check access, activate subscriptions in the subscription system, check
340
+ for stuff like IP-based access, etc. When this is done, it will resolve the `Promise` that was returned by
341
+ `tryUnlock()`.
347
342
 
348
- The resolution to the promise contains an object with attributes you can use to get details about why the user did not get access (or if he had access if you don't opt for reload or redirect). The object contains the following:
343
+ The resolution to the promise contains an object with attributes you can use to get details about why the user did not
344
+ get access (or if he had access if you don't opt for reload or redirect). The object contains the following:
349
345
 
350
- - isLoggedIn: True if the user is logged in, false otherwise. Useful if you want to show a login button, which makes no sense for logged in users.
346
+ - isLoggedIn: True if the user is logged in, false otherwise. Useful if you want to show a login button, which makes no
347
+ sense for logged-in users.
351
348
  - hasAccess: True if the user has access. Always false if you called `reloadOnAccess()` or `redirectOnAccess()`.
352
- - accessFeatures: List of access features the user has access to. Empty list if user is logged out or has no access. This list is useful if you want to upgrade from 'pluss' to 'plussalt' for instance. You might want to give a different user experience to users with some access than users with no access.
349
+ - accessFeatures: List of access features the user has access to. Empty list if noy logged in or has no access. This
350
+ list is useful if you want to upgrade from 'pluss' to 'plussalt' for instance. You might want to give a different user
351
+ experience to users with some access than users with no access.
353
352
 
354
353
  Full usage example:
355
354
 
356
355
  ```ts
357
356
  import { PaywallUnlockRequest } from '...';
358
357
 
359
- new PaywallUnlockRequest()
360
- .withAccessFeatures(['pluss'])
358
+ new PaywallUnlockRequest(['pluss'])
361
359
  .redirectOnAccess('https://my.neat/place') // Optional
362
360
  .reloadOnAccess() // Optional
363
361
  .tryUnlock()
@@ -389,22 +387,30 @@ new PaywallUnlockRequest()
389
387
  });
390
388
  ```
391
389
 
392
- Note that this _might result in redirects/reloads_ if the user is not already logged in. In that case you will end up here again if logging in did not result in access.
390
+ Note that this _might result in redirects/reloads_ if the user is not already logged in. In that case you will end up
391
+ here again if logging in did not result in access.
393
392
 
394
393
  ## Activating subscriptions / finding upgrade path
395
394
 
396
- Check the current users access on a specific site. If you're on a site that has its own access features (e.g. has a paywall), you should use PaywallUnlockRequest instead. This will set cookies as well.
395
+ `SiteAccessRequest` checks the current users' access to a specific site. If you're on a site that has its own access
396
+ features (e.g. has a paywall), you should use PaywallUnlockRequest instead. This will set cookies as well.
397
397
 
398
398
  - `withSiteDomain(siteDomain: string)` The domain you with to check access for / attempt activation against.
399
- - `withAccessFeatures(accessFeatures: Array<string>)` Which access features do you require in order to consider access is granted.
399
+ - `withAccessFeatures(accessFeatures: Array<string>)` Which access features do you require in order to consider access
400
+ is granted.
400
401
 
401
- Once your options have been set up, you can call `requestAccess()`. This is when all the magic happens. It will try to auto login the user on the current domain, check access, activate subscriptions in the subscription systems, check for stuff like IP based access etc. When this is done, it will resolve the `Promise` that was returned.
402
+ Once your options have been set up, you can call `requestAccess()`. This is when all the magic happens. It will try to
403
+ autologin the user on the current domain, check access, activate subscriptions in the subscription systems, check for
404
+ stuff like IP-based access etc. When this is done, it will resolve the `Promise` that was returned.
402
405
 
403
406
  The resolved promise contains the following:
404
407
 
405
- - isLoggedIn: True if the user is logged in, false otherwise. Useful if you want to show a login button (see [goToLoginPage(...)](#gotologinpagerequestedurl-string-context-string-void)).
408
+ - isLoggedIn: True if the user is logged in, false otherwise. Useful if you want to show a login button (see
409
+ [goToLoginPage(...)](#gotologinpagerequestedurl-string-context-string-void)).
406
410
  - hasAccess: True if the user has access that fulfils your `withAccessFeatures`-requirements.
407
- - accessFeatures: List of access features the user actually has at this time. Empty list if user is logged out or has no access. This list is useful if you want to upgrade from 'newspaper' to 'plussalt' for instance. You might want to give a different user experience to users with some access than users with no access.
411
+ - accessFeatures: List of access features the user actually has at this time. Empty list if user is logged out or has no
412
+ access. This list is useful if you want to upgrade from 'newspaper' to 'plussalt' for instance. You might want to give
413
+ a different user experience to users with some access than users with no access.
408
414
  - primarySite: Best guess of where the user may attain the access you requested.
409
415
 
410
416
  Full usage example:
@@ -413,9 +419,8 @@ Full usage example:
413
419
  import { SiteAccessRequest } from '@amedia/user';
414
420
  import { SiteAccessResolverError } from './SiteAccessRequest';
415
421
 
416
- new SiteAccessRequest()
422
+ new SiteAccessRequest(['sport_premium'])
417
423
  .withSiteDomain('www.direktesport.no')
418
- .withAccessFeatures(['sport_premium'])
419
424
  .requestAccess()
420
425
  .then(({ isLoggedIn, hasAccess, primarySite, accessFeatures }) => {
421
426
  console.log({ isLoggedIn, hasAccess, primarySite, accessFeatures });
@@ -435,23 +440,30 @@ new SiteAccessRequest()
435
440
  });
436
441
  ```
437
442
 
438
- Note that this might result in redirects/reloads if the user is not already logged in. In that case you will end up here again if logging in did not result in access.
443
+ Note that this might result in redirects/reloads if the user is not already logged in. In that case you will end up here
444
+ again if logging in did not result in access.
439
445
 
440
446
  ### Known limitations
441
447
 
442
- Subscription activation can only happen against the subscription system related to the `withSiteDomain`. #team-abo will need to look into activation across all subscription systems to improve this behavior.
448
+ Subscription activation can only happen against the subscription system related to the `withSiteDomain`. #team-abo will
449
+ need to look into activation across all subscription systems to improve this behavior.
443
450
 
444
451
  ## Performance
445
452
 
446
- This app aims to be able to deliver a lot of data fast. Still, we might need to call several services in order to get what you need. We do try to cache whenever this makes sense, but please don't ask for data you don't need.
453
+ This app aims to be able to deliver a lot of data fast. Still, we might need to call several services to get what you
454
+ need. We do try to cache whenever this makes sense, but please don't ask for data you don't need.
447
455
 
448
456
  # Behind the scenes
449
457
 
450
- There are a few techniques used to avoid overfetching and fetching multiple times when once would do.
458
+ There are a few techniques used to avoid over-fetching and fetching multiple times when once would do.
451
459
 
452
460
  ## Event-based actions
453
461
 
454
- Much like [node-userdata-browser/userdata-client](https://github.com/amedia/node-userdata-browser) did, we utilize events to message that data is being requested. This allowed us to decouple your request from the particular instance that will serve it. That in turn allows us to have this library loaded by multiple different components across the page, and only process the requests one place. In addition, if the component that's currently processing requests should be unloaded for whatever reason, one of the other instances will automatically take over.
462
+ Much like [node-userdata-browser/userdata-client](https://github.com/amedia/node-userdata-browser) did, we use events to
463
+ message that data is being requested. This allowed us to decouple your request from the particular instance that will
464
+ serve it. That in turn allows us to have this library loaded with multiple different components across the page and only
465
+ process the requests in one place. In addition, if the component currently processing requests should be unloaded for
466
+ whatever reason, one of the other instances will automatically take over.
455
467
 
456
468
  ## Request de-duping
457
469
 
@@ -459,7 +471,7 @@ Since we now process from a single instance of the package it's easy to avoid fe
459
471
 
460
472
  ## Caching
461
473
 
462
- @amedia/user has a caching layer that easily let ut switch out the caching mechanism.
474
+ @amedia/user has a caching layer that easily lets us switch out the caching mechanism.
463
475
  We have two strategies:
464
476
 
465
477
  - SessionStorage: (to survive page loads) Used if available.
@@ -467,45 +479,6 @@ We have two strategies:
467
479
 
468
480
  ## Debugging
469
481
 
470
- If you're curious about calls, response times etc, there is a debug flag you can set on the URL `debug=something`. If you'd like it to survive page loads, you can add a key to localStorage or sessionStorage: `localStorage.setItem('amedia-user:debug', 'something')`
471
-
472
- # Contributing to @amedia/user
473
-
474
- Hey, thanks! :)
475
-
476
- It's often nice to do development while testing on a real app. You may do so using `npm link`. When you run then `npm run build` (or `npm run dev` if you want to watch for changes and build automatically) this will expose actual code, letting you develop faster. This is because we still export index.js from the package, but replaces its content with an error if used directly.
477
-
478
- PS: Remember to comment-out the module in import maps ;-)
479
-
480
- ## Testing live
481
-
482
- You can test your version live by utilizing a browser extension like Requestly or similar. Run `npm run dev` (which will build and watch for changes locally _and_ starts a webserver listening on localhost:9999). Then add a rule in the extension that replaces requests for @amedia/user/v0/index.js with http://localhost:9999/user.js. Now reload and watch your wonderful change do its thing.
483
-
484
- ## Publishing new versions
485
-
486
- ### Creating a new version
487
-
488
- We use [Changesets](https://github.com/changesets/changesets/tree/main#readme).
489
-
490
- 1. `npx changeset`
491
- 2. Follow the instructions
492
- 3. Add the changeset `git add .changeset`
493
- 4. Commit and push
494
-
495
- After merging a release PR will be created/updated (given that tests pass).
496
- Merging this will push a new version to assets.acdn.no.
497
-
498
- ## Deploying
499
-
500
- **First snap then prod**:
501
- If amedia/user breaks in prod it may take down 100+ newspapers entirely,
502
- so please test on snap first :)
503
-
504
- We use [importmaps](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) as a means for deployment: https://github.com/amedia/importmap.
505
- Follow the readme there for the current deployment practice.
506
-
507
- Until we shut down eikserver, it's nice to have a valid alias should the
508
- newly created importmap and ESI-trickery fail:
509
-
510
- 1. https://github.com/amedia/amedia-user-js/actions/workflows/deploy.yml
511
- 2. Run that workflow. If what you want is to update the latest alias with the latest version, you can leave the fields empty.
482
+ If you're curious about calls, response times, etc., there is a debug flag you can set on the URL `debug=something`. If
483
+ you'd like it to survive page loads, you can add a key to localStorage or sessionStorage:
484
+ `localStorage.setItem('amedia-user:debug', 'something')`
package/package.json CHANGED
@@ -3,9 +3,10 @@
3
3
  "description": "Client lib for working with aID user and associated data",
4
4
  "repository": "https://github.com/amedia/amedia-user-js",
5
5
  "author": "Amedia Produkt og Teknologi AS (https://amedia.no)",
6
- "version": "1.0.0",
6
+ "version": "1.0.3",
7
7
  "type": "module",
8
8
  "types": "./index.d.ts",
9
+ "private": false,
9
10
  "exports": {
10
11
  ".": {
11
12
  "types": "./index.d.ts",
@@ -28,7 +29,7 @@
28
29
  }
29
30
  },
30
31
  "scripts": {
31
- "prepublishOnly": "cp ../../README.md . && cp ../../CHANGELOG.md .",
32
- "postpublish": "(cd ../../ && npm run build) && npx @eik/cli publish && rm README.md && rm CHANGELOG.md"
32
+ "prepublishOnly": "(cd ../../ && npm run build) && cp ../../dist/user.d.ts .",
33
+ "postpublish": "npx @eik/cli publish && rm user.d.ts"
33
34
  }
34
35
  }