JavaScript Client (@cognipeer/client-js)

The official JavaScript client library for Cognipeer provides a convenient way to interact with the Cognipeer API from both browser and Node.js environments.

Installation

npm install @cognipeer/client-js

Or with Yarn:

yarn add @cognipeer/client-js

Quick Start

import CognipeerClient from '@cognipeer/client-js';

// Initialize the client
const client = new CognipeerClient({
  baseUrl: 'https://api.cognipeer.com/v1/client', // Optional, defaults to this value
  token: 'your-api-token' // Required for authentication
});

// List available peers
const peers = await client.peer.list();
console.log(peers);

// Get a specific peer by ID
const peerId = '90aa68af-d5c4-4b60-b63e-b732db08bb46';
const peerDetails = await client.peer.get(peerId);

// Create a conversation with a peer
const conversation = await client.conversation.create(peerId);

// Send a message to a conversation
const conversationId = conversation._id;
const message = await client.conversation.sendMessage(
  conversationId, 
  'Hello, how can you help me?'
);
console.log(message.content);

API Reference

Constructor

const client = new CognipeerClient(options);

Options

Parameter	Type	Required	Description
baseUrl	string	No	The base URL for the Cognipeer API. Defaults to 'https://api.cognipeer.com/v1/client'
token	string	Yes	Authentication token for the API

Peer Methods

peer.list(options)

Retrieves a list of all available peers.

const peers = await client.peer.list({ limit: 20 });

Options

Parameter	Type	Required	Description
limit	number	No	Maximum number of peers to return (default: 10)

Returns

Promise<Peer[]>

peer.get(id)

Get details of a specific peer by ID.

const peer = await client.peer.get(peerId);

Parameters

Parameter	Type	Required	Description
id	string	Yes	The ID of the peer

Returns

Promise<Peer>

peer.competition(peerId, options)

Send a message to a peer in competition mode (creates a new conversation).

const response = await client.peer.competition(
  peerId, 
  { 
    content: 'Tell me about your products',
    responseFormat: 'json',
    responseSchema: { type: 'object', properties: {} }, // Optional
    additionalContext: { customData: 'value' } // Optional
  }
);

Parameters

Parameter	Type	Required	Description
peerId	string	Yes	The ID of the peer
options	object	Yes	Options for the competition
options.content	string	Yes	The message content
options.responseFormat	string	No	Format of the response. Can be 'text' (default) or 'json'
options.responseSchema	object	No	JSON schema for structured responses
options.additionalContext	object	No	Additional context to provide to the peer

Returns

Promise<Message> or Promise<JsonResponseMessage> depending on the response format

peer.chat(peerId, options)

Chat with a peer by sending a series of messages (creates a new conversation).

const response = await client.peer.chat(
  peerId,
  {
    messages: [
      { role: 'user', content: 'Hello' },
      { role: 'ai', content: 'Hi there! How can I help you?' },
      { role: 'user', content: 'What services do you offer?' }
    ],
    responseFormat: 'text'
  }
);

Parameters

Parameter	Type	Required	Description
peerId	string	Yes	The ID of the peer
options	object	Yes	Options for the chat
options.messages	array	Yes	Array of message objects, each with role ('user' or 'ai') and content
options.responseFormat	string	No	Format of the response. Can be 'text' (default) or 'json'
options.responseSchema	object	No	JSON schema for structured responses
options.additionalContext	object	No	Additional context to provide to the peer

Returns

Promise<Message> or Promise<JsonResponseMessage> depending on the response format

Conversation Methods

conversation.create(peerId)

Creates a new conversation with the specified peer.

const conversation = await client.conversation.create(peerId);

Parameters

Parameter	Type	Required	Description
peerId	string	Yes	The ID of the peer to create a conversation with

Returns

Promise<Conversation>

conversation.list(filter)

Get a list of conversations with optional filtering.

const conversations = await client.conversation.list({ peerId: 'some-id' });

Parameters

Parameter	Type	Required	Description
filter	object	No	Filter criteria for conversations
filter.peerId	string	No	Filter by peer ID

Returns

Promise<Conversation[]>

conversation.get(id)

Get a specific conversation by ID.

const conversation = await client.conversation.get(conversationId);

Parameters

Parameter	Type	Required	Description
id	string	Yes	The ID of the conversation to find

Returns

Promise<Conversation>

conversation.sendMessage(id, content, options)

Sends a message to an existing conversation.

const message = await client.conversation.sendMessage(
  conversationId, 
  content, 
  { responseFormat: 'json' }
);

Parameters

Parameter	Type	Required	Description
id	string	Yes	The ID of the conversation to send a message to
content	string	Yes	The content of the message to send
options	object	No	Additional options for the message
options.responseFormat	string	No	Format of the response. Can be 'text' (default) or 'json'

Returns

Promise<Message> or Promise<JsonResponseMessage> depending on the response format

conversation.getMessages(id, messagesCount)

Get messages from a conversation.

const messages = await client.conversation.getMessages(conversationId, 20);

Parameters

Parameter	Type	Required	Description
id	string	Yes	The ID of the conversation to find messages in
messagesCount	number	No	Number of messages to return (default: 10)

Returns

Promise<Message[]>

Flow Methods

flow.execute(id, options)

Execute a flow with the specified inputs.

const result = await client.flow.execute(flowId, {
  inputs: {
    name: 'John Doe',
    query: 'How do I reset my password?',
    preferences: { language: 'en' }
    // File inputs are supported and will be handled by the API
  }
});

Note: The legacy app.execute() method is still available for backward compatibility but will be deprecated. Please use flow.execute() for new implementations.

Parameters

Parameter	Type	Required	Description
id	string	Yes	The ID of the flow to execute
options	object	Yes	Options for the flow execution
options.inputs	object	Yes	Object containing input values keyed by input name

Returns

Promise<Record<string, any>> - The execution results with outputs mapped by name

Error Handling

The client includes built-in error handling that will log API errors to the console. You can also wrap your calls in try/catch blocks for custom error handling:

try {
  const peers = await client.peer.list();
} catch (error) {
  // Custom error handling
  console.error('Failed to list peers:', error);
}

Running on-premises

For on-premises deployments, just specify your local API endpoint when initializing the client:

const client = new CognipeerClient({
  baseUrl: 'https://your-local-cognipeer-api.com/v1/client',
  token: 'your-local-token'
});