# Node SDK

The official Node.js client for the Synthient API: IP and domain lookups, account details, real-time feed streams, and Parquet exports.

> **Note**: The package is on [npm](https://www.npmjs.com/package/@synthient/synthient). There is no hosted API reference, but every class and method carries TSDoc that your editor shows. These pages cover the same surface with examples. The source and runnable programs are at [github.com/synthient/synthient-node](https://github.com/synthient/synthient-node), with the programs in `examples/`.

## Getting started

### 1. Install

```bash
npm install @synthient/synthient
```

Requires Node.js 22.12 or later. The package is ESM only, and CommonJS code can `require()` it. It ships its own TypeScript declarations, tested with TypeScript 5.8 and later. The [gRPC schema](https://docs.synthient.com/sdks/node/grpc-schema) fetcher is a separate entry point, `@synthient/synthient/grpcschema`, that needs optional peer dependencies.

### 2. Make your first lookup

This program creates a client and looks up one address. Each lookup costs one credit. The examples on these pages use top-level `await`, which works in ES modules.

```ts
import { Synthient } from "@synthient/synthient";

const client = new Synthient();

const info = await client.lookupIP("8.8.8.8");
console.log(info.network?.isp, info.network?.type);
console.log(info.intelligence?.risk_score, info.intelligence?.categories);
```

`new Synthient()` reads the API key from the `SYNTHIENT_API_KEY` environment variable. `IPInfo.network`, `IPInfo.location`, and `IPInfo.intelligence` are absent when the API has no data for that section, so check them before reading their fields.

### 3. Check your credits

`account` returns the account that owns the API key, including its scopes and remaining lookup credits. It costs no credits.

```ts
const account = await client.account();
const { credits, resets_in } = account.lookup_quota;
console.log(account.email, account.organization.name, account.scopes);
console.log(credits, "credits, resetting in", resets_in, "seconds");
```

### 4. Handle errors

Failed requests reject with a `SynthientError` or one of its subclasses. Check them with `instanceof`:

```ts
import { APIError } from "@synthient/synthient";

try {
  await client.lookupIP("8.8.8.8");
} catch (error) {
  if (!(error instanceof APIError)) {
    throw error;
  }
  switch (error.status) {
    case 402:
      console.log("out of lookup credits");
      break;
    case 429:
      if (error.retryAfter === undefined) {
        console.log("monthly request budget spent");
      } else {
        console.log(`rate limited, retry after ${error.retryAfter} ms`);
      }
      break;
    default:
      console.log("request", error.requestID, "failed:", error.detail || error.title);
  }
}
```

### 5. Keep going

- [Client](https://docs.synthient.com/sdks/node/client): create and configure the client, and read the metadata of every API response.
- [Lookups](https://docs.synthient.com/sdks/node/lookups): look up IP addresses and domains, and check your account and the API's health.
- [Feeds](https://docs.synthient.com/sdks/node/feeds): stream each feed's real-time events and download its hourly and daily Parquet exports.
- [Errors and retries](https://docs.synthient.com/sdks/node/errors): how failed requests are reported, and which requests are retried.
- [Types](https://docs.synthient.com/sdks/node/types): the fields of every response and event type, and the enumerations they use.
- [gRPC schema](https://docs.synthient.com/sdks/node/grpc-schema): fetch the protobuf schema of the Synthient gRPC API.