@mindstudio-ai/interface

Frontend SDK for MindStudio v2 app web interfaces.

Typed RPC to backend methods, file uploads, authentication, agent chat, and realtime voice — all from the browser. The core entry has zero dependencies; voice lives on the ./voice subpath and loads its media transport (livekit-client) only when a session starts.

Install

npm install @mindstudio-ai/interface

Usage

import { createClient, platform, auth, type AppUser } from '@mindstudio-ai/interface';

const api = createClient();

// Reactive auth state — re-renders on login/logout
function useAuth() {
  const [user, setUser] = useState<AppUser | null>(null);
  useEffect(() => auth.onAuthStateChanged(setUser), []);
  return user;
}

function App() {
  const user = useAuth();

  if (!user) return <LoginPage />;

  return <Dashboard user={user} />;
}

function Dashboard({ user }: { user: AppUser }) {
  const [data, setData] = useState(null);

  useEffect(() => {
    api.getDashboard().then(setData);
  }, []);

  return (
    <div>
      <p>Welcome, {user.email}</p>
      <button onClick={() => auth.logout()}>Log out</button>
    </div>
  );
}

API

createClient<T>()

Returns a typed RPC client. Each method maps to a backend route:

const api = createClient();

const result = await api.submitVendorRequest({ name: 'Acme' });
const dashboard = await api.getDashboard();

For type safety, pass an interface matching your backend routes:

import type { SubmitVendorInput } from '../../backend/src/submitVendorRequest';

interface AppRoutes {
  submitVendorRequest(input: SubmitVendorInput): Promise<{ vendorId: string }>;
  getDashboard(): Promise<DashboardData>;
}

const api = createClient<AppRoutes>();

platform.uploadFile(file)

Upload a file to the MindStudio CDN. Returns a public CDN URL.

const url = await platform.uploadFile(file);

auth

Authentication flows, user state, and validation helpers. The platform handles verification code delivery, cookie management, and user storage — you build the login UI.

Login flow

import { auth } from '@mindstudio-ai/interface';

// Send a verification code
const { verificationId } = await auth.sendEmailCode('[email protected]');

// User enters the code in your UI...
const user = await auth.verifyEmailCode(verificationId, code);
// Session is now active — all SDK calls use the authenticated token

SMS works the same way — use auth.sendSmsCode(phone) and auth.verifySmsCode(verificationId, code). Phone numbers must be E.164 format.

User state

auth.getCurrentUser()    // { id, email, phone, roles, createdAt } or null
auth.isAuthenticated()   // boolean
auth.currentVisitorId    // stable per-browser, per-app opaque ID (or null)
await auth.logout()      // clears session

currentVisitorId is a stable identifier for this browser on this app, backed by a server-set HttpOnly cookie. It's the user's platform user ID when authenticated, a per-browser UUID when not. Persists ~1 year and updates in-place on login/logout. Useful for app-side analytics, "welcome back" UX for guests, or per-visitor preferences stored in your app's data DB.

Phone helpers

Utilities for building a phone input with country code picker:

auth.phone.countries          // [{ code: 'US', dialCode: '+1', name: 'United States', flag: '🇺🇸' }, ...]
auth.phone.detectCountry()    // 'US' — guessed from timezone
auth.phone.toE164('5551234567', 'US')  // '+15551234567'
auth.phone.format('+15551234567')      // '+1 (555) 123-4567'
auth.phone.isValid('+15551234567')     // true
auth.email.isValid('[email protected]') // true

Email/phone change

Authenticated users can change their email or phone through a verification flow:

await auth.requestEmailChange('[email protected]');
await auth.confirmEmailChange('[email protected]', code);

API keys

Apps with api-key in their auth methods can let users generate keys for programmatic access:

const { key } = await auth.createApiKey();   // full key (sk_...), shown once
console.log(auth.currentUser?.apiKey);       // masked: "sk_...a1b2"

await auth.revokeApiKey();                   // apiKey becomes null

Both methods trigger onAuthStateChanged since the user's apiKey field changes.

Reactive auth state

onAuthStateChanged fires immediately with the current user, then again on every auth transition. Use it to build reactive UIs:

// React hook
function useAuth() {
  const [user, setUser] = useState<AppUser | null>(null);
  useEffect(() => auth.onAuthStateChanged(setUser), []);
  return user;
}

You can also read the current user synchronously via auth.currentUser.

Auth error codes

Auth methods throw MindStudioInterfaceError. Handle specific cases via err.code:

