domain-suggester 1.0.0

package/README.md

@@ -0,0 +1,287 @@
+# 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
+
+```bash
+npm install domain-suggester
+```
+
+## Requirements
+
+- Node.js 18 or newer
+- A valid API key
+
+## Authentication
+
+Set your API key as an environment variable:
+
+```bash
+export DOMAIN_SUGGESTER_API_KEY="dsg_live_your_api_key_here"
+```
+
+## Quick start
+
+```js
+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
+
+```js
+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
+
+```js
+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
+
+```js
+{
+  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
+
+```js
+const status = await client.getJob(jobId);
+console.log(status);
+```
+
+---
+
+### `client.getResult(jobId)`
+
+Returns the final job result once completed.
+
+#### Example
+
+```js
+const result = await client.getResult(jobId);
+console.log(result);
+```
+
+---
+
+### `client.listJobs()`
+
+Returns the current customer's recent jobs.
+
+#### Example
+
+```js
+const jobs = await client.listJobs();
+console.log(jobs);
+```
+
+---
+
+### `client.me()`
+
+Returns current API key profile and usage information.
+
+#### Example
+
+```js
+const me = await client.me();
+console.log(me);
+```
+
+---
+
+### `client.waitForResult(jobId, options)`
+
+Polls until the job completes or fails.
+
+#### Example
+
+```js
+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
+
+```json
+{
+  "ok": true,
+  "jobId": "123",
+  "status": "queued",
+  "pollUrl": "/v1/jobs/123",
+  "resultUrl": "/v1/jobs/123/result"
+}
+```
+
+### Job status
+
+```json
+{
+  "ok": true,
+  "jobId": "123",
+  "name": "suggest",
+  "state": "active",
+  "progress": 15,
+  "submittedAt": "2026-03-26T12:00:00.000Z",
+  "finishedOn": null,
+  "failedReason": null
+}
+```
+
+### Job result
+
+```json
+{
+  "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.
+
+```js
+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.

package/bin/cli.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// bin/cli.js
+const fs = require("fs");
+const { Command } = require("commander");
+
+const program = new Command();
+
+program
+  .name("domain-suggester")
+  .description("CLI for the hosted domain suggester API")
+  .version("1.0.0");
+
+program
+  .command("suggest")
+  .argument("<file>", "path to txt file with domains")
+  .option("--top <number>", "top N results", "25")
+  .option("--api-url <url>", "API base URL", "https://suggest.domainhub.sbs")
+  .action(async (file, options) => {
+    const apiKey = process.env.DOMAIN_SUGGESTER_API_KEY;
+
+    if (!apiKey) {
+      console.error("Missing DOMAIN_SUGGESTER_API_KEY");
+      process.exit(1);
+    }
+
+    const raw = fs.readFileSync(file, "utf8");
+    const domains = raw
+      .split(/\r?\n/)
+      .map(x => x.trim())
+      .filter(Boolean);
+
+    const res = await fetch(`${options.apiUrl}/v1/jobs`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "authorization": `Bearer ${apiKey}`
+      },
+      body: JSON.stringify({
+        domains,
+        config: {
+          prefixes: ["get", "my", "try"],
+          tlds: { com: 0, net: 1, io: 2 }
+        },
+        options: {
+          topN: Number(options.top)
+        }
+      })
+    });
+
+    const text = await res.text();
+    console.log(text);
+
+    if (!res.ok) process.exit(1);
+  });
+
+program.parse();

package/index.js

@@ -0,0 +1,2 @@
+// index.js
+module.exports = require("./lib/client");

package/lib/client.js

@@ -0,0 +1,120 @@
+// lib/client.js
+const {
+  AuthenticationError,
+  RateLimitError,
+  ValidationError,
+  NotFoundError,
+  ApiError
+} = require("./errors");
+
+class DomainSuggesterClient {
+  constructor({ apiKey, baseUrl = "https://suggest.domainhub.sbs" }) {
+    if (!apiKey) {
+      throw new Error("Missing apiKey");
+    }
+
+    if (typeof baseUrl !== "string" || !baseUrl) {
+      throw new Error("Missing or invalid baseUrl");
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+  }
+
+  async request(path, options = {}) {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      ...options,
+      headers: {
+        authorization: `Bearer ${this.apiKey}`,
+        "content-type": "application/json",
+        ...(options.headers || {})
+      }
+    });
+
+    const text = await res.text();
+    let data;
+
+    try {
+      data = text ? JSON.parse(text) : null;
+    } catch {
+      data = { raw: text };
+    }
+
+    if (!res.ok) {
+      const message = data?.error || `Request failed with ${res.status}`;
+      const options = { status: res.status, data };
+
+      if (res.status === 400) throw new ValidationError(message, options);
+      if (res.status === 401) throw new AuthenticationError(message, options);
+      if (res.status === 404) throw new NotFoundError(message, options);
+      if (res.status === 429) throw new RateLimitError(message, options);
+
+      throw new ApiError(message, options);
+    }
+
+    return data;
+  }
+
+  async createJob(payload) {
+    return this.request("/v1/jobs", {
+      method: "POST",
+      body: JSON.stringify(payload)
+    });
+  }
+
+  async getJob(jobId) {
+    return this.request(`/v1/jobs/${jobId}`, {
+      method: "GET"
+    });
+  }
+
+  async getResult(jobId) {
+    return this.request(`/v1/jobs/${jobId}/result`, {
+      method: "GET"
+    });
+  }
+
+  async listJobs() {
+    return this.request("/v1/jobs", {
+      method: "GET"
+    });
+  }
+
+  async me() {
+    return this.request("/v1/me", {
+      method: "GET"
+    });
+  }
+
+  async waitForResult(jobId, { intervalMs = 3000, timeoutMs = 10 * 60 * 1000 } = {}) {
+    const started = Date.now();
+
+    while (true) {
+      const job = await this.getJob(jobId);
+
+      if (job.state === "completed") {
+        return this.getResult(jobId);
+      }
+
+      if (job.state === "failed") {
+        const err = new Error(job.failedReason || "Job failed");
+        err.job = job;
+        throw err;
+      }
+
+      if (Date.now() - started > timeoutMs) {
+        throw new Error("Timed out waiting for job result");
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+  }
+}
+
+function createClient(options) {
+  return new DomainSuggesterClient(options);
+}
+
+module.exports = {
+  createClient,
+  DomainSuggesterClient
+};

package/lib/errors.js

@@ -0,0 +1,54 @@
+// lib/errors.js
+class DomainSuggesterError extends Error {
+  constructor(message, options = {}) {
+    super(message);
+    this.name = "DomainSuggesterError";
+    this.status = options.status || null;
+    this.code = options.code || null;
+    this.data = options.data || null;
+  }
+}
+
+class AuthenticationError extends DomainSuggesterError {
+  constructor(message = "Unauthorized", options = {}) {
+    super(message, { ...options, status: options.status || 401 });
+    this.name = "AuthenticationError";
+  }
+}
+
+class RateLimitError extends DomainSuggesterError {
+  constructor(message = "Rate limit exceeded", options = {}) {
+    super(message, { ...options, status: options.status || 429 });
+    this.name = "RateLimitError";
+  }
+}
+
+class ValidationError extends DomainSuggesterError {
+  constructor(message = "Validation failed", options = {}) {
+    super(message, { ...options, status: options.status || 400 });
+    this.name = "ValidationError";
+  }
+}
+
+class NotFoundError extends DomainSuggesterError {
+  constructor(message = "Not found", options = {}) {
+    super(message, { ...options, status: options.status || 404 });
+    this.name = "NotFoundError";
+  }
+}
+
+class ApiError extends DomainSuggesterError {
+  constructor(message = "API request failed", options = {}) {
+    super(message, options);
+    this.name = "ApiError";
+  }
+}
+
+module.exports = {
+  DomainSuggesterError,
+  AuthenticationError,
+  RateLimitError,
+  ValidationError,
+  NotFoundError,
+  ApiError
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "domain-suggester",
+  "version": "1.0.0",
+  "description": "Node.js SDK for the DomainHub domain suggester API",
+  "main": "index.js",
+  "bin": {
+    "domain-suggester": "./bin/cli.js"
+  },
+  "type": "commonjs",
+  "files": [
+    "index.js",
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "keywords": [
+    "domain",
+    "sdk",
+    "api",
+    "domain-suggester",
+    "domainhub"
+  ],
+  "author": "DomainHub",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}