@lumerahq/ui 0.5.0

package/dist/lib/api.d.ts

@@ -0,0 +1,307 @@
+/**
+ * PocketBase API client for Lumera custom apps.
+ *
+ * All operations go through the parent bridge for authentication.
+ * This module provides a clean, typed interface for CRUD operations.
+ *
+ * @module api
+ */
+/** Base type for PocketBase records */
+export type PbRecord = Record<string, unknown> & {
+    id?: string;
+    created?: string;
+    updated?: string;
+};
+/** SQL query request */
+export type PbSqlRequest = {
+    /** SQL query string */
+    sql: string;
+    /** Named parameters (use $name in SQL) */
+    params?: Record<string, unknown>;
+    /** Positional arguments (use ? in SQL) */
+    args?: unknown[];
+};
+/** SQL query response */
+export type PbSqlResponse<T> = {
+    columns?: string[];
+    rows?: T[];
+    rowsAffected?: number | null;
+    lastInsertId?: number | null;
+    durationMs: number;
+};
+/** List query options */
+export type PbListOptions = {
+    /** Page number (1-indexed) */
+    page?: number;
+    /** Items per page */
+    perPage?: number;
+    /** Filter expression (PocketBase syntax) */
+    filter?: string;
+    /** Sort expression (e.g., "-created" for descending) */
+    sort?: string;
+    /** Relations to expand */
+    expand?: string;
+};
+/** Paginated list response */
+export type PbListResponse<T> = {
+    page: number;
+    perPage: number;
+    totalItems: number;
+    totalPages: number;
+    items: T[];
+};
+/** Bulk operation result */
+export type PbBulkResult = {
+    succeeded: number;
+    failed: number;
+    errors?: Array<{
+        index: number;
+        error: string;
+    }>;
+};
+/** File upload options */
+export type UploadOptions = {
+    /** Target collection ID */
+    collectionId: string;
+    /** Field name in the collection */
+    fieldName: string;
+    /** Upload timeout in milliseconds (default: 60000 for large files) */
+    timeout?: number;
+};
+/** Presigned upload response */
+export type UploadUrlResponse = {
+    object_key: string;
+    upload_url?: string;
+    download_url?: string;
+};
+/** File descriptor stored in Lumera */
+export type FileDescriptor = {
+    object_key: string;
+    original_name: string;
+    size: number;
+    content_type: string;
+    uploaded_at: string;
+};
+/** Email send request */
+export type EmailSendRequest = {
+    /** Recipient email address(es) */
+    to: string | string[];
+    /** Email subject line */
+    subject: string;
+    /** HTML body content */
+    body_html?: string;
+    /** Plain text body content */
+    body_text?: string;
+    /** CC recipient(s) */
+    cc?: string | string[];
+    /** BCC recipient(s) */
+    bcc?: string | string[];
+    /** Sender email address (uses platform default if not provided) */
+    from_address?: string;
+    /** Sender display name (uses platform default if not provided) */
+    from_name?: string;
+    /** Reply-to address */
+    reply_to?: string;
+    /** Custom tags for tracking/filtering */
+    tags?: Record<string, string>;
+};
+/** Email send result */
+export type EmailSendResult = {
+    /** AWS SES message ID */
+    message_id: string;
+    /** PocketBase log record ID in lm_email_logs */
+    log_id: string;
+};
+/**
+ * Execute a SQL query against PocketBase.
+ *
+ * @param req - SQL query request with query and optional params/args
+ * @returns Query result with rows and metadata
+ *
+ * @example
+ * // Simple query
+ * const result = await pbSql<{ id: string; name: string }>({
+ *   sql: 'SELECT id, name FROM users WHERE active = true'
+ * });
+ * console.log(result.rows);
+ *
+ * @example
+ * // With named parameters
+ * const result = await pbSql<{ count: number }>({
+ *   sql: 'SELECT COUNT(*) as count FROM orders WHERE status = $status',
+ *   params: { status: 'pending' }
+ * });
+ */
+export declare function pbSql<T = PbRecord>(req: PbSqlRequest): Promise<PbSqlResponse<T>>;
+/**
+ * Get a single record by ID.
+ *
+ * @param collection - Collection name or ID
+ * @param id - Record ID
+ * @param expand - Optional relations to expand
+ * @returns The record
+ *
+ * @example
+ * const user = await pbGet<User>('users', 'abc123');
+ */
+export declare function pbGet<T extends PbRecord = PbRecord>(collection: string, id: string, expand?: string): Promise<T>;
+/**
+ * List records with pagination, filtering, and sorting.
+ *
+ * @param collection - Collection name or ID
+ * @param options - List options (page, perPage, filter, sort, expand)
+ * @returns Paginated list of records
+ *
+ * @example
+ * const result = await pbList<User>('users', {
+ *   filter: 'active = true',
+ *   sort: '-created',
+ *   perPage: 50,
+ * });
+ * console.log(result.items, result.totalItems);
+ */
+export declare function pbList<T extends PbRecord = PbRecord>(collection: string, options?: PbListOptions): Promise<PbListResponse<T>>;
+/**
+ * Full-text search across records.
+ *
+ * @param collection - Collection name or ID
+ * @param query - Search query
+ * @param options - Additional list options
+ * @returns Search results
+ *
+ * @example
+ * const results = await pbSearch<Product>('products', 'laptop', { perPage: 10 });
+ */
+export declare function pbSearch<T extends PbRecord = PbRecord>(collection: string, query: string, options?: Omit<PbListOptions, 'filter'>): Promise<PbListResponse<T>>;
+/**
+ * Create a new record.
+ *
+ * @param collection - Collection name or ID
+ * @param data - Record data
+ * @returns The created record
+ *
+ * @example
+ * const user = await pbCreate<User>('users', {
+ *   name: 'John Doe',
+ *   email: 'john@example.com',
+ * });
+ */
+export declare function pbCreate<T extends PbRecord = PbRecord>(collection: string, data: Omit<T, 'id' | 'created' | 'updated'>): Promise<T>;
+/**
+ * Update an existing record.
+ *
+ * @param collection - Collection name or ID
+ * @param id - Record ID
+ * @param data - Fields to update
+ * @returns The updated record
+ *
+ * @example
+ * const user = await pbUpdate<User>('users', 'abc123', { name: 'Jane Doe' });
+ */
+export declare function pbUpdate<T extends PbRecord = PbRecord>(collection: string, id: string, data: Partial<Omit<T, 'id' | 'created' | 'updated'>>): Promise<T>;
+/**
+ * Delete a record.
+ *
+ * @param collection - Collection name or ID
+ * @param id - Record ID
+ *
+ * @example
+ * await pbDelete('users', 'abc123');
+ */
+export declare function pbDelete(collection: string, id: string): Promise<void>;
+export declare function pbBulkUpdate(collection: string, records: Array<{
+    id: string;
+} & Record<string, unknown>>): Promise<PbBulkResult>;
+/**
+ * Delete multiple records in a single request.
+ *
+ * @param collection - Collection name or ID
+ * @param ids - Array of record IDs to delete
+ * @returns Bulk operation result
+ *
+ * @example
+ * const result = await pbBulkDelete('temp_files', ['id1', 'id2', 'id3']);
+ */
+export declare function pbBulkDelete(collection: string, ids: string[]): Promise<PbBulkResult>;
+/**
+ * Upsert a record by external_id (create if not exists, update if exists).
+ *
+ * @param collection - Collection name or ID
+ * @param data - Record data (must include external_id)
+ * @returns The upserted record
+ *
+ * @example
+ * const product = await pbUpsert<Product>('products', {
+ *   external_id: 'SKU-123',
+ *   name: 'Widget',
+ *   price: 9.99,
+ * });
+ */
+export declare function pbUpsert<T extends PbRecord = PbRecord>(collection: string, data: {
+    external_id: string;
+} & Record<string, unknown>): Promise<T>;
+/**
+ * Get a presigned upload URL for file storage.
+ *
+ * @param filename - Original filename
+ * @param contentType - MIME type
+ * @param options - Collection and field to attach the file to
+ * @returns Presigned upload URL and object key
+ *
+ * @example
+ * const { upload_url, object_key } = await getUploadUrl('report.pdf', 'application/pdf', {
+ *   collectionId: 'documents',
+ *   fieldName: 'file',
+ * });
+ */
+export declare function getUploadUrl(filename: string, contentType: string, options: UploadOptions): Promise<UploadUrlResponse>;
+export declare function uploadFile(file: File, options: UploadOptions): Promise<{
+    objectKey: string;
+    descriptor: FileDescriptor;
+}>;
+/**
+ * Get a presigned download URL for a file.
+ *
+ * @param objectKey - The object key from the file descriptor
+ * @returns Presigned download URL
+ *
+ * @example
+ * const url = await getDownloadUrl(record.attachment.object_key);
+ * window.open(url);
+ */
+export declare function getDownloadUrl(objectKey: string): Promise<string>;
+/**
+ * Send an email through the Lumera platform.
+ *
+ * At least one of body_html or body_text must be provided. If only body_html
+ * is provided, a plain text version will be auto-generated.
+ *
+ * @param options - Email send options
+ * @returns Email send result with message_id and log_id
+ *
+ * @example
+ * // Simple email
+ * const result = await sendEmail({
+ *   to: 'user@example.com',
+ *   subject: 'Welcome!',
+ *   body_html: '<h1>Hello!</h1><p>Welcome to our platform.</p>',
+ * });
+ * console.log(result.message_id);
+ *
+ * @example
+ * // Email with multiple recipients and options
+ * const result = await sendEmail({
+ *   to: ['alice@example.com', 'bob@example.com'],
+ *   subject: 'Team Update',
+ *   body_html: '<h1>Update</h1><p>See details below.</p>',
+ *   body_text: 'Update\n\nSee details below.',
+ *   cc: 'manager@example.com',
+ *   tags: { type: 'notification', team: 'engineering' },
+ * });
+ */
+export declare function sendEmail(options: EmailSendRequest): Promise<EmailSendResult>;
+/**
+ * @deprecated Use pbUpdate instead
+ */
+export declare function pbUpdateRecord<T extends PbRecord = PbRecord>(collectionId: string, recordId: string, data: Record<string, unknown>): Promise<T>;
+//# sourceMappingURL=api.d.ts.map

