Copy page

SDKs

Deno SDK

@tomba/sdk is the official Deno client for the Tomba API, published on JSR. Each API area is a service class, and each method returns a promise for one request. This page describes version 1.0.4, the current release on JSR.

Requirements

Deno 2. deno.json declares no minimum version; the SDK is linted and tested on Deno 2.x. Run your program with --allow-net, and with --allow-env if it reads your keys from the environment.

Install

Code
deno add jsr:@tomba/sdk

This adds @tomba/sdk to the imports in your deno.json.

Authenticate

Create an API key and copy your secret on the API keys page, then export both:

Code
export TOMBA_API_KEY="ta_xxxx"
export TOMBA_SECRET_KEY="ts_xxxx"

The SDK doesn't read environment variables. Pass the values to setKey() and setSecret(), and the client sends them as the X-Tomba-Key and X-Tomba-Secret headers. Key expiry and rotation are covered in Authentication.

First request

Find the email address of a person at a company:

Code
import { Client, Finder } from "@tomba/sdk";

const client = new Client()
    .setKey(Deno.env.get("TOMBA_API_KEY")!)
    .setSecret(Deno.env.get("TOMBA_SECRET_KEY")!);

const result = await new Finder(client).emailFinder(
    "stripe.com",
    "Jane",
    "Doe",
);
const body = result.data as { data: { email: string | null } };
console.log(body.data.email);

Every method resolves to { data, rateLimit }, where data is the decoded JSON body, typed unknown. The API wraps its payload in its own data object (Response format), so the address is at data.data.email.

Errors

The SDK throws TombaException when the API responds with status 400 or higher, when the request fails, and before sending a request when a required argument is missing. TombaException doesn't extend Error, and for API errors its message is undefined and its code is 0: read the details from response, the decoded error body.

Code
import { Client, Finder, TombaException } from "@tomba/sdk";

type ErrorBody = { errors: { type: string; message: string; code: number } };

const client = new Client()
    .setKey(Deno.env.get("TOMBA_API_KEY")!)
    .setSecret(Deno.env.get("TOMBA_SECRET_KEY")!);

try {
    const result = await new Finder(client).emailFinder(
        "stripe.com",
        "Jane",
        "Doe",
    );
    console.log(result.data);
} catch (error) {
    if (!(error instanceof TombaException)) throw error;
    const { errors } = error.response as ErrorBody;
    console.log(errors.code, errors.type, errors.message);
}

errors.code is the HTTP status. Each errors.type is described in Errors. For a failed request or a missing argument, response is empty and message holds the cause.

Rate limits and retries

The SDK doesn't retry. result.rateLimit holds the response's rate limit headers as string | null fields: xSecondRateLimit, xMinuteRateLimit, xDailyRateLimit, xMinuteRequestLeft, xDailyRequestLeft, xMinuteResetSeconds, xDailyResetSeconds, retryAfter, rateLimitPolicy, and rateLimit.

A 429 throws TombaException without the response headers. Wait before retrying as described in Handle 429 responses.

Requests time out after 120 seconds; the timeout isn't configurable.

Method reference

Create each service with the client, for example new Finder(client).

Source

github.com/tomba-io/deno (Apache-2.0), published as @tomba/sdk on JSR. Release notes are in CHANGELOG.md.