straker-verify

Official Node.js SDK for the Straker Verify API — AI-powered content verification and translation quality evaluation.

Features

• 🔒 Full TypeScript support with comprehensive types
• 🚀 Modern ESM and CommonJS support
• 📦 Zero dependencies (uses native fetch)
• ⚡ Promise-based API with async/await
• 🛡️ Built-in error handling with custom error classes
• 🔄 Utility methods for common workflows

Installation

npm install straker-verify

yarn add straker-verify

pnpm add straker-verify

Quick Start

import { StrakerVerify } from 'straker-verify';

// Initialize the client
const client = new StrakerVerify({
  apiKey: 'your-api-key'
});

// Get supported languages
const languages = await client.getLanguages();
console.log(languages);

// Check your token balance
const balance = await client.getTokenBalance();
console.log(`Token balance: ${balance}`);

Configuration

import { StrakerVerify } from 'straker-verify';

const client = new StrakerVerify({
  // Required: Your API key
  apiKey: 'your-api-key',

  // Optional: Base URL (defaults to https://api-verify.straker.ai)
  baseUrl: 'https://api-verify.straker.ai',

  // Optional: Request timeout in ms (defaults to 30000)
  timeout: 30000,

  // Optional: Custom fetch implementation
  fetch: customFetch
});

API Reference

Languages

Get All Languages

Retrieve all supported languages:

const languages = await client.getLanguages();
// Returns: Language[]
// [{ id: 'uuid', code: 'en', name: 'English' }, ...]

Find Language by Code

const spanish = await client.findLanguageByCode('es');
// Returns: Language | undefined

Find Multiple Languages by Codes

const languages = await client.findLanguagesByCodes(['es', 'fr', 'de']);
// Returns: Language[]

Projects

Create a Translation Project

const result = await client.createProject({
  // Files to translate (File, Blob, or Buffer)
  files: [new File(['Hello world'], 'content.txt')],

  // Target language UUIDs
  languages: ['spanish-uuid', 'french-uuid'],

  // Project title
  title: 'Q4 Marketing Content',

  // Optional: Workflow ID
  workflowId: 'workflow-uuid',

  // Optional: Require confirmation before processing (default: true)
  confirmationRequired: true,

  // Optional: Webhook URL for notifications
  callbackUri: 'https://your-app.com/webhook',

  // Optional: Notes
  clientNotes: 'Rush order'
});

console.log(result.project_id);

Create a Human Verification Project

const result = await client.createHumanVerificationProject({
  files: [file],
  languages: ['spanish-uuid'],
  title: 'Human Review Needed'
});

Create a Quality Boost Project

For existing translations in XLF format:

const result = await client.createQualityBoostProject({
  files: [xlfFile],
  language: 'spanish-uuid', // Single language
  title: 'Improve Translation Quality'
});

Create a Quality Evaluation Project

const result = await client.createQualityEvaluationProject({
  files: [xlfFile],
  language: 'spanish-uuid',
  title: 'Evaluate Translation Quality'
});

Get All Projects

// Get first page (100 items)
const projects = await client.getProjects();

// With pagination
const projects = await client.getProjects({
  page: 2,
  pageSize: 50
});

Get Project Details

const project = await client.getProject('project-uuid');

console.log(project.data.status);
console.log(project.data.source_files);

// If confirmation is pending, token_cost is included
if ('token_cost' in project) {
  console.log(`Cost: ${project.token_cost} tokens`);
}

Confirm a Project

Projects created with confirmationRequired: true must be confirmed:

await client.confirmProject('project-uuid');

Wait for Project Completion

// Wait for project to complete (polls every 5 seconds)
const project = await client.waitForProject('project-uuid');

// With custom options
const project = await client.waitForProject(
  'project-uuid',
  ['completed', 'error'], // Target statuses
  {
    pollInterval: 10000, // 10 seconds
    timeout: 600000      // 10 minutes
  }
);

Get Project Segments

const segments = await client.getProjectSegments(
  'project-uuid',
  'file-uuid',
  'language-uuid',
  { page: 1, pageSize: 100 }
);

