@contentstorage/core 3.0.1 → 3.2.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
@@ -38,13 +39,21 @@ Create `contentstorage.config.js` in your project root:
 
 ```javascript
 export default {
-  contentKey: 'your-content-key',
+  // Option A: Content Key (read-only access)
+  contentKey: 'your-team-id/your-project-id',
+
+  // Option B: API Key (read + write access) - recommended for CI/CD
+  // apiKey: 'csk_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxx',
+  // projectId: 'your-project-uuid',
+
   languageCodes: ['EN', 'FR', 'DE'],
   contentDir: 'src/content/json',
   typesOutputFile: 'src/content/content-types.d.ts'
 };
 ```
 
+> **Note:** Use `contentKey` for read-only access (pull, stats). Use `apiKey` + `projectId` for full access including push operations. API keys can be created in Project Settings → API Keys.
+
 ### 2. Pull Content & Generate Types
 
 ```bash
@@ -85,18 +94,59 @@ npx 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
 
 **Examples:**
 ```bash
-npx contentstorage pull --content-key abc123
+# Using content key (read-only)
+npx contentstorage pull --content-key teamId/projectId
+
+# Using API key (recommended for CI/CD)
+npx contentstorage pull --api-key csk_xxx --project-id uuid
+
+# Pull specific language with draft content
 npx contentstorage pull --lang EN --pending-changes
-npx contentstorage pull --content-dir src/content
 ```
 
+### `contentstorage push`
+
+Push local content changes to Contentstorage (requires API key)
+
+```bash
+npx contentstorage push [options]
+```
+
+**Options:**
+- `--api-key <key>` - API key (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
+
+**Examples:**
+```bash
+# Push all configured languages
+npx contentstorage push --api-key csk_xxx --project-id uuid
+
+# Push specific language
+npx contentstorage push --api-key csk_xxx --project-id uuid --lang EN
+
+# Preview changes without applying
+npx contentstorage push --api-key csk_xxx --project-id uuid --dry-run
+```
+
+**Behavior:**
+- Adds new keys that don't exist in Contentstorage
+- Updates existing keys with different values
+- Never removes keys (safe by design)
+- If change tracking is enabled, creates pending changes for review
+
 ### `contentstorage generate-types`
 
 Generate TypeScript type definitions from content
@@ -126,15 +176,20 @@ npx 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 (fetches stats directly from API)
+- `--project-id <id>` - Project ID (required with --api-key)
 - `--content-dir <dir>` - Directory with content files
 - `--pending-changes` - Analyze pending/draft content
 
 **Examples:**
 ```bash
+# Using local files + content key
 npx contentstorage stats
