Ultrahost/ docs

@ultrahost/react sits on top of @ultrahost/sdk. The base client stays framework-independent. The React package adds session state, caching, cancellation, and loading flags.

Provider

tsx
import { createClient } from "@ultrahost/sdk";
import { UltrahostProvider } from "@ultrahost/react";

const ultrahost = createClient({
  projectId: "my-project",
  token: userAccessToken
});

export function AppRoot() {
  return (
    <UltrahostProvider client={ultrahost}>
      <App />
    </UltrahostProvider>
  );
}

The provider holds the user client. It does not accept an admin client. Privileged work stays on the server.

Hooks

HookPurpose
useAuth()Authentication state and actions
useUser()Current user profile
useSession()Current session
usePermissions()Permission checks for the interface
useDocument(collection, id)Retrieve one document
useDocuments(collection, query)Query documents
useMutation()Run a write and invalidate cached reads
useSearch(index, query)Full-text search
useVectorSearch(index, query)Semantic search
useTimeseries(metric, query)Read metrics
useFileUpload(bucket)Upload with progress, cancellation, and resume
useLLM(capability)Generate from a named capability
useLLMStream(capability)Stream a generation
useRAG(knowledgeBase)Grounded answers
useFunction(name)Invoke a function exposed to the client
useAgentSession(id)Agent session state

Auth also exposes the session directly:

tsx
const { user, loading, signIn, signOut } = useAuth();

The SDK owns OAuth redirects, token refresh, and session storage. Application code does not integrate each identity provider itself. See Federated Auth.

Read a collection

tsx
function Projects() {
  const { data, loading, error } = useDocuments("projects", {
    filter: { status: "active" }
  });

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Unable to load projects.</p>;

  return (
    <ul>
      {data.map((project) => (
        <li key={project.id}>{project.name}</li>
      ))}
    </ul>
  );
}

After a mutation, the hook cache invalidates the queries that read the same resource. The component does not manually refetch unless it wants to.

What stays on the server

usePermissions() and authorization.check() can hide controls the user cannot use. They are not the authorization decision. The API enforces that when the request arrives.

useLLM() calls a named capability. It cannot pick an arbitrary provider model or raise a budget. useFunction() can invoke functions that were exposed to the client, not deploy code or set secrets.