iris-ng-services
Advanced tools
A library containing services to help you build Angular applications that run on the Iris API.
A library containing services to help you build Angular applications that run on the Iris API.
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
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
) {}
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.).
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.
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.
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.
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.
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.
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.
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.
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.
AuthService.logout()
This method to clears the authenticated session and notifies the API that user has logged out.
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>
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.
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.
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.
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:
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.
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.
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.
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).
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.
ApiService.create(
model: string,
data: object
)
Create a new document under a specified model.
ApiService.createChild(
model: string,
data: object,
parentModel: string,
parentId: string
)
Create a document as a child of another document.
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.
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:
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.
ApiService.deleteDocument(
model: string,
id: string
)
Delete a document matching a model and id.
###v0.7 (Latest Stable)
###v0.6 (Deprecated December, 2018)
###v0.5 (Deprecated Aug, 2018)
###v0.4 (Deprecated July, 2018)
###v0.3 (Deprecated July, 2018)
###v0.2 (Deprecated July, 2018)
FAQs
A library containing services to help you build Angular applications that run on the Iris API.
We found that iris-ng-services demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.