@onesignal/node-onesignal 5.4.0 → 5.6.0

package/README.md

@@ -1,4 +1,4 @@
-<h1 align="center">Welcome to @onesignal/node-onesignal 👋</h1>
+<h1 align="center">Welcome to @onesignal/node-onesignal</h1>
 <p>
   <a href="https://www.npmjs.com/package/@onesignal/node-onesignal" target="_blank">
     <img alt="Version" src="https://img.shields.io/npm/v/@onesignal/node-onesignal.svg">
@@ -9,581 +9,112 @@
   <a href="https://github.com/OneSignal/node-onesignal/graphs/commit-activity" target="_blank">
     <img alt="Maintenance" src="https://img.shields.io/badge/Maintained%3F-yes-green.svg" />
   </a>
-  <a href="https://twitter.com/onesignal" target="_blank">
-    <img alt="Twitter: onesignal" src="https://img.shields.io/twitter/follow/onesignal.svg?style=social" />
-  </a>
 </p>
 
-> OpenAPI client for node-onesignal
-
-### 🏠 [Homepage](https://github.com/OneSignal/node-onesignal#readme)
-### 🖤 [npm](https://www.npmjs.com/package/@onesignal/node-onesignal)
-
-# Node Client SDK
-The OneSignal Node client is a server OneSignal SDK for NodeJS. Integrate OneSignal with your backend events, data, and 
-more.
+The OneSignal Node client is a server SDK for NodeJS. A powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at [onesignal.com](https://onesignal.com).
 
-
-# Install
+## Installation
 
 ```sh
-# yarn
-yarn add @onesignal/node-onesignal
-
 # npm
-npm install @onesignal/node-onesignal --save
-```
-
-# Usage
-```js
-const OneSignal = require('@onesignal/node-onesignal');
-```
-```js
-import * as OneSignal from '@onesignal/node-onesignal';
-```
+npm install @onesignal/node-onesignal
 
-## Creating a client
-### Configuration
-We can configure the client using the `createConfiguration` function. You can find more info on each configuration 
-parameter [here](https://github.com/OpenAPITools/openapi-generator/pull/10283/files).
+# pnpm
+pnpm add @onesignal/node-onesignal
 
-```js
-const configuration = OneSignal.createConfiguration(configParams);
-```
+# bun
+bun add @onesignal/node-onesignal
 
-### Initializing the Client
-```js
-const client = new OneSignal.DefaultApi(configuration);
+# yarn
+yarn add @onesignal/node-onesignal
 ```
 
-### Authentication
-You can configure auth parameters passing them like this:
+## Configuration
 
-```js
-const configuration = OneSignal.createConfiguration({
-    organizationApiKey: '<YOUR_ORGANIZATION_API_KEY>', // Organization key is only required for creating new apps and other top-level endpoints
-    restApiKey: '<YOUR_REST_API_KEY>', // App REST API key required for most endpoints
-});
+Every SDK requires authentication via API keys. Two key types are available:
 
-const client = new OneSignal.DefaultApi(configuration);
-```
+- **REST API Key** — required for most endpoints (sending notifications, managing users, etc.). Found in your app's **Settings > Keys & IDs**.
+- **Organization API Key** — only required for organization-level endpoints like creating or listing apps. Found in **Organization Settings**.
 
-#### Advanced Usage: Creating a brand-new app
-If creating a new app via the client, the response will return the app's API key via the `basic_auth_key` response 
-parameter. You can then use this to modify your configuration object and create a new client that will have both user-level and app-level authentication set up.
+> **Warning:** Store your API keys in environment variables or a secrets manager. Never commit them to source control.
 
-```js
-const response = await client.createApp(newapp);
+```javascript
+const OneSignal = require('@onesignal/node-onesignal');
 
 const configuration = OneSignal.createConfiguration({
-    organizationApiKey: '<YOUR_ORGANIZATION_API_KEY>', // Organization key is only required for creating new apps and other top-level endpoints
-    restApiKey: response.basic_auth_key,
+    restApiKey: 'YOUR_REST_API_KEY',
+    organizationApiKey: 'YOUR_ORGANIZATION_API_KEY',
 });
 
 const client = new OneSignal.DefaultApi(configuration);
 ```
 
----
-## API Reference
-
-> See the full list of [API Endpoints](DefaultApi.MD).
-
-To make stateful changes requests should take on the following pattern:
-1. create or get an object
-2. make changes to that object
-3. pass the object to the request function to make the changes
-
-Examples of important OneSignal objects include `App`, `Notification`, `Player`, and `Segment`.
-
-For example, see the section below on creating an app. First an app object is created via the instantiation of the `App`
-class. Then, the app instance is modified directly. Finally, we use the `client` to create the app via a remote request.
-
-### Creating an app
-Creates a new OneSignal app.
-
-**Example**
-```js
-const app = new OneSignal.App();
-
-// configure your application
-app.name = 'app_name';
-app.gcm_key = '<your key here>';
-app.android_gcm_sender_id = '<your id here>';
-
-const response = await client.createApp(app);
-```
-
-### Getting an app
-View the details of a single OneSignal app.
-
-**Example**
-```js
-const app = await client.getApp('<app id>');
-```
-
-### Getting multiple apps
-View apps.
-
-**Example**
-```js
-const apps = await client.getApps();
-```
-
-### Updating an app
-Updates the name or configuration settings of an existing OneSignal app.
-
-**Example**
-```js
-const app = new OneSignal.App();
-app.name = 'modified_app_name';
-
-const udpateAppResponse = await client.updateApp('<existing_app_id>', app);
-```
-
-### Creating a notification
-Sends a notification to your users.
-
-**Example**
-```js
-const notification = new OneSignal.Notification();
-notification.app_id = app.id;
-// Name property may be required in some case, for instance when sending an SMS.
-notification.name = "test_notification_name";
-notification.contents = {
-  en: "Gig'em Ags"
-}
-
-// required for Huawei
-notification.headings = {
-  en: "Gig'em Ags"
-}
-const notification = await client.createNotification(notification);
-```
-### Creating a notification using Filters
-Sends a notification to your users filtered by specific criteria.
+## Send a push notification
 
-**Example**
-```js
+```javascript
 const notification = new OneSignal.Notification();
-notification.app_id = app.id;
-
-notification.contents = {
-  en: "Gig'em Ags"
-}
-
-// required for Huawei
-notification.headings = {
-  en: "Gig'em Ags"
-}
-
-// Find all the users that have not spent any amount in USD on IAP.
-// https://documentation.onesignal.com/reference/create-notification#send-to-users-based-on-filters
-notification.filters = [
-    {
-        field: 'amount_spent',
-        relation: '=',
-        value: "0"
-    },
-];
-
-const notification = await client.createNotification(notification);
-```
-
-### Canceling a notification
-Stop a scheduled or currently outgoing notification.
-
-**Example**
-
-```js
-const cancelNotificationResponse = await client.cancelNotification('<app id>', '<notification id>');
-```
-
-
-### Getting a notification
-View the details of a single notification and outcomes associated with it.
-
-**Example**
-```js
-await client.getNotification('<app id>', '<notification id>');
-```
-
-### Getting notifications
-View the details of multiple notifications.
-
-| Param  | Type   | Description                                                                                                                                                                      |
-|--------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| app_id | string | The OneSignal App ID for your app.  Available in Keys &amp; IDs.                                                                                                                 |
-| limit  | string | How many notifications to return.  Max is 50.  Default is 50.                                                                                                                    |
-| offset | number | Page offset. Default is 0. Results are sorted by queued_at in descending order. `queued_at` is a representation of the time that the notification was queued at.                 |
-| kind   | number | Kind of notifications returned:   * unset - All notification types (default)   * `0` - Dashboard only   * `1` - API only    * `3` - Automated only |
-
-
-**Example**
-```js
-const notifications = await client.getNotifications('<app id>', '50', 0, 1);
-```
-
-### Getting notification history
-View the devices sent a message - **OneSignal Paid Plan Required**
-This method will return all devices that were sent the given `notification_id` of an Email or Push Notification if used 
-within 7 days of the date sent.
-
-**Example**
-```js
-const notificationHistory = await client.getNotificationHistory('<notification id>');
-```
-
-### Creating a segment
-Create segments visible and usable in the dashboard and API - **Required: OneSignal Paid Plan**
-
-**Example**
-```js
-const segment = new OneSignal.Segment();
-
-segment.filters = [
-  { field: 'session_count', relation: '&gt;', value: '1' },
-  { field: 'tag', key: 'my_tag', relation: 'exists' }
-]
-
-const segment = await client.createSegments(app.id, segment);
-```
-
-### Deleting a segment
-Delete segments (not user devices) - **Required: OneSignal Paid Plan**
-You can delete a segment under your app by calling this API. You must provide an API key in the Authorization header 
-that has admin access on the app.
-The `segment_id` can be found in the URL of the segment when viewing it in the dashboard.
-
-**Example**
-```js
-const deleteSegmentsResponse = await client.deleteSegments('<app id>', '<segment id>');
-```
+notification.app_id = 'YOUR_APP_ID';
+notification.contents = { en: 'Hello from OneSignal!' };
+notification.headings = { en: 'Push Notification' };
+notification.included_segments = ['Subscribed Users'];
 
-### Creating a player
-Add a device.
-
-**Example**
-```js
-const player = new OneSignal.Player();
-player.device_type = 1;
-player.app_id = app_id;
-player.identifier = '<identifier>';
-const player = await client.createPlayer(player);
-```
-
-### Getting a player
-View the details of an existing device in one of your OneSignal apps.
-The email and the hash is **only required if you have enabled Identity Verification and `device_type` is email**.
-
-**Example**
-```js
-const player = await client.getPlayer('<app id>', '<player id>', '<email auth hash>');
-```
-
-### Getting players
-View the details of multiple devices in one of your OneSignal apps. 
-
-⚠️ Unavailable for Apps Over 80,000 Users.
-
-| Param  | Type   | Description                                                      |
-|--------|--------|------------------------------------------------------------------|
-| app_id | string | The OneSignal App ID for your app.  Available in Keys &amp; IDs. |
-| limit  | string | How many devices to return. Max is 300. Default is 300           |
-| offset | number | Result offset. Default is 0. Results are sorted by id;           |
-
-
-**Example**
-```js
-const players = await client.getPlayers('<app id>', '300', 0);
+const response = await client.createNotification(notification);
+console.log('Notification ID:', response.id);
 ```
 
-### Exporting a player
-Generate a compressed CSV export of all of your current user data. This method can be used to generate a compressed CSV
-export of all of your existing user data and is a better alternative to retrieving this data using the /players API endpoint.
+## Send a push notification by External ID
 
-See [full CSV Export Reference](https://documentation.onesignal.com/reference/csv-export)
+Target specific users with the alias label `external_id` (snake_case). This is different from the notification-level `external_id` field, which is only for [idempotent requests](https://documentation.onesignal.com/docs/idempotent-notification-requests).
 
-**Example**
-```js
-const exportPlayerResponse = await client.exportPlayer('<app id>', {
-  extra_fields: ['location', 'external_user_id'],
-  last_active_since: 1469392779,
-  segment_name: "Subscribed Users"
-});
-```
-
-
-### Updating a player
-Update an existing device in one of your OneSignal apps.
-
-**Example**
-```js
-const updatePlayerResponse = await client.updatePlayer('<player id>', player);
-```
-
-### Updating player tags
-Update an existing device's tags in one of your OneSignal apps using the External User ID.
-
-```js
-const playerToUpdate = new OneSignal.Player();
+You must set `target_channel` when sending push (or email/SMS) to alias targets.
 
-player.app_id = APP_ID;
-player.device_type = 1;
-
-playerToUpdate.external_user_id = 'your_player_external_id'; // setting the same external_user_id as before
-const updatePlayerTagsRequestBody = new OneSignal.UpdatePlayerTagsRequestBody();
-updatePlayerTagsRequestBody.tags = {'typescript_test_tag': 1};
-const updatePlayerResponse = await api.updatePlayerTags(APP_ID, PLAYER_EXTERNAL_USER_ID, updatePlayerTagsRequestBody);
-```
-#### Deleting Tags
-To delete a tag, include its key and set its value to blank (""). Omitting a key/value will not delete it.
-
-For example, if you wanted to delete two existing tags rank and category while simultaneously adding a new tag class, the 
-tags JSON would look like the following:
-
-**Example**
-```json
-"tags": {
-   "rank": "",
-   "category": "",
-   "class": "my_new_value"
+```javascript
+const notification = new OneSignal.Notification();
+notification.app_id = 'YOUR_APP_ID';
+notification.contents = { en: 'Hello from OneSignal!' };
+notification.headings = { en: 'Push Notification' };
+// Keys under include_aliases must match API alias labels exactly (e.g. external_id, not externalId).
+notification.include_aliases = { external_id: ['YOUR_USER_EXTERNAL_ID'] };
+notification.target_channel = 'push';
+
+const response = await client.createNotification(notification);
+if (!response.id) {
+  console.error('Notification was not created:', response.errors);
+} else {
+  console.log('Notification ID:', response.id);
 }
 ```
 
-### Deleting a player
-Deletes a user record.
-
-**Example**
-```js
-const deletePlayerResponse = await client.deletePlayer(app.id, '<player id>')
-```
-
-### Getting outcomes
-View the details of all the outcomes associated with your app.
-
-🚧  **Requires your OneSignal App's REST API Key, available in Keys & IDs** 🚧
-
-Outcome data are accessible for 30 days before being deleted from our servers. You can export this data monthly if you need it for a more extended period.
-
-| Param               | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                     |
-|---------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| app_id              | string | The OneSignal App ID for your app.  Available in Keys &amp; IDs.                                                                                                                                                                                                                                                                                                                                                |
-| outcome_names       | string | Required Comma-separated list of names and the value (sum/count) for the returned outcome data. Note: Clicks only support count aggregation. For out-of-the-box OneSignal outcomes such as click and session duration, please use the “os” prefix with two underscores. For other outcomes, please use the name specified by the user. Example:os__session_duration.count,os__click.count,CustomOutcomeName.sum |
-| outcome_names2      | string | If outcome names contain any commas, then please specify only one value at a time. Example: `outcome_names[]=os__click.count&outcome_names[]=Sales, Purchase.count` where “Sales, Purchase” is the custom outcomes with a comma in the name.                                                                                                                                                                                                        |
-| outcome_time_range  | string | Optional Time range for the returned data. The values can be `1h` (for the last 1 hour data), `1d` (for the last 1 day data), or `1mo` (for the last 1 month data). Default is 1h if the parameter is omitted.                                                                                                                                                                                                        |
-| outcome_platforms   | string | Optional Platform id. Refer device&#39;s platform ids for values. **Example:** `outcome_platform=0` for iOS `outcome_platform=7`, `8` for Safari and Firefox Default is data from all platforms if the parameter is omitted.                                                                                                                                                                                     |
-| outcome_attribution | string | Optional Attribution type for the outcomes. The values can be direct or influenced or unattributed. Example: outcome_attribution=direct Default is total (returns direct+influenced+unattributed) if the parameter is omitted.                                                                                                                                                                             |
-
-**Example**
-```js
-const outcomes = await client.getOutcomes(app.id, 'os__click.count,os_session_duration.count,my_outcome.sum');
-```
-
-### Begin Live Activity
-Starts a Live Activity event
-```js
-// Create a player first
-const player = new OneSignal.Player();
-player.device_type = 0;
-player.app_id = '<app id>';
-const playerResponse = await api.createPlayer(player);
-
-// Prepare a request
-const beginLiveActivityRequest: BeginLiveActivityRequest = {
-    push_token: '<push_token>',
-    subscription_id: playerResponse.id!,
-};
-const activityId = '<activity_id>'; // any string
-
-// Begin activity
-await api.beginLiveActivity('<app_id>', activityId, beginLiveActivityRequest);
-```
-
-### Update Live Activity
-Updates a Live Activity event
-```js
-const updateLiveActivityRequest: UpdateLiveActivityRequest = {
-    event_updates: {
-        data: 'test'
-    },
-    event: "update",
-    name: "contents"
-};
-
-await api.updateLiveActivity('<app_id>', '<activity_id>', updateLiveActivityRequest);
-```
-
-### End Live Activity
-Stops a Live Activity event
-```js
-const subscriptionId = '<subscription_id>'; // player id
-await api.endLiveActivity('<app_id>', '<activity_id>', subscriptionId);
-```
-
-### Subscription types
-* iOSPush
-* AndroidPush
-* FireOSPush
-* ChromeExtensionPush
-* ChromePush
-* WindowsPush
-* SafariLegacyPush
-* FirefoxPush
-* macOSPush
-* HuaweiPush
-* SafariPush
-* Email
-* SMS
-
-## Users
-### Creating a OneSignal User
-```js
-const user = new OneSignal.User();
-
-const aliasLabel = '<alias_label>';
-const aliasId = '<alias_id>';
-const subscriptionToken = '<subscription_token>';
-
-user.identity = {
-    [aliasLabel]: aliasId,
-};
-
-user.subscriptions = [
-  {
-    type: "iOSPush",
-    token: subscriptionToken,
-  }
-];
-
-const createdUser = await api.createUser('<app_id>', user);
-assert(createdUser.identity!['onesignal_id'] != null);
-```
-
-### Getting a user by `onesignal_id`
-```js
-const oneisgnalAliasLabel = "onesignal_id";
-const onesignalAliasId = createdUser.identity!['onesignal_id'];
-
-const fetchedUser = await api.fetchUser('<app_id>', oneisgnalAliasLabel, onesignalAliasId);
-```
-
-### Getting a user by an alias
-```js
-const fetchedUser = await api.fetchUser('<app_id>', alias_label, alias_id);
-```
-
-### Updating a user
-```js
-const updateUserRequest: UpdateUserRequest = {
-    properties: {
-        language: 'fr'
-    }
-};
-
-const updatedUser = await api.updateUser('<app_id>', aliasLabel, aliasId, updateUserRequest);
-```
-
-### Deleting a user
-```js
-await api.deleteUser('<app_id>', aliasLabel, aliasId);
-```
+The API may return HTTP 200 with an empty `id` when no matching subscribed recipients are found; always check `response.id` and `response.errors`.
 
-## Subscriptions
-### Creating a subscription for existing user
-```js
-const createSubscriptionRequestBody: CreateSubscriptionRequestBody = {
-    subscription: {
-        type: "AndroidPush",
-        token: '<subscription_token>',
-    }
-};
-
-const response = await api.createSubscription('<app_id>', '<alias_label>', '<alias_id>', createSubscriptionRequestBody);
-```
+## Send an email
 
-### Updating a subscription
-```js
-const updateSubscriptionRequestBody: UpdateSubscriptionRequestBody = {
-    subscription: {
-        type: "iOSPush",
-        token: '<new-subscription-token>',
-    }
-};
-
-await api.updateSubscription('<app_id>', '<existing_subscription_id>', updateSubscriptionRequestBody);
-```
-
-### Deleting a subscription
-```js
-await api.deleteSubscription('<app_id>', '<subscription_id>');
-```
-
-### Transfer subscription ownership
-Transfers the subscription from one user to another.
-```js
-// Setting the user for transfering the subscription to. User is identyfied by an IdentityObject.
-const transferSubscriptionRequestBody: TransferSubscriptionRequestBody = {
-    identity: otherUserIdentityObject
-};
-
-const transferResponse = await api.transferSubscription('<app_id>', '<subscription_id>', transferSubscriptionRequestBody);
-```
-
-## Aliases
-### Fetching aliases for a user
-```js
-const fetchResponse = await api.fetchAliases('<app_id>', '<subscription_id>');
-```
-
-### Fetching user identity
-```js
-const fetchResponse = await api.fetchUserIdentity('<app_id>', '<alias_label>', '<alias_id>');
-```
-### Identifying user by alias
-```js
-const userIdentityRequestBody: UserIdentityRequestBody = {
-    identity: {
-        ['<new_alias_label>']: '<new_alias_id>'
-    }
-};
+```javascript
+const notification = new OneSignal.Notification();
+notification.app_id = 'YOUR_APP_ID';
+notification.email_subject = 'Important Update';
+notification.email_body = '<h1>Hello!</h1><p>This is an HTML email.</p>';
+notification.included_segments = ['Subscribed Users'];
+notification.channel_for_external_user_ids = 'email';
 
-const identifyResponse = await api.identifyUserByAlias('<app_id>', 
-                                                       '<existing_alias_label>', 
-                                                       '<existing_alias_id>',
-                                                       userIdentityRequestBody);
+const response = await client.createNotification(notification);
 ```
 
-### Identifying user by subscription id
-```js
-const userIdentityRequestBody: UserIdentityRequestBody = {
-    identity: {
-        ['<new_alias_label>']: '<new_alias_id>'
-    }
-};
+## Send an SMS
 
-const identifyResponse = await api.identifyUserBySubscriptionId('<app_id>', '<existing_subscription_id>', userIdentityRequestBody);
-```
+```javascript
+const notification = new OneSignal.Notification();
+notification.app_id = 'YOUR_APP_ID';
+notification.contents = { en: 'Your SMS message content here' };
+notification.included_segments = ['Subscribed Users'];
+notification.channel_for_external_user_ids = 'sms';
+notification.sms_from = '+15551234567';
 
-### Deleting an alias
-```js
-await api.deleteAlias('<app_id>', '<alias_label>', '<alias_id>', '<alias_label_to_delete>');
+const response = await client.createNotification(notification);
 ```
-## Author
-
-* Website: https://onesignal.com
-* Twitter: [@onesignal](https://twitter.com/onesignal)
-* Github: [@OneSignal](https://github.com/OneSignal)
-
-## 🤝 Contributing
-
-Contributions, issues and feature requests are welcome!<br />Feel free to check [issues page](https://github.com/OneSignal/node-onesignal/issues).
-
-## Show your support
-
-Give a ⭐️ if this project helped you!
 
-## 📝 License
+## Full API reference
 
-Copyright © 2023 [OneSignal](https://github.com/OneSignal).
+The complete list of API endpoints and their parameters is available in the [DefaultApi documentation](https://github.com/OneSignal/node-onesignal/blob/main/DefaultApi.md).
 
-This project is [MIT](https://github.com/OneSignal/node-onesignal/blob/main/LICENSE) licensed.
+For the underlying REST API, see the [OneSignal API reference](https://documentation.onesignal.com/reference).