@vocoder/cli 0.9.0 → 0.11.0

package/dist/lib.d.mts

@@ -1,3 +1,18 @@
+/**
+ * Supported app industry classifications.
+ * Set once in vocoder.config.ts; synced to ProjectApp at extraction time.
+ * Cannot be edited from the dashboard — config file is the source of truth.
+ *
+ * Keep in sync with APP_INDUSTRIES in
+ * vocoder-app/lib/vocoder/translation/context-constants.ts.
+ */
+type AppIndustry = "ecommerce" | "saas" | "healthcare" | "fintech" | "gaming" | "education" | "media" | "productivity";
+/**
+ * Translation formality level.
+ * Can be set project-wide in vocoder.config.ts or overridden per-string
+ * via <T formality="formal"> (requires allowAiTranslations plan).
+ */
+type Formality = "formal" | "informal" | "neutral";
 interface VocoderConfig {
     /** Glob patterns for files to extract strings from. */
     include?: string[];
@@ -13,6 +28,19 @@ interface VocoderConfig {
      * If set, `vocoder sync` writes {locale}.json files to this path.
      */
     localesPath?: string;
+    /**
+     * The industry or domain of this application.
+     * Used to improve translation quality for domain-specific terminology
+     * and to isolate cache entries by industry in the global translation cache.
+     * Synced to ProjectApp at extraction time.
+     */
+    appIndustry?: AppIndustry;
+    /**
+     * Project-wide default formality level for translations.
+     * Can be overridden per-string via <T formality="..."> on the AI plan.
+     * Synced to ProjectApp at extraction time.
+     */
+    formality?: Formality;
 }
 /** Type helper for vocoder.config.ts — provides autocomplete and type checking. */
 declare function defineConfig(config: VocoderConfig): VocoderConfig;
@@ -37,14 +65,11 @@ interface ExtractedString {
     line: number;
     context?: string;
     formality?: "formal" | "informal" | "neutral" | "auto";
+    /** Detected UI role from JSX parent element or prop. e.g. "button_label", "heading", "input_placeholder" */
+    uiRole?: string;
 }
 declare class StringExtractor {
     extractFromProject(pattern: string | string[], projectRoot?: string, excludePattern?: string | string[]): Promise<ExtractedString[]>;
-    private extractFromFile;
-    private extractPluralSelectICU;
-    private extractTemplateText;
-    private getStringAttribute;
-    private deduplicateStrings;
 }
 
 interface LocaleInfo {
@@ -53,12 +78,22 @@ interface LocaleInfo {
 }
 type LocalesMap = Record<string, LocaleInfo>;
 type EffectiveSyncMode = "required" | "best-effort";
+type RequestedSyncMode = "auto" | EffectiveSyncMode;
 interface SyncPolicyConfig {
     blockingBranches: string[];
     blockingMode: EffectiveSyncMode;
     nonBlockingMode: EffectiveSyncMode;
     defaultMaxWaitMs: number;
 }
+interface RepoIdentityPayload {
+    repoCanonical?: string;
+    repoAppDir?: string;
+    commitSha?: string;
+}
+interface LocalConfig {
+    apiKey: string;
+    apiUrl: string;
+}
 interface APIProjectConfig {
     projectName: string;
     organizationName: string;
@@ -69,6 +104,13 @@ interface APIProjectConfig {
     primaryBranch?: string;
     syncPolicy: SyncPolicyConfig;
 }
+interface TranslationStringEntry {
+    key: string;
+    text: string;
+    context?: string;
+    formality?: "formal" | "informal" | "neutral" | "auto";
+    uiRole?: string;
+}
 interface TranslationBatchResponse {
     batchId: string;
     newStrings: number;
@@ -121,6 +163,38 @@ interface SyncPolicyErrorResponse {
     boundRepoLabel?: string | null;
     boundScopePath?: string | null;
 }
+interface InitStartResponse {
+    sessionId: string;
+    deviceCode: string;
+    verificationUrl: string;
+    expiresAt: string;
+    poll: {
+        token: string;
+        intervalSeconds: number;
+    };
+}
+type InitStatusResponse = {
+    status: "pending";
+    pollIntervalSeconds: number;
+    expiresAt: string;
+    message?: string;
+} | {
+    status: "failed";
+    message: string;
+} | {
+    status: "completed";
+    credentials: {
+        apiKey: string;
+        apiUrl: string;
+        organizationId: string;
+        organizationName: string;
+        projectId: string;
+        projectName: string;
+        sourceLocale: string;
+        targetLocales: string[];
+        targetBranches?: string[];
+    };
+};
 
 type PackageManager = "pnpm" | "npm" | "yarn" | "bun";
 type DetectedFramework = "nextjs" | "vite" | "remix" | "nuxt" | "sveltekit" | "gatsby" | "angular" | null;
@@ -158,6 +232,265 @@ declare function getPackagesToInstall(detection: LocalDetectionResult): {
     runtimePackages: string[];
 };
 
+declare class VocoderAPIError extends Error {
+    readonly status: number;
+    readonly payload: unknown;
+    readonly limitError: LimitErrorResponse | null;
+    readonly syncPolicyError: SyncPolicyErrorResponse | null;
+    constructor(params: {
+        message: string;
+        status: number;
+        payload: unknown;
+        limitError?: LimitErrorResponse | null;
+        syncPolicyError?: SyncPolicyErrorResponse | null;
+    });
+}
+declare class VocoderAPI {
+    private apiUrl;
+    private apiKey;
+    constructor(config: LocalConfig);
+    private request;
+    /**
+     * Fetch project configuration from API
+     * Project is determined from the API key
+     */
+    getProjectConfig(): Promise<APIProjectConfig>;
+    /**
+     * Submit strings for translation
+     * Project is determined from the API key
+     */
+    private stableTextKey;
+    private normalizeStringEntries;
+    submitTranslation(branch: string, entries: string[] | TranslationStringEntry[], targetLocales: string[], options?: {
+        requestedMode?: RequestedSyncMode;
+        requestedMaxWaitMs?: number;
+        clientRunId?: string;
+        force?: boolean;
+        /** From vocoder.config.ts — synced to ProjectApp on every push */
+        appIndustry?: string;
+    }, repoIdentity?: RepoIdentityPayload): Promise<TranslationBatchResponse>;
+    /**
+     * Check translation status
+     */
+    getTranslationStatus(batchId: string): Promise<TranslationStatusResponse>;
+    getTranslationSnapshot(params: {
+        branch: string;
+        targetLocales: string[];
+    }): Promise<TranslationSnapshotResponse>;
+    /**
+     * Wait for translation to complete with polling
+     */
+    waitForCompletion(batchId: string, timeout?: number, onProgress?: (progress: number) => void): Promise<{
+        translations: Record<string, Record<string, string>>;
+        localeMetadata?: Record<string, {
+            nativeName: string;
+            dir?: "rtl";
+        }>;
+    }>;
+    startInitSession(input: {
+        projectName?: string;
+        sourceLocale?: string;
+        targetLocales?: string[];
+        repoCanonical?: string;
+        repoAppDir?: string;
+    }): Promise<InitStartResponse>;
+    getInitSessionStatus(params: {
+        sessionId: string;
+        pollToken: string;
+    }): Promise<InitStatusResponse>;
+    /**
+     * Start a CLI auth session. Returns `{ sessionId, verificationUrl, expiresAt }`.
+     * `sessionId` is the raw poll token — keep it secret, used for polling.
+     */
+    startCliAuthSession(callbackPort?: number, repoCanonical?: string): Promise<{
+        sessionId: string;
+        verificationUrl: string;
+        installUrl?: string;
+        expiresAt: string;
+    }>;
+    /**
+     * Poll for CLI auth session completion.
+     * Returns `{ token }` on success, throws on failure/expiry.
+     * The server returns HTTP 202 while still pending.
+     */
+    pollCliAuthSession(pollToken: string): Promise<{
+        status: "pending";
+    } | {
+        status: "complete";
+        token: string;
+        organizationId?: string;
+    } | {
+        status: "failed";
+        reason: string;
+    }>;
+    /**
+     * Validate a CLI user token and return the authenticated user's info.
+     * Used by the CLI to verify stored credentials on startup.
+     */
+    getCliUserInfo(userToken: string): Promise<{
+        userId: string;
+        email: string;
+        name: string | null;
+    }>;
+    /**
+     * Revoke the given CLI user token server-side.
+     */
+    revokeCliToken(userToken: string): Promise<void>;
+    listWorkspaces(userToken: string, params?: {
+        repo?: string;
+    }): Promise<{
+        workspaces: Array<{
+            id: string;
+            name: string;
+            planId: string;
+            maxProjects: number;
+            projectCount: number;
+            hasGitHubConnection: boolean;
+            connectionLabel: string | null;
+            /** null when no `repo` param was provided */
+            coversRepo: boolean | null;
+            installationConfigureUrl: string | null;
+        }>;
+        canCreateWorkspace: boolean;
+    }>;
+    listProjects(userToken: string, organizationId: string): Promise<Array<{
+        id: string;
+        name: string;
+        sourceLocale: string;
+        targetLocales: string[];
+        targetBranches: string[];
+    }>>;
+    regenerateProjectApiKey(userToken: string, projectId: string): Promise<{
+        apiKey: string;
+    }>;
+    startCliGitHubInstall(userToken: string, params: {
+        organizationId?: string;
+        callbackPort?: number;
+    }): Promise<{
+        installUrl: string;
+    }>;
+    /**
+     * Start the "link existing installation" discovery flow.
+     * Unlike startCliGitHubOAuth, this requires no bearer token — the Vocoder
+     * account is created from the OAuth code in the callback.
+     */
+    startCliGitHubLinkSession(sessionId: string, callbackPort?: number): Promise<{
+        oauthUrl: string;
+    }>;
+    startCliGitHubOAuth(userToken: string, params: {
+        organizationId?: string;
+        callbackPort?: number;
+    }): Promise<{
+        oauthUrl: string;
+    }>;
+    getCliGitHubDiscovery(userToken: string): Promise<{
+        installations: Array<{
+            installationId: number;
+            accountLogin: string;
+            accountType: string;
+            isSuspended: boolean;
+            conflictLabel: string | null;
+        }>;
+    }>;
+    claimCliGitHubInstallation(userToken: string, params: {
+        installationId: string;
+        organizationId: string | null;
+    }): Promise<{
+        organizationId: string;
+        organizationName: string;
+        connectionLabel: string;
+        repoCount: number;
+    }>;
+    listLocales(userToken: string): Promise<{
+        sourceLocales: Array<{
+            code: string;
+            name: string;
+            nativeName?: string;
+        }>;
+        targetLocales: Array<{
+            code: string;
+            name: string;
+            nativeName?: string;
+        }>;
+    }>;
+    listCompatibleLocales(userToken: string, sourceLocale: string): Promise<Array<{
+        code: string;
+        name: string;
+        nativeName?: string;
+    }>>;
+    createProject(userToken: string, params: {
+        organizationId: string;
+        name: string;
+        sourceLocale: string;
+        targetLocales: string[];
+        targetBranches: string[];
+        appDirs: string[];
+        repoCanonical?: string;
+    }): Promise<{
+        projectId: string;
+        projectName: string;
+        apiKey: string;
+        sourceLocale: string;
+        targetLocales: string[];
+        targetBranches: string[];
+        repositoryBound: boolean;
+        configureUrl?: string;
+    }>;
+    /**
+     * Look up all project apps for a given repo. Returns info about exact matches,
+     * existing apps in other scopes, and whether a whole-repo app exists.
+     * No auth required.
+     */
+    lookupProjectByRepo(params: {
+        repoCanonical: string;
+        appDir: string;
+    }): Promise<{
+        exactMatch: {
+            projectId: string;
+            projectName: string;
+            organizationName: string;
+            sourceLocale?: string;
+            targetBranches?: string[];
+        } | null;
+        existingApps: Array<{
+            appDir: string;
+            projectId: string;
+            projectName: string;
+            organizationName: string;
+        }>;
+        hasWholeRepoApp: boolean;
+    }>;
+    /**
+     * Add a new ProjectApp to an existing project (monorepo: new app directory).
+     * Does not check plan limits — no new project is created.
+     */
+    createProjectApp(userToken: string, params: {
+        projectId: string;
+        appDir: string;
+        sourceLocale: string;
+        targetLocales: string[];
+        targetBranches: string[];
+        repoCanonical: string;
+    }): Promise<{
+        appId: string;
+        projectId: string;
+        projectName: string;
+        apiKey: string;
+        appDir: string;
+    }>;
+}
+
+interface AuthData {
+    token: string;
+    userId: string;
+    email: string;
+    name: string | null;
+    createdAt: string;
+}
+declare function readAuthData(): AuthData | null;
+declare function writeAuthData(data: AuthData): void;
+declare function clearAuthData(): void;
+
 interface SetupSnippets {
     pluginStep: {
         file: string;
@@ -182,4 +515,4 @@ declare function getSetupSnippets(params: {
     targetBranches: string[];
 }): SetupSnippets;
 
-export { type APIProjectConfig, type DetectedEcosystem, type DetectedFramework, type ExtractedString, type LimitErrorResponse, type LocalDetectionResult, type LocaleInfo, type LocalesMap, type PackageManager, type SetupSnippets, StringExtractor, type SyncPolicyConfig, type SyncPolicyErrorResponse, type TranslationBatchResponse, type TranslationSnapshotResponse, type TranslationStatusResponse, type VocoderConfig, buildInstallCommand, defineConfig, detectLocalEcosystem, getPackagesToInstall, getSetupSnippets, loadVocoderConfig };
+export { type APIProjectConfig, type AuthData, type DetectedEcosystem, type DetectedFramework, type ExtractedString, type LimitErrorResponse, type LocalDetectionResult, type LocaleInfo, type LocalesMap, type PackageManager, type SetupSnippets, StringExtractor, type SyncPolicyConfig, type SyncPolicyErrorResponse, type TranslationBatchResponse, type TranslationSnapshotResponse, type TranslationStatusResponse, VocoderAPI, VocoderAPIError, type VocoderConfig, buildInstallCommand, clearAuthData, defineConfig, detectLocalEcosystem, getPackagesToInstall, getSetupSnippets, loadVocoderConfig, readAuthData, writeAuthData };

package/dist/lib.mjs

@@ -1,12 +1,17 @@
 import { createRequire as __createRequire } from 'module'; const require = __createRequire(import.meta.url);
 import {
   StringExtractor,
+  VocoderAPI,
+  VocoderAPIError,
   buildInstallCommand,
+  clearAuthData,
   detectLocalEcosystem,
   getPackagesToInstall,
   getSetupSnippets,
-  loadVocoderConfig
-} from "./chunk-IZN5HVYD.mjs";
+  loadVocoderConfig,
+  readAuthData,
+  writeAuthData
+} from "./chunk-XF3KGGYQ.mjs";
 
 // ../config/src/index.ts
 function defineConfig(config) {
@@ -14,11 +19,16 @@ function defineConfig(config) {
 }
 export {
   StringExtractor,
+  VocoderAPI,
+  VocoderAPIError,
   buildInstallCommand,
+  clearAuthData,
   defineConfig,
   detectLocalEcosystem,
   getPackagesToInstall,
   getSetupSnippets,
-  loadVocoderConfig
+  loadVocoderConfig,
+  readAuthData,
+  writeAuthData
 };
 //# sourceMappingURL=lib.mjs.map

package/dist/lib.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../config/src/index.ts"],"sourcesContent":["export interface VocoderConfig {\n\t/** Glob patterns for files to extract strings from. */\n\tinclude?: string[];\n\t/** Glob patterns to exclude. */\n\texclude?: string[];\n\t/**\n\t * Git branches that trigger string extraction and translation.\n\t * Synced to the Vocoder dashboard on each push — change here to update.\n\t */\n\ttargetBranches?: string[];\n\t/**\n\t * Directory to write translated locale files after sync (optional).\n\t * If set, `vocoder sync` writes {locale}.json files to this path.\n\t */\n\tlocalesPath?: string;\n}\n\n/** Type helper for vocoder.config.ts — provides autocomplete and type checking. */\nexport function defineConfig(config: VocoderConfig): VocoderConfig {\n\treturn config;\n}\n\n/**\n * Canonical translation bundle format shared by the build plugin and CLI.\n * Both read and write this shape — keeps cache files identical regardless of\n * which tool produced them.\n *\n * translations: locale → sourceKey (hash) → translated text\n * config.locales: locale metadata snapshot for the runtime\n */\nexport interface VocoderTranslationData {\n\tconfig: {\n\t\tsourceLocale: string;\n\t\ttargetLocales: string[];\n\t\tlocales: Record<string, {\n\t\t\tnativeName: string;\n\t\t\tdir?: \"rtl\";\n\t\t\tcurrencyCode?: string;\n\t\t\tordinalForms?: { type: \"suffix\"; suffixes: { zero?: string; one?: string; two?: string; few?: string; many?: string; other: string } } | { type: \"word\"; words: Record<string, Record<number, string>> };\n\t\t}>;\n\t};\n\ttranslations: Record<string, Record<string, string>>;\n\tupdatedAt: string | null;\n}\n"],"mappings":";;;;;;;;;;;AAkBO,SAAS,aAAa,QAAsC;AAClE,SAAO;AACR;","names":[]}
+{"version":3,"sources":["../../config/src/index.ts"],"sourcesContent":["/**\n * Supported app industry classifications.\n * Set once in vocoder.config.ts; synced to ProjectApp at extraction time.\n * Cannot be edited from the dashboard — config file is the source of truth.\n *\n * Keep in sync with APP_INDUSTRIES in\n * vocoder-app/lib/vocoder/translation/context-constants.ts.\n */\nexport type AppIndustry =\n\t| \"ecommerce\"\n\t| \"saas\"\n\t| \"healthcare\"\n\t| \"fintech\"\n\t| \"gaming\"\n\t| \"education\"\n\t| \"media\"\n\t| \"productivity\";\n\n/**\n * Translation formality level.\n * Can be set project-wide in vocoder.config.ts or overridden per-string\n * via <T formality=\"formal\"> (requires allowAiTranslations plan).\n */\nexport type Formality = \"formal\" | \"informal\" | \"neutral\";\n\nexport interface VocoderConfig {\n\t/** Glob patterns for files to extract strings from. */\n\tinclude?: string[];\n\t/** Glob patterns to exclude. */\n\texclude?: string[];\n\t/**\n\t * Git branches that trigger string extraction and translation.\n\t * Synced to the Vocoder dashboard on each push — change here to update.\n\t */\n\ttargetBranches?: string[];\n\t/**\n\t * Directory to write translated locale files after sync (optional).\n\t * If set, `vocoder sync` writes {locale}.json files to this path.\n\t */\n\tlocalesPath?: string;\n\t/**\n\t * The industry or domain of this application.\n\t * Used to improve translation quality for domain-specific terminology\n\t * and to isolate cache entries by industry in the global translation cache.\n\t * Synced to ProjectApp at extraction time.\n\t */\n\tappIndustry?: AppIndustry;\n\t/**\n\t * Project-wide default formality level for translations.\n\t * Can be overridden per-string via <T formality=\"...\"> on the AI plan.\n\t * Synced to ProjectApp at extraction time.\n\t */\n\tformality?: Formality;\n}\n\n/** Type helper for vocoder.config.ts — provides autocomplete and type checking. */\nexport function defineConfig(config: VocoderConfig): VocoderConfig {\n\treturn config;\n}\n\n/**\n * Canonical translation bundle format shared by the build plugin and CLI.\n * Both read and write this shape — keeps cache files identical regardless of\n * which tool produced them.\n *\n * translations: locale → sourceKey (hash) → translated text\n * config.locales: locale metadata snapshot for the runtime\n */\nexport interface VocoderTranslationData {\n\tconfig: {\n\t\tsourceLocale: string;\n\t\ttargetLocales: string[];\n\t\tlocales: Record<string, {\n\t\t\tnativeName: string;\n\t\t\tdir?: \"rtl\";\n\t\t\tcurrencyCode?: string;\n\t\t\tordinalForms?: { type: \"suffix\"; suffixes: { zero?: string; one?: string; two?: string; few?: string; many?: string; other: string } } | { type: \"word\"; words: Record<string, Record<number, string>> };\n\t\t}>;\n\t};\n\ttranslations: Record<string, Record<string, string>>;\n\tupdatedAt: string | null;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAwDO,SAAS,aAAa,QAAsC;AAClE,SAAO;AACR;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vocoder/cli",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "CLI tool for Vocoder translation workflow",
   "files": [
     "dist"
@@ -51,8 +51,8 @@
     "tsup": "^8.0.0",
     "typescript": "^5.4.0",
     "vitest": "^1.0.0",
-    "@vocoder/config": "0.9.0",
-    "@vocoder/extractor": "0.9.0"
+    "@vocoder/extractor": "0.11.0",
+    "@vocoder/config": "0.11.0"
   },
   "engines": {
     "node": ">=18"