-npx contentstorage stats --content-key abc123
-npx contentstorage stats --pending-changes
+npx contentstorage stats --content-key teamId/projectId
+
+# Using API key (fetches directly from server)
+npx contentstorage stats --api-key csk_xxx --project-id uuid
 ```
 
 **What it shows:**
@@ -167,8 +222,14 @@ npx contentstorage stats --help
 
 ```javascript
 export default {
-  // Required: Unique content identifier
-  contentKey: 'your-content-key',
+  // Authentication Option A: Content Key (read-only)
+  // Format: teamId/projectId
+  contentKey: 'your-team-id/your-project-id',
+
+  // Authentication Option B: API Key (read + write)
+  // Create in Project Settings → API Keys
+  // apiKey: 'csk_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxx',
+  // projectId: 'your-project-uuid',
 
   // Required: Array of language codes
   languageCodes: ['EN', 'FR', 'DE', 'ES'],
@@ -184,6 +245,17 @@ export default {
 };
 ```
 
+### Authentication Methods
+
+| Method | Access Level | Use Case |
+|--------|-------------|----------|
+| `contentKey` | Read-only | Pull content, view stats |
+| `apiKey` + `projectId` | Read + Write | Pull, push, CI/CD pipelines |
+
+**Getting your credentials:**
+- **Content Key**: Found in Project Settings → General (format: `teamId/projectId`)
+- **API Key**: Create in Project Settings → API Keys
+
 ### Supported Languages
 
 The CLI supports 40+ languages including:

package/dist/commands/cli.js

@@ -1,22 +1,38 @@
 #!/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';
+import { translateContent } from './translate.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',
@@ -33,7 +49,9 @@ 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',
         ],
@@ -47,6 +65,19 @@ const COMMANDS = {
             '  --content-key <key>    Content key for your project',
         ],
     },
+    translate: {
+        name: 'translate',
+        description: 'Push new/changed keys and create a translate session',
+        usage: 'contentstorage translate [options]',
+        options: [
+            '  --api-key <key>        API key for authentication',
+            '  --project-id <id>      Project ID',
+            '  --content-dir <dir>    Directory with content files',
+            '  --lang <code>          Source language code (e.g., EN)',
+            '  --dry-run              Preview changes without pushing',
+            '  -y                     Skip confirmation prompt',
+        ],
+    },
 };
 function showHelp() {
     console.log(chalk.bold('\nContentstorage CLI'));
@@ -103,6 +134,9 @@ async function main() {
         case 'pull':
             await pullContent();
             break;
+        case 'push':
+            await pushContent();
+            break;
         case 'generate-types':
             await generateTypes();
             break;
@@ -112,6 +146,9 @@ async function main() {
         case 'screenshot':
             await captureScreenshot();
             break;
+        case 'translate':
+            await translateContent();
+            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/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/commands/translate.d.ts

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

package/dist/commands/translate.js

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+import fs from 'fs/promises';
+import path from 'path';
+import readline from 'readline';
+import { exec, execSync } from 'child_process';
+import chalk from 'chalk';
+import { loadConfig } from '../core/config-loader.js';
+import { createApiClient } from '../core/api-client.js';
+import { flattenJson } from '../utils/flatten-json.js';
+function prompt(question) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+function getGitBranch() {
+    try {
+        return execSync('git rev-parse --abbrev-ref HEAD', {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+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:\n  ${url}`));
+        }
+    });
+}
+export async function translateContent() {
+    // 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 === '-y') {
+            cliConfig.skipConfirm = true;
+        }
+        else 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('--') && value !== '-y') {
+                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++;
+            }
+        }
+    }
+    // Load config
+    let fileConfig = {};
+    try {
+        fileConfig = await loadConfig();
+    }
+    catch {
+        console.log(chalk.yellow('Could not load configuration file. Using CLI arguments only.'));
+    }
+    const config = { ...fileConfig, ...cliConfig };
+    // Validate required fields
+    if (!config.apiKey) {
+        console.error(chalk.red('\n❌ Error: API key is required.\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.\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);
+    }
+    const sourceLanguage = config.languageCodes[0];
+    // 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);
+    }
+    // Step 1: Read local source file
+    const filePath = path.join(config.contentDir, `${sourceLanguage}.json`);
+    let localContent;
+    try {
+        const fileContent = await fs.readFile(filePath, 'utf-8');
+        localContent = JSON.parse(fileContent);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            console.error(chalk.red(`\n❌ Source file not found: ${filePath}\n` +
+                `   Check your contentDir setting and ensure the file exists.`));
+        }
+        else {
+            console.error(chalk.red(`\n❌ Error reading source file: ${error.message}`));
+        }
+        process.exit(1);
+    }
+    const localFlat = flattenJson(localContent);
+    // Step 2: Fetch server content
+    console.log(chalk.blue('Comparing with server...'));
+    let serverFlat;
+    try {
+        const serverResponse = await apiClient.getContent({
+            languageCode: sourceLanguage,
+            format: 'flat',
+            draft: true,
+        });
+        serverFlat = (serverResponse.data[sourceLanguage] || {});
+    }
+    catch (error) {
+        console.error(chalk.red(`\n❌ Could not fetch server content: ${error.message}`));
+        process.exit(1);
+    }
+    // Step 3: Compute diff
+    const diff = { newKeys: [], modifiedKeys: [] };
+    for (const [key, value] of Object.entries(localFlat)) {
+        const serverValue = serverFlat[key];
+        if (serverValue === undefined) {
+            diff.newKeys.push({ key, value });
+        }
+        else if (serverValue !== value) {
+            diff.modifiedKeys.push({ key, value, oldValue: serverValue });
+        }
+    }
+    const totalChanges = diff.newKeys.length + diff.modifiedKeys.length;
+    if (totalChanges === 0) {
+        console.log(chalk.green('\n✓ All keys are up to date. Nothing to translate.'));
+        process.exit(0);
+    }
+    // Step 4: Display diff
+    const parts = [];
+    if (diff.newKeys.length > 0)
+        parts.push(`${diff.newKeys.length} new`);
+    if (diff.modifiedKeys.length > 0)
+        parts.push(`${diff.modifiedKeys.length} modified`);
+    console.log(chalk.bold(`\nFound ${parts.join(', ')}:\n`));
+    for (const { key, value } of diff.newKeys) {
+        const displayValue = value.length > 50 ? value.substring(0, 47) + '...' : value;
+        console.log(chalk.green(`  + ${key.padEnd(35)} ${chalk.dim(`"${displayValue}"`)}`));
+    }
+    for (const { key, value, oldValue } of diff.modifiedKeys) {
+        const displayOld = oldValue.length > 25 ? oldValue.substring(0, 22) + '...' : oldValue;
+        const displayNew = value.length > 25 ? value.substring(0, 22) + '...' : value;
+        console.log(chalk.yellow(`  ~ ${key.padEnd(35)} ${chalk.dim(`"${displayOld}" → "${displayNew}"`)}`));
+    }
+    // Dry run stops here
+    if (config.dryRun) {
+        console.log(chalk.dim('\n(dry run — nothing was pushed)'));
+        process.exit(0);
+    }
+    // Step 5: Confirm
+    if (!config.skipConfirm) {
+        // Get project name for display
+        let projectName = config.projectId;
+        try {
+            const projectInfo = await apiClient.getProject();
+            projectName = projectInfo.project.name;
+        }
+        catch {
+            // Use projectId as fallback
+        }
+        console.log(chalk.dim(`\nThese will be pushed to Contentstorage (project: ${projectName}).`));
+        const answer = await prompt('Proceed? (Y/n) ');
+        if (answer.toLowerCase() === 'n') {
+            console.log(chalk.dim('Cancelled.'));
+            process.exit(0);
+        }
+    }
+    // Step 6: Push with session
+    const sessionKeys = [
+        ...diff.newKeys.map(({ key, value }) => ({ key, value, status: 'new' })),
+        ...diff.modifiedKeys.map(({ key, value }) => ({ key, value, status: 'modified' })),
+    ];
+    const gitBranch = getGitBranch();
+    try {
+        const response = await apiClient.pushContent(sourceLanguage, localContent, {
+            session: {
+                keys: sessionKeys,
+                metadata: {
+                    ...(gitBranch ? { gitBranch } : {}),
+                    pushedAt: new Date().toISOString(),
+                },
+            },
+        });
+        const { result } = response;
+        const pushed = result.keysAdded + result.keysUpdated;
+        console.log(chalk.green(`\n✓ ${pushed} keys pushed (${result.keysAdded} new, ${result.keysUpdated} modified)`) +
+            (response.session ? chalk.dim(` [session: ${response.session.id}]`) : ''));
+        // Step 7: Open browser
+        if (response.session) {
+            console.log(chalk.bold('\n→ Create task and add visual context:'));
+            console.log(chalk.cyan(`  ${response.session.url}`));
+            openInBrowser(response.session.url);
+        }
+    }
+    catch (error) {
+        console.error(chalk.red(`\n❌ Failed to push keys: ${error.message}`));
+        process.exit(1);
+    }
+}

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

