@contentstorage/core 1.1.1 → 1.2.0

package/README.md

@@ -1 +1,349 @@
-# contentstorage-core
+# @contentstorage/core
+
+> A key-value based CMS core library that fetches content from ContentStorage and generates TypeScript types
+
+[![npm version](https://img.shields.io/npm/v/@contentstorage/core.svg)](https://www.npmjs.com/package/@contentstorage/core)
+[![License](https://img.shields.io/npm/l/@contentstorage/core.svg)](https://github.com/kaidohussar/contentstorage-core/blob/master/LICENSE)
+
+## Features
+
+- **Key-Value Storage** - Organize content with hierarchical dot-notation paths
+- **Multi-Language Support** - Built-in support for 40+ languages
+- **TypeScript First** - Automatic type generation from your content
+- **Type Safety** - Full autocompletion and type checking for content access
+- **Live Editor Integration** - Real-time content editing without page reload
+- **Special Content Types** - Support for text, images, and variations
+- **Variable Substitution** - Dynamic content with template variables
+- **CLI Tools** - Easy content management with professional CLI
+
+## Installation
+
+```bash
+npm install @contentstorage/core
+```
+
+or
+
+```bash
+yarn add @contentstorage/core
+```
+
+## Quick Start
+
+### 1. Create Configuration File
+
+Create `contentstorage.config.js` in your project root:
+
+```javascript
+export default {
+  contentKey: 'your-content-key',
+  languageCodes: ['EN', 'FR', 'DE'],
+  contentDir: 'src/content/json',
+  typesOutputFile: 'src/content/content-types.d.ts'
+};
+```
+
+### 2. Pull Content & Generate Types
+
+```bash
+# Pull content from ContentStorage CDN
+npx contentstorage pull
+
+# Generate TypeScript type definitions
+npx contentstorage generate-types
+```
+
+### 3. Initialize and Use in Your App
+
+```typescript
+import { initContentStorage, fetchContent, getText, getImage } from '@contentstorage/core';
+
+// Initialize
+initContentStorage({
+  contentKey: 'your-content-key',
+  languageCodes: ['EN', 'FR', 'DE']
+});
+
+// Fetch content for a language
+await fetchContent('EN');
+
+// Access content with full type safety
+const title = getText('HomePage.title');
+// → { contentId: 'HomePage.title', text: 'Welcome!' }
+
+const heroImage = getImage('HomePage.hero');
+// → { contentId: 'HomePage.hero', data: { url: '...', altText: '...' } }
+
+// Use variables in text
+const greeting = getText('HomePage.greeting', { name: 'John' });
+// → { contentId: 'HomePage.greeting', text: 'Hello John!' }
+```
+
+## CLI Commands
+
+### `contentstorage pull`
+
+Pull content from ContentStorage CDN
+
+```bash
+npx contentstorage pull [options]
+```
+
+**Options:**
+- `--content-key <key>` - Content key for your project
+- `--content-dir <dir>` - Directory to save content files
+- `--lang <code>` - Language code (e.g., EN, FR)
+- `--pending-changes` - Fetch pending/draft content
+
+**Examples:**
+```bash
+npx contentstorage pull --content-key abc123
+npx contentstorage pull --lang EN --pending-changes
+npx contentstorage pull --content-dir src/content
+```
+
+### `contentstorage generate-types`
+
+Generate TypeScript type definitions from content
+
+```bash
+npx contentstorage generate-types [options]
+```
+
+**Options:**
+- `--output <file>` - Output file for generated types
+- `--content-key <key>` - Content key for your project
+- `--lang <code>` - Language code (e.g., EN, FR)
+- `--pending-changes` - Use pending/draft content
+
+**Examples:**
+```bash
+npx contentstorage generate-types --output src/types.ts
+npx contentstorage generate-types --content-key abc123 --lang EN
+```
+
+### `contentstorage --help`
+
+Show all available commands and options
+
+```bash
+npx contentstorage --help
+npx contentstorage pull --help
+npx contentstorage generate-types --help
+```
+
+## Configuration
+
+### Configuration File (`contentstorage.config.js`)
+
+```javascript
+export default {
+  // Required: Unique content identifier
+  contentKey: 'your-content-key',
+
+  // Required: Array of language codes
+  languageCodes: ['EN', 'FR', 'DE', 'ES'],
+
+  // Optional: Local storage path (default: src/content/json)
+  contentDir: 'src/content/json',
+
+  // Optional: Types file path (default: src/content/content-types.ts)
+  typesOutputFile: 'src/content/content-types.d.ts',
+
+  // Optional: Fetch draft content
+  pendingChanges: false
+};
+```
+
+### Supported Languages
+
+The library supports 40+ languages including:
+EN, FR, DE, ES, IT, PT, NL, PL, RU, TR, SV, NO, DA, FI, CS, SK, HU, RO, BG, HR, SL, SR, and more.
+
+## API Reference
+
+### Initialization
+
+#### `initContentStorage(config)`
+
+Initialize the content storage system.
+
+```typescript
+initContentStorage({
+  contentKey: string,
+  languageCodes: LanguageCode[]
+});
+```
+
+#### `setContentLanguage(config)`
+
+Set content for a specific language.
+
+```typescript
+setContentLanguage({
+  languageCode: LanguageCode,
+  contentJson: object
+});
+```
+
+### Content Retrieval
+
+#### `getText<Path>(contentId, variables?)`
+
+Get localized text with optional variable substitution.
+
+```typescript
+const result = getText('HomePage.title');
+// → { contentId: 'HomePage.title', text: 'Welcome!' }
+
+const greeting = getText('HomePage.greeting', { name: 'John', count: 5 });
+// → { contentId: 'HomePage.greeting', text: 'Hello John, you have 5 items' }
+```
+
+**Returns:** `{ contentId: string, text: string }`
+
+#### `getImage(contentId)`
+
+Get image content with CDN URL.
+
+```typescript
+const image = getImage('HomePage.hero');
+// → {
+//     contentId: 'HomePage.hero',
+//     data: {
+//       contentstorage_type: 'image',
+//       url: 'https://cdn.contentstorage.app/...',
+//       altText: 'Hero image'
+//     }
+//   }
+```
+
+**Returns:** `{ contentId: string, data: ImageObject } | undefined`
+
+#### `getVariation(contentId, variationKey?, variables?)`
+
+Get content variation for A/B testing.
+
+```typescript
+const cta = getVariation('HomePage.cta', 'mobile');
+// → { contentId: 'HomePage.cta', text: 'Tap Now' }
+
+// Defaults to 'default' variation if not specified
+const ctaDefault = getVariation('HomePage.cta');
+```
+
+**Returns:** `{ contentId: string, text: string }`
+
+### Content Fetching
+
+#### `fetchContent(languageCode)`
+
+Fetch content from ContentStorage CDN.
+
+```typescript
+await fetchContent('EN');
+```
+
+## TypeScript Integration
+
+The library uses interface augmentation for type-safe content access:
+
+```typescript
+// After running: npx contentstorage generate-types
+// The generated types augment the ContentStructure interface
+
+import { getText } from '@contentstorage/core';
+
+// TypeScript knows all available content paths
+const title = getText('HomePage.title'); // ✅ Autocomplete works
+const invalid = getText('Invalid.path'); // ❌ TypeScript error
+```
+
+## Content Structure
+
+Content is organized in a hierarchical key-value structure:
+
+```json
+{
+  "HomePage": {
+    "title": "Welcome to Our App",
+    "greeting": "Hello {name}, you have {count} items",
+    "hero": {
+      "contentstorage_type": "image",
+      "url": "hero.jpg",
+      "altText": "Hero image"
+    },
+    "cta": {
+      "contentstorage_type": "variation",
+      "data": {
+        "default": "Click Here",
+        "mobile": "Tap Now",
+        "desktop": "Click to Continue"
+      }
+    }
+  }
+}
+```
+
+**Access with dot notation:**
+- `getText('HomePage.title')` → "Welcome to Our App"
+- `getText('HomePage.greeting', { name: 'John', count: 5 })` → "Hello John, you have 5 items"
+- `getImage('HomePage.hero')` → Image object with CDN URL
+- `getVariation('HomePage.cta', 'mobile')` → "Tap Now"
+
+## Package.json Scripts
+
+Add these scripts to your `package.json` for convenience:
+
+```json
+{
+  "scripts": {
+    "content:pull": "contentstorage pull",
+    "content:types": "contentstorage generate-types",
+    "content:sync": "npm run content:pull && npm run content:types",
+    "prebuild": "npm run content:sync"
+  }
+}
+```
+
+Then run:
+
+```bash
+npm run content:pull    # Pull content
+npm run content:types   # Generate types
+npm run content:sync    # Pull and generate in one command
+```
+
+## Integration with React
+
+For React integration, use [@contentstorage/react](https://www.npmjs.com/package/@contentstorage/react) which builds on top of this core library and provides React-specific components and hooks.
+
+## Live Editor Mode
+
+When running in an iframe with live editor parameters, the library automatically:
+- Loads the live editor script from CDN
+- Tracks content usage via `window.memoryMap`
+- Enables real-time content updates without page reload
+
+## Requirements
+
+- Node.js >= 18.0.0
+- TypeScript >= 5.0.0 (for type generation)
+
+## License
+
+MIT
+
+## Author
+
+Kaido Hussar - [kaidohus@gmail.com](mailto:kaidohus@gmail.com)
+
+## Links
+
+- [Homepage](https://contentstorage.app)
+- [GitHub](https://github.com/kaidohussar/contentstorage-core)
+- [npm](https://www.npmjs.com/package/@contentstorage/core)
+
+## Support
+
+For issues and questions, please [open an issue](https://github.com/kaidohussar/contentstorage-core/issues) on GitHub.

package/dist/scripts/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/scripts/cli.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import chalk from 'chalk';
+import { pullContent } from './pull-content.js';
+import { generateTypes } from './generate-types.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-dir <dir>    Directory to save content files',
+            '  --lang <code>          Language code (e.g., EN, FR)',
+            '  --pending-changes      Fetch pending/draft content',
+        ],
+    },
+    'generate-types': {
+        name: 'generate-types',
+        description: 'Generate TypeScript type definitions from content',
+        usage: 'contentstorage generate-types [options]',
+        options: [
+            '  --output <file>        Output file for generated types',
+            '  --content-key <key>    Content key for your project',
+            '  --lang <code>          Language code (e.g., EN, FR)',
+            '  --pending-changes      Use pending/draft content',
+        ],
+    },
+};
+function showHelp() {
+    console.log(chalk.bold('\nContentStorage CLI'));
+    console.log(chalk.dim('Manage content and generate TypeScript types\n'));
+    console.log(chalk.bold('Usage:'));
+    console.log('  contentstorage <command> [options]\n');
+    console.log(chalk.bold('Commands:'));
+    Object.values(COMMANDS).forEach((cmd) => {
+        console.log(`  ${chalk.cyan(cmd.name.padEnd(20))} ${cmd.description}`);
+    });
+    console.log(chalk.bold('\nOptions:'));
+    console.log('  --help                 Show help for a command\n');
+    console.log(chalk.dim('Examples:'));
+    console.log(chalk.dim('  contentstorage pull --content-key abc123'));
+    console.log(chalk.dim('  contentstorage generate-types --output types.ts'));
+    console.log(chalk.dim('  contentstorage pull --help    # Show help for pull command\n'));
+}
+function showCommandHelp(commandName) {
+    const cmd = COMMANDS[commandName];
+    if (!cmd) {
+        console.error(chalk.red(`Unknown command: ${commandName}`));
+        process.exit(1);
+    }
+    console.log(chalk.bold(`\n${cmd.name}`));
+    console.log(chalk.dim(cmd.description + '\n'));
+    console.log(chalk.bold('Usage:'));
+    console.log(`  ${cmd.usage}\n`);
+    if (cmd.options.length > 0) {
+        console.log(chalk.bold('Options:'));
+        cmd.options.forEach((opt) => console.log(opt));
+        console.log('');
+    }
+}
+async function main() {
+    const args = process.argv.slice(2);
+    // No arguments - show help
+    if (args.length === 0) {
+        showHelp();
+        process.exit(0);
+    }
+    const command = args[0];
+    // Global --help flag
+    if (command === '--help' || command === '-h') {
+        showHelp();
+        process.exit(0);
+    }
+    // Command-specific --help
+    if (args.includes('--help') || args.includes('-h')) {
+        showCommandHelp(command);
+        process.exit(0);
+    }
+    // Route to commands
+    switch (command) {
+        case 'pull':
+            await pullContent();
+            break;
+        case 'generate-types':
+            await generateTypes();
+            break;
+        default:
+            console.error(chalk.red(`Unknown command: ${command}\n`));
+            console.log(chalk.dim('Run "contentstorage --help" for usage'));
+            process.exit(1);
+    }
+}
+main().catch((error) => {
+    console.error(chalk.red('Unexpected error:'), error);
+    process.exit(1);
+});

package/dist/scripts/generate-types.js

@@ -172,4 +172,3 @@ export async function generateTypes() {
         process.exit(1);
     }
 }
-generateTypes();

package/dist/scripts/pull-content.js

@@ -135,4 +135,3 @@ export async function pullContent() {
         process.exit(1); // Exit with error code
     }
 }
-pullContent();

package/package.json

@@ -2,14 +2,14 @@
   "name": "@contentstorage/core",
   "author": "Kaido Hussar <kaidohus@gmail.com>",
   "homepage": "https://contentstorage.app",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "type": "module",
   "description": "Fetch content from contentstorage and generate TypeScript types",
+  "license": "MIT",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
-    "pull-content": "dist/scripts/pull-content.js",
-    "generate-types": "dist/scripts/generate-types.js"
+    "contentstorage": "dist/scripts/cli.js"
   },
   "repository": {
     "type": "git",