segments.forEach(segment => {
  console.log(segment.source_text);
  console.log(segment.translation?.target_text);
});

Files

Download a File

const response = await client.downloadFile('file-uuid');
const blob = await response.blob();
// Or in Node.js:
const buffer = Buffer.from(await response.arrayBuffer());

User

Get Token Balance

const balance = await client.getTokenBalance();
console.log(`You have ${balance} tokens`);

API Keys

Get All API Keys

const keys = await client.getApiKeys();

Get Specific API Key

const key = await client.getApiKey('key-uuid');

Create API Key

const newKey = await client.createApiKey({
  name: 'Production Key',
  description: 'For production use'
});

Workflows

Get All Workflows

const workflows = await client.getWorkflows();

Get Workflow Details

const workflow = await client.getWorkflow('workflow-uuid');
console.log(workflow.actions);

Error Handling

The SDK provides custom error classes for better error handling:

import {
  StrakerVerify,
  StrakerVerifyError,
  AuthenticationError,
  ValidationError,
  NotFoundError,
  RateLimitError,
  TimeoutError,
  NetworkError
} from 'straker-verify';

try {
  await client.createProject({ ... });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof ValidationError) {
    console.error('Validation errors:', error.errors);
    // error.errors: [{ loc: ['title'], msg: 'Required', type: 'missing' }]
  } else if (error instanceof NotFoundError) {
    console.error('Resource not found');
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof TimeoutError) {
    console.error('Request timed out');
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message);
  } else if (error instanceof StrakerVerifyError) {
    console.error(`API error: ${error.message}`, error.statusCode);
  }
}

Complete Workflow Example

Here's a complete example showing a typical translation workflow:

import { StrakerVerify } from 'straker-verify';
import fs from 'fs/promises';

async function translateDocument() {
  const client = new StrakerVerify({
    apiKey: process.env.STRAKER_API_KEY!
  });

  // 1. Get target languages
  const [spanish, french] = await client.findLanguagesByCodes(['es', 'fr']);
  if (!spanish || !french) {
    throw new Error('Languages not found');
  }

  // 2. Check balance
  const balance = await client.getTokenBalance();
  console.log(`Current balance: ${balance} tokens`);

  // 3. Read file to translate
  const fileContent = await fs.readFile('document.txt');
  const file = new Blob([fileContent], { type: 'text/plain' });

  // 4. Create project with confirmation required
  const { project_id } = await client.createProject({
    files: [file],
    fileNames: ['document.txt'],
    languages: [spanish.id, french.id],
    title: 'Document Translation',
    confirmationRequired: true
  });

  console.log(`Project created: ${project_id}`);

  // 5. Check cost before confirming
  const projectDetails = await client.getProject(project_id);
  if ('token_cost' in projectDetails) {
    console.log(`This will cost ${projectDetails.token_cost} tokens`);
  }

  // 6. Confirm the project
  await client.confirmProject(project_id);
  console.log('Project confirmed');

  // 7. Wait for completion
  const completedProject = await client.waitForProject(project_id, ['completed'], {
    pollInterval: 10000 // Check every 10 seconds
  });

  console.log('Project completed!');

  // 8. Download translated files
  for (const sourceFile of completedProject.source_files) {
    for (const targetFile of sourceFile.target_files || []) {
      const response = await client.downloadFile(targetFile.target_file_uuid);
      const buffer = Buffer.from(await response.arrayBuffer());
      await fs.writeFile(`translated-${targetFile.language_uuid}.txt`, buffer);
      console.log(`Downloaded: translated-${targetFile.language_uuid}.txt`);
    }
  }
}

translateDocument().catch(console.error);

TypeScript Types

All types are exported for TypeScript users:

import type {
  Language,
  Project,
  Segment,
  Workflow,
  StrakerVerifyConfig,
  CreateProjectOptions
} from 'straker-verify';

Requirements

• Node.js 18+ (for native fetch support)
• Or provide a custom fetch implementation for older Node.js versions

Links

• API Documentation
• Straker Verify Help Center

License

MIT