@mitralab.io/platform-sdk 1.0.8 → 1.1.0-beta.0

package/dist/index.d.cts

@@ -0,0 +1,966 @@
+import { Transport, TransportRequestOptions, QueryParamValue, EntityTable, FunctionExecution, ListTemplateConfigsOptions, TemplateConfigPage, ProxyResult, ProxyInput, QueryResult, CredentialStatus, AgentModel as AgentModel$1, OAuthStartResult, OAuthExchangeInput, AuthenticationResult, DeviceAuthorization, PublicFunctionsModule, AgentTasksWithSessions } from '@mitralab.io/sdk-core';
+export { AgentQueueItem, AgentSendAndWaitOptions, AgentSendOptions, AgentSessionTransport, AgentTask, AgentTaskCreateInput, AgentTaskInput, AgentTaskListOptions, AgentTaskSessionEventMap, AgentTaskSessionOptions, AgentTaskSessionStatus, AgentTurnResult, AuthenticationResult, CredentialStatus, DeviceAuthorization, EntityListOptions, EntityTable, ExistingAgentTaskSessionOptions, FunctionExecution, ListTemplateConfigsOptions, AgentMessage as NativeAgentMessage, AgentModel as NativeAgentModel, AgentTaskSession as NativeAgentTaskSession, AgentTimelineItem as NativeAgentTimelineItem, AgentToolEvent as NativeAgentToolEvent, NewAgentTaskSessionOptions, OAuthExchangeInput, OAuthStartResult, Page, PageOptions, ProxyInput, ProxyResult, PublicFunctionAsyncResult, PublicFunctionResult, PublicFunctionsModule, QueryResult, TemplateConfigPage } from '@mitralab.io/sdk-core';
+import * as LegacyTypes from 'mitra-interactions-sdk';
+import { exchangeSsoCodeMitra as exchangeSsoCodeMitra$1, loginMitra as loginMitra$1, loginWithGoogleMitra as loginWithGoogleMitra$1, loginWithMicrosoftMitra as loginWithMicrosoftMitra$1 } from 'mitra-interactions-sdk';
+export { callIntegrationMitra, configureSdkMitra, createMitraInstance, createRecordMitra, createRecordsBatchMitra, deleteRecordMitra, executePublicServerFunctionAsyncMitra, executePublicServerFunctionMitra, executeServerFunctionAsyncMitra, executeServerFunctionMitra, getAgentTaskMitra, getConfig, getPublicServerFunctionExecutionMitra, getRecordMitra, listIntegrationsMitra, listRecordsMitra, manageAgentChatMitra, manageAgentCredentialMitra, patchRecordMitra, refreshTokenSilently, resolveProjectId, stopServerFunctionExecutionMitra, updateRecordMitra } from 'mitra-interactions-sdk';
+
+/**
+ * Configuration options for creating an HttpClient instance.
+ */
+interface HttpClientConfig {
+    /** Base URL for all HTTP requests (e.g., 'https://api.mitra.io') */
+    baseUrl: string;
+    /** Function that returns the current authentication token, or null if not authenticated */
+    getToken?: () => string | null;
+    /** Refreshes an authenticated session before the Authorization header is constructed. */
+    beforeAuthenticatedRequest?: () => Promise<void>;
+    /**
+     * Callback invoked on a 401 with the token used by that request. Returns
+     * true when the request should be retried once with the current credential.
+     */
+    onUnauthorized?: (requestToken: string | null) => Promise<boolean>;
+    /** Called whenever an API request fails. Useful for global error handling (e.g., toast notifications). */
+    onError?: (error: MitraApiError) => void;
+    /** Headers included in every request (e.g., X-App-Id for tracing). */
+    defaultHeaders?: Record<string, string>;
+}
+/**
+ * Options for making HTTP requests.
+ */
+interface RequestOptions extends Omit<TransportRequestOptions, 'method'> {
+    /** HTTP method (defaults to 'GET') */
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    /** Request body (will be JSON stringified) */
+    body?: unknown;
+    /** Additional headers to include in the request */
+    headers?: Record<string, string>;
+    /** URL query parameters */
+    params?: Record<string, QueryParamValue>;
+    /** @internal Flag to prevent infinite retry loops on 401 */
+    isRetry?: boolean;
+}
+/**
+ * HTTP client for making authenticated API requests.
+ *
+ * Handles JSON serialization, authentication headers, and error handling.
+ * All requests automatically include the Authorization header when a token is available.
+ *
+ * @example
+ * ```typescript
+ * const client = new HttpClient({
+ *   baseUrl: 'https://api.mitra.io',
+ *   getToken: () => localStorage.getItem('token'),
+ * });
+ *
+ * const users = await client.get<User[]>('/users');
+ * const user = await client.post<User>('/users', { name: 'John' });
+ * ```
+ */
+declare class HttpClient implements Transport {
+    private readonly baseUrl;
+    private readonly tokenGetter;
+    private readonly beforeAuthenticatedRequest?;
+    private readonly onUnauthorized?;
+    private readonly onError?;
+    private readonly defaultHeaders;
+    constructor(config: HttpClientConfig);
+    /**
+     * Returns the current authentication token.
+     * @returns The JWT token if authenticated, null otherwise
+     */
+    getToken(): string | null;
+    /**
+     * Makes an HTTP request with automatic JSON handling and authentication.
+     *
+     * @param path - API endpoint path (e.g., '/users')
+     * @param options - Request options including method, body, headers, and params
+     * @returns Promise resolving to the parsed JSON response
+     * @throws {MitraApiError} When the API returns an error response
+     *
+     * @example
+     * ```typescript
+     * const result = await client.request<User>('/users/123', {
+     *   method: 'PUT',
+     *   body: { name: 'Updated Name' },
+     * });
+     * ```
+     */
+    request<T>(path: string, options?: RequestOptions): Promise<T>;
+    private errorFromResponse;
+    private parseResponseBody;
+    /**
+     * Makes a GET request.
+     *
+     * @param path - API endpoint path
+     * @param params - Optional query parameters
+     * @returns Promise resolving to the parsed JSON response
+     *
+     * @example
+     * ```typescript
+     * const users = await client.get<User[]>('/users', { limit: 10 });
+     * ```
+     */
+    get<T>(path: string, params?: Record<string, QueryParamValue>): Promise<T>;
+    /**
+     * Makes a POST request.
+     *
+     * @param path - API endpoint path
+     * @param body - Request body (will be JSON stringified)
+     * @returns Promise resolving to the parsed JSON response
+     *
+     * @example
+     * ```typescript
+     * const user = await client.post<User>('/users', { name: 'John', email: 'john@example.com' });
+     * ```
+     */
+    post<T>(path: string, body?: unknown): Promise<T>;
+    /**
+     * Makes a PUT request.
+     *
+     * @param path - API endpoint path
+     * @param body - Request body (will be JSON stringified)
+     * @returns Promise resolving to the parsed JSON response
+     *
+     * @example
+     * ```typescript
+     * const user = await client.put<User>('/users/123', { name: 'Updated Name' });
+     * ```
+     */
+    put<T>(path: string, body?: unknown): Promise<T>;
+    /**
+     * Makes a DELETE request.
+     *
+     * @param path - API endpoint path
+     * @param params - Optional query parameters
+     * @returns Promise resolving to the parsed JSON response (or undefined for 204 responses)
+     *
+     * @example
+     * ```typescript
+     * await client.delete('/users/123');
+     * ```
+     */
+    delete<T>(path: string, params?: Record<string, QueryParamValue>): Promise<T>;
+}
+/**
+ * Error thrown when a Mitra API request fails.
+ *
+ * Contains detailed information about the error including HTTP status,
+ * error code, and additional details from the server response.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await mitra.entities.Task.get('invalid-id');
+ * } catch (error) {
+ *   if (error instanceof MitraApiError) {
+ *     console.log(error.status);   // 404
+ *     console.log(error.message);  // "Task not found"
+ *     console.log(error.code);     // "ENTITY_NOT_FOUND"
+ *   }
+ * }
+ * ```
+ */
+declare class MitraApiError extends Error {
+    /** HTTP status code (e.g., 400, 401, 404, 500) */
+    readonly status: number;
+    /** Application-specific error code (e.g., 'ENTITY_NOT_FOUND', 'VALIDATION_ERROR') */
+    readonly code?: string | undefined;
+    /** Additional error details from the server response */
+    readonly details?: unknown | undefined;
+    constructor(message: string, 
+    /** HTTP status code (e.g., 400, 401, 404, 500) */
+    status: number, 
+    /** Application-specific error code (e.g., 'ENTITY_NOT_FOUND', 'VALIDATION_ERROR') */
+    code?: string | undefined, 
+    /** Additional error details from the server response */
+    details?: unknown | undefined);
+}
+
+/** Authenticated user in the Mitra Platform. */
+interface User {
+    /** Unique identifier. */
+    id: string;
+    /** Tenant the user belongs to. */
+    tenantId: string;
+    /** Email address. */
+    email: string;
+    /** Display name (optional). */
+    name: string | null;
+}
+/** Credentials for sign-in. */
+interface SignInCredentials {
+    email: string;
+    password: string;
+}
+/** Data for user registration. */
+interface SignUpData {
+    email: string;
+    password: string;
+    name?: string;
+}
+/** App-scoped session received from a trusted platform boundary. */
+interface AuthSession {
+    accessToken: string;
+    refreshToken?: string | null;
+}
+/** Options for Google SSO. */
+interface GoogleSignInOptions {
+    /** Opens a popup by default. Redirect mode navigates the current page. */
+    mode?: 'popup' | 'redirect';
+}
+/** Options for Microsoft SSO. Same handshake as Google, through the brand auth page. */
+type MicrosoftSignInOptions = GoogleSignInOptions;
+/** Callback for auth state changes. Receives the user on login, null on logout. */
+type AuthStateChangeCallback = (user: User | null) => void;
+
+interface AuthModuleOptions {
+    apiUrl?: string;
+    authPageUrl?: string;
+}
+/**
+ * Authentication module for managing user sessions.
+ *
+ * Handles Google SSO, trusted session adoption, sign-out, and automatic token refresh.
+ * Auth state is persisted to localStorage with key `mitra_auth_{appId}`
+ * and restored on page reload.
+ *
+ * @example
+ * ```typescript
+ * await mitra.auth.signInWithGoogle({ mode: 'popup' });
+ * console.log(mitra.auth.currentUser);
+ * ```
+ */
+declare class AuthModule {
+    #private;
+    private readonly appId;
+    private _currentUser;
+    private sessionGeneration;
+    private refreshFlight;
+    private transientRefreshFailureGeneration;
+    private readonly listeners;
+    private readonly sessionListeners;
+    private readonly storageKey;
+    private readonly publicClient;
+    private readonly authedClient;
+    private readonly currentUserApi;
+    private readonly googleAuth;
+    private readonly microsoftAuth;
+    constructor(appId: string, iamBaseUrl: string, options?: AuthModuleOptions);
+    /** The currently authenticated user, or null. */
+    get currentUser(): User | null;
+    /** The current JWT access token, or null. */
+    get accessToken(): string | null;
+    /** Whether a user is currently authenticated (local check, not server-validated). */
+    get isAuthenticated(): boolean;
+    /** @deprecated Email/password authentication is not implemented by IAM. Use Google or Microsoft SSO. */
+    signIn(_credentials: SignInCredentials): Promise<User>;
+    /**
+     * Signs in with Google SSO.
+     *
+     * Popup mode is used by default. Redirect mode stores a one-time CSRF context
+     * in `sessionStorage` and navigates to the configured `sdk-auth.html` page.
+     * Call {@link completeGoogleSignInRedirect} during application startup to
+     * finish a redirect response.
+     *
+     * The auth page is resolved from `createClient({ authPageUrl })`, then
+     * `window.__mitraEnv.authPageUrl`, and finally `/sdk-auth.html` on the API
+     * gateway origin.
+     *
+     * @param options - Popup or redirect mode.
+     * @returns The authenticated and hydrated user in popup mode.
+     * @throws {MitraApiError} When IAM rejects the authorization code.
+     * @throws {Error} When the browser blocks or cancels the popup, the flow times
+     * out, or the OAuth response fails origin, source, state, or shape validation.
+     *
+     * @example
+     * ```typescript
+     * const user = await mitra.auth.signInWithGoogle();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * await mitra.auth.signInWithGoogle({ mode: 'redirect' });
+     * ```
+     */
+    signInWithGoogle(options?: GoogleSignInOptions): Promise<User>;
+    /**
+     * Completes a Google redirect response from `#codeMitra` and `#stateMitra`.
+     *
+     * The method consumes and clears the fragment and stored CSRF context, sends
+     * the single-use code directly to IAM, persists both tokens, calls `auth.me()`,
+     * and notifies auth-state listeners. It returns `null` when the current URL is
+     * not a Google SSO redirect. Redirect errors must carry the same `stateMitra`
+     * stored at the start of the flow before their message is exposed or consumed.
+     *
+     * @returns The authenticated user, or `null` when no redirect result is present.
+     *
+     * @example
+     * ```typescript
+     * const redirectedUser = await mitra.auth.completeGoogleSignInRedirect();
+     * if (redirectedUser) console.log(redirectedUser.email);
+     * ```
+     */
+    completeGoogleSignInRedirect(): Promise<User | null>;
+    /**
+     * Signs in with Microsoft SSO: the same auth-page handshake as Google, exchanged
+     * at IAM's `/auth/microsoft`. Popup by default; redirect mode navigates away.
+     *
+     * @example
+     * ```typescript
+     * const user = await mitra.auth.signInWithMicrosoft();
+     * ```
+     */
+    signInWithMicrosoft(options?: MicrosoftSignInOptions): Promise<User>;
+    /**
+     * Completes a Microsoft redirect response from `#codeMitra` and `#stateMitra`.
+     * Mirrors {@link completeGoogleSignInRedirect}; returns `null` when the current
+     * URL is not a Microsoft SSO redirect.
+     */
+    completeMicrosoftSignInRedirect(): Promise<User | null>;
+    /** @deprecated Email/password registration is not implemented by IAM. Use Google or Microsoft SSO. */
+    signUp(_data: SignUpData): Promise<User>;
+    /**
+     * Signs out the current user, clearing all auth state and localStorage.
+     *
+     * @param redirectUrl - Optional URL to navigate to after sign-out.
+     *
+     * @example
+     * ```typescript
+     * mitra.auth.signOut();
+     * mitra.auth.signOut('/login');
+     * ```
+     */
+    signOut(redirectUrl?: string): void;
+    /**
+     * Refreshes the session using the stored refresh token.
+     *
+     * Called automatically before requests whose JWT is close to expiry and on
+     * `401` responses. Can also be called manually. Multiple proactive, reactive,
+     * and manual calls are deduplicated into one refresh request.
+     *
+     * @returns `true` if refresh succeeded, `false` otherwise.
+     *
+     * @example
+     * ```typescript
+     * const ok = await mitra.auth.refreshSession();
+     * if (!ok) mitra.auth.redirectToLogin();
+     * ```
+     */
+    refreshSession(): Promise<boolean>;
+    /**
+     * Resolves a 401 against the credential that actually reached the server.
+     * A newer session is retried as-is instead of being refreshed because of an
+     * older request. A signed-out session is neither refreshed nor retried.
+     *
+     * @param requestToken - Access token attached to the rejected request.
+     * @returns Whether the request should be retried once with the current token.
+     *
+     * @internal
+     */
+    private handleUnauthorized;
+    /**
+     * Fetches the current user from the server and updates local state.
+     *
+     * Clears auth state on a definitive 401. When the request reaches 401 after
+     * IAM refresh failed due to a network error, 408, 429, or 5xx response, the
+     * retained session is preserved and this method returns null.
+     *
+     * @returns The user if authenticated, `null` otherwise.
+     *
+     * @example
+     * ```typescript
+     * const user = await mitra.auth.me();
+     * if (!user) console.log('Not authenticated');
+     * ```
+     */
+    me(): Promise<User | null>;
+    /**
+     * Validates the current session with the server.
+     *
+     * @returns `true` if the session is valid, `false` otherwise.
+     *
+     * @example
+     * ```typescript
+     * const valid = await mitra.auth.checkAuth();
+     * if (!valid) mitra.auth.redirectToLogin();
+     * ```
+     */
+    checkAuth(): Promise<boolean>;
+    /**
+     * Sets the access token manually (e.g., from SSO/OAuth callback).
+     *
+     * Call `me()` afterwards to fetch the associated user data.
+     *
+     * @param token - JWT access token.
+     * @param saveToStorage - Whether to persist to localStorage (default: true).
+     *
+     * @example
+     * ```typescript
+     * mitra.auth.setToken(tokenFromCallback);
+     * await mitra.auth.me();
+     * ```
+     */
+    setToken(token: string, saveToStorage?: boolean): void;
+    /**
+     * Reads the tokens currently held by this module.
+     *
+     * Used by the legacy session bridge to hand a session persisted by this SDK
+     * over to `mitra-interactions-sdk` on startup.
+     *
+     * @returns The access and refresh tokens, each `null` when absent.
+     *
+     * @internal
+     */
+    private readSessionTokens;
+    /**
+     * Adopts an app-scoped session received from a trusted platform boundary.
+     *
+     * This preserves the access and refresh tokens together so the normal refresh
+     * lifecycle continues after an embedded preview hands its session to the app.
+     * Call {@link checkAuth} afterward to validate the token and hydrate the user.
+     */
+    setSession(session: AuthSession): boolean;
+    /**
+     * Ensures the current access token has enough remaining validity.
+     *
+     * JWT decoding is used only as a scheduling heuristic. Opaque tokens and JWTs
+     * without a numeric `exp` claim proceed unchanged and remain server-authoritative.
+     * Multiple proactive and reactive callers share the same refresh request.
+     * Transient refresh failures preserve the current session so the caller can
+     * continue and rely on the normal one-time `401` refresh fallback.
+     *
+     * This method is suitable for authenticated HTTP, WebSocket, and Server-Sent
+     * Events boundaries that need a fresh token before connecting.
+     *
+     * @param minValidityMs - Minimum remaining token lifetime. Defaults to 30 seconds.
+     * @returns `true` when no refresh is needed or refresh succeeds. Returns
+     * `false` when a required refresh fails, even when a transient failure keeps
+     * the current session available for a reactive server-authoritative fallback.
+     */
+    ensureFreshSession(minValidityMs?: number): Promise<boolean>;
+    /**
+     * Subscribes an internal boundary to token changes without triggering login
+     * or refresh. Unlike auth-state listeners, this callback is not invoked
+     * immediately and does not depend on the user being hydrated.
+     *
+     * @param callback - Receives the current access and refresh tokens.
+     * @returns A function that removes the callback.
+     *
+     * @internal
+     */
+    private onSessionChange;
+    /**
+     * Adopts a session produced outside this module, such as a legacy SSO login.
+     *
+     * Replaces the in-memory tokens and persists them under the same storage key
+     * the rest of the module uses. The current user is left untouched because the
+     * legacy SDK does not return one; call `me()` to hydrate it.
+     *
+     * @param session - Access token and, when the issuer returned one, refresh token.
+     *
+     * @internal
+     */
+    private adoptSession;
+    /**
+     * Redirects to `/login?returnUrl=...` for unauthenticated users.
+     *
+     * @param returnUrl - URL to return to after login (default: '/').
+     *
+     * @example
+     * ```typescript
+     * if (!mitra.auth.isAuthenticated) {
+     *   mitra.auth.redirectToLogin(window.location.pathname);
+     * }
+     * ```
+     */
+    redirectToLogin(returnUrl?: string): void;
+    /**
+     * Registers a callback for auth state changes.
+     *
+     * Called immediately with the current state, then on every sign-in/sign-out.
+     *
+     * @param callback - Receives the User on login, null on logout.
+     * @returns Unsubscribe function.
+     *
+     * @example
+     * ```typescript
+     * useEffect(() => {
+     *   const unsub = mitra.auth.onAuthStateChange((user) => {
+     *     setUser(user);
+     *     setLoading(false);
+     *   });
+     *   return unsub;
+     * }, []);
+     * ```
+     */
+    onAuthStateChange(callback: AuthStateChangeCallback): () => void;
+    private doRefresh;
+    private establishSession;
+    private setAuthState;
+    private getCurrentUser;
+    private clearAuthState;
+    private invalidatePendingRefreshes;
+    private hasValidAppIdentity;
+    private belongsToConfiguredApp;
+    private notifySessionListeners;
+    private notifyListeners;
+    private saveToStorage;
+    private loadFromStorage;
+    private removeFromStorage;
+}
+
+/**
+ * Compatibility facade for the Platform SDK 1.x entity API.
+ * Shared request behavior lives in `@mitralab.io/sdk-core`.
+ */
+declare class EntitiesModule {
+    private readonly httpClient;
+    private core;
+    constructor(httpClient: HttpClient, _dataSourceId: string);
+    static createProxy(httpClient: HttpClient, dataSourceId: string): EntitiesModule;
+    /**
+     * Preserved for Platform SDK 1.x compatibility.
+     * Records now resolve the app from authenticated context instead of a data source path.
+     */
+    setDataSourceId(_dataSourceId: string): void;
+    getTable<T = Record<string, unknown>>(tableName: string): EntityTable<T>;
+}
+type EntitiesProxy = EntitiesModule & {
+    [tableName: string]: EntityTable;
+};
+
+/** Platform SDK 1.x facade over the shared Function contract. */
+declare class FunctionsModule {
+    private readonly core;
+    constructor(httpClient: HttpClient);
+    /**
+     * Executes a Function synchronously and waits for its terminal result.
+     */
+    execute(functionId: string, input?: Record<string, unknown>): Promise<FunctionExecution>;
+    /** Queues a Function and returns its initial execution record. */
+    executeAsync(functionId: string, input?: Record<string, unknown>): Promise<FunctionExecution>;
+    /** Reads the current state of an asynchronous Function execution. */
+    getExecution(executionId: string): Promise<FunctionExecution>;
+    /** Requests cancellation of a queued or running Function execution. */
+    cancelExecution(executionId: string): Promise<void>;
+}
+
+/** Platform SDK 1.x facade over the shared integration contract. */
+declare class IntegrationModule {
+    private readonly core;
+    private readonly configs;
+    constructor(httpClient: HttpClient);
+    /** Lists the current app's integration configs without exposing admin mutations. */
+    list(options?: ListTemplateConfigsOptions): Promise<TemplateConfigPage>;
+    executeResource(resourceId: string, params?: Record<string, unknown>): Promise<ProxyResult>;
+    execute(configId: string, request: ProxyInput): Promise<ProxyResult>;
+    /** Executes a saved integration config selected by its app-scoped alias. */
+    executeByAlias(alias: string, request: ProxyInput): Promise<ProxyResult>;
+}
+
+/** Platform SDK 1.x facade over the shared custom query contract. */
+declare class QueriesModule {
+    private readonly core;
+    constructor(httpClient: HttpClient);
+    /**
+     * @deprecated Preserved for Platform SDK 1.x source compatibility. Data Manager now resolves
+     * the Data Source from the authenticated app.
+     */
+    setDataSourceId(_dataSourceId: string): void;
+    execute(id: string, parameters?: Record<string, unknown>): Promise<QueryResult>;
+}
+
+type AgentCredentialProvider = 'ANTHROPIC' | 'OPENAI';
+type AgentOAuthProvider = 'ANTHROPIC';
+type AgentDeviceProvider = 'OPENAI';
+interface AgentCredentialsModule {
+    list(): Promise<CredentialStatus[]>;
+    listModels(agentId?: string): Promise<AgentModel$1[]>;
+    saveApiKey(provider: AgentCredentialProvider, apiKey: string): Promise<void>;
+    remove(provider: AgentCredentialProvider): Promise<void>;
+    startOAuth(provider: AgentOAuthProvider): Promise<OAuthStartResult>;
+    exchangeOAuth(provider: AgentOAuthProvider, input: OAuthExchangeInput): Promise<AuthenticationResult>;
+    startDeviceAuthorization(provider: AgentDeviceProvider): Promise<DeviceAuthorization>;
+    pollDeviceAuthorization(provider: AgentDeviceProvider, deviceAuthId: string): Promise<AuthenticationResult>;
+}
+
+/**
+ * Configuration options for creating a Mitra client.
+ */
+interface MitraClientConfig {
+    /**
+     * Your app's unique identifier.
+     * Found in the Mitra Code Studio dashboard.
+     */
+    appId: string;
+    /**
+     * Base URL for the Mitra API (Kong Gateway).
+     * Injected automatically via `VITE_MITRA_API_URL` environment variable
+     * during the Code Studio build process.
+     *
+     * @example
+     * ```typescript
+     * apiUrl: import.meta.env.VITE_MITRA_API_URL
+     * ```
+     */
+    apiUrl: string;
+    /**
+     * Absolute URL of the Mitra Google SSO page.
+     *
+     * When omitted, the SDK reads `window.__mitraEnv.authPageUrl` and then falls
+     * back to `/sdk-auth.html` on the origin of `apiUrl`.
+     *
+     * @example
+     * ```typescript
+     * authPageUrl: 'https://auth.example.com/sdk-auth.html'
+     * ```
+     */
+    authPageUrl?: string;
+    /**
+     * Global error handler called whenever an API request fails.
+     * Useful for displaying toast notifications or logging errors.
+     *
+     * @example
+     * ```typescript
+     * const mitra = createClient({
+     *   appId: 'your-app-id',
+     *   apiUrl: 'https://api.example.com',
+     *   onError: (error) => toast.error(error.message),
+     * });
+     * ```
+     */
+    onError?: (error: MitraApiError) => void;
+}
+/**
+ * The Mitra client instance providing access to all SDK modules.
+ *
+ * @example
+ * ```typescript
+ * const mitra = createClient({
+ *   appId: 'your-app-id',
+ *   apiUrl: 'https://api.example.com',
+ * });
+ *
+ * // Initialize (resolves app config automatically)
+ * await mitra.init();
+ *
+ * // Authentication
+ * await mitra.auth.signInWithGoogle({ mode: 'popup' });
+ *
+ * // Database operations
+ * const tasks = await mitra.entities.Task.list();
+ *
+ * // Serverless functions
+ * const execution = await mitra.functions.execute('function-id', { orderId });
+ * ```
+ */
+interface MitraClient {
+    /**
+     * Initializes the client by resolving app config from the server.
+     *
+     * Fetches the compatibility dataSourceId and allowSignup from the public app info endpoint.
+     *
+     * Safe to call multiple times. Subsequent calls are no-ops.
+     *
+     * @example
+     * ```typescript
+     * const mitra = createClient({
+     *   appId: 'your-app-id',
+     *   apiUrl: 'https://api.example.com',
+     * });
+     * await mitra.init();
+     * ```
+     */
+    init(): Promise<void>;
+    /**
+     * Authentication module for managing user sessions.
+     *
+     * Handles Google SSO, trusted preview sessions, and session lifecycle.
+     *
+     * @example
+     * ```typescript
+     * await mitra.auth.signInWithGoogle({ mode: 'popup' });
+     * console.log(mitra.auth.currentUser);
+     * ```
+     */
+    auth: AuthModule;
+    /**
+     * Entities module for database CRUD operations.
+     *
+     * Access any table dynamically using `mitra.entities.TableName`.
+     *
+     * @example
+     * ```typescript
+     * const tasks = await mitra.entities.Task.list('-created_at', 10);
+     * const task = await mitra.entities.Task.create({ title: 'New task' });
+     * ```
+     */
+    entities: EntitiesProxy;
+    /**
+     * Functions module for executing serverless functions.
+     *
+     * @example
+     * ```typescript
+     * const execution = await mitra.functions.execute('function-id', { orderId });
+     * console.log(execution.status, execution.output);
+     * ```
+     */
+    functions: FunctionsModule;
+    /** Anonymous execution of Functions explicitly published as public. */
+    publicFunctions: PublicFunctionsModule;
+    /** Browser-safe Agent task REST API and native live sessions. */
+    agentTasks: AgentTasksWithSessions;
+    /** Browser-safe credential status, model discovery, and provider auth flows. */
+    agentCredentials: AgentCredentialsModule;
+    /**
+     * Integration module for proxying HTTP requests to external APIs.
+     *
+     * Sends requests through the Mitra server, which handles authentication
+     * and credential injection automatically based on the template config.
+     *
+     * @example
+     * ```typescript
+     * const result = await mitra.integration.execute('config-id', {
+     *   method: 'GET',
+     *   endpoint: '/users',
+     * });
+     * console.log(result.body);
+     * ```
+     */
+    integration: IntegrationModule;
+    /**
+     * Queries module for executing reusable named SELECT queries.
+     *
+     * @example
+     * ```typescript
+     * const result = await mitra.queries.execute('query-id', { status: 'active' });
+     * console.log(result.rows);
+     * ```
+     */
+    queries: QueriesModule;
+    /**
+     * Whether this app allows public user registration.
+     * Defaults to `true` before `init()` is called.
+     */
+    readonly allowSignup: boolean;
+    /**
+     * The configuration used to create this client.
+     */
+    config: MitraClientConfig;
+}
+/**
+ * Creates a new Mitra client instance.
+ *
+ * The client provides access to all Mitra Platform features:
+ * - **auth**: User authentication and session management
+ * - **entities**: Database CRUD operations
+ * - **functions**: Serverless function invocation
+ * - **integration**: Proxy HTTP requests to external APIs
+ * - **queries**: Custom query management and execution
+ *
+ * After creating the client, call `init()` to resolve the app's compatibility config
+ * (dataSourceId, allowSignup) automatically from the server.
+ *
+ * @param config - Configuration options for the client.
+ * @returns A configured MitraClient instance.
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from '@mitralab.io/platform-sdk';
+ *
+ * const mitra = createClient({
+ *   appId: import.meta.env.VITE_MITRA_APP_ID,
+ *   apiUrl: import.meta.env.VITE_MITRA_API_URL,
+ * });
+ *
+ * await mitra.init();
+ *
+ * // Use the client
+ * await mitra.auth.signInWithGoogle({ mode: 'popup' });
+ * const tasks = await mitra.entities.Task.list();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Export as singleton for use throughout your app
+ * // src/api/mitraClient.ts
+ * import { createClient } from '@mitralab.io/platform-sdk';
+ *
+ * export const mitra = createClient({
+ *   appId: import.meta.env.VITE_MITRA_APP_ID,
+ *   apiUrl: import.meta.env.VITE_MITRA_API_URL,
+ * });
+ * ```
+ */
+declare function createClient(config: MitraClientConfig): MitraClient;
+
+/**
+ * Legacy `mitra-interactions-sdk` surface, re-exported so an application can
+ * swap the legacy package for `@mitralab.io/platform-sdk` without rewriting
+ * call sites first.
+ *
+ * Everything here is deprecated. The capabilities remain available during
+ * migration even when the native API has different input or response
+ * semantics.
+ *
+ * The four legacy entry points that produce a session are wrapped so the
+ * resulting session also lands in this SDK. Every other export is the legacy
+ * implementation itself.
+ *
+ * @module
+ */
+
+/**
+ * @deprecated Use `mitra.auth.signInWithGoogle()` when `method` is Google.
+ * Other legacy login methods remain supported until an equivalent exists.
+ */
+declare const loginMitra: typeof loginMitra$1;
+/**
+ * @deprecated Use `mitra.auth.signInWithGoogle()`.
+ */
+declare const loginWithGoogleMitra: typeof loginWithGoogleMitra$1;
+/**
+ * @deprecated Use `mitra.auth.signInWithMicrosoft()`.
+ */
+declare const loginWithMicrosoftMitra: typeof loginWithMicrosoftMitra$1;
+/**
+ * @deprecated For Google redirects, use
+ * `mitra.auth.completeGoogleSignInRedirect()`. Other providers remain supported
+ * through the legacy surface.
+ */
+declare const exchangeSsoCodeMitra: typeof exchangeSsoCodeMitra$1;
+
+/** @deprecated Legacy compatibility type. */
+type AgentChat = LegacyTypes.AgentChat;
+/** @deprecated Legacy compatibility type. */
+type AgentCredentialStatus = LegacyTypes.AgentCredentialStatus;
+/** @deprecated Legacy compatibility type. */
+type AgentDeltaEvent = LegacyTypes.AgentDeltaEvent;
+/** @deprecated Legacy compatibility type. */
+type AgentErrorEvent = LegacyTypes.AgentErrorEvent;
+/** @deprecated Legacy compatibility type. */
+type AgentMessage = LegacyTypes.AgentMessage;
+/** @deprecated Legacy compatibility type. */
+type AgentModel = LegacyTypes.AgentModel;
+/** @deprecated Legacy compatibility type. */
+type AgentProvider = LegacyTypes.AgentProvider;
+/** @deprecated Legacy compatibility type. */
+type AgentQueueChangeEvent = LegacyTypes.AgentQueueChangeEvent;
+/** @deprecated Legacy compatibility type. */
+type AgentRawEvent = LegacyTypes.AgentRawEvent;
+/** @deprecated Legacy compatibility type. */
+type AgentStatusChangeEvent = LegacyTypes.AgentStatusChangeEvent;
+/** @deprecated Legacy compatibility type. */
+type AgentTaskCreatedEvent = LegacyTypes.AgentTaskCreatedEvent;
+/** @deprecated Legacy compatibility type. */
+type AgentTaskEventMap = LegacyTypes.AgentTaskEventMap;
+/** @deprecated Legacy compatibility type. */
+type AgentTaskEventName = LegacyTypes.AgentTaskEventName;
+/** @deprecated Legacy compatibility type. */
+type AgentTaskSession = LegacyTypes.AgentTaskSession;
+/** @deprecated Legacy compatibility type. */
+type AgentTaskStatus = LegacyTypes.AgentTaskStatus;
+/** @deprecated Legacy compatibility type. */
+type AgentTaskTransport = LegacyTypes.AgentTaskTransport;
+/** @deprecated Legacy compatibility type. */
+type AgentTimelineItem = LegacyTypes.AgentTimelineItem;
+/** @deprecated Legacy compatibility type. */
+type AgentToolEvent = LegacyTypes.AgentToolEvent;
+/** @deprecated Legacy compatibility type. */
+type AgentTurnEndEvent = LegacyTypes.AgentTurnEndEvent;
+/** @deprecated Legacy compatibility type. */
+type AgentType = LegacyTypes.AgentType;
+/** @deprecated Legacy compatibility type. */
+type AuthAgentCredentialResult = LegacyTypes.AuthAgentCredentialResult;
+/** @deprecated Legacy compatibility type. */
+type CallIntegrationOptions = LegacyTypes.CallIntegrationOptions;
+/** @deprecated Legacy compatibility type. */
+type CallIntegrationResponse = LegacyTypes.CallIntegrationResponse;
+/** @deprecated Legacy compatibility type. */
+type ChatManageAction = LegacyTypes.ChatManageAction;
+/** @deprecated Legacy compatibility type. */
+type ConnectAgentCredentialResult = LegacyTypes.ConnectAgentCredentialResult;
+/** @deprecated Legacy compatibility type. */
+type CreateRecordOptions = LegacyTypes.CreateRecordOptions;
+/** @deprecated Legacy compatibility type. */
+type CreateRecordsBatchOptions = LegacyTypes.CreateRecordsBatchOptions;
+/** @deprecated Legacy compatibility type. */
+type CredentialAction = LegacyTypes.CredentialAction;
+/** @deprecated Legacy compatibility type. */
+type DeleteAgentChatResult = LegacyTypes.DeleteAgentChatResult;
+/** @deprecated Legacy compatibility type. */
+type DeleteRecordOptions = LegacyTypes.DeleteRecordOptions;
+/** @deprecated Legacy compatibility type. */
+type DeviceAuthAgentCredentialResult = LegacyTypes.DeviceAuthAgentCredentialResult;
+/** @deprecated Legacy compatibility type. */
+type ExecutePublicServerFunctionAsyncResponse = LegacyTypes.ExecutePublicServerFunctionAsyncResponse;
+/** @deprecated Legacy compatibility type. */
+type ExecutePublicServerFunctionOptions = LegacyTypes.ExecutePublicServerFunctionOptions;
+/** @deprecated Legacy compatibility type. */
+type ExecutePublicServerFunctionResponse = LegacyTypes.ExecutePublicServerFunctionResponse;
+/** @deprecated Legacy compatibility type. */
+type ExecuteServerFunctionAsyncOptions = LegacyTypes.ExecuteServerFunctionAsyncOptions;
+/** @deprecated Legacy compatibility type. */
+type ExecuteServerFunctionAsyncResponse = LegacyTypes.ExecuteServerFunctionAsyncResponse;
+/** @deprecated Legacy compatibility type. */
+type ExecuteServerFunctionOptions = LegacyTypes.ExecuteServerFunctionOptions;
+/** @deprecated Legacy compatibility type. */
+type ExecuteServerFunctionResponse = LegacyTypes.ExecuteServerFunctionResponse;
+/** @deprecated Legacy compatibility type. */
+type GetAgentTaskCreateOptions = LegacyTypes.GetAgentTaskCreateOptions;
+/** @deprecated Legacy compatibility type. */
+type GetAgentTaskOpenOptions = LegacyTypes.GetAgentTaskOpenOptions;
+/** @deprecated Legacy compatibility type. */
+type GetAgentTaskOptions = LegacyTypes.GetAgentTaskOptions;
+/** @deprecated Legacy compatibility type. */
+type GetPublicServerFunctionExecutionOptions = LegacyTypes.GetPublicServerFunctionExecutionOptions;
+/** @deprecated Legacy compatibility type. */
+type GetPublicServerFunctionExecutionResponse = LegacyTypes.GetPublicServerFunctionExecutionResponse;
+/** @deprecated Legacy compatibility type. */
+type GetRecordOptions = LegacyTypes.GetRecordOptions;
+/** @deprecated Legacy compatibility type. */
+type IntegrationResponse = LegacyTypes.IntegrationResponse;
+/** @deprecated Legacy compatibility type. */
+type ListAgentModelsResult = LegacyTypes.ListAgentModelsResult;
+/** @deprecated Legacy compatibility type. */
+type ListAgentProvidersResult = LegacyTypes.ListAgentProvidersResult;
+/** @deprecated Legacy compatibility type. */
+type ListIntegrationsOptions = LegacyTypes.ListIntegrationsOptions;
+/** @deprecated Legacy compatibility type. */
+type ListRecordsOptions = LegacyTypes.ListRecordsOptions;
+/** @deprecated Legacy compatibility type. */
+type ListRecordsResponse = LegacyTypes.ListRecordsResponse;
+/** @deprecated Legacy compatibility type. */
+type LoginOptions = LegacyTypes.LoginOptions;
+/** @deprecated Legacy compatibility type. */
+type LoginResponse = LegacyTypes.LoginResponse;
+/** @deprecated Legacy compatibility type. */
+type ManageAgentChatDeleteOptions = LegacyTypes.ManageAgentChatDeleteOptions;
+/** @deprecated Legacy compatibility type. */
+type ManageAgentChatListOptions = LegacyTypes.ManageAgentChatListOptions;
+/** @deprecated Legacy compatibility type. */
+type ManageAgentChatOptions = LegacyTypes.ManageAgentChatOptions;
+/** @deprecated Legacy compatibility type. */
+type ManageAgentChatRenameOptions = LegacyTypes.ManageAgentChatRenameOptions;
+/** @deprecated Legacy compatibility type. */
+type ManageAgentCredentialOptions = LegacyTypes.ManageAgentCredentialOptions;
+/** @deprecated Legacy compatibility type. */
+type MitraConfig = LegacyTypes.MitraConfig;
+/** @deprecated Legacy compatibility type. */
+type MitraInstance = LegacyTypes.MitraInstance;
+/** @deprecated Legacy compatibility type. */
+type PatchRecordOptions = LegacyTypes.PatchRecordOptions;
+/** @deprecated Legacy compatibility type. */
+type QueuedItem = LegacyTypes.QueuedItem;
+/** @deprecated Legacy compatibility type. */
+type RenameAgentChatResult = LegacyTypes.RenameAgentChatResult;
+/** @deprecated Legacy compatibility type. */
+type SendOptions = LegacyTypes.SendOptions;
+/** @deprecated Legacy compatibility type. */
+type StopServerFunctionExecutionOptions = LegacyTypes.StopServerFunctionExecutionOptions;
+/** @deprecated Legacy compatibility type. */
+type StopServerFunctionExecutionResponse = LegacyTypes.StopServerFunctionExecutionResponse;
+/** @deprecated Legacy compatibility type. */
+type UpdateRecordOptions = LegacyTypes.UpdateRecordOptions;
+
+export { type AgentChat, type AgentCredentialProvider, type AgentCredentialStatus, type AgentCredentialsModule, type AgentDeltaEvent, type AgentDeviceProvider, type AgentErrorEvent, type AgentMessage, type AgentModel, type AgentOAuthProvider, type AgentProvider, type AgentQueueChangeEvent, type AgentRawEvent, type AgentStatusChangeEvent, type AgentTaskCreatedEvent, type AgentTaskEventMap, type AgentTaskEventName, type AgentTaskSession, type AgentTaskStatus, type AgentTaskTransport, type AgentTimelineItem, type AgentToolEvent, type AgentTurnEndEvent, type AgentType, type AuthAgentCredentialResult, type CallIntegrationOptions, type CallIntegrationResponse, type ChatManageAction, type ConnectAgentCredentialResult, type CreateRecordOptions, type CreateRecordsBatchOptions, type CredentialAction, type DeleteAgentChatResult, type DeleteRecordOptions, type DeviceAuthAgentCredentialResult, type ExecutePublicServerFunctionAsyncResponse, type ExecutePublicServerFunctionOptions, type ExecutePublicServerFunctionResponse, type ExecuteServerFunctionAsyncOptions, type ExecuteServerFunctionAsyncResponse, type ExecuteServerFunctionOptions, type ExecuteServerFunctionResponse, type GetAgentTaskCreateOptions, type GetAgentTaskOpenOptions, type GetAgentTaskOptions, type GetPublicServerFunctionExecutionOptions, type GetPublicServerFunctionExecutionResponse, type GetRecordOptions, type GoogleSignInOptions, type IntegrationResponse, type ListAgentModelsResult, type ListAgentProvidersResult, type ListIntegrationsOptions, type ListRecordsOptions, type ListRecordsResponse, type LoginOptions, type LoginResponse, type ManageAgentChatDeleteOptions, type ManageAgentChatListOptions, type ManageAgentChatOptions, type ManageAgentChatRenameOptions, type ManageAgentCredentialOptions, type MicrosoftSignInOptions, MitraApiError, type MitraClient, type MitraClientConfig, type MitraConfig, type MitraInstance, type PatchRecordOptions, type QueuedItem, type RenameAgentChatResult, type SendOptions, type SignInCredentials, type SignUpData, type StopServerFunctionExecutionOptions, type StopServerFunctionExecutionResponse, type UpdateRecordOptions, type User, createClient, exchangeSsoCodeMitra, loginMitra, loginWithGoogleMitra, loginWithMicrosoftMitra };