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