# SDK - Veezee docs

Typed TypeScript client for the Veezee REST API: LinkedIn, Reddit, and X (formerly Twitter) data behind one client. Zero runtime dependencies, built on Node 20's global `fetch`. Package home: [@veezee/sdk on npm](https://www.npmjs.com/package/@veezee/sdk); source: [veezeehq/veezee-sdk on GitHub](https://github.com/veezeehq/veezee-sdk).

## Install

```
npm install @veezee/sdk
```

Node 20+ required. The package also ships the [`veezee` CLI](/docs/cli) (short alias: `vz`) and the [agent skill packs](/docs/skills).

## Quickstart

```ts
import { VeezeeClient } from "@veezee/sdk";

const client = new VeezeeClient(); // finds your key: constructor option, VEEZEE_API_KEY, or ~/.veezee/config
const profile = await client.linkedin.getProfile({ identifier: "williamhgates" });
const chatter = await client.reddit.search({ query: "notion alternative", type: "comments" });
const tweets = await client.x.getTweets({ identifier: "nasa" });
```

No key yet? `await client.mint()` creates a free one and saves it to `~/.veezee/config` (same store `npx @veezee/sdk init` writes). The free key includes 200 credits per IP per day. Need more? `client.checkout({ pack: "flex" })` (or [/upgrade](/upgrade) in a browser) adds credits to the same key, so nothing needs reconfiguring. Already have a key? `new VeezeeClient({ apiKey: process.env.VEEZEE_API_KEY })`.

## The methods

One method per tool, same names and envelopes as the REST contract (https://veezee.io/openapi.json). Every data response carries `usage` with the receipt id, credits charged, and balance.

LinkedIn, under `client.linkedin` ([platform docs](/docs/linkedin)):

- `getProfile`: a person's profile with named sections (about, experience, education, skills)
- `searchPeople`: people search with typed filters (title, current or past company, school, keywords)
- `getCompany`: a company page by URL, slug, or website domain
- `getPosts`: recent posts by a person or company

Reddit, under `client.reddit` ([platform docs](/docs/reddit)):

- `search`: search posts, comments, subreddits, or users
- `getSubreddit`: subreddit details, optionally including settings
- `getSubredditPosts`: one page of a subreddit's posts, by sort
- `getUser`: a Reddit user, with optional comments, posts, and subreddits sections
- `getPost`: posts by id, optionally with the full discussion thread
- `resolveUrl`: identify a Reddit URL

X, under `client.x` ([platform docs](/docs/x)):

- `search`: search recent or popular tweets, or people
- `getProfile`: a profile with follower and tweet counts
- `getTweets`: an account's tweets by mode (posts, posts and replies, highlights)
- `getTweet`: one tweet with full engagement metrics
- `resolveUrl`: identify an X URL

Top-level on the client:

- `resolveUrl`: identify a LinkedIn URL (person, company, or post)
- `getUsage`: credits, plan, and recent charges; free, requires a key
- `checkout`: buy a key or add credits

## Retries and idempotency

The client retries RATE_LIMITED, CONCURRENCY_LIMIT, UPSTREAM_UNAVAILABLE, INTERNAL, and network failures up to 3 attempts with backoff, honoring retry_after_seconds. Each metered call gets one Idempotency-Key reused across its own retries, so retries never double-charge. Terminal errors throw `VeezeeError` with the same code/message/param shape the API returns, including `offer` and `credits_required` on payment-fixable errors.