Copilot Client SDK

Install

• To install from NPM registry

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

Default Mode

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

HTTP Long Polling Only Mode (No Websockets)

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

Using API Token for Authentication

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

Example Usage

• Callbacks
• Async Generator
• Reconnect

Default Usage

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

Establishing Connection Automatically

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

Reconnecting to a Disconnected Session

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();

Defining Search Returned Fields Types

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

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

Defining Browse Returned Fields Types

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

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

Handling Request Ack Failure

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.