Elevate Agentic Discovery SDK

TypeScript SDK for interacting with the Elevate Discovery Agent APIs and streaming responses over SSE.

Install

npm install @voyado/elevate-agent-sdk

The package ships prebuilt (dist/), so no build step is needed on install.

Usage

import {
  ElevateAgentClient,
  type QueryMessageDeltaPayload,
  type RequestOptions,
} from '@voyado/elevate-agent-sdk';

const customerKey = crypto.randomUUID();
const sessionKey = crypto.randomUUID();

const clientDefaults: RequestOptions = {
  deployment: 'my-deployment',
};

const client = ElevateAgentClient.create(
  {
    onQueryMessageDelta: (payload: QueryMessageDeltaPayload) => {
      console.log(payload.text);
    },
    onCompleted: () => {
      console.log('Conversation completed');
    },
  },
  'https://w123abc4d.elevate-api.cloud',
  clientDefaults,
);

await client.startConversation({
  market: 'US',
  customerKey,
  messageId: crypto.randomUUID(),
  touchpoint: 'desktop',
  query: 'running shoes',
  sessionKey,
  locale: 'en-US',
  conversationStarterTicket: 'starter-ticket',
  departmentTicket: 'department-ticket',
});

await client.refine(
  {
    market: 'US',
    customerKey,
    messageId: crypto.randomUUID(),
    touchpoint: 'desktop',
    query: 'only show trail shoes',
    sessionKey,
    locale: 'en-US',
    topicId: 'topic-123',
  },
  {
    useCache: true,
  },
);

const requestContext = {
  market: 'US',
  locale: 'en-US',
  touchpoint: 'desktop',
};

const welcomeScreen = await client.getWelcomeScreen(requestContext, {
  useCache: true,
});
console.log(welcomeScreen.globalConversationStarters[0]?.ticket);

await client.notifyExposed({ ...requestContext, customerKey, sessionKey });
await client.notifyActivated({ ...requestContext, customerKey, sessionKey });
await client.notifyTopicClick({
  ...requestContext,
  customerKey,
  sessionKey,
  ticket: 'topic-ticket',
});

await client.refine({
  market: 'US',
  customerKey,
  messageId: crypto.randomUUID(),
  touchpoint: 'desktop',
  query: 'show only waterproof ones',
  sessionKey,
  locale: 'en-US',
});

const resumedClient = ElevateAgentClient.forConversation(
  'conversation-id',
  {
    onCompleted: () => {
      console.log('Resumed conversation completed');
    },
  },
  'https://conduit-eu-north-1.voyado.io',
);

Use ElevateAgentClient.create(...) to start a new client, or ElevateAgentClient.forConversation(...) to attach to an existing conversation.

Both factory methods require baseUrl, and accept optional RequestOptions for client-wide defaults. Per-request methods also accept optional overrides that are merged with the client defaults. baseUrl stays fixed on the client and cannot be overridden per request.

getWelcomeScreen({ market, locale, touchpoint }) returns the published welcome screen configuration, including global conversation starters and department-specific conversation starters.

Pass a starter ticket from the welcome screen response as conversationStarterTicket when starting from a conversation starter. Pass a department ticket as departmentTicket when starting from a selected department.

onTopicCompleted payload includes a ticket field that can be used when sending notification calls.

Notification endpoints are available via:

• notifyExposed({ market, locale, touchpoint, ...context })
• notifyActivated({ market, locale, touchpoint, ...context })
• notifyDepartmentClick({ ticket, ...context })
• notifyTopicClick({ ticket, ...context })
• notifyCarouselNavigationInteraction({ ticket, ...context })

Development

Run the reference integration locally:

npm install
npm run dev

Open http://localhost:5173 to see the example in examples/reference-integration.ts.

Scripts

• npm run build: Compile TypeScript SDK.
• npm run build:example: Build example page.
• npm run dev: Start development server for example.
• npm run typecheck: Typecheck the example.
• npm run format: Format sources.

Releases are cut from GitHub Actions — run the Prepare release workflow, let Copilot finish the changelog on the generated PR, then merge it to publish to npm. See AGENTS.md.