@turingverify/sdk

Official TypeScript / Node SDK for the Turing Verify document verification API.

Install

npm install @turingverify/sdk

Ships as dual ESM + CJS with generated .d.ts types. Node 18+ (native fetch).

Quickstart

import { TuringVerify } from '@turingverify/sdk';
import { readFile } from 'node:fs/promises';

const client = new TuringVerify({ apiKey: process.env.TURING_VERIFY_API_KEY! });

const buf = await readFile('diploma.pdf');
const ver = await client.verifications.create({
  file: buf,
  filename: 'diploma.pdf',
  mimeType: 'application/pdf',
});

console.log(ver.verdict, ver.confidence);

Verifying webhook signatures

import express from 'express';
import { verifyWebhookSignature, SignatureVerificationError } from '@turingverify/sdk';

const app = express();

app.post(
  '/hooks/turing-verify',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    try {
      verifyWebhookSignature(
        req.body,
        req.get('X-TuringVerify-Signature') ?? '',
        process.env.WEBHOOK_SECRET!,
        { tolerance: 300 },
      );
    } catch (err) {
      if (err instanceof SignatureVerificationError) {
        return res.status(400).send('bad signature');
      }
      throw err;
    }
    // process event…
    res.sendStatus(200);
  },
);

The same function is also available as a method on the client: client.webhooks.verifyWebhookSignature(body, header, secret).

Token management

// List all API tokens
const tokens = await client.tokens.list();

// Create a new token (defaults to the client's environment)
const token = await client.tokens.create({ name: 'ci-pipeline' });
console.log(token.raw); // only present on creation

// Rotate a token (invalidates the old secret, returns new one)
const rotated = await client.tokens.rotate(token.id);

// Delete a token
await client.tokens.delete(token.id);

Errors

All errors inherit TuringVerifyError:

import {
  TuringVerifyError,
  APIError,
  AuthenticationError,
  PermissionError,          // 403
  NotFoundError,            // 404
  InvalidRequestError,      // 400 / 422
  IdempotencyConflictError, // 409
  RateLimitError,           // 429 (has .retryAfter)
  SignatureVerificationError,
} from '@turingverify/sdk';

Retry behavior

• 5xx, 429, and network errors retry with exponential backoff + jitter.
• Retry-After is honored when the server sends it.
• maxRetries: 3 by default — pass maxRetries: 0 to disable.

Type generation

src/types.ts is hand-written to stay in sync with the Pydantic schemas in backend/app/schemas/v1/*.py. When the API server starts serving /v1/openapi.json as a stable artifact, run:

npm run generate-types

to regenerate src/types.generated.ts from that spec. The hand-written types remain authoritative until the generator is adopted.

CLI

The companion Python SDK ships a turingverify CLI. This package is a library only — framework handlers, serverless functions, Next.js API routes.

License

MIT — see LICENSE.