Node.js SDK

@subdomainto/node v0.1 supports Node.js 20 and later. It is server-only and covers all 12 core API operations with TypeScript types.

Installation

npm install @subdomainto/node

Initialize the client

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

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

baseUrl and a custom fetch implementation are optional. Never expose the API key in browser code.

Create a domain

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

Creation methods require a stable 1–128 character idempotency key. The SDK performs no implicit retries.

Resources

The client exposes destinations.list/create, domains.list/create/get/delete, webhooks.create, widget.createSession, usage.get, and the public health() method.

Handle errors

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

try {
  await client.domains.get(domainId);
} catch (error) {
  if (error instanceof SubdomainToError) {
    console.error(error.status, error.code, error.requestId);
  }
}

responseBody contains the original response. Client validation failures are TypeError instances.

Verify a webhook

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

const event = verifyWebhook(rawBody, signatureHeader, webhookSecret, {
  tolerance: 300,
});

Pass the untouched raw body. Verification checks the HMAC-SHA256 signature in constant time and rejects stale timestamps and malformed payloads.