@mindstudio-ai/interface 0.1.0

package/README.md

@@ -0,0 +1,229 @@
+# @mindstudio-ai/interface
+
+Frontend SDK for [MindStudio](https://mindstudio.ai) v2 app web interfaces.
+
+Typed RPC to backend methods, file uploads, agent chat, and user context — all from the browser. Zero dependencies.
+
+## Install
+
+```bash
+npm install @mindstudio-ai/interface
+```
+
+## Usage
+
+```tsx
+import { createClient, platform, auth } from '@mindstudio-ai/interface';
+
+const api = createClient();
+
+function App() {
+  const [dashboard, setDashboard] = useState(null);
+
+  useEffect(() => {
+    api.getDashboard().then(setDashboard);
+  }, []);
+
+  const handleUpload = async (file: File) => {
+    const url = await platform.uploadFile(file);
+    // use the CDN url...
+  };
+
+  return (
+    <div>
+      <p>Welcome, {auth.name}</p>
+      <img src={auth.profilePictureUrl} />
+      <input type="file" onChange={(e) => handleUpload(e.target.files[0])} />
+    </div>
+  );
+}
+```
+
+## API
+
+### `createClient<T>()`
+
+Returns a typed RPC client. Each method maps to a backend route:
+
+```ts
+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:
+
+```ts
+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.
+
+```ts
+const url = await platform.uploadFile(file);
+```
+
+### `auth`
+
+Current user's identity (read-only, synchronous):
+
+```ts
+auth.userId             // "uuid"
+auth.name               // "Sean"
+auth.email              // "sean@example.com"
+auth.profilePictureUrl  // "https://..." or null
+```
+
+For display purposes only. Role checking and permissions are handled by backend routes using `@mindstudio-ai/agent`.
+
+### `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
+
+```ts
+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);
+
+// Paginate
+const page2 = await chat.listThreads(nextCursor);
+```
+
+#### 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.
+
+```tsx
+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:
+
+```ts
+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:
+
+```ts
+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.
+
+#### 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` |
+| `error` | `error` | `onError` |
+| `tool_use` | `id`, `name`, `input` | `onEvent` only |
+| `tool_input_delta` | `id`, `name`, `delta` | `onEvent` only |
+| `done` | `stopReason`, `usage` | resolves the Promise |
+
+## Error handling
+
+```ts
+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, user info, 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`). 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.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,668 @@
+/**
+ * Method RPC client — typed function calls to backend methods.
+ *
+ * `createClient()` returns a Proxy where every property access creates
+ * an async function that invokes the corresponding backend method via HTTP.
+ * The method name matches the method's `export` field in `app.json`.
+ *
+ * ## How it works
+ *
+ * ```
+ * api.submitVendorRequest({ name: 'Acme' })
+ *   │
+ *   ├─ Look up method ID: config.methods["submitVendorRequest"]
+ *   │  → "submit-vendor-request"
+ *   │
+ *   ├─ POST /_/methods/submit-vendor-request/invoke
+ *   │  Authorization: Bearer {session token}
+ *   │  Body: { input: { name: "Acme" } }
+ *   │
+ *   └─ Returns response.output (or throws on error)
+ * ```
+ *
+ * The method registry (export name → method ID mapping) is embedded in
+ * `window.__MINDSTUDIO__.methods` at page load time — no extra HTTP call
+ * needed to discover methods.
+ *
+ * ## Streaming
+ *
+ * Methods can optionally stream LLM token output via SSE. Pass
+ * `{ stream: true }` as the second argument along with an `onToken`
+ * callback to receive incremental updates:
+ *
+ * ```ts
+ * const result = await api.submitVendorRequest({ name: 'Acme' }, {
+ *   stream: true,
+ *   onToken: (text) => setResponseText(text),
+ * });
+ * ```
+ *
+ * **Important:** The `text` value passed to `onToken` is the accumulated
+ * response so far (not a delta). Replace your display content each time —
+ * do not append. See {@link InvokeOptions.onToken} for details.
+ *
+ * ## Type safety
+ *
+ * Since the frontend and backend live in the same project, you can import
+ * types directly:
+ *
+ * ```ts
+ * import type { SubmitVendorInput, SubmitVendorOutput }
+ *   from '../../backend/src/submitVendorRequest';
+ *
+ * interface AppMethods {
+ *   submitVendorRequest(input: SubmitVendorInput): Promise<SubmitVendorOutput>;
+ *   getDashboard(): Promise<GetDashboardOutput>;
+ * }
+ *
+ * const api = createClient<AppMethods>();
+ * const result = await api.submitVendorRequest({ name: 'Acme' }); // fully typed
+ * ```
+ *
+ * If no type parameter is provided, methods accept `any` input and return `any`.
+ */
+/**
+ * Options for method invocation. Pass as the optional second argument to
+ * any method on the client returned by {@link createClient}.
+ *
+ * When `stream` is `true`, the SDK sends `{ stream: true }` in the request
+ * body and parses the response as an SSE (Server-Sent Events) stream.
+ * Three event types are handled:
+ *
+ * | SSE `type` | Payload field | SDK action |
+ * |------------|---------------|------------|
+ * | `token`    | `text`        | Calls {@link onToken} with accumulated text |
+ * | `error`    | `error`       | Calls {@link onStreamError} with the message |
+ * | `done`     | `output`      | Captures as the method's return value |
+ *
+ * The method's `Promise` resolves with the final `output` from the `done`
+ * event — the same shape you'd get without streaming.
+ */
+interface InvokeOptions {
+    /**
+     * Enable SSE streaming for LLM token output.
+     *
+     * When `true`, the request body includes `{ stream: true }` and the
+     * response is parsed as an SSE stream instead of a single JSON payload.
+     * The method still returns a `Promise` that resolves with the final
+     * output once the stream completes.
+     *
+     * @default false
+     */
+    stream?: boolean;
+    /**
+     * Called with the accumulated response text each time a new token arrives.
+     *
+     * **Important:** `text` is the full response so far, not a delta/chunk.
+     * Your frontend should **replace** (not append to) its display content
+     * with this value each time the callback fires.
+     *
+     * This design avoids edge cases where the platform sanitizes or
+     * reformats JSON mid-stream, causing earlier portions of the text to
+     * change between tokens.
+     *
+     * @example
+     * ```ts
+     * const result = await api.generate({ prompt: 'Hello' }, {
+     *   stream: true,
+     *   onToken: (text) => {
+     *     // Replace — do NOT append
+     *     responseElement.textContent = text;
+     *   },
+     * });
+     * ```
+     */
+    onToken?: (text: string) => void;
+    /**
+     * Called if a stream-level error occurs.
+     *
+     * Stream errors are non-fatal at the protocol level — the method may
+     * still complete and resolve with a final output. Use this callback for
+     * logging or showing a transient warning, not for control flow.
+     *
+     * If the stream ends without a `done` event, the method rejects with a
+     * `MindStudioInterfaceError` (code `stream_incomplete`) regardless of
+     * whether `onStreamError` was provided.
+     */
+    onStreamError?: (error: string) => void;
+}
+/**
+ * Default client type when no generic parameter is provided.
+ * Every property returns an async function accepting optional input
+ * and optional {@link InvokeOptions} for streaming.
+ */
+type DefaultMethodClient = Record<string, (input?: Record<string, unknown>, options?: InvokeOptions) => Promise<unknown>>;
+/**
+ * Create a typed RPC client for calling backend methods.
+ *
+ * @typeParam T - Optional interface mapping method names to their signatures.
+ *   If omitted, all methods accept `any` and return `Promise<any>`.
+ *
+ * @returns A Proxy object where each property is an async function that
+ *   invokes the corresponding backend method.
+ *
+ * @example
+ * ```ts
+ * import { createClient } from '@mindstudio-ai/interface';
+ *
+ * const api = createClient();
+ *
+ * // Each method maps to a backend method export
+ * const result = await api.submitVendorRequest({ name: 'Acme' });
+ * const dashboard = await api.getDashboard();
+ *
+ * // Stream LLM output — onToken receives accumulated text (replace, don't append)
+ * const streamed = await api.submitVendorRequest({ name: 'Acme' }, {
+ *   stream: true,
+ *   onToken: (text) => setResponseText(text),
+ * });
+ * // `streamed` is the same final output you'd get without streaming
+ * ```
+ */
+declare function createClient<T = DefaultMethodClient>(): T;
+
+/**
+ * Agent chat client — thread-based conversations with AI agents.
+ *
+ * `createAgentChatClient()` returns an object with methods for thread
+ * lifecycle (create, list, get, rename, delete) and message streaming.
+ * The agent runs server-side with access to the app's methods as tools.
+ *
+ * ## How it works
+ *
+ * ```
+ * chat.sendMessage(threadId, 'Help me prep for my review', {
+ *   onText: (delta) => setAssistantMessage((prev) => prev + delta),
+ * })
+ *   │
+ *   ├─ POST /_/agent/threads/{threadId}/messages
+ *   │  Authorization: Bearer {session token}
+ *   │  Body: { content: "Help me prep for my review" }
+ *   │
+ *   ├─ Response: SSE stream
+ *   │  data: {"type":"text","text":"I'll create...","ts":1711...}
+ *   │  data: {"type":"tool_call_start","id":"call_abc","name":"create-todo","ts":1711...}
+ *   │  data: {"type":"tool_call_result","id":"call_abc","output":{...},"ts":1711...}
+ *   │  data: {"type":"text","text":"Done — added it.","ts":1711...}
+ *   │  data: {"type":"done","stopReason":"end_turn","usage":{...},"ts":1711...}
+ *   │
+ *   └─ Promise resolves with { stopReason, usage }
+ * ```
+ *
+ * ## Stateless design
+ *
+ * This client is a thin wrapper over HTTP endpoints. It does not manage
+ * local state — your React/framework layer owns the thread list, message
+ * array, and UI state. Each method is an independent request.
+ *
+ * ## Streaming callbacks
+ *
+ * `sendMessage` accepts named callbacks for common events (onText,
+ * onThinking, onToolCallStart, etc.) plus a catch-all `onEvent` that
+ * receives every SSE event as a discriminated union. Both fire for the
+ * same event — use named callbacks for convenience, `onEvent` for
+ * logging or handling low-level events like `tool_use` and
+ * `tool_input_delta`.
+ *
+ * @example
+ * ```ts
+ * import { createAgentChatClient } from '@mindstudio-ai/interface';
+ *
+ * const chat = createAgentChatClient();
+ *
+ * // Thread lifecycle
+ * const thread = await chat.createThread();
+ * const { threads } = await chat.listThreads();
+ * const full = await chat.getThread(thread.id);
+ *
+ * // Send a message with streaming
+ * const response = chat.sendMessage(thread.id, 'Hello!', {
+ *   onText: (delta) => setMessage((prev) => prev + delta),
+ *   onToolCallStart: (id, name) => showToolSpinner(name),
+ *   onToolCallResult: (id, output) => showToolResult(output),
+ * });
+ *
+ * const { stopReason, usage } = await response;
+ *
+ * // Abort mid-stream
+ * response.abort();
+ * ```
+ */
+/** Thread summary returned from create and list endpoints. */
+interface ThreadSummary {
+    /** Thread ID (UUID). */
+    id: string;
+    /** User-editable title, auto-generated on first message. */
+    title: string | null;
+    /** ISO 8601 creation timestamp. */
+    dateCreated: string;
+    /** ISO 8601 last-updated timestamp. */
+    dateUpdated: string;
+}
+/** Full thread with message history, returned from get endpoint. */
+interface Thread {
+    /** Thread ID (UUID). */
+    id: string;
+    /** User-editable title. */
+    title: string | null;
+    /** Full conversation history. */
+    messages: Message[];
+    /** ISO 8601 creation timestamp. */
+    dateCreated: string;
+    /** ISO 8601 last-updated timestamp. */
+    dateUpdated: string;
+}
+/** A tool call requested by the assistant. */
+interface ToolCall {
+    /** Tool call ID, used to match results. */
+    id: string;
+    /** Method name. */
+    name: string;
+    /** Input arguments. */
+    input: Record<string, unknown>;
+}
+/** A single message in a thread's conversation history. */
+interface Message {
+    /** `"user"` for human messages, `"assistant"` for agent responses. */
+    role: 'user' | 'assistant';
+    /** Message text content. For tool results, this is JSON-stringified output. */
+    content: string;
+    /**
+     * MindStudio CDN URLs attached to this message (user messages only).
+     *
+     * Images (`i.mscdn.ai`) are sent to the model as vision input.
+     * Documents (`f.mscdn.ai`, `files.mindstudio-cdn.com`) have their text
+     * extracted server-side and included in the model context. The original
+     * URLs are preserved in thread history for the frontend to render.
+     */
+    attachments?: string[];
+    /** Tool calls the assistant requested (assistant messages only). */
+    toolCalls?: ToolCall[];
+    /** ID of the tool call this message is a result for (tool result messages only). */
+    toolCallId?: string;
+    /** Whether this tool result represents an error. */
+    isToolError?: boolean;
+}
+/** Paginated thread list response. */
+interface ThreadListPage {
+    /** Threads for this page. */
+    threads: ThreadSummary[];
+    /** Cursor for the next page, or `null` if this is the last page. */
+    nextCursor: string | null;
+}
+/** Assistant text delta — append to your display string, do not replace. */
+interface AgentTextEvent {
+    type: 'text';
+    text: string;
+    ts: number;
+}
+/** Model thinking text (extended thinking). */
+interface AgentThinkingEvent {
+    type: 'thinking';
+    text: string;
+    ts: number;
+}
+/** Thinking complete with full text and signature. */
+interface AgentThinkingCompleteEvent {
+    type: 'thinking_complete';
+    thinking: string;
+    signature: string;
+    ts: number;
+}
+/** Model requested a tool call (includes parsed input). */
+interface AgentToolUseEvent {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+    ts: number;
+}
+/** Streaming delta for tool call input JSON. */
+interface AgentToolInputDeltaEvent {
+    type: 'tool_input_delta';
+    id: string;
+    name: string;
+    delta: string;
+    ts: number;
+}
+/** Agent began executing a tool call. */
+interface AgentToolCallStartEvent {
+    type: 'tool_call_start';
+    id: string;
+    name: string;
+    ts: number;
+}
+/** Tool call returned a result. */
+interface AgentToolCallResultEvent {
+    type: 'tool_call_result';
+    id: string;
+    output: unknown;
+    ts: number;
+}
+/** Stream complete. */
+interface AgentDoneEvent {
+    type: 'done';
+    stopReason: string;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    ts: number;
+}
+/** Stream-level error. */
+interface AgentErrorEvent {
+    type: 'error';
+    error: string;
+    ts: number;
+}
+/** Discriminated union of all SSE events from the agent chat stream. */
+type AgentChatEvent = AgentTextEvent | AgentThinkingEvent | AgentThinkingCompleteEvent | AgentToolUseEvent | AgentToolInputDeltaEvent | AgentToolCallStartEvent | AgentToolCallResultEvent | AgentDoneEvent | AgentErrorEvent;
+/**
+ * Callbacks for `sendMessage` streaming.
+ *
+ * Named callbacks fire for common events. The catch-all `onEvent` fires
+ * for every event including those with named callbacks — use it for
+ * logging or handling low-level events like `tool_use` and
+ * `tool_input_delta`.
+ */
+interface SendMessageCallbacks {
+    /**
+     * Called with each text delta as the assistant responds.
+     *
+     * **Important:** `text` is a delta (new chunk), not the accumulated
+     * response. Append it to your display string — do not replace.
+     *
+     * @example
+     * ```ts
+     * onText: (delta) => setMessage((prev) => prev + delta)
+     * ```
+     */
+    onText?: (text: string) => void;
+    /** Called with model thinking text (extended thinking). */
+    onThinking?: (text: string) => void;
+    /** Called when thinking is complete. */
+    onThinkingComplete?: (thinking: string, signature: string) => void;
+    /** Called when a tool call begins executing. */
+    onToolCallStart?: (id: string, name: string) => void;
+    /** Called when a tool call produces a result. */
+    onToolCallResult?: (id: string, output: unknown) => void;
+    /** Called on a stream-level error event. */
+    onError?: (error: string) => void;
+    /** Called for every SSE event (including ones with named callbacks). */
+    onEvent?: (event: AgentChatEvent) => void;
+    /** AbortSignal to cancel the stream. */
+    signal?: AbortSignal;
+}
+/** Options for `sendMessage`. */
+interface SendMessageOptions {
+    /**
+     * MindStudio CDN URLs to attach to the message.
+     *
+     * Images (`i.mscdn.ai`) are sent to the model as vision input (one per message).
+     * Documents (`f.mscdn.ai`, `files.mindstudio-cdn.com`) have their text
+     * extracted server-side and included in context.
+     *
+     * Upload files first via `platform.uploadFile()`.
+     *
+     * @example
+     * ```ts
+     * const url = await platform.uploadFile(file);
+     * chat.sendMessage(threadId, 'What is this?', callbacks, {
+     *   attachments: [url],
+     * });
+     * ```
+     */
+    attachments?: string[];
+}
+/** Resolved value of `sendMessage` — extracted from the `done` event. */
+interface SendMessageResult {
+    /** Why the agent stopped (`"end_turn"`, `"max_tokens"`, etc.). */
+    stopReason: string;
+    /** Token usage for the full agent loop. */
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+/** A Promise with an `abort()` method for cancelling the stream. */
+type AbortablePromise<T> = Promise<T> & {
+    /** Cancel the in-flight stream. The promise rejects with `AbortError`. */
+    abort: () => void;
+};
+/** Agent chat client returned by {@link createAgentChatClient}. */
+interface AgentChatClient {
+    /** Create a new conversation thread. */
+    createThread(): Promise<ThreadSummary>;
+    /** List threads with cursor-based pagination (50 per page). */
+    listThreads(cursor?: string): Promise<ThreadListPage>;
+    /** Get a thread with its full message history. */
+    getThread(threadId: string): Promise<Thread>;
+    /** Update a thread's title. */
+    updateThread(threadId: string, title: string): Promise<void>;
+    /** Delete a thread (soft delete). */
+    deleteThread(threadId: string): Promise<void>;
+    /**
+     * Send a message and stream the agent's response.
+     *
+     * Returns an {@link AbortablePromise} that resolves with
+     * `{ stopReason, usage }` when the stream completes. Call `.abort()`
+     * on the returned promise to cancel mid-stream.
+     *
+     * @param options.attachments - MindStudio CDN URLs to attach.
+     *   Images (`i.mscdn.ai`) are sent as vision input.
+     *   Documents (`f.mscdn.ai`) have text extracted into context.
+     *   Upload files first via `platform.uploadFile()`.
+     */
+    sendMessage(threadId: string, content: string, callbacks?: SendMessageCallbacks, options?: SendMessageOptions): AbortablePromise<SendMessageResult>;
+}
+/**
+ * Create an agent chat client for thread-based conversations.
+ *
+ * The client is stateless — each method is an independent HTTP request.
+ * Your application layer owns thread state, message arrays, and UI updates.
+ *
+ * @returns An {@link AgentChatClient} with methods for thread CRUD and
+ *   message streaming.
+ *
+ * @example
+ * ```ts
+ * import { createAgentChatClient } from '@mindstudio-ai/interface';
+ *
+ * const chat = createAgentChatClient();
+ *
+ * const thread = await chat.createThread();
+ *
+ * const response = chat.sendMessage(thread.id, 'Hello!', {
+ *   onText: (delta) => setAssistantMessage((prev) => prev + delta),
+ *   onToolCallStart: (id, name) => showToolSpinner(name),
+ *   onToolCallResult: (id, output) => showToolResult(output),
+ * });
+ *
+ * const { stopReason, usage } = await response;
+ * ```
+ */
+declare function createAgentChatClient(): AgentChatClient;
+
+/**
+ * Platform actions — file uploads via presigned S3 POST.
+ *
+ * Uses the session token from `window.__MINDSTUDIO__` to request a
+ * presigned upload URL from the platform, then uploads directly to S3.
+ * Returns the public CDN URL.
+ *
+ * @example
+ * ```ts
+ * import { platform } from '@mindstudio-ai/interface';
+ *
+ * const file = document.querySelector('input[type=file]').files[0];
+ * const url = await platform.uploadFile(file);
+ *
+ * // With progress and abort
+ * const controller = new AbortController();
+ * const url = await platform.uploadFile(file, {
+ *   onProgress: (fraction) => console.log(`${Math.round(fraction * 100)}%`),
+ *   signal: controller.signal,
+ * });
+ * ```
+ */
+/**
+ * Options for `platform.uploadFile()`.
+ */
+interface UploadFileOptions {
+    /** Called with upload progress as a fraction from 0 to 1. */
+    onProgress?: (fraction: number) => void;
+    /** AbortSignal to cancel the upload. */
+    signal?: AbortSignal;
+}
+/**
+ * The platform namespace — file upload actions.
+ */
+declare const platform: {
+    /**
+     * Upload a file to the MindStudio CDN.
+     *
+     * Requests a presigned upload URL from the platform, then uploads
+     * the file directly to S3. Returns the public CDN URL.
+     *
+     * @param file - The File to upload
+     * @param options - Optional progress callback and abort signal
+     * @returns CDN URL of the uploaded file
+     *
+     * @example
+     * ```ts
+     * const url = await platform.uploadFile(file);
+     *
+     * // With progress
+     * const url = await platform.uploadFile(file, {
+     *   onProgress: (f) => setProgress(f),
+     * });
+     *
+     * // With abort
+     * const controller = new AbortController();
+     * const url = await platform.uploadFile(file, {
+     *   signal: controller.signal,
+     * });
+     * // controller.abort() to cancel
+     * ```
+     */
+    uploadFile(file: File, options?: UploadFileOptions): Promise<string>;
+};
+
+/**
+ * Auth context — current user's identity for display purposes.
+ *
+ * Provides synchronous access to the current user's name, email, and
+ * profile picture. Hydrated from the bootstrap globals injected by the
+ * platform — no HTTP call needed.
+ *
+ * This is for **display only**. Role checking, permission enforcement,
+ * and user lookups for other users are backend concerns — the frontend
+ * calls backend methods that handle those via `@mindstudio-ai/agent`'s
+ * `auth` namespace.
+ *
+ * @example
+ * ```ts
+ * import { auth } from '@mindstudio-ai/interface';
+ *
+ * return (
+ *   <div>
+ *     <p>Welcome, {auth.name}</p>
+ *     <img src={auth.profilePictureUrl} />
+ *   </div>
+ * );
+ * ```
+ */
+/**
+ * User identity context. All properties are read-only and synchronous.
+ */
+interface AuthContext {
+    /** Current user's ID (UUID). */
+    readonly userId: string;
+    /** Current user's display name. */
+    readonly name: string;
+    /** Current user's email address. */
+    readonly email: string;
+    /** Current user's profile picture URL, or null if not set. */
+    readonly profilePictureUrl: string | null;
+}
+/**
+ * Lazy auth proxy — reads from bootstrap globals on first property access.
+ *
+ * Using a Proxy lets us export `auth` as a module-level constant while
+ * deferring the `getConfig()` call until the first property is accessed.
+ * This avoids throwing during import if the page hasn't finished loading
+ * the bootstrap script yet.
+ */
+declare const auth: AuthContext;
+
+/**
+ * Error class for the @mindstudio-ai/interface SDK.
+ *
+ * Thrown by `createClient()` method calls on HTTP errors, by `platform`
+ * actions on failures, and by the config reader when bootstrap globals
+ * are missing.
+ */
+declare class MindStudioInterfaceError extends Error {
+    /** Machine-readable error code (e.g. 'method_not_found', 'not_initialized'). */
+    readonly code: string;
+    /** HTTP status code, when the error originated from an API response. */
+    readonly status?: number;
+    constructor(message: string, code: string, status?: number);
+}
+
+/**
+ * Type definitions for the @mindstudio-ai/interface SDK.
+ *
+ * These types describe the bootstrap globals injected by the platform,
+ * the user context, and options for platform actions.
+ */
+/**
+ * Bootstrap configuration injected into the page by the MindStudio
+ * platform before the app's JavaScript runs.
+ *
+ * Available at `window.__MINDSTUDIO__`. The SDK reads this automatically —
+ * app code should use `createClient()`, `auth`, and `platform` instead
+ * of accessing this directly.
+ *
+ * Injection mechanism: The Cloudflare Worker on `*.static.mscdn.ai`
+ * intercepts requests for `index.html`, injects a `<script>` tag with
+ * the session context, and returns the modified HTML.
+ */
+interface BootstrapConfig {
+    /** Short-lived session token scoped to this app + user. */
+    token: string;
+    /** App ID (optional — not needed for API calls, resolved from subdomain). */
+    appId?: string;
+    /** Current release ID. */
+    releaseId: string;
+    /** API base URL (optional — SDK uses same-origin `/_/` paths). */
+    apiBaseUrl?: string;
+    /** Resolved user fragment — display info for the current user. */
+    user: BootstrapUser;
+    /**
+     * Method registry mapping export names to method IDs.
+     * Embedded at injection time from the release manifest.
+     *
+     * @example
+     * ```
+     * { "submitVendorRequest": "submit-vendor-request", "getDashboard": "get-dashboard" }
+     * ```
+     */
+    methods: Record<string, string>;
+}
+/**
+ * Resolved user fragment. Includes display info so apps can render
+ * personalized UI immediately without an extra API call.
+ */
+interface BootstrapUser {
+    /** User ID (UUID). */
+    id: string;
+    /** Display name. */
+    name: string;
+    /** Email address. */
+    email: string;
+    /** Profile picture URL, if set. */
+    profilePictureUrl?: string;
+}
+
+export { type AbortablePromise, type AgentChatClient, type AgentChatEvent, type AuthContext, type BootstrapConfig, type BootstrapUser, type InvokeOptions, type Message, MindStudioInterfaceError, type SendMessageCallbacks, type SendMessageOptions, type SendMessageResult, type Thread, type ThreadListPage, type ThreadSummary, type UploadFileOptions, auth, createAgentChatClient, createClient, platform };

package/dist/index.js

@@ -0,0 +1,4 @@
+var s=class extends Error{code;status;constructor(t,n,i){super(t),this.name="MindStudioInterfaceError",this.code=n,this.status=i}};var k;function h(){if(k)return k;let e=globalThis.__MINDSTUDIO__;if(!e)throw new s("@mindstudio-ai/interface requires the MindStudio platform context. This page must be loaded inside MindStudio (window.__MINDSTUDIO__ is missing).","not_initialized");if(!e.token||!e.releaseId||!e.user||!e.methods){let t=["token","releaseId","user","methods"].filter(n=>!e[n]).join(", ");throw new s(`MindStudio platform context is incomplete. Missing: ${t}`,"invalid_config")}return k=e,k}function v(){return new Proxy({},{get(e,t){return async(n,i)=>{let a=h(),o=a.methods[t];if(!o)throw new s(`Method "${t}" not found. Available methods: ${Object.keys(a.methods).join(", ")||"(none)"}`,"method_not_found");let r=`/_/methods/${o}/invoke`,l=i?.stream===!0,d=await fetch(r,{method:"POST",headers:{"Content-Type":"application/json",Authorization:`Bearer ${a.token}`},body:JSON.stringify({input:n??{},...l&&{stream:!0}})});if(!d.ok){let p=`Method "${t}" failed: ${d.status} ${d.statusText}`,T="method_error";try{let g=await d.json();g.error&&(p=g.error),g.code&&(T=g.code)}catch{}throw new s(p,T,d.status)}if(!l)return(await d.json()).output;let w=d.body.getReader(),u=new TextDecoder,f="",y;for(;;){let{done:p,value:T}=await w.read();if(p)break;f+=u.decode(T,{stream:!0});let g=f.split(`
+`);f=g.pop()??"";for(let b of g){if(!b.startsWith("data: "))continue;let m=b.slice(6);try{let c=JSON.parse(m);c.type==="token"&&i?.onToken&&c.text?i.onToken(c.text):c.type==="error"&&c.error?i?.onStreamError&&i.onStreamError(c.error):c.type==="done"&&(y=c.output)}catch{}}}if(y===void 0)throw new s("Stream ended without a done event","stream_incomplete");return y}}})}var S="/_/agent";async function x(e,t,n){let a={Authorization:`Bearer ${h().token}`};n!==void 0&&(a["Content-Type"]="application/json");let o=await fetch(`${S}${e}`,{method:t,headers:a,...n!==void 0&&{body:JSON.stringify(n)}});if(!o.ok){let r=`Agent chat request failed: ${o.status} ${o.statusText}`,l="agent_chat_error";try{let d=await o.json();d.error&&(r=d.error),d.code&&(l=d.code)}catch{}throw new s(r,l,o.status)}return await o.json()}function A(e,t){switch(t.onEvent?.(e),e.type){case"text":t.onText?.(e.text);break;case"thinking":t.onThinking?.(e.text);break;case"thinking_complete":t.onThinkingComplete?.(e.thinking,e.signature);break;case"tool_call_start":t.onToolCallStart?.(e.id,e.name);break;case"tool_call_result":t.onToolCallResult?.(e.id,e.output);break;case"error":t.onError?.(e.error);break}}function _(){return{createThread(){return x("/threads","POST")},listThreads(e){let t=e?`?cursor=${encodeURIComponent(e)}`:"";return x(`/threads${t}`,"GET")},getThread(e){return x(`/threads/${e}`,"GET")},async updateThread(e,t){await x(`/threads/${e}`,"PATCH",{title:t})},async deleteThread(e){await x(`/threads/${e}`,"DELETE")},sendMessage(e,t,n,i){let a=new AbortController,o=n??{};o.signal&&(o.signal.aborted?a.abort():o.signal.addEventListener("abort",()=>a.abort(),{once:!0}));let l=(async()=>{let d=h(),w=`${S}/threads/${e}/messages`,u=await fetch(w,{method:"POST",headers:{"Content-Type":"application/json",Authorization:`Bearer ${d.token}`},body:JSON.stringify({content:t,...i?.attachments?.length&&{attachments:i.attachments}}),signal:a.signal});if(!u.ok){let g=`Send message failed: ${u.status} ${u.statusText}`,b="agent_chat_error";try{let m=await u.json();m.error&&(g=m.error),m.code&&(b=m.code)}catch{}throw new s(g,b,u.status)}let f=u.body.getReader(),y=new TextDecoder,p="",T;for(;;){let{done:g,value:b}=await f.read();if(g)break;p+=y.decode(b,{stream:!0});let m=p.split(`
+`);p=m.pop()??"";for(let c of m){if(!c.startsWith("data: "))continue;let E=c.slice(6);try{let C=JSON.parse(E);C.type==="done"&&(T={stopReason:C.stopReason,usage:C.usage}),A(C,o)}catch{}}}if(!T)throw new s("Stream ended without a done event","stream_incomplete");return T})();return l.abort=()=>a.abort(),l}}}var M={async uploadFile(e,t){let n=h(),{onProgress:i,signal:a}=t??{};a?.throwIfAborted();let r=await fetch("/_/generate-upload-request",{method:"POST",headers:{Authorization:`Bearer ${n.token}`,"Content-Type":"application/json"},body:JSON.stringify({filename:e.name,contentType:e.type||"application/octet-stream"}),signal:a});if(!r.ok)throw new s(`Upload presign failed: ${r.status} ${r.statusText}`,"upload_error",r.status);let{uploadUrl:l,uploadFields:d,publicUrl:w}=await r.json(),u=new FormData;for(let[y,p]of Object.entries(d))u.append(y,p);if(u.append("file",e),i)return await P(l,u,i,a),w;let f=await fetch(l,{method:"POST",body:u,signal:a});if(!f.ok)throw new s(`File upload failed: ${f.status} ${f.statusText}`,"upload_error",f.status);return w}};function P(e,t,n,i){return new Promise((a,o)=>{let r=new XMLHttpRequest;if(r.upload.addEventListener("progress",l=>{l.lengthComputable&&n(l.loaded/l.total)}),r.addEventListener("load",()=>{r.status>=200&&r.status<300?(n(1),a()):o(new s(`File upload failed: ${r.status} ${r.statusText}`,"upload_error",r.status))}),r.addEventListener("error",()=>{o(new s("File upload failed: network error","upload_error"))}),r.addEventListener("abort",()=>{o(new DOMException("Upload aborted","AbortError"))}),i){if(i.aborted){o(new DOMException("Upload aborted","AbortError"));return}i.addEventListener("abort",()=>r.abort(),{once:!0})}r.open("POST",e),r.send(t)})}var O=new Proxy({},{get(e,t){let{user:n}=h();switch(t){case"userId":return n.id;case"name":return n.name;case"email":return n.email;case"profilePictureUrl":return n.profilePictureUrl??null;default:return}}});export{s as MindStudioInterfaceError,O as auth,_ as createAgentChatClient,v as createClient,M as platform};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/config.ts","../src/client.ts","../src/agent-chat.ts","../src/platform.ts","../src/auth.ts"],"sourcesContent":["/**\n * Error class for the @mindstudio-ai/interface SDK.\n *\n * Thrown by `createClient()` method calls on HTTP errors, by `platform`\n * actions on failures, and by the config reader when bootstrap globals\n * are missing.\n */\nexport class MindStudioInterfaceError extends Error {\n  /** Machine-readable error code (e.g. 'method_not_found', 'not_initialized'). */\n  readonly code: string;\n\n  /** HTTP status code, when the error originated from an API response. */\n  readonly status?: number;\n\n  constructor(message: string, code: string, status?: number) {\n    super(message);\n    this.name = 'MindStudioInterfaceError';\n    this.code = code;\n    this.status = status;\n  }\n}\n","/**\n * Bootstrap configuration reader.\n *\n * Reads and validates `window.__MINDSTUDIO__` — the globals injected by\n * the platform before the app's JavaScript runs. The result is cached\n * after first read.\n *\n * All other modules in the SDK call `getConfig()` internally. App code\n * should never need to call this directly — use `createClient()`, `auth`,\n * and `platform` instead.\n */\n\nimport { MindStudioInterfaceError } from './errors.js';\nimport type { BootstrapConfig } from './types.js';\n\nlet _config: BootstrapConfig | undefined;\n\n/**\n * Read and validate the bootstrap configuration from `window.__MINDSTUDIO__`.\n *\n * Caches the result after first successful read. Throws if the globals\n * are missing or incomplete — this means the page isn't running inside\n * the MindStudio platform.\n *\n * @returns The validated bootstrap config\n * @throws {MindStudioInterfaceError} if `window.__MINDSTUDIO__` is missing or invalid\n */\nexport function getConfig(): BootstrapConfig {\n  if (_config) {\n    return _config;\n  }\n\n  const raw = (globalThis as Record<string, unknown>).__MINDSTUDIO__ as\n    | Partial<BootstrapConfig>\n    | undefined;\n\n  if (!raw) {\n    throw new MindStudioInterfaceError(\n      '@mindstudio-ai/interface requires the MindStudio platform context. ' +\n        'This page must be loaded inside MindStudio (window.__MINDSTUDIO__ is missing).',\n      'not_initialized',\n    );\n  }\n\n  // Validate required fields\n  if (!raw.token || !raw.releaseId || !raw.user || !raw.methods) {\n    const missing = ['token', 'releaseId', 'user', 'methods']\n      .filter((k) => !raw[k as keyof BootstrapConfig])\n      .join(', ');\n\n    throw new MindStudioInterfaceError(\n      `MindStudio platform context is incomplete. Missing: ${missing}`,\n      'invalid_config',\n    );\n  }\n\n  _config = raw as BootstrapConfig;\n  return _config;\n}\n","/**\n * Method RPC client — typed function calls to backend methods.\n *\n * `createClient()` returns a Proxy where every property access creates\n * an async function that invokes the corresponding backend method via HTTP.\n * The method name matches the method's `export` field in `app.json`.\n *\n * ## How it works\n *\n * ```\n * api.submitVendorRequest({ name: 'Acme' })\n *   │\n *   ├─ Look up method ID: config.methods[\"submitVendorRequest\"]\n *   │  → \"submit-vendor-request\"\n *   │\n *   ├─ POST /_/methods/submit-vendor-request/invoke\n *   │  Authorization: Bearer {session token}\n *   │  Body: { input: { name: \"Acme\" } }\n *   │\n *   └─ Returns response.output (or throws on error)\n * ```\n *\n * The method registry (export name → method ID mapping) is embedded in\n * `window.__MINDSTUDIO__.methods` at page load time — no extra HTTP call\n * needed to discover methods.\n *\n * ## Streaming\n *\n * Methods can optionally stream LLM token output via SSE. Pass\n * `{ stream: true }` as the second argument along with an `onToken`\n * callback to receive incremental updates:\n *\n * ```ts\n * const result = await api.submitVendorRequest({ name: 'Acme' }, {\n *   stream: true,\n *   onToken: (text) => setResponseText(text),\n * });\n * ```\n *\n * **Important:** The `text` value passed to `onToken` is the accumulated\n * response so far (not a delta). Replace your display content each time —\n * do not append. See {@link InvokeOptions.onToken} for details.\n *\n * ## Type safety\n *\n * Since the frontend and backend live in the same project, you can import\n * types directly:\n *\n * ```ts\n * import type { SubmitVendorInput, SubmitVendorOutput }\n *   from '../../backend/src/submitVendorRequest';\n *\n * interface AppMethods {\n *   submitVendorRequest(input: SubmitVendorInput): Promise<SubmitVendorOutput>;\n *   getDashboard(): Promise<GetDashboardOutput>;\n * }\n *\n * const api = createClient<AppMethods>();\n * const result = await api.submitVendorRequest({ name: 'Acme' }); // fully typed\n * ```\n *\n * If no type parameter is provided, methods accept `any` input and return `any`.\n */\n\nimport { getConfig } from './config.js';\nimport { MindStudioInterfaceError } from './errors.js';\n\n/**\n * Options for method invocation. Pass as the optional second argument to\n * any method on the client returned by {@link createClient}.\n *\n * When `stream` is `true`, the SDK sends `{ stream: true }` in the request\n * body and parses the response as an SSE (Server-Sent Events) stream.\n * Three event types are handled:\n *\n * | SSE `type` | Payload field | SDK action |\n * |------------|---------------|------------|\n * | `token`    | `text`        | Calls {@link onToken} with accumulated text |\n * | `error`    | `error`       | Calls {@link onStreamError} with the message |\n * | `done`     | `output`      | Captures as the method's return value |\n *\n * The method's `Promise` resolves with the final `output` from the `done`\n * event — the same shape you'd get without streaming.\n */\nexport interface InvokeOptions {\n  /**\n   * Enable SSE streaming for LLM token output.\n   *\n   * When `true`, the request body includes `{ stream: true }` and the\n   * response is parsed as an SSE stream instead of a single JSON payload.\n   * The method still returns a `Promise` that resolves with the final\n   * output once the stream completes.\n   *\n   * @default false\n   */\n  stream?: boolean;\n\n  /**\n   * Called with the accumulated response text each time a new token arrives.\n   *\n   * **Important:** `text` is the full response so far, not a delta/chunk.\n   * Your frontend should **replace** (not append to) its display content\n   * with this value each time the callback fires.\n   *\n   * This design avoids edge cases where the platform sanitizes or\n   * reformats JSON mid-stream, causing earlier portions of the text to\n   * change between tokens.\n   *\n   * @example\n   * ```ts\n   * const result = await api.generate({ prompt: 'Hello' }, {\n   *   stream: true,\n   *   onToken: (text) => {\n   *     // Replace — do NOT append\n   *     responseElement.textContent = text;\n   *   },\n   * });\n   * ```\n   */\n  onToken?: (text: string) => void;\n\n  /**\n   * Called if a stream-level error occurs.\n   *\n   * Stream errors are non-fatal at the protocol level — the method may\n   * still complete and resolve with a final output. Use this callback for\n   * logging or showing a transient warning, not for control flow.\n   *\n   * If the stream ends without a `done` event, the method rejects with a\n   * `MindStudioInterfaceError` (code `stream_incomplete`) regardless of\n   * whether `onStreamError` was provided.\n   */\n  onStreamError?: (error: string) => void;\n}\n\n/**\n * Default client type when no generic parameter is provided.\n * Every property returns an async function accepting optional input\n * and optional {@link InvokeOptions} for streaming.\n */\ntype DefaultMethodClient = Record<\n  string,\n  (input?: Record<string, unknown>, options?: InvokeOptions) => Promise<unknown>\n>;\n\n/**\n * Create a typed RPC client for calling backend methods.\n *\n * @typeParam T - Optional interface mapping method names to their signatures.\n *   If omitted, all methods accept `any` and return `Promise<any>`.\n *\n * @returns A Proxy object where each property is an async function that\n *   invokes the corresponding backend method.\n *\n * @example\n * ```ts\n * import { createClient } from '@mindstudio-ai/interface';\n *\n * const api = createClient();\n *\n * // Each method maps to a backend method export\n * const result = await api.submitVendorRequest({ name: 'Acme' });\n * const dashboard = await api.getDashboard();\n *\n * // Stream LLM output — onToken receives accumulated text (replace, don't append)\n * const streamed = await api.submitVendorRequest({ name: 'Acme' }, {\n *   stream: true,\n *   onToken: (text) => setResponseText(text),\n * });\n * // `streamed` is the same final output you'd get without streaming\n * ```\n */\nexport function createClient<T = DefaultMethodClient>(): T {\n  return new Proxy({} as Record<string, unknown> as T & object, {\n    get(_, methodName: string) {\n      return async (input?: unknown, options?: InvokeOptions) => {\n        const config = getConfig();\n\n        const methodId = config.methods[methodName];\n        if (!methodId) {\n          throw new MindStudioInterfaceError(\n            `Method \"${methodName}\" not found. Available methods: ${Object.keys(config.methods).join(', ') || '(none)'}`,\n            'method_not_found',\n          );\n        }\n\n        const url = `/_/methods/${methodId}/invoke`;\n        const wantsStream = options?.stream === true;\n\n        const res = await fetch(url, {\n          method: 'POST',\n          headers: {\n            'Content-Type': 'application/json',\n            Authorization: `Bearer ${config.token}`,\n          },\n          body: JSON.stringify({\n            input: input ?? {},\n            ...(wantsStream && { stream: true }),\n          }),\n        });\n\n        if (!res.ok) {\n          let errorMessage = `Method \"${methodName}\" failed: ${res.status} ${res.statusText}`;\n          let errorCode = 'method_error';\n          try {\n            const body = (await res.json()) as {\n              error?: string;\n              code?: string;\n            };\n            if (body.error) {\n              errorMessage = body.error;\n            }\n            if (body.code) {\n              errorCode = body.code;\n            }\n          } catch {\n            // Response wasn't JSON — use the default message\n          }\n          throw new MindStudioInterfaceError(\n            errorMessage,\n            errorCode,\n            res.status,\n          );\n        }\n\n        // Non-streaming: unchanged behavior\n        if (!wantsStream) {\n          const body = (await res.json()) as { output?: unknown };\n          return body.output;\n        }\n\n        // Streaming: parse SSE events from response body\n        const reader = res.body!.getReader();\n        const decoder = new TextDecoder();\n        let buffer = '';\n        let finalOutput: unknown;\n\n        while (true) {\n          const { done, value } = await reader.read();\n          if (done) {\n            break;\n          }\n\n          buffer += decoder.decode(value, { stream: true });\n          const lines = buffer.split('\\n');\n          buffer = lines.pop() ?? '';\n\n          for (const line of lines) {\n            if (!line.startsWith('data: ')) {\n              continue;\n            }\n            const json = line.slice(6);\n            try {\n              const event = JSON.parse(json) as {\n                type: string;\n                text?: string;\n                error?: string;\n                output?: unknown;\n              };\n\n              if (event.type === 'token' && options?.onToken && event.text) {\n                options.onToken(event.text);\n              } else if (event.type === 'error' && event.error) {\n                if (options?.onStreamError) {\n                  options.onStreamError(event.error);\n                }\n              } else if (event.type === 'done') {\n                finalOutput = event.output;\n              }\n            } catch {\n              // Skip malformed SSE lines\n            }\n          }\n        }\n\n        if (finalOutput === undefined) {\n          throw new MindStudioInterfaceError(\n            'Stream ended without a done event',\n            'stream_incomplete',\n          );\n        }\n\n        return finalOutput;\n      };\n    },\n  });\n}\n","/**\n * Agent chat client — thread-based conversations with AI agents.\n *\n * `createAgentChatClient()` returns an object with methods for thread\n * lifecycle (create, list, get, rename, delete) and message streaming.\n * The agent runs server-side with access to the app's methods as tools.\n *\n * ## How it works\n *\n * ```\n * chat.sendMessage(threadId, 'Help me prep for my review', {\n *   onText: (delta) => setAssistantMessage((prev) => prev + delta),\n * })\n *   │\n *   ├─ POST /_/agent/threads/{threadId}/messages\n *   │  Authorization: Bearer {session token}\n *   │  Body: { content: \"Help me prep for my review\" }\n *   │\n *   ├─ Response: SSE stream\n *   │  data: {\"type\":\"text\",\"text\":\"I'll create...\",\"ts\":1711...}\n *   │  data: {\"type\":\"tool_call_start\",\"id\":\"call_abc\",\"name\":\"create-todo\",\"ts\":1711...}\n *   │  data: {\"type\":\"tool_call_result\",\"id\":\"call_abc\",\"output\":{...},\"ts\":1711...}\n *   │  data: {\"type\":\"text\",\"text\":\"Done — added it.\",\"ts\":1711...}\n *   │  data: {\"type\":\"done\",\"stopReason\":\"end_turn\",\"usage\":{...},\"ts\":1711...}\n *   │\n *   └─ Promise resolves with { stopReason, usage }\n * ```\n *\n * ## Stateless design\n *\n * This client is a thin wrapper over HTTP endpoints. It does not manage\n * local state — your React/framework layer owns the thread list, message\n * array, and UI state. Each method is an independent request.\n *\n * ## Streaming callbacks\n *\n * `sendMessage` accepts named callbacks for common events (onText,\n * onThinking, onToolCallStart, etc.) plus a catch-all `onEvent` that\n * receives every SSE event as a discriminated union. Both fire for the\n * same event — use named callbacks for convenience, `onEvent` for\n * logging or handling low-level events like `tool_use` and\n * `tool_input_delta`.\n *\n * @example\n * ```ts\n * import { createAgentChatClient } from '@mindstudio-ai/interface';\n *\n * const chat = createAgentChatClient();\n *\n * // Thread lifecycle\n * const thread = await chat.createThread();\n * const { threads } = await chat.listThreads();\n * const full = await chat.getThread(thread.id);\n *\n * // Send a message with streaming\n * const response = chat.sendMessage(thread.id, 'Hello!', {\n *   onText: (delta) => setMessage((prev) => prev + delta),\n *   onToolCallStart: (id, name) => showToolSpinner(name),\n *   onToolCallResult: (id, output) => showToolResult(output),\n * });\n *\n * const { stopReason, usage } = await response;\n *\n * // Abort mid-stream\n * response.abort();\n * ```\n */\n\nimport { getConfig } from './config.js';\nimport { MindStudioInterfaceError } from './errors.js';\n\n// ---------------------------------------------------------------------------\n// Thread types\n// ---------------------------------------------------------------------------\n\n/** Thread summary returned from create and list endpoints. */\nexport interface ThreadSummary {\n  /** Thread ID (UUID). */\n  id: string;\n  /** User-editable title, auto-generated on first message. */\n  title: string | null;\n  /** ISO 8601 creation timestamp. */\n  dateCreated: string;\n  /** ISO 8601 last-updated timestamp. */\n  dateUpdated: string;\n}\n\n/** Full thread with message history, returned from get endpoint. */\nexport interface Thread {\n  /** Thread ID (UUID). */\n  id: string;\n  /** User-editable title. */\n  title: string | null;\n  /** Full conversation history. */\n  messages: Message[];\n  /** ISO 8601 creation timestamp. */\n  dateCreated: string;\n  /** ISO 8601 last-updated timestamp. */\n  dateUpdated: string;\n}\n\n/** A tool call requested by the assistant. */\nexport interface ToolCall {\n  /** Tool call ID, used to match results. */\n  id: string;\n  /** Method name. */\n  name: string;\n  /** Input arguments. */\n  input: Record<string, unknown>;\n}\n\n/** A single message in a thread's conversation history. */\nexport interface Message {\n  /** `\"user\"` for human messages, `\"assistant\"` for agent responses. */\n  role: 'user' | 'assistant';\n  /** Message text content. For tool results, this is JSON-stringified output. */\n  content: string;\n  /**\n   * MindStudio CDN URLs attached to this message (user messages only).\n   *\n   * Images (`i.mscdn.ai`) are sent to the model as vision input.\n   * Documents (`f.mscdn.ai`, `files.mindstudio-cdn.com`) have their text\n   * extracted server-side and included in the model context. The original\n   * URLs are preserved in thread history for the frontend to render.\n   */\n  attachments?: string[];\n  /** Tool calls the assistant requested (assistant messages only). */\n  toolCalls?: ToolCall[];\n  /** ID of the tool call this message is a result for (tool result messages only). */\n  toolCallId?: string;\n  /** Whether this tool result represents an error. */\n  isToolError?: boolean;\n}\n\n/** Paginated thread list response. */\nexport interface ThreadListPage {\n  /** Threads for this page. */\n  threads: ThreadSummary[];\n  /** Cursor for the next page, or `null` if this is the last page. */\n  nextCursor: string | null;\n}\n\n// ---------------------------------------------------------------------------\n// SSE event types\n// ---------------------------------------------------------------------------\n\n/** Assistant text delta — append to your display string, do not replace. */\nexport interface AgentTextEvent {\n  type: 'text';\n  text: string;\n  ts: number;\n}\n\n/** Model thinking text (extended thinking). */\nexport interface AgentThinkingEvent {\n  type: 'thinking';\n  text: string;\n  ts: number;\n}\n\n/** Thinking complete with full text and signature. */\nexport interface AgentThinkingCompleteEvent {\n  type: 'thinking_complete';\n  thinking: string;\n  signature: string;\n  ts: number;\n}\n\n/** Model requested a tool call (includes parsed input). */\nexport interface AgentToolUseEvent {\n  type: 'tool_use';\n  id: string;\n  name: string;\n  input: Record<string, unknown>;\n  ts: number;\n}\n\n/** Streaming delta for tool call input JSON. */\nexport interface AgentToolInputDeltaEvent {\n  type: 'tool_input_delta';\n  id: string;\n  name: string;\n  delta: string;\n  ts: number;\n}\n\n/** Agent began executing a tool call. */\nexport interface AgentToolCallStartEvent {\n  type: 'tool_call_start';\n  id: string;\n  name: string;\n  ts: number;\n}\n\n/** Tool call returned a result. */\nexport interface AgentToolCallResultEvent {\n  type: 'tool_call_result';\n  id: string;\n  output: unknown;\n  ts: number;\n}\n\n/** Stream complete. */\nexport interface AgentDoneEvent {\n  type: 'done';\n  stopReason: string;\n  usage: { inputTokens: number; outputTokens: number };\n  ts: number;\n}\n\n/** Stream-level error. */\nexport interface AgentErrorEvent {\n  type: 'error';\n  error: string;\n  ts: number;\n}\n\n/** Discriminated union of all SSE events from the agent chat stream. */\nexport type AgentChatEvent =\n  | AgentTextEvent\n  | AgentThinkingEvent\n  | AgentThinkingCompleteEvent\n  | AgentToolUseEvent\n  | AgentToolInputDeltaEvent\n  | AgentToolCallStartEvent\n  | AgentToolCallResultEvent\n  | AgentDoneEvent\n  | AgentErrorEvent;\n\n// ---------------------------------------------------------------------------\n// Callbacks and result types\n// ---------------------------------------------------------------------------\n\n/**\n * Callbacks for `sendMessage` streaming.\n *\n * Named callbacks fire for common events. The catch-all `onEvent` fires\n * for every event including those with named callbacks — use it for\n * logging or handling low-level events like `tool_use` and\n * `tool_input_delta`.\n */\nexport interface SendMessageCallbacks {\n  /**\n   * Called with each text delta as the assistant responds.\n   *\n   * **Important:** `text` is a delta (new chunk), not the accumulated\n   * response. Append it to your display string — do not replace.\n   *\n   * @example\n   * ```ts\n   * onText: (delta) => setMessage((prev) => prev + delta)\n   * ```\n   */\n  onText?: (text: string) => void;\n\n  /** Called with model thinking text (extended thinking). */\n  onThinking?: (text: string) => void;\n\n  /** Called when thinking is complete. */\n  onThinkingComplete?: (thinking: string, signature: string) => void;\n\n  /** Called when a tool call begins executing. */\n  onToolCallStart?: (id: string, name: string) => void;\n\n  /** Called when a tool call produces a result. */\n  onToolCallResult?: (id: string, output: unknown) => void;\n\n  /** Called on a stream-level error event. */\n  onError?: (error: string) => void;\n\n  /** Called for every SSE event (including ones with named callbacks). */\n  onEvent?: (event: AgentChatEvent) => void;\n\n  /** AbortSignal to cancel the stream. */\n  signal?: AbortSignal;\n}\n\n/** Options for `sendMessage`. */\nexport interface SendMessageOptions {\n  /**\n   * MindStudio CDN URLs to attach to the message.\n   *\n   * Images (`i.mscdn.ai`) are sent to the model as vision input (one per message).\n   * Documents (`f.mscdn.ai`, `files.mindstudio-cdn.com`) have their text\n   * extracted server-side and included in context.\n   *\n   * Upload files first via `platform.uploadFile()`.\n   *\n   * @example\n   * ```ts\n   * const url = await platform.uploadFile(file);\n   * chat.sendMessage(threadId, 'What is this?', callbacks, {\n   *   attachments: [url],\n   * });\n   * ```\n   */\n  attachments?: string[];\n}\n\n/** Resolved value of `sendMessage` — extracted from the `done` event. */\nexport interface SendMessageResult {\n  /** Why the agent stopped (`\"end_turn\"`, `\"max_tokens\"`, etc.). */\n  stopReason: string;\n  /** Token usage for the full agent loop. */\n  usage: { inputTokens: number; outputTokens: number };\n}\n\n/** A Promise with an `abort()` method for cancelling the stream. */\nexport type AbortablePromise<T> = Promise<T> & {\n  /** Cancel the in-flight stream. The promise rejects with `AbortError`. */\n  abort: () => void;\n};\n\n// ---------------------------------------------------------------------------\n// Client interface\n// ---------------------------------------------------------------------------\n\n/** Agent chat client returned by {@link createAgentChatClient}. */\nexport interface AgentChatClient {\n  /** Create a new conversation thread. */\n  createThread(): Promise<ThreadSummary>;\n\n  /** List threads with cursor-based pagination (50 per page). */\n  listThreads(cursor?: string): Promise<ThreadListPage>;\n\n  /** Get a thread with its full message history. */\n  getThread(threadId: string): Promise<Thread>;\n\n  /** Update a thread's title. */\n  updateThread(threadId: string, title: string): Promise<void>;\n\n  /** Delete a thread (soft delete). */\n  deleteThread(threadId: string): Promise<void>;\n\n  /**\n   * Send a message and stream the agent's response.\n   *\n   * Returns an {@link AbortablePromise} that resolves with\n   * `{ stopReason, usage }` when the stream completes. Call `.abort()`\n   * on the returned promise to cancel mid-stream.\n   *\n   * @param options.attachments - MindStudio CDN URLs to attach.\n   *   Images (`i.mscdn.ai`) are sent as vision input.\n   *   Documents (`f.mscdn.ai`) have text extracted into context.\n   *   Upload files first via `platform.uploadFile()`.\n   */\n  sendMessage(\n    threadId: string,\n    content: string,\n    callbacks?: SendMessageCallbacks,\n    options?: SendMessageOptions,\n  ): AbortablePromise<SendMessageResult>;\n}\n\n// ---------------------------------------------------------------------------\n// Private helpers\n// ---------------------------------------------------------------------------\n\nconst AGENT_BASE = '/_/agent';\n\nasync function request<T>(\n  path: string,\n  method: string,\n  body?: unknown,\n): Promise<T> {\n  const config = getConfig();\n  const headers: Record<string, string> = {\n    Authorization: `Bearer ${config.token}`,\n  };\n\n  if (body !== undefined) {\n    headers['Content-Type'] = 'application/json';\n  }\n\n  const res = await fetch(`${AGENT_BASE}${path}`, {\n    method,\n    headers,\n    ...(body !== undefined && { body: JSON.stringify(body) }),\n  });\n\n  if (!res.ok) {\n    let errorMessage = `Agent chat request failed: ${res.status} ${res.statusText}`;\n    let errorCode = 'agent_chat_error';\n    try {\n      const err = (await res.json()) as { error?: string; code?: string };\n      if (err.error) {\n        errorMessage = err.error;\n      }\n      if (err.code) {\n        errorCode = err.code;\n      }\n    } catch {\n      // Response wasn't JSON — use the default message\n    }\n    throw new MindStudioInterfaceError(errorMessage, errorCode, res.status);\n  }\n\n  return (await res.json()) as T;\n}\n\nfunction dispatchEvent(\n  event: AgentChatEvent,\n  callbacks: SendMessageCallbacks,\n): void {\n  // Catch-all fires for every event\n  callbacks.onEvent?.(event);\n\n  // Named callbacks\n  switch (event.type) {\n    case 'text':\n      callbacks.onText?.(event.text);\n      break;\n    case 'thinking':\n      callbacks.onThinking?.(event.text);\n      break;\n    case 'thinking_complete':\n      callbacks.onThinkingComplete?.(event.thinking, event.signature);\n      break;\n    case 'tool_call_start':\n      callbacks.onToolCallStart?.(event.id, event.name);\n      break;\n    case 'tool_call_result':\n      callbacks.onToolCallResult?.(event.id, event.output);\n      break;\n    case 'error':\n      callbacks.onError?.(event.error);\n      break;\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/**\n * Create an agent chat client for thread-based conversations.\n *\n * The client is stateless — each method is an independent HTTP request.\n * Your application layer owns thread state, message arrays, and UI updates.\n *\n * @returns An {@link AgentChatClient} with methods for thread CRUD and\n *   message streaming.\n *\n * @example\n * ```ts\n * import { createAgentChatClient } from '@mindstudio-ai/interface';\n *\n * const chat = createAgentChatClient();\n *\n * const thread = await chat.createThread();\n *\n * const response = chat.sendMessage(thread.id, 'Hello!', {\n *   onText: (delta) => setAssistantMessage((prev) => prev + delta),\n *   onToolCallStart: (id, name) => showToolSpinner(name),\n *   onToolCallResult: (id, output) => showToolResult(output),\n * });\n *\n * const { stopReason, usage } = await response;\n * ```\n */\nexport function createAgentChatClient(): AgentChatClient {\n  return {\n    createThread() {\n      return request<ThreadSummary>('/threads', 'POST');\n    },\n\n    listThreads(cursor?: string) {\n      const query = cursor ? `?cursor=${encodeURIComponent(cursor)}` : '';\n      return request<ThreadListPage>(`/threads${query}`, 'GET');\n    },\n\n    getThread(threadId: string) {\n      return request<Thread>(`/threads/${threadId}`, 'GET');\n    },\n\n    async updateThread(threadId: string, title: string) {\n      await request(`/threads/${threadId}`, 'PATCH', { title });\n    },\n\n    async deleteThread(threadId: string) {\n      await request(`/threads/${threadId}`, 'DELETE');\n    },\n\n    sendMessage(\n      threadId: string,\n      content: string,\n      callbacks?: SendMessageCallbacks,\n      options?: SendMessageOptions,\n    ): AbortablePromise<SendMessageResult> {\n      const controller = new AbortController();\n      const cb = callbacks ?? {};\n\n      // Wire caller's signal to our internal controller\n      if (cb.signal) {\n        if (cb.signal.aborted) {\n          controller.abort();\n        } else {\n          cb.signal.addEventListener('abort', () => controller.abort(), {\n            once: true,\n          });\n        }\n      }\n\n      const promise = (async (): Promise<SendMessageResult> => {\n        const config = getConfig();\n        const url = `${AGENT_BASE}/threads/${threadId}/messages`;\n\n        const res = await fetch(url, {\n          method: 'POST',\n          headers: {\n            'Content-Type': 'application/json',\n            Authorization: `Bearer ${config.token}`,\n          },\n          body: JSON.stringify({\n            content,\n            ...(options?.attachments?.length && {\n              attachments: options.attachments,\n            }),\n          }),\n          signal: controller.signal,\n        });\n\n        if (!res.ok) {\n          let errorMessage = `Send message failed: ${res.status} ${res.statusText}`;\n          let errorCode = 'agent_chat_error';\n          try {\n            const err = (await res.json()) as {\n              error?: string;\n              code?: string;\n            };\n            if (err.error) {\n              errorMessage = err.error;\n            }\n            if (err.code) {\n              errorCode = err.code;\n            }\n          } catch {\n            // Response wasn't JSON — use the default message\n          }\n          throw new MindStudioInterfaceError(\n            errorMessage,\n            errorCode,\n            res.status,\n          );\n        }\n\n        const reader = res.body!.getReader();\n        const decoder = new TextDecoder();\n        let buffer = '';\n        let result: SendMessageResult | undefined;\n\n        while (true) {\n          const { done, value } = await reader.read();\n          if (done) {\n            break;\n          }\n\n          buffer += decoder.decode(value, { stream: true });\n          const lines = buffer.split('\\n');\n          buffer = lines.pop() ?? '';\n\n          for (const line of lines) {\n            if (!line.startsWith('data: ')) {\n              continue;\n            }\n            const json = line.slice(6);\n            try {\n              const event = JSON.parse(json) as AgentChatEvent;\n\n              if (event.type === 'done') {\n                result = {\n                  stopReason: event.stopReason,\n                  usage: event.usage,\n                };\n              }\n\n              dispatchEvent(event, cb);\n            } catch {\n              // Skip malformed SSE lines\n            }\n          }\n        }\n\n        if (!result) {\n          throw new MindStudioInterfaceError(\n            'Stream ended without a done event',\n            'stream_incomplete',\n          );\n        }\n\n        return result;\n      })();\n\n      const abortable = promise as AbortablePromise<SendMessageResult>;\n      abortable.abort = () => controller.abort();\n      return abortable;\n    },\n  };\n}\n","/**\n * Platform actions — file uploads via presigned S3 POST.\n *\n * Uses the session token from `window.__MINDSTUDIO__` to request a\n * presigned upload URL from the platform, then uploads directly to S3.\n * Returns the public CDN URL.\n *\n * @example\n * ```ts\n * import { platform } from '@mindstudio-ai/interface';\n *\n * const file = document.querySelector('input[type=file]').files[0];\n * const url = await platform.uploadFile(file);\n *\n * // With progress and abort\n * const controller = new AbortController();\n * const url = await platform.uploadFile(file, {\n *   onProgress: (fraction) => console.log(`${Math.round(fraction * 100)}%`),\n *   signal: controller.signal,\n * });\n * ```\n */\n\nimport { getConfig } from './config.js';\nimport { MindStudioInterfaceError } from './errors.js';\n\n/**\n * Options for `platform.uploadFile()`.\n */\nexport interface UploadFileOptions {\n  /** Called with upload progress as a fraction from 0 to 1. */\n  onProgress?: (fraction: number) => void;\n\n  /** AbortSignal to cancel the upload. */\n  signal?: AbortSignal;\n}\n\n/**\n * The platform namespace — file upload actions.\n */\nexport const platform = {\n  /**\n   * Upload a file to the MindStudio CDN.\n   *\n   * Requests a presigned upload URL from the platform, then uploads\n   * the file directly to S3. Returns the public CDN URL.\n   *\n   * @param file - The File to upload\n   * @param options - Optional progress callback and abort signal\n   * @returns CDN URL of the uploaded file\n   *\n   * @example\n   * ```ts\n   * const url = await platform.uploadFile(file);\n   *\n   * // With progress\n   * const url = await platform.uploadFile(file, {\n   *   onProgress: (f) => setProgress(f),\n   * });\n   *\n   * // With abort\n   * const controller = new AbortController();\n   * const url = await platform.uploadFile(file, {\n   *   signal: controller.signal,\n   * });\n   * // controller.abort() to cancel\n   * ```\n   */\n  async uploadFile(file: File, options?: UploadFileOptions): Promise<string> {\n    const config = getConfig();\n    const { onProgress, signal } = options ?? {};\n\n    // Check if already aborted\n    signal?.throwIfAborted();\n\n    // Step 1: Get presigned upload URL\n    const presignUrl = '/_/generate-upload-request';\n    const presignRes = await fetch(presignUrl, {\n      method: 'POST',\n      headers: {\n        Authorization: `Bearer ${config.token}`,\n        'Content-Type': 'application/json',\n      },\n      body: JSON.stringify({\n        filename: file.name,\n        contentType: file.type || 'application/octet-stream',\n      }),\n      signal,\n    });\n\n    if (!presignRes.ok) {\n      throw new MindStudioInterfaceError(\n        `Upload presign failed: ${presignRes.status} ${presignRes.statusText}`,\n        'upload_error',\n        presignRes.status,\n      );\n    }\n\n    const { uploadUrl, uploadFields, publicUrl } =\n      (await presignRes.json()) as {\n        uploadUrl: string;\n        uploadFields: Record<string, string>;\n        publicUrl: string;\n      };\n\n    // Step 2: Upload directly to S3\n    const formData = new FormData();\n    for (const [key, value] of Object.entries(uploadFields)) {\n      formData.append(key, value);\n    }\n    formData.append('file', file); // must be last\n\n    // Use XHR for upload progress (fetch doesn't support it)\n    if (onProgress) {\n      await xhrUpload(uploadUrl, formData, onProgress, signal);\n      return publicUrl;\n    }\n\n    const uploadRes = await fetch(uploadUrl, {\n      method: 'POST',\n      body: formData,\n      signal,\n    });\n\n    if (!uploadRes.ok) {\n      throw new MindStudioInterfaceError(\n        `File upload failed: ${uploadRes.status} ${uploadRes.statusText}`,\n        'upload_error',\n        uploadRes.status,\n      );\n    }\n\n    return publicUrl;\n  },\n};\n\n/**\n * Upload via XMLHttpRequest to get progress events.\n * Falls back from fetch because fetch upload streams don't support progress.\n */\nfunction xhrUpload(\n  url: string,\n  formData: FormData,\n  onProgress: (fraction: number) => void,\n  signal?: AbortSignal,\n): Promise<void> {\n  return new Promise<void>((resolve, reject) => {\n    const xhr = new XMLHttpRequest();\n\n    xhr.upload.addEventListener('progress', (e) => {\n      if (e.lengthComputable) {\n        onProgress(e.loaded / e.total);\n      }\n    });\n\n    xhr.addEventListener('load', () => {\n      if (xhr.status >= 200 && xhr.status < 300) {\n        onProgress(1);\n        resolve();\n      } else {\n        reject(\n          new MindStudioInterfaceError(\n            `File upload failed: ${xhr.status} ${xhr.statusText}`,\n            'upload_error',\n            xhr.status,\n          ),\n        );\n      }\n    });\n\n    xhr.addEventListener('error', () => {\n      reject(\n        new MindStudioInterfaceError(\n          'File upload failed: network error',\n          'upload_error',\n        ),\n      );\n    });\n\n    xhr.addEventListener('abort', () => {\n      reject(new DOMException('Upload aborted', 'AbortError'));\n    });\n\n    // Wire up abort signal\n    if (signal) {\n      if (signal.aborted) {\n        reject(new DOMException('Upload aborted', 'AbortError'));\n        return;\n      }\n      signal.addEventListener('abort', () => xhr.abort(), { once: true });\n    }\n\n    xhr.open('POST', url);\n    xhr.send(formData);\n  });\n}\n","/**\n * Auth context — current user's identity for display purposes.\n *\n * Provides synchronous access to the current user's name, email, and\n * profile picture. Hydrated from the bootstrap globals injected by the\n * platform — no HTTP call needed.\n *\n * This is for **display only**. Role checking, permission enforcement,\n * and user lookups for other users are backend concerns — the frontend\n * calls backend methods that handle those via `@mindstudio-ai/agent`'s\n * `auth` namespace.\n *\n * @example\n * ```ts\n * import { auth } from '@mindstudio-ai/interface';\n *\n * return (\n *   <div>\n *     <p>Welcome, {auth.name}</p>\n *     <img src={auth.profilePictureUrl} />\n *   </div>\n * );\n * ```\n */\n\nimport { getConfig } from './config.js';\n\n/**\n * User identity context. All properties are read-only and synchronous.\n */\nexport interface AuthContext {\n  /** Current user's ID (UUID). */\n  readonly userId: string;\n\n  /** Current user's display name. */\n  readonly name: string;\n\n  /** Current user's email address. */\n  readonly email: string;\n\n  /** Current user's profile picture URL, or null if not set. */\n  readonly profilePictureUrl: string | null;\n}\n\n/**\n * Lazy auth proxy — reads from bootstrap globals on first property access.\n *\n * Using a Proxy lets us export `auth` as a module-level constant while\n * deferring the `getConfig()` call until the first property is accessed.\n * This avoids throwing during import if the page hasn't finished loading\n * the bootstrap script yet.\n */\nexport const auth: AuthContext = new Proxy({} as AuthContext, {\n  get(_, prop: string) {\n    const { user } = getConfig();\n\n    switch (prop) {\n      case 'userId':\n        return user.id;\n      case 'name':\n        return user.name;\n      case 'email':\n        return user.email;\n      case 'profilePictureUrl':\n        return user.profilePictureUrl ?? null;\n      default:\n        return undefined;\n    }\n  },\n});\n"],"mappings":"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","names":["MindStudioInterfaceError","message","code","status","_config","getConfig","raw","MindStudioInterfaceError","missing","k","createClient","_","methodName","input","options","config","getConfig","methodId","MindStudioInterfaceError","url","wantsStream","res","errorMessage","errorCode","body","reader","decoder","buffer","finalOutput","done","value","lines","line","json","event","AGENT_BASE","request","path","method","body","headers","getConfig","res","errorMessage","errorCode","err","MindStudioInterfaceError","dispatchEvent","event","callbacks","createAgentChatClient","cursor","query","threadId","title","content","options","controller","cb","abortable","config","url","reader","decoder","buffer","result","done","value","lines","line","json","platform","file","options","config","getConfig","onProgress","signal","presignRes","MindStudioInterfaceError","uploadUrl","uploadFields","publicUrl","formData","key","value","xhrUpload","uploadRes","url","resolve","reject","xhr","e","auth","_","prop","user","getConfig"]}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@mindstudio-ai/interface",
+  "version": "0.1.0",
+  "description": "Frontend SDK for MindStudio v2 app interfaces",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "prepare": "husky && tsup",
+    "prepublishOnly": "tsup",
+    "lint:fix": "prettier --write ./src"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "mindstudio",
+    "interface",
+    "frontend",
+    "sdk"
+  ],
+  "homepage": "https://github.com/mindstudio-ai/mindstudio-interface#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mindstudio-ai/mindstudio-interface.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mindstudio-ai/mindstudio-interface/issues"
+  },
+  "author": "MindStudio <support@mindstudio.ai> (https://mindstudio.ai)",
+  "license": "MIT",
+  "sideEffects": false,
+  "devDependencies": {
+    "husky": "^9.1.7",
+    "lint-staged": "^16.3.2",
+    "prettier": "^3.8.1",
+    "prettier-plugin-curly": "^0.4.1",
+    "tsup": "^8",
+    "typescript": "^5.5"
+  },
+  "lint-staged": {
+    "**/*": "prettier --write --ignore-unknown"
+  }
+}