@intlpullhq/cli 0.1.7 → 0.1.9

package/README.md

@@ -19,6 +19,31 @@
 
 ---
 
+## Table of Contents
+
+| Section | Description |
+|---------|-------------|
+| [Features](#features) | Key capabilities of the CLI |
+| [Installation](#installation) | How to install the CLI |
+| [Quick Start](#quick-start) | Get started in 4 commands |
+| [Authentication](#authentication) | Login, API keys, and auth methods |
+| [Commands Reference](#commands-reference) | All available commands |
+| ↳ [Initialize](#initialize-project) | Set up IntlPull in your project |
+| ↳ [Upload / Push](#upload--push) | Upload translation keys |
+| ↳ [Download / Pull](#download--pull) | Download translations |
+| ↳ [Sync](#sync) | One-time sync for CI/CD |
+| ↳ [Listen / Watch](#listen--watch) | Real-time sync during dev |
+| ↳ [Import / Export](#import) | Bulk import/export translations |
+| ↳ [OTA Releases](#ota-releases) | Over-the-air updates |
+| ↳ [Migration](#migration) | Migrate from other platforms |
+| [CI/CD Integration](#cicd-integration) | GitHub Actions, GitLab CI, Docker |
+| [Configuration](#configuration) | Project config and output patterns |
+| ↳ [Output Patterns](#output-patterns-namespace-support) | Namespace file structures |
+| [Tips & Best Practices](#tips--best-practices) | Recommended usage patterns |
+| [Support](#support) | Get help |
+
+---
+
 ## Features
 
 - **Parallel Downloads** - Fetch translations by namespace concurrently for blazing fast syncs
@@ -792,35 +817,54 @@ npx @intlpullhq/cli pull --output "locales/[namespace]/[locale].json"
 
 **Important:** Ensure your i18n library's configuration matches the output path:
 
-- **next-intl**: Update `src/i18n/request.ts` to load from the correct path
-- **i18next / react-i18next**: Update `backend.loadPath` in your i18n config
-- **Chrome Extension**: Must use `_locales/[locale]/messages.json` (Chrome requirement)
-```
+| Library | Config Update Required |
+|---------|----------------------|
+| **next-intl** | Update `src/i18n/request.ts` to load from the correct path |
+| **i18next / react-i18next** | Update `backend.loadPath` in your i18n config |
+| **Chrome Extension** | Must use `_locales/[locale]/messages.json` (Chrome requirement) |
 
 ### Environment Variables
 
 | Variable | Description |
 |----------|-------------|
-| `INTLPULL_API_KEY` | API key for authentication |
-| `INTLPULL_DEBUG` | Enable debug logging |
+| `INTLPULL_API_KEY` | API key for authentication (required) |
+| `INTLPULL_PROJECT_ID` | Default project ID |
+| `INTLPULL_DEBUG` | Enable debug logging (`true`/`false`) |
 
 ---
 
 ## Tips & Best Practices
 
-1. **Use project-scoped API keys** - Auto-detects project ID, no need to specify `--project`
-2. **Enable parallel mode** (default) - Downloads namespaces concurrently for faster syncs
-3. **Use `--quiet` in CI** - Minimal output, machine-friendly
-4. **Use `--dry-run`** - Preview changes before applying
-5. **Set up Git branch detection** - CLI auto-detects git branch for branch workflows
+| Practice | Recommendation |
+|----------|----------------|
+| 🔑 **API Keys** | Use project-scoped keys for auto-detection (no `--project` flag needed) |
+| ⚡ **Parallel Mode** | Enabled by default — downloads namespaces concurrently |
+| 🤫 **CI/CD Output** | Use `--quiet` for minimal, machine-friendly logs |
+| 🔍 **Preview Changes** | Use `--dry-run` before applying destructive operations |
+| 🌿 **Branch Workflows** | CLI auto-detects git branch for branch-based translations |
+| 📦 **Namespace Files** | Use output patterns like `[locale]/[namespace].json` for organized files |
 
 ---
 
 ## Support
 
-- Documentation: [docs.intlpull.com](https://docs.intlpull.com)
-- Email: support@intlpull.com
+| Resource | Link |
+|:---------|:-----|
+| 📚 Documentation | [docs.intlpull.com](https://docs.intlpull.com) |
+| 📧 Email Support | [support@intlpull.com](mailto:support@intlpull.com) |
+| 🐛 GitHub Issues | [github.com/intlpullhq/cli/issues](https://github.com/intlpullhq/cli/issues) |
+| 💬 Discord | [discord.gg/intlpull](https://discord.gg/intlpull) |
+
+---
 
-## License
+<p align="center">
+  <a href="#features">Features</a> •
+  <a href="#installation">Installation</a> •
+  <a href="#commands-reference">Commands</a> •
+  <a href="#cicd-integration">CI/CD</a> •
+  <a href="#configuration">Config</a>
+</p>
 
-MIT © [IntlPull](https://intlpull.com)
+<p align="center">
+  MIT © <a href="https://intlpull.com">IntlPull</a>
+</p>

package/dist/api-77ZWU4IB.js

@@ -0,0 +1,47 @@
+import {
+  ApiClient,
+  ApiKeysApi,
+  BillingApi,
+  ContributorsApi,
+  DocumentsApi,
+  EmailsApi,
+  ImportExportApi,
+  PLAN_LIMITS,
+  SnapshotsApi,
+  TMApi,
+  WebhooksApi,
+  WorkflowsApi,
+  createApiClient
+} from "./chunk-WVCVQFBI.js";
+import {
+  ProjectsApi
+} from "./chunk-KCZQUMQP.js";
+import {
+  TranslationsApi
+} from "./chunk-WSY27J6N.js";
+import {
+  KeysApi
+} from "./chunk-BULIQM4U.js";
+import {
+  BaseApiClient
+} from "./chunk-KIDP7N6D.js";
+import "./chunk-IWYURZV2.js";
+export {
+  ApiClient,
+  ApiKeysApi,
+  BaseApiClient,
+  BillingApi,
+  ContributorsApi,
+  DocumentsApi,
+  EmailsApi,
+  ImportExportApi,
+  KeysApi,
+  PLAN_LIMITS,
+  ProjectsApi,
+  SnapshotsApi,
+  TMApi,
+  TranslationsApi,
+  WebhooksApi,
+  WorkflowsApi,
+  createApiClient
+};

package/dist/chunk-BULIQM4U.js

@@ -0,0 +1,73 @@
+import {
+  BaseApiClient
+} from "./chunk-KIDP7N6D.js";
+
+// src/lib/api/keys.ts
+var KeysApi = class extends BaseApiClient {
+  /**
+   * List translation keys for a project
+   */
+  async listKeys(projectId, options = {}) {
+    const params = new URLSearchParams();
+    if (options.namespace) {
+      params.append("namespace", options.namespace);
+    }
+    if (options.search) {
+      params.append("search", options.search);
+    }
+    if (options.tags && options.tags.length > 0) {
+      params.append("tags", options.tags.join(","));
+    }
+    if (options.limit) {
+      params.append("limit", options.limit.toString());
+    }
+    const query = params.toString();
+    const endpoint = `/api/v1/projects/${projectId}/keys${query ? `?${query}` : ""}`;
+    return this.request(endpoint);
+  }
+  /**
+   * Get a specific translation key
+   */
+  async getKey(projectId, keyId) {
+    return this.request(`/api/v1/projects/${projectId}/keys/${keyId}`);
+  }
+  /**
+   * Create a new translation key
+   */
+  async createKey(projectId, data) {
+    return this.request(`/api/v1/projects/${projectId}/keys`, {
+      method: "POST",
+      body: JSON.stringify(data)
+    });
+  }
+  /**
+   * Update an existing translation key
+   */
+  async updateKey(projectId, keyId, data) {
+    return this.request(`/api/v1/projects/${projectId}/keys/${keyId}`, {
+      method: "PATCH",
+      body: JSON.stringify(data)
+    });
+  }
+  /**
+   * Delete a translation key
+   */
+  async deleteKey(projectId, keyId) {
+    return this.request(`/api/v1/projects/${projectId}/keys/${keyId}`, {
+      method: "DELETE"
+    });
+  }
+  /**
+   * Bulk delete translation keys
+   */
+  async bulkDeleteKeys(projectId, keyIds) {
+    return this.request(`/api/v1/projects/${projectId}/keys/bulk-delete`, {
+      method: "POST",
+      body: JSON.stringify({ key_ids: keyIds })
+    });
+  }
+};
+
+export {
+  KeysApi
+};

package/dist/{chunk-GQADIM7O.js → chunk-IWYURZV2.js}

@@ -1,7 +1,7 @@
 // src/lib/config.ts
 import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync, chmodSync, renameSync } from "fs";
 import { homedir } from "os";
-import { join, dirname } from "path";
+import { join, dirname, resolve, relative } from "path";
 function writeFileAtomic(filePath, content, options) {
   const dir = dirname(filePath);
   if (options?.createDir && !existsSync(dir)) {
@@ -331,7 +331,16 @@ function resolveOutputDir(outputDir, projectRoot) {
   if (outputDir.startsWith("/") || outputDir.match(/^[A-Z]:\\/i)) {
     return outputDir;
   }
-  return join(projectRoot, outputDir);
+  const resolvedPath = resolve(projectRoot, outputDir);
+  const relativePath = relative(projectRoot, resolvedPath);
+  if (relativePath.startsWith("..") || relativePath.includes("/../")) {
+    throw new Error(
+      `Invalid output directory: path traversal detected. Output directory must be within the project directory.
+Project root: ${projectRoot}
+Attempted path: ${outputDir}`
+    );
+  }
+  return resolvedPath;
 }
 function detectGitBranch(dir = process.cwd()) {
   try {

package/dist/chunk-KCZQUMQP.js

@@ -0,0 +1,64 @@
+import {
+  BaseApiClient
+} from "./chunk-KIDP7N6D.js";
+
+// src/lib/api/projects.ts
+var ProjectsApi = class extends BaseApiClient {
+  async listProjects() {
+    return this.request("/api/v1/projects");
+  }
+  async getProject(projectId) {
+    return this.request(`/api/v1/projects/${projectId}`);
+  }
+  async createProject(data) {
+    return this.request("/api/v1/projects", {
+      method: "POST",
+      body: JSON.stringify(data)
+    });
+  }
+  /**
+   * Find a project by name (searches through all projects)
+   */
+  async findProjectByName(name) {
+    const { projects } = await this.listProjects();
+    const normalizedName = name.toLowerCase().trim();
+    return projects.find(
+      (p) => p.name.toLowerCase() === normalizedName || p.slug.toLowerCase() === normalizedName
+    ) || null;
+  }
+  /**
+   * Get project languages/settings
+   */
+  async getProjectLanguages(projectId) {
+    return this.request(`/api/v1/projects/${projectId}/language-settings`);
+  }
+  /**
+   * Add multiple languages to a project with optional skip_translation flag
+   */
+  async addLanguagesBulk(projectId, languages, skipTranslation = false) {
+    return this.request(`/api/v1/projects/${projectId}/language-settings/bulk`, {
+      method: "POST",
+      body: JSON.stringify({
+        languages,
+        skip_translation: skipTranslation
+      })
+    });
+  }
+  // Versions
+  async listVersions(projectId) {
+    return this.request(`/api/v1/projects/${projectId}/versions`);
+  }
+  async createVersion(projectId, data) {
+    return this.request(`/api/v1/projects/${projectId}/versions`, {
+      method: "POST",
+      body: JSON.stringify(data)
+    });
+  }
+  async downloadVersion(projectId, version) {
+    return this.requestBlob(`/api/v1/projects/${projectId}/versions/${version}/download`);
+  }
+};
+
+export {
+  ProjectsApi
+};

package/dist/chunk-KIDP7N6D.js

@@ -0,0 +1,149 @@
+import {
+  getAuthErrorMessage,
+  getGlobalConfig,
+  getResolvedApiKey
+} from "./chunk-IWYURZV2.js";
+
+// src/lib/api/base.ts
+var DEFAULT_API_URL = process.env.INTLPULL_API_URL || "https://api.intlpull.com";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var BaseApiClient = class {
+  baseUrl;
+  apiKey;
+  timeout;
+  constructor() {
+    const globalConfig = getGlobalConfig();
+    this.baseUrl = globalConfig.apiUrl || DEFAULT_API_URL;
+    const resolved = getResolvedApiKey();
+    this.apiKey = resolved?.key || null;
+    this.timeout = DEFAULT_TIMEOUT_MS;
+  }
+  async request(endpoint, options = {}) {
+    if (!this.apiKey) {
+      throw new Error(getAuthErrorMessage());
+    }
+    const url = `${this.baseUrl}${endpoint}`;
+    const headers = {
+      "Content-Type": "application/json",
+      "X-API-Key": this.apiKey,
+      ...options.headers || {}
+    };
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    let response;
+    try {
+      response = await fetch(url, {
+        ...options,
+        headers,
+        signal: controller.signal
+      });
+    } catch (err) {
+      clearTimeout(timeoutId);
+      if (err instanceof Error && err.name === "AbortError") {
+        throw new Error(`Request timeout: Server did not respond within ${this.timeout / 1e3}s`);
+      }
+      if (err instanceof TypeError) {
+        throw new Error(`Network error: Unable to connect to ${this.baseUrl}. Check your internet connection.`);
+      }
+      throw new Error(`Request failed: ${err instanceof Error ? err.message : "Unknown network error"}`);
+    } finally {
+      clearTimeout(timeoutId);
+    }
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ error: `Request failed: ${response.status}` }));
+      throw new Error(error.error || `Request failed: ${response.status}`);
+    }
+    const text = await response.text();
+    if (!text) {
+      return {};
+    }
+    try {
+      return JSON.parse(text);
+    } catch {
+      throw new Error(`Invalid JSON response from API`);
+    }
+  }
+  async requestBlob(endpoint) {
+    if (!this.apiKey) {
+      throw new Error(getAuthErrorMessage());
+    }
+    const url = `${this.baseUrl}${endpoint}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    let response;
+    try {
+      response = await fetch(url, {
+        headers: {
+          "X-API-Key": this.apiKey
+        },
+        signal: controller.signal
+      });
+    } catch (err) {
+      clearTimeout(timeoutId);
+      if (err instanceof Error && err.name === "AbortError") {
+        throw new Error(`Request timeout: Server did not respond within ${this.timeout / 1e3}s`);
+      }
+      if (err instanceof TypeError) {
+        throw new Error(`Network error: Unable to connect to ${this.baseUrl}. Check your internet connection.`);
+      }
+      throw new Error(`Request failed: ${err instanceof Error ? err.message : "Unknown network error"}`);
+    } finally {
+      clearTimeout(timeoutId);
+    }
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ error: "Request failed" }));
+      throw new Error(error.error || "Request failed");
+    }
+    return response.blob();
+  }
+  async requestBlobWithJsonFallback(endpoint) {
+    if (!this.apiKey) {
+      throw new Error(getAuthErrorMessage());
+    }
+    const url = `${this.baseUrl}${endpoint}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    let response;
+    try {
+      response = await fetch(url, {
+        headers: {
+          "X-API-Key": this.apiKey
+        },
+        signal: controller.signal
+      });
+    } catch (err) {
+      clearTimeout(timeoutId);
+      if (err instanceof Error && err.name === "AbortError") {
+        throw new Error(`Request timeout: Server did not respond within ${this.timeout / 1e3}s`);
+      }
+      if (err instanceof TypeError) {
+        throw new Error(`Network error: Unable to connect to ${this.baseUrl}. Check your internet connection.`);
+      }
+      throw new Error(`Request failed: ${err instanceof Error ? err.message : "Unknown network error"}`);
+    } finally {
+      clearTimeout(timeoutId);
+    }
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ error: "Request failed" }));
+      throw new Error(error.error || "Request failed");
+    }
+    const contentType = response.headers.get("content-type") || "";
+    if (contentType.includes("application/json")) {
+      const jsonData = await response.json();
+      if (jsonData.url && typeof jsonData.url === "string") {
+        const fileResponse = await fetch(jsonData.url);
+        if (!fileResponse.ok) {
+          throw new Error(`Failed to download file: ${fileResponse.status}`);
+        }
+        return fileResponse.blob();
+      }
+      const jsonString = JSON.stringify(jsonData, null, 2);
+      return new Blob([jsonString], { type: "application/json" });
+    }
+    return response.blob();
+  }
+};
+
+export {
+  BaseApiClient
+};

package/dist/chunk-WSY27J6N.js

@@ -0,0 +1,116 @@
+import {
+  BaseApiClient
+} from "./chunk-KIDP7N6D.js";
+import {
+  getProjectConfig
+} from "./chunk-IWYURZV2.js";
+
+// src/lib/api/translations.ts
+var TranslationsApi = class extends BaseApiClient {
+  // Keys - uses import endpoint to create/update keys
+  async pushKeys(projectId, keys, language = "en", namespace, options) {
+    const content = {};
+    for (const k of keys) {
+      content[k.key] = k.value;
+    }
+    const fileName = namespace ? `${namespace}.json` : "push.json";
+    const result = await this.request(`/api/v1/projects/${projectId}/import`, {
+      method: "POST",
+      body: JSON.stringify({
+        content: JSON.stringify(content),
+        file_name: fileName,
+        language,
+        options: {
+          namespace_name: namespace || "common",
+          update_existing: true,
+          branch_id: options?.branchId,
+          platforms: options?.platforms
+        }
+      })
+    });
+    return {
+      keys_inserted: result.keys_inserted,
+      keys_updated: result.keys_updated,
+      keys_skipped: result.keys_skipped,
+      translations_inserted: result.translations_inserted,
+      translations_updated: result.translations_updated
+    };
+  }
+  async getKeys(projectId, namespace) {
+    const params = namespace ? `?namespace=${namespace}` : "";
+    return this.request(`/api/v1/projects/${projectId}/keys${params}`);
+  }
+  // Translations - uses export/download endpoint
+  async pullTranslations(projectId, options) {
+    const params = new URLSearchParams();
+    params.set("format", "json");
+    if (options.languages?.length) {
+      options.languages.forEach((lang) => params.append("languages", lang));
+    }
+    if (options.branch) {
+      params.set("branch", options.branch);
+    }
+    if (options.platform) {
+      params.set("platform", options.platform);
+    }
+    return this.request(`/api/v1/projects/${projectId}/export/download?${params.toString()}`);
+  }
+  // Glossary
+  async searchGlossary(query, options) {
+    const params = new URLSearchParams();
+    params.set("q", query);
+    if (options?.limit) params.set("limit", String(options.limit));
+    if (options?.language) params.set("language", options.language);
+    return this.request(`/api/v1/glossary/search?${params.toString()}`);
+  }
+  async addGlossaryTerm(data) {
+    const config = getProjectConfig();
+    if (!config?.projectId) {
+      throw new Error("No project configured. Run `npx @intlpullhq/cli init` first.");
+    }
+    return this.request(`/api/v1/projects/${config.projectId}/glossary`, {
+      method: "POST",
+      body: JSON.stringify(data)
+    });
+  }
+  async exportGlossary(glossaryId) {
+    const config = getProjectConfig();
+    if (!config?.projectId) {
+      throw new Error("No project configured. Run `npx @intlpullhq/cli init` first.");
+    }
+    const params = glossaryId ? `?glossary_id=${glossaryId}` : "";
+    return this.request(`/api/v1/projects/${config.projectId}/glossary/export${params}`);
+  }
+  // Translation Memory
+  async searchTM(data) {
+    const config = getProjectConfig();
+    if (!config?.projectId) {
+      throw new Error("No project configured. Run `npx @intlpullhq/cli init` first.");
+    }
+    return this.request(`/api/v1/projects/${config.projectId}/memory/search`, {
+      method: "POST",
+      body: JSON.stringify(data)
+    });
+  }
+  async addTMEntry(data) {
+    const config = getProjectConfig();
+    if (!config?.projectId) {
+      throw new Error("No project configured. Run `npx @intlpullhq/cli init` first.");
+    }
+    return this.request(`/api/v1/projects/${config.projectId}/memory`, {
+      method: "POST",
+      body: JSON.stringify(data)
+    });
+  }
+  async getTMStats() {
+    const config = getProjectConfig();
+    if (!config?.projectId) {
+      throw new Error("No project configured. Run `npx @intlpullhq/cli init` first.");
+    }
+    return this.request(`/api/v1/projects/${config.projectId}/memory/stats`);
+  }
+};
+
+export {
+  TranslationsApi
+};