NotificationAPI Node.js Server SDK

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported

  cause Attempting to import the NotificationAPI SDK using CommonJS `require()` syntax in an environment configured for ES Modules, or if the SDK is ESM-only.
  fix Use ES Module `import` syntax: `import { NotificationAPI } from 'notificationapi-node-server-sdk';` ensure your `package.json` has `"type": "module"` if using ESM for your project, or configure your TypeScript/bundler appropriately.

• TypeError: Cannot read properties of undefined (reading 'send')

  cause The NotificationAPI client was not correctly initialized, or `clientId`/`clientSecret` were missing, leading to an undefined or improperly constructed object.
  fix Verify that `new NotificationAPI({ clientId, clientSecret })` is called with valid credentials and that the `notificationapi` object is available in scope before attempting to call its methods.

• API Error: Invalid credentials

  cause The provided `clientId` or `clientSecret` are incorrect, expired, or lack the necessary permissions to perform the requested operation.
  fix Double-check your `NOTIFICATIONAPI_CLIENT_ID` and `NOTIFICATIONAPI_CLIENT_SECRET` environment variables. Ensure they match the keys from your NotificationAPI dashboard and have the required permissions.

Warnings

• breaking Future major versions of this SDK may drop support for older Node.js LTS versions (e.g., Node.js 16 or 18 as Node.js 20+ becomes prevalent). Always check the release notes for minimum Node.js requirements before upgrading to a new major SDK version.
  Fix: Ensure your Node.js runtime environment meets the minimum version specified in the SDK's `package.json` or release notes before upgrading the SDK. Consider using Node.js LTS versions for production.
• gotcha API Keys (ClientId and ClientSecret) should never be hardcoded directly into your application's source code, especially in client-side bundles. Exposure of these keys can lead to unauthorized access to your NotificationAPI account.
  Fix: Store API keys as environment variables (e.g., `process.env.NOTIFICATIONAPI_CLIENT_ID`) and inject them securely at runtime. For serverless functions, use secrets management services provided by your cloud provider.
• breaking Changes in the NotificationAPI platform's API or data models may necessitate updates to the SDK, potentially introducing breaking changes in method signatures or response structures. Always review the migration guide when upgrading major SDK versions.
  Fix: Consult the official NotificationAPI documentation and SDK release notes for specific migration steps when upgrading across major versions. Update your payload structures and method calls accordingly.
• gotcha Incorrectly formatted notification payloads (e.g., missing required fields, invalid types) will result in API errors. The SDK may perform basic validation, but robust server-side validation is still essential.
  Fix: Refer to the NotificationAPI documentation for exact payload schemas for each notification type. Implement thorough input validation on your backend before constructing and sending payloads via the SDK.

Install

• npm install notificationapi-node-server-sdk npm
• yarn add notificationapi-node-server-sdk yarn
• pnpm add notificationapi-node-server-sdk pnpm

Imports

• NotificationAPI
  wrong:

  const NotificationAPI = require('notificationapi-node-server-sdk');

  correct:

  import { NotificationAPI } from 'notificationapi-node-server-sdk';

  The SDK primarily uses ES Modules. While Node.js has CJS-ESM interop, direct `require` statements for this package can lead to `ERR_REQUIRE_ESM` errors in certain configurations, especially with TypeScript or modern build setups. Prefer ESM `import`.
• NotificationAPI
  wrong:

  import { NotificationApi } from 'notificationapi-node-server-sdk';

  correct:

  import NotificationAPI from 'notificationapi-node-server-sdk';

  The main class is typically exported as a named export. A default import might not be available or could lead to undefined behavior if the package structure changes. Be mindful of casing for 'NotificationAPI' (PascalCase).
• NotificationAPIClientConfig

  import type { NotificationAPIClientConfig } from 'notificationapi-node-server-sdk';

  For type-checking configuration objects without importing the runtime value, use `import type` for better tree-shaking and to avoid accidental runtime imports.

Quickstart

Demonstrates initializing the NotificationAPI SDK with environment variables and sending a basic welcome notification to a user with merge tags.

import { NotificationAPI } from 'notificationapi-node-server-sdk';

const CLIENT_ID = process.env.NOTIFICATIONAPI_CLIENT_ID ?? '';
const CLIENT_SECRET = process.env.NOTIFICATIONAPI_CLIENT_SECRET ?? '';

if (!CLIENT_ID || !CLIENT_SECRET) {
  console.error('Environment variables NOTIFICATIONAPI_CLIENT_ID and NOTIFICATIONAPI_CLIENT_SECRET must be set.');
  process.exit(1);
}

const notificationapi = new NotificationAPI({
  clientId: CLIENT_ID,
  clientSecret: CLIENT_SECRET,
});

async function sendExampleNotification() {
  try {
    const response = await notificationapi.send({
      notificationId: 'user_welcome',
      user: {
        id: 'test-user-123',
        email: 'test@example.com',
        // Additional user properties like 'name', 'phone_number' can be added
      },
      mergeTags: {
        firstName: 'John',
        lastName: 'Doe',
        welcomeMessage: 'Welcome to our service!',
      },
    });
    console.log('Notification sent successfully:', response);
  } catch (error) {
    console.error('Failed to send notification:', error);
  }
}

sendExampleNotification();