Docs/Server SDKs/Node.js SDK

Node.js SDK

@emitwave/node — a server-side SDK that HMAC-signs and publishes events to the gateway.

Server SDK· 4 min read

Install

bash

npm install @emitwave/node

Requires Node.js 18+, an application ID, and an active server credential (public key + one-time secret). Keep the secret on the server — never in browser bundles, public env vars, logs, or API responses.

The key and secret are a server credential, not the browser public application key. For every request the SDK hashes the exact JSON body and signs the method, path, canonical query, and body hash with HMAC-SHA256.

Publish an event

trigger(channel, event, data) serializes the event, signs the body, and sends it to /apps/{appId}/events. The same method publishes to every external channel type; publishing permission does not bypass subscriber authorization.

publish.ts

import { Client } from '@emitwave/node'

const emitwave = new Client({
  appId: process.env.EMITWAVE_APP_ID,
  key: process.env.EMITWAVE_KEY,
  secret: process.env.EMITWAVE_SECRET,
  // gatewayUrl defaults to https://api.emitwave.com
})

await emitwave.trigger('orders', 'order.created', {
  id: 'ord_123',
  total: 4900,
})

Error handling

EmitwaveError represents a non-2xx gateway response; network failures remain ordinary transport errors. The SDK never adds the credential secret to its error message.

errors.ts

import { Client, EmitwaveError } from '@emitwave/node'

try {
  await emitwave.trigger('orders', 'order.created', { id: 'ord_123' })
} catch (error) {
  if (error instanceof EmitwaveError) {
    console.error('Emitwave rejected the event', error.status, error.body)
  } else {
    console.error('Transport or configuration error', error)
  }
}

Custom fetch

Node 18+ provides fetch. Tests or specialized runtimes can inject another implementation.

custom.ts

const emitwave = new Client({
  gatewayUrl: 'https://api.emitwave.com',
  appId, key, secret,
  fetch: customFetch,
})

This SDK publishes the provided JSON as-is. It does not build the ciphertext envelope for a private-encrypted channel — see Encryption.

← Previous

Vue

Python