gengo-ts 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,703 @@
+import { T as Tier, J as JobType, A as Attachment, C as Currency, a as JobStatus, P as PaginationOptions, R as RejectionReason, F as FollowUp, b as Comment } from './common-Bk4hl8fX.js';
+export { c as CommentAuthor } from './common-Bk4hl8fX.js';
+
+/**
+ * HTTP client configuration
+ */
+interface HttpClientConfig {
+    publicKey: string;
+    privateKey: string;
+    sandbox?: boolean;
+    timeout?: number;
+}
+/**
+ * HTTP client for making authenticated requests to the Gengo API
+ */
+declare class HttpClient {
+    private readonly publicKey;
+    private readonly privateKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    constructor(config: HttpClientConfig);
+    /**
+     * Makes an authenticated GET request
+     */
+    get<T>(path: string, params?: object): Promise<T>;
+    /**
+     * Makes an authenticated POST request
+     */
+    post<T>(path: string, data?: object): Promise<T>;
+    /**
+     * Makes an authenticated PUT request
+     */
+    put<T>(path: string, data?: object): Promise<T>;
+    /**
+     * Makes an authenticated DELETE request
+     */
+    delete<T>(path: string): Promise<T>;
+    /**
+     * Core request method that handles authentication, serialization, and error handling
+     */
+    private request;
+}
+
+/**
+ * Job input payload for creating translation jobs
+ */
+interface JobInput {
+    /** Original body of text to be translated */
+    body_src: string;
+    /** Source language code (IETF format) */
+    lc_src: string;
+    /** Target language code (IETF format) */
+    lc_tgt: string;
+    /** Quality level */
+    tier: Tier;
+    /** Job title for internal reference */
+    slug: string;
+    /** Job type: 'text' (default) or 'file' */
+    type?: JobType;
+    /** File identifier from quote (required if type is 'file') */
+    identifier?: string;
+    /** Glossary ID to use for translation */
+    glossary_id?: number;
+    /** Position in job group (starts at 1) */
+    position?: number;
+    /** Force new translation even if duplicate exists */
+    force?: boolean;
+    /** Instructions or context for translator */
+    comment?: string;
+    /** File attachments for context */
+    attachments?: Attachment[];
+    /** Plus services (e.g., ['translation', 'edit']) */
+    services?: ('translation' | 'edit')[];
+    /** Purpose of translation */
+    purpose?: string;
+    /** Desired tone for translation */
+    tone?: string;
+    /** Use preferred translators */
+    use_preferred?: boolean;
+    /** Callback URL for job updates */
+    callback_url?: string;
+    /** Automatically approve on completion */
+    auto_approve?: boolean;
+    /** Custom client data (max 1KB) */
+    custom_data?: string;
+    /** Maximum character limit for translation */
+    max_chars?: number;
+    /** Group jobs from same language pair (default: true) */
+    as_group?: boolean;
+}
+/**
+ * Job response from the API
+ */
+interface Job {
+    job_id: number;
+    order_id: number;
+    body_src: string;
+    body_tgt: string;
+    lc_src: string;
+    lc_tgt: string;
+    unit_count: number;
+    tier: Tier;
+    credits: number;
+    status: JobStatus;
+    eta: number;
+    ctime: number;
+    callback_url: string;
+    auto_approve: boolean;
+    custom_data: string;
+    slug: string;
+    currency: Currency;
+    file_url_src?: string;
+    file_url_tgt?: string;
+    file_download_ready?: boolean;
+}
+/**
+ * Minimal job info returned in list endpoints
+ */
+interface JobSummary {
+    job_id: number;
+    ctime: number;
+}
+/**
+ * Revision entry for a job
+ */
+interface Revision {
+    rev_id: number;
+    ctime: string;
+}
+/**
+ * Revision details
+ */
+interface RevisionDetail {
+    body_tgt: string;
+    ctime: string;
+}
+/**
+ * Feedback for a job
+ */
+interface Feedback {
+    for_translator: string;
+    rating: number;
+}
+/**
+ * Action to approve a job
+ */
+interface ApproveAction {
+    action: 'approve';
+    /** Rating 1-5 */
+    rating?: 1 | 2 | 3 | 4 | 5;
+    /** Comment for translator */
+    for_translator?: string;
+    /** Private comment for Gengo staff */
+    for_mygengo?: string;
+    /** Allow public sharing */
+    public?: boolean;
+}
+/**
+ * Action to request revision
+ */
+interface ReviseAction {
+    action: 'revise';
+    /** Reason for revision request */
+    comment: string;
+}
+/**
+ * Action to reject a job
+ */
+interface RejectAction {
+    action: 'reject';
+    reason: RejectionReason;
+    comment: string;
+    follow_up?: FollowUp;
+}
+/**
+ * Action to archive a job
+ */
+interface ArchiveAction {
+    action: 'archive';
+}
+/**
+ * Union of all job actions
+ */
+type JobAction = ApproveAction | ReviseAction | RejectAction | ArchiveAction;
+/**
+ * Options for listing jobs
+ */
+interface ListJobsOptions extends PaginationOptions {
+    status?: JobStatus;
+}
+/**
+ * Response from job creation
+ */
+interface CreateJobsResponse {
+    order_id: number;
+    job_count: number;
+    credits_used: number;
+    currency: Currency;
+    jobs?: Record<string, Job[]>;
+}
+/**
+ * Bulk job action with job IDs
+ */
+interface BulkApproveAction {
+    action: 'approve';
+    job_ids: Array<{
+        job_id: number;
+        rating?: 1 | 2 | 3 | 4 | 5;
+        for_translator?: string;
+        for_mygengo?: string;
+        public?: boolean;
+    }>;
+}
+/**
+ * Bulk revise action
+ */
+interface BulkReviseAction {
+    action: 'revise';
+    job_ids: Array<{
+        job_id: number;
+        comment: string;
+    }>;
+}
+/**
+ * Bulk reject action
+ */
+interface BulkRejectAction {
+    action: 'reject';
+    job_ids: Array<{
+        job_id: number;
+        reason: RejectionReason;
+        comment: string;
+        follow_up?: FollowUp;
+    }>;
+}
+/**
+ * Bulk archive action
+ */
+interface BulkArchiveAction {
+    action: 'archive';
+    job_ids: number[];
+}
+/**
+ * Union of bulk job actions
+ */
+type BulkJobAction = BulkApproveAction | BulkReviseAction | BulkRejectAction | BulkArchiveAction;
+
+/**
+ * Account statistics
+ */
+interface AccountStats {
+    credits_spent: number;
+    user_since: number;
+    currency: Currency;
+    billing_type: string;
+    customer_type: string;
+}
+/**
+ * Account information
+ */
+interface AccountMe {
+    email: string;
+    full_name: string;
+    display_name: string;
+    language_code: string;
+}
+/**
+ * Account balance
+ */
+interface AccountBalance {
+    credits: number;
+    currency: Currency;
+}
+/**
+ * Preferred translator info
+ */
+interface PreferredTranslator {
+    id: number;
+    last_login: number;
+}
+/**
+ * Preferred translators for a language pair
+ */
+interface PreferredTranslatorGroup {
+    lc_src: string;
+    lc_tgt: string;
+    tier: Tier;
+    translators: PreferredTranslator[];
+}
+
+/**
+ * Order details
+ */
+interface Order {
+    order_id: string;
+    total_credits: string;
+    total_units: number;
+    total_jobs: string;
+    currency: Currency;
+    jobs_queued: number;
+    jobs_available: string[];
+    jobs_pending: string[];
+    jobs_reviewable: string[];
+    jobs_approved: string[];
+    jobs_revising: string[];
+    jobs_cancelled: string[];
+    jobs_held: string[];
+}
+
+/**
+ * Target language entry in glossary
+ */
+type TargetLanguage = [number, string];
+/**
+ * Glossary details
+ */
+interface Glossary {
+    id: number;
+    customer_user_id: number;
+    source_language_id: number;
+    source_language_code: string;
+    target_languages: TargetLanguage[];
+    is_public: boolean;
+    unit_count: number;
+    title: string;
+    description: string | null;
+    status: number;
+    ctime: string;
+}
+
+/**
+ * Supported language
+ */
+interface Language {
+    lc: string;
+    language: string;
+    localized_name: string;
+    unit_type: 'word' | 'character';
+}
+/**
+ * Language pair with pricing
+ */
+interface LanguagePair {
+    lc_src: string;
+    lc_tgt: string;
+    tier: Tier;
+    unit_price: number;
+    currency: Currency;
+}
+/**
+ * Quote for a single job
+ */
+interface JobQuote {
+    credits: number;
+    eta: number;
+    unit_count: number;
+    lc_src_detected?: string;
+    currency: Currency;
+    type: JobType;
+    custom_data?: string;
+    identifier?: string;
+}
+/**
+ * Quote error for a job
+ */
+interface JobQuoteError {
+    err: {
+        code: number;
+        key: string;
+        filename?: string;
+    };
+}
+/**
+ * Response from quote endpoint
+ */
+interface QuoteResponse {
+    jobs: Record<string, JobQuote | JobQuoteError>;
+}
+/**
+ * File job input for quotes
+ */
+interface FileJobInput {
+    type: 'file';
+    lc_src: string;
+    lc_tgt: string;
+    tier: Tier;
+    file_path: string;
+}
+/**
+ * Unit count request item
+ */
+interface UnitCountInput {
+    text: string;
+    lc: string;
+}
+/**
+ * Unit count response item
+ */
+interface UnitCountResult {
+    text: string;
+    lc: string;
+    unit_type: 'word' | 'character';
+    unit_count: number;
+}
+/**
+ * Partial job input for quotes (only required fields)
+ */
+type QuoteJobInput = Pick<JobInput, 'body_src' | 'lc_src' | 'lc_tgt' | 'tier'> & Partial<Pick<JobInput, 'type' | 'custom_data' | 'services' | 'slug' | 'comment' | 'callback_url'>>;
+
+/**
+ * Account resource for managing account information
+ */
+declare class AccountResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Retrieves account statistics such as orders made and credits spent
+     */
+    getStats(): Promise<AccountStats>;
+    /**
+     * Retrieves account information such as email and display name
+     */
+    getMe(): Promise<AccountMe>;
+    /**
+     * Retrieves account balance in credits
+     */
+    getBalance(): Promise<AccountBalance>;
+    /**
+     * Retrieves list of preferred translators set by user
+     */
+    getPreferredTranslators(): Promise<PreferredTranslatorGroup[]>;
+}
+
+/**
+ * Jobs payload for submission
+ */
+interface JobsPayload {
+    jobs: Record<string, JobInput>;
+    comment?: string;
+}
+/**
+ * Jobs resource for managing translation jobs
+ */
+declare class JobsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Submits a job or group of jobs for translation
+     * @param jobs - Record of job keys to job inputs, or a JobsPayload with optional order comment
+     */
+    create(jobs: Record<string, JobInput> | JobsPayload): Promise<CreateJobsResponse>;
+    /**
+     * Retrieves a list of recent jobs filtered by parameters
+     */
+    list(options?: ListJobsOptions): Promise<JobSummary[]>;
+    /**
+     * Retrieves a specific job by ID
+     */
+    get(id: number | string): Promise<{
+        job: Job;
+    }>;
+    /**
+     * Retrieves multiple jobs by their IDs
+     * @param ids - Array of job IDs or comma-separated string
+     */
+    getMany(ids: (number | string)[] | string): Promise<{
+        jobs: Job[];
+    }>;
+    /**
+     * Updates a job (approve, revise, reject, or archive)
+     */
+    update(id: number | string, action: JobAction): Promise<void>;
+    /**
+     * Updates multiple jobs with the same action
+     */
+    updateMany(action: BulkJobAction): Promise<void>;
+    /**
+     * Cancels a job (only if not yet started by translator)
+     */
+    cancel(id: number | string): Promise<void>;
+    /**
+     * Gets list of revisions for a job
+     */
+    getRevisions(id: number | string): Promise<{
+        job_id: number;
+        revisions: Revision[];
+    }>;
+    /**
+     * Gets a specific revision for a job
+     */
+    getRevision(id: number | string, revisionId: number | string): Promise<{
+        revision: RevisionDetail;
+    }>;
+    /**
+     * Retrieves feedback submitted for a job
+     */
+    getFeedback(id: number | string): Promise<{
+        feedback: Feedback;
+    }>;
+    /**
+     * Retrieves the comment thread for a job
+     */
+    getComments(id: number | string): Promise<{
+        thread: Comment[];
+    }>;
+    /**
+     * Submits a new comment to the job's comment thread
+     */
+    addComment(id: number | string, body: string): Promise<void>;
+}
+
+/**
+ * Orders resource for managing translation orders
+ */
+declare class OrdersResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Retrieves an order by ID with job status breakdown
+     */
+    get(id: number | string): Promise<{
+        order: Order;
+    }>;
+    /**
+     * Cancels all available jobs in an order
+     * Note: This will not cancel jobs that are already in progress
+     */
+    cancel(id: number | string): Promise<{
+        order: Order;
+    }>;
+    /**
+     * Retrieves the comment thread for an order
+     */
+    getComments(id: number | string): Promise<{
+        thread: Comment[];
+    }>;
+    /**
+     * Submits a new comment to the order's comment thread
+     */
+    addComment(id: number | string, body: string): Promise<void>;
+}
+
+/**
+ * Glossary resource for managing translation glossaries
+ */
+declare class GlossaryResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Retrieves all glossaries belonging to the authenticated user
+     */
+    list(): Promise<Glossary[]>;
+    /**
+     * Retrieves a specific glossary by ID
+     */
+    get(id: number | string): Promise<Glossary>;
+}
+
+/**
+ * Service resource for language and pricing information
+ */
+declare class ServiceResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Returns a list of supported languages and their language codes
+     */
+    getLanguages(): Promise<Language[]>;
+    /**
+     * Returns supported translation language pairs with pricing
+     * @param lcSrc - Optional source language code to filter pairs
+     */
+    getLanguagePairs(lcSrc?: string): Promise<LanguagePair[]>;
+    /**
+     * Returns credit quote and unit count for text jobs
+     */
+    getQuote(jobs: Record<string, QuoteJobInput>): Promise<QuoteResponse>;
+    /**
+     * Uploads files and returns quotes with identifiers for ordering
+     * Note: File upload requires multipart/form-data which is not yet implemented.
+     * Use the Gengo dashboard for file jobs, or implement custom file upload logic.
+     */
+    getFileQuote(_jobs: Record<string, {
+        type: 'file';
+        lc_src: string;
+        lc_tgt: string;
+        tier: string;
+    }>): Promise<QuoteResponse>;
+}
+
+/**
+ * Configuration options for the Gengo client
+ */
+interface GengoClientConfig {
+    /** Your Gengo API public key */
+    publicKey: string;
+    /** Your Gengo API private key */
+    privateKey: string;
+    /** Use sandbox environment (default: false) */
+    sandbox?: boolean;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+/**
+ * Gengo API client for human translation services
+ *
+ * @example
+ * ```typescript
+ * import { GengoClient } from 'gengo-ts';
+ *
+ * const client = new GengoClient({
+ *   publicKey: 'your_public_key',
+ *   privateKey: 'your_private_key',
+ *   sandbox: true,
+ * });
+ *
+ * // Get account balance
+ * const balance = await client.account.getBalance();
+ *
+ * // Submit translation jobs
+ * const order = await client.jobs.create({
+ *   job_1: {
+ *     body_src: 'Hello, world!',
+ *     lc_src: 'en',
+ *     lc_tgt: 'ja',
+ *     tier: 'standard',
+ *     slug: 'greeting',
+ *   },
+ * });
+ * ```
+ */
+declare class GengoClient {
+    private readonly http;
+    /** Account information and statistics */
+    readonly account: AccountResource;
+    /** Translation jobs management */
+    readonly jobs: JobsResource;
+    /** Translation orders management */
+    readonly orders: OrdersResource;
+    /** Glossary management */
+    readonly glossary: GlossaryResource;
+    /** Language and pricing services */
+    readonly service: ServiceResource;
+    constructor(config: GengoClientConfig);
+}
+
+/**
+ * Base error class for all Gengo API errors
+ */
+declare class GengoError extends Error {
+    readonly code: number;
+    constructor(message: string, code?: number);
+}
+/**
+ * Authentication failed (invalid API keys, missing signature, etc.)
+ * Error codes: 1000, 1100, 1150
+ */
+declare class GengoAuthError extends GengoError {
+    constructor(message: string, code?: number);
+}
+/**
+ * Validation errors for request parameters
+ * Error codes: 1200-1951
+ */
+declare class GengoValidationError extends GengoError {
+    constructor(message: string, code?: number);
+}
+/**
+ * Resource not found or unauthorized access
+ * Error codes: 2100, 2200, 2600, 2750
+ */
+declare class GengoNotFoundError extends GengoError {
+    constructor(message: string, code?: number);
+}
+/**
+ * Rate limit exceeded
+ * HTTP status: 429
+ */
+declare class GengoRateLimitError extends GengoError {
+    constructor(message?: string);
+}
+/**
+ * Insufficient credits in account
+ * Error code: 2700
+ */
+declare class GengoInsufficientCreditsError extends GengoError {
+    constructor(message?: string);
+}
+/**
+ * Network or connection errors
+ */
+declare class GengoNetworkError extends GengoError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Job is not in the correct state for the requested action
+ * Error codes: 2250, 2251, 2252, 2650
+ */
+declare class GengoJobStateError extends GengoError {
+    constructor(message: string, code?: number);
+}
+
+export { type AccountBalance, type AccountMe, type AccountStats, type ApproveAction, type ArchiveAction, Attachment, type BulkApproveAction, type BulkArchiveAction, type BulkJobAction, type BulkRejectAction, type BulkReviseAction, Comment, type CreateJobsResponse, Currency, type Feedback, type FileJobInput, FollowUp, GengoAuthError, GengoClient, type GengoClientConfig, GengoError, GengoInsufficientCreditsError, GengoJobStateError, GengoNetworkError, GengoNotFoundError, GengoRateLimitError, GengoValidationError, type Glossary, type Job, type JobAction, type JobInput, type JobQuote, type JobQuoteError, JobStatus, type JobSummary, JobType, type Language, type LanguagePair, type ListJobsOptions, type Order, PaginationOptions, type PreferredTranslator, type PreferredTranslatorGroup, type QuoteJobInput, type QuoteResponse, type RejectAction, RejectionReason, type ReviseAction, type Revision, type RevisionDetail, type TargetLanguage, Tier, type UnitCountInput, type UnitCountResult };