langbly 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Langbly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+# langbly-js
+
+[![npm](https://img.shields.io/npm/v/langbly)](https://www.npmjs.com/package/langbly)
+[![TypeScript](https://img.shields.io/badge/TypeScript-first--class-blue)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Official JavaScript/TypeScript SDK for the [Langbly](https://langbly.com) translation API — a drop-in replacement for Google Translate v2, powered by LLMs.
+
+**5-10x cheaper than Google Translate** · **Better quality** · **Switch in one PR**
+
+## Installation
+
+```bash
+npm install langbly
+```
+
+## Quick Start
+
+```typescript
+import { Langbly } from "langbly";
+
+const client = new Langbly({ apiKey: "your-api-key" });
+
+// Translate text
+const result = await client.translate("Hello world", { target: "nl" });
+console.log(result.text); // "Hallo wereld"
+
+// Batch translate
+const results = await client.translate(["Hello", "Goodbye"], { target: "nl" });
+results.forEach((r) => console.log(r.text));
+
+// Detect language
+const detection = await client.detect("Bonjour le monde");
+console.log(detection.language); // "fr"
+
+// List supported languages
+const languages = await client.languages({ target: "en" });
+```
+
+## Migrate from Google Translate
+
+Already using `@google-cloud/translate`? Switching takes 2 minutes:
+
+```typescript
+// Before (Google Translate)
+import { Translate } from "@google-cloud/translate/build/src/v2";
+const client = new Translate();
+const [translation] = await client.translate("Hello", "nl");
+
+// After (Langbly) — same concepts, better translations, 5x cheaper
+import { Langbly } from "langbly";
+const client = new Langbly({ apiKey: "your-key" });
+const result = await client.translate("Hello", { target: "nl" });
+```
+
+→ Full migration guide: [langbly.com/docs/migrate-google](https://langbly.com/docs/migrate-google)
+
+## Features
+
+- **Google Translate v2 API compatible** — same endpoint format
+- **Zero dependencies** — uses native `fetch`
+- **Full TypeScript types** — interfaces for all request/response shapes
+- **Auto-retry** — exponential backoff on 429/5xx with Retry-After support
+- **Typed errors** — `RateLimitError`, `AuthenticationError`, `LangblyError`
+- **Batch translation** — translate multiple texts in one request
+- **Language detection** — automatic source language identification
+- **HTML support** — translate HTML while preserving tags
+
+## Error Handling
+
+```typescript
+import { Langbly, RateLimitError, AuthenticationError } from "langbly";
+
+const client = new Langbly({ apiKey: "your-key" });
+
+try {
+  const result = await client.translate("Hello", { target: "nl" });
+} catch (err) {
+  if (err instanceof AuthenticationError) {
+    console.error("Invalid API key");
+  } else if (err instanceof RateLimitError) {
+    console.error(`Rate limited — retry after ${err.retryAfter}s`);
+  }
+}
+```
+
+## API Reference
+
+### `new Langbly(options)`
+
+Create a client instance.
+
+- `apiKey` (string): Your Langbly API key — [get one free](https://langbly.com/signup)
+- `baseUrl` (string, optional): Override API URL (default: `https://api.langbly.com`)
+- `timeout` (number, optional): Request timeout in ms (default: 30000)
+- `maxRetries` (number, optional): Retries for transient errors (default: 2)
+
+### `client.translate(text, options)`
+
+- `text` (string | string[]): Text(s) to translate
+- `options.target` (string): Target language code
+- `options.source` (string, optional): Source language code
+- `options.format` ("text" | "html", optional): Input format
+
+### `client.detect(text)`
+
+- `text` (string): Text to analyze
+
+### `client.languages(options?)`
+
+- `options.target` (string, optional): Language code for names
+
+## Links
+
+- [Website](https://langbly.com)
+- [Documentation](https://langbly.com/docs)
+- [Compare: Langbly vs Google vs DeepL](https://langbly.com/compare)
+- [Python SDK](https://github.com/Langbly/langbly-python)
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Langbly — Official JavaScript/TypeScript SDK for the Langbly translation API.
+ *
+ * A drop-in replacement for Google Translate v2 — powered by LLMs.
+ */
+export interface LangblyOptions {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+    /** Number of retries for transient errors (429, 5xx). Default: 2. */
+    maxRetries?: number;
+}
+export interface TranslateOptions {
+    target: string;
+    source?: string;
+    format?: "text" | "html";
+}
+export interface Translation {
+    text: string;
+    source: string;
+    model?: string;
+}
+export interface Detection {
+    language: string;
+    confidence: number;
+}
+export interface Language {
+    code: string;
+    name?: string;
+}
+export declare class LangblyError extends Error {
+    status: number;
+    code: string;
+    constructor(message: string, status?: number, code?: string);
+}
+export declare class RateLimitError extends LangblyError {
+    retryAfter: number | null;
+    constructor(message: string, retryAfter?: number | null);
+}
+export declare class AuthenticationError extends LangblyError {
+    constructor(message: string);
+}
+export declare class Langbly {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    private maxRetries;
+    constructor(options: LangblyOptions);
+    /**
+     * Translate text to the target language.
+     */
+    translate(text: string, options: TranslateOptions): Promise<Translation>;
+    translate(text: string[], options: TranslateOptions): Promise<Translation[]>;
+    /**
+     * Detect the language of text.
+     */
+    detect(text: string): Promise<Detection>;
+    /**
+     * List supported languages.
+     */
+    languages(options?: {
+        target?: string;
+    }): Promise<Language[]>;
+    private postWithRetry;
+    private fetchWithRetry;
+    private throwForStatus;
+    private parseRetryAfter;
+    private getRetryDelay;
+    private backoffDelay;
+    private sleep;
+}

package/dist/client.js

@@ -0,0 +1,179 @@
+/**
+ * Langbly — Official JavaScript/TypeScript SDK for the Langbly translation API.
+ *
+ * A drop-in replacement for Google Translate v2 — powered by LLMs.
+ */
+export class LangblyError extends Error {
+    constructor(message, status = 0, code = "") {
+        super(message);
+        this.name = "LangblyError";
+        this.status = status;
+        this.code = code;
+    }
+}
+export class RateLimitError extends LangblyError {
+    constructor(message, retryAfter = null) {
+        super(message, 429, "RATE_LIMITED");
+        this.name = "RateLimitError";
+        this.retryAfter = retryAfter;
+    }
+}
+export class AuthenticationError extends LangblyError {
+    constructor(message) {
+        super(message, 401, "UNAUTHENTICATED");
+        this.name = "AuthenticationError";
+    }
+}
+const RETRIABLE_STATUS_CODES = new Set([429, 500, 502, 503, 504]);
+export class Langbly {
+    constructor(options) {
+        if (!options.apiKey) {
+            throw new Error("apiKey is required");
+        }
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl ?? "https://api.langbly.com").replace(/\/$/, "");
+        this.timeout = options.timeout ?? 30000;
+        this.maxRetries = options.maxRetries ?? 2;
+    }
+    async translate(text, options) {
+        const q = Array.isArray(text) ? text : [text];
+        const body = { q, target: options.target };
+        if (options.source)
+            body.source = options.source;
+        if (options.format)
+            body.format = options.format;
+        const data = await this.postWithRetry("/language/translate/v2", body);
+        const translations = data.data.translations.map((item) => ({
+            text: item.translatedText,
+            source: item.detectedSourceLanguage ?? options.source ?? "",
+            model: item.model,
+        }));
+        return Array.isArray(text) ? translations : translations[0];
+    }
+    /**
+     * Detect the language of text.
+     */
+    async detect(text) {
+        const data = await this.postWithRetry("/language/translate/v2/detect", {
+            q: text,
+        });
+        const det = data.data.detections[0][0];
+        return {
+            language: det.language,
+            confidence: det.confidence ?? 0,
+        };
+    }
+    /**
+     * List supported languages.
+     */
+    async languages(options) {
+        const params = new URLSearchParams();
+        if (options?.target)
+            params.set("target", options.target);
+        const qs = params.toString();
+        const url = `/language/translate/v2/languages${qs ? `?${qs}` : ""}`;
+        const resp = await this.fetchWithRetry(`${this.baseUrl}${url}`, {
+            method: "GET",
+        });
+        const data = await resp.json();
+        return data.data.languages.map((lang) => ({
+            code: lang.language,
+            name: lang.name,
+        }));
+    }
+    async postWithRetry(path, body) {
+        const resp = await this.fetchWithRetry(`${this.baseUrl}${path}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        return resp.json();
+    }
+    async fetchWithRetry(url, init) {
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            "User-Agent": "langbly-js/0.1.0",
+            ...init.headers,
+        };
+        let lastError;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            let resp;
+            try {
+                resp = await fetch(url, {
+                    ...init,
+                    headers,
+                    signal: AbortSignal.timeout(this.timeout),
+                });
+            }
+            catch (err) {
+                // Network error or timeout
+                lastError = err instanceof Error ? err : new Error(String(err));
+                if (attempt < this.maxRetries) {
+                    await this.sleep(this.backoffDelay(attempt));
+                    continue;
+                }
+                throw new LangblyError(`Request failed after ${this.maxRetries + 1} attempts: ${lastError.message}`, 0, "CONNECTION_ERROR");
+            }
+            if (resp.ok) {
+                return resp;
+            }
+            // Non-retriable error — throw immediately
+            if (!RETRIABLE_STATUS_CODES.has(resp.status)) {
+                await this.throwForStatus(resp);
+            }
+            // Retriable error — retry if we have attempts left
+            if (attempt < this.maxRetries) {
+                const delay = this.getRetryDelay(resp, attempt);
+                await this.sleep(delay);
+                continue;
+            }
+            // Final attempt failed
+            await this.throwForStatus(resp);
+        }
+        // Should not reach here
+        throw lastError ?? new LangblyError("Request failed");
+    }
+    async throwForStatus(resp) {
+        let message = resp.statusText;
+        let code = "";
+        try {
+            const err = await resp.json();
+            message = err?.error?.message ?? message;
+            code = err?.error?.status ?? "";
+        }
+        catch {
+            // ignore parse errors
+        }
+        if (resp.status === 401) {
+            throw new AuthenticationError(message);
+        }
+        if (resp.status === 429) {
+            const retryAfter = this.parseRetryAfter(resp);
+            throw new RateLimitError(message, retryAfter);
+        }
+        throw new LangblyError(message, resp.status, code);
+    }
+    parseRetryAfter(resp) {
+        const header = resp.headers.get("retry-after");
+        if (!header)
+            return null;
+        const value = Number(header);
+        return Number.isFinite(value) ? value : null;
+    }
+    getRetryDelay(resp, attempt) {
+        const retryAfter = resp.headers.get("retry-after");
+        if (retryAfter) {
+            const value = Number(retryAfter);
+            if (Number.isFinite(value)) {
+                return Math.min(value * 1000, 30000);
+            }
+        }
+        return Math.min(500 * 2 ** attempt, 10000);
+    }
+    backoffDelay(attempt) {
+        return Math.min(500 * 2 ** attempt, 10000);
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { Langbly, LangblyError, RateLimitError, AuthenticationError, } from "./client.js";
+export type { LangblyOptions, TranslateOptions, Translation, Detection, Language, } from "./client.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { Langbly, LangblyError, RateLimitError, AuthenticationError, } from "./client.js";

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "langbly",
+  "version": "0.1.0",
+  "description": "Official JavaScript/TypeScript SDK for the Langbly translation API",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "translation",
+    "api",
+    "langbly",
+    "google-translate",
+    "i18n",
+    "localization",
+    "llm"
+  ],
+  "author": "Jasper de Winter <jasper@langbly.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Langbly/langbly-js.git"
+  },
+  "homepage": "https://langbly.com",
+  "devDependencies": {
+    "typescript": "^5.4",
+    "vitest": "^1.6"
+  }
+}