@contentstorage/core 2.2.1 → 3.1.0

package/README.md

@@ -11,11 +11,12 @@ Contentstorage Core is a powerful CLI tool for managing translations and content
 
 ## Features
 
-- **Translation Management** - Pull content from Contentstorage CDN
+- **Translation Management** - Pull and push content to/from Contentstorage
 - **TypeScript Generation** - Automatic type generation from your content
 - **Translation Statistics** - Analyze translation completeness across languages
 - **Multi-Language Support** - Built-in support for 40+ languages
 - **CLI Tools** - Professional command-line interface
+- **API Key Authentication** - Secure project-level API keys for CI/CD integration
 - **Plugin Ecosystem** - Integrate with i18next, react-intl, vue-i18n, and more
 
 ## Installation

package/dist/commands/cli.js

@@ -1,21 +1,37 @@
 #!/usr/bin/env node
 import chalk from 'chalk';
 import { pullContent } from './pull.js';
+import { pushContent } from './push.js';
 import { generateTypes } from './generate-types.js';
 import { showStats } from './stats.js';
+import { captureScreenshot } from './screenshot.js';
 const COMMANDS = {
     pull: {
         name: 'pull',
         description: 'Pull content from Contentstorage CDN',
         usage: 'contentstorage pull [options]',
         options: [
-            '  --content-key <key>    Content key for your project',
+            '  --content-key <key>    Content key (read-only access)',
+            '  --api-key <key>        API key (read + write access)',
+            '  --project-id <id>      Project ID (required with --api-key)',
             '  --content-dir <dir>    Directory to save content files',
             '  --lang <code>          Language code (e.g., EN, FR)',
             '  --pending-changes      Fetch pending/draft content',
             '  --flatten              Output flattened key-value pairs',
         ],
     },
+    push: {
+        name: 'push',
+        description: 'Push local content changes to Contentstorage',
+        usage: 'contentstorage push [options]',
+        options: [
+            '  --api-key <key>        API key for authentication (required)',
+            '  --project-id <id>      Project ID (required)',
+            '  --content-dir <dir>    Directory with content files',
+            '  --lang <code>          Language code to push (e.g., EN)',
+            '  --dry-run              Preview changes without applying',
+        ],
+    },
     'generate-types': {
         name: 'generate-types',
         description: 'Generate TypeScript type definitions from content',
@@ -32,11 +48,22 @@ const COMMANDS = {
         description: 'Show translation completeness statistics',
         usage: 'contentstorage stats [options]',
         options: [
-            '  --content-key <key>    Content key for your project',
+            '  --content-key <key>    Content key (read-only access)',
+            '  --api-key <key>        API key (read + write access)',
+            '  --project-id <id>      Project ID (required with --api-key)',
             '  --content-dir <dir>    Directory with content files',
             '  --pending-changes      Analyze pending/draft content',
         ],
     },
+    screenshot: {
+        name: 'screenshot',
+        description: 'Open browser in live-editor mode for screenshots',
+        usage: 'contentstorage screenshot --url <url> [options]',
+        options: [
+            '  --url <url>            Dev server URL (e.g., http://localhost:3000)',
+            '  --content-key <key>    Content key for your project',
+        ],
+    },
 };
 function showHelp() {
     console.log(chalk.bold('\nContentstorage CLI'));
@@ -93,12 +120,18 @@ async function main() {
         case 'pull':
             await pullContent();
             break;
+        case 'push':
+            await pushContent();
+            break;
         case 'generate-types':
             await generateTypes();
             break;
         case 'stats':
             await showStats();
             break;
+        case 'screenshot':
+            await captureScreenshot();
+            break;
         default:
             console.error(chalk.red(`Unknown command: ${command}\n`));
             console.log(chalk.dim('Run "contentstorage --help" for usage'));

package/dist/commands/pull.js

@@ -4,6 +4,7 @@ import fs from 'fs/promises';
 import path from 'path';
 import chalk from 'chalk';
 import { loadConfig } from '../core/config-loader.js';
+import { createApiClient } from '../core/api-client.js';
 import { CONTENTSTORAGE_CONFIG } from '../utils/constants.js';
 import { flattenJson } from '../utils/flatten-json.js';
 export async function pullContent() {
@@ -31,6 +32,12 @@ export async function pullContent() {
                 else if (key === 'content-dir') {
                     cliConfig.contentDir = value;
                 }
+                else if (key === 'api-key') {
+                    cliConfig.apiKey = value;
+                }
+                else if (key === 'project-id') {
+                    cliConfig.projectId = value;
+                }
                 // Skip the value in the next iteration
                 i++;
             }
@@ -44,18 +51,42 @@ export async function pullContent() {
         console.log(chalk.yellow('Could not load a configuration file. Proceeding with CLI arguments.'));
     }
     const config = { ...fileConfig, ...cliConfig };
-    // Validate required fields
-    if (!config.contentKey) {
-        console.error(chalk.red('Error: Configuration is missing the required "contentKey" property.'));
+    // Check if using API key authentication or contentKey (read-only)
+    const useApiClient = !!(config.apiKey && config.projectId);
+    // Validate required fields based on auth method
+    if (!useApiClient && !config.contentKey) {
+        console.error(chalk.red('Error: Either "contentKey" or "apiKey" + "projectId" is required.\n' +
+            '  Use --content-key for read-only access, or\n' +
+            '  Use --api-key and --project-id for full API access (read + write).'));
         process.exit(1);
     }
     if (!config.contentDir) {
         console.error(chalk.red('Error: Configuration is missing the required "contentDir" property.'));
         process.exit(1);
     }
-    console.log(chalk.blue(`Content key: ${config.contentKey}`));
+    if (useApiClient) {
+        console.log(chalk.blue(`Using API key authentication`));
+        console.log(chalk.blue(`Project ID: ${config.projectId}`));
+    }
+    else {
+        console.log(chalk.blue(`Content key: ${config.contentKey}`));
+    }
     console.log(chalk.blue(`Saving content to: ${config.contentDir}`));
     try {
+        // Create API client if using new authentication
+        const apiClient = useApiClient
+            ? createApiClient({
+                apiKey: config.apiKey,
+                projectId: config.projectId,
+            })
+            : null;
+        // If using API client and no languages specified, fetch from project info
+        if (apiClient && (!config.languageCodes || config.languageCodes.length === 0)) {
+            console.log(chalk.dim('Fetching available languages from project...'));
+            const projectInfo = await apiClient.getProject();
+            config.languageCodes = projectInfo.project.languages;
+            console.log(chalk.blue(`Found languages: ${config.languageCodes.join(', ')}`));
+        }
         // Validate languageCodes array
         if (!Array.isArray(config.languageCodes)) {
             console.log(chalk.red(`Expected array from config.languageCodes, but received type ${typeof config.languageCodes}. Cannot pull files.`));
@@ -67,6 +98,37 @@ export async function pullContent() {
         }
         // Ensure the output directory exists (create it once before the loop)
         await fs.mkdir(config.contentDir, { recursive: true });
+        // Use API client if available
+        if (apiClient) {
+            // Fetch all content at once using new API
+            const format = config.flatten ? 'flat' : 'nested';
+            const draft = config.pendingChanges !== false; // Default to draft
+            console.log(chalk.dim(`\nFetching ${draft ? 'draft' : 'published'} content...`));
+            const response = await apiClient.getContent({
+                format,
+                draft,
+            });
+            // Save each language to a file
+            for (const languageCode of config.languageCodes) {
+                const upperLang = languageCode.toUpperCase();
+                const jsonData = response.data[upperLang];
+                if (!jsonData) {
+                    console.log(chalk.yellow(`\nNo content found for language: ${upperLang}`));
+                    continue;
+                }
+                const filename = `${upperLang}.json`;
+                const outputPath = path.join(config.contentDir, filename);
+                console.log(chalk.blue(`\nProcessing language: ${upperLang}`));
+                await fs.writeFile(outputPath, JSON.stringify(jsonData, null, 2));
+                console.log(chalk.green(`Successfully saved ${outputPath}`));
+            }
+            if (response.metadata.hasPendingChanges) {
+                console.log(chalk.cyan('\n📝 Note: This project has pending changes awaiting publish.'));
+            }
+            console.log(chalk.green('\nAll content successfully pulled and saved.'));
+            return;
+        }
+        // contentKey path: read-only access via CDN/API
         // Process each language code
         for (const languageCode of config.languageCodes) {
             let fileUrl;

package/dist/commands/push.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function pushContent(): Promise<void>;

package/dist/commands/push.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+import fs from 'fs/promises';
+import path from 'path';
+import chalk from 'chalk';
+import { loadConfig } from '../core/config-loader.js';
+import { createApiClient } from '../core/api-client.js';
+export async function pushContent() {
+    console.log(chalk.blue('Starting content push...'));
+    // Parse CLI arguments
+    const args = process.argv.slice(2);
+    const cliConfig = {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg.startsWith('--')) {
+            const key = arg.substring(2);
+            const value = args[i + 1];
+            if (key === 'dry-run') {
+                cliConfig.dryRun = true;
+            }
+            else if (value && !value.startsWith('--')) {
+                if (key === 'lang') {
+                    cliConfig.languageCodes = [value.toUpperCase()];
+                }
+                else if (key === 'api-key') {
+                    cliConfig.apiKey = value;
+                }
+                else if (key === 'project-id') {
+                    cliConfig.projectId = value;
+                }
+                else if (key === 'content-dir') {
+                    cliConfig.contentDir = value;
+                }
+                i++; // Skip the value in next iteration
+            }
+        }
+    }
+    // Load config from file
+    let fileConfig = {};
+    try {
+        fileConfig = await loadConfig();
+    }
+    catch {
+        console.log(chalk.yellow('Could not load a configuration file. Proceeding with CLI arguments.'));
+    }
+    const config = { ...fileConfig, ...cliConfig };
+    // Validate required fields
+    if (!config.apiKey) {
+        console.error(chalk.red('\n❌ Error: API key is required for push.\n' +
+            '   Provide it via config file (apiKey) or --api-key argument.\n' +
+            '   You can create an API key in Project Settings → API Keys.'));
+        process.exit(1);
+    }
+    if (!config.projectId) {
+        console.error(chalk.red('\n❌ Error: Project ID is required for push.\n' +
+            '   Provide it via config file (projectId) or --project-id argument.'));
+        process.exit(1);
+    }
+    if (!config.contentDir) {
+        console.error(chalk.red('\n❌ Error: Content directory is required.\n' +
+            '   Provide it via config file (contentDir) or --content-dir argument.'));
+        process.exit(1);
+    }
+    if (!config.languageCodes || config.languageCodes.length === 0) {
+        console.error(chalk.red('\n❌ Error: At least one language code is required.\n' +
+            '   Provide it via config file (languageCodes) or --lang argument.'));
+        process.exit(1);
+    }
+    // Create API client
+    const apiClient = createApiClient({
+        apiKey: config.apiKey,
+        projectId: config.projectId,
+    });
+    if (!apiClient) {
+        console.error(chalk.red('Failed to create API client'));
+        process.exit(1);
+    }
+    console.log(chalk.blue(`Project ID: ${config.projectId}`));
+    console.log(chalk.blue(`Content directory: ${config.contentDir}`));
+    console.log(chalk.blue(`Languages to push: ${config.languageCodes.join(', ')}`));
+    if (config.dryRun) {
+        console.log(chalk.yellow('\n🔍 Dry run mode - no changes will be made\n'));
+    }
+    try {
+        let totalAdded = 0;
+        let totalUpdated = 0;
+        let totalSkipped = 0;
+        for (const languageCode of config.languageCodes) {
+            const filePath = path.join(config.contentDir, `${languageCode}.json`);
+            console.log(chalk.blue(`\nProcessing ${languageCode}...`));
+            console.log(chalk.dim(`  Reading from: ${filePath}`));
+            // Read the local content file
+            let content;
+            try {
+                const fileContent = await fs.readFile(filePath, 'utf-8');
+                content = JSON.parse(fileContent);
+            }
+            catch (error) {
+                if (error.code === 'ENOENT') {
+                    console.error(chalk.red(`  ❌ File not found: ${filePath}`));
+                    continue;
+                }
+                console.error(chalk.red(`  ❌ Error reading file: ${error.message}`));
+                continue;
+            }
+            // Push to API
+            try {
+                const response = await apiClient.pushContent(languageCode, content, {
+                    dryRun: config.dryRun,
+                });
+                const { result } = response;
+                if (config.dryRun) {
+                    console.log(chalk.cyan(`  📊 Dry run results for ${languageCode}:`));
+                    console.log(chalk.green(`     Keys to add: ${result.keysAdded}`));
+                    console.log(chalk.yellow(`     Keys to update: ${result.keysUpdated}`));
+                    console.log(chalk.dim(`     Keys unchanged: ${result.keysSkipped}`));
+                }
+                else {
+                    console.log(chalk.green(`  ✅ Successfully pushed ${languageCode}`));
+                    console.log(chalk.green(`     Keys added: ${result.keysAdded}`));
+                    console.log(chalk.yellow(`     Keys updated: ${result.keysUpdated}`));
+                    console.log(chalk.dim(`     Keys skipped: ${result.keysSkipped}`));
+                    if (result.pendingChangesCreated) {
+                        console.log(chalk.cyan('     📝 Changes added to pending (publish required)'));
+                    }
+                }
+                totalAdded += result.keysAdded;
+                totalUpdated += result.keysUpdated;
+                totalSkipped += result.keysSkipped;
+            }
+            catch (error) {
+                console.error(chalk.red(`  ❌ Failed to push ${languageCode}: ${error.message}`));
+                throw error;
+            }
+        }
+        // Summary
+        console.log(chalk.bold('\n📊 Summary:'));
+        console.log(chalk.dim('─'.repeat(40)));
+        if (config.dryRun) {
+            console.log(chalk.cyan('  Dry run completed'));
+            console.log(chalk.green(`  Total keys to add: ${totalAdded}`));
+            console.log(chalk.yellow(`  Total keys to update: ${totalUpdated}`));
+            console.log(chalk.dim(`  Total keys unchanged: ${totalSkipped}`));
+            console.log(chalk.dim('\n  Run without --dry-run to apply changes.'));
+        }
+        else {
+            console.log(chalk.green(`  ✅ Push completed successfully`));
+            console.log(chalk.green(`  Total keys added: ${totalAdded}`));
+            console.log(chalk.yellow(`  Total keys updated: ${totalUpdated}`));
+            console.log(chalk.dim(`  Total keys skipped: ${totalSkipped}`));
+        }
+    }
+    catch {
+        console.error(chalk.red('\n❌ Push failed. See errors above.'));
+        process.exit(1);
+    }
+}

package/dist/commands/screenshot.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function captureScreenshot(): Promise<void>;

package/dist/commands/screenshot.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import { exec } from 'child_process';
+import chalk from 'chalk';
+import { loadConfig } from '../core/config-loader.js';
+export async function captureScreenshot() {
+    console.log(chalk.blue('Starting screenshot mode...'));
+    // Parse CLI arguments
+    const config = await parseArguments();
+    // Validate configuration
+    if (!validateConfig(config)) {
+        process.exit(1);
+    }
+    // Build URL with live-editor params
+    const liveEditorUrl = buildLiveEditorUrl(config.url, config.contentKey);
+    console.log(chalk.blue(`Opening browser with live-editor mode...`));
+    console.log(chalk.dim(`URL: ${liveEditorUrl}`));
+    // Open in default browser
+    openInBrowser(liveEditorUrl);
+    console.log(chalk.green('\nBrowser opened successfully!'));
+    console.log(chalk.dim('Use the Contentstorage UI to capture screenshots.'));
+}
+async function parseArguments() {
+    const args = process.argv.slice(2);
+    const cliConfig = {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg.startsWith('--')) {
+            const key = arg.substring(2);
+            const value = args[i + 1];
+            if (value && !value.startsWith('--')) {
+                if (key === 'url') {
+                    cliConfig.url = value;
+                }
+                else if (key === 'content-key') {
+                    cliConfig.contentKey = value;
+                }
+                i++;
+            }
+        }
+    }
+    // Load file config for contentKey fallback
+    let fileConfig = {};
+    try {
+        fileConfig = await loadConfig();
+    }
+    catch {
+        console.log(chalk.yellow('Could not load configuration file. Using CLI arguments only.'));
+    }
+    return {
+        url: cliConfig.url || '',
+        contentKey: cliConfig.contentKey || fileConfig.contentKey,
+    };
+}
+function validateConfig(config) {
+    if (!config.url) {
+        console.error(chalk.red('Error: --url argument is required.'));
+        console.log(chalk.dim('Usage: contentstorage screenshot --url http://localhost:3000'));
+        console.log(chalk.dim('       contentstorage screenshot --url http://localhost:5173'));
+        return false;
+    }
+    try {
+        new URL(config.url);
+    }
+    catch {
+        console.error(chalk.red(`Error: Invalid URL format: ${config.url}`));
+        return false;
+    }
+    if (!config.contentKey) {
+        console.error(chalk.red('Error: content-key is required.'));
+        console.log(chalk.dim('Provide via --content-key or in contentstorage.config.js'));
+        return false;
+    }
+    return true;
+}
+function buildLiveEditorUrl(baseUrl, contentKey) {
+    const url = new URL(baseUrl);
+    url.searchParams.set('contentstorage_live_editor', 'true');
+    url.searchParams.set('screenshot_mode', 'true');
+    if (contentKey) {
+        url.searchParams.set('contentstorage_key', contentKey);
+    }
+    return url.toString();
+}
+function openInBrowser(url) {
+    const platform = process.platform;
+    let command;
+    if (platform === 'darwin') {
+        command = `open "${url}"`;
+    }
+    else if (platform === 'win32') {
+        command = `start "" "${url}"`;
+    }
+    else {
+        command = `xdg-open "${url}"`;
+    }
+    exec(command, (error) => {
+        if (error) {
+            console.error(chalk.red(`Failed to open browser: ${error.message}`));
+            console.log(chalk.yellow(`Please open this URL manually: ${url}`));
+        }
+    });
+}

package/dist/commands/stats.js

@@ -3,6 +3,7 @@ import chalk from 'chalk';
 import { promises as fs } from 'fs';
 import path from 'path';
 import { loadConfig } from '../core/config-loader.js';
+import { createApiClient } from '../core/api-client.js';
 import { flattenJson } from '../utils/flatten-json.js';
 import { CONTENTSTORAGE_CONFIG } from '../utils/constants.js';
 /**
@@ -171,6 +172,70 @@ function displayStats(result) {
     console.log(overallColor(`Overall Completion: ${chalk.bold(result.overallCompletion.toFixed(1) + '%')}`));
     console.log('');
 }
+/**
+ * Display statistics from API response
+ */
+function displayApiStats(response) {
+    const { stats } = response;
+    console.log(chalk.bold('\n📊 Translation Statistics (from API)'));
+    console.log(chalk.dim('═'.repeat(70)));
+    console.log(chalk.cyan(`\nTotal unique content items: ${chalk.bold(stats.totalKeys)}`));
+    // Language statistics table header
+    console.log(chalk.bold('\n📋 Language Statistics:'));
+    console.log(chalk.dim('─'.repeat(70)));
+    // Table header
+    const headerFormat = (str, width) => str.padEnd(width, ' ');
+    console.log(chalk.bold(headerFormat('Language', 12) +
+        headerFormat('Completed', 12) +
+        headerFormat('Total', 10) +
+        'Complete'));
+    console.log(chalk.dim('─'.repeat(70)));
+    // Calculate overall completion
+    let totalCompleted = 0;
+    let totalPossible = 0;
+    // Language rows
+    for (const lang of stats.languages) {
+        const percentageColor = lang.percentage === 100
+            ? chalk.green
+            : lang.percentage >= 80
+                ? chalk.yellow
+                : chalk.red;
+        const percentage = percentageColor(lang.percentage + '%');
+        console.log(chalk.white(headerFormat(lang.code, 12)) +
+            chalk.white(headerFormat(lang.completed.toString(), 12)) +
+            chalk.white(headerFormat(stats.totalKeys.toString(), 10)) +
+            percentage);
+        totalCompleted += lang.completed;
+        totalPossible += stats.totalKeys;
+    }
+    console.log(chalk.dim('─'.repeat(70)));
+    // Pending changes info
+    if (stats.pendingChanges.total > 0) {
+        console.log(chalk.bold('\n📝 Pending Changes:'));
+        console.log(chalk.dim('─'.repeat(70)));
+        console.log(chalk.cyan(`  Total: ${stats.pendingChanges.total}`));
+        if (stats.pendingChanges.added > 0) {
+            console.log(chalk.green(`  Added: ${stats.pendingChanges.added}`));
+        }
+        if (stats.pendingChanges.edited > 0) {
+            console.log(chalk.yellow(`  Edited: ${stats.pendingChanges.edited}`));
+        }
+        if (stats.pendingChanges.removed > 0) {
+            console.log(chalk.red(`  Removed: ${stats.pendingChanges.removed}`));
+        }
+    }
+    // Overall completion
+    console.log(chalk.bold('\n📈 Overall Summary:'));
+    console.log(chalk.dim('─'.repeat(70)));
+    const overallCompletion = totalPossible > 0 ? (totalCompleted / totalPossible) * 100 : 100;
+    const overallColor = overallCompletion === 100
+        ? chalk.green
+        : overallCompletion >= 80
+            ? chalk.yellow
+            : chalk.red;
+    console.log(overallColor(`Overall Completion: ${chalk.bold(overallCompletion.toFixed(1) + '%')}`));
+    console.log('');
+}
 /**
  * Main stats command function
  */
@@ -196,6 +261,12 @@ export async function showStats() {
                         else if (key === 'content-dir') {
                             cliConfig.contentDir = value;
                         }
+                        else if (key === 'api-key') {
+                            cliConfig.apiKey = value;
+                        }
+                        else if (key === 'project-id') {
+                            cliConfig.projectId = value;
+                        }
                         i++; // Skip the value in next iteration
                     }
                 }
@@ -211,11 +282,31 @@ export async function showStats() {
         }
         // Merge configurations (CLI args override file config)
         const config = { ...fileConfig, ...cliConfig };
-        // Validate required fields
-        if (!config.contentKey) {
-            console.error(chalk.red('\n❌ Error: Content key is required. Provide it via config file or --content-key argument.'));
+        // Check if using new API key authentication
+        const useApiClient = !!(config.apiKey && config.projectId);
+        // Validate required fields based on auth method
+        if (!useApiClient && !config.contentKey) {
+            console.error(chalk.red('\n❌ Error: Either "contentKey" or "apiKey" + "projectId" is required.\n' +
+                '   Use --content-key for read-only access, or\n' +
+                '   Use --api-key and --project-id for full API access.'));
             process.exit(1);
         }
+        // If using API client, fetch stats directly from API
+        if (useApiClient) {
+            const apiClient = createApiClient({
+                apiKey: config.apiKey,
+                projectId: config.projectId,
+            });
+            if (!apiClient) {
+                console.error(chalk.red('Failed to create API client'));
+                process.exit(1);
+            }
+            console.log(chalk.blue('Fetching statistics from API...\n'));
+            const apiStats = await apiClient.getStats();
+            displayApiStats(apiStats);
+            return;
+        }
+        // contentKey path: local file analysis or fetch from CDN/API
         if (!config.languageCodes || config.languageCodes.length === 0) {
             console.error(chalk.red('\n❌ Error: At least one language code is required in configuration.'));
             process.exit(1);

package/dist/core/api-client.d.ts

@@ -0,0 +1,105 @@
+/**
+ * API Client for Contentstorage CLI API
+ * Uses API key authentication for project-level access
+ */
+export interface ContentResponse {
+    success: boolean;
+    data: Record<string, Record<string, any>>;
+    metadata: {
+        projectId: string;
+        languages: string[];
+        hasPendingChanges: boolean;
+        format: string;
+        source: 'draft' | 'published';
+    };
+}
+export interface PushResult {
+    keysAdded: number;
+    keysUpdated: number;
+    keysSkipped: number;
+    pendingChangesCreated: boolean;
+    uploadId?: string;
+}
+export interface PushResponse {
+    success: boolean;
+    result: PushResult;
+    dryRun?: boolean;
+}
+export interface ProjectResponse {
+    success: boolean;
+    project: {
+        id: string;
+        name: string;
+        languages: string[];
+        changeTrackingEnabled: boolean;
+        createdAt: string;
+        updatedAt: string;
+    };
+}
+export interface StatsResponse {
+    success: boolean;
+    stats: {
+        totalKeys: number;
+        languages: Array<{
+            code: string;
+            completed: number;
+            percentage: number;
+        }>;
+        pendingChanges: {
+            total: number;
+            added: number;
+            edited: number;
+            removed: number;
+        };
+    };
+}
+export interface ApiError {
+    success: false;
+    error: string;
+    message: string;
+}
+export declare class ApiClient {
+    private client;
+    private projectId;
+    constructor(apiKey: string, projectId: string);
+    /**
+     * Handle API errors consistently
+     */
+    private handleError;
+    /**
+     * Pull content from the API
+     * @param options.languageCode - Optional specific language (returns all if omitted)
+     * @param options.format - 'nested' or 'flat' (default: nested)
+     * @param options.draft - true for draft content, false for published (default: true)
+     */
+    getContent(options?: {
+        languageCode?: string;
+        format?: 'nested' | 'flat';
+        draft?: boolean;
+    }): Promise<ContentResponse>;
+    /**
+     * Push content to the API
+     * @param languageCode - The language code to push
+     * @param content - The content object (nested or flat)
+     * @param options.dryRun - If true, validate only without saving
+     */
+    pushContent(languageCode: string, content: Record<string, any>, options?: {
+        dryRun?: boolean;
+    }): Promise<PushResponse>;
+    /**
+     * Get project information
+     */
+    getProject(): Promise<ProjectResponse>;
+    /**
+     * Get translation statistics
+     */
+    getStats(): Promise<StatsResponse>;
+}
+/**
+ * Create an API client from config
+ * Returns null if API key is not configured
+ */
+export declare function createApiClient(config: {
+    apiKey?: string;
+    projectId?: string;
+}): ApiClient | null;

package/dist/core/api-client.js

@@ -0,0 +1,114 @@
+/**
+ * API Client for Contentstorage CLI API
+ * Uses API key authentication for project-level access
+ */
+import axios from 'axios';
+import { CONTENTSTORAGE_CONFIG } from '../utils/constants.js';
+export class ApiClient {
+    constructor(apiKey, projectId) {
+        this.projectId = projectId;
+        this.client = axios.create({
+            baseURL: `${CONTENTSTORAGE_CONFIG.API_URL}/api/v1/cli`,
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            timeout: 30000,
+        });
+    }
+    /**
+     * Handle API errors consistently
+     */
+    handleError(error) {
+        if (error.response?.data) {
+            const { error: errorCode, message } = error.response.data;
+            throw new Error(`${errorCode}: ${message}`);
+        }
+        if (error.response) {
+            throw new Error(`API error: ${error.response.status} ${error.response.statusText}`);
+        }
+        throw new Error(`Network error: ${error.message}`);
+    }
+    /**
+     * Pull content from the API
+     * @param options.languageCode - Optional specific language (returns all if omitted)
+     * @param options.format - 'nested' or 'flat' (default: nested)
+     * @param options.draft - true for draft content, false for published (default: true)
+     */
+    async getContent(options = {}) {
+        try {
+            const params = new URLSearchParams();
+            params.append('projectId', this.projectId);
+            if (options.languageCode) {
+                params.append('languageCode', options.languageCode);
+            }
+            if (options.format) {
+                params.append('format', options.format);
+            }
+            if (options.draft !== undefined) {
+                params.append('draft', String(options.draft));
+            }
+            const response = await this.client.get(`/content?${params}`);
+            return response.data;
+        }
+        catch (error) {
+            this.handleError(error);
+        }
+    }
+    /**
+     * Push content to the API
+     * @param languageCode - The language code to push
+     * @param content - The content object (nested or flat)
+     * @param options.dryRun - If true, validate only without saving
+     */
+    async pushContent(languageCode, content, options = {}) {
+        try {
+            const response = await this.client.post('/content/push', {
+                projectId: this.projectId,
+                languageCode,
+                content,
+                options: {
+                    dryRun: options.dryRun || false,
+                },
+            });
+            return response.data;
+        }
+        catch (error) {
+            this.handleError(error);
+        }
+    }
+    /**
+     * Get project information
+     */
+    async getProject() {
+        try {
+            const response = await this.client.get(`/projects/${this.projectId}`);
+            return response.data;
+        }
+        catch (error) {
+            this.handleError(error);
+        }
+    }
+    /**
+     * Get translation statistics
+     */
+    async getStats() {
+        try {
+            const response = await this.client.get(`/projects/${this.projectId}/stats`);
+            return response.data;
+        }
+        catch (error) {
+            this.handleError(error);
+        }
+    }
+}
+/**
+ * Create an API client from config
+ * Returns null if API key is not configured
+ */
+export function createApiClient(config) {
+    if (!config.apiKey || !config.projectId) {
+        return null;
+    }
+    return new ApiClient(config.apiKey, config.projectId);
+}

package/dist/core/config-loader.js

@@ -37,6 +37,9 @@ export async function loadConfig() {
         contentKey: mergedConfig.contentKey || '',
         contentDir: path.resolve(process.cwd(), mergedConfig.contentDir),
         typesOutputFile: path.resolve(process.cwd(), mergedConfig.typesOutputFile),
+        // New API key authentication fields
+        apiKey: mergedConfig.apiKey,
+        projectId: mergedConfig.projectId,
     };
     return finalConfig;
 }

package/dist/types.d.ts

@@ -5,6 +5,8 @@ export type AppConfig = {
     typesOutputFile: string;
     pendingChanges?: boolean;
     flatten?: boolean;
+    apiKey?: string;
+    projectId?: string;
 };
 export type LanguageCode = 'SQ' | 'BE' | 'BS' | 'BG' | 'HR' | 'CS' | 'DA' | 'NL' | 'EN' | 'ET' | 'FI' | 'FR' | 'DE' | 'EL' | 'HU' | 'GA' | 'IT' | 'LV' | 'LT' | 'MK' | 'NO' | 'PL' | 'PT' | 'RO' | 'RU' | 'SR' | 'SK' | 'SL' | 'ES' | 'SV' | 'TR' | 'UK';
 /**

package/dist/utils/browser.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Find Chrome executable on the system
+ * @returns Path to Chrome executable or null if not found
+ */
+export declare function findChrome(): string | null;
+/**
+ * Get helpful error message when Chrome is not found
+ */
+export declare function getChromeNotFoundMessage(): string;

package/dist/utils/browser.js

@@ -0,0 +1,58 @@
+import fs from 'fs';
+import path from 'path';
+/**
+ * Common Chrome installation paths by platform
+ */
+const CHROME_PATHS = {
+    darwin: [
+        '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+        '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary',
+        '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    ],
+    win32: [
+        'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+        'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+        process.env.LOCALAPPDATA
+            ? path.join(process.env.LOCALAPPDATA, 'Google\\Chrome\\Application\\chrome.exe')
+            : '',
+    ].filter(Boolean),
+    linux: [
+        '/usr/bin/google-chrome',
+        '/usr/bin/google-chrome-stable',
+        '/usr/bin/chromium',
+        '/usr/bin/chromium-browser',
+        '/snap/bin/chromium',
+    ],
+};
+/**
+ * Find Chrome executable on the system
+ * @returns Path to Chrome executable or null if not found
+ */
+export function findChrome() {
+    const platform = process.platform;
+    const paths = CHROME_PATHS[platform] || [];
+    for (const chromePath of paths) {
+        if (chromePath && fs.existsSync(chromePath)) {
+            return chromePath;
+        }
+    }
+    return null;
+}
+/**
+ * Get helpful error message when Chrome is not found
+ */
+export function getChromeNotFoundMessage() {
+    const platform = process.platform;
+    const installInstructions = {
+        darwin: 'Download from https://www.google.com/chrome/ or install via: brew install --cask google-chrome',
+        win32: 'Download from https://www.google.com/chrome/',
+        linux: 'Install via: sudo apt install google-chrome-stable (Debian/Ubuntu) or sudo dnf install google-chrome-stable (Fedora)',
+    };
+    return `Chrome not found on your system.
+
+Searched locations:
+${(CHROME_PATHS[platform] || []).map((p) => `  - ${p}`).join('\n')}
+
+To install Chrome:
+  ${installInstructions[platform] || 'Download from https://www.google.com/chrome/'}`;
+}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@contentstorage/core",
   "author": "Kaido Hussar <kaido@contentstorage.app>",
   "homepage": "https://contentstorage.app",
-  "version": "2.2.1",
+  "version": "3.1.0",
   "type": "module",
   "description": "Contentstorage CLI for managing translations and generating TypeScript types",
   "license": "MIT",
@@ -23,7 +23,7 @@
     "release": "npx release-it"
   },
   "dependencies": {
-    "axios": "^1.7.2",
+    "axios": "^1.13.2",
     "chalk": "^4.1.2",
     "pluralize": "^8.0.0"
   },