@notificationapi/js

NotificationAPI TypeScript SDK

A fully-typed TypeScript SDK for the NotificationAPI, automatically generated from OpenAPI specifications.

Features

• ✅ Fully Typed - Complete TypeScript type definitions for all API endpoints
• ✅ Auto-Generated - Generated from OpenAPI spec, always up-to-date
• ✅ Promise-based - Modern async/await API
• ✅ Organized by Domain - APIs grouped by functionality (Users, Logs, Health, Slack)
• ✅ Fetch-based - Uses the standard Fetch API (works in Node.js 18+ and browsers)
• ✅ Multi-Region - Supports US, EU, and CA regions
• ✅ Multiple Auth Methods - API Key, Client Credentials, End User, and End User Hashed

Installation

Production (latest stable)

npm install @notificationapi/js

Alpha (pre-release for testing)

npm install @notificationapi/js@alpha

Building

The SDK uses an automated code generation pipeline:

• Generate OpenAPI types - Creates TypeScript API classes from OpenAPI spec
• Generate client wrapper - Automatically creates the client with all APIs
• Build - Compile TypeScript to JavaScript

Full build (runs all steps):

npm run build:full

Individual steps:

npm run generate           # Generate API classes from OpenAPI
npm run generate:client    # Generate client wrapper with all APIs
npm run build             # Compile TypeScript

How Client Generation Works

The client wrapper (src/client.ts) is automatically generated from a template (src/client.template.ts):

• Reads the OpenAPI spec to discover all API tags (Health, Logs, Users, Slack, etc.)
• Generates appropriate imports for all API classes
• Generates property declarations for each API
• Generates constructor instantiation code
• Runs prettier for consistent styling

This means you never need to manually update the client - just run npm run generate:client after updating the OpenAPI spec!

Usage

Basic Setup

The SDK supports four authentication methods:

• API Key (Bearer) - Server-side project authentication
• Client Credentials (Basic) - Server-side with clientId/clientSecret
• End User (Basic) - Client-side with clientId/userId
• End User Hashed (Basic) - Client-side with clientId/userId/hashedUserId

import { NotificationAPIClient } from '@notificationapi/js';

// Server-side: API Key (Bearer token)
const apiClient = new NotificationAPIClient({
  apiKey: process.env.API_KEY
});

// Server-side: Client Credentials (Basic)
const credentialsClient = new NotificationAPIClient({
  clientId: process.env.CLIENT_ID,
  clientSecret: process.env.CLIENT_SECRET
});

// Client-side: End User (Basic)
const endUserClient = new NotificationAPIClient({
  clientId: process.env.CLIENT_ID,
  userId: 'user123'
});

// Client-side: End User with Hash (Basic)
const hashedClient = new NotificationAPIClient({
  clientId: process.env.CLIENT_ID,
  userId: 'user123',
  hashedUserId: 'hashed-user-id'
});

Factory Methods (Convenience)

For cleaner code, use the static factory methods:

// API Key
const client = NotificationAPIClient.withApiKey('your-api-key');

// Client Credentials
const client = NotificationAPIClient.withClientCredentials(
  'clientId',
  'clientSecret'
);

// End User
const client = NotificationAPIClient.withEndUser('clientId', 'userId');

// End User Hashed
const client = NotificationAPIClient.withEndUserHashed(
  'clientId',
  'userId',
  'hashedUserId'
);

// With options (region, custom headers, etc.)
const euClient = NotificationAPIClient.withApiKey('your-api-key', {
  region: 'eu',
  headers: { 'X-Custom': 'value' }
});

Regions

NotificationAPI supports three regions:

• us (default): https://api.notificationapi.com
• eu: https://api.eu.notificationapi.com
• ca: https://api.ca.notificationapi.com

If neither region nor basePath is specified, the client defaults to the US region.

User Management

// Get a user
const user = await client.users.usersGet({
  accountId: 'abc123',
  userId: 'user456'
});

// Create or update a user
const updatedUser = await client.users.usersPost({
  accountId: 'abc123',
  userId: 'user456',
  postUserRequest: {
    email: '[e-mail]',
    number: '[phone]'
  }
});

