docs: improve documentation

.gitlab-ci.yml

@@ -21,9 +21,9 @@ prepare:
 
 test:
   stage: test
-  image: selenium/node-chrome
+  image: psafont/angular-cli_build
   script:
-    - yarn test:sr
+    - yarn test:sr:chromium
   artifacts:
     paths:
       - coverage/

CONTRIBUTING.md

 # Contributing to angular-aap-auth
 
-Thanks for your willingness to contribute and help to the angular-aap-auth
-library.
+Thanks for your willingness to contribute to the angular-aap-auth library.
 
 ## Setup
 
@@ -38,8 +37,7 @@ npm -i
 ## Development server
 
 Run `ng serve` for a dev server. Navigate to `http://localhost:4200/`. The app
-will automatically reload if you change any of the source files.  It is
-recommended to use the git hooks provided:
+will automatically reload if you change any of the source files.
 
 ## Build library
 

README.md

-# NgAapAuth
+# angular-aap-auth
 
-This project was generated with [Angular CLI](https://github.com/angular/angular-cli) version 1.6.6.
+[![test and build status](https://gitlab.ebi.ac.uk/tools-glue/angular-aap-auth/badges/master/build.svg)](https://gitlab.ebi.ac.uk/tools-glue/angular-aap-auth/commits/master 'test and build status')
+[![coverage report](https://gitlab.ebi.ac.uk/tools-glue/angular-aap-auth/badges/master/coverage.svg?job=test)](https://gitlab.ebi.ac.uk/tools-glue/angular-aap-auth/commits/master)
+[![npm version](https://badge.fury.io/js/angular-aap-auth.svg)](https://www.npmjs.com/package/angular-aap-auth)
+[//]: # (shiels.io is slow: [![npm version](https://img.shields.io/npm/v/angular-aap-auth)](https://www.npmjs.com/package/angular-aap-auth))
+[![npm downloads](https://img.shields.io/npm/dm/angular-aap-auth.svg)](https://www.npmjs.com/package/angular-aap-auth)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-## Development server
+The angular-aap-auth is a simple authentication Angular library that relies on
+EBI's Authentication and Authorization Profile (AAP) infrastructure. After
+successful login, a JWT token is stored on the browser (via cookie, local or
+session storage).
 
-Run `ng serve` for a dev server. Navigate to `http://localhost:4200/`. The app will automatically reload if you change any of the source files.
+## Want to help?
 
-## Code scaffolding
+Want to file a bug, contribute some code, or improve documentation? Excellent!
+Read up on our guidelines for [contributing][contributing].
 
-Run `ng generate component component-name` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module`.
+## Installation
 
-## Build
+To install this library, run:
 
-Run `ng build` to build the project. The build artifacts will be stored in the `dist/` directory. Use the `-prod` flag for a production build.
+```
+npm install angular-aap-auth --save
 
-## Running unit tests
+or
 
-Run `ng test` to execute the unit tests via [Karma](https://karma-runner.github.io).
+yarn add angular-aap-auth
+```
 
-## Running end-to-end tests
+## Consuming the library
 
-Run `ng e2e` to execute the end-to-end tests via [Protractor](http://www.protractortest.org/).
+In your Angular `AppModule` (app.module.ts):
 
-## Further help
+```typescript
+import {
+    BrowserModule
+} from '@angular/platform-browser';
+import {
+    NgModule
+} from '@angular/core';
 
-To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI README](https://github.com/angular/angular-cli/blob/master/README.md).
+import {
+    AppComponent
+} from './app.component';
+import {
+    AuthModule
+} from './modules/auth/auth.module';
+
+@NgModule({
+    declarations: [
+        AppComponent
+    ],
+    imports: [
+        BrowserModule,
+        AuthModule.forRoot(),
+    ],
+    providers: [
+    ],
+    bootstrap: [AppComponent]
+})
+export class AppModule {}
+```
+
+The default configuration uses localStorage to save the JWT token under the key
+'id_token'. See [Advance usage](Advance usage) for a more fine grained configuration.
+
+Example use on a component:
+
+```typescript
+import {
+    Component,
+    OnInit
+} from '@angular/core';
+import {
+    Observable,
+} from 'rxjs/Observable';
+import {
+    map
+} from 'rxjs/operators';
+
+import {
+    AuthService,
+} from 'angular-aap-auth/auth.service';
+
+@Component({
+    selector: 'app-root',
+    template: `<h1>Welcome</h1>
+    <button (click)="auth.windowOpen()">Login small window</button>
+    <button (click)="auth.tabOpen()" target="_blank">Login new tab</button>
+    <button (click)="auth.logOut()" target="_blank">Logout</button>
+
+    <p>Authenticated: {{ isAuthenticated|async }}</p>
+    <p>Real name: {{ realname|async }}</p>
+    <p>Username: {{ username|async }}</p>
+    <p>Token: {{ token|async }}</p>
+    `
+})
+export class AppComponent implements OnInit {
+    username: Observable < string | null > ;
+    realname: Observable < string | null > ;
+    token: Observable < string | null > ;
+    isAuthenticated: Observable < string > ;
+
+    constructor(
+        // Public for demonstration purposes
+        public auth: AuthService,
+    ) {
+        this.username = auth.username();
+        this.realname = auth.realname();
+        this.token = auth.token();
+
+        this.isAuthenticated = (auth.isAuthenticated()).pipe(
+            map(value => value && 'true' || 'false')
+        );
+    }
+
+    ngOnInit() {
+        this.auth.addLogInEventListener(() => console.log('Welcome'));
+        this.auth.addLogOutEventListener(() => console.log('Bye'));
+    }
+}
+```
+
+## Advance uses
+
+Advance module configuration:
+
+```typescript
+import {
+    BrowserModule
+} from '@angular/platform-browser';
+import {
+    NgModule
+} from '@angular/core';
+
+import {
+    AppComponent
+} from './app.component';
+import {
+    AuthModule
+} from './modules/auth/auth.module';
+
+export function getToken(): string {
+    return localStorage.getItem('jwt_token') || '';
+}
+export function removeToken(): void {
+    return localStorage.removeItem('jwt_token');
+}
+export function updateToken(newToken: string): void {
+    return localStorage.setItem('jwt_token', newToken);
+}
+
+@NgModule({
+    declarations: [
+        AppComponent
+    ],
+    imports: [
+        BrowserModule,
+        AuthModule.forRoot({
+            aapURL: 'https://api.aai.ebi.ac.uk',
+            tokenGetter: getToken,
+            tokenUpdater: updateToken,
+            tokenRemover: removeToken,
+        }),
+    ],
+    providers: [
+    ],
+    bootstrap: [AppComponent]
+})
+export class AppModule {}
+```
+
+Example on how to get specific claims:
+
+```typescript
+import {
+    Component,
+    OnInit
+} from '@angular/core';
+import {
+    Observable,
+} from 'rxjs/Observable';
+import {
+    map
+} from 'rxjs/operators';
+
+import {
+    AuthService,
+} from 'angular-aap-auth/auth.service';
+
+// Only need to inspect other claims in the JWT token
+import {
+    TokenService,
+} from 'angular-aap-auth/token.service';
+
+@Component({
+    selector: 'app-root',
+    templateUrl: './app.component.html',
+    styleUrls: ['./app.component.css']
+})
+export class AppComponent implements OnInit {
+    username: Observable < string | null > ;
+    realname: Observable < string | null > ;
+    token: Observable < string | null > ;
+
+    // How to obtain other claims
+    expiration: Observable < Date | null > ;
+
+    constructor(
+        // Public for demonstration purposes
+        public auth: AuthService,
+        private jwt: TokenService
+    ) {
+        this.username = auth.username();
+        this.realname = auth.realname();
+        this.token = auth.token();
+
+        this.expiration = this.token.pipe(
+            map(token => {
+                try {
+                    return jwt.getTokenExpirationDate(<string>token);
+                } catch (e) {
+                    return null;
+                }
+
+            })
+        );
+    }
+
+    ngOnInit() {
+        // Demonstration of register and unregister login events
+        this.auth.addLogInEventListener(() => console.log('Welcome'));
+        const firstEventID = this.auth.addLogInEventListener(() => console.log('This should not be visible'));
+        this.auth.removeLogInEventListener(firstEventID);
+        this.auth.addLogInEventListener(() => alert('Welcome'));
+        const secondEventID = this.auth.addLogInEventListener(() => alert('This should never be displayed'));
+        this.auth.removeLogInEventListener(secondEventID);
+
+        // Demonstration of register and unregister logout events
+        this.auth.addLogOutEventListener(() => console.log('Bye'));
+        const thirdEventID = this.auth.addLogOutEventListener(() => console.log('This should not be visible'));
+        this.auth.removeLogOutEventListener(thirdEventID);
+        this.auth.addLogOutEventListener(() => alert('Bye'));
+        const fourthEventID = this.auth.addLogOutEventListener(() => alert('This should never be displayed'));
+        this.auth.removeLogOutEventListener(fourthEventID);
+    }
+}
+```
+
+## License
+
+Apache 2.0 © [EMBL - European Bioinformatics Institute](https://www.ebi.ac.uk/about/terms-of-use)
+[contributing]: http://github.com/angular/angular/blob/master/CONTRIBUTING.md

karma.conf.js

@@ -15,7 +15,7 @@ module.exports = function (config) {
       clearContext: false // leave Jasmine Spec Runner output visible in browser
     },
     coverageIstanbulReporter: {
-      reports: [ 'html', 'lcovonly' ],
+      reports: [ 'text-summary', 'text', 'html', 'lcovonly' ],
       fixWebpackSourcePaths: true
     },
     angularCli: {

package.json

@@ -8,6 +8,7 @@
         "build": "ng build --prod --aot",
         "test": "ng test --config=karma_chrome.conf.js",
         "test:sr": "ng test --progress=false --single-run=true --code-coverage=true",
+        "test:sr:chromium": "ng test --progress=false --single-run=true --code-coverage=true --config=karma_chromium.conf.js",
         "lint": "ng lint --type-check",
         "e2e": "ng e2e",
         "packagr": "ng-packagr -p ng-package.json"