Catalogs

Introduction

Catalogs are the REST side of the client: the list of a user’s conversations and the list of agents they can talk to. Everything else in a conversation travels over the socket. You need them to build a conversation sidebar or an agent picker.

Reading conversations and agents

import { createAgentCatalog, createConversationCatalog } from '@pilotoo/chat-core';

// `apiUrl` is your server's base URL; `credentials` is your CredentialsProvider.
const conversations = createConversationCatalog(apiUrl, fetch, { credentials });
const agents = createAgentCatalog(apiUrl, fetch, { credentials });

The second argument is the fetch to use. A host that routes HTTP itself passes its own. credentials is described in Connecting a client.

React hooks sit on top: useConversations and useAgents (ConversationsState, AgentsState). A SaaS app that wants an agent picker wraps createAgentCatalog and useAgents in its own component, then remounts ChatProvider with key={agentId} when the reader switches.

Every response is parsed with the schema the gateway validates its own replies against, so a shape the client cannot read is reported rather than assumed.

The other clients

The demo web app creates one client per concern, each with the same arguments:

apps/web/src/app/environment.ts

createConversationCatalog(apiUrl, fetch, { credentials });
createAgentCatalog(apiUrl, fetch, { credentials });
createAgentAdmin(apiUrl, fetch, { credentials });
createUsageReader(apiUrl, fetch, { credentials });
createScheduleClient(apiUrl, fetch, { credentials });
createPresentationSource(apiUrl, fetch, { credentials });

The @pilotoo/ui/settings screens are built on them. See Usage, Schedules and Presentation.

Next steps

• Connecting a client for the transport and credentials.
• Chat UI for the components that render these lists.