An SDK provided by Iris Digital Communities, PBC
*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.
``
npm i --save iris-sdk@latest
The Iris SDK contains two modules that can be imported:
1. iris-sdk/components - a collection of reusable components. More details...
2. iris-sdk/services - a collection of services that consume the Iris API. More details...
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.
CUSTOM_ELEMENTS_SCHEMA`##### ./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 { }
`
2. 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);
`
3. 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
`
#### React
1. 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(
registerServiceWorker();
defineCustomElements(window);
`
2. 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 (
<>
This works
)
}
#### Vue
1. In a Vue application, import1 the defineCustomElements(window)` method inside the `main.js` file. This file is auto-generated using `vue-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');
`
2. Call an Iris component from the list of components above inside the HTML template of a Vue component.
#### Ember
1. Ember requires installation of the `ember-cli-stencil` by running the following command in an Ember application:
`
ember install ember-cli-stencil
2. 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
`
##### Method B: More modern approach using ES Modules to import
`
For more details on setting props and utilizing these prebuilt web components, see the stenciljs
documentation.
1. `
#### 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
`
purpose="test-image">
`
JSX (Not React)
`
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 (
purpose="test-image"/>
)
}
}
`
Check future updates for more reusable Iris components.
The Services module contains the microservices that are available through Iris's API. Currently, this module is broken up into two separate microservices:
1. Authentication - Used for authentication and other user management features.
2. CRUD - Used for updating, creating, deleting and filtering documents stored in the database.
3. 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:
1. 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.
2. 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.
3. 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.
`
import { CrudService, AuthService, UtilService } from 'iris-sdk/services';
2. 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()...
`
$3
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
Sign up new user.
1. Runs default creation of new user documents (user, profile, and two collections)
2. 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
}
`
$3
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 => {})
.sendEmail()`
2. Auth:
- .getFullUserInfo()`
3. 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'})``