Node.js SDK

The official Zyphr SDK for Node.js, React, and React Native. Auto-generated from the OpenAPI specification using native fetch - zero dependencies.

Installation

npm install @zyphr-dev/node-sdk
# or
yarn add @zyphr-dev/node-sdk

Quick Start

import { Configuration, EmailsApi } from '@zyphr-dev/node-sdk';

const config = new Configuration({
  apiKey: process.env.ZYPHR_API_KEY,
});

const emails = new EmailsApi(config);

const result = await emails.sendEmail({
  sendEmailRequest: {
    to: 'user@example.com',
    subject: 'Welcome!',
    html: '<h1>Hello!</h1>',
  },
});

console.log(`Email sent: ${result.id}`);

Configuration

import { Configuration } from '@zyphr-dev/node-sdk';

const config = new Configuration({
  apiKey: 'zy_live_xxx',
  basePath: 'https://api.zyphr.dev/v1', // Custom API endpoint
  headers: {
    'X-Custom-Header': 'value',
  },
});

API Classes

The SDK exposes one API class per resource:

Class	Description
EmailsApi	Send and manage email messages
PushApi	Send push notifications
SmsApi	Send SMS text messages
InboxApi	In-app notification inbox
SubscribersApi	Manage subscriber profiles
DevicesApi	Register push notification devices
TemplatesApi	Create and manage templates
TopicsApi	Pub/sub topics
WebhooksApi	Configure webhook endpoints

Emails

Send Email

import { EmailsApi, Configuration } from '@zyphr-dev/node-sdk';

const emails = new EmailsApi(new Configuration({
  apiKey: process.env.ZYPHR_API_KEY,
}));

const email = await emails.sendEmail({
  sendEmailRequest: {
    to: 'user@example.com',
    from: 'hello@yourapp.com',
    subject: 'Welcome to our app!',
    html: '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
    text: 'Welcome! Thanks for signing up.',
    replyTo: 'support@yourapp.com',
    tags: ['welcome', 'onboarding'],
    metadata: { userId: 'user_123' },
  },
});

Send with Template

const email = await emails.sendEmail({
  sendEmailRequest: {
    to: 'user@example.com',
    templateId: 'welcome-email',
    templateData: {
      name: 'John',
      actionUrl: 'https://yourapp.com/activate',
    },
  },
});

Get Email Status

const email = await emails.getEmail({ id: 'msg_abc123' });
console.log(`Status: ${email.status}`);

List Emails

const { data, meta } = await emails.listEmails({
  page: 1,
  perPage: 25,
});

Push Notifications

import { PushApi, Configuration } from '@zyphr-dev/node-sdk';

const push = new PushApi(new Configuration({
  apiKey: process.env.ZYPHR_API_KEY,
}));

await push.sendPush({
  sendPushRequest: {
    userId: 'user_123',
    title: 'New Message',
    body: 'You have a new message',
    data: { messageId: 'msg_456' },
  },
});

SMS

import { SmsApi, Configuration } from '@zyphr-dev/node-sdk';

const sms = new SmsApi(new Configuration({
  apiKey: process.env.ZYPHR_API_KEY,
}));

const result = await sms.sendSms({
  sendSmsRequest: {
    to: '+14155551234',
    body: 'Your verification code is 123456',
  },
});

In-App Inbox

import { InboxApi, Configuration } from '@zyphr-dev/node-sdk';

const inbox = new InboxApi(new Configuration({
  apiKey: process.env.ZYPHR_API_KEY,
}));

await inbox.sendInboxNotification({
  sendInboxRequest: {
    subscriberId: 'user_123',
    title: 'New Comment',
    body: 'John commented on your post',
    actionUrl: '/posts/123#comments',
  },
});

Subscribers

import { SubscribersApi, Configuration } from '@zyphr-dev/node-sdk';

const subscribers = new SubscribersApi(new Configuration({
  apiKey: process.env.ZYPHR_API_KEY,
}));

const subscriber = await subscribers.createSubscriber({
  createSubscriberRequest: {
    externalId: 'user_123',
    email: 'user@example.com',
    phone: '+14155551234',
    name: 'John Doe',
    metadata: { plan: 'pro' },
  },
});

Error Handling

try {
  await emails.sendEmail({ sendEmailRequest: { /* ... */ } });
} catch (error) {
  if (error instanceof Response) {
    const body = await error.json();
    console.log(`API error: ${body.error.code} - ${body.error.message}`);
  } else {
    throw error;
  }
}

Platform Compatibility

This SDK uses native fetch and works on:

• Node.js 18+ (native fetch)
• React (browser fetch)
• React Native (polyfilled fetch)
• Deno and Bun (native fetch)
• Edge runtimes (Cloudflare Workers, Vercel Edge)

Requirements

• Node.js 18.0 or later (for native fetch support)
• TypeScript 4.7+ (for TypeScript users)