@@ -0,0 +1,122 @@
+/**
+ * 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 TranslateSessionData {
+    keys: Array<{
+        key: string;
+        value: string;
+        status: 'new' | 'modified';
+    }>;
+    metadata?: {
+        gitBranch?: string;
+        pushedAt?: string;
+    };
+}
+export interface TranslateSessionResult {
+    id: string;
+    url: string;
+}
+export interface PushResponse {
+    success: boolean;
+    result: PushResult;
+    dryRun?: boolean;
+    session?: TranslateSessionResult;
+}
+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;
+        session?: TranslateSessionData;
+    }): 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,118 @@
+/**
+ * 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 body = {
+                projectId: this.projectId,
+                languageCode,
+                content,
+                options: {
+                    dryRun: options.dryRun || false,
+                },
+            };
+            if (options.session) {
+                body.session = options.session;
+            }
+            const response = await this.client.post('/content/push', body);
+            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/package.json

@@ -2,7 +2,7 @@
   "name": "@contentstorage/core",
   "author": "Kaido Hussar <kaido@contentstorage.app>",
   "homepage": "https://contentstorage.app",
-  "version": "3.0.1",
+  "version": "3.2.0",
   "type": "module",
   "description": "Contentstorage CLI for managing translations and generating TypeScript types",
   "license": "MIT",