TypeScript SDK

About

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

Install

npm install @goliath-data/sdk

Requires Node.js 20.3 or later, including WHATWG fetch and AbortSignal.any. The package is in public beta (0.1.0-beta.x); pin a version when you need stability across upgrades.

Quickstart

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: { sellerFirstName: 'Jane', sellerLastName: 'Doe' } },
  { 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 the operations in your installed release. Upgrade to pick up newer types, or use execute() for an operation added after that release.
• Retries done right: rate-limit rejections (both 429s) are retried for any operation with Retry-After honored exactly; network failures, timeouts, and 5xxs are retried only when a re-send cannot double-fire a side effect. See Errors, retries & idempotency.
• 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.

Ask Goliath in one call

askGoliath(goliath, { message }) sends a message to the key owner’s Ask Goliath and polls until the reply is done; pass conversationId to carry on a chat. It ships in the next SDK beta — see the Ask Goliath API.

Go deeper