The Hog TypeScript SDK

A production-quality TypeScript SDK for The Hog API. It wraps authentication, retries, polling, operation management, error handling, and response parsing behind a small resource-oriented API.

import { Hog } from "hog-sdk-js";

const hog = new Hog({
  accessKey: process.env.THEHOG_ACCESS_KEY!,
  secretKey: process.env.THEHOG_SECRET_KEY!,
});

const operation = await hog.companies.search({
  query: "YC AI Startups",
});

await operation.wait();
console.log(operation.result);

Installation

npm install hog-sdk-js

Requires Node.js 20 or newer. The SDK is ESM-only and uses native fetch.

Authentication

The Hog uses dashboard-created API credentials. Pass them once when constructing the client; the SDK sends X-Access-Key and X-Secret-Key on every request.

const hog = new Hog({
  accessKey: "ak_xxxxxxxxxxxxxxxx",
  secretKey: "sk_xxxxxxxxxxxxxxxx",
});

Do not expose these credentials in browsers, public repos, or logs.

Quick start

const companies = await hog.companies.search({
  query: "Series B SaaS companies in the US with 50-200 employees",
  limit: 10,
});

await companies.wait();

if (companies.status === "succeeded") {
  console.log(companies.result);
}

Search endpoints are asynchronous. They return an Operation immediately, and the operation can poll itself until it reaches a terminal state.

Examples by API

hog.companies.search()

const operation = await hog.companies.search({
  query: "B2B SaaS companies in Austin hiring engineers",
  limit: 25,
  includeSignals: true,
  filters: {
    industries: ["Software"],
    locations: ["Austin"],
    employeeCount: { min: 50, max: 500 },
  },
});

await operation.wait();
console.log(operation.result);

Implemented endpoint: POST /api/v1/companies/search.

hog.people.estimate()

Use this before people search when you want to understand credit exposure or set a safe maxCredits value.

const estimate = await hog.people.estimate({
  query: "VP Engineering at B2B SaaS companies",
  limit: 10,
  includeContacts: true,
  contactFields: ["email"],
});

console.log(estimate.estimatedCredits);
console.log(estimate.withinPlanLimits);
console.log(estimate.breakdown.contactEnrichment);

Implemented endpoint: POST /api/v1/people/search/estimate.

hog.people.search()

const operation = await hog.people.search({
  query: "VP Engineering at hiring B2B SaaS companies in SF",
  limit: 25,
  includeContacts: true,
  contactFields: ["email"],
  maxCredits: 2500,
});

await operation.wait();
console.log(operation.result);

Implemented endpoint: POST /api/v1/people/search.

hog.operations.get()

Use this when you already have an operation ID and just want the latest snapshot.

const snapshot = await hog.operations.get("op_01HZXYZ");

console.log(snapshot.status);
console.log(snapshot.progress);
console.log(snapshot.result);

Implemented endpoint: GET /api/operations/:id.

Polling and operations

All async search methods return an Operation instance.

const operation = await hog.people.search({ query: "CFOs at fintech startups" });

operation.id;       // "op_..."
operation.status;   // "queued"
operation.progress; // number | null
operation.result;   // result payload once complete

await operation.refresh(); // fetch the latest state once
await operation.wait();    // poll until succeeded or partial_success

You can also fetch an operation directly:

const snapshot = await hog.operations.get("op_01HZXYZ");

Operation statuses are:

• queued
• processing
• succeeded
• failed
• partial_success
• cancelled

wait() resolves for succeeded and partial_success. It throws a HogError if the operation fails, is cancelled, times out, or is aborted.

Retries

The SDK automatically retries:

• 429
• 500
• 502
• 503
• 504
• transient network failures

It honors Retry-After, uses exponential backoff, and adds jitter by default.

const hog = new Hog({
  accessKey,
  secretKey,
  retries: 5,
  retry: {
    baseDelay: 1000,
    maxDelay: 30_000,
    jitter: true,
  },
});

Async search requests include an Idempotency-Key. Pass your own key when you want repeated application-level attempts to return the same queued operation.

await hog.companies.search(
  { query: "AI infrastructure companies" },
  { idempotencyKey: "job_123" },
);

Errors

The SDK never throws plain Error instances for SDK/API failures. Catch HogError or one of its subclasses:

• HogError
• ApiError
• AuthenticationError
• ValidationError
• RateLimitError
• ServerError
• NotFoundError

import { HogError, RateLimitError } from "hog-sdk-js";

try {
  await hog.companies.search({ query: "" });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(error.status, error.headers);
  }

  if (error instanceof HogError) {
    console.log(error.message);
    console.log(error.status);
    console.log(error.requestId);
    console.log(error.endpoint);
    console.log(error.response);
  }
}

Every API error exposes:

• status
• message
• requestId
• endpoint
• headers
• response

Configuration

const hog = new Hog({
  accessKey,
  secretKey,
  baseURL: "https://developer.thehog.ai",
  timeout: 30_000,
  retries: 5,
  pollingInterval: 3_000,
  debug: true,
  fetch: customFetch,
});

| Option | Default | Description | | --- | --- | --- | | accessKey | required | Public API key from The Hog dashboard. | | secretKey | required | Secret API key from The Hog dashboard. | | baseURL | https://developer.thehog.ai | Override for testing or private deployments. | | timeout | 30000 | Per-request timeout in milliseconds. | | retries | 2 | Retry attempts after the initial request. | | pollingInterval | 5000 | Default interval used by operation.wait(). | | debug | false | Logs request/response metadata. | | fetch | globalThis.fetch | Custom fetch implementation. |

Middleware

Middleware is supported from day one. It wraps the shared transport layer, so every endpoint goes through the same instrumentation path.

import { logger } from "hog-sdk-js";

hog.use(logger());

hog.use(async (request, next) => {
  const startedAt = Date.now();
  const response = await next(request);
  console.log(request.method, request.path, response.response.status, Date.now() - startedAt);
  return response;
});

Abort and timeout

const controller = new AbortController();

const operation = await hog.people.search(
  { query: "VP Sales at healthcare SaaS companies" },
  { signal: controller.signal, timeout: 10_000 },
);

await operation.wait({ signal: controller.signal, timeout: 120_000 });

Implemented APIs

This package intentionally implements only:

• hog.companies.search() → POST /api/v1/companies/search
• hog.people.estimate() → POST /api/v1/people/search/estimate
• hog.people.search() → POST /api/v1/people/search
• hog.operations.get() and operation.wait() → GET /api/operations/:id