# onesignal-node
> A Node.js Library for OneSignal push notification service
Latest version **3.4.0** (published 2022-06-28) · MIT license · 0 weekly downloads
## Install
```sh
npm install onesignal-node
pnpm add onesignal-node
yarn add onesignal-node
bun add onesignal-node
```
## Health
**Score 25/100 (F)** — status: abandoned.
Positive: has types; no vulnerabilities; high quality score.
Warnings: low downloads; no esm support.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 3.4.0 |
| Published | 2022-06-28 |
| First published | 2017-07-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=8.13.0 |
| Dependencies | 2 |
| Unpacked size | 71.5 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 209 |
| Author | Zeynel |
| Maintainers | fxgx |
| Keywords | onesignal, one-signal, gcm, signal, notification |
## Links
- npm: https://www.npmjs.com/package/onesignal-node
- Repository: https://github.com/zeyneloz/onesignal-node
- Homepage: https://github.com/zeyneloz/onesignal-node.git#readme
- Issues: https://github.com/zeyneloz/onesignal-node.git/issues
- npm.io page: https://npm.io/package/onesignal-node
## Dependencies (2)
- [request](https://npm.io/package/request.md) ^2.88.2
- [request-promise](https://npm.io/package/request-promise.md) ^4.2.6
## Alternatives
- [update-check](https://npm.io/package/update-check.md) — 4.0M weekly downloads
- [react-native-onesignal](https://npm.io/package/react-native-onesignal.md) — 134.5K weekly downloads
- [react-redux-toastr](https://npm.io/package/react-redux-toastr.md) — 33.7K weekly downloads
- [@nocobase/plugin-notification-manager](https://npm.io/package/@nocobase/plugin-notification-manager.md) — 2.0K weekly downloads
- [react-simple-toasts](https://npm.io/package/react-simple-toasts.md) — 1.9K weekly downloads
## Recent versions
- 3.4.0 (latest) — 2022-06-28
- 3.3.0 — 2021-08-03
- 3.2.1 — 2020-12-31
- 3.2.0 — 2020-09-22
- 3.1.5 — 2020-08-04
- 3.1.0 — 2020-07-19
- 3.0.2 — 2020-06-03
- 3.0.1 — 2020-05-25
- 3.0.0 — 2019-12-20
- 2.1.1 — 2019-08-07
- 2.1.0 — 2019-04-30
- 2.0.1 — 2018-10-13
- 2.0.0 — 2018-07-28
- 1.2.0 — 2018-07-25
- 1.1.2 — 2018-05-21
- … 7 more at https://npm.io/package/onesignal-node/versions
## README
# onesignal-node
A Node.js client library for [OneSignal](https://onesignal.com/) API.
## Table of Contents
* [Overview](#overview)
* [Installation](#installation)
* [Usage](#usage)
* [Client Types](#client-types)
* [Creating Client](#creating-client)
* [Create notification](#create-notification)
* [Cancel notification](#cancel-notification)
* [View notifications](#view-notifications)
* [View notification](#view-notification)
* [View apps](#view-apps)
* [Create an app](#create-an-app)
* [Update an app](#update-an-app)
* [View devices](#view-devices)
* [View device](#view-device)
* [Add a device](#add-a-device)
* [Edit a device](#edit-a-device)
* [Edit tags with external user id](#edit-tags-with-external-user-id)
* [New session](#new-session)
* [New purchase](#new-purchase)
* [Increment Session Length](#increment-session-length)
* [CSV Export](#csv-export)
* [Identity verification](#identity-verification)
* [Tests](#tests)
* [Contributing](#contributing)
## Overview
This is a wrapper library over [OneSignal REST API](https://documentation.onesignal.com/reference). You can create notifications,
view apps, edit a device and all other actions you can take on OneSignal REST API.
## Installation
```
npm install onesignal-node --save
```
## Usage
``` js
const OneSignal = require('onesignal-node');
```
OR
``` js
import * as OneSignal from 'onesignal-node';
```
### Client Types:
For all the actions that require your OneSignal app id and app api key, you should use `OneSignal.Client`.
Sample actions: create notification, add device, csv export, create segment...
``` js
const client = new OneSignal.Client('appId', 'apiKey');
```
For all the actions that require your User Auth Key you should use `OneSignal.UserClient`.
Sample actions: view apps, update an app, create an app...
``` js
const userClient = new OneSignal.UserClient('userAuthKey');
```
### Creating client
You can create a `Client` object as shown below. It requires two parameters: `appId` and `apiKey`, which you can find them on
your applications page on OneSignal dashboard.
There is also an optional parameter called `options`. You can set OneSignal rest api endpoint if you wish to using options.
By default the library uses `https://onesignal.com/api/v1` for api endpoint.
```js
// With default options
const client = new OneSignal.Client('appId', 'apiKey');
// With custom API endpoint
const client = new OneSignal.Client('appId', 'apiKey', { apiRoot: 'https://onesignal.com/api/v2'});
```
### Creating UserClient
You can create a `UserClient` object as shown below. It requires one parameter: `userAuthKey`, which you can find it on
your OneSignal dashboard.
There is also an optional parameter called `options`. You can set OneSignal rest api endpoint if you wish to using options.
By default the library uses `https://onesignal.com/api/v1` for api endpoint.
```js
// With default options
const userClient = new OneSignal.UserClient('userAuthKey');
// With custom API endpoint
const userClient = new OneSignal.UserClient('userAuthKey', { apiRoot: 'https://onesignal.com/api/v2'});
```
### Create notification
https://documentation.onesignal.com/reference/create-notification
```ts
.createNotification(body: CreateNotificationBody): Promise
```
Please read the sections above to learn how to create a `Client` object.
```js
// See all fields: https://documentation.onesignal.com/reference/create-notification
const notification = {
contents: {
'tr': 'Yeni bildirim',
'en': 'New notification',
},
included_segments: ['Subscribed Users'],
filters: [
{ field: 'tag', key: 'level', relation: '>', value: 10 }
]
};
// using async/await
try {
const response = await client.createNotification(notification);
console.log(response.body.id);
} catch (e) {
if (e instanceof OneSignal.HTTPError) {
// When status code of HTTP response is not 2xx, HTTPError is thrown.
console.log(e.statusCode);
console.log(e.body);
}
}
// or you can use promise style:
client.createNotification(notification)
.then(response => {})
.catch(e => {});
```
### Cancel notification
https://documentation.onesignal.com/reference/cancel-notification
```ts
.cancelNotification(notificationId: string): Promise
```
```js
const response = await client.cancelNotification('notification-id');
console.log(response.body);
console.log(response.headers);
console.log(response.statusCode);
```
### View notifications
https://documentation.onesignal.com/reference/view-notifications
```ts
.viewNotifications(query?: ViewNotificationsQuery): Promise
```
```js
// without query
const response = await client.viewNotifications();
console.log(response.body);
// with query
const response = await client.viewNotifications({ limit:10, kind: 2, offset: 2 });
```
### View notification
https://documentation.onesignal.com/reference/view-notification
```ts
.viewNotification(notificationId: string): Promise
```
```js
const response = await client.viewNotification('notification-id');
console.log(response.body);
```
### View apps
https://documentation.onesignal.com/reference/view-apps-apps
You should use `UserClient` for view apps since it requires User Auth Key
```ts
.viewApps(): Promise
```
```js
const response = await userClient.viewApps();
console.log(response.body);
```
### Create an app
https://documentation.onesignal.com/reference/create-an-app
You should use `UserClient` for view apps since it requires User Auth Key
```ts
.createApp(body: CreateAppBody): Promise
```
```js
const response = await userClient.createApp( { name: 'APP 1' });
console.log(response.body);
```
### Update an app
https://documentation.onesignal.com/reference/update-an-app
You should use `UserClient` for view apps since it requires User Auth Key
```ts
.updateApp(appId: string, body: UpdateAppBody): Promise
```
```js
const response = await userClient.updateApp( 'app-id',{ site_name: 'test' });
console.log(response.body);
```
### View devices
https://documentation.onesignal.com/reference/view-devices
```ts
.viewDevices(query?: LimitOffsetQuery): Promise
```
```js
const response = await client.viewDevices({ limit: 200, offset: 0 });
console.log(response.body);
```
### View device
https://documentation.onesignal.com/reference/view-device
```ts
.viewDevice(identifier: string): Promise
```
```js
const response = await client.viewDevice('device-id');
console.log(response.body);
```
### Add a device
https://documentation.onesignal.com/reference/add-a-device
```ts
.addDevice(body: AddDeviceBody): Promise
```
```js
const response = await client.addDevice({
device_type: 'ios',
identifier: 'id1',
});
console.log(response.body);
```
### Edit a device
https://documentation.onesignal.com/reference/edit-device
```ts
.editDevice(deviceId: string, body: EditDeviceBody): Promise
```
```js
const response = await client.editDevice('device-id',{
identifier: 'id2',
});
console.log(response.body);
```
### Edit tags with external user id
https://documentation.onesignal.com/reference/edit-tags-with-external-user-id
```ts
.editTagsWithExternalUserIdDevice(externalUserId: string, body: EditTagsBody): Promise
```
```js
const response = await client.editTagsWithExternalUserIdDevice('external-user-id', {
tags: {
customTag: "customValue"
},
});
console.log(response.body);
```
### New Session
https://documentation.onesignal.com/reference/new-session
```ts
.newSession(deviceId: string, body: NewSessionBody): Promise
```
```js
const response = await client.newSession('device-id',{
language: 'tr',
});
console.log(response.body);
```
### New Purchase
https://documentation.onesignal.com/reference/new-purchase
```ts
.newPurchase(deviceId: string, body: NewPurchaseBody): Promise
```
```js
const response = await client.newPurchase('device-id',{
purchases: [...],
});
console.log(response.body);
```
### Increment Session Length
https://documentation.onesignal.com/reference#increment-session-length
```ts
.incrementSessionLength(deviceId: string, body: IncrementSessionLengthBody): Promise
```
```js
const response = await client.incrementSessionLength('device-id',{
state: '',
active_time: 11,
});
console.log(response.body);
```
### CSV Export
https://documentation.onesignal.com/reference/csv-export
```ts
.exportCSV(body: ExportCSVBody): Promise
```
```js
const response = await client.exportCSV({});
console.log(response.body);
```
### Create Segment
https://documentation.onesignal.com/reference/create-segments
```ts
.createSegment(body: CreateSegmentBody): Promise
```
```js
const response = await client.createSegment({
name: 'new-segment',
filters: [..]
});
console.log(response.body);
```
### Delete Segment
https://documentation.onesignal.com/reference/delete-segments
```ts
.deleteSegment(segmentId: string): Promise
```
```js
const response = await client.deleteSegment('segment-id1');
console.log(response.body);
```
### Identity Verification
https://documentation.onesignal.com/docs/identity-verification
You can use these simple helpers to sign user id or email to be used in client-side code.
```ts
.signUserExternalId(id: string | number): string
.signUserEmail(email: string): string
```
Each of these will return SHA-256 hash, that was generated using apiKey.
## Tests
Running all tests, coverage, build:
```bash
$ npm run test
$ npm run test-integration
$ npm run coverage
$ npm run build
```
## Contributing
### TL;DR
To send a pull request:
- Fork the repo
- Clone the forked repo on your computer
- Switch to master branch
- Create a feature branch (`git checkout -b feature/new-feature-name`)
- Make your changes and add new tests if necessary
- Push your changes to your fork
- Open a pull request
## License
This project is under the MIT license.
---
_Source: https://npm.io/package/onesignal-node · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._