@coreo/ionic-core/README.md

# @coreo/ionic-core

Ionic 2+ module for integrating with Coreo.

## Installation
```
npm install @coreo/ionic-core --save
```

Update your Ionic `app.module.ts`:
```
import { CoreoModule } from '@coreo/ionic-core';
...
@NgModule({
    imports: [CoreoModule]
    ...
})
export class AppModule {}
```
### With Configuration

```
import { CoreoModule, CoreoConfig } from '@coreo/ionic-core';
...
const coreoConfig = new CoreoConfig({
    baseUrl: 'https://coreo-dev.herokuapp.com'
});


@NgModule({
    imports: [
        CoreoModule.forRoot(coreoConfig)
    ]
    ...
})
export class AppModule {}
```

Configuration options available:

- `baseUrl`: location of coreo server (leave blank to point to production Coreo server)
- `publicUrl`: location of Coreo main site (leave blank to point to production site)
- `projectId`: ID of project to submit to when using the `CoreoClient`. If you leave this blank, you must send it in the payload of each `CoreoClient` request.
- `googleMapsKey`: API key to use with the Google Maps provider.
- `ionicViewAppId`: App ID to use for Ionic View.
- `googleWebClientId`: ID to use for Google login.

## API

The following services are provided as `@Injectable()`s
### CoreoAuth - Authentication

A thin wrapper around Ionic Native's GooglePlus and Facebook authentication.
Ensure you have installed the relevant plugins and followed the configuration steps in the following documentation:

- Google : https://ionicframework.com/docs/v2/native/google-plus/
- Facebook : https://ionicframework.com/docs/v2/native/facebook/

**NOTE** You must configure your OAuth credentials within Coreo.
Go to Surveys > Your Survey > Credentials and add the relevant data.

```
import { CoreoAuth, CoreoAuthResult } from '@coreo/ionic-core';

@Component({
...
})
export class MyLoginComponent {
    constructor(
        private auth: CoreoAuth
    ) {}

    login(): Promise<CoreoAuthResult> {
        return this.auth.login('basic', { email: 'bob@mail.com', password: 'bob});
        // OR
        // const surveyId = 12;
        // return this.auth.login('google', surveyId);
    }
}
```

#### Methods:
- `login(method: 'basic' | 'google' | 'facebook', params: CoreoAuthLoginOptions)`
- `logout(): void`

#### Types:
- CoreoAuthLoginOptions - If the method is 'basic' then this is an `{email, password}` object, else it is the surveyId you are logging in to.

### CoreoUser - User

#### Properties:
- `isLoggedIn: boolean` - Flag indicating whether the user is logged in or not.
- `id: number` - User ID
- `email: string` - Email
- `role: string` - Role
- `displayName: string` - Display Name
- `imageUrl: string` - Users' profile image URL

### Client

An HTTP client for sending queries and posting data to Coreo. Handles all authentication (if the user is logged in)

```
import { CoreoClient } from '@coreo/ionic-core';

@Injectable()
export class MyDataService {
    constructor(
        private client: CoreoClient
    ) {}

    getData(): Observable<any> {
        return this.client.request('/records?q=surveyId:12');
    }
}
```

### Methods:
- request(path: string, options: CoreoClientRequestOptions = {}) : Observable<any>
- post(path: string, body?: FormData | any, options: CoreoClientRequestOptions = {}) : Observable<any>

### Types:
- CoreoClientRequestOptions
  - `method: string` - HTTP method. Defaults to 'get'
  - `headers?: any` - An Object of HTTP headers
  - `body?: string | FormData | null`
  - `authentication?: CoreoAuthToken | false` - If false, then no authentication header is set (even if the user is logged in).
  If set to a CoreoAuthToken, this token will be used again regardless of the user's logged in token. If `authentication` is not supplied
  then the user's logged in token will be used, if logged in.