A1D - Picadabra Docs

Installation

npm install @picadabra/client @tanstack/react-query

Setup

Create a React client with TanStack Query utilities:

// lib/picadabra.ts
import { createPicadabraClient } from "@picadabra/client";
import { createPicadabraReactClient } from "@picadabra/client/react";

const client = createPicadabraClient({
  baseUrl: "https://api.picadabra.ai",
  credentials: () => getAuthToken(), // your auth token getter
});

export const picadabra = createPicadabraReactClient(client);

Streaming with TanStack Query

Use streamedOptions to consume SSE streams with automatic state management:

import {  } from "@tanstack/react-query";

import {  } from "../lib/picadabra";

function ({  }: { : string }) {
  const { ,  } = (
    .stream.streamedOptions({
      : { : "generate", : {  } },
      : true, // Auto-reconnect on disconnect
    }),
  );

  // data is StreamEvent[], new events appended to end
  const  = ?.at(-1);

  if ( === "pending") return <>Connecting...</>;
  if (?.type === "error") return <>Error: {.error}</>;
  if (?.type === "done") return <>Complete!</>;

  return <>Progress: {.(?.data)}</>;
}

Multiple Concurrent Streams

TanStack Query automatically manages multiple streams with distinct query keys:

import {  } from "@tanstack/react-query";

import {  } from "../lib/picadabra";

function ({  }: { : string }) {
  const {  } = (
    .stream.streamedOptions({
      : { : "process", : {  } },
      : true,
    }),
  );

  const  = ?.at(-1);
  const  = (?.data as { ?: number })?. ?? 0;

  return (
    <>
      <>Task {}</>
      < ={} ={100} />
    </>
  );
}

// Render 5 concurrent task progress bars
function ({  }: { : string[] }) {
  return (
    <>
      {.(() => (
        < ={} ={} />
      ))}
    </>
  );
}

Each TaskProgress component:

Has its own SSE connection
Shares data if the same taskId is used elsewhere
Automatically cleans up when unmounted

Query Options

streamedOptions

For accumulating events (chat messages, logs):

picadabra.stream.streamedOptions({
  input: { endpoint: "chat", input: { message: "Hello" } },
  queryFnOptions: {
    refetchMode: "reset", // 'reset' | 'append'
    maxChunks: 100, // Limit stored events
  },
  retry: true,
});

liveOptions

For latest-value only (progress, status):

picadabra.stream.liveOptions({
  input: { endpoint: "status", input: { taskId } },
  retry: true,
});
// data is always the latest StreamEvent (not an array)

Cancellation

Streams are automatically cancelled when the component unmounts. For manual control:

import { ,  } from "@tanstack/react-query";

import {  } from "../lib/picadabra";

function ({  }: { : string }) {
  const  = ();

  const {  } = (
    .stream.streamedOptions({
      : { : "process", : {  } },
    }),
  );

  const  = () => {
    .({
      : .stream.key({
        : { : "process", : {  } },
      }),
    });
  };

  return (
    <>
      <>{.(?.at(-1))}</>
      < ={}>Cancel</>
    </>
  );
}

Error Handling

import {  } from "@orpc/client";
import {  } from "@tanstack/react-query";

import {  } from "../lib/picadabra";

function ({  }: { : string }) {
  const { , ,  } = (
    .stream.streamedOptions({
      : { : "process", : {  } },
    }),
  );

  // Connection-level error
  if ( && ()) {
    return <>Connection error: {.message}</>;
  }

  // Stream-level error (from event)
  const  = ?.at(-1);
  if (?.type === "error") {
    return <>Task error: {.error}</>;
  }

  return <>{.(?.data)}</>;
}

How is this guide?

React

On this page