@contentstorage/core 3.1.0 → 3.2.1

package/README.md

@@ -39,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
@@ -86,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
@@ -127,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:**
@@ -168,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'],
@@ -185,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

@@ -5,6 +5,7 @@ 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',
@@ -14,6 +15,7 @@ const COMMANDS = {
             '  --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)',
+            '  --api-url <url>        API base URL (default: production)',
             '  --content-dir <dir>    Directory to save content files',
             '  --lang <code>          Language code (e.g., EN, FR)',
             '  --pending-changes      Fetch pending/draft content',
@@ -27,6 +29,7 @@ const COMMANDS = {
         options: [
             '  --api-key <key>        API key for authentication (required)',
             '  --project-id <id>      Project ID (required)',
+            '  --api-url <url>        API base URL (default: production)',
             '  --content-dir <dir>    Directory with content files',
             '  --lang <code>          Language code to push (e.g., EN)',
             '  --dry-run              Preview changes without applying',
@@ -51,6 +54,7 @@ const COMMANDS = {
             '  --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)',
+            '  --api-url <url>        API base URL (default: production)',
             '  --content-dir <dir>    Directory with content files',
             '  --pending-changes      Analyze pending/draft content',
         ],
@@ -64,6 +68,20 @@ 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',
+            '  --api-url <url>        API base URL (default: production)',
+            '  --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'));
@@ -132,6 +150,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

@@ -38,6 +38,9 @@ export async function pullContent() {
                 else if (key === 'project-id') {
                     cliConfig.projectId = value;
                 }
+                else if (key === 'api-url') {
+                    cliConfig.apiUrl = value;
+                }
                 // Skip the value in the next iteration
                 i++;
             }
@@ -78,6 +81,7 @@ export async function pullContent() {
             ? createApiClient({
                 apiKey: config.apiKey,
                 projectId: config.projectId,
+                apiUrl: config.apiUrl,
             })
             : null;
         // If using API client and no languages specified, fetch from project info

package/dist/commands/push.js

@@ -30,6 +30,9 @@ export async function pushContent() {
                 else if (key === 'content-dir') {
                     cliConfig.contentDir = value;
                 }
+                else if (key === 'api-url') {
+                    cliConfig.apiUrl = value;
+                }
                 i++; // Skip the value in next iteration
             }
         }
@@ -69,6 +72,7 @@ export async function pushContent() {
     const apiClient = createApiClient({
         apiKey: config.apiKey,
         projectId: config.projectId,
+        apiUrl: config.apiUrl,
     });
     if (!apiClient) {
         console.error(chalk.red('Failed to create API client'));

package/dist/commands/stats.js

@@ -267,6 +267,9 @@ export async function showStats() {
                         else if (key === 'project-id') {
                             cliConfig.projectId = value;
                         }
+                        else if (key === 'api-url') {
+                            cliConfig.apiUrl = value;
+                        }
                         i++; // Skip the value in next iteration
                     }
                 }
@@ -296,6 +299,7 @@ export async function showStats() {
             const apiClient = createApiClient({
                 apiKey: config.apiKey,
                 projectId: config.projectId,
+                apiUrl: config.apiUrl,
             });
             if (!apiClient) {
                 console.error(chalk.red('Failed to create API client'));

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,251 @@
+#!/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;
+                }
+                else if (key === 'api-url') {
+                    cliConfig.apiUrl = 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,
+        apiUrl: config.apiUrl,
+    });
+    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: Show session URL and ask before opening browser
+        if (response.session) {
+            console.log(chalk.bold('\n→ Translate session created:'));
+            console.log(chalk.cyan(`  ${response.session.url}`));
+            const openAnswer = await prompt('Open in browser? (Y/n) ');
+            if (openAnswer.toLowerCase() !== 'n') {
+                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

@@ -20,10 +20,26 @@ export interface PushResult {
     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;
@@ -61,7 +77,7 @@ export interface ApiError {
 export declare class ApiClient {
     private client;
     private projectId;
-    constructor(apiKey: string, projectId: string);
+    constructor(apiKey: string, projectId: string, apiUrl?: string);
     /**
      * Handle API errors consistently
      */
@@ -85,6 +101,7 @@ export declare class ApiClient {
      */
     pushContent(languageCode: string, content: Record<string, any>, options?: {
         dryRun?: boolean;
+        session?: TranslateSessionData;
     }): Promise<PushResponse>;
     /**
      * Get project information
@@ -102,4 +119,5 @@ export declare class ApiClient {
 export declare function createApiClient(config: {
     apiKey?: string;
     projectId?: string;
+    apiUrl?: string;
 }): ApiClient | null;

package/dist/core/api-client.js

@@ -5,10 +5,11 @@
 import axios from 'axios';
 import { CONTENTSTORAGE_CONFIG } from '../utils/constants.js';
 export class ApiClient {
-    constructor(apiKey, projectId) {
+    constructor(apiKey, projectId, apiUrl) {
         this.projectId = projectId;
+        const baseApiUrl = apiUrl || CONTENTSTORAGE_CONFIG.API_URL;
         this.client = axios.create({
-            baseURL: `${CONTENTSTORAGE_CONFIG.API_URL}/api/v1/cli`,
+            baseURL: `${baseApiUrl}/api/v1/cli`,
             headers: {
                 Authorization: `Bearer ${apiKey}`,
                 'Content-Type': 'application/json',
@@ -63,14 +64,18 @@ export class ApiClient {
      */
     async pushContent(languageCode, content, options = {}) {
         try {
-            const response = await this.client.post('/content/push', {
+            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) {
@@ -110,5 +115,5 @@ export function createApiClient(config) {
     if (!config.apiKey || !config.projectId) {
         return null;
     }
-    return new ApiClient(config.apiKey, config.projectId);
+    return new ApiClient(config.apiKey, config.projectId, config.apiUrl);
 }

package/dist/core/config-loader.js

@@ -40,6 +40,7 @@ export async function loadConfig() {
         // New API key authentication fields
         apiKey: mergedConfig.apiKey,
         projectId: mergedConfig.projectId,
+        apiUrl: process.env.CONTENTSTORAGE_API_URL || mergedConfig.apiUrl,
     };
     return finalConfig;
 }

package/dist/types.d.ts

@@ -7,6 +7,7 @@ export type AppConfig = {
     flatten?: boolean;
     apiKey?: string;
     projectId?: string;
+    apiUrl?: 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.1.0",
+  "version": "3.2.1",
   "type": "module",
   "description": "Contentstorage CLI for managing translations and generating TypeScript types",
   "license": "MIT",