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

package/dist/index.d.mts

@@ -1,659 +0,0 @@
-import { Transport, TransportRequestOptions, QueryParamValue, EntityTable, ProxyResult } from '@mitralab.io/sdk-core';
-export { EntityListOptions, EntityTable, ProxyResult } from '@mitralab.io/sdk-core';
-
-/**
- * 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 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 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;
-    private readonly appId;
-    private _currentUser;
-    private refreshPromise;
-    private readonly listeners;
-    private readonly storageKey;
-    private readonly publicClient;
-    private readonly authedClient;
-    private readonly currentUserApi;
-    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 getCurrentUser;
-    private clearAuthState;
-    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;
-};
-
-/** 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 returned by the Functions service. */
-    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;
-}
-
-/** Platform SDK 1.x facade over the shared Function contract. */
-declare class FunctionsModule {
-    private readonly core;
-    constructor(httpClient: HttpClient);
-    /**
-     * Executes a Function using the Platform SDK 1.x server-default invocation semantics.
-     * The runtime SDK uses an explicit invocation header instead.
-     */
-    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>;
-}
-
-/** Platform SDK 1.x facade over the shared integration contract. */
-declare class IntegrationModule {
-    private readonly core;
-    constructor(httpClient: HttpClient);
-    executeResource(resourceId: string, params?: Record<string, unknown>): Promise<ProxyResult>;
-    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;
-}
-
-/** Platform SDK 1.x facade over the shared custom query contract. */
-declare class QueriesModule {
-    private dataSourceId;
-    private readonly core;
-    constructor(httpClient: HttpClient);
-    /** Called by `client.init()` to set the app's resolved data source. */
-    setDataSourceId(dataSourceId: string): void;
-    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 FunctionExecution, MitraApiError, type MitraClient, type MitraClientConfig, type ProxyInput, type QueryResult, type SignInCredentials, type SignUpData, type User, createClient };