tryhobbes-sdk

Official TypeScript SDK for the Hobbes API.

This package currently implements the SDK infrastructure and three representative Hobbes API resources:

• sessions
• people
• analytics (backed by the Hobbes Metrics API)

It is designed to be small, typed, and easy to extend as more Hobbes APIs are added.

Installation

npm install tryhobbes-sdk

Requirements

• Node.js >=20

Quick Start

import { Hobbes } from "tryhobbes-sdk";

const hobbes = new Hobbes({
  apiKey: process.env.HOBBES_API_KEY!,
});

For runnable local scripts, see the examples/ folder.

Configuration

The client accepts:

• apiKey - required Hobbes API key
• baseURL - optional API base URL
• timeout - optional request timeout in milliseconds
• headers - optional custom headers
• fetch - optional custom fetch implementation
• maxRetries - optional retry count for retryable failures
• middlewares - optional SDK middleware array

Example:

import { Hobbes } from "tryhobbes-sdk";

const hobbes = new Hobbes({
  apiKey: process.env.HOBBES_API_KEY!,
  timeout: 30_000,
  maxRetries: 2,
});

Supported APIs

The SDK currently covers these Hobbes endpoints:

• GET /api/v1/sessions
• GET /api/v1/sessions/{session_id}
• GET /api/v1/people
• GET /api/v1/people/{email}
• GET /api/v1/metrics

Sessions API

List sessions

const result = await hobbes.sessions.list({
  qualification_status: ["qualified"],
  buying_intent: ["high", "medium"],
  limit: 25,
  offset: 0,
});

console.log(result.sessions);
console.log(result.pagination);

Retrieve a session

const session = await hobbes.sessions.retrieve(
  "018f3f6a-0d7b-7f56-bb2a-54c91e57a202",
);

console.log(session.id);
console.log(session.summaryMarkdown);
console.log(session.timelineEvents);

Search sessions

This is a convenience wrapper over the documented search query parameter on the list endpoint.

const result = await hobbes.sessions.search("[email protected]", {
  limit: 10,
});

console.log(result.sessions);

People API

List people

const result = await hobbes.people.list({
  qualification_status: ["qualified"],
  buying_intent: ["high"],
  limit: 25,
});

console.log(result.people);
console.log(result.pagination);

Retrieve a person

The SDK lowercases and URL-encodes the email automatically.

const person = await hobbes.people.retrieve("[email protected]");

console.log(person.id);
console.log(person.email);
console.log(person.summaryMarkdown);

Search people

This is a convenience wrapper over the documented search query parameter on the list endpoint.

const result = await hobbes.people.search("acme.example", {
  limit: 10,
});

console.log(result.people);

Analytics API

Retrieve funnel metrics

The analytics resource is backed by Hobbes GET /api/v1/metrics.

const metrics = await hobbes.analytics.retrieve({
  days: 30,
});

console.log(metrics.totalSessions);
console.log(metrics.qualifiedCount);
console.log(metrics.topSources);

Error Handling

The SDK throws typed errors for common API and transport failures.

import {
  AuthenticationError,
  NotFoundError,
  RateLimitError,
  ValidationError,
} from "tryhobbes-sdk";

try {
  await hobbes.people.retrieve("[email protected]");
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error("Invalid API key or missing scope.");
  } else if (error instanceof NotFoundError) {
    console.error("Resource not found.");
  } else if (error instanceof ValidationError) {
    console.error("Request validation failed.");
  } else if (error instanceof RateLimitError) {
    console.error("Rate limited. Retry later.");
  } else {
    console.error("Unexpected SDK error:", error);
  }
}

Notes

• All requests go through a shared HttpClient
• resources never call fetch() directly
• retries are applied for retryable failures such as 429 and selected 5xx
• this package currently implements only a subset of the Hobbes API

Development

npm run typecheck
npm test -- --run
npm run build