| Code | Status | Meaning | |------|--------|---------| | rate_limited | 429 | Too many code requests (max 5 per 15 min) | | invalid_code | 400 | Wrong verification code | | verification_expired | 400 | Code expired (10 min TTL) | | max_attempts_exceeded | 400 | Too many incorrect attempts (max 3) | | not_authenticated | 401 | No auth session (change/logout/api-key endpoints) | | invalid_session | 401 | Session expired or invalid | | not_supported | 400 | Feature not enabled (e.g. api-key auth not in app methods) |

try {
  await auth.verifyEmailCode(verificationId, code);
} catch (err) {
  if (err instanceof MindStudioInterfaceError) {
    if (err.code === 'invalid_code') {
      showError('Wrong code, try again');
    } else if (err.code === 'verification_expired') {
      showError('Code expired — sending a new one');
      await auth.sendEmailCode(email);
    }
  }
}

Session management

Verify, confirm, and logout methods update the SDK's internal session in-place. All downstream calls (method invocation, agent chat, uploads) immediately use the new authenticated (or unauthenticated) session. No page refresh needed.

createAgentChatClient()

Stateless client for thread-based conversations with AI agents. The agent runs server-side with access to your app's methods as tools.

Thread management

import { createAgentChatClient } from '@mindstudio-ai/interface';

const chat = createAgentChatClient();

const thread = await chat.createThread();
const { threads, nextCursor } = await chat.listThreads();
const full = await chat.getThread(thread.id);
await chat.updateThread(thread.id, 'New title');
await chat.deleteThread(thread.id);
await chat.claimThread(thread.id); // after in-app login: keep anonymous threads

// Paginate
const page2 = await chat.listThreads(nextCursor);

If the app's agent interface declares an auth block, createThread and sendMessage reject with MindStudioInterfaceError code auth_required (401, no authenticated user) or role_required (403, user lacks a required role) — route those to the app's login flow. createThread also throws no_agent_config (404) when the app has no live agent interface.

Sending messages

sendMessage streams the agent's response via SSE. Named callbacks handle common events; the catch-all onEvent receives everything as a discriminated union.

function ChatInput({ threadId }: { threadId: string }) {
  const [text, setText] = useState('');
  const [thinking, setThinking] = useState('');
  const [tools, setTools] = useState<Map<string, string>>(new Map());

  const send = (content: string) => {
    const response = chat.sendMessage(threadId, content, {
      // Text deltas — append, don't replace
      onText: (delta) => setText((prev) => prev + delta),

      // Extended thinking (also deltas)
      onThinking: (delta) => setThinking((prev) => prev + delta),
      onThinkingComplete: (thinking, signature) => setThinking(''),

      // Tool execution
      onToolCallStart: (id, name) =>
        setTools((m) => new Map(m).set(id, `Running ${name}...`)),
      onToolCallResult: (id, output) =>
        setTools((m) => new Map(m).set(id, JSON.stringify(output))),

      // Errors
      onError: (error) => console.error('Stream error:', error),

      // Catch-all for logging or low-level events (tool_use, tool_input_delta)
      onEvent: (event) => console.log(event.type, event),
    });

    // Resolves when stream completes
    response.then(({ stopReason, usage }) => {
      console.log(`Done: ${stopReason}, tokens: ${usage.inputTokens}+${usage.outputTokens}`);
    });

    // Cancel mid-stream
    // response.abort();
  };
}

Abort support

sendMessage returns an AbortablePromise — a standard Promise with an .abort() method. You can also pass an AbortSignal via the callbacks:

const controller = new AbortController();

const response = chat.sendMessage(threadId, content, {
  onText: (delta) => setText((prev) => prev + delta),
  signal: controller.signal,
});

// Either works:
response.abort();
controller.abort();

Attachments

Send images or documents alongside a message. Upload files first via platform.uploadFile(), then pass the CDN URLs:

const url = await platform.uploadFile(file);

chat.sendMessage(threadId, "What's in this document?", {
  onText: (delta) => setText((prev) => prev + delta),
}, {
  attachments: [url],
});

• Images (i.mscdn.ai): Sent to the model as vision input (one image per message)
• Documents (f.mscdn.ai): Text extracted server-side and included in context

Attachments are preserved in thread history — when you load a thread via getThread(), user messages include their original attachments array.

Client tools

A tool declared in agent.md with target: "client" runs in this browser instead of the app's backend. Register a handler and its return value goes back to the agent as the tool result, so the agent knows what happened instead of assuming:

