@amedia/user 0.14.43 → 0.14.45

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.
package/README.md CHANGED
@@ -6,11 +6,13 @@ The goal of this module is to simplify the usage of aID data and services in Ame
6
6
 
7
7
  An important requirement for this module is Eik. When used in production, this module should always be loaded from an alias in Eik. This is to ensure that all components on a page that uses this module will use same version. The normal way to load the module from Eik is through import maps.
8
8
 
9
+ This module is owned by Team aID. If you, after having read this file, have any questions or comments; we are happy to help on slack #team-aid
10
+
9
11
  # Usage
10
12
  Please be advised that you are required to use ESM in order to use this module.
11
13
 
12
14
  ## Importing the module
13
- Add this module to your project by running `npm install -d @amedia/user`. This will allow for type-hinting, but will not include any code. This means you must also set up import maps for loading the actual code. Just point `@amedia/user` to `https://assets.acdn.no/pkg/@amedia/user/v0/user.js`.
15
+ Add this module to your project by running `npm install -d @amedia/user`. This will allow for type-hinting, but will not include the implementation. This means you must also set up import maps for loading the actual code. Just point `@amedia/user` to `https://assets.acdn.no/pkg/@amedia/user/v0/user.js`.
14
16
 
15
17
  See Ego, Bacchus or Saturn for examples on how to use this module through Eik.
16
18
 
@@ -29,45 +31,34 @@ When your source code is bundled together for production, it's important that th
29
31
 
30
32
  You can read more about Eik on [Slite](https://amedia.slite.com/app/channels/hOlqx3Miez/notes/iexhL4MZn3).
31
33
 
32
- ## Contributing to @amedia/user
33
- Hey, thanks! :)
34
-
35
- 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 user.js from the package, but replaces it content with an error if used directly.
36
-
37
- PS: Remember to comment-out the module in import maps ;-)
38
-
39
- ### Testing live!
40
- 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/user.js with http://localhost:9999/user.js. Now reload and watch your wonderful change do its thing.
41
-
42
34
  ## Getting user data
43
35
  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.
44
36
 
45
- To get user data you first need to create a `UserDataRequest`, then you specify what data you need and once that is done, you decide if you want to wait until all data is available, or you want to get partial updates.
37
+ To get user data you first need to create a `new UserDataRequest()`, 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.
46
38
 
47
- This module tries to simplify the model representing various data about the user. We have introduced (and re used) some concepts that are listed here.
39
+ This module tries to simplify the model representing various data about the user. We have introduced (and re-used) some concepts that are listed.
48
40
 
49
41
  ### Data model
50
42
  #### Attributes
51
43
  Attributes are data directly related to the user, with the exception of access. Supported attributes are:
