Iris-sdk NPM | npm.io

Iris SDK (beta)

A framework-agnostic sdk compatible with most JavaScript/TypeScript frameworks (Angular, React, Vue, and Ember) and plain vanilla JavaScript

The purpose of the Iris SDK is to provide developers with prebuilt services and web components that run on the Iris platform.

Getting Started
Components
- Multiple Framework Support
- List of Components
  - Iris Uploader
API Services
Patch Notes

Getting Started

npm i --save iris-sdk@latest

The Iris SDK contains two modules that can be imported:

iris-sdk/components - a collection of reusable components. More details...
iris-sdk/services - a collection of services that consume the Iris API. More details...

Components

The Components module contains Iris's reusable web components which are intended to be framework agnostic. This means that they can be imported into any front end framework or a plain vanilla JS project.

Multiple Framework Support

Iris's prebuilt web components are compiled using stenciljs, which makes them compatible with plain JS and JS front end frameworks. The method to integrate these prebuilt web components vary. Read more to find out how these components are imported into the most popular JavaScript frameworks.

Angular

In an Angular application, import the CUSTOM_ELEMENTS_SCHEMA in the modules that use the components.

./src/app/app.module.ts

import { BrowserModule } from '@angular/platform-browser';
import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

import { AppComponent } from './app.component';
import { TestComponent } from './test/test.component';

