nativ-sdk 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nativ Technologies
+
+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,200 @@
+# Nativ Node.js/TypeScript SDK
+
+The official Node.js client for the [Nativ](https://usenativ.com) AI localization platform.
+
+Wraps the full Nativ REST API with **TypeScript types**, zero runtime dependencies (uses native `fetch`), and ESM + CommonJS dual output.
+
+## Installation
+
+```bash
+npm install nativ
+```
+
+## Quick start
+
+```typescript
+import { Nativ } from "nativ";
+
+const client = new Nativ({ apiKey: "nativ_..." }); // or set NATIV_API_KEY env var
+
+// Translate text
+const result = await client.translate("Launch your product globally", "French");
+console.log(result.translatedText); // "Lancez votre produit à l'international"
+console.log(result.tmMatch);        // TM match details (score, source, etc.)
+
+// Batch translate
+const results = await client.translateBatch(
+  ["Sign up", "Log in", "Settings"],
+  "German",
+);
+for (const r of results) {
+  console.log(r.translatedText);
+}
+```
+
+## Features
+
+### Translation
+
+```typescript
+const result = await client.translate(
+  "Welcome to our platform",
+  "Spanish",
+  {
+    context: "SaaS onboarding email subject line",
+    formality: "formal",
+    backtranslate: true,
+  },
+);
+
+console.log(result.translatedText);  // translated text
+console.log(result.backtranslation); // back-translation for QA
+console.log(result.rationale);       // AI explanation of translation choices
+console.log(result.tmMatch?.score);  // TM match percentage
+```
+
+### OCR — extract text from images
+
+```typescript
+const result = await client.extractText("screenshot.png");
+console.log(result.extractedText);
+```
+
+### Image culturalization
+
+```typescript
+const result = await client.culturalizeImage(
+  "banner_en.png",
+  "Soldes d'été",
+  "fr",
+  { numImages: 3 },
+);
+for (const img of result.images) {
+  // img.imageBase64 contains the generated image
+}
+```
+
+### Cultural sensitivity inspection
+
+```typescript
+const result = await client.inspectImage("ad_creative.jpg");
+console.log(result.verdict); // "SAFE" or "NOT SAFE"
+for (const issue of result.affectedCountries) {
+  console.log(`${issue.country}: ${issue.issue} → ${issue.suggestion}`);
+}
+```
+
+### Translation memory
+
+```typescript
+// Search
+const matches = await client.searchTm("Sign up", {
+  targetLanguageCode: "fr",
+});
+for (const m of matches) {
+  console.log(`${m.score}% — ${m.sourceText} → ${m.targetText}`);
+}
+
+// Add entry
+await client.addTmEntry(
+  "Sign up",
+  "S'inscrire",
+  "en",
+  "fr-FR",
+  { name: "onboarding CTA" },
+);
+
+// List & filter
+const entries = await client.listTmEntries({
+  targetLanguageCode: "fr-FR",
+  enabledOnly: true,
+});
+console.log(`${entries.total} entries`);
+
+// Stats
+const stats = await client.getTmStats();
+console.log(`${stats.total} total, ${stats.enabled} enabled`);
+```
+
+### Languages
+
+```typescript
+const languages = await client.getLanguages();
+for (const lang of languages) {
+  console.log(`${lang.language} (${lang.languageCode}) — formality: ${lang.formality}`);
+}
+```
+
+### Style guides & brand voice
+
+```typescript
+// List style guides
+const guides = await client.getStyleGuides();
+for (const g of guides) {
+  console.log(`${g.title} — ${g.isEnabled ? "enabled" : "disabled"}`);
+}
+
+// Get brand voice prompt
+const voice = await client.getBrandVoice();
+console.log(voice.prompt);
+
+// Create a style guide
+await client.createStyleGuide(
+  "Tone of Voice",
+  "Always use active voice. Avoid jargon.",
+);
+```
+
+## Error handling
+
+```typescript
+import { Nativ, InsufficientCreditsError, AuthenticationError } from "nativ";
+
+const client = new Nativ();
+
+try {
+  const result = await client.translate("Hello", "French");
+} catch (e) {
+  if (e instanceof AuthenticationError) {
+    console.log("Bad API key");
+  } else if (e instanceof InsufficientCreditsError) {
+    console.log("Top up at dashboard.usenativ.com");
+  }
+}
+```
+
+All exceptions extend `NativError` and carry `statusCode` and `body` properties.
+
+| Exception                  | HTTP | When                          |
+|----------------------------|------|-------------------------------|
+| `AuthenticationError`      | 401  | Invalid or missing API key    |
+| `InsufficientCreditsError` | 402  | Not enough credits            |
+| `ValidationError`          | 400  | Bad request parameters        |
+| `NotFoundError`            | 404  | Resource not found            |
+| `RateLimitError`           | 429  | Too many requests             |
+| `ServerError`              | 5xx  | Nativ API server error        |
+
+## Configuration
+
+```typescript
+const client = new Nativ({
+  apiKey: "nativ_...",            // or NATIV_API_KEY env var
+  baseUrl: "https://...",        // or NATIV_API_URL env var (default: api.usenativ.com)
+  timeout: 120_000,              // request timeout in ms (default: 2 minutes)
+});
+```
+
+## Requirements
+
+- Node.js 18+ (uses native `fetch`)
+- Zero runtime dependencies
+
+## Related packages
+
+- **[nativ](https://pypi.org/project/nativ/)** (Python SDK)
+- **[nativ-mcp](https://pypi.org/project/nativ-mcp/)** — MCP server for Claude, Cursor, etc.
+- **[langchain-nativ](https://pypi.org/project/langchain-nativ/)** — LangChain tool
+
+## License
+
+MIT

package/dist/cjs/client.d.ts

@@ -0,0 +1,114 @@
+import type { BrandVoice, CulturalInspection, FileInput, ImageResult, Language, OCRResult, StyleGuide, TMEntry, TMEntryList, TMSearchMatch, TMStats, TranslateBatchOptions, TranslateOptions, Translation } from "./types.js";
+export interface NativOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Default: 120 000 (2 minutes). */
+    timeout?: number;
+}
+/**
+ * Nativ API client.
+ *
+ * @example
+ * ```ts
+ * import { Nativ } from "nativ";
+ *
+ * const client = new Nativ({ apiKey: "nativ_..." });
+ * const result = await client.translate("Hello world", "French");
+ * console.log(result.translatedText);
+ * ```
+ */
+export declare class Nativ {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    constructor(options?: NativOptions);
+    private request;
+    /**
+     * Translate text with cultural adaptation.
+     *
+     * Uses your translation memory, brand voice, and style guides
+     * automatically.
+     */
+    translate(text: string, targetLanguage: string, options?: TranslateOptions): Promise<Translation>;
+    /**
+     * Translate multiple texts to the same target language.
+     *
+     * Convenience wrapper that calls {@link translate} for each text.
+     */
+    translateBatch(texts: string[], targetLanguage: string, options?: TranslateBatchOptions): Promise<Translation[]>;
+    /** Extract text from an image via OCR. */
+    extractText(image: FileInput): Promise<OCRResult>;
+    /** Generate a culturalized image with styled text. */
+    culturalizeImage(image: FileInput, text: string, languageCode: string, options?: {
+        outputFormat?: string;
+        model?: string;
+        numImages?: number;
+    }): Promise<ImageResult>;
+    /** Check an image for cultural sensitivity issues. */
+    inspectImage(image: FileInput, options?: {
+        countries?: string[];
+    }): Promise<CulturalInspection>;
+    /** Get all languages configured in your Nativ workspace. */
+    getLanguages(): Promise<Language[]>;
+    /** Update the formality setting for a language. */
+    updateLanguageFormality(mappingId: number, formality: string): Promise<boolean>;
+    /** Update the custom style directive for a language. */
+    updateLanguageCustomStyle(mappingId: number, customStyle: string | null): Promise<boolean>;
+    /** Fuzzy-search the translation memory. */
+    searchTm(query: string, options?: {
+        sourceLanguageCode?: string;
+        targetLanguageCode?: string;
+        minScore?: number;
+        limit?: number;
+    }): Promise<TMSearchMatch[]>;
+    /** List translation memory entries with optional filters. */
+    listTmEntries(options?: {
+        sourceLanguageCode?: string;
+        targetLanguageCode?: string;
+        informationSource?: string;
+        search?: string;
+        enabledOnly?: boolean;
+        limit?: number;
+        offset?: number;
+    }): Promise<TMEntryList>;
+    /** Add an entry to the translation memory. */
+    addTmEntry(sourceText: string, targetText: string, sourceLanguageCode: string, targetLanguageCode: string, options?: {
+        name?: string;
+    }): Promise<TMEntry>;
+    /** Update a translation memory entry. */
+    updateTmEntry(entryId: string, update: {
+        targetText?: string;
+        enabled?: boolean;
+    }): Promise<boolean>;
+    /** Delete a translation memory entry. */
+    deleteTmEntry(entryId: string): Promise<boolean>;
+    /** Get translation memory statistics. */
+    getTmStats(): Promise<TMStats>;
+    /** Get all style guides. */
+    getStyleGuides(): Promise<StyleGuide[]>;
+    /** Create a new style guide. */
+    createStyleGuide(title: string, content: string, options?: {
+        isEnabled?: boolean;
+    }): Promise<StyleGuide>;
+    /** Update an existing style guide. */
+    updateStyleGuide(guideId: string, update: {
+        title?: string;
+        content?: string;
+        isEnabled?: boolean;
+    }): Promise<StyleGuide>;
+    /** Delete a style guide. */
+    deleteStyleGuide(guideId: string): Promise<boolean>;
+    /** Get the brand voice prompt. */
+    getBrandVoice(): Promise<BrandVoice>;
+    /** Get the combined prompt (brand voice + style guides). */
+    getCombinedPrompt(): Promise<Record<string, unknown>>;
+    /** Submit feedback on a translation. */
+    submitFeedback(feedback: {
+        source?: string;
+        result?: string;
+        language?: string;
+        feedback?: string;
+        approved?: boolean;
+    }): Promise<Record<string, unknown>>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/cjs/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}