React SDK Types

interface TamboThread {
  id: string;
  name?: string;
  messages: TamboThreadMessage[];
  status: RunStatus;
  metadata?: Record<string, unknown>;
  createdAt: string;
  updatedAt: string;
  lastRunCancelled: boolean;
}

type RunStatus = "idle" | "waiting" | "streaming";

interface StreamingState {
  status: RunStatus;
  runId?: string;
  messageId?: string;
  startTime?: number;
  reasoningStartTime?: number;
  error?: {
    message: string;
    code?: string;
  };
}

type TamboAuthState =
  | { status: "identified"; source: "userKey" | "tokenExchange" }
  | { status: "exchanging" }
  | { status: "error"; error: Error }
  | { status: "invalid" }
  | { status: "unauthenticated" };

import { useTambo } from "@tambo-ai/react";

function AuthAwareChat() {
  const { authState, isIdentified } = useTambo();

  if (authState.status === "exchanging") {
    return <div>Authenticating...</div>;
  }

  if (authState.status === "error") {
    return <div>Auth failed: {authState.error.message}</div>;
  }

  if (!isIdentified) {
    return <div>Please sign in to continue.</div>;
  }

  return <ChatInterface />;
}

interface TamboConfig {
  userKey?: string;
  autoGenerateThreadName?: boolean;
  autoGenerateNameThreshold?: number;
  initialMessages?: InitialInputMessage[];
}

interface InitialInputMessage {
  content: Array<TextContent | ResourceContent>;
  role: "user" | "system" | "assistant";
  metadata?: unknown;
}

import { TamboProvider } from "@tambo-ai/react";

function App() {
  return (
    <TamboProvider
      apiKey="your-api-key"
      initialMessages={[
        {
          role: "system",
          content: [
            { type: "text", text: "You are a helpful cooking assistant." },
          ],
        },
        {
          role: "assistant",
          content: [
            { type: "text", text: "What would you like to cook today?" },
          ],
        },
      ]}
    >
      <Chat />
    </TamboProvider>
  );
}

interface TamboThreadMessage {
  id: string;
  role: MessageRole;
  content: Content[];
  createdAt?: string;
  metadata?: Record<string, unknown>;
  parentMessageId?: string;
  reasoning?: string[];
  reasoningDurationMS?: number;
}

type MessageRole = "user" | "assistant" | "system";

type Content =
  | TextContent
  | TamboComponentContent
  | TamboToolUseContent
  | ToolResultContent
  | ResourceContent;

interface TextContent {
  type: "text";
  text: string;
}

interface TamboComponentContent {
  type: "component";
  id: string;
  name: string;
  props: Record<string, unknown>;
  streamingState?: "started" | "streaming" | "done";
  renderedComponent?: ReactElement | null;
}

interface TamboToolUseContent {
  type: "tool_use";
  id: string;
  name: string;
  input: Record<string, unknown>;
  hasCompleted?: boolean;
  statusMessage?: string;
  tamboDisplayProps?: TamboToolDisplayProps;
}

interface TamboToolDisplayProps {
  _tambo_statusMessage?: string;
  _tambo_completionStatusMessage?: string;
}

interface ToolResultContent {
  type: "tool_result";
  toolUseId: string;
  content: Array<TextContent | ResourceContent>;
  isError?: boolean;
}

interface ResourceContent {
  type: "resource";
  uri: string;
  name?: string;
  mimeType?: string;
  text?: string;
}

interface TamboComponent {
  name: string;
  description: string;
  component: ComponentType<any>;
  propsSchema?: SupportedSchema;
  loadingComponent?: ComponentType<any>;
  associatedTools?: TamboTool[];
  annotations?: ToolAnnotations;
}

import { z } from "zod";

const WeatherCardSchema = z.object({
  city: z.string().describe("The city name"),
  temperature: z.number().describe("Temperature in Fahrenheit"),
  condition: z.string().describe("Weather condition"),
});

