cobrili-client 1.0.2 → 1.0.4

package/README.md

@@ -1,15 +1,30 @@
 # Cobrili-Client
 
-Modern TypeScript API client for Cobrili REST API. Works in both Browser and Node.js environments.
+Modern TypeScript API client for the [Cobrili™](https://acolada.de/produkte/cobrili-2/) Content Delivery System by [Acolada GmbH](https://acolada.de/).
+
+Developed by [dictaJet Ingenieurgesellschaft mbH](https://www.dictajet.de/).
+
+## About Cobrili
+
+Cobrili™ is an HTML5-based Content Delivery System for online help and e-learning content. Key features include:
+
+- Online and offline availability
+- Faceted search and terminology-based search functions  
+- Multi-language and multi-variant content delivery
+- Flexible metadata filtering
+- Rich API for integration into software applications
+
+This client library provides a TypeScript/JavaScript interface to the Cobrili REST API.
 
 ## Features
 
 - ✅ Full TypeScript support with type definitions
 - ✅ Registry-driven API with all methods auto-generated
 - ✅ Works in Browser and Node.js
-- ✅ JSON-based communication
+- ✅ XML-over-JSON communication (handled internally)
 - ✅ Promise/async-await API
 - ✅ Configurable base URL and headers
+- ✅ Explicit session initialization
 
 ## Installation
 
@@ -17,123 +32,201 @@ Modern TypeScript API client for Cobrili REST API. Works in both Browser and Nod
 npm install cobrili-client
 ```
 
-## Usage
-
-### ES6 Import (Recommended)
+## Quick Start
 
 ```typescript
 import { createCobriliClient } from 'cobrili-client';
 
 const client = createCobriliClient({
-  baseUrl: 'http://localhost:5000',
-  endpoint: '/api/cobrili',
-  headers: {
-    'Authorization': 'Basic ' + btoa('user:pass')
-  }
+  baseUrl: 'https://your-server.com',
+  endpoint: '/api/cobrili'
 });
 
-// Login
-const loginResult = await client.login({ loginUser: { username: 'user', password: 'pass' } });
+// Initialize session (required before making API calls)
+await client.init();
 
-// Get navigation
-const nav = await client.getNavigationWithMetaData({ currentNavigationID: 0 });
+// Now you can make API calls
+const helpsets = await client.getAllHelpsets({
+  masterHelpSetApplicationIdentifier: 'MyApp',
+  withMetadata: true
+});
 
-// Get content
-const content = await client.getContent({ topicID: 12345 });
+if (helpsets.data) {
+  console.log('Helpsets:', helpsets.data.helpsetInfos);
+} else {
+  console.error('Error:', helpsets.error.message);
+}
 ```
 
-### CommonJS
+## Usage
 
-```javascript
-const { createCobriliClient } = require('cobrili-client');
+### Creating the Client
+
+```typescript
+import { createCobriliClient } from 'cobrili-client';
 
-const client = createCobriliClient({ baseUrl: 'http://localhost:5000' });
+const client = createCobriliClient({
+  baseUrl: 'https://your-server.com',  // Backend server URL
+  endpoint: '/api/cobrili',             // API endpoint path
+  timeout: 30000,                       // Request timeout in ms (optional)
+  headers: {},                          // Custom headers (optional)
+  debug: false                          // Enable debug logging (optional)
+});
 ```
 
-## API Methods
+### Initialization (Required)
 
-All methods are auto-generated from the API registry. Import `API_METHODS` for the full list:
+The client must be initialized before making API calls. This creates a session with the backend:
 
 ```typescript
-import { API_METHODS } from 'cobrili-client';
+// Initialize the session
+await client.init();
 
-// List all available methods
-console.log(Object.keys(API_METHODS));
+// Check if initialized
+if (client.isInitialized()) {
+  // Ready to make API calls
+}
 ```
 
-### Authentication
-- `login({ loginUser: { username, password } })` - Login with credentials
-- `logout({})` - Logout
+### Typical Workflow
 
-### Navigation
-- `getNavigationWithMetaData({ currentNavigationID })` - Get navigation tree
-- `navigateToTopic({ topicID, navigationID })` - Navigate to topic
+```typescript
+// 1. Initialize
+await client.init();
 
-### Content
-- `getContent({ topicID })` - Get topic content
-- `getTopicForExternalId({ externalIdForTopic, externalIdForHelpset })` - Find topic
+// 2. Activate a master helpset
+const masterResult = await client.switchMasterHelpSet({
+  masterHelpSetApplicationIdentifier: 'Convotherm',
+  initActiveHelpset: true
+});
 
-### Helpset
-- `getAllHelpsets({ masterHelpSetApplicationIdentifier, withMetadata })` - Get all helpsets
-- `getHomeTopicId({ helpsetID })` - Get home topic
-- `loadActiveHelpset({ helpsetID })` - Load a helpset
+// 3. Get all helpsets
+const helpsetsResult = await client.getAllHelpsets({
+  masterHelpSetApplicationIdentifier: 'Convotherm',
+  withMetadata: true
+});
 
-### Bookmarks
-- `historyBack(steps?)` / `historyForward(steps?)` - Navigate history
-- `getBookmarkList()` - Get bookmarks
-- `addBookmark(topicID, navigationID, title)` - Add bookmark
+// 4. Load a specific helpset
+await client.loadActiveHelpset({ helpsetID: 123 });
 
-### Metadata
-- `getUsedMetaValues(metaKey)` - Get meta values
-- `getMetaValueForTopic(metaKey, topicID)` - Get meta for topic
-- `getMetaKeyWhichRepresentsLanguage()` - Get language key
+// 5. Get navigation tree
+const navResult = await client.getNavigationWithMetaData({
+  currentNavigationID: 0,
+  wantedMetaKeys: [],
+  useHelpsetMetadataFallback: false
+});
 
-### System
-- `getCurrentCobriliVersion()` - Get version
-- `getConfigurationData()` - Get configuration
-- `clearStaticCaches()` - Clear caches
-- `healthCheck()` - Health check
+// 6. Get topic content
+const contentResult = await client.getContent({ topicID: 456 });
+if (contentResult.data) {
+  // contentResult.data.content contains base64-encoded HTML
+}
+```
 
 ## Response Format
 
+All API methods return a discriminated union type:
+
 ```typescript
-interface ApiResponse<T> {
-  success: boolean;
-  data: T;
-  status: number;
-  message?: string;
+type ApiResponse<T> = 
+  | { data: T; error?: never }      // Success
+  | { data?: never; error: CobriliError };  // Error
+
+interface CobriliError {
+  code: string;
+  message: string;
+  details?: any;
 }
 ```
 
-## Development
+### Handling Responses
 
-```bash
-# Install dependencies
-npm install
+```typescript
+const result = await client.getAllHelpsets({
+  masterHelpSetApplicationIdentifier: 'MyApp',
+  withMetadata: true
+});
 
-# Build the package
-npm run build
+if (result.error) {
+  // Handle error
+  console.error(`${result.error.code}: ${result.error.message}`);
+} else {
+  // Use data
+  const helpsets = result.data.helpsetInfos;
+}
+```
 
-# Watch mode for development
-npm run dev
+## API Methods
 
-# Run tests
-npm run test
+All methods are auto-generated from the API registry:
 
-# Type check
-npm run type-check
+```typescript
+import { API_METHODS } from 'cobrili-client';
 
-# Lint
-npm run lint
+// List all available methods
+console.log(Object.keys(API_METHODS));
 ```
 
-## Publishing
+### Session & Authentication
+- `init()` - Initialize session (required first)
+- `isInitialized()` - Check if session is active
+- `login({ loginUser })` - Login with credentials
+- `logout({})` - Logout
 
-```bash
-npm run build
-npm publish
+### Master Helpset
+- `switchMasterHelpSet({ masterHelpSetApplicationIdentifier, initActiveHelpset })` - Activate master
+- `getAllHelpsets({ masterHelpSetApplicationIdentifier, withMetadata })` - Get all helpsets
+- `getAllowedMetaKeysForMasterhelpset({ masterHelpSetApplicationIdentifier })` - Get metadata keys
+
+### Helpset
+- `loadActiveHelpset({ helpsetID })` - Load a helpset
+- `getHelpsetInfoForActiveHelpset({})` - Get active helpset info
+- `getHomeTopicId({ helpsetID })` - Get home topic
+
+### Navigation
+- `getNavigationWithMetaData({ currentNavigationID, wantedMetaKeys })` - Get navigation tree
+- `navigateToTopic({ topicID, navigationID })` - Navigate to topic
+
+### Content
+- `getContent({ topicID })` - Get topic content (base64-encoded)
+- `getTopicForExternalId({ externalIdForTopic, externalIdForHelpset })` - Find topic by external ID
+- `getMetaValuesForTopics({ externalTopicIDs, wantedMetaKeys })` - Get metadata for topics
+
+### Metadata
+- `getPossibleMetaValues({ metaKey })` - Get possible values for a meta key
+- `getMetaValueForTopic({ metaKey, topicID })` - Get meta value for topic
+
+### History & Bookmarks
+- `historyBack({ steps })` / `historyForward({ steps })` - Navigate history
+- `getBookmarkList({})` - Get bookmarks
+- `addBookmark({ topicID, navigationID, title })` - Add bookmark
+
+### System
+- `getCurrentCobriliVersion({})` - Get version
+- `getConfigurationData({})` - Get configuration
+- `clearStaticCaches({})` - Clear caches
+
+## CommonJS
+
+```javascript
+const { createCobriliClient } = require('cobrili-client');
+
+const client = createCobriliClient({ baseUrl: 'https://your-server.com' });
+await client.init();
 ```
 
+## Links
+
+- [Cobrili™ Product Page](https://acolada.de/produkte/cobrili-2/) - Acolada GmbH
+- [dictaJet](https://www.dictajet.de/) - Client developer
+- [npm Package](https://www.npmjs.com/package/cobrili-client)
+
 ## License
 
 MIT
+
+---
+
+**Cobrili™** is a trademark of [Acolada GmbH](https://acolada.de/), Nürnberg, Germany.
+
+**cobrili-client** is developed by [dictaJet Ingenieurgesellschaft mbH](https://www.dictajet.de/), Wiesbaden, Germany.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cobrili-client",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Modern TypeScript API client for Cobrili REST API - works in Browser and Node.js",
   "main": "dist/index.js",
   "module": "dist/index.mjs",