@dotcms/client 1.0.0-next.4 → 1.0.0-next.5

package/CLAUDE.md

@@ -0,0 +1,253 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is the **DotCMS Client SDK** (`@dotcms/client`) - a JavaScript/TypeScript library for interacting with DotCMS REST APIs. The SDK is part of a larger DotCMS monorepo and serves as the foundation for framework-specific integrations (React, Angular, etc.).
+
+## Essential Commands
+
+### Development Commands
+```bash
+# Install dependencies (from monorepo root)
+yarn install
+
+# Build library for distribution
+nx run sdk-client:build                  # ESM/CJS dual package build
+nx run sdk-client:build:js               # Specialized esbuild for editor integration
+
+# Run tests
+nx run sdk-client:test                   # Run Jest tests
+nx run sdk-client:test:ci                # Run tests with CI configuration and coverage
+
+# Code quality
+nx run sdk-client:lint                   # ESLint code linting
+
+# Publishing
+nx run sdk-client:publish --args.ver=1.0.0 --args.tag=latest
+```
+
+### Testing Commands
+```bash
+# Run specific test file
+nx test sdk-client --testNamePattern="specific test name"
+
+# Run tests in watch mode
+nx test sdk-client --watch
+
+# Run tests with coverage
+nx test sdk-client --coverage
+```
+
+## Architecture Overview
+
+### Project Structure
+```
+libs/sdk/client/
+├── src/
+│   ├── index.ts                    # Main export (createDotCMSClient)
+│   ├── internal.ts                 # Internal utilities for other SDKs
+│   └── lib/
+│       ├── client/
+│       │   ├── client.ts          # Main DotCMSClient class
+│       │   ├── content/           # Content API with query builders
+│       │   ├── navigation/        # Navigation API
+│       │   ├── page/             # Page API with GraphQL support
+│       │   └── models/           # TypeScript interfaces and types
+│       └── utils/
+│           └── graphql/          # GraphQL utilities
+├── project.json                   # Nx project configuration
+├── package.json                   # NPM package configuration
+├── tsconfig.json                  # TypeScript configuration
+└── jest.config.ts                 # Jest testing configuration
+```
+
+### Key Components
+
+**Core API Pattern**: The SDK follows a client-builder pattern with three main APIs:
+- `client.page.get()` - Fetches complete page content with layout and containers
+- `client.content.getCollection()` - Builder pattern for querying content collections
+- `client.navigation.get()` - Fetches site navigation structure
+
+**Build Targets**:
+- `build` - Standard library build producing ESM/CJS dual packages
+- `build:js` - Specialized esbuild for editor integration (outputs to `dotCMS/src/main/webapp/html/js/editor-js`)
+
+## Development Standards
+
+### TypeScript Configuration
+- **Strict mode enabled**: Full TypeScript strict checking
+- **Target**: ES2020 with lib support for ES2020, DOM, DOM.Iterable
+- **Dual package support**: ESM and CJS through Rollup build
+- **Type definitions**: `@dotcms/types` for comprehensive type safety
+
+### Code Patterns
+
+#### Client Builder Pattern
+```typescript
+// Main client initialization
+const client = createDotCMSClient({
+    dotcmsUrl: 'https://instance.com',
+    authToken: 'token',
+    siteId: 'site-id'
+});
+
+// Page API - single request for complete page
+const { pageAsset } = await client.page.get('/about-us');
+
+// Content API - fluent builder pattern
+const blogs = await client.content
+    .getCollection('Blog')
+    .query((qb) => qb.field('title').equals('dotCMS*'))
+    .limit(10)
+    .sortBy([{ field: 'publishDate', direction: 'desc' }]);
+```
+
+#### GraphQL Integration
+```typescript
+// Extend page requests with GraphQL for additional content
+const { pageAsset, content } = await client.page.get('/about-us', {
+    graphql: {
+        page: `title vanityUrl { url }`,
+        content: {
+            blogs: `BlogCollection(limit: 3) { title urlTitle }`,
+            navigation: `DotNavigation(uri: "/", depth: 2) { href title }`
+        }
+    }
+});
+```
+
+#### Query Builder Pattern
+```typescript
+// Fluent query building for content collections
+const query = await client.content
+    .getCollection('Product')
+    .query((qb) => qb
+        .field('category').equals('electronics')
+        .and()
+        .field('price').raw(':[100 TO 500]')
+        .not()
+        .field('discontinued').equals('true')
+    )
+    .limit(10)
+    .page(1);
+```
+
+### Testing Standards
+
+#### Jest Configuration
+- **Framework**: Jest with TypeScript support
+- **Coverage**: Outputs to `../../../coverage/libs/sdk/client`
+- **File patterns**: `**/*.spec.ts` and `**/*.test.ts`
+- **CI mode**: Supports CI configuration with coverage reporting
+
+#### Test Patterns
+```typescript
+// Use descriptive test names and group related tests
+describe('DotCMSClient', () => {
+    describe('page.get()', () => {
+        it('should fetch page content with default options', async () => {
+            // Test implementation
+        });
+        
+        it('should apply GraphQL extensions correctly', async () => {
+            // Test implementation
+        });
+    });
+});
+
+// Mock external dependencies
+jest.mock('../utils/fetch', () => ({
+    dotFetch: jest.fn()
+}));
+```
+
+### Build System Integration
+
+#### Nx Monorepo Integration
+- **Executor**: `@nx/rollup:rollup` for main build, `@nx/esbuild:esbuild` for editor build
+- **Outputs**: Dual package (ESM/CJS) with proper export maps
+- **Dependencies**: Automatically managed through Nx dependency graph
+
+#### Export Configuration
+```typescript
+// Package exports support both named and default imports
+export { createDotCMSClient } from './lib/client/client';
+export type { DotCMSClient } from './lib/client/client';
+
+// Internal exports for framework SDKs
+export { DotCMSClientImpl } from './lib/client/client-impl';
+```
+
+## Key Configuration Files
+
+- **project.json**: Nx project configuration with build targets
+- **package.json**: NPM package metadata with proper exports field
+- **tsconfig.json**: TypeScript configuration with strict mode
+- **tsconfig.lib.json**: Library-specific TypeScript settings
+- **jest.config.ts**: Jest testing configuration
+
+## Development Workflow
+
+### Standard Development Flow
+1. **Make changes** → Test locally with `nx test sdk-client`
+2. **Lint code** → `nx lint sdk-client`
+3. **Build library** → `nx build sdk-client`
+4. **Integration testing** → Test with dependent SDKs or examples
+
+### Editor Integration Build
+For changes affecting the editor integration:
+1. **Build editor version** → `nx run sdk-client:build:js`
+2. **Test in dotCMS editor** → Verify functionality in dotCMS admin
+3. **Clean build artifacts** → Script automatically removes temporary files
+
+### Release Process
+1. **Version bump** → Update version in `package.json`
+2. **Build all targets** → `nx build sdk-client`
+3. **Publish** → `nx run sdk-client:publish --args.ver=X.X.X --args.tag=latest`
+
+## Integration Context
+
+### Framework SDKs
+This client SDK serves as the foundation for:
+- `@dotcms/react` - React integration with UVE support
+- `@dotcms/angular` - Angular integration with UVE support
+- `@dotcms/uve` - Universal Visual Editor low-level integration
+
+### Dependencies
+- **Runtime**: `consola` for logging
+- **Development**: `@dotcms/types` for TypeScript definitions
+- **Peer Dependencies**: Framework-specific SDKs extend this client
+
+## Common Development Tasks
+
+### Adding New API Methods
+1. **Define interfaces** in `lib/client/models/`
+2. **Implement method** in appropriate API class (`page/`, `content/`, `navigation/`)
+3. **Export** from main `index.ts`
+4. **Add tests** following existing patterns
+5. **Update TypeScript types** if needed
+
+### Extending Query Builders
+1. **Add method** to appropriate builder class
+2. **Update builder interface** with new method signature
+3. **Add tests** for new query capabilities
+4. **Document** in README with examples
+
+### GraphQL Integration
+1. **Define GraphQL fragments** in `utils/graphql/`
+2. **Add to page API** GraphQL parameter types
+3. **Test** with various GraphQL queries
+4. **Update documentation** with new capabilities
+
+## Summary Checklist
+- ✅ Use Nx commands for all build/test operations
+- ✅ Follow client-builder pattern for new APIs
+- ✅ Maintain TypeScript strict mode compliance
+- ✅ Write comprehensive Jest tests for new features
+- ✅ Use proper export patterns for dual package support
+- ✅ Test both ESM and CJS builds
+- ✅ Verify editor integration when making core changes
+- ❌ Avoid breaking changes to public API without migration plan
+- ❌ Don't add runtime dependencies without careful consideration

