nexus-platform-sdk 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,760 @@
+/**
+ * Configuration options for creating an HttpClient instance.
+ */
+interface HttpClientConfig {
+    /** Base URL for all HTTP requests (e.g., 'https://api.nexus.io') */
+    baseUrl: string;
+    /** Function that returns the current authentication token, or null if not authenticated */
+    getToken?: () => string | null;
+}
+/**
+ * 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, string | number | boolean | undefined>;
+}
+/**
+ * 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.nexus.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 baseUrl;
+    private tokenGetter;
+    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 {NexusApiError} 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, string | number | boolean | undefined>): 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, string | number | boolean | undefined>): Promise<T>;
+}
+/**
+ * Error thrown when a Nexus 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 nexus.entities.Task.get('invalid-id');
+ * } catch (error) {
+ *   if (error instanceof NexusApiError) {
+ *     console.log(error.status);   // 404
+ *     console.log(error.message);  // "Task not found"
+ *     console.log(error.code);     // "ENTITY_NOT_FOUND"
+ *   }
+ * }
+ * ```
+ */
+declare class NexusApiError 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);
+}
+
+/**
+ * Represents an authenticated user in the Nexus Platform.
+ */
+interface User {
+    /** Unique identifier for the user. */
+    id: string;
+    /** Tenant ID the user belongs to. */
+    tenantId: string;
+    /** User's email address. */
+    email: string;
+    /** User's display name (optional). */
+    name: string | null;
+}
+/**
+ * Credentials required for user sign-in.
+ */
+interface SignInCredentials {
+    /** User's email address. */
+    email: string;
+    /** User's password. */
+    password: string;
+}
+/**
+ * Data required for user registration.
+ */
+interface SignUpData {
+    /** User's email address. */
+    email: string;
+    /** User's password (minimum 6 characters recommended). */
+    password: string;
+    /** User's display name (optional). */
+    name?: string;
+}
+/**
+ * Callback function type for auth state change listeners.
+ */
+interface AuthStateChangeCallback {
+    (user: User | null): void;
+}
+
+/**
+ * @see {@link AuthModuleInterface} in auth.types.ts for full documentation.
+ */
+declare class AuthModule {
+    private tenantId;
+    private iamBaseUrl;
+    private _currentUser;
+    private _accessToken;
+    private listeners;
+    private storageKey;
+    constructor(_httpClient: HttpClient, tenantId: string, iamBaseUrl: string);
+    get currentUser(): User | null;
+    get accessToken(): string | null;
+    get isAuthenticated(): boolean;
+    signIn(credentials: SignInCredentials): Promise<User>;
+    signUp(data: SignUpData): Promise<User>;
+    signOut(redirectUrl?: string): void;
+    logout(redirectUrl?: string): void;
+    me(): Promise<User | null>;
+    refreshUser(): Promise<User | null>;
+    checkAuth(): Promise<boolean>;
+    setToken(token: string, saveToStorage?: boolean): void;
+    redirectToLogin(returnUrl?: string): void;
+    onAuthStateChange(callback: AuthStateChangeCallback): () => void;
+    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 `nexus.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 nexus.entities.Task.list();
+ *
+ * // Typed access
+ * interface Task {
+ *   id: string;
+ *   title: string;
+ *   status: 'pending' | 'done';
+ * }
+ * const tasks = nexus.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 nexus.entities.Task.list();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Get first 10 records sorted by date (newest first)
+     * const tasks = await nexus.entities.Task.list('-created_at', 10);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Get paginated results (page 3, 10 items per page)
+     * const tasks = await nexus.entities.Task.list('-created_at', 10, 20);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Using options object
+     * const tasks = await nexus.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 nexus.entities.Task.filter({ status: 'done' });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Filter by multiple fields (AND logic)
+     * const urgentTasks = await nexus.entities.Task.filter({
+     *   status: 'pending',
+     *   priority: 'high',
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Filter with sorting and pagination
+     * const tasks = await nexus.entities.Task.filter(
+     *   { status: 'pending' },
+     *   '-priority',  // sort by priority descending
+     *   10,           // limit
+     *   0             // skip
+     * );
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Filter with specific fields
+     * const tasks = await nexus.entities.Task.filter(
+     *   { assignee: 'user-123' },
+     *   '-created_at',
+     *   20,
+     *   0,
+     *   ['id', 'title', 'status']
+     * );
+     * ```
+     */
+    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 {NexusApiError} When record is not found (404).
+     *
+     * @example
+     * ```typescript
+     * const task = await nexus.entities.Task.get('task-123');
+     * console.log(task.title);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With error handling
+     * try {
+     *   const task = await nexus.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 {NexusApiError} When validation fails (400).
+     *
+     * @example
+     * ```typescript
+     * const task = await nexus.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 nexus.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 {NexusApiError} When record is not found (404).
+     *
+     * @example
+     * ```typescript
+     * // Update single field
+     * const updated = await nexus.entities.Task.update('task-123', {
+     *   status: 'completed',
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Update multiple fields
+     * const updated = await nexus.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 {NexusApiError} When record is not found (404).
+     *
+     * @example
+     * ```typescript
+     * await nexus.entities.Task.delete('task-123');
+     * console.log('Task deleted');
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With confirmation
+     * if (confirm('Delete this task?')) {
+     *   await nexus.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 nexus.entities.Task.deleteMany({ status: 'done' });
+     * console.log(`Deleted ${result.deleted} tasks`);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Delete by multiple criteria
+     * const result = await nexus.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 nexus.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 nexus.entities.Product.bulkCreate(importedData);
+     * toast.success(`Imported ${records.length} products`);
+     * ```
+     */
+    bulkCreate(data: Partial<T>[]): Promise<T[]>;
+}
+
+/**
+ * @see {@link EntitiesModuleInterface} in entities.types.ts for full documentation.
+ */
+declare class EntitiesModule {
+    private httpClient;
+    private dataSourceId;
+    private tableProxies;
+    constructor(httpClient: HttpClient, dataSourceId: string);
+    getTable<T = Record<string, unknown>>(tableName: string): EntityTable<T>;
+    private createTableAccessor;
+}
+type EntitiesProxy = EntitiesModule & {
+    [tableName: string]: EntityTable;
+};
+
+/**
+ * Result from a function execution.
+ *
+ * @typeParam T - The type of the data returned by the function.
+ * @internal
+ */
+interface FunctionResult<T = unknown> {
+    /** Whether the function executed successfully. */
+    success: boolean;
+    /** The data returned by the function (if successful). */
+    data?: T;
+    /** Execution time in milliseconds. */
+    executionTime?: number;
+}
+/**
+ * Information about an available function.
+ */
+interface FunctionInfo {
+    /** The function name used to invoke it. */
+    name: string;
+    /** Optional description of what the function does. */
+    description?: string;
+}
+
+/**
+ * @see {@link FunctionsModuleInterface} in functions.types.ts for full documentation.
+ */
+declare class FunctionsModule {
+    private httpClient;
+    private appId;
+    private functionsBaseUrl;
+    constructor(httpClient: HttpClient, appId: string, functionsBaseUrl: string);
+    invoke<TInput = unknown, TOutput = unknown>(functionName: string, input?: TInput): Promise<TOutput>;
+    list(): Promise<FunctionInfo[]>;
+}
+
+/**
+ * Configuration options for creating a Nexus client.
+ */
+interface NexusClientConfig {
+    /**
+     * Your application's unique identifier.
+     * Found in the Nexus Code Studio app settings.
+     */
+    appId: string;
+    /**
+     * Your tenant's unique identifier.
+     * Represents your organization in the Nexus Platform.
+     */
+    tenantId: string;
+    /**
+     * The data source ID for your app's database.
+     * Found in the Nexus Data Manager settings.
+     */
+    dataSourceId: string;
+    /**
+     * Base URL for the Nexus API.
+     * Defaults to 'http://localhost:8080' for local development.
+     *
+     * @example
+     * ```typescript
+     * // Local development
+     * apiUrl: 'http://localhost:8080'
+     *
+     * // Production
+     * apiUrl: 'https://api.nexus.io'
+     * ```
+     */
+    apiUrl?: string;
+}
+/**
+ * The Nexus client instance providing access to all SDK modules.
+ *
+ * @example
+ * ```typescript
+ * const nexus = createClient({
+ *   appId: 'your-app-id',
+ *   tenantId: 'your-tenant-id',
+ *   dataSourceId: 'your-datasource-id',
+ * });
+ *
+ * // Authentication
+ * await nexus.auth.signIn({ email, password });
+ *
+ * // Database operations
+ * const tasks = await nexus.entities.Task.list();
+ *
+ * // Serverless functions
+ * await nexus.functions.invoke('sendEmail', { to, subject, body });
+ * ```
+ */
+interface NexusClient {
+    /**
+     * Authentication module for managing user sessions.
+     *
+     * Handles user registration, login, logout, and session persistence.
+     *
+     * @example
+     * ```typescript
+     * await nexus.auth.signIn({ email: 'user@example.com', password: 'password' });
+     * console.log(nexus.auth.currentUser);
+     * ```
+     */
+    auth: AuthModule;
+    /**
+     * Entities module for database CRUD operations.
+     *
+     * Access any table dynamically using `nexus.entities.TableName`.
+     *
+     * @example
+     * ```typescript
+     * const tasks = await nexus.entities.Task.list('-created_at', 10);
+     * const task = await nexus.entities.Task.create({ title: 'New task' });
+     * ```
+     */
+    entities: EntitiesProxy;
+    /**
+     * Functions module for invoking serverless functions.
+     *
+     * @example
+     * ```typescript
+     * const result = await nexus.functions.invoke('processOrder', { orderId });
+     * ```
+     */
+    functions: FunctionsModule;
+    /**
+     * The configuration used to create this client.
+     */
+    config: NexusClientConfig;
+}
+/**
+ * Creates a new Nexus client instance.
+ *
+ * The client provides access to all Nexus Platform features:
+ * - **auth**: User authentication and session management
+ * - **entities**: Database CRUD operations
+ * - **functions**: Serverless function invocation
+ *
+ * @param config - Configuration options for the client.
+ * @returns A configured NexusClient instance.
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from 'nexus-platform-sdk';
+ *
+ * // Create the client
+ * const nexus = createClient({
+ *   appId: import.meta.env.VITE_NEXUS_APP_ID,
+ *   tenantId: import.meta.env.VITE_NEXUS_TENANT_ID,
+ *   dataSourceId: import.meta.env.VITE_NEXUS_DATASOURCE_ID,
+ *   apiUrl: import.meta.env.VITE_NEXUS_API_URL,
+ * });
+ *
+ * // Use the client
+ * await nexus.auth.signIn({ email, password });
+ * const tasks = await nexus.entities.Task.list();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Export as singleton for use throughout your app
+ * // src/api/nexusClient.ts
+ * import { createClient } from 'nexus-platform-sdk';
+ *
+ * export const nexus = createClient({
+ *   appId: process.env.NEXUS_APP_ID,
+ *   tenantId: process.env.NEXUS_TENANT_ID,
+ *   dataSourceId: process.env.NEXUS_DATASOURCE_ID,
+ *   apiUrl: process.env.NEXUS_API_URL,
+ * });
+ * ```
+ */
+declare function createClient(config: NexusClientConfig): NexusClient;
+
+export { type EntityListOptions, type EntityTable, type FunctionInfo, type FunctionResult, NexusApiError, type NexusClient, type NexusClientConfig, type SignInCredentials, type SignUpData, type User, createClient };