const unregister = chat.registerClientTool('pickFile', async ({ prompt }) => {
  const file = await openFilePicker(prompt);
  return file ? { path: file.path } : { cancelled: true };
});

The agent holds its turn while your handler runs, for up to 15 minutes — long enough that a handler can resolve from a dialog's Save button rather than returning immediately, which is what makes confirm-before-acting possible:

chat.registerClientTool('confirmDeploy', ({ summary }) =>
  new Promise((resolve) => {
    showApprovalDialog(summary, {
      onApprove: (note) => resolve({ approved: true, note }),
      onReject: (reason) => resolve({ approved: false, reason }),
    });
  }),
);

The SDK always answers, so the agent is never left hanging: your return value, { error: <message> } if the handler throws, result_too_large past ~32KB serialized, and unhandled_client_tool immediately when no handler is registered for the name. If nothing answers within the window the agent gets client_timeout; closing the page gets it client_disconnected.

Handlers are keyed by tool name, live for the lifetime of the client rather than one message, and the returned function unregisters. For a one-off, the onClientToolCall callback on sendMessage works the same way — whatever it returns becomes the result — and is consulted only when no handler is registered for that name.

SSE event types

All events are available via the onEvent catch-all as the AgentChatEvent discriminated union:

| Event | Fields | Named callback | |-------|--------|----------------| | text | text (delta) | onText | | thinking | text (delta) | onThinking | | thinking_complete | thinking, signature | onThinkingComplete | | tool_call_start | id, name | onToolCallStart | | tool_call_result | id, output | onToolCallResult | | client_tool_call | id, name, input, timeoutMs | answered by registerClientTool | | error | error | onError | | tool_use | id, name, input | onEvent only | | tool_input_delta | id, name, delta | onEvent only | | done | stopReason, usage | resolves the Promise |

createVoiceClient()

Realtime voice sessions for apps with a voice interface. Imported from the ./voice subpath — the media transport (livekit-client) loads dynamically on the first startSession(), so apps that never use voice ship none of it.

import { createVoiceClient } from '@mindstudio-ai/interface/voice';

const voice = createVoiceClient();
const session = await voice.startSession();

session.on('stateChange', (state) => setOrbState(state));
// 'connecting' | 'listening' | 'thinking' | 'speaking' | 'ended'

session.on('transcript', ({ role, segmentId, text, final }) =>
  upsertCaption(segmentId, role, text, final),
); // full text per segment (never deltas); same segmentId replaces

session.on('toolCall', ({ method, status, result }) => {
  showToolStatus(method, status);
  // Every successful tool delivers its raw return value here on 'done' —
  // render what the agent just did in lockstep with speech. Over ~32KB
  // serialized arrives as `resultTruncated: true` instead.
  if (status === 'done' && result !== undefined) renderToolResult(method, result);
});

session.mute();
session.unmute();
await session.sendText('123 Main Street'); // exact strings beat spelling aloud
// Client tools (voice.md `target: "client"`): the agent invokes, your handler
// runs in this browser, and its return value goes back as the tool result.
session.registerClientTool('showVerification', async (args) => {
  openVerifySheet(args);
  return { opened: true };
});

// Progressive auth: after your in-app verification succeeds, upgrade the live
// session anonymous → signed-in in place (no teardown, conversation continues).
await session.refreshIdentity();
await session.end();

Agent audio playback is handled by the SDK (a hidden autoplaying element) — the app never touches audio elements. startSession() throws MindStudioInterfaceError with code microphone_denied when mic access is refused, voice_concurrency_limit / voice_visitor_limit when the app's session limits are hit, or auth_required (401) / role_required (403) when the voice interface's auth block denies the caller — route those to the app's login flow.

Past sessions are call records:

const { sessions, nextCursor } = await voice.listSessions();
const detail = await voice.getSession(sessions[0].id); // includes transcript

events

