Public API

createConfiguration

function createConfiguration(conf: ConfigurationParameters): Configuration;

Factory that builds a Configuration object from partial parameters. Pass restApiKey for most endpoints or organizationApiKey for org-level operations. Defaults: baseServer = server1 (https://api.onesignal.com), empty middleware array, isomorphic fetch HTTP adapter.

DefaultApi

class DefaultApi {
  constructor(configuration: Configuration);
  createNotification(notification: Notification): Promise<CreateNotificationSuccessResponse>;
  getNotification(appId: string, notificationId: string): Promise<NotificationWithMeta>;
  getApp(appId: string): Promise<App>;
  // ...many more endpoints; see DefaultApi.md
}

The primary API client. Instantiate it with a Configuration and call its methods to interact with every OneSignal REST endpoint. All methods return Promises.

Middleware / PromiseMiddleware

interface PromiseMiddleware {
  pre(context: RequestContext): Promise<RequestContext>;
  post(context: ResponseContext): Promise<ResponseContext>;
}

Use these interfaces to intercept outgoing requests (e.g. to log, mutate headers) or incoming responses (e.g. to log errors, transform payloads). Pass instances via ConfigurationParameters.promiseMiddleware.

Working examples

Scenario - Send a push notification to all subscribers

Create a Notification model, set the required fields, and call createNotification. The response includes the OneSignal notification ID for tracking.

import { createConfiguration, DefaultApi, Notification } from '../source/index';

const config = createConfiguration({
  restApiKey: process.env.ONESIGNAL_REST_API_KEY!,
});
const client = new DefaultApi(config);

async function sendPush(): Promise<void> {
  const notification = new Notification();
  notification.app_id = process.env.ONESIGNAL_APP_ID!;
  notification.contents = { en: 'Hello from the server!' };
  notification.headings = { en: 'New Alert' };
  notification.included_segments = ['Subscribed Users'];

  const response = await client.createNotification(notification);
  console.log('Created notification ID:', response.id);
}

sendPush().catch(console.error);

Scenario - Log all outgoing requests with a PromiseMiddleware

Register a custom PromiseMiddleware to inspect the RequestContext before every API call — useful for debugging or auditing.

import {
  createConfiguration,
  DefaultApi,
  Notification,
} from '../source/index';
import { PromiseMiddleware } from '../source/middleware';
import { RequestContext, ResponseContext } from '../source/http/http';

const loggingMiddleware: PromiseMiddleware = {
  async pre(context: RequestContext): Promise<RequestContext> {
    console.log(`[PRE] ${context.getHttpMethod()} ${context.getUrl()}`);
    return context;
  },
  async post(context: ResponseContext): Promise<ResponseContext> {
    console.log(`[POST] status: ${context.httpStatusCode}`);
    return context;
  },
};

const config = createConfiguration({
  restApiKey: process.env.ONESIGNAL_REST_API_KEY!,
  promiseMiddleware: [loggingMiddleware],
});

const client = new DefaultApi(config);

const n = new Notification();
n.app_id = process.env.ONESIGNAL_APP_ID!;
n.contents = { en: 'Middleware test' };
n.included_segments = ['Test Users'];
client.createNotification(n).then(r => console.log(r.id));

Scenario - Send an email notification

Use the same Notification model but set email_subject, email_body, and channel_for_external_user_ids to target the email channel.

import { createConfiguration, DefaultApi, Notification } from '../source/index';

const config = createConfiguration({
  restApiKey: process.env.ONESIGNAL_REST_API_KEY!,
});
const client = new DefaultApi(config);

async function sendEmail(): Promise<void> {
  const notification = new Notification();
  notification.app_id = process.env.ONESIGNAL_APP_ID!;
  notification.email_subject = 'Your weekly digest';
  notification.email_body = '<h1>Hello!</h1><p>Here is your update.</p>';
  notification.included_segments = ['Subscribed Users'];
  notification.channel_for_external_user_ids = 'email';

  const response = await client.createNotification(notification);
  console.log('Email notification ID:', response.id);
}

sendEmail().catch(console.error);

File walkthrough

• index.ts - Barrel file; re-exports everything the consumer needs (DefaultApi, Notification, createConfiguration, Middleware, etc.).
• configuration.ts - Defines ConfigurationParameters, Configuration interface, and the createConfiguration factory that merges auth, server, and middleware settings.
• middleware.ts - Declares the Middleware (Observable-based) and PromiseMiddleware interfaces; provides PromiseMiddlewareWrapper to bridge them.
• servers.ts - ServerConfiguration generic class for URL template resolution; exports server1 (https://api.onesignal.com) as the default.
• util.ts - Two pure utility functions (isCodeInRange, canConsumeForm) used internally by generated API code.
• rxjsStub.ts - Minimal Observable/from shim so the SDK does not require a full RxJS dependency.
• apis/DefaultApi.ts - All REST endpoint implementations as class methods returning Promises.
• apis/baseapi.ts - Abstract base class for generated API classes; exports RequiredError.
• apis/exception.ts - ApiException class thrown on non-2xx responses.
• auth/auth.ts - configureAuthMethods and supporting types for REST API key and Organization API key schemes.
• http/http.ts - RequestContext, ResponseContext, HttpLibrary interface, and HttpMethod enum.
• http/isomorphic-fetch.ts - Default HttpLibrary implementation using the global fetch.
• models/ - One file per model (e.g. Notification.ts, App.ts); plus ObjectSerializer.ts for (de)serialization.
• types/ - Promise-based API wrappers generated from the Observable-based core; PromiseDefaultApi is exported as DefaultApi.

Common pitfalls and fixes

• Missing fetch in Node < 18 — install node-fetch and assign global.fetch = require('node-fetch') before importing the SDK, or use --experimental-fetch on Node 17.
• btoa not defined — the SDK depends on btoa; in Node < 16 add global.btoa = (str) => Buffer.from(str).toString('base64') at your entry point.
• restApiKey vs organizationApiKey confusion — most app-level endpoints (notifications, users) require restApiKey; org-level endpoints (create/list apps) require organizationApiKey. Passing the wrong key returns a 401 that looks like a network error.
• ESM/CJS interop — if your project uses "type": "module", the SDK ships CommonJS; wrap imports with createRequire or set "moduleResolution": "bundler" in tsconfig and use a bundler like esbuild.
• ApiException not caught — the SDK throws ApiException (from apis/exception.ts) on HTTP errors; catch it explicitly: catch (e) { if (e instanceof ApiException) ... }.
• TypeScript path aliases not resolved at runtime — if you add paths to tsconfig, also configure tsconfig-paths or tsc-alias so compiled JS resolves the aliases; otherwise module not found errors appear at runtime.

Vibe-coding prompt template

I have the OneSignal Node.js Server SDK source code located in `source/` and
its integration guide at `USAGE.md`. The upstream package is
`@onesignal/node-onesignal@5.5.0`.

Please integrate the SDK into my existing project step by step:

1. Read `USAGE.md` in full for correct import paths, types, and examples.
2. Install all required dependencies listed in the "Required dependencies" section.
3. Create a shared client module at `src/onesignalClient.ts` that reads API
   keys from environment variables and exports a configured `DefaultApi` instance.
4. Add a utility function `sendPushNotification(appId, contents, segments)` that
   uses the shared client to call `client.createNotification(...)` and returns
   the notification ID.
5. Add error handling that catches `ApiException` (from `source/apis/exception`)
   and logs the HTTP status code and body.
6. Show me the final file tree of modified/added files.

Do not invent any API methods or types. Only use exports visible in
`source/index.ts` and documented in `USAGE.md`.

License and credit

The source is licensed under the MIT License — see source/LICENSE for the full text. Upstream package: @onesignal/node-onesignal by OneSignal, Inc. Repository: github.com/OneSignal/node-onesignal.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Plivo Node.js SDK for Voice and Messaging

WordPress & WooCommerce Plugins

Free