domain-suggester

Node.js SDK for the DomainHub Domain Suggester API.

This package is a thin client for the hosted API. It does not contain the private scoring engine or internal domain suggestion logic.

Installation

npm install domain-suggester

Requirements

• Node.js 18 or newer
• A valid API key

Authentication

Set your API key as an environment variable:

export DOMAIN_SUGGESTER_API_KEY="dsg_live_your_api_key_here"

Quick start

const { createClient } = require("@domainhub/domain-suggester");

async function main() {
  const client = createClient({
    apiKey: process.env.DOMAIN_SUGGESTER_API_KEY,
    baseUrl: "https://suggest.domainhub.sbs"
  });

  const job = await client.createJob({
    domains: [
      "example.com",
      "domain.com"
    ],
    config: {
      prefixes: ["get", "my", "try"],
      tlds: {
        com: 0,
        net: 1,
        io: 2
      }
    },
    options: {
      topN: 25
    }
  });

  console.log("Submitted job:", job);

  const result = await client.waitForResult(job.jobId, {
    intervalMs: 3000,
    timeoutMs: 10 * 60 * 1000
  });

  console.log(JSON.stringify(result, null, 2));
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

Creating a client

const { createClient } = require("@domainhub/domain-suggester");

const client = createClient({
  apiKey: process.env.DOMAIN_SUGGESTER_API_KEY,
  baseUrl: "https://suggest.domainhub.sbs"
});

Options

• apiKey — required, your customer API key
• baseUrl — optional, defaults to your API base URL if you set one in the SDK

API

createClient(options)

Creates a new SDK client.

client.createJob(payload)

Creates a new suggestion job.

Example

const job = await client.createJob({
  domains: ["example.com", "domain.com"],
  config: {
    prefixes: ["get", "my", "try"],
    tlds: { com: 0, net: 1, io: 2 }
  },
  options: {
    topN: 25,
    debug: false,
    ideal: "example"
  }
});

Payload shape

{
  domains: string[],
  config: {
    prefixes: string[],
    tlds: Record<string, number>
  },
  options: {
    topN?: number,
    debug?: boolean,
    ideal?: string,
    target?: string
  }
}

client.getJob(jobId)

Returns job status.

Example

const status = await client.getJob(jobId);
console.log(status);

client.getResult(jobId)

Returns the final job result once completed.

Example

const result = await client.getResult(jobId);
console.log(result);

client.listJobs()

Returns the current customer's recent jobs.

Example

const jobs = await client.listJobs();
console.log(jobs);

client.me()

Returns current API key profile and usage information.

Example

const me = await client.me();
console.log(me);

client.waitForResult(jobId, options)

Polls until the job completes or fails.

Example

const result = await client.waitForResult(jobId, {
  intervalMs: 3000,
  timeoutMs: 10 * 60 * 1000
});

Options

• intervalMs — polling interval in milliseconds
• timeoutMs — max total wait time in milliseconds

Example response

Job created

{
  "ok": true,
  "jobId": "123",
  "status": "queued",
  "pollUrl": "/v1/jobs/123",
  "resultUrl": "/v1/jobs/123/result"
}

Job status

{
  "ok": true,
  "jobId": "123",
  "name": "suggest",
  "state": "active",
  "progress": 15,
  "submittedAt": "2026-03-26T12:00:00.000Z",
  "finishedOn": null,
  "failedReason": null
}

Job result

{
  "ok": true,
  "jobId": "123",
  "state": "completed",
  "result": {
    "count": 25,
    "durationMs": 8123,
    "sortedDomains": [
      "getexample.com",
      "myexample.com"
    ],
    "detailedResults": [
      {
        "domain": "getexample.com",
        "score": 12.34
      }
    ]
  }
}

Error handling

The SDK throws when the API returns a non-2xx response.

try {
  await client.createJob(payload);
} catch (err) {
  console.error(err.message);
  console.error(err.status);
  console.error(err.data);
}

Security

• Keep your API key secret
• Never expose your API key in frontend/browser code
• Use this SDK only in trusted backend or local Node.js environments

Notes

• This SDK is only a transport client
• The private suggestion engine runs on the hosted service
• Request options such as prefixes, tlds, and topN are passed through to the API

Support

For support, contact DomainHub.