Cobrili-Client

Modern TypeScript API client for the Cobrili™ Content Delivery System by Acolada GmbH.

Developed by dictaJet Ingenieurgesellschaft mbH.

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
• ✅ XML-over-JSON communication (handled internally)
• ✅ Promise/async-await API
• ✅ Configurable base URL and headers
• ✅ Explicit session initialization

Installation

npm install cobrili-client

Quick Start

import { createCobriliClient } from 'cobrili-client'

const client = createCobriliClient({
	baseUrl: 'https://your-server.com',
	endpoint: '/api/cobrili'
})

// Initialize session (required before making API calls)
await client.init()

// Now you can make API calls
const helpsets = await client.getAllHelpsets({
	masterHelpSetApplicationIdentifier: 'MyApp',
	withMetadata: true
})

if (helpsets.data) {
	console.log('Helpsets:', helpsets.data.helpsetInfos)
} else {
	console.error('Error:', helpsets.error.message)
}

Usage

Creating the Client

import { createCobriliClient } from 'cobrili-client'

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)
})

Server-Side Usage (Node.js)

For server-side usage, you need to provide a cookieStore to manage session cookies manually:

import { createCobriliClient, type CookieStore } from 'cobrili-client'

// Create a simple cookie store
let sessionCookie: string | undefined
const cookieStore: CookieStore = {
	get: () => sessionCookie,
	set: (value: string) => {
		sessionCookie = value
	}
}

const client = createCobriliClient({
	baseUrl: 'https://your-server.com',
	endpoint: '/api/cobrili',
	cookieStore // Required for Node.js/server environments
})

Initialization (Required)

The client must be initialized before making API calls. This creates a session with the backend:

// Initialize the session
await client.init()

// Check if initialized
if (client.isInitialized()) {
	// Ready to make API calls
}

Typical Workflow

// 1. Initialize
await client.init()

// 2. Activate a master helpset
const masterResult = await client.switchMasterHelpSet({
	masterHelpSetApplicationIdentifier: 'MyApp',
	initActiveHelpset: true
})

// 3. Get all helpsets
const helpsetsResult = await client.getAllHelpsets({
	masterHelpSetApplicationIdentifier: 'MyApp',
	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:

type ApiResponse<T> =
	| { data: T; error?: never } // Success
	| { data?: never; error: CobriliError } // Error

interface CobriliError {
	code: string
	message: string
	details?: any
}

Handling Responses

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

The client provides 163 auto-generated API methods. See API_COMPLETE_REFERENCE.md for the full list.

Key Method Categories

| Category | Examples | |----------|----------| | Session | init(), login(), logout() | | Helpsets | switchMasterHelpSet(), getAllHelpsets(), loadActiveHelpset() | | Navigation | getNavigation(), getBreadCrumb(), navigateToTopic() | | Content | getContent(), getTopicInfo(), getTopicForExternalId() | | Metadata | getPossibleMetaValues(), setCurrentMetaDataSetForSession() | | Search | startSearch(), getSearchResults(), getSuggestionsForSearchInput() | | Bookmarks | addBookmark(), deleteBookmark(), getBookmarkList() | | Users | createUser(), modifyUser(), getAllUsers() |

import { API_METHODS } from 'cobrili-client'

// List all available methods
console.log(Object.keys(API_METHODS))

CommonJS

const { createCobriliClient } = require('cobrili-client')

const client = createCobriliClient({ baseUrl: 'https://your-server.com' })
await client.init()

Documentation

For detailed documentation, see the docs folder:

• COBRILI_CONCEPTS.md - Core concepts (MasterHelpset, Helpset, Topic, Navigation, Metadata), typical workflows, and architecture overview
• API_COMPLETE_REFERENCE.md - Complete API reference with all 163 methods, parameters, and XML definitions

Links

• Cobrili™ Product Page - Acolada GmbH
• dictaJet - Client developer
• npm Package

License

MIT

Cobrili™ is a trademark of Acolada GmbH, Nürnberg, Germany.

cobrili-client is developed by dictaJet Ingenieurgesellschaft mbH, Wiesbaden, Germany.