subdomain.to Node.js SDK

@subdomainto/node is the typed, server-side JavaScript and TypeScript SDK for adding customer custom domains to a SaaS product. It covers destination setup, domain onboarding, DNS instructions, TLS and routing status, widget sessions, usage, and signed webhook verification.

Installation

npm install @subdomainto/node

Node.js 20 or later is required. Keep the API key and webhook secret in server-side environment variables; this package is not intended for browser bundles.

Connect a customer domain

import { SubdomainTo } from '@subdomainto/node';

const client = new SubdomainTo({
  apiKey: process.env.SUBDOMAINTO_API_KEY!,
});

const destination = await client.destinations.create(
  'https://app.example.com',
  'main-destination',
);

const domain = await client.domains.create(
  'portal.customer.com',
  'customer-42-domain',
  { destinationId: destination.id },
);

console.log(domain.dns_records, domain.certificate_status, domain.routing_status);

Creation methods require an explicit, stable idempotency key. The SDK performs no implicit retries, so retry policy remains under your application's control.

Verify signed webhooks

import { verifyWebhook } from '@subdomainto/node';

const event = verifyWebhook(
  rawRequestBody,
  request.headers.get('SubdomainTo-Signature') ?? '',
  process.env.SUBDOMAINTO_WEBHOOK_SECRET!,
);

The verifier checks the HMAC signature and timestamp before parsing the event. API failures throw SubdomainToError with status, code, requestId, and responseBody.

Resources and documentation

The client exposes typed resources for destinations, domains, webhooks, widget sessions, usage, and health. Read the Node.js SDK guide, browse the API documentation, or report a problem in the GitHub repository.

License

MIT