Allthings Node/Javascript SDK
| Option | Default | Description | | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- | | accessToken | | API Access Token | | clientId | | OAuth 2.0 clientId | | clientSecret | | OAuth 2.0 client secret | | username | | Username to use with OAuth 2.0 Password Grant authentication flow | | password | | Password to use with OAuth 2.0 Password Grant authentication flow | | concurrency | | Number of concurrent requests to perform in parallel. Default behavior is burst of 30/s, 1/s thereafter | | apiUrl | | Base API url to use. Defaults to https://api.allthings.me/, respects value of the
process.env.ALLTHINGSOAUTHCLIENTID process.env.ALLTHINGSOAUTHCLIENTSECRET, process.env.ALLTHINGSOAUTHPASSWORD, process.env.ALLTHINGSOAUTHUSERNAME,
At this point
The Allthings SDK makes use of semantic-release which automates the whole package release workflow including:
This repository is also configured to
When you squash merge, GitHub takes the title of the PR for the squash-merge's commit subject.
By choosing a proper PR title e.g.
See semantic-releases docs for available prefixes.
Contents
1. [Options](#configuration-options)
- Authentication
- API
- OAuth Implicit Grant Example
- OAuth Authorization Code Grant Example
- Release management & versioning
Installation & Usage
yarn add @allthings/sdk
const allthings = require('@allthings/sdk')
const client = allthings.restClient({
accessToken: '043dab7447450772example1214b552838003522',
})
client
.getCurrentUser()
.then((viewer) => console.log(`Welcome back ${viewer.username}!`))
Configuration
Request logs
If you want to see in your logs which url has been called during it's runtime, you can enable them by providingLOG_REQUEST
as an environment variable where the
value can be anything which is truthy.Configuration Options
The available configuration options are outlined here:| Option | Default | Description | | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- | | accessToken | | API Access Token | | clientId | | OAuth 2.0 clientId | | clientSecret | | OAuth 2.0 client secret | | username | | Username to use with OAuth 2.0 Password Grant authentication flow | | password | | Password to use with OAuth 2.0 Password Grant authentication flow | | concurrency | | Number of concurrent requests to perform in parallel. Default behavior is burst of 30/s, 1/s thereafter | | apiUrl | | Base API url to use. Defaults to https://api.allthings.me/, respects value of the
ALLTHINGS_REST_API_URL
environment variable |Authentication
@TODOprocess.env.ALLTHINGSOAUTHCLIENTID process.env.ALLTHINGSOAUTHCLIENTSECRET, process.env.ALLTHINGSOAUTHPASSWORD, process.env.ALLTHINGSOAUTHUSERNAME,
OAuth Implicit Grant Example
@TODOconst allthings = require('@allthings/sdk')
const client = allthings.restClient({
accessToken: '043dab7447450772example1214b552838003522',
})
client
.getCurrentUser()
.then((viewer) => console.log(`Welcome back ${viewer.username}!`))
OAuth Authorization Code Grant Example
- Initialize instance of
client
:
const allthings = require('@allthings/sdk')
const client = allthings.restClient({
clientId: '5d038ef2441f4de574005c54_example',
clientSecret: '40f63f981ff082dbc8d273983ac3852c2e51e90856123156',
redirectUri: 'https://example-app.com/callback',
})
- Construct a URI to send authorization request to using a
state
which should be unique per request and hard to guess. It can be generated withclient.oauth.generateState()
method:
const state = client.oauth.generateState()
const authorizationUri = client.oauth.authorizationCode.getUri(state)
- Direct user's browser to the constructed URI.
- When user completes authentication process, he is redirected to the
redirectUri
havingcode
andstate
query string arguments, e.g.:
https://example-app.com/callback?code=ebc110bee11b2829&state=k1bt3c1d0vnfu7qk
At this point
state
must be validated - if it doesn't match the one generated on step 2, such request is probably malicious and should be aborted.- Use the code extracted from query parameters on the previous step to obtain an access token:
await client.oauth.authorizationCode.requestToken(code)
- Client is ready to make API requests:
const user = await client.getCurrentUser()
API
Allthings SDK module
-client.agentCreate()
- client.agentCreatePermissions()
- client.appCreate()
- client.lookupIds()
- client.groupCreate()
- client.groupGetById()
- client.groupUpdateById()
- client.getGroups()
- client.propertyCreate()
- client.propertyGetById()
- client.propertyUpdateById()
- client.getProperties()
- client.registrationCodeCreate()
- client.unitCreate()
- client.unitGetById()
- client.unitUpdateById()
- client.getUnits()
- client.userCreate()
- client.userGetById()
- client.userUpdateById()
- client.userChangePassword()
- client.userCreatePermission()
- client.userGetPermissions()
- client.userDeletePermission()
- client.userGetUtilisationPeriods()
- client.userCheckInToUtilisationPeriod()
- client.getUsers()
- client.getCurrentUser()
- client.userRelationCreate()
- client.userRelationDelete()
- client.utilisationPeriodCreate()
- client.utilisationPeriodDelete()
- client.utilisationPeriodGetById()
- client.utilisationPeriodUpdateById()
- client.utilisationPeriodCheckInUser()
- client.utilisationPeriodAddRegistrationCode()
- client.delete()
- client.get()
- client.post()
- client.patch()
restClient(configurationOptions?): Client
Create an client instance of the SDK.const allthings = require('@allthings/sdk')
const client = allthings.restClient(configurationOptions)
client.createAgent()
Create a new agent. This is a convenience function around creating a user and adding that user to a property-manager's team.const appId = '575027e58178f56a008b4568'
const propertyManagerId = '5a818c07ef5f2f00441146a2'
const username = 'mr.example@allthings.test'
const agent = await client.createAgent(appId, propertyManagerId, username, {
email: 'mr.example@allthings.test',
locale: 'en_US',
})
export type MethodCreateAgent = (
appId: string,
propertyManagerId: string,
username: string,
data: PartialUser & {
readonly email: string
readonly locale: EnumLocale
},
) => UserResult
// Describes the API wrapper's resulting interface
export interface IAllthingsRestClient {
readonly delete: MethodHttpDelete
readonly get: MethodHttpGet
readonly post: MethodHttpPost
readonly patch: MethodHttpPatch
// Agent
/**
* Create a new agent. This is a convenience function around
* creating a user and adding that user to a property-manager's team
*/
readonly agentCreate: MethodAgentCreate
/**
* Create agent permissions. This is a convenience function around
* creating two user permission's: one "admin" and the other "pinboard"
*/
readonly agentCreatePermissions: MethodAgentCreatePermissions
// App
/**
* Create a new App.
*/
readonly appCreate: MethodAppCreate
// Booking
/**
* Get a booking by its ID
*/
readonly bookingGetById: MethodBookingGetById
/**
* Update a booking by its ID
*/
readonly bookingUpdateById: MethodBookingUpdateById
// Group
/**
* Create a new group within a property
*/
readonly groupCreate: MethodGroupCreate
/**
* Get a group by its ID
*/
readonly groupGetById: MethodGroupGetById
/**
* Update a group by its ID
*/
readonly groupUpdateById: MethodGroupUpdateById
// ID Lookup
/**
* Map one or more externalId's to API ObjectId's within the scope of a specified App
*/
readonly lookupIds: MethodLookupIds
// Notification
/**
* Returns a collection of notifications for a given user
*/
readonly notificationsGetByUser: MethodNotificationsGetByUser
/**
* Marks all notifications of a user - until a provided timestamp (or now) - as read
*/
readonly notificationsUpdateReadByUser: MethodNotificationsUpdateReadByUser
/**
* Mark a notification as read
*/
readonly notificationUpdateRead: MethodNotificationUpdateRead
// Notification settings
/**
* Set all notification settings to default
*/
readonly notificationSettingsResetByUser: MethodNotificationSettingsResetByUser
/**
* Change user notification-settings
*/
readonly notificationSettingsUpdateByUser: MethodNotificationSettingsUpdateByUser
// Property
/**
* Create a new property
*/
readonly propertyCreate: MethodPropertyCreate
/**
* Get a property by its ID
*/
readonly propertyGetById: MethodPropertyGetById
/**
* Update a property by its ID
*/
readonly propertyUpdateById: MethodPropertyUpdateById
// Registration Code
/**
* Create a new registration code
*/
readonly registrationCodeCreate: MethodRegistrationCodeCreate
// Unit
/**
* Create a unit within a group
*/
readonly unitCreate: MethodUnitCreate
/**
* Get a unit by its ID
*/
readonly unitGetById: MethodUnitGetById
/**
* Update a unit by its ID
*/
readonly unitUpdateById: MethodUnitUpdateById
// User
/**
* Create a new User.
*/
readonly userCreate: MethodUserCreate
/**
* Get a user by their ID
*/
readonly userGetById: MethodUserGetById
/**
* Update a user by their ID
*/
readonly userUpdateById: MethodUserUpdateById
/**
* Get a list of users
*/
readonly getUsers: MethodGetUsers
/**
* Get the current user from active session
*/
readonly getCurrentUser: MethodGetCurrentUser
/**
* Change a user's password
*/
readonly userChangePassword: MethodUserChangePassword
/**
* Give a user a permission/role on an given object of specified type
*/
readonly userCreatePermission: MethodUserCreatePermission
/**
* Get a list of user's permissions
*/
readonly userGetPermissions: MethodUserGetPermissions
/**
* Delete a user a permission/role on an given object of specified type
*/
readonly userDeletePermission: MethodUserDeletePermission
/**
* Get a list of user's current utilisation - periods
*/
readonly userGetUtilisationPeriods: MethodUserGetUtilisationPeriods
/**
* Checkin a user into a Utilisation-Period with userId and
* utilisation-periodId
*/
readonly userCheckInToUtilisationPeriod: MethodUserCheckInToUtilisationPeriod
// User Relation
/**
* Creates a new user relation
*/
readonly userRelationCreate: MethodUserRelationCreate
/**
* Deletes a new user relation
*/
readonly userRelationDelete: MethodUserRelationDelete
// Utilisation Period
/**
* Create a new utilisation period within a Unit
*/
readonly utilisationPeriodCreate: MethodUtilisationPeriodCreate
/**
* Deletes a utilisation period by its id
*/
readonly utilisationPeriodDelete: MethodUtilisationPeriodDelete
/**
* Get a utilisation period by its ID
*/
readonly utilisationPeriodGetById: MethodUtilisationPeriodGetById
/*
* Update a utilisation period by its ID
*/
readonly utilisationPeriodUpdateById: MethodUtilisationPeriodUpdateById
/**
* Check-in a user to a utilisation period with the users email
*/
readonly utilisationPeriodCheckInUser: MethodUtilisationPeriodCheckInUser
}
Release management & versioning
!! DO NOTnpm version
!!The Allthings SDK makes use of semantic-release which automates the whole package release workflow including:
- determining the next version number
- generating the release notes and publishing the package.
This repository is also configured to
squash-merge
(see here).When you squash merge, GitHub takes the title of the PR for the squash-merge's commit subject.
By choosing a proper PR title e.g.
feat: my new feature
your merged PR will trigger a new release.See semantic-releases docs for available prefixes.