gengo-ts

Modern TypeScript client for the Gengo Translation API.

Features

• Full TypeScript support with comprehensive types
• Works across Node.js 18+, Deno, and Bun
• Zero runtime dependencies
• Class-based API with namespaced methods
• Typed error handling
• Webhook handlers for job updates

Installation

# npm
npm install gengo-ts

# pnpm
pnpm add gengo-ts

# yarn
yarn add gengo-ts

# bun
bun add gengo-ts

Quick Start

import { GengoClient } from 'gengo-ts';

const client = new GengoClient({
  publicKey: 'your_public_key',
  privateKey: 'your_private_key',
  sandbox: true, // Use false for production
});

// Get account balance
const balance = await client.account.getBalance();
console.log(`Balance: ${balance.credits} ${balance.currency}`);

// Submit a translation job
const order = await client.jobs.create({
  job_1: {
    body_src: 'Hello, world!',
    lc_src: 'en',
    lc_tgt: 'ja',
    tier: 'standard',
    slug: 'greeting',
  },
});

console.log(`Order ID: ${order.order_id}`);

API Reference

Client Configuration

const client = new GengoClient({
  publicKey: string;      // Your Gengo API public key
  privateKey: string;     // Your Gengo API private key
  sandbox?: boolean;      // Use sandbox environment (default: false)
  timeout?: number;       // Request timeout in ms (default: 30000)
});

Account Methods

// Get account statistics
const stats = await client.account.getStats();

// Get account information
const me = await client.account.getMe();

// Get account balance
const balance = await client.account.getBalance();

// Get preferred translators
const translators = await client.account.getPreferredTranslators();

Jobs Methods

// Submit jobs for translation
const order = await client.jobs.create({
  job_1: {
    body_src: 'Text to translate',
    lc_src: 'en',
    lc_tgt: 'ja',
    tier: 'standard',
    slug: 'my-job',
    comment: 'Instructions for translator',
    callback_url: 'https://example.com/webhook',
    auto_approve: false,
    custom_data: '{"id": 123}',
  },
});

// List recent jobs
const jobs = await client.jobs.list({ status: 'reviewable', count: 10 });

// Get a specific job
const { job } = await client.jobs.get(jobId);

// Get multiple jobs
const { jobs } = await client.jobs.getMany([1, 2, 3]);

// Approve a job
await client.jobs.update(jobId, {
  action: 'approve',
  rating: 5,
  for_translator: 'Great work!',
});

// Request revision
await client.jobs.update(jobId, {
  action: 'revise',
  comment: 'Please use formal language.',
});

// Reject a job
await client.jobs.update(jobId, {
  action: 'reject',
  reason: 'quality',
  comment: 'Translation is incorrect.',
  follow_up: 'requeue',
});

// Cancel a job (before translator starts)
await client.jobs.cancel(jobId);

// Get job revisions
const { revisions } = await client.jobs.getRevisions(jobId);

// Get job comments
const { thread } = await client.jobs.getComments(jobId);

// Add a comment
await client.jobs.addComment(jobId, 'Please clarify the context.');

Orders Methods

// Get order details
const { order } = await client.orders.get(orderId);

// Cancel all available jobs in an order
await client.orders.cancel(orderId);

// Get order comments
const { thread } = await client.orders.getComments(orderId);

// Add comment to order
await client.orders.addComment(orderId, 'General instructions...');

Glossary Methods

// List all glossaries
const glossaries = await client.glossary.list();

// Get a specific glossary
const glossary = await client.glossary.get(glossaryId);

Service Methods

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

// Get language pairs (optionally filtered by source)
const pairs = await client.service.getLanguagePairs('en');

// Get a quote for jobs
const quote = await client.service.getQuote({
  job_1: {
    body_src: 'Text to translate',
    lc_src: 'en',
    lc_tgt: 'ja',
    tier: 'standard',
  },
});

Error Handling

The library throws typed errors for different failure modes:

import {
  GengoClient,
  GengoError,
  GengoAuthError,
  GengoValidationError,
  GengoNotFoundError,
  GengoRateLimitError,
  GengoInsufficientCreditsError,
  GengoNetworkError,
  GengoJobStateError,
} from 'gengo-ts';

try {
  await client.jobs.create(jobs);
} catch (error) {
  if (error instanceof GengoAuthError) {
    console.error('Authentication failed. Check your API keys.');
  } else if (error instanceof GengoInsufficientCreditsError) {
    console.error('Not enough credits. Please top up.');
  } else if (error instanceof GengoValidationError) {
    console.error(`Validation error (${error.code}): ${error.message}`);
  } else if (error instanceof GengoRateLimitError) {
    console.error('Rate limited. Please slow down.');
  } else if (error instanceof GengoNetworkError) {
    console.error('Network error:', error.message);
  }
}

Webhook Handler

Handle job updates and translator comments with the webhook handler:

Express

import express from 'express';
import { createWebhookHandler } from 'gengo-ts/webhook';
import { expressAdapter } from 'gengo-ts/webhook/express';

const app = express();
app.use(express.urlencoded({ extended: true }));

const handler = createWebhookHandler({
  onJobUpdate: async (job) => {
    console.log(`Job ${job.job_id}: ${job.status}`);
    if (job.status === 'approved') {
      // Save translation: job.body_tgt
    }
  },
  onComment: async (comment) => {
    console.log(`Comment on job ${comment.job_id}: ${comment.body}`);
  },
});

app.post('/webhook', expressAdapter(handler));

Hono (Deno, Bun, Cloudflare Workers)

import { Hono } from 'hono';
import { createWebhookHandler } from 'gengo-ts/webhook';
import { honoAdapter } from 'gengo-ts/webhook/hono';

const app = new Hono();

const handler = createWebhookHandler({
  onJobUpdate: async (job) => {
    console.log(`Job ${job.job_id}: ${job.status}`);
  },
});

app.post('/webhook', honoAdapter(handler));

Raw Web Request (Deno, Bun, Workers)

import { createWebhookHandler, handleRequest } from 'gengo-ts/webhook';

const handler = createWebhookHandler({
  onJobUpdate: async (job) => {
    console.log(`Job ${job.job_id}: ${job.status}`);
  },
});

// In your request handler
const response = await handleRequest(request, handler);

Job Statuses

Jobs go through the following statuses:

Status	Description
queued	Being processed, not yet visible to translators
available	Waiting for a translator to start
pending	Translator is working on it
reviewable	Translation complete, awaiting review
approved	Approved and complete
revising	Sent back for revisions
rejected	Rejected by customer
cancelled	Cancelled before work started
hold	On hold by Gengo support

Quality Tiers

Tier	Description
standard	Native-level fluency, general content
pro	Professional translators, specialized content

License

MIT