const components: TamboComponent[] = [
  {
    name: "WeatherCard",
    description: "Displays current weather for a city",
    component: WeatherCard,
    propsSchema: WeatherCardSchema,
  },
];

interface ComponentRendererProps {
  content: TamboComponentContent;
  threadId: string;
  messageId: string;
  fallback?: React.ReactNode;
}

interface TamboCurrentComponent {
  componentName?: string;
  props?: Record<string, unknown>;
  interactableId?: string;
  description?: string;
  threadId?: string;
}

interface ComponentContentContext {
  componentId: string;
  threadId: string;
  messageId: string;
  componentName: string;
}

interface TamboTool {
  name: string;
  description: string;
  title?: string;
  tool: (params: Record<string, unknown>) => unknown;
  inputSchema: SupportedSchema;
  outputSchema: SupportedSchema;
  transformToContent?: (result: any) => Promise<ContentPart[]> | ContentPart[];
  maxCalls?: number;
  annotations?: ToolAnnotations;
}

type TamboCustomEvent =
  | ComponentStartEvent
  | ComponentPropsDeltaEvent
  | ComponentStateDeltaEvent
  | ComponentEndEvent
  | RunAwaitingInputEvent
  | MessageParentEvent;

type ComponentStartEvent = {
  name: "tambo.component.start";
  value: {
    messageId: string;
    componentId: string;
    componentName: string;
  };
};

type ComponentPropsDeltaEvent = {
  name: "tambo.component.props_delta";
  value: {
    componentId: string;
    operations: Operation[];
  };
};

type ComponentStateDeltaEvent = {
  name: "tambo.component.state_delta";
  value: {
    componentId: string;
    operations: Operation[];
  };
};

type ComponentEndEvent = {
  name: "tambo.component.end";
  value: {
    componentId: string;
  };
};

type RunAwaitingInputEvent = {
  name: "tambo.run.awaiting_input";
  value: {
    pendingToolCalls: PendingToolCall[];
  };
};

interface PendingToolCall {
  toolCallId: string;
  toolName: string;
  arguments: string;
}

type MessageParentEvent = {
  name: "tambo.message.parent";
  value: {
    messageId: string;
    parentMessageId: string;
  };
};

function isTamboCustomEvent(event: {
  name?: string;
}): event is TamboCustomEvent;
function asTamboCustomEvent(event: CustomEvent): TamboCustomEvent | undefined;

interface SubmitOptions {
  debug?: boolean;
  toolChoice?: ToolChoice;
}

type ToolChoice = "auto" | "required" | "none" | { name: string };

interface StreamStatus {
  isPending: boolean;
  isStreaming: boolean;
  isSuccess: boolean;
  isError: boolean;
  streamError?: Error;
}

interface PropStatus {
  isPending: boolean;
  isStreaming: boolean;
  isSuccess: boolean;
  error?: Error;
}

type ToolAnnotations = MCPToolAnnotations & {
  tamboStreamableHint?: boolean;
};

interface TamboInteractableComponent<
  Props = Record<string, unknown>,
  State = Record<string, unknown>,
> extends TamboComponent {
  id: string;
  props: Props;
  isSelected?: boolean;
  state?: State;
  stateSchema?: SupportedSchema<State>;
}

interface InteractableConfig<
  Props = Record<string, unknown>,
  State = Record<string, unknown>,
> {
  componentName: string;
  description: string;
  propsSchema?: SupportedSchema<Props>;
  stateSchema?: SupportedSchema<State>;
  annotations?: ToolAnnotations;
}

interface WithTamboInteractableProps {
  interactableId?: string;
  onInteractableReady?: (id: string) => void;
  onPropsUpdate?: (newProps: Record<string, unknown>) => void;
}

interface StagedImage {
  id: string;
  name: string;
  dataUrl: string;
  file: File;
  size: number;
  type: string;
}

interface ResourceSource {
  listResources: (search?: string) => Promise<ListResourceItem[]>;
  getResource: (
    uri: string,
    args?: Record<string, unknown>,
  ) => Promise<ReadResourceResult>;
}