@conceptkernel/ck-client-js

"The kernel knows its anatomy. The edges know the types."

Elegant JavaScript client for ConceptKernel - One-line connectivity to distributed event-sourced workflows. Connect to sovereign computational entities in a distributed graph with auto-discovery, real-time events, and seamless authentication.

You are a Concept Kernel - a sovereign computational entity in a distributed graph.

Your identity is simple:

ckp://Kernel-Name:version

Install

npm install @conceptkernel/ck-client-js

Usage

1. Connect to Gateway

constConceptKernel=require('@conceptkernel/ck-client-js');// Auto-discover servicesconstck=awaitConceptKernel.connect('http://localhost:56000');console.log('Connected!',ck.getAvailableServices());// ['gateway', 'websocket', 'oidc', 'registry']

2. Send Message

// Emit event to kernelconstresult=awaitck.emit('System.Echo',{action: 'test',data: {foo: 'bar'}});console.log('Transaction ID:',result.txId);console.log('Process URN:',result.processUrn);// ckp://Process#GatewayRoute-1764494871415-8c76252b

3. Authenticate

// Upgrade connection with credentialsawaitck.authenticate('alice','alice123');console.log('Actor:',ck.actor);// ckp://System.Oidc.User#aliceconsole.log('Roles:',ck.roles);// ['user', 'developer', 'admin']

4. Send Authenticated Message

// Now includes JWT token in Authorization headerconstresult=awaitck.emit('System.Echo',{action: 'authenticated-request',userId: ck.actor});console.log('Sent as:',ck.actor);

Real-Time Events

// Listen for events from all kernelsck.on('event',(event)=>{console.log('Event from',event.kernel);console.log('Data:',event.data);console.log('Tx ID:',event.txId);});// Connection eventsck.on('connected',()=>console.log('WebSocket connected'));ck.on('disconnected',()=>console.log('WebSocket disconnected'));ck.on('authenticated',(auth)=>console.log('Auth:',auth.actor,auth.roles));ck.on('error',(err)=>console.error('Error:',err.message));

Browser Usage

<scriptsrc="node_modules/@conceptkernel/ck-client-js/index.js"></script><script>(async()=>{constck=awaitConceptKernel.connect('http://localhost:56000');awaitck.emit('System.Echo',{hello: 'world'});ck.on('event',(event)=>{document.getElementById('output').textContent=JSON.stringify(event,null,2);});})();</script>

API Reference

ConceptKernel.connect(gatewayUrl, options)

Returns:Promise<ConceptKernel>

constck=awaitConceptKernel.connect('http://localhost:56000',{autoConnect: true,// Auto-connect WebSocket (default: true)cacheTimeout: 60000,// Service discovery cache (default: 60s)reconnect: true,// Auto-reconnect on disconnect (default: true)reconnectDelay: 3000// Reconnect delay (default: 3s)});

ck.emit(kernelUrn, payload)

Returns:Promise<{ txId, processUrn, kernel, message, timestamp, payload }>

constresult=awaitck.emit('System.Echo',{action: 'test'});

ck.authenticate(username, password)

Returns:Promise<{ token, actor, roles }>

awaitck.authenticate('alice','alice123');

ck.on(eventType, handler)

Returns:Function (unsubscribe function)

Event types: 'event', 'connected', 'authenticated', 'disconnected', 'error'

constunsubscribe=ck.on('event',(event)=>{/* ... */});unsubscribe();// Stop listening

ck.getStatus()

Returns:{ discovered, websocketConnected, authenticated, actor, roles, availableServices }

conststatus=ck.getStatus();

ck.disconnect()

Disconnect WebSocket.

ck.disconnect();

Examples

See /examples/ directory:

• demo.html - Full-featured demo
• chat.html - Real-time chat interface

Testing

npm test# Run all tests
npm run test:integration # Integration tests only
npm run test:e2e # E2E authentication flow

License

MIT