@zyphr-dev/node-sdk 0.1.1 → 0.1.3

package/README.md

@@ -1,6 +1,9 @@
 # @zyphr-dev/node-sdk
 
-Official Zyphr SDK for Node.js, React, and React Native.
+Official Zyphr SDK for Node.js, React, and React Native. Type-safe access to multi-channel notifications, subscriber management, webhooks, and authentication.
+
+[![npm version](https://img.shields.io/npm/v/@zyphr-dev/node-sdk)](https://www.npmjs.com/package/@zyphr-dev/node-sdk)
+[![license](https://img.shields.io/npm/l/@zyphr-dev/node-sdk)](./LICENSE)
 
 ## Installation
 
@@ -10,7 +13,7 @@ npm install @zyphr-dev/node-sdk
 yarn add @zyphr-dev/node-sdk
 ```
 
-Requires Node.js 18 or later.
+**Requirements:** Node.js 18+. Zero runtime dependencies.
 
 ## Quick Start
 
@@ -22,48 +25,425 @@ const zyphr = new Zyphr({
 });
 
 // Send an email
-const { data: email } = await zyphr.emails.send({
-  to: 'user@example.com',
+await zyphr.emails.sendEmail({
+  to: [{ email: 'user@example.com', name: 'Jane' }],
   subject: 'Welcome!',
-  html: '<h1>Hello!</h1>',
+  html: '<h1>Hello, {{name}}!</h1>',
+  templateData: { name: 'Jane' },
 });
 
 // Send a push notification
-await zyphr.push.send({
-  subscriber_id: 'sub_123',
-  title: 'New message',
-  body: 'You have a new notification',
+await zyphr.push.sendPush({
+  subscriberId: 'sub_123',
+  payload: { title: 'New message', body: 'You have a new notification' },
 });
 
 // Send an SMS
-await zyphr.sms.send({
+await zyphr.sms.sendSms({
   to: '+15551234567',
-  body: 'Your verification code is 123456',
+  message: 'Your verification code is 123456',
 });
 
 // Send an in-app notification
-await zyphr.inbox.send({
-  subscriber_id: 'sub_123',
+await zyphr.inbox.sendInApp({
+  subscriberId: 'sub_123',
   title: 'Welcome aboard',
   body: 'Thanks for signing up!',
 });
 ```
 
-## Available APIs
-
-| Property | Description |
-|----------|-------------|
-| `zyphr.emails` | Send and manage emails |
-| `zyphr.push` | Send push notifications |
-| `zyphr.sms` | Send SMS messages |
-| `zyphr.inbox` | In-app notifications |
-| `zyphr.subscribers` | Manage subscribers and preferences |
-| `zyphr.templates` | Create and render templates |
-| `zyphr.webhooks` | Configure and monitor webhooks |
-| `zyphr.topics` | Manage notification topics |
-| `zyphr.devices` | Manage push devices |
-| `zyphr.applications` | Manage applications |
-| `zyphr.auth.*` | Authentication APIs (login, registration, MFA, etc.) |
+## Configuration
+
+```ts
+const zyphr = new Zyphr({
+  apiKey: 'zy_live_xxxx',            // Required — your API key
+  baseUrl: 'https://custom.api.url', // Optional — defaults to https://api.zyphr.dev/v1
+});
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | `string` | — | **Required.** API key (`zy_live_*` or `zy_test_*`) |
+| `baseUrl` | `string` | `https://api.zyphr.dev/v1` | API base URL override |
+
+## API Reference
+
+### Emails — `zyphr.emails`
+
+Send transactional emails with template support, tracking, and scheduling.
+
+```ts
+// Send a single email
+await zyphr.emails.sendEmail({
+  to: [{ email: 'user@example.com', name: 'Jane' }],
+  from: { email: 'noreply@company.com', name: 'My App' },
+  subject: 'Order Confirmed',
+  html: '<h1>Order #{{orderId}} confirmed</h1>',
+  templateData: { orderId: '12345' },
+  tag: 'order-confirmation',
+  trackingEnabled: true,
+});
+
+// Send batch emails (up to 100)
+await zyphr.emails.sendBatchEmail({
+  messages: [
+    { to: [{ email: 'a@example.com' }], subject: 'Hello A', html: '...' },
+    { to: [{ email: 'b@example.com' }], subject: 'Hello B', html: '...' },
+  ],
+});
+
+// Get email details and tracking
+const email = await zyphr.emails.getEmail('email_id');
+const events = await zyphr.emails.getEmailEvents('email_id');
+const tracking = await zyphr.emails.getEmailTracking('email_id');
+
+// List emails with filtering
+const { data } = await zyphr.emails.listEmails('delivered', 'welcome', 20, 0);
+```
+
+**Send options:** `to`, `from`, `replyTo`, `cc`, `bcc`, `subject`, `html`, `text`, `templateId`, `templateData`, `tag`, `metadata`, `headers`, `trackingEnabled`, `sendAt`, `delay`.
+
+### SMS — `zyphr.sms`
+
+Send SMS messages with scheduling and provider configuration.
+
+```ts
+// Send SMS
+await zyphr.sms.sendSms({
+  to: '+15551234567',
+  message: 'Your code is 123456',
+});
+
+// Batch send (up to 100)
+await zyphr.sms.sendBatchSms({
+  messages: [
+    { to: '+15551234567', message: 'Hello from Zyphr' },
+    { to: '+15559876543', message: 'Hello from Zyphr' },
+  ],
+});
+
+// Manage SMS provider configuration
+const config = await zyphr.sms.getSmsConfig();
+await zyphr.sms.upsertSmsConfig({
+  provider: 'twilio',
+  accountSid: 'AC...',
+  authToken: '...',
+  fromNumber: '+15550001234',
+});
+await zyphr.sms.verifySmsConfig();
+
+// List and inspect
+const list = await zyphr.sms.listSms(1, 20, 'delivered');
+const detail = await zyphr.sms.getSms('sms_id');
+```
+
+### Push Notifications — `zyphr.push`
+
+Send push notifications to individual devices, subscribers, or topic subscribers.
+
+```ts
+// Send to a subscriber (all their devices)
+await zyphr.push.sendPush({
+  subscriberId: 'sub_123',
+  payload: {
+    title: 'New Order',
+    body: 'Order #12345 has been placed',
+    icon: 'https://cdn.example.com/icon.png',
+    clickAction: 'https://app.example.com/orders/12345',
+    customData: { orderId: '12345' },
+  },
+  priority: 'high',
+  ttl: 3600,
+});
+
+// Send to a topic
+await zyphr.push.sendPushToTopic('product-updates', {
+  payload: { title: 'New Feature', body: 'Check out our latest update' },
+});
+
+// Topic management
+await zyphr.push.subscribePushTopic('alerts', { deviceIds: ['device_1'] });
+await zyphr.push.unsubscribePushTopic('alerts', { deviceIds: ['device_1'] });
+
+// Stats and listing
+const stats = await zyphr.push.getPushStats();
+const pushes = await zyphr.push.listPush('sub_123');
+```
+
+### In-App Inbox — `zyphr.inbox`
+
+Manage in-app notifications for the `@zyphr-dev/inbox-react` component library.
+
+```ts
+// Send in-app notification
+await zyphr.inbox.sendInApp({
+  subscriberId: 'sub_123',
+  title: 'New comment',
+  body: 'Someone replied to your post',
+  category: 'comments',
+  cta: { label: 'View Comment', action: '/posts/456#comments' },
+  icon: 'https://cdn.example.com/comment.svg',
+});
+
+// Batch send (up to 100)
+await zyphr.inbox.sendBatchInApp({
+  notifications: [
+    { subscriberId: 'sub_123', title: 'Hello', body: '...' },
+    { subscriberId: 'sub_456', title: 'Hello', body: '...' },
+  ],
+});
+
+// Read operations
+const unread = await zyphr.inbox.getUnreadCount('sub_123');
+const notifications = await zyphr.inbox.listInbox('sub_123');
+
+// Actions
+await zyphr.inbox.markInboxRead('notification_id');
+await zyphr.inbox.markAllInboxRead({ subscriberId: 'sub_123' });
+await zyphr.inbox.archiveInboxNotification('notification_id');
+await zyphr.inbox.deleteInboxNotification('notification_id');
+```
+
+### Subscribers — `zyphr.subscribers`
+
+Manage subscribers, their preferences, and consent records.
+
+```ts
+// Create/upsert subscriber
+const subscriber = await zyphr.subscribers.createSubscriber({
+  externalId: 'user_123',
+  email: 'jane@example.com',
+  name: 'Jane Doe',
+  timezone: 'America/New_York',
+  metadata: { plan: 'pro', company: 'Acme' },
+});
+
+// Get by ID or external ID
+const sub = await zyphr.subscribers.getSubscriber('sub_id');
+const subByExt = await zyphr.subscribers.getSubscriberByExternalId('user_123');
+
+// Update
+await zyphr.subscribers.updateSubscriber('sub_id', {
+  name: 'Jane Smith',
+  metadata: { plan: 'enterprise' },
+});
+
+// List with filtering
+const subs = await zyphr.subscribers.listSubscribers('subscribed', undefined, 50, 0);
+
+// Preferences
+const prefs = await zyphr.subscribers.getSubscriberPreferences('sub_id');
+await zyphr.subscribers.setSubscriberPreferences('sub_id', {
+  categoryId: 'marketing',
+  subscribed: false,
+  channel: 'email',
+});
+
+// Unsubscribe/resubscribe
+await zyphr.subscribers.unsubscribeSubscriber('sub_id');
+await zyphr.subscribers.resubscribeSubscriber('sub_id');
+
+// Consent management
+await zyphr.subscribers.recordSubscriberConsent('sub_id', {
+  type: 'opt_in', source: 'signup_form',
+});
+const consent = await zyphr.subscribers.getSubscriberConsent('sub_id');
+const history = await zyphr.subscribers.getSubscriberConsentHistory('sub_id');
+
+// Categories
+const category = await zyphr.subscribers.createCategory({
+  name: 'Product Updates', slug: 'product-updates',
+});
+```
+
+### Templates — `zyphr.templates`
+
+Create and manage reusable email templates with variable substitution.
+
+```ts
+// Create template
+const template = await zyphr.templates.createTemplate({
+  name: 'welcome-email',
+  subject: 'Welcome, {{name}}!',
+  html: '<h1>Hello {{name}}</h1><p>Welcome to {{company}}.</p>',
+  variables: ['name', 'company'],
+});
+
+// Render template (preview without sending)
+const rendered = await zyphr.templates.renderTemplate('template_id', {
+  data: { name: 'Jane', company: 'Acme' },
+});
+
+// CRUD operations
+const t = await zyphr.templates.getTemplate('template_id');
+await zyphr.templates.updateTemplate('template_id', { subject: 'New subject' });
+await zyphr.templates.deleteTemplate('template_id');
+const all = await zyphr.templates.listTemplates(20, 0);
+```
+
+### Webhooks — `zyphr.webhooks`
+
+Configure webhook endpoints, monitor deliveries, and manage circuit breakers.
+
+```ts
+// Create webhook
+const webhook = await zyphr.webhooks.createWebhook({
+  url: 'https://api.example.com/webhooks',
+  events: ['email.delivered', 'email.bounced', 'subscriber.created'],
+  active: true,
+});
+
+// Delivery management
+const deliveries = await zyphr.webhooks.listWebhookDeliveries(
+  'webhook_id', 'failed', undefined, undefined, undefined, undefined, 20, 0
+);
+await zyphr.webhooks.retryWebhookDelivery('webhook_id', 'delivery_id');
+await zyphr.webhooks.bulkRetryWebhookDeliveries('webhook_id', {
+  status: 'failed', startDate: new Date('2026-01-01'),
+});
+
+// Replay events
+await zyphr.webhooks.replayWebhookEvents('webhook_id', {
+  startDate: new Date('2026-01-01'), endDate: new Date('2026-01-02'),
+});
+
+// Testing
+await zyphr.webhooks.sendWebhookTestEvent('webhook_id', {
+  eventType: 'email.delivered',
+});
+
+// Metrics and health
+const metrics = await zyphr.webhooks.getWebhookMetrics('webhook_id');
+const circuit = await zyphr.webhooks.getWebhookCircuitState('webhook_id');
+await zyphr.webhooks.closeWebhookCircuit('webhook_id');
+
+// Secret rotation
+await zyphr.webhooks.rotateWebhookSecret('webhook_id');
+
+// Metadata
+const eventTypes = await zyphr.webhooks.listWebhookEventTypes();
+const versions = await zyphr.webhooks.listWebhookVersions();
+const ips = await zyphr.webhooks.getWebhookIps();
+```
+
+### Topics — `zyphr.topics`
+
+Group subscribers by interest for targeted notifications.
+
+```ts
+// Create topic
+await zyphr.topics.createTopic({
+  key: 'product-updates',
+  name: 'Product Updates',
+  description: 'New features and releases',
+});
+
+// Manage subscribers
+await zyphr.topics.addTopicSubscribers('product-updates', {
+  subscriberIds: ['sub_123', 'sub_456'],
+});
+await zyphr.topics.removeTopicSubscribers('product-updates', ['sub_789']);
+
+// CRUD
+const topic = await zyphr.topics.getTopic('product-updates');
+await zyphr.topics.updateTopic('product-updates', { name: 'Product News' });
+await zyphr.topics.deleteTopic('old-topic');
+const topics = await zyphr.topics.listTopics(50, 0);
+```
+
+### Devices — `zyphr.devices`
+
+Register and manage push notification devices.
+
+```ts
+// Register device
+const device = await zyphr.devices.registerDevice({
+  userId: 'user_123',
+  platform: 'ios',
+  pushToken: 'apns_token_xxx',
+  deviceName: 'iPhone 16 Pro',
+});
+
+// List devices
+const devices = await zyphr.devices.listDevices('user_123', 'ios', 20, 0);
+
+// Stats
+const stats = await zyphr.devices.getDeviceStats();
+
+// Cleanup
+await zyphr.devices.deleteDevice('device_id');
+await zyphr.devices.deleteUserDevices('user_123');
+```
+
+### Authentication — `zyphr.auth.*`
+
+Full authentication API with login, registration, MFA, magic links, OAuth, and more.
+
+```ts
+// Login
+const session = await zyphr.auth.login.loginEndUser({
+  email: 'user@example.com',
+  password: 'secure_password',
+});
+
+// Registration
+await zyphr.auth.registration.registerUser({
+  email: 'new@example.com',
+  password: 'secure_password',
+  name: 'New User',
+});
+
+// Email verification
+await zyphr.auth.emailVerification.sendVerification('user@example.com');
+
+// Password reset
+await zyphr.auth.passwordReset.requestReset('user@example.com');
+
+// Magic links
+await zyphr.auth.magicLinks.sendMagicLink('user@example.com');
+
+// MFA
+const mfaStatus = await zyphr.auth.mfa.getMfaStatus();
+await zyphr.auth.mfa.enrollMfa({ method: 'totp' });
+
+// User profile
+const profile = await zyphr.auth.profile.getProfile();
+await zyphr.auth.profile.updateProfile({ name: 'Updated Name' });
+```
+
+**Available auth modules:** `login`, `registration`, `sessions`, `emailVerification`, `passwordReset`, `magicLinks`, `mfa`, `oauth`, `phone`, `webauthn`, `profile`.
+
+### WaaS — `zyphr.waas.*`
+
+Webhooks-as-a-Service: multi-tenant webhook delivery infrastructure for your customers.
+
+```ts
+// Create a WaaS application
+const app = await zyphr.waas.applications.createWaaSApplication({
+  name: 'My SaaS',
+  description: 'Webhook delivery for My SaaS customers',
+});
+
+// Define event types
+await zyphr.waas.eventTypes.createEventType(app.data.id, {
+  eventType: 'order.created',
+  name: 'Order Created',
+  description: 'Fired when a new order is placed',
+  examplePayload: { order_id: '123', total: 99.99 },
+});
+
+// Send events to all subscribed endpoints
+await zyphr.waas.events.sendEvent(app.data.id, {
+  eventType: 'order.created',
+  payload: { order_id: '456', total: 149.99 },
+});
+
+// Generate portal token for embedded UI
+const portalToken = await zyphr.waas.portal.getPortalToken(app.data.id);
+// Pass this token to @zyphr-dev/webhook-portal
+```
+
+**Available WaaS modules:** `applications`, `eventTypes`, `endpoints`, `events`, `deliveries`, `portal`.
 
 ## Error Handling
 
@@ -80,41 +460,50 @@ import {
 } from '@zyphr-dev/node-sdk';
 
 try {
-  await zyphr.subscribers.get('non_existent_id');
+  await zyphr.subscribers.getSubscriber('non_existent_id');
 } catch (error) {
   if (error instanceof ZyphrNotFoundError) {
-    console.log('Not found:', error.message);       // 404
+    console.log('Not found:', error.message);        // 404
   } else if (error instanceof ZyphrValidationError) {
-    console.log('Invalid input:', error.details);    // 400/422
+    console.log('Invalid input:', error.details);     // 400/422
   } else if (error instanceof ZyphrAuthenticationError) {
-    console.log('Check your API key');               // 401/403
+    console.log('Check your API key');                // 401/403
   } else if (error instanceof ZyphrRateLimitError) {
-    console.log('Retry after:', error.retryAfter);   // 429
+    console.log('Retry after:', error.retryAfter);    // 429
   } else if (error instanceof ZyphrError) {
     console.log('API error:', error.status, error.code);
   }
 }
 ```
 
-All error classes extend `ZyphrError`, which extends `Error`. Common properties:
+### Error Properties
 
-- `status` — HTTP status code
-- `code` — Machine-readable error code
-- `requestId` — Request ID for support
-- `details` — Additional error context (validation errors)
+All error classes extend `ZyphrError`, which extends `Error`:
 
-## Configuration
+| Property | Type | Description |
+|----------|------|-------------|
+| `status` | `number` | HTTP status code |
+| `code` | `string \| undefined` | Machine-readable error code |
+| `requestId` | `string \| undefined` | Request ID for support tickets |
+| `details` | `Record<string, unknown> \| undefined` | Validation errors and context |
+| `retryAfter` | `number \| undefined` | Seconds to wait (`ZyphrRateLimitError` only) |
 
-```ts
-const zyphr = new Zyphr({
-  apiKey: 'zy_live_xxxx',            // Required
-  baseUrl: 'https://custom.api.url', // Optional override
-});
-```
+## Bundle
+
+Dual-format build — works with both ESM and CommonJS:
+
+- **ESM:** `dist/index.js`
+- **CommonJS:** `dist/index.cjs`
+- **Types:** `dist/index.d.ts`
+
+Zero runtime dependencies.
 
-## Examples
+## Related Packages
 
-See the [examples/](./examples/) directory for complete usage examples covering all APIs.
+| Package | Description |
+|---------|-------------|
+| [`@zyphr-dev/inbox-react`](https://www.npmjs.com/package/@zyphr-dev/inbox-react) | Drop-in React notification inbox components |
+| [`@zyphr-dev/webhook-portal`](https://www.npmjs.com/package/@zyphr-dev/webhook-portal) | Embeddable webhook management portal |
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zyphr-dev/node-sdk",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Official Zyphr SDK for Node.js, React, and React Native",
   "type": "module",
   "main": "./dist/index.cjs",