# Hooksbase SDKs

Hooksbase ships one first-party SDK today: `@hooksbase/sdk` for TypeScript and modern JavaScript runtimes. Everything else in the docs should be read as raw HTTP guidance or language-specific reference snippets, not as first-party maintained clients.

**Available through**

The TypeScript SDK is the only first-party SDK today. Other language examples are raw HTTP guidance.

| Surface | Status | Notes |
| --- | --- | --- |
| [TypeScript SDK](https://www.npmjs.com/package/@hooksbase/sdk) | Preferred | Use @hooksbase/sdk for Node.js and TypeScript integrations. |
| [Public API](/docs/api-reference.md) | Available | Use raw HTTP for public route families not yet wrapped by the SDK. |
| [CLI](/docs/cli.md) | Available | Use the CLI when the workflow is terminal-driven rather than embedded in code. |
| [Dashboard](/docs/dashboard.md) | Not applicable | Dashboard workflows are not SDK capabilities. |

## Client surfaces

- [TypeScript SDK](https://www.npmjs.com/package/@hooksbase/sdk): The first-party client for project APIs, ingest publishing, pagination helpers, and signature verification.
- [CLI](/docs/cli.md): The first-party command-line surface for profiles, projects, templates, webhooks, deliveries, replay, DLQ, usage, schedules, and ingest sends.
- [Raw HTTP](/docs/api-reference.md): Use cURL or your own client when you need routes that are not yet wrapped by the SDK or CLI.
- [Language snippets](/docs/quickstart.md): Python, Ruby, Go, and PHP examples in these docs are reference snippets, not first-party client libraries.

## TypeScript SDK

The SDK covers the core Public API routes and helper flows:

- `client.projects` — `getCurrent()`, `update()`
- `client.templates` — `list()`
- `client.webhooks` — `list()`, `get()`, `create()`, `pause()`, `resume()`, `archive()`, `restore()`, `destroy()`, `rotateIngestSecret()`, `rotateSigningSecret()`, `listSecretVersions()`
- `client.schedules` — `list()`, `create()`, `pause()`, `resume()`, `delete()`
- `client.deliveries` — `list()`, `get()`, `replay()`
- `client.replayJobs` — `get()`
- `client.dlq` — `list()`, `get()`, `redrive()`, `export()`
- `client.usage` — `get({ from, to, webhookId? })`
- `client.ingest` — `publishJson()`, `publishBytes()`, `publishJsonByWebhookName()`, `publishBytesByWebhookName()`
- `verifyHooksbaseWebhook()` for outbound signature verification
- `paginateCursor()` and `takePages()` for cursor pagination
- typed errors such as `HooksbaseApiError`, `HooksbaseAuthError`, `HooksbaseRateLimitError`, `HooksbaseNetworkError`, and `HooksbaseTimeoutError`

**Create a client**

```ts
import { createHooksbaseClient } from '@hooksbase/sdk'

const client = createHooksbaseClient({
  apiKey: process.env.HOOKSBASE_API_KEY,
})
```

`createHooksbaseClient()` accepts:

- `apiKey` — project API key (`swk_...`)
- `baseUrl` — defaults to `https://api.hooksbase.com`
- `timeoutMs` — per-request timeout, defaults to `10000`
- `retryCount` — idempotent retry count on transient failures, defaults to `2`
- `userAgent` — optional override for the outbound `User-Agent` header
- `fetch` — optional `fetch` implementation for testing or non-standard runtimes

## Coverage gaps

The SDK does not currently wrap every public machine route. Assume raw HTTP is still required for:

- destinations and routing
- payload transforms
- email allowlists
- webhook metrics and backlog
- event drain management
- operator notification APIs
- file download helpers
- form-ingest helpers
- bulk-operation lookup

When a public route is not wrapped yet, use cURL or your own HTTP client and keep the same project API key, ingest-secret, public form, or signed-file auth model described elsewhere in these docs. See [raw HTTP examples](/docs/raw-http-examples.md) for common unwrapped routes. The SDK does not wrap dashboard-only product workflows.

## Common mistakes

- Treating Python, Ruby, Go, or PHP snippets in the docs as official SDKs.
- Assuming the SDK wraps dashboard-only product flows. The dashboard is a UI and is not exposed as a public API surface.
- Using raw HTTP examples from old docs that still reference removed prefixes instead of current `swk_...` and `whsec_...` values.
- Assuming SDK coverage and public API coverage are the same. Check the [Public API reference](/docs/api-reference.md) and this page together.