> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goliathdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> Call the Goliath developer API with typed methods, built-in retries, and safe idempotent sends using @goliath-data/sdk

## About

`@goliath-data/sdk` is the official TypeScript client for the developer API. Instead
of hand-building HTTP calls against the [operation catalog](/developer-api/overview),
you get one typed method per operation, namespaced by domain — plus transport,
authentication, retries, typed errors, and idempotency handled for you.

<Note>
  **Live in production**

  The developer API is live — point the SDK at
  `https://server.goliathdata.com` with a key from **Settings → API Keys**.
  The examples below reflect the shipping surface.
</Note>

## Install

```bash theme={null}
npm install @goliath-data/sdk
```

## Quickstart

```ts theme={null}
import { GoliathClient } from '@goliath-data/sdk'

// gsk_... from Settings → API keys. Narrowed to `string` first: apiKey is
// required, and process.env values are `string | undefined` in strict TS.
const apiKey = process.env.GOLIATH_API_KEY
if (!apiKey) throw new Error('GOLIATH_API_KEY is not set')

// baseUrl: the API host — https://server.goliathdata.com for production.
const baseUrl = process.env.GOLIATH_BASE_URL
if (!baseUrl) throw new Error('GOLIATH_BASE_URL is not set')

const goliath = new GoliathClient({ apiKey, baseUrl })

const { dealQuery } = await goliath.deals.findDeals({ limit: 25 })

await goliath.contacts.createContact(
  { input: { firstName: 'Jane', lastName: 'Doe', phoneNumbers: ['+13235550100'] } },
  { idempotencyKey: crypto.randomUUID() }
)
```

Your key is a **server-to-server** credential — never ship it in a browser or
mobile app. Every call runs as the key's owning user, so your real organization
permissions apply.

## What the SDK does for you

* **Typed inputs and outputs** for every operation in the catalog, generated
  from the same source of truth the API executes — the SDK can never disagree
  with the server about an operation's variables or response shape.
* **Retries done right**: rate-limit rejections (both `429`s) are retried for
  any operation with `Retry-After` honored exactly; network failures, timeouts,
  and `5xx`s are retried only when a re-send cannot double-fire a side effect.
  See [Errors, retries & idempotency](/developer-api/sdk-errors).
* **Compile-time idempotency**: every mutation accepts `options.idempotencyKey`
  — on a read it's a TypeScript error, matching the `400` the gateway would
  return.
* **Org safety in the types**: variables the gateway derives from your key
  (like an analytics `orgId`) don't appear in the method's input type at all.
* **Docs inside the package**: a generated markdown reference ships in
  `node_modules/@goliath-data/sdk/docs/` so coding agents can look up any
  operation offline. See [Discovering operations](/developer-api/sdk-discovery).

## Go deeper

<CardGroup cols={3}>
  <Card title="Configuration" icon="sliders" href="/developer-api/sdk-configuration">
    Constructor options, timeouts, custom fetch, and testing.
  </Card>

  <Card title="Errors, retries & idempotency" icon="shield" href="/developer-api/sdk-errors">
    Every error class, the retry policy, and safe sends.
  </Card>

  <Card title="Discovering operations" icon="magnifying-glass" href="/developer-api/sdk-discovery">
    The in-package docs tree, live discovery endpoints, and the untyped escape hatch.
  </Card>
</CardGroup>