package/dist/lib/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/lib/api.ts"],"names":[],"mappings":"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"}

package/dist/lib/automations.d.ts

@@ -0,0 +1,274 @@
+/**
+ * Automation API client for Lumera custom apps.
+ *
+ * Provides functions for triggering and monitoring automation runs.
+ * All operations go through the parent bridge for authentication.
+ *
+ * @module automations
+ */
+/** Automation run status */
+export type AutomationStatus = 'preparing' | 'queued' | 'running' | 'cancelling' | 'succeeded' | 'failed' | 'cancelled';
+/**
+ * Check if a status is terminal (run is complete).
+ */
+export declare const isTerminalStatus: (status: AutomationStatus) => boolean;
+/**
+ * Check if a status is active (run is in progress).
+ */
+export declare const isActiveStatus: (status: AutomationStatus) => boolean;
+/** Automation definition */
+export type Automation = {
+    id: string;
+    external_id?: string;
+    name?: string;
+    description?: string;
+};
+/** Automation run */
+export type AutomationRun = {
+    id: string;
+    automation_id: string;
+    inputs?: string;
+    status: AutomationStatus;
+    error?: string | null;
+    trigger?: string | null;
+    result?: unknown;
+    metadata?: Record<string, unknown>;
+    external_id?: string | null;
+    created?: string;
+    updated?: string;
+    started_at?: string | null;
+    finished_at?: string | null;
+    artifacts?: AutomationRunFile[];
+};
+/** File attached to an automation run */
+export type AutomationRunFile = {
+    name: string;
+    content_type?: string;
+    size_bytes?: number;
+    created_at?: string;
+    object?: string;
+    type?: string;
+};
+/** Options for creating a run */
+export type CreateRunOptions = {
+    /** Automation ID or external_id (if contains `:`, treated as external_id) */
+    automationId: string;
+    /** Input parameters for the automation */
+    inputs: Record<string, unknown>;
+    /** Optional external ID for idempotency */
+    externalId?: string;
+    /** Trigger source identifier */
+    trigger?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+};
+/** Options for listing runs */
+export type ListRunsOptions = {
+    /** Filter by automation ID */
+    automationId?: string;
+    /** Filter by external ID */
+    externalId?: string;
+    /** Maximum number of results */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+    /** Sort direction */
+    dir?: 'asc' | 'desc';
+};
+/** Options for polling a run */
+export type PollOptions = {
+    /** Polling interval in milliseconds (default: 2000) */
+    intervalMs?: number;
+    /** Timeout in milliseconds (default: 300000 = 5 minutes) */
+    timeoutMs?: number;
+    /** Callback for status updates */
+    onUpdate?: (run: AutomationRun) => void;
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+};
+/**
+ * Clear the automation ID cache.
+ * Call this if automation external_ids have changed.
+ *
+ * @param externalId - Optional specific external_id to clear. If omitted, clears entire cache.
+ *
+ * @example
+ * // Clear specific entry
+ * clearAutomationCache('my_app:process_data');
+ *
+ * // Clear entire cache
+ * clearAutomationCache();
+ */
+export declare function clearAutomationCache(externalId?: string): void;
+/**
+ * Get automation ID by external_id.
+ * Results are cached to avoid repeated lookups.
+ *
+ * @param externalId - The external_id of the automation
+ * @returns The internal automation ID
+ *
+ * @example
+ * const id = await getAutomationByExternalId('my_app:process_data');
+ */
+export declare function getAutomationByExternalId(externalId: string): Promise<string>;
+/**
+ * Create and start a new automation run.
+ *
+ * @param options - Run creation options
+ * @returns The created run
+ *
+ * @example
+ * const run = await createRun({
+ *   automationId: 'my_app:process_data',
+ *   inputs: { file_id: 'abc123' },
+ * });
+ * console.log(`Started run: ${run.id}`);
+ */
+export declare function createRun(options: CreateRunOptions): Promise<AutomationRun>;
+/**
+ * Get a run by ID.
+ *
+ * @param runId - The run ID
+ * @returns The run
+ *
+ * @example
+ * const run = await getRun('run_abc123');
+ * console.log(`Status: ${run.status}`);
+ */
+export declare function getRun(runId: string): Promise<AutomationRun>;
+/**
+ * List runs with optional filters.
+ *
+ * @param options - Filter and pagination options
+ * @returns Array of runs
+ *
+ * @example
+ * const runs = await listRuns({
+ *   automationId: 'my_app:process_data',
+ *   limit: 10,
+ * });
+ */
+export declare function listRuns(options?: ListRunsOptions): Promise<AutomationRun[]>;
+/**
+ * Cancel a running automation.
+ *
+ * @param runId - The run ID to cancel
+ * @returns The updated run
+ *
+ * @example
+ * const run = await cancelRun('run_abc123');
+ * console.log(`Status: ${run.status}`); // 'cancelling' or 'cancelled'
+ */
+export declare function cancelRun(runId: string): Promise<AutomationRun>;
+/**
+ * Poll a run until it reaches a terminal state.
+ *
+ * @param runId - The run ID to poll
+ * @param options - Polling options
+ * @returns The final run state
+ * @throws {Error} If polling times out
+ *
+ * @example
+ * // Simple polling
+ * const run = await pollRun('run_abc123');
+ * console.log(`Completed with status: ${run.status}`);
+ *
+ * @example
+ * // With progress updates and cancellation
+ * const controller = new AbortController();
+ *
+ * const run = await pollRun('run_abc123', {
+ *   intervalMs: 1000,
+ *   timeoutMs: 60000,
+ *   signal: controller.signal,
+ *   onUpdate: (run) => console.log(`Status: ${run.status}`),
+ * });
+ */
+export declare function pollRun(runId: string, options?: PollOptions): Promise<AutomationRun>;
+/**
+ * Ensure a run exists, reusing an active or succeeded run if one exists.
+ * This provides idempotency for automation runs.
+ *
+ * @param options - Run creation options (externalId is required)
+ * @returns An existing active/succeeded run, or a newly created run
+ *
+ * @example
+ * // Idempotent run - safe to call multiple times
+ * const run = await ensureRun({
+ *   automationId: 'my_app:process_data',
+ *   inputs: { batch_id: 'batch_123' },
+ *   externalId: 'batch_123_processing',
+ * });
+ */
+export declare function ensureRun(options: CreateRunOptions & {
+    externalId: string;
+}): Promise<AutomationRun>;
+/**
+ * List files attached to a run.
+ *
+ * @param runId - The run ID
+ * @returns Array of file metadata
+ *
+ * @example
+ * const files = await getRunFiles('run_abc123');
+ * for (const file of files) {
+ *   console.log(`${file.name} (${file.size_bytes} bytes)`);
+ * }
+ */
+export declare function getRunFiles(runId: string): Promise<AutomationRunFile[]>;
+/**
+ * Get a download URL for a run file.
+ *
+ * @param runId - The run ID
+ * @param filename - The file name
+ * @returns Presigned download URL
+ *
+ * @example
+ * const url = await getRunFileUrl('run_abc123', 'output.csv');
+ * window.open(url);
+ */
+export declare function getRunFileUrl(runId: string, filename: string): Promise<string>;
+/** Status helper functions and constants */
+export declare const automationStatuses: {
+    readonly TERMINAL_STATUSES: AutomationStatus[];
+    readonly ACTIVE_STATUSES: AutomationStatus[];
+    readonly isTerminal: (status: AutomationStatus) => boolean;
+    readonly isActive: (status: AutomationStatus) => boolean;
+};
+/** Options with agentId for backwards compatibility */
+export type LegacyCreateRunOptions = {
+    agentId: string;
+    inputs: Record<string, unknown>;
+    externalId?: string;
+    trigger?: string;
+    metadata?: Record<string, unknown>;
+};
+/** @deprecated Use createRun instead */
+export declare function createAutomationRun(options: LegacyCreateRunOptions): Promise<AutomationRun>;
+/** @deprecated Use getRun instead */
+export declare const getAutomationRun: typeof getRun;
+/** @deprecated Use cancelRun instead */
+export declare const cancelAutomationRun: typeof cancelRun;
+/** @deprecated Use ensureRun instead */
+export declare function ensureAutomationRun(options: LegacyCreateRunOptions & {
+    externalId: string;
+}): Promise<AutomationRun>;
+/** @deprecated Use pollRun instead */
+export declare const pollAutomationRun: typeof pollRun;
+/** @deprecated Use getRunFiles instead */
+export declare const listAutomationRunFiles: typeof getRunFiles;
+/** @deprecated Use getRunFileUrl instead */
+export declare const getAutomationRunFileDownloadUrl: typeof getRunFileUrl;
+/** @deprecated Use listRuns with automationId filter instead */
+export declare function listRunsByAgent(params: {
+    agentId: string;
+    limit?: number;
+    offset?: number;
+}): Promise<AutomationRun[]>;
+/** @deprecated Use listRuns with externalId filter instead */
+export declare function listRunsByExternalId(params: {
+    externalId: string;
+    agentId?: string;
+    limit?: number;
+}): Promise<AutomationRun[]>;
+//# sourceMappingURL=automations.d.ts.map

package/dist/lib/automations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"automations.d.ts","sourceRoot":"","sources":["../../src/lib/automations.ts"],"names":[],"mappings":"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"}