cobrili-client 1.0.1 → 1.0.3

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,9 +32,7 @@ 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';
@@ -32,27 +45,123 @@ const client = createCobriliClient({
   }
 });
 
-// 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
+
+### Creating the Client
 
-```javascript
-const { createCobriliClient } = require('cobrili-client');
+```typescript
+import { createCobriliClient } from 'cobrili-client';
 
-const client = createCobriliClient({ baseUrl: 'http://localhost:5000' });
+const client = createCobriliClient({
+  baseUrl: 'http://localhost:5000',  // Backend server URL
+  endpoint: '/api/cobrili',           // API endpoint path
+  timeout: 30000,                     // Request timeout in ms
+  headers: {},                        // Custom headers
+  debug: false                        // Enable debug logging
+});
+```
+
+### Initialization (Required)
+
+The client must be initialized before making API calls. This creates a session with the backend:
+
+```typescript
+// Initialize the session
+await client.init();
+
+// Check if initialized
+if (client.isInitialized()) {
+  // Ready to make API calls
+}
+```
+
+### Typical Workflow
+
+```typescript
+// 1. Initialize
+await client.init();
+
+// 2. Activate a master helpset
+const masterResult = await client.switchMasterHelpSet({
+  masterHelpSetApplicationIdentifier: 'Convotherm',
+  initActiveHelpset: true
+});
+
+// 3. Get all helpsets
+const helpsetsResult = await client.getAllHelpsets({
+  masterHelpSetApplicationIdentifier: 'Convotherm',
+  withMetadata: true
+});
+
+// 4. Load a specific helpset
+await client.loadActiveHelpset({ helpsetID: 123 });
+
+// 5. Get navigation tree
+const navResult = await client.getNavigationWithMetaData({
+  currentNavigationID: 0,
+  wantedMetaKeys: [],
+  useHelpsetMetadataFallback: false
+});
+
+// 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
+type ApiResponse<T> = 
+  | { data: T; error?: never }      // Success
+  | { data?: never; error: CobriliError };  // Error
+
+interface CobriliError {
+  code: string;
+  message: string;
+  details?: any;
+}
+```
+
+### Handling Responses
+
+```typescript
+const result = await client.getAllHelpsets({
+  masterHelpSetApplicationIdentifier: 'MyApp',
+  withMetadata: true
+});
+
+if (result.error) {
+  // Handle error
+  console.error(`${result.error.code}: ${result.error.message}`);
+} else {
+  // Use data
+  const helpsets = result.data.helpsetInfos;
+}
 ```
 
 ## API Methods
 
-All methods are auto-generated from the API registry. Import `API_METHODS` for the full list:
+All methods are auto-generated from the API registry:
 
 ```typescript
 import { API_METHODS } from 'cobrili-client';
@@ -61,59 +170,66 @@ import { API_METHODS } from 'cobrili-client';
 console.log(Object.keys(API_METHODS));
 ```
 
-### Authentication
-- `login({ loginUser: { username, password } })` - Login with credentials
+### Session & Authentication
+- `init()` - Initialize session (required first)
+- `isInitialized()` - Check if session is active
+- `login({ loginUser })` - Login with credentials
 - `logout({})` - Logout
 
-### Navigation
-- `getNavigationWithMetaData({ currentNavigationID })` - Get navigation tree
-- `navigateToTopic({ topicID, navigationID })` - Navigate to topic
-
-### Content
-- `getContent({ topicID })` - Get topic content
-- `getTopicForExternalId({ externalIdForTopic, externalIdForHelpset })` - Find topic
+### Master Helpset
+- `switchMasterHelpSet({ masterHelpSetApplicationIdentifier, initActiveHelpset })` - Activate master
+- `getAllHelpsets({ masterHelpSetApplicationIdentifier, withMetadata })` - Get all helpsets
+- `getAllowedMetaKeysForMasterhelpset({ masterHelpSetApplicationIdentifier })` - Get metadata keys
 
 ### Helpset
-- `getAllHelpsets({ masterHelpSetApplicationIdentifier, withMetadata })` - Get all helpsets
-- `getHomeTopicId({ helpsetID })` - Get home topic
 - `loadActiveHelpset({ helpsetID })` - Load a helpset
+- `getHelpsetInfoForActiveHelpset({})` - Get active helpset info
+- `getHomeTopicId({ helpsetID })` - Get home topic
 
-## License
+### Navigation
+- `getNavigationWithMetaData({ currentNavigationID, wantedMetaKeys })` - Get navigation tree
+- `navigateToTopic({ topicID, navigationID })` - Navigate to topic
 
-MIT
-- `historyBack(steps?)` / `historyForward(steps?)` - Navigate history
-- `getBookmarkList()` - Get bookmarks
-- `addBookmark(topicID, navigationID, title)` - Add bookmark
+### Content
+- `getContent({ topicID })` - Get topic content (base64-encoded)
+- `getTopicForExternalId({ externalIdForTopic, externalIdForHelpset })` - Find topic by external ID
+- `getMetaValuesForTopics({ externalTopicIDs, wantedMetaKeys })` - Get metadata for topics
 
 ### Metadata
-- `getUsedMetaValues(metaKey)` - Get meta values
-- `getMetaValueForTopic(metaKey, topicID)` - Get meta for topic
-- `getMetaKeyWhichRepresentsLanguage()` - Get language key
+- `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
-- `healthCheck()` - Health check
+- `getCurrentCobriliVersion({})` - Get version
+- `getConfigurationData({})` - Get configuration
+- `clearStaticCaches({})` - Clear caches
 
-## Response Format
+## CommonJS
 
-```typescript
-interface ApiResponse<T> {
-  success: boolean;
-  data: T;
-  status: number;
-  message?: string;
-}
+```javascript
+const { createCobriliClient } = require('cobrili-client');
+
+const client = createCobriliClient({ baseUrl: 'http://localhost:5000' });
+await client.init();
 ```
 
-## Development
+## Links
 
-```bash
-npm install
-npm run build
-```
+- [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.