Server→client realtime. Backend code publishes to named channels (the agent SDK's events.publish); this client receives those publishes live over a platform-held SSE — no polling, no WebSockets. Authorization is a grant minted by one of the app's own backend methods, which is why connect takes a token provider: grants expire on purpose (expiry is the revocation window), and the SDK re-mints through your method on every expiry, re-running your auth checks.

import { createClient, events } from '@mindstudio-ai/interface';
const api = createClient();

const sub = events.connect({
  // Your backend method does its auth checks, then mints the grant:
  getToken: () => api.watchJobs().then((r) => r.token),

  // A publish on one of the grant's channels:
  onEvent: (e) => {
    if (e.channel.startsWith('jobs:')) refreshJob(e.data);
  },

  // Fires on EVERY (re)connect — refetch current state here.
  onConnect: () => refetchJobs(),

  // Terminal only: your getToken threw (logged out, role revoked).
  onError: (err) => showBanner(err.message),
});

sub.close(); // on unmount

Reconcile on connect. Events are at-most-once nudges: nothing is buffered while you're disconnected, nothing is replayed when you return. onConnect is where you refetch — a subscriber without it will silently miss whatever happened while it was away. Subscribe for speed, reconcile for truth.

Reconnects (network drops, grant expiry, deploys) are handled internally with backoff; the app sees them only as onConnect firing again. A getToken failure is deliberately terminal — it means your own method refused, and retrying an authorization refusal in a loop is wrong; call connect again when your auth state changes.

Error handling

import { MindStudioInterfaceError } from '@mindstudio-ai/interface';

try {
  await api.submitVendorRequest({ name: '' });
} catch (err) {
  if (err instanceof MindStudioInterfaceError) {
    console.error(err.message); // human-readable
    console.error(err.code);    // 'route_error', 'forbidden', etc.
    console.error(err.status);  // HTTP status
  }
}

How it works

The MindStudio platform injects window.__MINDSTUDIO__ into the page before your code runs. This contains the session token, authenticated user (or null), and method registry. The SDK reads this automatically — no configuration needed.

All API calls use same-origin /_/ paths (e.g. /_/methods/{id}/invoke, /_/agent/threads, /_/auth/email/send). The platform proxy resolves the app from the subdomain — no cross-origin requests or app IDs in URLs. This works identically in production and local dev.

Authentication is cookie-based (HttpOnly, Secure, SameSite=Lax). The SDK never touches the cookie directly — it's set by the server on verify and cleared on logout. Auth state transitions (login, logout, email/phone change) return a fresh session token which the SDK applies in-place, so all subsequent API calls use the new session without a page refresh.

Error reporting

Uncaught errors and unhandled promise rejections are automatically captured and shipped to the platform for bucketing + dashboards. No setup required — install happens when the SDK module loads. Reports include the error, a stack, and a breadcrumb trail of recent navigations + network calls for context.

React crashes need two lines

React does not tell the window about an error one of its error boundaries caught — onCaughtError defaults to console.error and nothing else. An app with an error boundary and no root hooks reports no render crashes at all, and those are the ones that white-screen an app. Wire React 19's root hooks and they come through with the component stack attached:

import { telemetry } from '@mindstudio-ai/interface';

createRoot(document.getElementById('root')!, {
  onUncaughtError: telemetry.reactErrorHandler(),
  onCaughtError: telemetry.reactErrorHandler(),
}).render(
  <ErrorBoundary>
    <App />
  </ErrorBoundary>,
);

Crashes reported this way are marked unhandled — a boundary existing is not evidence the app recovered. If yours renders a real fallback the user can carry on from, say so: telemetry.reactErrorHandler({ handled: true }).

Reporting something you caught

try {
  await api.submitOrder(order);
} catch (err) {
  telemetry.captureException(err);
  setError('Could not submit that order.');
}

Manual captures are marked handled by default, so they sort below real crashes in the dashboard.

Opt out per app via bootstrap config — this covers captureException too:

window.__MINDSTUDIO__.telemetry = { errors: false };

Failed-fetch breadcrumbs can optionally include response bodies (off by default; enable both client-side via window.__MINDSTUDIO__.telemetryCaptureResponseBodies = true and via the per-app setting in the dashboard).

Analytics

Visitor analytics — pageviews, referrers, UTMs, geo, devices — Plausible/Fathom style. Pageviews are tracked automatically on every history change (pushState, replaceState, popstate, hashchange). Server-side enrichment handles geo, UA parsing, UTM extraction, and sessionization. Aggregate visitor metrics are surfaced through the platform dashboard to the app owner.

import { analytics } from '@mindstudio-ai/interface';

// Custom events (optional — pageviews track automatically)
analytics.track('vendor_submitted', { vendorType: 'restaurant' });

Custom event props must be flat primitives (string | number | boolean) — non-primitive values are stripped client-side before send.

Opt out per app via bootstrap config:

window.__MINDSTUDIO__.telemetry = { analytics: false };

License

MIT