Skip to main content

Client Libraries

BotShield provides official client libraries as an alternative to calling the REST API directly. Each library wraps the same SDK A operations and provides typed interfaces, automatic retries, and error handling out of the box.
Client libraries require an API key. Request developer access to get started.

Available SDKs

TypeScript / JavaScript

Server-side TypeScript and JavaScript SDK. Works with Node.js, Deno, Bun, Cloudflare Workers, and Vercel Edge Runtime.

More Languages Coming

Additional SDKs (Python, Go, etc.) are planned. Contact us if you have a specific language requirement.

TypeScript / JavaScript

The TypeScript SDK is published on npm and generated with Stainless for full type safety and consistency with the REST API.

Installation

npm install botshield-sdk

Quick Start

import BotShield from 'botshield-sdk';

const client = new BotShield({
  apiKey: process.env['BOTSHIELD_API_KEY'],
  environment: 'production', // or 'development' for test keys
});

// Create a session
const session = await client.sdk.createSession({
  partner_user_id: 'your_internal_user_id',
});

// Create a verification link
const verification = await client.sdk.createVerificationLink({
  scope: 'checkout.complete',
  sdk_type: 'signal',
  webhook_url: 'https://your-platform.com/botshield-webhook',
});

console.log(verification.data.deep_link);
console.log(verification.data.web_url);
console.log(verification.data.qr_code_url);

Error Handling

try {
  const response = await client.sdk.createVerificationLink({ ... });
} catch (err) {
  if (err instanceof BotShield.APIError) {
    console.log(err.status);  // 400, 401, etc.
    console.log(err.name);    // BadRequestError, AuthenticationError, etc.
    console.log(err.message);
  }
}
Status CodeError Type
400BadRequestError
401AuthenticationError
403PermissionDeniedError
404NotFoundError
422UnprocessableEntityError
429RateLimitError
>=500InternalServerError

Automatic Retries

The SDK automatically retries failed requests up to 2 times with exponential backoff. Connection errors, timeouts, 429 rate limits, and 5xx server errors are all retried by default.
const client = new BotShield({
  maxRetries: 0, // disable retries
});

// Or per-request:
await client.sdk.createVerificationLink({
  maxRetries: 5,
});

Supported Runtimes

  • Node.js 20 LTS or later
  • Deno v1.28.0+
  • Bun 1.0+
  • Cloudflare Workers
  • Vercel Edge Runtime

Resources


REST API vs. Client Library

Both approaches use the same underlying API and provide the same guarantees. Choose what fits your stack:
REST APIClient Library
IntegrationHTTP calls from any languageImport and call typed methods
Type SafetyManual (parse JSON responses)Built-in TypeScript types
RetriesImplement yourselfAutomatic with backoff
Error HandlingParse HTTP status codesTyped error classes
DependenciesNone (just HTTP)npm package
If you’re already using TypeScript/JavaScript on your server, the client library is the fastest path to integration. For other languages or minimal-dependency environments, the REST API works from anywhere.

Next Steps