SDK Reference

SDK Reference

The notabotly npm package provides a robust, fully-typed wrapper over our HTTP API. It is designed to be minimal, modern, and highly secure.

Initialization

You can initialize the client explicitly or let it automatically pick up your API key from environment variables.

import { Notabotly } from 'notabotly';

// Explicit initialization
const nb = new Notabotly({
  apiKey: 'nb_live_...',
  proxyUrl: 'http://my-proxy:8080', // Optional proxy support
  baseUrl: 'https://api.notabotly.com' // Optional, defaults to production
});

// OR: Let it read NOTABOTLY_API_KEY from process.env
const nb = new Notabotly();

Static Helpers (Modern API)

For the simplest integration, use the static methods. They use a shared global instance of the client.

import { Notabotly } from 'notabotly';

// Create and wait in one line
const { session, status } = await Notabotly.verify({
  appId: 'app_abc123',
  redirectUrl: 'https://yoursite.com'
});

nb.verify()

The high-level helper for server-side verification flows. It combines create and waitForResult into a single call.

const { session, status } = await nb.verify({
  appId: 'app_xyz',
  redirectUrl: 'https://example.com'
});

nb.session.create()

Creates a new verification session.

const session = await nb.session.create({
  appId: 'app_abc123',
  redirectUrl: 'https://example.com/callback'
});

Returns:

interface SessionResponse {
  session_id: string; // The ID of the session
  verify_url: string; // The URL to show as a QR Code
  expires_in: number; // TTL in seconds (600)
}

nb.session.waitForResult()

Listens to the SSE stream and resolves as soon as a terminal state (true, false, timeout) is reached.

const result = await nb.session.waitForResult('sess_xyz123');
// result.status: 'true' | 'false' | 'timeout'

Advanced: nb.session.stream()

Raw access to the Server-Sent Events stream for advanced handling.

const controller = await nb.session.stream('sess_xyz123', (event) => {
    console.log("Real-time event:", event);
});

// controller.abort(); // Cancel the stream manually

Errors

The SDK throws specific error classes which you can catch:

• NotabotlyAuthError - Thrown when the API key is missing or invalid.
• NotabotlyCreditError - Thrown when your starter plan runs out of monthly credits.
• NotabotlyNetworkError - Thrown on connectivity failures.
• NotabotlyAPIError - Thrown on all other HTTP errors (contains .status).