52
- - uuid (string): The user's unique ID
53
- - name (string): User's full name
54
- - trackingKey (string): Unique ID of user that can be used for tracking (pseudonym)
55
- - access (list of strings): User's access on current site (list of access features)
56
- - extraData (dynamic object): Data that has been modelled about the user (gender, ad segments etc. from Nebula)
57
- - privacyPreferences (privacy preferences object): Privacy preferences set on Min aID.
44
+
45
+ | name | type | description |
46
+ |--------------------|---------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------|
47
+ | uuid | string | The users unique ID. (NOT for tracking) |
48
+ | name | string | Users full name |
49
+ | trackingKey | string | Unique ID of user that can be used for tracking (pseudonym) This is also known as the legacy name user_key |
50
+ | access | Array<string> | Users access on current site (list of access features) |
51
+ | extraData | Record<string,unknown> | Data that has been modelled about the user (gender, ad segments etc. from Nebula) |
52
+ | privacyPreferences | [PrivacyPreferences](https://github.com/amedia/amedia-user-js/blob/master/src/types.ts#L16) | Privacy preferences set on Min aID. |
58
53
 
59
54
  Attributes are requested by calling `.withAttributes()` on a `UserDataRequest` with a list of the attributes you need.
60
55
 
61
56
  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.
62
57
 
63
- Privacy preferences contains the following boolean attributes:
64
- - allowResearchUsage
65
- - connectWithSurveys
66
- - personalizedAds
67
- - personalizedContent
68
-
69
58
  NOTE: Fetching each attribute has a cost, so keep the list to a minimum. Don't request attributes you don't really need.
70
59
 
60
+ 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.
61
+
71
62
  #### Storage
72
63
  Storage are namespaces stored in 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.
73
64
 
@@ -79,11 +70,14 @@ In the response, `storage` is an object with each namespace as an attribute whic
79
70
  State is meant 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.
80
71
 
81
72
  Current attributes in `state`:
82
- - isLoggedIn (boolean): Is the user currently logged in? If not, most attributes will be undefined
83
- - emergencyMode (list of strings): Current state of emergency mode in production environment (paywall, aid etc.)
73
+
74
+ | name | type | description |
75
+ |---------------|---------------|-------------------------------------------------------------------------------|
76
+ | isLoggedIn | boolean | Is the user currently logged in? If not, most attributes will be undefined |
77
+ | emergencyMode | Array<string> | Current state of emergency mode in production environment (paywall, aid etc.) |
84
78
 
85
79
  ### Executing the request
86
- 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 updates or wait until everything is ready and get everything in one package.
80
+ 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.
87
81
 
88
82
  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.
89
83
 
@@ -95,7 +89,7 @@ Full usage example:
95
89
  import { UserDataRequest } from '...';
96
90
 
97
91
  new UserDataRequest()
98
- .withAttributes(['name', 'email'])
92
+ .withAttributes(['name', 'trackingKey'])
99
93
  .withStorage(['my_namespace']) // You might know this as Europa
100
94
  .subscribe(({attributes, state, storage}) => {
101
95
  console.log(attributes, state, storage)
@@ -107,7 +101,7 @@ The callback you supplied to subscribe is called whenever there are any changes
107
101
  Also, your requested properties might not arrive all at once. This callback will be called whenever we get data in from the various services.
108
102
 
109
103
  #### Fetching all the data once (no rerenders)
110
- 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.
104
+ 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.
111
105
 
112
106
  Full usage example:
113
107
  ```ts
@@ -124,12 +118,13 @@ new UserDataRequest()
124
118
 
125
119
  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 resolving the returned promise.
126
120
 
127
- If you really need to render the user's name etc. as fast as possible, use `.subscribe()`, if not, this is probably easier.
121
+ If you really need to render the user's name or get its uuid etc. as fast as possible, use `.subscribe()`, if not, this is probably easier.
128
122
 
129
123
  ##### Timeouts
130
124
  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.
131
125
 
132
- FetchTimeoutError will include any data we might have gotten before we timed out
126
+ _FetchTimeoutError will include any data we might have gotten before we timed out_
127
+
133
128
  ```ts
134
129
  .catch((e) => {
135
130
  if (e instanceof FetchTimeoutError) {
@@ -143,9 +138,58 @@ If you're running a background task and don't mind waiting longer than default (
143
138
  ```ts
144
139
  .fetch({timeout: 60000 /* milliseconds */ })
145
140
  ```
141
+ 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.
142
+
143
+ ## Actions
144
+ The following methods are actions that the user needs to be able to perform in an environment using logged in users.
145
+
146
+ ### `goToLoginPage(requestedUrl: string)`
147
+ This action will 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.
148
+
149
+ You may include a requestedUrl if you need to control where the user should end up after logging in. The default is to send the user back to the current URL where this action was called.
150
+
151
+ ### `logout()`
152
+ 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.
153
+
154
+ ## Updating storage
155
+ If you need to store preferences, favourite teams etc for the user, you can choose between two methods. One will update only the attributes of a namespace that you specify, the other will update everything. The main difference is that if you opt for updating everything, attributes that are present on the backend, but not in the update, will be deleted.
156
+
157
+ ### Update changed values (PATCH)
158
+ The safest way to update a value is to use `updateStorage()`. This will send a `PATCH` to 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.
159
+
160
+ Example of use:
161
+ ```ts
162
+ import { updateStorage } from '...';
163
+
164
+ updateStorage({
165
+ my_namespace: {
166
+ my: 'data'
167
+ }
168
+ });
169
+ ```
170
+
171
+ In the example, only `my` in `my_namespace` would be updated to `data`. If the namespace also contained `{ your: 'loss' }`, this would be kept untouched, so the resulting namespace would now contain `{ my: 'data', your: 'loss' }`.
172
+
173
+ ### Update the entire namespace (PUT)
174
+ If you're not afraid of concurrency issues, or you need to make sure that old attributes are removed, you should use `saveStorage()`. This works in the same way as `updateStorage()`, but it will send a `PUT` to Europa, which will then make sure that attributes that are stored in the namespaces in the request, but are not a part of the request, will be removed.
175
+
176
+ Example of use:
177
+ ```ts
178
+ import { updateStorage } from '...';
179
+
180
+ saveStorage({
181
+ my_namespace: {
182
+ my: 'data'
183
+ }
184
+ });
185
+ ```
186
+
187
+ In the example, `my` in `my_namespace` would be updated to `data`. If the namespace also contained `{ your: 'loss' }`, this would removed, so the resulting namespace would now contain `{ my: 'data' }`.
146
188
 
147
189
  ## Unlocking the paywall
148
- 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 buy subscriptions. The incentive will use a `PaywallUnlockRequest` to see if it can somehow grant access to the user. In some cases it makes sense to create a different user interface for a paywall. In these cases we recommend that you use this `PaywallUnlockRequest` in order to get the same functionality.
190
+ 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.
191
+
192
+ 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.
149
193
 
150
194
  More information about the paywall can be found here: [How the Paywall works](https://amedia.slite.com/app/channels/hOlqx3Miez/notes/UFqOFRV3g1)
151
195
 
@@ -206,52 +250,6 @@ new PaywallUnlockRequest()
206
250
 
207
251
  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.
208
252
 
209
- ## Actions
210
- The following methods are actions that the user needs to be able to perform in an environment using logged in users.
211
-
212
- ### `goToLoginPage(requestedUrl: string)`
213
- This action will 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.
214
-
215
- You may include a requestedUrl if you need to control where the user should end up after logging in. The default is to send the user back to the current URL where this action was called.
216
-
217
- ### `logout()`
218
- 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.
219
-
220
- ## Updating storage
221
- If you need to store preferences, favourite teams etc for the user, you can choose between two methods. One will update only the attributes of a namespace that you specify, the other will update everything. The main difference is that if you opt for updating everything, attributes that are present on the backend, but not in the update, will be deleted.
222
-
223
- ### Update changed values (PATCH)
224
- The safest way to update a value is to use `updateStorage()`. This will send a `PATCH` to 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.
225
-
226
- Example of use:
227
- ```ts
228
- import { updateStorage } from '...';
229
-
230
- updateStorage({
231
- my_namespace: {
232
- my: 'data'
233
- }
234
- });
235
- ```
236
-
237
- In the example, only `my` in `my_namespace` would be updated to `data`. If the namespace also contained `{ your: 'loss' }`, this would be kept untouched, so the resulting namespace would now contain `{ my: 'data', your: 'loss' }`.
238
-
239
- ### Update the entire namespace (PUT)
240
- If you're not afraid of concurrency issues, or you need to make sure that old attributes are removed, you should use `saveStorage()`. This works in the same way as `updateStorage()`, but it will send a `PUT` to Europa, which will then make sure that attributes that are stored in the namespaces in the request, but are not a part of the request, will be removed.
241
-
242
- Example of use:
243
- ```ts
244
- import { updateStorage } from '...';
245
-
246
- saveStorage({
247
- my_namespace: {
248
- my: 'data'
249
- }
250
- });
251
- ```
252
-
253
- In the example, `my` in `my_namespace` would be updated to `data`. If the namespace also contained `{ your: 'loss' }`, this would removed, so the resulting namespace would now contain `{ my: 'data' }`.
254
-
255
253
  ## Performance
256
254
  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.
257
255
 
@@ -259,37 +257,39 @@ This app aims to be able to deliver a lot of data fast. Still, we might need to
259
257
  There are a few techniques used to avoid overfetching and fetching multiple times when once would do.
260
258
 
261
259
  ## Event-based actions
262
- 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. This allows us to have this packed 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.
260
+ 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.
263
261
 
264
262
  ## Request de-duping
265
263
  Since we now process from a single instance of the package it's easy to avoid fetching the same resource multiple times.
266
264
 
267
265
  ## Caching
268
- Tha app has got few caching mechanisms, through local storage and indexeddb
266
+ @amedia/user has a caching layer that easily let ut switch out the caching mechanism, but p.t. we only use it to cache to a global object for the life of the page.
269
267
 
270
- # Publishing new versions
271
- This module can be used both as an Eik module and as a standard NPM module. When publishing new versions, the version needs to be published to both channels.
268
+ ## Contributing to @amedia/user
269
+ Hey, thanks! :)
272
270
 
273
- ## NPM package
274
- To publish a new version to NPM, do the following:
271
+ 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 user.js from the package, but replaces its content with an error if used directly.
275
272
 
276
- - Update version number in `package.json`
277
- - Run `npm publish`
278
- - Commit new versions of `package.json` and `package-lock.json` to master in Git.
273
+ PS: Remember to comment-out the module in import maps ;-)
279
274
 
280
- Now the new version can be installed in a project by running `npm install -u @amedia/user@v<new version>`
275
+ ### Testing live!
276
+ 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/user.js with http://localhost:9999/user.js. Now reload and watch your wonderful change do its thing.
281
277
 
282
- ## Eik
283
- When publishing to Eik you need to take into consideration any breaking API changes. A new version can safely be published to Eik at any time, but when it is given an alias, any client using this alias will get the new version, so any breaking API changes will break all clients. If there are breaking changes a new alias must be created.
278
+ # Publishing new versions
279
+ NB: Please be advised, as with all packages in Eik, that once you update the alias, _every_ place that uses this module will get your version. It's therefore extra important that you don't break the API without creating a new major version! This can cause the front page not to load, users not being able to log in or get access to content they paid good money for etc.
284
280
 
285
- If for some reason we need to update clients using an older alias, we need to create a separate version where the API stays the same as the previous API in the same alias.
281
+ Since not all IDEs, linters etc support import maps and certainly don't support loading types that way, yet; we must publish typings to npm and the implementation to Eik.
282
+ This has been built into the prepublishOnly and postpublish hooks in package.json
286
283
 
287
- The alias version should be the same as the major version of the NPM module.
284
+ 1. Your change is merged to master.
285
+ 2. Checkout and update master.
286
+ 3. Update the version number i both package.json and eik.json.
287
+ 4. Run `npm publish` (will publish to both npm and eik)
288
+ 5. Commit changed files to master.
288
289
 
289
- Before publishing to Eik, you need to be logged in by running `eik/eik-login` in the tools repo.
290
+ Now the new version can be installed in a project by running `npm install -u @amedia/user@v<new version>`
290
291
 
291
- To publish a new version do the following:
292
- - Update version number in `eik.json` to the same version as in `package.json`
293
- - Run `npm run eik:package` (no publishing will be done unless packages passes lint, typings, tests and builds successfully)
292
+ When you are as sure as you can be that you didn't break anything to can update the Eik alias:
294
293
  - Run `npx eik package-alias @amedia/user <version from eik.json> <Alias version>`
295
- Example: `npx eik package-alias @amedia/user 0.13.31 0`
294
+
295
+ Example: `npx eik package-alias @amedia/user 0.13.31 0`
package/dist/user.d.ts CHANGED
@@ -1,15 +1,15 @@
1
1
  import * as rt from 'runtypes';
2
2
 
3
3
  declare type UserAttributes = {
4
- uuid?: string | null;
5
- name?: string | null;
6
- trackingKey?: string | null;
7
- avatar?: string | null;
8
- extraData?: {
4
+ uuid: string | null;
5
+ name: string | null;
6
+ trackingKey: string | null;
7
+ avatar: string | null;
8
+ extraData: {
9
9
  [index: string]: unknown;
10
10
  };
11
- access?: string[];
12
- privacyPreferences?: PrivacyPreferences | null;
11
+ access: string[];
12
+ privacyPreferences: PrivacyPreferences | null;
13
13
  };
14
14
  declare type State = {
15
15
  isLoggedIn: boolean;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@amedia/user",
3
- "version": "0.14.43",
3
+ "version": "0.14.45",
4
4
  "description": "Client lib for working with aID user and associated data",
5
5
  "repository": "https://github.com/amedia/amedia-user-js",
6
6
  "author": "Amedia Utvikling (ID og data)",
@@ -43,17 +43,17 @@
43
43
  "@eik/cli": "^2.0.22",
44
44
  "@eik/esbuild-plugin": "^1.1.7",
45
45
  "@types/jest": "^27.4.1",
46
- "@typescript-eslint/eslint-plugin": "^5.20.0",
47
- "@typescript-eslint/parser": "^5.20.0",
46
+ "@typescript-eslint/eslint-plugin": "^5.21.0",
47
+ "@typescript-eslint/parser": "^5.21.0",
48
48
  "concurrently": "^7.1.0",
49
49
  "cors": "^2.8.5",
50
- "esbuild": "0.14.37",
51
- "eslint": "^8.13.0",
50
+ "esbuild": "0.14.38",
51
+ "eslint": "^8.14.0",
52
52
  "eslint-config-airbnb-typescript": "^17.0.0",
53
53
  "eslint-config-prettier": "^8.5.0",
54
54
  "eslint-plugin-import": "^2.26.0",
55
55
  "eslint-plugin-prettier": "^4.0.0",
56
- "express": "^4.17.3",
56
+ "express": "^4.18.0",
57
57
  "jest": "^27.5.1",
58
58
  "jest-extended": "^2.0.0",
59
59
  "jest-fetch-mock": "^3.0.3",
@@ -63,7 +63,7 @@
63
63
  "rollup": "2.70.2",
64
64
  "rollup-plugin-dts": "4.2.1",
65
65
  "ts-jest": "^27.1.4",
66
- "tslib": "^2.3.1",
66
+ "tslib": "^2.4.0",
67
67
  "typescript": "^4.6.3"
68
68
  }
69
69
  }