Copilot Client SDK

Install

* To install from NPM registry
``sh
npm install @cimulate/copilot-sdk
`

Configuration Options

| Option | Type | Default Value | Description |
|-----------------|----------|-------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| apiKey | string | Required if apiToken is not used | The API key used for authentication. |
| apiToken | string | Required if apiKey is not used | The API JWT token used for authentication. |
| baseUrl | string | Required | The base URL of the Copilot API server. |
| namespace | string | '/copilot' | The Socket.IO namespace for the connection. |
| socketOptions | object | {path: "/api/v1/socket.io", autoConnect: false, transports: ["polling", "websocket"], upgrade: true, timeout: 10000,} | Additional SocketIO supported options can be passed in the configuration object.
For more information, refer to the SocketIO documentation. |

Connection Modes

$3

`typescript
const client = new CimulateCopilot({
apiKey: "your-api-key",
baseUrl: "https://cimulate.copilot.url",
});
`

$3

`typescript
const client = new CimulateCopilot({
apiKey: "your-api-key",
baseUrl: "https://cimulate.copilot.url",
namespace: "/copilot",
socketOptions: {
path: "/api/v1/socket.io",
transports: ["polling"],
upgrade: false,
timeout: 10000,
},
});
`

$3

`typescript
const client = CimulateCopilot({
apiToken: "your-api-token",
baseUrl: "https://cimulate.copilot.url",
});
`

Example Usage

- Callbacks
- Async Generator
- Reconnect

$3

`typescript
import { CimulateCopilot } from '@cimulate/copilot-sdk';

// Establish Connection
const client = new CimulateCopilot({
apiKey: "your-api-key",
baseUrl: "https://cimulate.copilot.url",
});

// Connect to the Copilot server
client.connect();

// Handle connection acknowledgment
client.on("connect_ack", function connectAck(data) {
console.log("Connected: ", data);
});

// Handle errors
client.on("error", function handleError(err) {
console.error("Error: ", err);
});

// Perform a search request
const search = await client.search({
userPrompt: "What specifications should I consider for a budget gaming laptop?",
searchParams: {"query": "gaming laptops"}
});

// Print search acknowledgment
console.log("Search Acknowledgement: ", search.result);

// Perform a browse request
const browse = await client.browse({
userPrompt: "What specifications should I consider for a budget gaming laptop?",
browseParams: {"categoryId": "gaming laptops"}
});

// Print browse acknowledgment
console.log("Browse Acknowledgement: ", browse.result);

// Perform a product view request
const productView = await client.productView({
userPrompt: "What colors are available for this product?",
productId: "product-123"
});

// Print product view acknowledgment
console.log("Product View Acknowledgement: ", productView.result);

// Perform a Conversation Reset
const conversationReset = await client.conversationReset({});

// Print conversation reset acknowledgment
console.log("Conversation Reset Acknowledgement: ", conversationReset.result);

// Handler for listening to an event
const handleEvent = client.on("event_name", function handleEvent(data) {
console.log("Event Data: ", data);
});

// Follow-up Example for listening to an event response
const followUp = client.on("follow_up", function followup(event) {
if (event.eventSourceId == search.result.eventId) {
event.suggestions.forEach((s) => console.log(s.displayText));
}
});

// Client side disconnect
client.disconnect();

// Handle disconnect event
client.onDisconnect((reason) => {
console.log("Disconnected:", reason);
});
`

$3


`typescript
import { CimulateCopilot } from '@cimulate/copilot-sdk';

// Establish Connection with autoConnect set to false
const client = new CimulateCopilot({
apiKey: "your-api-key",
baseUrl: "https://cimulate.copilot.url",
socketOptions: {
autoConnect: true,
},
});

// Handle connection acknowledgment
client.on("connect_ack", function connectAck(data) {
console.log("Connected: ", data);
});
`

$3


`typescript
import { CimulateCopilot } from '@cimulate/copilot-sdk';

// Establish Connection to an existing session
// Note: If session does not exists, a new session will be created.
const client = new CimulateCopilot({
apiKey: "your-api-key",
baseUrl: "https://cimulate.copilot.url",
socketOptions: {
transportOptions: {
polling: {
extraHeaders: {
"x-cimulate-api-key": "api-123",
},
},
},
});

// If connections gets disconnected, reconnect to the session
client.reconnect();
`

$3


`typescript
interface SearchReturnedFields {
id: string,
title: string,
image_url: string,
price: number,
}

// Instantiate client object
const client = new CimulateCopilot({
apiKey: "your-api-key",
baseUrl: "https://cimulate.copilot.url",
});
`

$3


`typescript
interface BrowseReturnedFields {
id: string,
title: string,
image_url: string,
price: number,
}
`

// Instantiate client object
const client = new CimulateCopilot({
apiKey: "your-api-key",
baseUrl: "https://cimulate.copilot.url",
});

$3

`typescript
import {
CimulateCopilot,
CimulateCopilotException,
} from "@cimulate/copilot-sdk";

const copilot = new CimulateCopilot({
apiKey: "your-api-key",
baseUrl: "https://cimulate.copilot.url",
});

try {
const search = await copilot.search({
searchParams: { query: "" },
});
console.log("Search request ack:", search.result);
} catch (error) {
// Handles errors that occur during the search request acknowledgement
if (error instanceof CimulateCopilotException) {
console.error("Error received via event:", error);
}
}
`

Notes


- The apiKey is required to authenticate and establish the connection.
- Ensure the baseUrl matches the appropriate Copilot API environment.
- Set upgradeTransport: false if you want to restrict transport to the defined methods.
- Adjust the timeout based on your network conditions.
- The copilot search request will fail if the query is an empty payload "" and includeFacets is set to false.
Ensure to provide a valid query string in the search request or set includeFacets to true`.