package/MIGRATION.md

@@ -0,0 +1,329 @@
+# Migration Guide: Alpha to 1.0.X
+
+If you're upgrading from the `alpha.xx` version of `@dotcms/client`, this guide will help you migrate to the 1.0.X release. The 1.0.X version introduces several breaking changes and improvements for better developer experience, type safety, and performance.
+
+### Breaking Changes Summary
+
+| Change | Alpha Version | 1.0.X Version |
+|--------|---------------|----------------|
+| Client Initialization | `DotCmsClient.init()` | `createDotCMSClient()` |
+| Import Statement | `import { DotCmsClient }` | `import { createDotCMSClient }` |
+| Navigation API | `client.nav.get()` | `client.navigation.get()` |
+| Content Collection | `.fetch()` method required | Direct await on collection |
+| Parameter Names | `language_id` | `languageId` |
+| Response Structure | Different format | Standardized response format |
+
+## Step-by-Step Migration Guide
+
+### 1. Update Dependencies
+
+First, update your package.json to use the latest 1.0.X version:
+
+```bash
+# Remove the alpha version
+npm uninstall @dotcms/client
+
+# Install the 1.0.X version with types
+npm install @dotcms/client@latest @dotcms/types@latest
+```
+
+### 2. Update Import Statements
+
+**Before (Alpha):**
+```javascript
+import { DotCmsClient } from '@dotcms/client';
+```
+
+**After (1.0.X):**
+```javascript
+import { createDotCMSClient } from '@dotcms/client';
+```
+
+### 3. Update Client Initialization
+
+**Before (Alpha):**
+```javascript
+const client = DotCmsClient.init({
+    dotcmsUrl: 'https://your-dotcms-instance.com',
+    authToken: 'your-auth-token',
+    siteId: 'your-site-id'
+});
+```
+
+**After (1.0.X):**
+```javascript
+const client = createDotCMSClient({
+    dotcmsUrl: 'https://your-dotcms-instance.com',
+    authToken: 'your-auth-token',
+    siteId: 'your-site-id'
+});
+```
+
+### 4. Update Navigation API Calls
+
+**Before (Alpha):**
+```javascript
+const navData = await client.nav.get({
+    path: '/',
+    depth: 2,
+    languageId: 1
+});
+```
+
+**After (1.0.X):**
+```javascript
+const navData = await client.navigation.get('/', {
+    depth: 2,
+    languageId: 1
+});
+```
+
+### 5. Update Content Collection Queries
+
+**Before (Alpha):**
+```javascript
+const collectionResponse = await client.content
+    .getCollection('Blog')
+    .limit(10)
+    .page(1)
+    .fetch(); // .fetch() was required
+
+console.log(collectionResponse.contentlets);
+```
+
+**After (1.0.X):**
+```javascript
+const blogs = await client.content
+    .getCollection('Blog')
+    .limit(10)
+    .page(1); // Direct await, no .fetch() needed
+
+console.log(blogs.contentlets);
+```
+
+### 6. Update Parameter Names
+
+**Before (Alpha):**
+```javascript
+const pageData = await client.page.get({
+    path: '/your-page-path',
+    language_id: 1, // underscore naming
+    personaId: 'optional-persona-id'
+});
+```
+
+**After (1.0.X):**
+```javascript
+const { pageAsset } = await client.page.get('/your-page-path', {
+    languageId: 1, // camelCase naming
+    personaId: 'optional-persona-id'
+});
+```
+
+🚨 Also notice that the url path is now the first param of the `get` method and is not longer in the object.
+
+### 7. Update Response Handling
+
+**Before (Alpha):**
+```javascript
+const pageData = await client.page.get({ path: '/about-us' });
+// Direct access to page data
+console.log(pageData.page.title);
+```
+
+**After (1.0.X):**
+```javascript
+const { pageAsset } = await client.page.get('/about-us');
+// Destructured response
+console.log(pageAsset.page.title);
+```
+
+### 8. Update Query Builder Syntax
+
+**Before (Alpha):**
+```javascript
+const complexQueryResponse = await client.content
+    .getCollection('Blog')
+    .query((qb) => qb.field('author').equals('John Doe').and().field('title').equals('Hello World'))
+    .fetch();
+```
+
+**After (1.0.X):**
+```javascript
+const blogs = await client.content
+    .getCollection('Blog')
+    .query((qb) => qb.field('author').equals('John Doe').and().field('title').equals('Hello World'));
+```
+
+### 9. Update Sorting Syntax
+
+**Before (Alpha):**
+```javascript
+const sortedResponse = await client.content
+    .getCollection('Blog')
+    .sortBy([{ field: 'title', order: 'asc' }])
+    .fetch();
+```
+
+**After (1.0.X):**
+```javascript
+const blogs = await client.content
+    .getCollection('Blog')
+    .sortBy([{ field: 'title', order: 'asc' }]);
+```
+
+## Troubleshooting
+
+### Common Migration Issues
+
+**Issue 1: `DotCmsClient is not a function` Error**
+
+**Problem:** Using the old initialization method.
+
+**Solution:**
+```javascript
+// ❌ This will fail
+const client = DotCmsClient.init({...});
+
+// ✅ Use this instead
+const client = createDotCMSClient({...});
+```
+
+**Issue 2: `client.nav is not a function` Error**
+
+**Problem:** The navigation API method name changed.
+
+**Solution:**
+```javascript
+// ❌ This will fail
+const navData = await client.nav.get({...});
+
+// ✅ Use this instead
+const navData = await client.navigation.get('/', {...});
+```
+
+**Issue 3: `Cannot read property 'contentlets' of undefined` Error**
+
+**Problem:** Response structure changed, especially for page requests.
+
+**Solution:**
+```javascript
+// ❌ This might fail
+const pageData = await client.page.get('/path');
+console.log(pageData.page.title);
+
+// ✅ Use destructuring
+const { pageAsset } = await client.page.get('/path');
+console.log(pageAsset.page.title);
+```
+
+**Issue 4: Content Collection `.fetch()` Method Not Found**
+
+**Problem:** The `.fetch()` method is no longer required.
+
+**Solution:**
+```javascript
+// ❌ This will fail
+const result = await client.content.getCollection('Blog').fetch();
+
+// ✅ Direct await
+const result = await client.content.getCollection('Blog');
+```
+
+**Issue 5: TypeScript Errors After Migration**
+
+**Problem:** Missing type definitions or changed interfaces.
+
+**Solution:**
+```bash
+# Install the types package
+npm install @dotcms/types@latest
+
+# Update your TypeScript imports
+import type { DotCMSClient } from '@dotcms/client';
+import type { DotCMSPageAsset } from '@dotcms/types';
+```
+
+**Issue 6: Build or Runtime Errors with Module Resolution**
+
+**Problem:** Module resolution issues after updating packages.
+
+**Solution:**
+```bash
+# Clear node_modules and reinstall
+rm -rf node_modules package-lock.json
+npm install
+
+# Or if using Yarn
+rm -rf node_modules yarn.lock
+yarn install
+```
+
+**Issue 7: Unexpected Response Format**
+
+**Problem:** Trying to access properties that don't exist in the new response format.
+
+**Solution:**
+```javascript
+// ❌ This might fail
+const response = await client.page.get('/path');
+console.log(response.containers); // This property structure changed
+
+// ✅ Use the new structure
+const { pageAsset } = await client.page.get('/path');
+console.log(pageAsset.containers);
+```
+
+### Migration Checklist
+
+Use this checklist to ensure you've completed all necessary migration steps:
+
+- [ ] **Dependencies**: Update package.json dependencies
+- [ ] **Imports**: Change import statements from `DotCmsClient` to `createDotCMSClient`
+- [ ] **Initialization**: Update client initialization method
+- [ ] **Navigation API**: Replace `client.nav.get()` with `client.navigation.get()`
+- [ ] **Content Collections**: Remove `.fetch()` calls from content collection queries
+- [ ] **Parameter Names**: Update parameter names from snake_case to camelCase
+- [ ] **Response Handling**: Update response destructuring (especially for page requests)
+- [ ] **TypeScript**: Install and configure TypeScript types if using TypeScript
+- [ ] **Testing**: Test all API calls to ensure they work correctly
+- [ ] **Documentation**: Update any internal documentation or comments
+
+### Testing Your Migration
+
+After completing the migration, test these key areas:
+
+1. **Client Initialization**: Verify the client initializes without errors
+2. **Page Fetching**: Test fetching different pages and accessing their properties
+3. **Content Collections**: Test querying different content types with various filters
+4. **Navigation**: Test navigation API calls with different parameters
+5. **Error Handling**: Verify error handling works as expected
+6. **TypeScript**: If using TypeScript, ensure there are no type errors
+
+### Performance Considerations
+
+The 1.0.X version includes several performance improvements:
+
+- **Optimized Requests**: Reduced request overhead and improved caching
+- **Better Error Handling**: More efficient error processing
+- **Type Safety**: Compile-time checks prevent runtime errors
+- **GraphQL Integration**: More efficient data fetching with GraphQL
+
+### Need Help?
+
+If you encounter issues during migration that aren't covered here:
+
+1. **Check the Full Documentation**: Review the [README.md](./README.md) for updated API documentation
+2. **GitHub Issues**: [Open an issue](https://github.com/dotCMS/core/issues/new/choose) on GitHub with your specific problem
+3. **Community Support**: Visit our [community forum](https://community.dotcms.com/) for community support
+
+### Additional Resources
+
+- [dotCMS Client SDK Documentation](./README.md)
+- [dotCMS API Documentation](https://dev.dotcms.com/docs/rest-api)
+- [dotCMS GraphQL Documentation](https://dev.dotcms.com/docs/graphql)
+- [dotCMS Community Forum](https://community.dotcms.com/)
+
+---
+
+**Note**: This migration guide is specific to upgrading from the alpha version to the 1.0.X release. For other version migrations, please refer to the appropriate documentation or release notes.