npm package: @sherlockeye/sdk
Description: The official JavaScript/TypeScript SDK for Sherlockeye
Author: Sherlockeye
Latest version: 0.1.0

## @sherlockeye/sdk: The official JavaScript/TypeScript SDK for Sherlockeye

Sherlockeye is a reverse search engine for investigations, fraud prevention, threat intelligence, and broader digital risk analysis.

This SDK lets you integrate Sherlockeye’s multi-source reverse search capabilities into your Node.js applications — run OSINT searches (email, phone, username, domain, IP and more).

### Get your API key

Create and manage your API keys at:

- `https://app.sherlockeye.io/api`

Full API documentation:

- `https://docs.sherlockeye.io`

### Installation

```bash
npm install @sherlockeye/sdk
```

### Quick start

```ts
import { SherlockeyeClient } from "@sherlockeye/sdk";

const client = new SherlockeyeClient({ apiKey: "YOUR_API_KEY" });

// Check your token balance
const balance = await client.getBalance();
console.log(balance.data.tokens);

// Run a synchronous search (waits for results up to timeoutSeconds)
const syncResult = await client.createSyncSearch({
  type: "email",
  value: "someone@example.com",
  timeoutSeconds: 60,
});

console.log(syncResult.data.status, syncResult.data.results);
```

```ts
import { SherlockeyeClient } from "@sherlockeye/sdk";

const client = new SherlockeyeClient({ apiKey: "YOUR_API_KEY" });

// Run an asynchronous search (fire-and-forget style, then poll)
const search = await client.createSearch({
  type: "email",
  value: "someone@example.com",
});

const searchId = search.data.searchId;
let status = search.data.status; // usually "processing"
console.log("Created search:", searchId, status);

// Poll until the search is complete (or a max number of attempts)
const maxAttempts = 10;
let attempt = 0;

while (status !== "complete" && attempt < maxAttempts) {
  attempt += 1;
  const searchDetails = await client.getSearch(searchId);
  status = searchDetails.data.status ?? status;
  console.log(`[attempt ${attempt}] status:`, status);
  if (status !== "complete") {
    await new Promise((resolve) => setTimeout(resolve, 5000));
  }
}

const finalDetails = await client.getSearch(searchId);
const results = finalDetails.data.results ?? [];
console.log("Final status:", status);
console.log("Results:", results);
```

### Basic usage

```ts
import { SherlockeyeClient } from "@sherlockeye/sdk";

const client = new SherlockeyeClient({ apiKey: "YOUR_API_KEY" });

// Token balance
const balance = await client.getBalance();
console.log(balance.data.tokens);

// Synchronous search
const syncResult = await client.createSyncSearch({
  type: "ip",
  value: "1.1.1.1",
  timeoutSeconds: 60, // Maximum time (in seconds) to wait for results
});

const status = syncResult.data.status;
const results = syncResult.data.results;
console.log(status, results);
```

### Webhooks

```ts
import { SherlockeyeClient } from "@sherlockeye/sdk";

const client = new SherlockeyeClient({ apiKey: "YOUR_API_KEY" });

// Create webhook
const webhook = await client.createWebhook({
  url: "https://YOUR_DOMAIN/webhooks/sherlockeye",
  events: ["search.completed"],
  enabled: true,
});

// List webhooks
const allWebhooks = await client.listWebhooks();

// Delivery history
const deliveries = await client.getWebhookDeliveries(webhook.data.id ?? "");
```

### Error handling

All API failures throw subclasses of `SherlockeyeError`:

```ts
import {
  SherlockeyeClient,
  SherlockeyeError,
  SherlockeyeAuthError,
  SherlockeyeRateLimitError,
  SherlockeyeValidationError,
} from "@sherlockeye/sdk";

const client = new SherlockeyeClient({ apiKey: "YOUR_API_KEY" });

try {
  const balance = await client.getBalance();
} catch (err) {
  if (err instanceof SherlockeyeAuthError) {
    console.error("Invalid API key or not allowed.");
  } else if (err instanceof SherlockeyeRateLimitError) {
    console.error("Rate limit or credits exceeded.");
  } else if (err instanceof SherlockeyeValidationError) {
    console.error("Validation error:", err);
  } else if (err instanceof SherlockeyeError) {
    console.error("Generic Sherlockeye API error:", err);
  } else {
    console.error("Unexpected error:", err);
  }
}
```