// Delete a user
await client.users.usersDelete({
  accountId: 'abc123',
  userId: 'user456'
});

// Get account metadata
const metadata = await client.users.usersAccountMetadata({
  accountId: 'abc123'
});

Logs

// Get log retention settings
const retention = await client.logs.logsRetention({
  accountId: 'abc123'
});

// Tail recent logs
const recentLogs = await client.logs.logsTail({
  accountId: 'abc123'
});

// Query logs
const queryResponse = await client.logs.logsQuery({
  accountId: 'abc123',
  logQueryPostBody: {
    notificationId: 'welcome_email',
    startDate: '2024-01-01',
    endDate: '2024-01-31',
    userId: 'user456'
  }
});

// Get query results
const results = await client.logs.logsQueryQueryId({
  accountId: 'abc123',
  queryId: queryResponse.queryId
});

// Get logs by tracking IDs
const logs = await client.logs.logsTrackingIds({
  accountId: 'abc123',
  trackingIds: 'id1,id2,id3'
});

Health Check

const health = await client.health.healthGet();
console.log(health.message); // "Health checks passed."

Slack Integration

// Complete OAuth flow
const oauthResponse = await client.slack.usersSlackOauth({
  accountId: 'abc123',
  userId: 'user456',
  slackOauthRequest: {
    code: 'oauth-code',
    redirect_uri: 'https://yourapp.com/callback'
  }
});

// Get Slack channels
const channels = await client.slack.usersSlackChannels({
  accountId: 'abc123',
  userId: 'user456'
});

Advanced Configuration

// Change base path dynamically (e.g., for staging)
client.setBasePath('https://staging-api.notificationapi.com');

// Custom headers
const client = new NotificationAPIClient({
  apiKey: 'your-api-key',
  headers: {
    'X-Custom-Header': 'value',
    'X-Another-Header': 'another-value'
  }
});

// Custom fetch implementation (e.g., for Node.js < 18)
import fetch from 'node-fetch';

const clientWithCustomFetch = new NotificationAPIClient({
  apiKey: 'your-api-key',
  fetchApi: fetch as any
});

// Combining options with factory methods
const client = NotificationAPIClient.withClientCredentials(
  'clientId',
  'clientSecret',
  {
    region: 'eu',
    headers: { 'X-Custom': 'value' },
    fetchApi: customFetch
  }
);

Development

Prerequisites

• Node.js 16+
• OpenJDK 11+ (for SDK generation)
  • On macOS: OpenJDK is installed at /Library/Java/JavaVirtualMachines/
  • Ensure JAVA_HOME is set: export JAVA_HOME=/Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home
  • Add Java to PATH: export PATH="$JAVA_HOME/bin:$PATH"

Regenerate from OpenAPI Spec

When the API changes, regenerate the SDK:

# From the serverless root
npm run codegen

# Then regenerate the SDK
cd sdks/typescript
npm run generate
npm run build

Watch Mode

The root project has a watch mode that automatically regenerates the OpenAPI spec when handlers change:

# From the serverless root
npm run codegen:watch

Type Safety

The SDK provides full type safety:

// TypeScript will autocomplete and validate all parameters
const user = await client.users.usersGet({
  accountId: 'abc123', // ✅ Required, typed as string
  userId: 'user456' // ✅ Required, typed as string
});

// Response is fully typed
console.log(user.email); // ✅ string | undefined
console.log(user.webPushTokens); // ✅ PushToken[] | undefined
console.log(user.emailSuppressionStatus); // ✅ UserEmailSuppressionStatus | undefined

Generated APIs

The SDK includes the following API modules:

• HealthApi - Health check endpoints
• LogsApi - Log querying and retrieval
• UsersApi - User management
• SlackApi - Slack integration

All types are exported from the main package:

import {
  NotificationAPIClient,
  User,
  PostUserRequest,
  LogQueryPostBody,
  LogsRetentionResponse
  // ... all other types
} from '@notificationapi/js';

Error Handling

The SDK throws errors with detailed information:

try {
  await client.users.usersGet({
    accountId: 'invalid',
    userId: 'user'
  });
} catch (error) {
  console.error('API Error:', error);
}

License

MIT

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a pull request.