Emblem SDK v1

Contract-aligned SDK for the Emblem Publisher API (v1). This SDK is a thin adapter over HTTP and mirrors the public contract.

Requirements

• Node.js 18+ for server usage

Install

npm install @emblemapp/sdk

Server usage (apiKey)

import { createClient } from '@emblemapp/sdk'

const client = createClient({
  apiKey: process.env.EMBLEM_API_KEY,
})

const start = await client.startVerification({
  integration_id: '00000000-0000-0000-0000-000000000000',
  callback_url: 'https://publisher.example/callback',
  state: 'abc123',
})

// result_token is returned via redirect or webhook after verification completes
const result = await client.validateVerification({
  result_token: resultTokenFromCallback,
})

Browser usage (publicKey)

import { createClient } from '@emblemapp/sdk'

const client = createClient({
  publicKey: 'emb_pk_live_123',
})

await client.startVerification({
  integration_id: '00000000-0000-0000-0000-000000000000',
  callback_url: 'https://publisher.example/callback',
})

Warning: Secret API keys must never be used in browser contexts. validateVerification() is server-only.

Errors, rate limiting, retries, timeouts

The SDK throws an EmblemApiError when the API returns an error envelope.

import { EmblemApiError } from '@emblemapp/sdk'

try {
  await client.startVerification({
    integration_id: '00000000-0000-0000-0000-000000000000',
    callback_url: 'https://publisher.example/callback',
  })
} catch (err) {
  if (err instanceof EmblemApiError) {
    // Stable error code from the API contract.
    console.log(err.code)

    // Optional error metadata.
    console.log(err.request_id, err.details)

    // Rate limiting: check the code and respect Retry-After when provided.
    if (err.isRateLimited) {
      console.log('retryAfter (seconds):', err.retryAfter)
    }
  }
}

This SDK is a thin HTTP wrapper and does not implement retries or request timeouts. If you need timeouts, provide a custom fetch implementation (e.g. using AbortSignal.timeout() in Node 18+).

Webhook verification

import { verifyWebhookSignature } from '@emblemapp/sdk'

const isValid = verifyWebhookSignature({
  // X-Emblem-Signature: t={unix_seconds},v1={hex_hmac}
  signature: signatureHeaderValue,
  // X-Emblem-Timestamp: {unix_seconds}
  timestamp: timestampHeaderValue,
  rawBody: rawBodyString,
  secret: process.env.EMBLEM_WEBHOOK_SECRET,
})

Note: verifyWebhookSignature() is server-only. It requires a webhook secret and Node.js crypto.

Important: rawBody must be the exact raw request body used to compute the signature.

Type generation

Types are generated from openapi/emblem-publisher-api.yaml and committed to the repo. To regenerate:

npm run types:generate

To verify types are up to date:

npm run types:check