@NgModule({
  declarations: [
    AppComponent,
    TestingComponent
  ],
  imports: [
    BrowserModule
  ],
  providers: [],
  bootstrap: [AppComponent],
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class AppModule { }

Import the defineCustomElements(window) method into the main controller of the app from iris-sdk/components/loader.

./src/main.ts

import { enableProdMode } from '@angular/core';
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';

import { AppModule } from './app/app.module';
import { environment } from './environments/environment';

import { defineCustomElements } from 'iris-sdk/components/loader';

if (environment.production) {
  enableProdMode();
}

platformBrowserDynamic().bootstrapModule(AppModule)
  .catch(err => console.log(err));

defineCustomElements(window);

Call an Iris web component from the list of components above inside the HTML file of a component. For demo purposes, the main app component's HTML was used, but any child component's HTML is compatible as well.

./src/app/app.component.html

<iris-test></iris-test>

React

In a React application, import the defineCustomElements(window) method inside the index.js file. This file is automatically generated through create-react-app.

./src/index.js

import React from 'react';
import ReactDOM from 'react-dom';
import './index.css';
import App from './App';
import registerServiceWorker from './registerServiceWorker';

import { defineCustomElements } from 'iris-sdk/components/loader';

ReactDOM.render(<App />, document.getElementById('root'));
registerServiceWorker();
defineCustomElements(window);

Call an Iris component from the list of components above inside the JSX that is returned in the render method of a component.

render () {
  return (
    <>
      <h1>This works</h1>
      <iris-test/> 
    </>
  )
}

Vue

In a Vue application, import1 the defineCustomElements(window) method inside the main.js file. This file is auto-generated using js-cli (preferrably with ES2015 and WebPack as primary options).

import Vue from 'vue';
import App from './App.vue';
import { defineCustomElements } from 'iris-sdk/components/loader';

Vue.config.productionTip = false;
Vue.config.ignoredElements = [/test-\w*/];

defineCustomElements(window);

new Vue({
  render: h => h(App)
}).$mount('#app');

Call an Iris component from the list of components above inside the HTML template of a Vue component.

Ember

Ember requires installation of the ember-cli-stencil by running the following command in an Ember application:

ember install ember-cli-stencil

This addon will handle the rest of the heavywork so that developers can start using any of the web components listed above in any hbs files. More info here.

JavaScript

For projects written in plain JavaScript with a simple HTML page, Iris components can easily be imported using unpkg. There are two methods to import components:

Method A: Basic approach without ES Modules

<!DOCTYPE html>
<html lang="en">
<head>
  <script src="https://unpkg.com/iris-sdk@latest/components/iris-components.js"></script>
</head>
<body>
  <iris-test></iris-test>
</body>
</html>

Method B: More modern approach using ES Modules to import

<!DOCTYPE html>
<html lang="en">
<head>
  <script type="module">
    import { defineCustomElements } from 'https://unpkg.com/iris-sdk@latest/components/iris-components.js';

    defineCustomElements(window);
  </script>
</head>
<body>
  <iris-test></iris-test>
</body>
</html>

For more details on setting props and utilizing these prebuilt web components, see the stenciljs documentation.

List of Components

The list of available web components is still being updated as projects are undergoing development. In the meantime, only the following test component is available:

<iris-uploader></iris-uploader - File uploader component.

Iris Uploader

A component used to upload files that currently supports image uploads. Future updates will support other format types. User must be logged see this component.

Props

upload-to (required)
- Used to specify the url of the Iris API to upload the file to.
purpose (optional)
- Purpose of file. Though optional, this prop will be useful later when searching for a specific file.
- Any string value is possible.
- E.g., 'post-image', 'comment-image', 'main-image', etc.
onUploadCompleted (JSX)
- NOTE: If using plain HTML, add event listener for 'uploadCompleted' event on the uploader element (see example below)
- Returns metadata of the file after it is successfully uploaded.
- This metadata is located inside the details field of the returned object (see example below).

Example

HTML

<!DOCTYPE html>
<html lang="en">
<head>
  <script src="https://unpkg.com/iris-sdk@latest/components/iris-components.js"></script>
</head>
<body>

  <iris-uploader
    upload-to="https://sandboxapi.iris-oc.com/client_name"
    purpose="test-image"></iris-uploader>
  
  <script>
    const uploader = document.querySelector('iris-uploader');
    uploader.addEventListener('uploadCompleted', (event) => {
      // event.detail contains the uploaded file's metadata
    })
  </script>

</body>
</html>

JSX (Not React)

<iris-uploader
  upload-to="https://sandboxapi.iris-oc.com/client_name"
  purpose="test-image"
  onUploadCompleted={event => this.someHandlerMethod(event.details)/>

JSX (React) Currently, there are some caveats with using web components in a React application because React implements its own event system and cannot listen for DOM events that come from web components. To work around this, you have to reference a component and manually add an event listener like you would with the plain HTML approach:

import React from 'react';

export default class ReactApp extends React.Component {
  constructor() {
    this.uploader = React.createRef();
  }

  componentDidMount() {
    this.uploader.current.addEventListener('uploadCompleted', (e) => {
      console.log(e.detail);
    })
  }

  render() {
    return (
      <iris-uploader
        upload-to="https://sandboxapi.iris-oc.com/client_name"
        purpose="test-image"/>
    )
  }
}

Check future updates for more reusable Iris components.

API Services

The Services module contains the microservices that are available through Iris's API. Currently, this module is broken up into two separate microservices:

Authentication - Used for authentication and other user management features.
CRUD - Used for updating, creating, deleting and filtering documents stored in the database.
Util - Used for utility funcitons such as emailing and SMS on the API (currently in beta).

Another important thing to note is that the Iris API is comprised of three separate environments all with its own separate document database and user database. These environments are separated into:

Public - This is the live/production version of the Iris API that contains real data and real user accounts. Consider all data on this environment to be permanent and public-facing. Use this environement with caution as it is reserved for deployed applications only.
Sandbox - This is the staging environement of the Iris API that contains some backed up documents from Production as well as some developer-generated documents. This is where new features are tested on Production documents one last time before they are deployed to Production. Use this for a final round of testing on stable, ready-for-deployment features.
Development - This is the test version of the Iris API that contains little to no Production documents. It is primarily used for stabilizing new features and resolving bugs before further testing on Sandbox. Use this for all general development purposes or working with untested code.

Setting Up

Import the services you want use from the Iris API:

import { CrudService, AuthService, UtilService } from 'iris-sdk/services';

Provide the url of the Iris API environment that you want to use. This example uses a fake 'atlantis' client of the Sandbox environment:

import { CrudService, AuthService, UtilService } from 'iris-sdk/services';

const apiUrl = 'https://sandboxapi.iris-oc.com/atlantis/'

const Crud = new CrudService(apiUrl);
const Auth = new AuthService(apiUrl);
const Utils = new UtilService(apiUrl);

NOTE: Not all clients you enter may exist! Please contact an Iris dev for list of available clients on the Iris API.

Example

import { CrudService, AuthService, UtilService } from 'iris-sdk/services';

const apiUrl = 'https://sandboxapi.iris-oc.com/atlantis/'

const Crud = new CrudService(apiUrl);
const Auth = new AuthService(apiUrl);
const Utils = new UtilService(apiUrl);

Auth.login()...
Crud.listAll()...

Authentication

Iris's authentication microservice allows for user signup, login, authorization and other user management functions directly on the Iris API.

This service implements JWT's and is an integral part of the Iris API. Without it, many functions within the CRUD service is inaccessible because they sit behind a protected endpoint. Therefore, it is important that developers correctly implement this authentication service to prevent running into authorization errors when using Iris's CRUD service.

Init

import { AuthService } from 'iris-sdk/services';

const Auth = new AuthService('api_url');

Login

A promise that logs in a user and assigns the client DOM a JWT.

const loginObj = {
  email: 'john.doe@test.com', 
  password: 'Testing1'
};

Auth.login(loginObj)
  .then(success => {}) 
  .catch(err => {})

Signup

Runs default creation of new user documents (user, profile, and two collections)
Assigns to the client DOM a JWT

const signupObj = {
  username: 'johndoe', 
  email: 'john.doe@test.com',
  password: 'Testing1',
  accountType: 'member' || 'organization'
};

Auth.signup(signupObj)
  .then(success => {})
  .catch(err => {})

Check Email

Check if an email address is available to use.

Auth.checkEmail('john.doe@test.com')
  .then(emailAvailable => {})
  .catch(err => {})

Check Username

Check if a username is available to use.

Auth.checkUsername('johndoe')
  .then(usernameAvailable => {}) 
  .catch(err => {})

Change Username

Change user's member id. This method requires that a user is logged in with valid JWT.

const changeObj = { 
  newUsername: 'johndoe2', 
  password: 'Testing1'
};

Auth.changeUsername(changeObj)
  .then(success => {})
  .catch(err => {})

Change Email

Change user's primary email address. This method requires that a user is logged in with valid JWT.

const changeObj =  {
  newEmail: 'john.doe2@test.com', 
  password: 'Testing1'
};

Auth.changeEmail(changeObj)
  .then(success => {})
  .catch(err => {})

Change Password

Change a user's password. This method requires that a user is logged in with valid JWT.

const changeObj = {
  currentPassword: 'Testing1',
  newPassword: 'Testing2'
}; 

Auth.changePassword(changeObj)
  .then(success => {})
  .catch(err => {})

Reset Password

Send a reset password link to the email if it exists in the user database.

Auth.resetPassword('john.doe@test.com')
  .then(success => {})
  .catch(err => {})

Verify Email

Send an email verification link to the email if it exists in the user database.

AuthService.verifyEmail('john.doe@test.com')
  .then(success => {})
  .catch(err => {})

Logout

Logs user out by deleting the session on the client DOM and notifying the Iris Api.

Auth.logout()

Check Authentication

Return a boolean for user's login status. If user's session is expired, then the session is deleted.

AuthService.isAuthenticated()

Get User Info

Get basic user information from the client session.

AuthService.getUserInfo()

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

CRUD

Iris's crud microservice allows for management of personal documents on Iris's database.

Listed below are the publicly available model names of collections on Iris's database. Note: Not all collections will have full access to all crud service functions.

'adverts'
'appPref'
'articles'
'collections'
'events'
'healthCheck'
'hero'
'media'
'notes'
'notifications'
'posts'
'profiles'
'reactions'
'teasers'
'users'
'vendors'

Init

import { CrudService } from 'iris-sdk/services';

const Crud = new CrudService('api_url');

Count Documents

Returns a count of all the documents matching a given model name and optional filter params.

const filters = { // optional
  'key.field1': 'value', 
  'key.field2.field3': 'value' 
};

Crud.count(model: String, filters?: Object)
  .then(data => {})
  .catch(err => {})

List All

List all documents with a given model name.

const modifiers = { // optional
  '~key': 'value', 
  '~key': 'value' 
};

Crud.listAll(model: String, modifiers?: Object)
  .then(data => {})
  .catch(err => {})

Get By ID

Get specific document by one ID or multiple ID's.

const oneId = 'id_1';
const multipleIds = 'id1, id2, id3';

Crud.getById(model: String, oneId || multipleIds)
  .then(data => {})
  .catch(err => {})

Filter Document

Granular filtering of document(s) based off a filter and optional modifier query parameters.

const filters = {
  'key.field1': 'value', 
  'key.field2.field3': 'value' 
};
const modifiers = { // optional
  '~key': 'value', 
  '~key': 'value' 
};

Crud.getByFilter(model: String, filters: Object, modifiers?: Object)
  .then(data => {})
  .catch(err => {})

Note: More details are being documented on Iris's specific filter-modifier query structure and will be available as a link here later.

Query Objects

Older form of document query that filters documents based off 'loose' (or search) and 'strict' (and search) query objects. Query needs at least one of queryLoose or queryStrict to filter correctly.

const queryStrict = {
  'key.field1': 'value', 
  'key.field2.field3': 'value'  
};

const queryLoose = {
  'key.field4': 'value', 
  'key.field5.field6': 'value' 
};

Crud.getByQueryObjects(model: String, queryStrict?: Object, queryLoose?: Object)
  .then(data => {})
  .catch(err => {})

Generation List

Performs a generational search that filters for a parent document and associated child documents with a specific level of nesting.

Crud.getGenList(parentModel: String, parentId: String, levels: String, childModel: String)
  .then(data => {})
  .catch(err => {})

Create Document

Create a new document for a collection with a given model name. This method requires that a user is logged in with valid JWT.

const docBody = {
  contentSummary: {...},
  contentInfo: {...},
  contentData: {...}
};

Crud.createDocument(model: String, docBody: Object)
  .then(res => {})
  .catch(err => {})

Create Child Document

Create a document as a child of a parent document. This method requires that a user is logged in with valid JWT.

const docBody = {
  contentSummary: {...},
  contentInfo: {...},
  contentData: {...}
};

Crud.createChild(model: String, docBody: Object, parentModel: String, parentId: String)
  .then(res => {})
  .catch(err => {})

Replace Document (Put)

Searches for a document by given id and model name and replaces the body of the document with new data. This method requires that a user is logged in with valid JWT.

const docBody = {
  contentSummary: {...},
  contentInfo: {...},
  contentData: {...}
};

Crud.replaceDocument(model: String, id: String, docBody: Object)
  .then(res => {})
  .catch(err => {})

Patch Document (Update)

Searches for a specific document by its id and model name, then replaces a the specified field of the document with a new data object. This method requires that a user is logged in with valid JWT.

Crud.patchDocument(model: String, id: String, field: String, data: Any)
  .then(res => {})
  .catch(err => {})

Delete Document

Delete a document by its id and model name. This method requires that a user is logged in with valid JWT.

Crud.deleteDocument(model: String, id: String)
  .then(res => {})
  .catch(err => {})

Patch Notes

Current

v0.1.19: Updated the getById function in crud services to return single object if response data is an array with only one item.
v0.1.18: Resolved bug in Uploader.
v0.1.17: Updated Uploader Component to take in a URL for the 'upload-to' attribute.
v0.1.16: Fixed bug in AuthService and updated README.
v0.1.15: Minor changes to allow passing in a URL to all API services.
v0.1.14: Added functionality in AuthService to check admin access of a user.
v0.1.13: Restyled the uploader component for better visibility.
v0.1.12: Released new utility service to the services module and an uploader component to the component module of this package. Updated README to provide basic instruction for the uploader component. Further revision of this README will be added in a future patch to cover new functions not yet available on the public API:
1. Util:
- .sendEmail()
1. Auth:
- .getFullUserInfo()
1. Crud:
- .getMyProfile()
- .getBookmarks()
- .addBookmarks({docType: 'doc_model', docId: 'id'})
- .removeBookmarks({docType: 'doc_model', docId: 'id'})
- .getConnections()
- .follow({friendUsername: 'member_id', friendId: 'id'})
- .unfollow({friendUsername: 'member_id', friendId: 'id'})
v0.1.10: Added new features to auth and crud services in Dev and Sandbox environments (these features will be documented in a future patch when they are made available on the public API).
v0.1.9: Resolved multiple potential bugs in authentication service.
v0.1.5: Updated package.json and README.
v0.1.4: Updated README.
v0.1.3: Stabilized services to support Angular.
v0.1.2: Restructured directories to simplify naming. Also converted services to Typescript to support Angular 2+.
v0.1.1: Removed distribution directory.
v0.1.0: Test released reusable, framework-agnostic components. Also restructured this package to separate it into two separate modules:
1. iris-sdk/iris-components - Contains Iris's reusable components
2. iris-sdk/iris-services - Contains Iris's API services