gengo-ts 1.0.0

package/README.md

@@ -0,0 +1,316 @@
+# gengo-ts
+
+Modern TypeScript client for the [Gengo Translation API](https://gengo.com/).
+
+## 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
+
+```bash
+# npm
+npm install gengo-ts
+
+# pnpm
+pnpm add gengo-ts
+
+# yarn
+yarn add gengo-ts
+
+# bun
+bun add gengo-ts
+```
+
+## Quick Start
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+// 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
+
+```typescript
+// 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
+
+```typescript
+// 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
+
+```typescript
+// List all glossaries
+const glossaries = await client.glossary.list();
+
+// Get a specific glossary
+const glossary = await client.glossary.get(glossaryId);
+```
+
+### Service Methods
+
+```typescript
+// 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:
+
+```typescript
+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
+
+```typescript
+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)
+
+```typescript
+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)
+
+```typescript
+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

package/dist/common-Bk4hl8fX.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Quality tier for translation jobs
+ */
+type Tier = 'standard' | 'pro';
+/**
+ * Job type
+ */
+type JobType = 'text' | 'file';
+/**
+ * Currency code
+ */
+type Currency = 'USD' | string;
+/**
+ * Job status values
+ */
+type JobStatus = 'queued' | 'available' | 'pending' | 'reviewable' | 'approved' | 'revising' | 'rejected' | 'cancelled' | 'hold';
+/**
+ * Rejection reason
+ */
+type RejectionReason = 'quality' | 'incomplete' | 'other';
+/**
+ * Follow-up action after rejection
+ */
+type FollowUp = 'requeue' | 'cancel';
+/**
+ * Comment author type
+ */
+type CommentAuthor = 'customer' | 'translator';
+/**
+ * File attachment for jobs
+ */
+interface Attachment {
+    url: string;
+    filename: string;
+    mime_type: string;
+}
+/**
+ * Comment in a thread
+ */
+interface Comment {
+    body: string;
+    author: CommentAuthor;
+    ctime: number;
+}
+/**
+ * Pagination options for list endpoints
+ */
+interface PaginationOptions {
+    count?: number;
+    timestamp_after?: number;
+}
+
+export type { Attachment as A, Currency as C, FollowUp as F, JobType as J, PaginationOptions as P, RejectionReason as R, Tier as T, JobStatus as a, Comment as b, CommentAuthor as c };