@mitralab.io/platform-sdk 1.0.1

package/dist/index.d.ts

@@ -0,0 +1,1140 @@
+/** Allowed query parameter value types. */
+type QueryParamValue = string | number | boolean | undefined;
+/**
+ * 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;
+    /** Callback invoked on 401 responses. Should attempt token refresh and return true if successful. */
+    onUnauthorized?: () => 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 {
+    /** 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 {
+    private readonly baseUrl;
+    private readonly tokenGetter;
+    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>;
+    /**
+     * 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;
+}
+/** Callback for auth state changes. Receives the user on login, null on logout. */
+type AuthStateChangeCallback = (user: User | null) => void;
+
+/**
+ * Authentication module for managing user sessions.
+ *
+ * Handles sign-in, sign-up, 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.signIn({ email: 'user@example.com', password: 'password' });
+ * console.log(mitra.auth.currentUser);
+ * ```
+ */
+declare class AuthModule {
+    private readonly appId;
+    private _currentUser;
+    private _accessToken;
+    private _refreshToken;
+    private refreshPromise;
+    private readonly listeners;
+    private readonly storageKey;
+    private readonly publicClient;
+    private readonly authedClient;
+    constructor(appId: string, iamBaseUrl: string);
+    /** 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;
+    /**
+     * Signs in a user with email and password.
+     *
+     * On success, stores access token, refresh token, and user data.
+     * Subsequent API requests use the token automatically.
+     *
+     * @param credentials - Email and password.
+     * @returns The authenticated user.
+     * @throws {MitraApiError} On invalid credentials (401).
+     *
+     * @example
+     * ```typescript
+     * const user = await mitra.auth.signIn({
+     *   email: 'user@example.com',
+     *   password: 'password123',
+     * });
+     * ```
+     */
+    signIn(credentials: SignInCredentials): Promise<User>;
+    /**
+     * Registers a new user and signs them in automatically.
+     *
+     * @param data - Email, password, and optional name.
+     * @returns The newly created and authenticated user.
+     * @throws {MitraApiError} On duplicate email (409) or validation error (400).
+     *
+     * @example
+     * ```typescript
+     * const user = await mitra.auth.signUp({
+     *   email: 'new@example.com',
+     *   password: 'securepassword',
+     *   name: 'Jane Doe',
+     * });
+     * ```
+     */
+    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 by the SDK on 401 responses. Can also be called
+     * manually. Multiple concurrent calls are deduplicated (only one refresh
+     * request is made).
+     *
+     * @returns `true` if refresh succeeded, `false` otherwise.
+     *
+     * @example
+     * ```typescript
+     * const ok = await mitra.auth.refreshSession();
+     * if (!ok) mitra.auth.redirectToLogin();
+     * ```
+     */
+    refreshSession(): Promise<boolean>;
+    /**
+     * Fetches the current user from the server and updates local state.
+     *
+     * Only clears auth state on 401 (expired/invalid token).
+     * Transient errors (500, network) return null without clearing the session.
+     *
+     * @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;
+    /**
+     * 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 setAuthState;
+    private clearAuthState;
+    private notifyListeners;
+    private saveToStorage;
+    private loadFromStorage;
+    private removeFromStorage;
+}
+
+/**
+ * Options for listing entities with sorting and pagination.
+ */
+interface EntityListOptions {
+    /**
+     * Field to sort by. Prefix with '-' for descending order.
+     *
+     * @example
+     * ```typescript
+     * // Sort by created_at descending (newest first)
+     * { sort: '-created_at' }
+     *
+     * // Sort by name ascending (A-Z)
+     * { sort: 'name' }
+     * ```
+     */
+    sort?: string;
+    /**
+     * Maximum number of records to return.
+     * Defaults to 100. Maximum allowed is 1000.
+     */
+    limit?: number;
+    /**
+     * Number of records to skip for pagination.
+     * Use with `limit` to implement pagination.
+     *
+     * @example
+     * ```typescript
+     * // Get page 2 (records 11-20)
+     * { limit: 10, skip: 10 }
+     * ```
+     */
+    skip?: number;
+    /**
+     * Array of field names to include in the response.
+     * If not specified, all fields are returned.
+     *
+     * @example
+     * ```typescript
+     * // Only return id, title, and status
+     * { fields: ['id', 'title', 'status'] }
+     * ```
+     */
+    fields?: string[];
+}
+/**
+ * Entity handler providing CRUD operations for a specific entity type.
+ *
+ * Each table in the database gets a handler with these methods for managing data.
+ * Access tables dynamically using `mitra.entities.TableName`.
+ *
+ * @typeParam T - The shape of records in this table. Defaults to `Record<string, unknown>`.
+ *
+ * @example
+ * ```typescript
+ * // Dynamic access (no type safety)
+ * const tasks = await mitra.entities.Task.list();
+ *
+ * // Typed access
+ * interface Task {
+ *   id: string;
+ *   title: string;
+ *   status: 'pending' | 'done';
+ * }
+ * const tasks = mitra.entities.getTable<Task>('Task');
+ * const pending = await tasks.filter({ status: 'pending' });
+ * ```
+ */
+interface EntityTable<T = Record<string, unknown>> {
+    /**
+     * Lists records with optional pagination and sorting.
+     *
+     * Retrieves all records from the table with support for sorting,
+     * pagination, and field selection. Supports both positional parameters
+     * (for quick usage) and options object (for clarity).
+     *
+     * @param sortOrOptions - Sort field (e.g., '-created_at') or options object.
+     * @param limit - Maximum number of results to return. Defaults to 100.
+     * @param skip - Number of results to skip for pagination. Defaults to 0.
+     * @param fields - Array of field names to include in the response.
+     * @returns Promise resolving to an array of records.
+     *
+     * @example
+     * ```typescript
+     * // Get all records
+     * const tasks = await mitra.entities.Task.list();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Get first 10 records sorted by date (newest first)
+     * const tasks = await mitra.entities.Task.list('-created_at', 10);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Get paginated results (page 3, 10 items per page)
+     * const tasks = await mitra.entities.Task.list('-created_at', 10, 20);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Using options object
+     * const tasks = await mitra.entities.Task.list({
+     *   sort: '-created_at',
+     *   limit: 10,
+     *   skip: 0,
+     *   fields: ['id', 'title', 'status'],
+     * });
+     * ```
+     */
+    list(sortOrOptions?: string | EntityListOptions, limit?: number, skip?: number, fields?: string[]): Promise<T[]>;
+    /**
+     * Filters records based on a query.
+     *
+     * Retrieves records that match specific criteria with support for
+     * sorting, pagination, and field selection. All query conditions
+     * are combined with AND logic.
+     *
+     * @param query - Query object with field-value pairs. Records matching
+     *   all specified criteria are returned. Field names are case-sensitive.
+     * @param sort - Sort field (prefix '-' for descending). Defaults to '-created_at'.
+     * @param limit - Maximum number of results to return. Defaults to 100.
+     * @param skip - Number of results to skip for pagination. Defaults to 0.
+     * @param fields - Array of field names to include in the response.
+     * @returns Promise resolving to an array of matching records.
+     *
+     * @example
+     * ```typescript
+     * // Filter by single field
+     * const doneTasks = await mitra.entities.Task.filter({ status: 'done' });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Filter by multiple fields (AND logic)
+     * const urgentTasks = await mitra.entities.Task.filter({
+     *   status: 'pending',
+     *   priority: 'high',
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Filter with sorting and pagination
+     * const tasks = await mitra.entities.Task.filter(
+     *   { status: 'pending' },
+     *   '-priority',  // sort by priority descending
+     *   10,           // limit
+     *   0             // skip
+     * );
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Filter with specific fields
+     * const tasks = await mitra.entities.Task.filter(
+     *   { assignee: 'user-123' },
+     *   '-created_at',
+     *   20,
+     *   0,
+     *   ['id', 'title', 'status']
+     * );
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Comparison operators: $gt, $gte, $lt, $lte, $ne
+     * const expensive = await mitra.entities.Product.filter({ price: { $gt: 100 } });
+     * const recent = await mitra.entities.Order.filter({ created_at: { $gte: '2025-01-01' } });
+     * const notDone = await mitra.entities.Task.filter({ status: { $ne: 'done' } });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Range query (combines with AND)
+     * const midRange = await mitra.entities.Product.filter({
+     *   price: { $gte: 50, $lte: 200 },
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Mix equality and operators
+     * const results = await mitra.entities.Order.filter({
+     *   status: 'shipped',
+     *   total: { $gt: 1000 },
+     * });
+     * ```
+     */
+    filter(query: Record<string, unknown>, sort?: string, limit?: number, skip?: number, fields?: string[]): Promise<T[]>;
+    /**
+     * Gets a single record by ID.
+     *
+     * Retrieves a specific record using its unique identifier.
+     *
+     * @param id - The unique identifier of the record.
+     * @returns Promise resolving to the record.
+     * @throws {MitraApiError} When record is not found (404).
+     *
+     * @example
+     * ```typescript
+     * const task = await mitra.entities.Task.get('task-123');
+     * console.log(task.title);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With error handling
+     * try {
+     *   const task = await mitra.entities.Task.get(taskId);
+     *   setTask(task);
+     * } catch (error) {
+     *   if (error.status === 404) {
+     *     console.error('Task not found');
+     *   }
+     * }
+     * ```
+     */
+    get(id: string | number): Promise<T>;
+    /**
+     * Creates a new record.
+     *
+     * Creates a new record in the table with the provided data.
+     * The server will generate an `id` and timestamps automatically.
+     *
+     * @param data - Object containing the record data.
+     * @returns Promise resolving to the created record (including generated id).
+     * @throws {MitraApiError} When validation fails (400).
+     *
+     * @example
+     * ```typescript
+     * const task = await mitra.entities.Task.create({
+     *   title: 'Complete documentation',
+     *   status: 'pending',
+     *   priority: 'high',
+     * });
+     * console.log('Created task:', task.id);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With error handling
+     * try {
+     *   const task = await mitra.entities.Task.create(formData);
+     *   toast.success('Task created!');
+     *   navigate(`/tasks/${task.id}`);
+     * } catch (error) {
+     *   toast.error(error.message);
+     * }
+     * ```
+     */
+    create(data: Partial<T>): Promise<T>;
+    /**
+     * Updates an existing record.
+     *
+     * Updates a record by ID with the provided data. Only the fields
+     * included in the data object will be updated; other fields remain
+     * unchanged (partial update).
+     *
+     * @param id - The unique identifier of the record to update.
+     * @param data - Object containing the fields to update.
+     * @returns Promise resolving to the updated record.
+     * @throws {MitraApiError} When record is not found (404).
+     *
+     * @example
+     * ```typescript
+     * // Update single field
+     * const updated = await mitra.entities.Task.update('task-123', {
+     *   status: 'completed',
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Update multiple fields
+     * const updated = await mitra.entities.Task.update('task-123', {
+     *   status: 'done',
+     *   completedAt: new Date().toISOString(),
+     *   completedBy: currentUser.id,
+     * });
+     * ```
+     */
+    update(id: string | number, data: Partial<T>): Promise<T>;
+    /**
+     * Deletes a single record by ID.
+     *
+     * Permanently removes a record from the database. This action cannot
+     * be undone.
+     *
+     * @param id - The unique identifier of the record to delete.
+     * @returns Promise resolving when deletion is complete.
+     * @throws {MitraApiError} When record is not found (404).
+     *
+     * @example
+     * ```typescript
+     * await mitra.entities.Task.delete('task-123');
+     * console.log('Task deleted');
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With confirmation
+     * if (confirm('Delete this task?')) {
+     *   await mitra.entities.Task.delete(task.id);
+     *   toast.success('Task deleted');
+     *   navigate('/tasks');
+     * }
+     * ```
+     */
+    delete(id: string | number): Promise<void>;
+    /**
+     * Deletes multiple records matching a query.
+     *
+     * Permanently removes all records that match the provided query.
+     * Use with caution as this action cannot be undone.
+     *
+     * @param query - Query object with field-value pairs. Records matching
+     *   all specified criteria will be deleted.
+     * @returns Promise resolving to object with count of deleted records.
+     *
+     * @example
+     * ```typescript
+     * // Delete all completed tasks
+     * const result = await mitra.entities.Task.deleteMany({ status: 'done' });
+     * console.log(`Deleted ${result.deleted} tasks`);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Delete by multiple criteria
+     * const result = await mitra.entities.Task.deleteMany({
+     *   status: 'archived',
+     *   createdAt: { $lt: '2024-01-01' },
+     * });
+     * ```
+     */
+    deleteMany(query: Record<string, unknown>): Promise<{
+        deleted: number;
+    }>;
+    /**
+     * Creates multiple records in a single request.
+     *
+     * Efficiently creates multiple records at once. This is faster than
+     * calling `create()` multiple times as it uses a single API request.
+     *
+     * @param data - Array of record data objects.
+     * @returns Promise resolving to an array of created records.
+     *
+     * @example
+     * ```typescript
+     * const tasks = await mitra.entities.Task.bulkCreate([
+     *   { title: 'Task 1', status: 'pending' },
+     *   { title: 'Task 2', status: 'pending' },
+     *   { title: 'Task 3', status: 'pending' },
+     * ]);
+     * console.log(`Created ${tasks.length} tasks`);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Import from external source
+     * const importedData = parseCSV(csvContent);
+     * const records = await mitra.entities.Product.bulkCreate(importedData);
+     * toast.success(`Imported ${records.length} products`);
+     * ```
+     */
+    bulkCreate(data: Partial<T>[]): Promise<T[]>;
+}
+
+/**
+ * Module for database CRUD operations.
+ *
+ * Access any table dynamically: `mitra.entities.TableName.method()`.
+ * Table names are case-sensitive and must match the Data Manager config.
+ *
+ * @example
+ * ```typescript
+ * // Dynamic access
+ * const tasks = await mitra.entities.Task.list('-created_at', 10);
+ * const task = await mitra.entities.Task.create({ title: 'New task' });
+ *
+ * // Typed access
+ * const typed = mitra.entities.getTable<Task>('Task');
+ * const pending = await typed.filter({ status: 'pending' });
+ * ```
+ */
+declare class EntitiesModule {
+    private readonly httpClient;
+    private dataSourceId;
+    private readonly tableProxies;
+    constructor(httpClient: HttpClient, dataSourceId: string);
+    static createProxy(httpClient: HttpClient, dataSourceId: string): EntitiesModule;
+    setDataSourceId(dataSourceId: string): void;
+    getTable<T = Record<string, unknown>>(tableName: string): EntityTable<T>;
+    private createTableAccessor;
+}
+type EntitiesProxy = EntitiesModule & {
+    [tableName: string]: EntityTable;
+};
+
+/** Result of a serverless function execution. */
+interface FunctionExecution {
+    /** Unique execution ID. */
+    id: string;
+    /** ID of the executed function. */
+    functionId: string;
+    /** ID of the function version that was executed. */
+    functionVersionId: string;
+    /** Execution status: PENDING, RUNNING, COMPLETED, or FAILED. */
+    status: string;
+    /** Input data passed to the function. */
+    input: Record<string, unknown>;
+    /** Output data returned by the function. */
+    output: Record<string, unknown> | null;
+    /** Error message if execution failed. */
+    errorMessage: string | null;
+    /** Execution logs. */
+    logs: string | null;
+    /** Duration in milliseconds. */
+    durationMs: number | null;
+    /** When execution started (ISO 8601). */
+    startedAt: string | null;
+    /** When execution finished (ISO 8601). */
+    finishedAt: string | null;
+    /** When the execution record was created (ISO 8601). */
+    createdAt: string;
+}
+
+/**
+ * Module for executing serverless functions.
+ *
+ * @example
+ * ```typescript
+ * const result = await mitra.functions.execute('function-id', { orderId: '123' });
+ * if (result.status === 'COMPLETED') {
+ *   console.log(result.output);
+ * }
+ * ```
+ */
+declare class FunctionsModule {
+    private readonly httpClient;
+    constructor(httpClient: HttpClient);
+    /**
+     * Executes a serverless function by ID.
+     *
+     * Triggers the function's current published version with the provided input.
+     *
+     * @param functionId - UUID of the function to execute.
+     * @param input - Input data to pass to the function.
+     * @returns The execution result with status, output, and metadata.
+     * @throws {MitraApiError} On function not found (404) or unauthorized (401).
+     *
+     * @example
+     * ```typescript
+     * const execution = await mitra.functions.execute('fn-id', { key: 'value' });
+     * console.log(execution.status, execution.output);
+     * ```
+     */
+    execute(functionId: string, input?: Record<string, unknown>): Promise<FunctionExecution>;
+}
+
+/** Input for a proxied HTTP request through an integration. */
+interface ProxyInput {
+    /** HTTP method (GET, POST, PUT, DELETE, etc.). */
+    method: string;
+    /** API endpoint path (appended to the template's baseUrl). */
+    endpoint: string;
+    /** Additional headers. */
+    headers?: Record<string, string>;
+    /** Request body. */
+    body?: unknown;
+    /** Query parameters. */
+    queryParams?: Record<string, string>;
+}
+/** Result of a proxied HTTP request. */
+interface ProxyResult {
+    /** HTTP status code from the external API. */
+    status: number;
+    /** Response headers. */
+    headers: Record<string, string>;
+    /** Response body. */
+    body: unknown;
+    /** Execution time in milliseconds. */
+    durationMs: number;
+    /** Unique execution record ID. */
+    executionId: string;
+}
+
+/**
+ * Module for proxying HTTP requests to external APIs.
+ *
+ * Sends requests through the Mitra server, which handles authentication
+ * and credential injection based on the integration config.
+ *
+ * @example
+ * ```typescript
+ * const result = await mitra.integration.executeResource('resource-id', {
+ *   descricao: 'Notebook',
+ *   limit: 10,
+ * });
+ * console.log(result.body);
+ * ```
+ */
+declare class IntegrationModule {
+    private readonly httpClient;
+    constructor(httpClient: HttpClient);
+    /**
+     * Executes a pre-defined integration resource by ID.
+     *
+     * The resource's endpoint, method, and body are resolved server-side
+     * using the provided parameters. Only declared parameters can be passed.
+     *
+     * @param resourceId - UUID of the integration resource.
+     * @param params - Named parameters declared in the resource's params schema.
+     * @returns Proxy result with status, headers, body, and execution metadata.
+     * @throws {MitraApiError} On resource not found (404) or external API failure.
+     *
+     * @example
+     * ```typescript
+     * const result = await mitra.integration.executeResource('resource-id', {
+     *   descricao: 'Notebook',
+     *   limit: 10,
+     * });
+     * console.log(result.body);
+     * ```
+     */
+    executeResource(resourceId: string, params?: Record<string, unknown>): Promise<ProxyResult>;
+    /**
+     * Executes a proxied HTTP request through an integration config.
+     *
+     * The Mitra server handles authentication and injects credentials automatically.
+     * Note: integrations configured with RESOURCE_ONLY mode will block direct proxy access.
+     *
+     * @param configId - UUID of the integration config.
+     * @param request - The HTTP request to proxy (method, endpoint, body, etc.).
+     * @returns Proxy result with status, headers, body, and execution metadata.
+     * @throws {MitraApiError} On config not found (404) or external API failure.
+     */
+    execute(configId: string, request: ProxyInput): Promise<ProxyResult>;
+}
+
+/** Result of executing a custom query. */
+interface QueryResult {
+    /** Array of row objects returned by the query. */
+    rows: Record<string, unknown>[];
+    /** Number of affected rows (null for SELECT). */
+    affectedRows: number | null;
+}
+
+/**
+ * Module for executing reusable named queries.
+ *
+ * @example
+ * ```typescript
+ * const result = await mitra.queries.execute('query-id', { status: 'active' });
+ * console.log(result.rows);
+ * ```
+ */
+declare class QueriesModule {
+    private readonly httpClient;
+    private dataSourceId;
+    constructor(httpClient: HttpClient);
+    /** @internal Called by client.init() to set the resolved data source. */
+    setDataSourceId(dataSourceId: string): void;
+    /**
+     * Executes a named query.
+     *
+     * @param id - UUID of the custom query.
+     * @param parameters - Named parameters for the prepared statement.
+     * @returns Query result with rows and affected row count.
+     * @throws {MitraApiError} On query not found (404).
+     *
+     * @example
+     * ```typescript
+     * const result = await mitra.queries.execute('query-id', { status: 'active' });
+     * console.log(`Found ${result.rows.length} rows`);
+     * ```
+     */
+    execute(id: string, parameters?: Record<string, unknown>): Promise<QueryResult>;
+}
+
+/**
+ * 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;
+    /**
+     * 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',
+     *   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',
+ * });
+ *
+ * // Initialize (resolves app config automatically)
+ * await mitra.init();
+ *
+ * // Authentication
+ * await mitra.auth.signIn({ email, password });
+ *
+ * // 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.
+     *
+     * Must be called before using `auth.signUp()` or `entities`.
+     * Fetches 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' });
+     * await mitra.init();
+     * ```
+     */
+    init(): Promise<void>;
+    /**
+     * Authentication module for managing user sessions.
+     *
+     * Handles user registration, login, logout, and session persistence.
+     *
+     * @example
+     * ```typescript
+     * await mitra.auth.signIn({ email: 'user@example.com', password: 'password' });
+     * 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;
+    /**
+     * 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 config
+ * (dataSourceId, allowSignup) automatically from the server.
+ *
+ * @param config - Configuration options for the client.
+ * @returns A configured MitraClient instance.
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from 'mitra-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.signIn({ email, password });
+ * const tasks = await mitra.entities.Task.list();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Export as singleton for use throughout your app
+ * // src/api/mitraClient.ts
+ * import { createClient } from 'mitra-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;
+
+export { type EntityListOptions, type EntityTable, type FunctionExecution, MitraApiError, type MitraClient, type MitraClientConfig, type ProxyInput, type ProxyResult, type QueryResult, type SignInCredentials, type SignUpData, type User, createClient };