@starasia/chat-core

Headless chat / AI conversation logic — message state, streaming lifecycle, and transport helpers. Zero UI. Pair with @starasia/chat-ui for components, or render however you like.

Install

pnpm add @starasia/chat-core

react >= 18 is a peer dependency.

Quick start

import { useChat, createSSETransport } from "@starasia/chat-core";

const transport = createSSETransport({
  endpoint: "/api/chat",
  body: (messages) => ({ messages }),
});

function Chat() {
  const { messages, input, setInput, send, stop, status, isStreaming } =
    useChat({ transport });

  return (
    <>
      {messages.map((m) => (
        <p key={m.id}><b>{m.role}:</b> {m.content}</p>
      ))}
      <input value={input} onChange={(e) => setInput(e.target.value)} />
      {isStreaming
        ? <button onClick={stop}>Stop</button>
        : <button onClick={() => send()}>Send</button>}
    </>
  );
}

API

useChat(options): UseChatHelpers

| Option | Type | Notes | |---|---|---| | transport | ChatTransport | Required. Yields text deltas for the reply. | | initialMessages | ChatMessage[] | Seed the thread. | | generateId | () => string | Defaults to a built-in generator. | | onError | (err: Error) => void | | | onFinish | (msg: ChatMessage) => void | Final assistant message. |

Returns: messages, input, setInput, status (idle \| submitted \| streaming \| error), error, isStreaming, send(text?), stop(), regenerate(), setMessages(), clear().

Transports

A ChatTransport is (ctx: { messages, signal }) => AsyncIterable<string>. Bring your own, or use a helper:

• createSSETransport(opts) — Server-Sent Events. parseChunk maps each event to a delta (default: JSON { content | delta | text }, else raw data; stops on [DONE]).
• createTextTransport(opts) — plain chunked-text response (no SSE framing).
• parseSSE(response, { signal }) — low-level SSE event generator for custom transports.

Dev

pnpm dev   # http://localhost:3010 — mock-streamed demo
pnpm build