Iris-ng-services NPM

Iris Angular Services Library (Beta)

A library containing services to help you build Angular applications that run on the Iris API.

Installation
AuthService
ApiService
Patch Notes

Installation

1. Download the package:

npm install --save iris-ng-services

2. Import the IrisNgServicesModule into your application's module:

import { IrisNgServicesModule, ApiService, AuthService } from 'iris-ng-services';

Note: You will also need to import ApiService and AuthService for step 3

3. Inject IrisNgServicesModule and configure the ApiService and AuthService:

@NgModule({
  declarations: [],
  imports: [
    IrisNgServicesModule
  ],
  providers: [
    [ApiService, 
      {provide: 'api_url', useValue: 'API_URL'}
    ],
    [AuthService, 
      {provide: 'api_url', useValue: 'API_URL'} 
    ]
  ],
  bootstrap: [AppComponent]
})

API URLS

You may use the following API URLs (as strings) in the 'API_URL' field in the example above:

1. 'https://api.iris-oc.com/' - API to use for production (i.e., Iris's Live API)

2. 'https://testapi.iris-oc.com/' - API to use for development purposes (defaults to this)

3. 'https://sandbox.iris-oc.com/' - A sandbox API that is the last-backed-up version of Iris's Live API for use with testing the Live API before deployment

4. 'http://localhost:9000/' - Only available to developers with internal access

AuthService

Before you can use the methods provided by the AuthService, you need to import the service and reference it:

import { AuthService } from 'iris-ng-services';

...
export class SampleComponent {
  constructor(
    private irisAuth: AuthService
  ) {}

Login

AuthService.login(login: LoginObject)
  .subscribe(
    next => {}, // Handle success (optional)
    error => {} // Handle error (optional)
  );

// LoginObject's required format (for reference):
interface LoginObject {
  email: string;
  password: string;
}

This method is an observable and requires you to subscribe to it when running. Successful login will automatically set the client application's local storage with an access token, expiration time for the token and basic user information. Various errors may return--e.g. invalid email or password. Be sure to handle these errors (e.g., Redirect back to form, notify user of their error, etc.).

Signup

Create an account and default documents on the Iris API for a new user

AuthService.signup(signup: SignupObject)
  .subscribe(
    next => {}, // Handle success (optional)
    error => {} // Handle error (optional)
  );

// SignupObject's required format (for reference):
interface SignupObject {
  username: string;
  email: string;
  password: string;
  accountType: string; // 'member' or 'organization'
}

Similar to the login method above, this method is an observable that requires you to subscribe to it when running. Successful signup will automatically set the client application's local storage with an access token, expiration time for the token and basic user information. Various errors may return--e.g., invalid username, email or password. Be sure to handle the errors.

Check Email

Check on the Iris API if an email address is available to use

AuthService.checkEmail(email: string)
  .subscribe(
    next => {}, // Handle success (email available) (optional)
    error => {} // Handle error (optional)
  );

This method checks the availability of a given email. It is meant to be used for form validation. A success response means that a provided email is available for use. Various errors may return--e.g., an email is invalid or taken. Check the error message returned for more details.

Check Username

Check on the Iris API if a username is available to use

AuthService.checkUsername(username: string)
  .subscribe(
    next => {}, // Handle success (username available) (optional)
    error => {} // Handle error (optional)
  );

This method checks the availability of a given username. It is to be used for form validation. A success response means that a provided username is available for use. Various errors may return--e.g., username is invalid or taken. Check the error message returned for more details.

Change Username

Change Iris Member ID associated with a user's account

AuthService.changeUsername(object: ChangeUsername)
  .subscribe(
    next => {}, // Handle success (optional)
    error => {} // Handle error (optional)
  );

// ChangeUsername object's required format (for reference):
interface ChangeUsername {
  newUsername: string;
  password: string;
}

This method sends a request to change username and will only work if the user is currently logged in. This is an expensive operation on the API and can only be performed once per month. The method requires a password to authorize and will reauthenticate the user with a new access token,expiration time for the access token, and basic user info with the new username. Various errors may return--e.g., the username is taken or invalid or the password is wrong or invalid. Check error messages for more details.

Change Email

Change primary email address associated with a user's account

AuthService.changeEmail(object: ChangeEmail)
  .subscribe(
    next => {}, // Handle success (optional)
    error => {} // Handle error (optional)
  );

// ChangeEmail object's required format (for reference):
interface ChangeEmail {
  newEmail: string;
  password: string;
}

This method sends a request to change email and will only work if the user is currently logged in. The method requires a password to authorize the change and will replace basic user info with the new email. Various errors may return--e.g., the email is taken or invalid. Check error messages for more details.

Change Password

Change the login password associated with a user's account

AuthService.changePassword(object: ChangePassword)
  .subscribe(
    next => {}, // Handle success (optional)
    error => {} // Handle error (optional)
  );

// ChangePassword object's required format (for reference):
interface ChangePassword {
  newPassword: string;
  currentPassword: string;
}

This method sends a request to change password and will only work if the user is currently logged in. The method requires the currentPassword to be passed with the newPassword to authorize the change. Various errors may return--e.g., the password is invalid or too weak. Check error messages for more details.

Reset Password

Request an email with a link to reset password

AuthService.resetPassword(email: string)
  .subscribe(
    next => successHandler(), // Handle success your own way
    err => errorHandler() // Handle error your own way
  );

Request to change password. This method does not require a user to be logged in but requires a valid email address (String) to be passed as a parameter. A time-sensitive email will then be sent to the provided email address to access the password change portal. Various errors may return--e.g., the provided email does not exist in Iris's database. Check error messages for more details.

Verify Email

Request an email with a link to verify the email

AuthService.resetPassword()
  .subscribe(
    next => successHandler(), // Handle success your own way
    err => errorHandler() // Handle error your own way
  );

Request to verify email. This method does not take in any parameters but requires a user to be logged in so that the verification email can be sent to the user's primary email. An email will then be sent to the user's primary email address with a link to verify the email. Various errors may return. Check error messages for more details.

Logout

Delete the session on the client side and notifies Iris API

AuthService.logout()

This method to clears the authenticated session and notifies the API that user has logged out.

Check Authentication

Return a boolean for user's login status

AuthService.isAuthenticated()

Returns a boolean to check if session is active. Use this method to confirm that user is logged in/out. If the session is expired (after 24 hours), then the session is cleared and method returns false. If user is active, method will return true.

This method is also useful for rendering different views in your application. For example, you can render a login button or logout button.

// sample.component.ts
...
export class SampleComponent {
  constructor(
    private irisAuth: AuthService
  ) {}

  userLoggedIn() {
    return this.irisAuth.isAuthenticated();
  }
}

// sample.comonent.html
...
<button id="login" *ngIf="!userLoggedIn()"></button>
<button id="logout" *ngIf="userLoggedIn()"></button>

Get User Info

Return basic user information

AuthService.getUserInfo()

Returns:
{
  email: String,
  emailVerified: Boolean,
  username: String,
  accountType: String,
  nameCasing: String or null,
  newUser: Boolean
}

Returns a logged in user's information as an object with email and username properties. Will only work if there is an active session for the user. Otherwise, a null will be returned.

Get User's Permissions

Return a boolean for admin status

AuthService.getUserPermissions()

This returns the admin status of a user as a boolean. The admin privilege is handled through the Iris API, so you must contact an Iris developer to provide your account with admin status.

Master Delete (DANGER!)

Delete user's account and all associated documents on the Iris API

AuthService.masterDelete()
  .subscribe(
    next => successHandler(), // Handle success your own way
    err => errorHandler() // Handle error your own way
  )

Use this method with caution. This is a delete all method that will delete the user and all traces of her/his documents on Iris's API. This method will only work when a user is logged in. Once this method returns successfully, there will be no further traces of the user on the Iris API and user will be logged out from client app. If any documents or user fails to delete, the method returns an error. Inspect errors for more details.

ApiService

Before you can use the methods provided by the ApiService, you need to import the service and reference it:

import { ApiService } from 'iris-ng-services';

...
export class SampleComponent {
  constructor(
    private irisApi: ApiService
  ) {}

NOTES ABOUT API SERVICE:

Some of the methods will require authentication/authorization or an unauthorized error response will be returned from the server.
The Iris database contains a special collection of documents called Collections. Thus, to prevent naming confusion for Iris Developers, the term model is used in place of collection in this documentation to refer to the name of a database collection.

Count Documents

Counts all documents with given model name and with (optional)specific params

ApiService.count(model: string, params: object)

This is useful in situations where documents are displayed and queried using infinite scrolling. Having a count of all the total documents will prevent duplication on the last documents in a collection after they've already been queried for.

List All

List all document with a given model name

ApiService.listAll(model: string, modifiers?: object)

Lists all documents associated with the model provided (as a string) and optional modifiers parameter as an object.

More information on the modifier object will be made available soon.

Get By ID

Get specific document(s) by document ID(s)

ApiService.getById(model: string, id: string)

Get a specific document by its model and id. The id could also support multiple id strings separated by ',' or '|' to query for multiple documents in one query.

Filter Document

Granular filter that finds specific document(s) based off query and (optional) modifier parameters

ApiService.getByFilter(
  model: string,
  query: object,
  modifiers?: object
)

A loosely defined query method that will search a target document model that matches all the key-value pairs provided in the query object. An optional modifiers object will allow you to modify how the data are returned. Compared to getByQueryObjects() (see bellow), this method is limited to searching only by an and operator between each key you pass in--each key targeting a field on a document model you're searching. However, the benefit of this method is that it allows for a much more granular search on the search value (more on this and how Iris's search query works later).

Query Objects

Basic filter that finds specific document(s) based off query objects

ApiService.getByQueryObjects(
  model: string,
  queryStrict: object,
  queryLoose: object
)

This is quite similar to .getByFilter(), but not as granular in searching values. It searches without modifiers. Additionally, it allows searching with or operators as well as and operators using queryLoose and queryStrict, respectively. Combining both will naturally search with an and operator between queryLoose and queryStrict, which is a rare instance and provides an even stricter search where all results must match queryLoose AND queryStrict

-queryStrict: Returned document(s) have to match ALL specified parameters. Pass in null to bypass and search by queryLoose only. -queryLoose: Returned document(s)only have to match AT LEAST 1 of the specified parameters. Pass in null to bypass and search by queryStrict only.

Create Document

Create a new document for a given model name

ApiService.create(
  model: string,
  data: object
)

Create a new document under a specified model.

Create Child Document

Create a document as a child of a parent document

ApiService.createChild(
  model: string,
  data: object,
  parentModel: string,
  parentId: string
)

Create a document as a child of another document.

Replace (Put)

Replace a document with new data

ApiService.replace(
  model: string,
  id: string,
  data: object
)

Replaces a document's data with new data using the HTTP put method. Use with caution as this uses a PUT request, meaning the whole document will be replaced by the JSON object you send with your request. Pay attention to all fields of the JSON you send.

Patch (Update)

Patch specific sections of a document with new data

ApiService.patch(
  model: string,
  id: string,
  field: string,
  data: object
)

Update a section of document with new values depending on what field you target. Use dot notation for the field to be more specific:

From broad to specific field strings:
- 'contentData' > 'contentData.orgName' > 'contentData.orgName.value'

Use with caution--make sure to provide all other fields at the same object level with values or they will be reset to default. Uses the HTTP patch method.

Delete

Delete a document by its ID

ApiService.deleteDocument(
  model: string,
  id: string
)

Delete a document matching a model and id.

Patch Notes:

###v0.7 (Latest Stable)

v0.7.0: AuthService has been rewritten with the release of the new Iris Authentication system on the Iris API. Some methods have been introduced to AuthService while others are no longer available in this release. Please view the documentation on AuthService for more info. Also, minor bugs were also addressed on the ApiService.
v0.7.1: Removed unnecessary third-party dependencies from library
v0.7.2: Updated README file
v0.7.3: Renamed variable within AuthService

###v0.6 (Deprecated December, 2018)

v0.6.0: Changes to ApiService to accommodate the new changes to the Iris API's new query methods. This will break ALL previous versions. Additionally, if you are using any versions prior to v0.6.0, you will not be able to properly utilize the Iris API.
v0.6.1: AuthService updated to support authentication for Iris's Sandbox API and to improve the handleAuthentication() method by implementing Observables. This gives more control to applications such as Iris's Login App that are using this method to proceed with rendering the appropriate interface.
v0.6.2: Bug fixes to handleAuthentication() method of AuthService
v0.6.3: Added developerLogin() functionality for developers
v0.6.4: Added a count() functionality to ApiService
v0.6.5: Updated count() on ApiService to accept query parameters
v0.6.6: Made a name_casing available for user_info to keep a record of original username entered with original uppercased/lowercased letter
v0.6.7: Removed postMessage after handleAuthentication completes and set logout() method to remove only associated user credentials in local storage
v0.6.8: Removed reload functionality from AuthService logout()

###v0.5 (Deprecated Aug, 2018)

v0.5.0: AuthService's direct login and signup features have been improved with the implementation of rxjs observables, allowing for direct error handling from within an application. Successful authentication request will redirect immediately back to your app. Using direct login and signup the old way will not work with this version of iris-ng-services because no subscription was required in the old way.
v0.5.1: Added change password functionality to AuthService and revised README documentation
v0.5.4: Stylistic changes to README
v0.5.5: Removed unusued getCollection() method from ApiService and updated and cleaned up dependencies for AuthService

###v0.4 (Deprecated July, 2018)

v0.4.0: AuthService now supports direct login/signup methods to skip authentication interface
v0.4.1: AuthService direct login/signup methods' paramters provided with interfaces to specify the required fields for better error notifications
v0.4.2: AuthService provided with a default that supports legacy login/signup form

###v0.3 (Deprecated July, 2018)

v0.3.0: AuthService now allows developers to configure the authentication credentials
v0.3.1: Cleaned up code

###v0.2 (Deprecated July, 2018)

v0.2.0: First stable version released interally to developers with all API endpoints and Authentication flow available for all Iris's apps
v0.2.1: Changes made to Authentication and API services to accommodate improvements on the API to support the creation of default documents for first-time users
v0.2.2: Reverted services to disable default creation, which is now completely handled on the backend without needing to call the API through these services
v0.2.3: Update to Iris Auth Service to store previous state of an app to more seemlessly redirect user after login or return user from a cancelled login
v0.2.4: Updated README
v0.2.5: Added dev_apps environment for Authentication of all Iris apps and revised README
v0.2.6: Modified behavior of authentication to return null for no authentication
v0.2.7: Reconfigured AuthService to better support an in-app authentication flow, removed rerouting functionality completely, and updated authentication configurations
v0.2.8: Changed the auth configurations for web_dev (development site)
v0.2.9: Addressed bug in auth configurations for web_dev
v0.2.10: Changed the auth configurations for web_public (public site)
v0.2.11: Resolved bug with auth configurations