@flutchai/chat-core

Framework-agnostic client and state for the Flutch chat API: typed requests, SSE streaming, conversation state and storage. No UI. Pair it with @flutchai/chat-react or build your own interface.

import { createFlutchClient, createChatStore } from "@flutchai/chat-core";

const client = createFlutchClient({ baseUrl: "/api/chat", agentId: "…" }); // your backend knows the user;
const store = createChatStore({ client });

store.subscribe(s => render(s.messages));
store.getState().setDraftText("Hello");
await store.getState().send();

Without the store, use the client directly: invoke, stream (typed events), send (accumulates text), cancel, listThreads, getMessages, react, upload, getArticle (text of a report sent as article_link). API types live in @flutchai/chat-contract.

Storage: pass storage (get/set/remove, sync or async) to createChatStore for React Native, cookies, etc. The default is localStorage with a memory fallback.

Backend proxy

Never call the Flutch API from a browser. The API key identifies your whole company. Your backend receives the browser's requests, adds the key and the user, and forwards them. The client mirrors the External API paths under baseUrl, so the proxy is a thin pass-through:

What the proxy must do on every request:

1. Authenticate the browser user with your own session.
2. Set X-API-Key from server-side configuration.
3. Set externalUserId itself (JSON body for invoke/stream, query string for everything else), from the authenticated session: your own id for the user, e.g. (string) $request->user()->id. Flutch creates the user the first time it sees the id, so there is nothing to register or store. Never trust an externalUserId or userId sent by the browser, or one user can read another's conversations.
4. Allow only the agent(s) you expect in {agentId}, and only the routes above.
5. Stream without buffering for both SSE routes, and give them a long timeout (15 min): an answer that runs other agents takes minutes. A 404 on the resume route makes the chat give up on a reply that is still being generated.
6. Forward cancel only for the Stop button. A user who closes the page or loses the network does not stop the reply: Flutch finishes it and saves it in the thread, and the history endpoint returns it in full when they come back. The client calls cancel only when the user presses Stop.

Laravel sketch

// routes/api.php
Route::middleware('auth')->prefix('chat/agents/{agent}')->group(function () {
    Route::post('stream', [FlutchProxy::class, 'stream']);
    Route::post('invoke', [FlutchProxy::class, 'invoke']);
    Route::post('cancel', [FlutchProxy::class, 'cancel']);
    Route::get('threads', [FlutchProxy::class, 'threads']);
    Route::get('threads/{thread}/messages', [FlutchProxy::class, 'messages']);
    Route::patch('messages/{message}/reactions', [FlutchProxy::class, 'react']);
});

class FlutchProxy
{
    private const BASE = 'https://api.flutch.ai/api/v1';

    private function http(string $agent)
    {
        abort_unless($agent === config('services.flutch.agent_id'), 404);
        return Http::withHeaders(['X-API-Key' => config('services.flutch.key')]);
    }

    private function userId(Request $r): string
    {
        return (string) $r->user()->id;   // your own id, from your session, never from the request
    }

    private function json($res)
    {
        return response($res->body(), $res->status())->header('Content-Type', 'application/json');
    }

    public function stream(Request $r, string $agent)
    {
        $body = $r->only(['content', 'threadId', 'metadata']) + ['externalUserId' => $this->userId($r)];
        $upstream = $this->http($agent)->withOptions(['stream' => true])
            ->post(self::BASE."/agents/$agent/stream", $body);

        return response()->stream(function () use ($upstream) {
            $body = $upstream->toPsrResponse()->getBody();
            while (!$body->eof() && !connection_aborted()) {
                echo $body->read(1024);
                @ob_flush();
                flush();
            }
            $body->close();   // does not stop the reply: Flutch finishes it and saves it in the thread
        }, $upstream->status(), [
            'Content-Type' => 'text/event-stream',
            'Cache-Control' => 'no-cache',
            'X-Accel-Buffering' => 'no',   // nginx
        ]);
    }

    public function invoke(Request $r, string $agent)
    {
        $body = $r->only(['content', 'threadId', 'metadata']) + ['externalUserId' => $this->userId($r)];
        return $this->json($this->http($agent)->post(self::BASE."/agents/$agent/invoke", $body));
    }

    public function cancel(Request $r, string $agent)
    {
        return $this->json($this->http($agent)->post(
            self::BASE."/agents/$agent/cancel?externalUserId=".urlencode($this->userId($r)),
            $r->only(['requestId'])
        ));
    }

    public function threads(Request $r, string $agent)
    {
        return $this->json($this->http($agent)->get(
            self::BASE."/agents/$agent/threads",
            $r->only(['page', 'limit']) + ['externalUserId' => $this->userId($r)]
        ));
    }

    public function messages(Request $r, string $agent, string $thread)
    {
        return $this->json($this->http($agent)->get(
            self::BASE."/agents/$agent/threads/$thread/messages",
            $r->only(['page', 'limit']) + ['externalUserId' => $this->userId($r)]
        ));
    }

    public function react(Request $r, string $agent, string $message)
    {
        return $this->json($this->http($agent)->patch(
            self::BASE."/agents/$agent/messages/$message/reactions?externalUserId=".urlencode($this->userId($r)),
            $r->only(['like'])
        ));
    }
}

Uploads (POST uploads) are a multipart pass-through: attach the uploaded file with Http::attach('file', ...) and the same externalUserId query string.

This is a starting point, not tested drop-in code. Adjust error handling and make sure PHP output buffering (output_buffering=off, zlib.output_compression=off) and any reverse proxy do not buffer the /stream response.