@leadcms/sdk 2.1.5 → 2.2.2

package/README.md

@@ -44,9 +44,40 @@ npm install -g @leadcms/sdk
 - 🛠️ Project initialization and setup
 - 🛠️ Content fetching and Docker template generation
 
+## Quick Start
+
+Get started with LeadCMS in 3 simple steps:
+
+### 1. Initialize Your Project
+```bash
+npx leadcms init
+```
+This will:
+- Connect to your LeadCMS instance
+- Detect available entity types (content, media, comments)
+- Create configuration files (`.env` and optionally `leadcms.config.json`)
+
+### 2. Authenticate (for write access)
+```bash
+npx leadcms login
+```
+- **LeadCMS v1.2.88+**: Automatic device authentication via browser
+- **Older versions**: Guided manual token extraction
+- Saves your API token securely to `.env`
+
+**Skip this step** if you only need read-only access to public content.
+
+### 3. Download Your Content
+```bash
+npx leadcms pull
+```
+Downloads all content, media, and comments to your local project.
+
+**That's it!** You're ready to use LeadCMS content in your application. See [Usage Examples](#usage-examples) below.
+
 ## CI/CD Integration
 
-[![CI](https://github.com/LeadCMS/leadcms-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/LeadCMS/leadcms-sdk/actions/workflows/ci.yml)
+[![Build & Test](https://github.com/LeadCMS/leadcms.sdk/actions/workflows/build-and-test.yml/badge.svg)](https://github.com/LeadCMS/leadcms.sdk/actions/workflows/build-and-test.yml)
 
 The LeadCMS SDK includes comprehensive CI/CD workflows for GitHub Actions that provide:
 
@@ -101,15 +132,6 @@ npm run test:coverage
 
 # Run tests in watch mode
 npm run test:watch
-
-# Run tests with mock server (includes CLI integration tests)
-./tests/run-tests.sh
-
-# Run only unit tests
-npm run test:unit
-
-# Run only CLI integration tests
-npm run test:integration
 ```
 
 ### Test Coverage
@@ -134,23 +156,19 @@ LEADCMS_USE_MOCK=true LEADCMS_CONTENT_DIR=./test-content npx leadcms status
 # Test with different mock scenarios
 LEADCMS_USE_MOCK=true LEADCMS_MOCK_SCENARIO=hasConflicts npx leadcms status
 LEADCMS_USE_MOCK=true LEADCMS_MOCK_SCENARIO=mixedOperations npx leadcms push --dry-run
-
-# Test in development with localhost (automatically uses mock)
-LEADCMS_URL=http://localhost:3001 npx leadcms status
 ```
 
 **Available Mock Scenarios:**
 - `allNew` - Local content that doesn't exist remotely (default)
 - `noChanges` - All content is in sync
 - `hasConflicts` - Remote content is newer than local
-- `hasUpdates` - Local content is newer than remote  
+- `hasUpdates` - Local content is newer than remote
 - `mixedOperations` - Mix of new, updated, and conflicted content
 - `missingContentTypes` - Content with unknown types
 
-**Mock Mode Auto-Detection:**
+**Mock Mode Activation:**
 - `NODE_ENV=test` - Automatically uses mock mode
 - `LEADCMS_USE_MOCK=true` - Force mock mode
-- `LEADCMS_URL` contains `localhost` - Automatically uses mock mode
 
 The data service abstraction automatically handles switching between real API calls and mock data based on your environment, providing seamless testing without external dependencies.
 
@@ -158,13 +176,18 @@ The data service abstraction automatically handles switching between real API ca
 
 LeadCMS SDK supports multiple configuration methods in order of priority:
 
+> **🚀 Quick Start:** Run `npx leadcms init` for an interactive setup wizard that handles everything!
+
 ### 1. Environment Variables (Recommended for API credentials)
 
 For security reasons, it's best to keep sensitive credentials as environment variables:
 
 ```bash
-# Required - keep these as environment variables for security
+# Required
 LEADCMS_URL=your-leadcms-instance-url
+
+# Optional - API key for authenticated access
+# Omit this for public-only mode (published content only)
 LEADCMS_API_KEY=your-api-key
 
 # Optional - can also be set via environment variables
@@ -178,6 +201,8 @@ NEXT_PUBLIC_LEADCMS_URL=your-leadcms-instance-url
 NEXT_PUBLIC_LEADCMS_DEFAULT_LANGUAGE=en
 ```
 
+> **� Security Note:** The SDK uses a **security-first approach** - all read operations (content, comments, media sync) are performed WITHOUT authentication, ensuring only public data is retrieved. API keys are only used for write operations. See [Public API Mode Guide](./docs/PUBLIC_API_MODE.md) for details.
+
 ### 2. Configuration File (For project-specific settings)
 
 Create a `leadcms.config.json` file **only if you need to override default settings** like `contentDir`, `mediaDir`, or `defaultLanguage`:
@@ -220,33 +245,141 @@ configure({
 ### Configuration Options
 
 - `url` - Your LeadCMS instance URL (**required**, best as env var)
-- `apiKey` - Your LeadCMS API key (**required**, best as env var)
+- `apiKey` - Your LeadCMS API key (**optional**, omit for public-only mode, best as env var when used)
 - `defaultLanguage` - Default language code (default: "en")
 - `contentDir` - Directory for downloaded content (default: ".leadcms/content")
 - `mediaDir` - Directory for media files (default: "public/media")
-- `enableDrafts` - Enable draft content support (default: false)
+- `enableDrafts` - Enable draft content support (default: false, requires API key)
 
 ## CLI Usage
 
+### Check SDK version
+```bash
+npx leadcms version
+# or
+npx leadcms -v
+# or
+npx leadcms --version
+```
+
 ### Initialize configuration
 ```bash
 npx leadcms init
-# Creates leadcms.config.json with sample configuration
 ```
 
+Interactive setup wizard that:
+1. **Connects to your LeadCMS instance** - Validates URL and checks for existing authentication
+2. **Fetches configuration** - Retrieves default language and available languages from public `/api/config` endpoint
+3. **Configures directories** - Sets content and media directories (defaults: `.leadcms/content`, `public/media`)
+4. **Creates environment file** - Saves configuration to `.env`
+5. **Creates config file** - Only if you use non-default directories (keeps your project clean!)
+
+**Note:** The `/api/config` endpoint is public and works without authentication. For write operations and private content, run `leadcms login` after initialization.
+
+### Login to LeadCMS
+```bash
+npx leadcms login
+```
+
+Authenticates with your LeadCMS instance:
+- **Device Authentication** (LeadCMS v1.2.88+) - Opens a browser link for secure authentication
+- **Manual Token** (older versions) - Guides you through extracting an API token
+- **Saves token** - Automatically stores the token in your `.env` file
+
+**When to use:**
+- After running `leadcms init` if you need write access
+- To update an expired or invalid token
+- When switching between LeadCMS instances
+
+Example session:
+
+```
+🚀 LeadCMS SDK Initialization
+
+Enter your LeadCMS URL: https://your-instance.leadcms.ai
+
+🔐 Authentication Setup
+   Authentication is optional and can be skipped for most use cases.
+   • Without authentication: You can pull content and build your site (read-only access)
+   • With authentication: You can also push content changes back to LeadCMS
+   • You can always authenticate later by running: leadcms login
+
+Would you like to authenticate now? (Y/n): n
+ℹ️  Skipping authentication. Continuing in read-only mode.
+   You can run "leadcms login" later to authenticate.
+
+🔍 Connecting to LeadCMS...
+✅ Connected successfully!
+
+📋 Available languages:
+   1. English (United States) [en-US] (default)
+   2. Russian (Russia) [ru-RU]
+
+Default language code [en-US]: 
+✓ Using default language: en-US
+
+📦 Supported entity types:
+   ✓ Content
+   ✓ Media
+   ✓ Comments
+
+Content directory [.leadcms/content]:
+Media directory [public/media]:
+Comments directory [.leadcms/comments]:
+
+📝 Creating configuration files...
+
+✅ Updated .env
+ℹ️  Using default directories, no leadcms.config.json needed.
+
+✨ Configuration complete!
+
+Next steps:
+  1. Run: npx leadcms login (for write access and private content)
+  2. Run: npx leadcms pull (to download content)
+  3. Start using LeadCMS content in your project
+```
+
+The wizard creates:
+- **`.env`** (or `.env` if exists) with `LEADCMS_URL`, `LEADCMS_DEFAULT_LANGUAGE`, and optionally `LEADCMS_API_KEY`
+- **`leadcms.config.json`** only if custom directories are specified
+
+**Anonymous Mode:** Perfect for static sites that only need public content. Omit the API key to skip authentication entirely.
+
 ### Generate Docker deployment templates
 ```bash
 npx leadcms docker
 # Creates Docker files for production and preview deployments
 ```
 
-### Pull content from LeadCMS
+### Pull content, media and comments from LeadCMS
+
+The CLI supports several focused pull commands so you can sync exactly what you need.
+
 ```bash
+# Pull everything (content, media, comments)
 npx leadcms pull
+
+# Pull only content (no media or comments)
+npx leadcms pull-content
+
+# Pull only media files
+npx leadcms pull-media
+
+# Pull only comments
+npx leadcms pull-comments
 ```
 
 > **Note:** `npx leadcms fetch` is still supported as an alias for backward compatibility.
 
+What each command does:
+- `npx leadcms pull` - Syncs content, media and comments into your project using the configured directories. Updates incremental sync tokens so subsequent runs are faster.
+- `npx leadcms pull-content` - Downloads only content entities (MDX/JSON files) and updates local metadata.
+- `npx leadcms pull-media` - Downloads media files to your `mediaDir` (e.g., `public/media`). Use this when you changed media or want to refresh assets separately from content.
+- `npx leadcms pull-comments` - Downloads comments to the comments directory (e.g., `.leadcms/comments/`). Useful when you only need comment updates.
+
+> **Note:** The CLI uses incremental sync tokens to avoid re-downloading unchanged items where supported by the LeadCMS API.
+
 ### Push local content to LeadCMS
 ```bash
 npx leadcms push [options]
@@ -263,37 +396,36 @@ Push your local content changes to LeadCMS. This command will:
 - `--force` - Override remote changes (skip conflict check)
 
 
-**Required Metadata Fields:**
+**Content frontmatter / metadata (required and optional fields):**
 ```yaml
 ---
-type: "article"                    # Content type (must exist in LeadCMS)
-title: "Article Title"             # Content title
-slug: "article-slug"               # URL slug
-language: "en"                     # Content language
-publishedAt: "2024-10-29T10:00:00Z" # Publication date
-updatedAt: "2024-10-29T10:00:00Z"   # Last update (used for conflict detection)
+type: "article"                    # required: Content type (must exist in LeadCMS)
+title: "Article Title"             # required: Content title
+slug: "article-slug"               # required: URL slug (unique per locale)
+language: "en"                     # required: Content language
+publishedAt: "2024-10-29T10:00:00Z" # optional: Publication date (omit to create a draft or schedule a future publish)
+# updatedAt: "2024-10-29T10:00:00Z"   # optional: maintained by the server; do not set for new content
 ---
 ```
 
+Notes:
+- `publishedAt` is optional. Omitting it is a valid way to create draft or scheduled content depending on your LeadCMS workflow.
+- `updatedAt` is typically set and maintained by the LeadCMS server after content is created or updated. The SDK will use `updatedAt` when present for conflict detection, but you should not rely on it being set for brand-new local files.
+
 ### Check sync status
 ```bash
 npx leadcms status
 ```
 
-Shows the current sync status between local and remote content without making any changes.
+Shows the current sync status between local and remote **content** without making any changes.
+
+**Note:** The `status` command currently only supports content. Media and comments do not have sync status checking yet.
 
 ### Watch for real-time updates
 ```bash
 npx leadcms watch
 ```
 
-### Generate environment variables file
-```bash
-npx leadcms generate-env
-```
-
-
-
 ## Framework Integration
 
 The SDK provides framework-agnostic data access. Most frameworks use it as a **development dependency** for build-time static generation:
@@ -354,63 +486,73 @@ app.get('/api/content/:slug', (req, res) => {
 
 ## API Reference
 
-### Core Functions
+### Content API
+
+Get content from your LeadCMS instance:
 
 ```typescript
-import {
+import { 
   getCMSContentBySlugForLocale,
   getAllContentSlugsForLocale,
-  getAllContentRoutes,
-  getAvailableLanguages,
-  configure
+  getAllContentRoutes 
 } from '@leadcms/sdk';
 
-// Get content by slug and locale
+// Get single content item
 const content = getCMSContentBySlugForLocale('about-us', 'en');
 
-// Get all content slugs for a locale
+// Get all content slugs
 const slugs = getAllContentSlugsForLocale('en');
 
-// Get all routes (framework-agnostic)
+// Get all routes for static generation
 const routes = getAllContentRoutes();
-// Returns: [{ locale: 'en', slug: 'about-us', path: '/about-us', ... }]
+```
+
+**📖 See [Content Management Guide](./docs/CONTENT_MANAGEMENT.md)** for complete API documentation, framework integration examples, and advanced features.
 
-// Get available languages (uses configured contentDir)
-const languages = getAvailableLanguages();
+### Media API
 
-// Get content with draft support (userUid must be a valid GUID)
-const draftContent = getCMSContentBySlugForLocaleWithDraftSupport(
-  'about-us',
-  'en',
-  '550e8400-e29b-41d4-a716-446655440000' // Valid GUID format
-);
+Media files are automatically synced during content pull:
 
-// Load configuration objects (header, footer, etc.)
-const headerConfig = getHeaderConfig('en');
-const footerConfig = getFooterConfig('en');
+```bash
+# Sync all media files
+npx leadcms pull
+
+# Sync only media
+npx leadcms pull-media
 ```
 
-### Advanced Configuration Loading
+**📖 See [Media Management Guide](./docs/MEDIA_MANAGEMENT.md)** for media handling, optimization, and deployment strategies.
+
+### Comments API
+
+Work with comments on your content:
+
+```bash
+# Sync comments
+npx leadcms pull
+
+# Sync only comments
+npx leadcms pull-comments
+```
 
 ```typescript
-import {
-  loadContentConfig,
-  loadContentConfigStrict
+import { 
+  getCommentsForContent,
+  getCommentsTreeForContent 
 } from '@leadcms/sdk';
 
-// Generic config loading with auto contentDir resolution (userUid must be valid GUID)
-const menuConfig = loadContentConfig('menu', 'en', '6ba7b810-9dad-11d1-80b4-00c04fd430c8');
+// Get flat list of comments
+const comments = getCommentsForContent(contentId);
 
-// Strict config loading with detailed error information (throws on missing files)
-try {
-  const requiredConfig = loadContentConfigStrict('layout', 'en');
-} catch (error) {
-  console.log('Missing config:', error.configName);
-  console.log('Expected locale:', error.locale);
-  console.log('Expected path:', error.message);
-}
+// Get comments as tree for threading
+const tree = getCommentsTreeForContent(contentId, undefined, {
+  sortOrder: 'newest',
+  replySortOrder: 'oldest'
+});
 ```
 
+**📖 See [Comment Tree Guide](./docs/COMMENT_TREE.md)** for complete documentation on threaded comments, sorting, filtering, and advanced features.
+
 ## Docker Deployment
 
 LeadCMS SDK includes framework-agnostic Docker templates for easy deployment:
@@ -471,39 +613,7 @@ docker run -p 80:80 \
   my-leadcms-site-preview
 ```
 
-### Template Features
-
-✅ **Framework-agnostic** - Works with any static site generator
-✅ **Production optimized** - Nginx with proper caching headers
-✅ **Live preview** - Development mode with hot reload support
-✅ **Multi-service** - Nginx proxy + dev server + LeadCMS watcher
-✅ **Runtime configuration** - Environment variables injected at startup
-✅ **Health checks** - Built-in container health monitoring
-
-### Customizing Templates
-
-After generating templates with `npx leadcms docker`, you can customize:
-
-1. **Source directory** in `Dockerfile`:
-   ```dockerfile
-   # Change 'out' to your framework's build output:
-   COPY dist /usr/share/nginx/html    # Astro
-   COPY public /usr/share/nginx/html  # Gatsby
-   COPY .output/public /usr/share/nginx/html  # Nuxt
-   ```
-
-2. **Nginx configuration** in `nginx.conf` for custom routing rules
-
-3. **Development command** in `preview/supervisord.conf`:
-   ```ini
-   [program:dev-server]
-   command=npm run livepreview    # Your development command
-   ```
-
-## Performance & Debugging
-
-### Configuration Caching
-The SDK automatically caches configuration files for 60 seconds and content files for 30 seconds to improve build performance. Multiple calls to the same configuration functions will use cached results.
+## Debugging
 
 ### Debug Logging
 Control SDK logging verbosity with environment variables:
@@ -551,42 +661,52 @@ try {
 - ✅ Configuration is cached across multiple function calls within the same process
 - ✅ Use `loadContentConfig()` for optional configs, `loadContentConfigStrict()` for required configs
 
+## Features & Documentation
+
+### 📚 Complete Guides
+
+- **[Documentation Index](./docs/README)** - Central hub for all documentation
+
+#### Content & Media
+- **[Content Management](./docs/CONTENT_MANAGEMENT.md)** - Retrieving, organizing, and working with content
+- **[Media Management](./docs/MEDIA_MANAGEMENT.md)** - Handling media files and optimization
+- **[Draft Handling](./docs/DRAFT_HANDLING.md)** - Working with draft content and user-specific drafts
+
+#### Comments
+- **[Comment Tree Guide](./docs/COMMENT_TREE.md)** - Building threaded comment interfaces with sorting and filtering
+
+#### Setup & Configuration
+- **[Interactive Init](./docs/INTERACTIVE_INIT.md)** - Setup wizard and authentication
+- **[Public API Mode](./docs/PUBLIC_API_MODE.md)** - Security-first approach and operation modes
+
+#### Development
+- **[Development Guide](./docs/DEVELOPMENT.md)** - Local development, testing, and debugging
+- **[GitHub Actions](./docs/GITHUB_ACTIONS.md)** - CI/CD setup and automated publishing
+
 ## Development
 
-For SDK development and contributions:
+For SDK development and contributions, see [Development Guide](./docs/DEVELOPMENT.md).
+
+**Quick Start:**
 
 ```bash
 # Clone and setup
 git clone https://github.com/LeadCMS/leadcms.sdk.git
-cd leadcms-sdk
+cd leadcms.sdk
 npm install
+npm run build
 
-# Development workflow
-npm run build    # Build the SDK
-npm run dev      # Watch mode for development
-npm run test     # Run tests
-npm run clean    # Clean build artifacts
-
-# Local testing with npm link
-npm link
-cd ../your-test-project
-npm link @leadcms/sdk
-```
-
-### Debug Mode
-
-Enable detailed logging during development:
+# Run tests
+npm test
 
-```bash
-LEADCMS_DEBUG=true npm run build
+# Development mode
+npm run dev
 ```
 
-### Contributing
+**Contributing:**
 
 1. Fork the repository
 2. Create a feature branch
 3. Make your changes
-4. Run tests: `npm run test`
+4. Run tests: `npm test`
 5. Submit a pull request
-
-For detailed development setup, see [DEVELOPMENT.md](./docs/DEVELOPMENT.md).