@slflows/sdk 0.0.3 → 0.0.5

package/dist/v1/index.d.ts

@@ -1,15 +1,91 @@
+/**
+ * Main schema interface for defining a Flows app.
+ *
+ * An app consists of blocks (entities) that can process events, manage state,
+ * expose HTTP endpoints, and handle scheduled tasks. Apps are the fundamental
+ * unit of deployment in Flows.
+ *
+ * @example
+ * ```typescript
+ * export default defineApp({
+ *   name: "Data Processor",
+ *   blocks: {
+ *     processor: {
+ *       name: "Process Data",
+ *       description: "Transforms incoming data",
+ *       inputs: {
+ *         data: {
+ *           name: "Input Data",
+ *           onEvent: async (input) => {
+ *             // Process the event
+ *             await events.emit(processedData);
+ *           }
+ *         }
+ *       },
+ *       outputs: {
+ *         processed: {
+ *           name: "Processed Data",
+ *           default: true
+ *         }
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
+ */
 interface AppSchema {
+    /** Display name for the app */
     name?: string;
+    /**
+     * Instructions shown to users when installing the app.
+     * Supports Markdown formatting.
+     */
     installationInstructions?: string;
+    /**
+     * Configuration fields for the app. These are set during installation
+     * and available to all blocks within the app.
+     */
     config?: Record<string, AppConfigField>;
+    /**
+     * Signals exported by the app.
+     * These are available to all blocks within the app.
+     */
+    signals?: Record<string, AppSignal>;
+    /**
+     * Lifecycle hook called when the app needs to synchronize its state.
+     * Use this to provision resources, validate configuration, or perform setup.
+     */
     onSync?: (input: AppInput) => Promise<AppLifecycleCallbackOutput>;
+    /**
+     * Lifecycle hook called when the app is being drained (shut down).
+     * Use this to clean up resources, save state, or perform teardown.
+     */
     onDrain?: (input: AppInput) => Promise<AppLifecycleCallbackOutput>;
+    /** Custom status description shown when the app is in draft mode */
     draftCustomStatusDescription?: string;
+    /**
+     * Handler for internal messages sent to the app from blocks.
+     * Used for app-level coordination and communication.
+     */
     onInternalMessage?: (input: AppOnInternalMessageInput) => Promise<void>;
+    /**
+     * Map of block definitions. Each block becomes an entity that can be
+     * placed on the flow canvas. Key is the block type ID.
+     */
     blocks: Record<string, AppBlock>;
+    /** HTTP server configuration for app-level endpoints */
     http?: AppHTTPComponent;
+    /** UI component configuration for custom app interfaces */
     ui?: AppUIComponent;
+    /**
+     * Declarative schedules that trigger at app level.
+     * Use for periodic maintenance, data synchronization, etc.
+     */
     schedules?: Record<string, AppSchedule>;
+    /**
+     * Handler for imperative timers set by the app.
+     * Called when a timer created with timers.set() expires.
+     */
     onTimer?: (input: AppOnTimerInput) => Promise<void>;
 }
 interface AppUIComponent {
@@ -38,6 +114,12 @@ interface AppConfigField {
     fixed?: boolean;
     required: boolean;
     default?: unknown;
+    sensitive?: boolean;
+}
+interface AppSignal {
+    name: string;
+    description: string;
+    sensitive?: boolean;
 }
 interface AppHTTPComponent {
     onRequest: (input: AppOnHTTPRequestInput) => Promise<void>;
@@ -86,6 +168,7 @@ interface AppBlockConfigField {
     required: boolean;
     default?: unknown;
     fieldKey?: string;
+    sensitive?: boolean;
 }
 interface AppBlockComponentInput {
     name?: string;
@@ -117,6 +200,7 @@ interface AppBlockUIComponent {
 interface AppBlockSignal {
     name: string;
     description: string;
+    sensitive?: boolean;
 }
 interface AppBlockSchedule {
     description?: string;
@@ -130,27 +214,61 @@ interface EntityView {
     type: EntityViewType;
 }
 type EntityViewType = "default" | "fullScreen" | "regular";
+/**
+ * Input context provided to app-level handlers.
+ * Contains app configuration and runtime information.
+ */
 interface AppInput {
+    /** App installation context and configuration */
     app: AppContext;
 }
+/**
+ * App runtime context containing configuration and endpoints.
+ * Available in all app-level handlers (onSync, onDrain, onInternalMessage, etc.).
+ */
 interface AppContext {
+    /** App configuration values set during installation */
     config: Record<string, any>;
-    installationStatus: "new" | "active" | "failed";
+    /** Current status of the app installation */
+    status: "draft" | "in_progress" | "ready" | "failed" | "draining" | "draining_failed" | "drained";
+    /** HTTP endpoint information for this app */
     http: AppHTTPEndpoint;
+    /** URL for managing this app installation */
     installationUrl: string;
+    /** Signals exported by this app */
+    signals: Record<string, any>;
 }
+/**
+ * HTTP endpoint information for app-level HTTP handlers.
+ */
 interface AppHTTPEndpoint {
+    /** Base URL for this app's HTTP endpoints */
     url: string;
 }
+/**
+ * Input context provided to block-level handlers.
+ * Extends AppInput with block-specific context.
+ */
 interface EntityInput extends AppInput {
+    /** Block (entity) instance context and configuration */
     block: EntityContext;
 }
+/**
+ * Block (entity) runtime context containing configuration and state.
+ * Available in all block-level handlers (onEvent, onSync, onDrain, etc.).
+ */
 interface EntityContext {
+    /** Unique identifier for this block instance */
     id: string;
+    /** Display name of this block instance */
     name: string;
+    /** Description of this block instance */
     description: string;
+    /** Block configuration values set in the flow */
     config: Record<string, any>;
+    /** Lifecycle state information (null if block has no lifecycle) */
     lifecycle: EntityLifecycleComponent | null;
+    /** HTTP endpoint information (null if block has no HTTP handler) */
     http: EntityHTTPEndpoint | null;
 }
 interface EntityLifecycleComponent {
@@ -161,14 +279,31 @@ type EntityLifecycleStatus = "draft" | "in_progress" | "ready" | "drifted" | "fa
 interface EntityHTTPEndpoint {
     url: string;
 }
+/**
+ * Input context provided to event handlers (onEvent).
+ * Extends EntityInput with event-specific information.
+ */
 interface EventInput extends EntityInput {
+    /** Event data and metadata */
     event: EventContext;
 }
+/**
+ * Event context containing the event data and metadata.
+ * Available in all onEvent handlers when processing incoming events.
+ */
 interface EventContext {
+    /** Unique identifier for this event */
     id: string;
+    /** Configuration values for the specific input that received this event */
     inputConfig: Record<string, any>;
+    /**
+     * Echo information for request-response patterns.
+     * Present when this event was emitted with echo: true.
+     */
     echo?: {
+        /** The event body that was echoed */
         body: any;
+        /** The output key where the original event was emitted */
         outputKey: string;
     };
 }
@@ -259,68 +394,209 @@ interface UIRequest {
     payload?: any;
 }
 
+/**
+ * Key-value pair for storage operations.
+ * Supports TTL (time-to-live) and optimistic locking for safe concurrent access.
+ */
 interface KVPair {
+    /** The storage key */
     key: string;
+    /**
+     * The stored value. May be undefined (key doesn't exist),
+     * null (explicitly set to null), or any other value.
+     */
     value?: any;
+    /** Unix timestamp of when this key was last updated */
     updatedAt?: number;
+    /** Time-to-live in seconds. If set, key will expire after this duration */
     ttl?: number;
+    /** Optional lock information for atomic operations */
     lock?: {
+        /** Unique lock identifier */
         id: string;
+        /** Lock timeout in seconds */
         timeout?: number;
     };
 }
+/**
+ * Input parameters for listing key-value pairs with optional pagination.
+ * Used with kv.app.list() and kv.block.list() to retrieve multiple keys.
+ */
 interface KVListInput {
+    /** Prefix to filter keys (e.g., "user:" to get all user-related keys) */
     keyPrefix: string;
+    /** Starting key for pagination (from previous nextStartingKey) */
     startingKey?: string;
 }
+/**
+ * Output from key-value list operations with pagination support.
+ * Contains the retrieved key-value pairs and pagination information.
+ */
 interface KVListOutput {
+    /** Array of key-value pairs matching the prefix */
     pairs: Array<KVPair>;
+    /** Next starting key for pagination (undefined if no more results) */
     nextStartingKey?: string;
 }
+/**
+ * Input parameters for listing blocks within the same app installation.
+ * Used to discover other blocks for coordination and messaging.
+ */
 interface ListBlocksInput {
+    /** Filter by specific block type IDs (omit to list all blocks) */
     typeIds?: string[];
 }
+/**
+ * Output from blocks.list() operation containing discovered blocks.
+ * Provides information about other blocks in the same app installation.
+ */
 interface ListBlocksOutput {
+    /** Array of blocks found in the app installation */
     blocks: {
+        /** Unique identifier of the block instance */
         id: string;
+        /** Type ID of the block (from the app's block definitions) */
         typeId: string;
+        /** Current configuration values of the block */
         config: Record<string, any>;
     }[];
 }
-declare const setAppInstallationStatus: (status: "active" | "failed") => Promise<void>;
+/**
+ * Options for emitting events to downstream blocks.
+ */
 interface EmitOptions {
+    /** The output key to emit on (defaults to default output) */
     outputKey?: string;
+    /** Parent event ID for lineage tracking */
     parentEventId?: string;
+    /** Additional parent event IDs for complex lineage */
     secondaryParentEventIds?: string[];
+    /**
+     * Whether to echo this event back for request-response patterns.
+     *
+     * When enabled, if this block later receives an event that has one of its own
+     * events in its ancestry, the original event will be automatically made available
+     * in input.event.echo. This eliminates the need for manual tracking of
+     * request-response relationships.
+     *
+     * The echo contains:
+     * - body: The original event payload
+     * - outputKey: The output ID where the original event was emitted
+     *
+     * Particularly useful for:
+     * - HTTP request/response patterns
+     * - Multi-step workflows where responses need to be matched to original requests
+     * - Any scenario where maintaining context across multiple events is important
+     */
     echo?: boolean;
+    /** Pending event ID to complete when emitting */
     complete?: string;
 }
+/**
+ * Options for creating a pending event.
+ */
 interface CreatePendingEventOptions {
+    /** Optional predicted event payload */
     event?: Record<string, any>;
+    /** Which output this will emit on (optional) */
     outputId?: string;
+    /** Parent event (auto-populated in handlers) */
     parentEventId?: string;
+    /** Additional parent event IDs for complex lineage */
     secondaryParentEventIds?: string[];
+    /** User-readable status message */
     statusDescription: string | null;
 }
+/**
+ * Options for updating an existing pending event.
+ * Used with updatePendingEvent() to modify pending event data or status.
+ */
 interface UpdatePendingEventOptions {
+    /** Updated event data (replaces previous event data) */
     event?: Record<string, any>;
+    /** Updated output ID to emit on when completed */
     outputId?: string;
+    /** Updated parent event ID for lineage tracking */
     parentEventId?: string;
+    /** Updated additional parent event IDs */
     secondaryParentEventIds?: string[];
+    /** Updated status description shown while pending */
     statusDescription?: string | null;
 }
+/**
+ * Options for creating user prompts in approval workflows.
+ * Used with createPrompt() to request manual user input or approval.
+ */
 interface PromptOptions {
+    /** Redirect configuration for the approval interface */
     redirect: {
+        /** URL where users will be redirected for approval */
         url: string;
+        /** HTTP method for the approval request */
         method: "GET" | "POST";
+        /** Form fields to include with POST requests */
         formFields?: Record<string, string>;
     };
 }
+/**
+ * Metadata about the current function invocation.
+ * Provides context for logging, debugging, and correlation.
+ */
 interface InvocationMetadata {
+    /** Unique identifier for this invocation */
     invocationId: string;
+    /** Unix timestamp when the invocation started */
     timestamp: number;
 }
+/**
+ * Gets metadata about the current function invocation.
+ *
+ * Provides information about when and how the current handler was invoked.
+ * Useful for logging, debugging, and correlation across distributed operations.
+ *
+ * @returns Promise resolving to invocation metadata
+ *
+ * @example
+ * ```typescript
+ * const metadata = await getInvocationMetadata();
+ * console.log(`Invocation ${metadata.invocationId} started at ${new Date(metadata.timestamp)}`);
+ *
+ * // Use in logging for correlation
+ * console.log(`[${metadata.invocationId}] Processing event:`, input.event.body);
+ * ```
+ */
 declare const getInvocationMetadata: () => Promise<InvocationMetadata>;
+/**
+ * Events service for emitting and managing events within flows.
+ *
+ * Events are the primary way blocks communicate with each other.
+ * The events service provides both immediate emission and pending event management
+ * for handling long-running operations.
+ *
+ * @example
+ * ```typescript
+ * // Simple event emission
+ * await events.emit({ message: "Hello World" });
+ *
+ * // Emit to specific output
+ * await events.emit(data, { outputId: "success" });
+ *
+ * // Create pending event for long operation
+ * const pendingId = await events.createPending({
+ *   statusDescription: "Processing data...",
+ *   event: { progress: 0 }
+ * });
+ *
+ * // Update progress
+ * await events.updatePending(pendingId, {
+ *   event: { progress: 50 },
+ *   statusDescription: "Half complete..."
+ * });
+ *
+ * // Complete the operation
+ * await events.completePending(pendingId);
+ * ```
+ */
 declare const events: {
     emit: (event: any, options?: EmitOptions) => Promise<void>;
     createPending: (options: CreatePendingEventOptions) => Promise<string>;
@@ -328,7 +604,112 @@ declare const events: {
     cancelPending: (pendingEventId: string, reason: string) => Promise<void>;
     completePending: (pendingEventId: string) => Promise<void>;
 };
+/**
+ * Key-Value storage service for persisting data at block and app level.
+ *
+ * KV storage provides persistent, scoped storage with TTL support and optimistic locking.
+ * Block-level storage is isolated per block instance, while app-level storage is shared
+ * across all blocks in the app installation.
+ *
+ * ## Locking Mechanism
+ *
+ * The KV service includes a robust locking system for coordinating concurrent access:
+ *
+ * - **Lock Acquisition**: Use unique lock IDs to acquire exclusive access to keys
+ * - **Timeout Management**: Locks automatically expire after specified duration
+ * - **Lock Ownership**: Only the exact lock ID can modify or release the lock
+ * - **Graceful Failures**: Lock conflicts return `false` instead of throwing errors
+ * - **Automatic Cleanup**: Expired locks are automatically cleared
+ * - **Database-Level Safety**: Uses PostgreSQL row-level locks for atomicity
+ *
+ * ## Lock Behavior Details
+ *
+ * - **Conflict Resolution**: If a key is already locked by a different lock ID,
+ *   operations return `success: false` rather than throwing errors
+ * - **Lock Expiration**: Locks with timeouts are automatically considered expired
+ *   when `lock_timeout < NOW()`, allowing new acquisitions
+ * - **Lock Renewal**: Extend lock duration using `renewLock()` with the same lock ID
+ * - **Permanent Locks**: Omit timeout for locks that persist until explicitly released
+ *
+ * @example
+ * ```typescript
+ * // Block-level storage (scoped to this block)
+ * await kv.block.set({
+ *   key: "counter",
+ *   value: 42,
+ *   ttl: 3600 // 1 hour TTL
+ * });
+ * const counter = await kv.block.get("counter");
+ *
+ * // App-level storage (shared across all blocks)
+ * await kv.app.set({
+ *   key: "shared-config",
+ *   value: { apiKey: "secret" }
+ * });
+ *
+ * // Safe concurrent access with locking
+ * import { randomUUID } from "crypto";
+ *
+ * const lockId = randomUUID();
+ * const acquired = await kv.app.set({
+ *   key: "shared-counter",
+ *   value: "processing",
+ *   lock: { id: lockId, timeout: 30 } // 30 second timeout
+ * });
+ *
+ * if (acquired) {
+ *   try {
+ *     // Perform atomic read-modify-write operation
+ *     const current = await kv.app.get("shared-counter");
+ *
+ *     // Simulate some processing time
+ *     await new Promise(resolve => setTimeout(resolve, 1000));
+ *
+ *     // Update with same lock ID
+ *     const updated = await kv.app.set({
+ *       key: "shared-counter",
+ *       value: current.value + 1,
+ *       lock: { id: lockId } // Same lock ID required for updates
+ *     });
+ *
+ *     if (!updated) {
+ *       throw new Error("Lock was lost during operation");
+ *     }
+ *   } finally {
+ *     // Always release the lock to avoid blocking other operations
+ *     await kv.app.releaseLock({ key: "shared-counter", lockId });
+ *   }
+ * } else {
+ *   // Lock acquisition failed - another process has the lock
+ *   console.log("Resource is currently locked, will retry later");
+ *
+ *   // Implement retry logic with exponential backoff
+ *   setTimeout(() => { yourRetryLogic }, 1000);
+ * }
+ *
+ * // Renew lock for long-running operations
+ * const lockId2 = randomUUID();
+ * await kv.app.set({
+ *   key: "long-process",
+ *   value: "starting",
+ *   lock: { id: lockId2, timeout: 30 }
+ * });
+ *
+ * // Extend lock before it expires
+ * const renewed = await kv.app.renewLock({
+ *   key: "long-process",
+ *   lock: { id: lockId2, timeout: 60 } // Extend for 60 more seconds
+ * });
+ *
+ * if (renewed) {
+ *   console.log("Lock extended successfully");
+ * } else {
+ *   console.log("Lock renewal failed - may have expired or been released");
+ * }
+ * ```
+ */
 declare const kv: {
+    /** Block-scoped key-value storage (isolated per block instance) */
     block: {
         getMany: (keys: string[]) => Promise<KVPair[]>;
         get: (key: string) => Promise<KVPair>;
@@ -348,6 +729,7 @@ declare const kv: {
             };
         }) => Promise<boolean>;
     };
+    /** App-scoped key-value storage (shared across all blocks in the app) */
     app: {
         getMany: (keys: string[]) => Promise<KVPair[]>;
         get: (key: string) => Promise<KVPair>;
@@ -368,6 +750,27 @@ declare const kv: {
         }) => Promise<boolean>;
     };
 };
+/**
+ * Messaging service for internal communication between app components.
+ *
+ * Enables blocks to send messages to other blocks or to the app level,
+ * bypassing the normal event flow. Useful for coordination, service discovery,
+ * and notifications.
+ *
+ * @example
+ * ```typescript
+ * // Send message to specific blocks
+ * await messaging.sendToBlocks({
+ *   body: { action: "refresh", data: newConfig },
+ *   blockIds: ["block-1", "block-2"]
+ * });
+ *
+ * // Send message to app level
+ * await messaging.sendToApp({
+ *   body: { type: "status-update", status: "ready" }
+ * });
+ * ```
+ */
 declare const messaging: {
     sendToBlocks: (input: {
         body: unknown;
@@ -377,9 +780,36 @@ declare const messaging: {
         body: unknown;
     }) => Promise<void>;
 };
+/**
+ * Blocks service for querying other blocks within the same app installation.
+ *
+ * @example
+ * ```typescript
+ * // List all blocks
+ * const allBlocks = await blocks.list();
+ *
+ * // List specific block types
+ * const processors = await blocks.list({
+ *   typeIds: ["dataProcessor", "validator"]
+ * });
+ * ```
+ */
 declare const blocks: {
     list: (input?: ListBlocksInput) => Promise<ListBlocksOutput>;
 };
+/**
+ * HTTP service for responding to HTTP requests.
+ *
+ * @example
+ * ```typescript
+ * // In an HTTP handler
+ * await http.respond(input.request.requestId, {
+ *   statusCode: 200,
+ *   headers: { "Content-Type": "application/json" },
+ *   body: { success: true, data: result }
+ * });
+ * ```
+ */
 declare const http: {
     respond: (requestId: string, response: {
         statusCode?: number;
@@ -387,6 +817,190 @@ declare const http: {
         body?: unknown;
     }) => Promise<void>;
 };
+/**
+ * Lifecycle service for managing block state, resource provisioning, and user prompts.
+ *
+ * The lifecycle service enables blocks to manage their state in a controlled, observable way.
+ * It provides mechanisms for blocks to reconcile their desired state with actual state,
+ * report status, and share computed values with other blocks through signals.
+ *
+ * ## Core Concepts
+ *
+ * - **State Management**: Track and update block status through defined lifecycle phases
+ * - **Resource Provisioning**: Create, update, and cleanup external resources (cloud, APIs, etc.)
+ * - **Signal System**: Share computed values between blocks for reactive dependencies
+ * - **Status Reporting**: Provide meaningful status descriptions for monitoring and debugging
+ * - **Approval Workflows**: Implement manual approval steps using prompts and proceed operations
+ *
+ * ## Lifecycle States
+ *
+ * - `draft`: Initial state, block configured but hasn't processed state yet
+ * - `in_progress`: Block currently computing or updating its state
+ * - `ready`: All calculations/operations complete, block ready for use
+ * - `failed`: Block failed to compute, update, or maintain its state
+ * - `draining`: Block currently cleaning up resources or state
+ * - `draining_failed`: Cleanup operations failed
+ * - `drained`: All cleanup successfully completed
+ *
+ * ## Implementation Pattern
+ *
+ * Blocks with lifecycle implement `onSync` and `onDrain` handlers:
+ * - **onSync**: Reconcile desired state, provision resources, update signals
+ * - **onDrain**: Clean up resources when block is removed or app is deleted
+ * - **signals**: Export computed values for other blocks to reference
+ *
+ * ## Signal Dependencies
+ *
+ * Signals create reactive dependencies between blocks. When a block updates its signals,
+ * dependent blocks automatically trigger their sync operations to adapt to changes.
+ * This enables building complex reactive systems where changes cascade automatically.
+ *
+ * @example
+ * ```typescript
+ * // Complete lifecycle example with resource management
+ * export const cloudResourceBlock: AppBlock = {
+ *   name: "Cloud Storage Bucket",
+ *   description: "Manages a cloud storage bucket with lifecycle",
+ *
+ *   config: {
+ *     bucketName: {
+ *       name: "Bucket Name",
+ *       type: "string",
+ *       required: true
+ *     },
+ *     region: {
+ *       name: "Region",
+ *       type: "string",
+ *       required: true,
+ *       default: "us-west-2"
+ *     }
+ *   },
+ *
+ *   // Values shared with other blocks
+ *   signals: {
+ *     bucketId: {
+ *       name: "Bucket ID",
+ *       description: "The unique identifier of the created bucket"
+ *     },
+ *     bucketUrl: {
+ *       name: "Bucket URL",
+ *       description: "The access URL for the bucket"
+ *     }
+ *   },
+ *
+ *   // Provision resources and maintain state
+ *   onSync: async (input) => {
+ *     const config = input.block.config;
+ *
+ *     // Check if bucket already exists
+ *     const existingBucket = await kv.block.get("bucketId");
+ *
+ *     if (!existingBucket?.value) {
+ *       // Create new bucket
+ *       const bucketId = await cloudApi.createBucket({
+ *         name: config.bucketName,
+ *         region: config.region
+ *       });
+ *
+ *       await kv.block.set({ key: "bucketId", value: bucketId });
+ *
+ *       return {
+ *         newStatus: "in_progress",
+ *         customStatusDescription: "Bucket creation in progress",
+ *         nextScheduleDelay: 30 // Check again in 30 seconds
+ *       };
+ *     }
+ *
+ *     // Check bucket status
+ *     const bucketStatus = await cloudApi.getBucketStatus(existingBucket.value);
+ *
+ *     if (bucketStatus === "ready") {
+ *       const bucketDetails = await cloudApi.getBucketDetails(existingBucket.value);
+ *
+ *       return {
+ *         newStatus: "ready",
+ *         signalUpdates: {
+ *           bucketId: existingBucket.value,
+ *           bucketUrl: bucketDetails.url
+ *         }
+ *       };
+ *     }
+ *
+ *     return {
+ *       newStatus: "in_progress",
+ *       customStatusDescription: "Waiting for bucket to be ready",
+ *       nextScheduleDelay: 30
+ *     };
+ *   },
+ *
+ *   // Clean up resources when block is removed
+ *   onDrain: async (input) => {
+ *     const bucketId = await kv.block.get("bucketId");
+ *
+ *     if (bucketId?.value) {
+ *       await cloudApi.deleteBucket(bucketId.value);
+ *       await kv.block.delete(["bucketId"]);
+ *     }
+ *
+ *     return {
+ *       newStatus: "drained",
+ *       signalUpdates: {
+ *         bucketId: null,
+ *         bucketUrl: null
+ *       }
+ *     };
+ *   },
+ *
+ *   // Trigger sync when configuration changes
+ *   inputs: {
+ *     configChange: {
+ *       name: "Configuration Change",
+ *       onEvent: async (input) => {
+ *         // Configuration updated, trigger sync
+ *         await lifecycle.sync();
+ *       }
+ *     }
+ *   }
+ * };
+ *
+ * // Approval workflow example
+ * export const approvalBlock: AppBlock = {
+ *   name: "Production Deployment Approval",
+ *
+ *   http: {
+ *     onRequest: async (input) => {
+ *       if (input.request.path === "/approve") {
+ *         // Manual approval received
+ *         await lifecycle.proceed();
+ *
+ *         await http.respond(input.request.requestId, {
+ *           statusCode: 200,
+ *           body: { message: "Deployment approved" }
+ *         });
+ *       }
+ *     }
+ *   },
+ *
+ *   onSync: async (input) => {
+ *     // Create approval prompt if needed
+ *     const promptId = await lifecycle.prompt.create(
+ *       "Please approve production deployment",
+ *       {
+ *         redirect: {
+ *           url: `${input.block.http.url}/approve`,
+ *           method: "POST"
+ *         }
+ *       }
+ *     );
+ *
+ *     return {
+ *       newStatus: "in_progress",
+ *       customStatusDescription: "Waiting for manual approval"
+ *     };
+ *   }
+ * };
+ * ```
+ */
 declare const lifecycle: {
     sync: () => Promise<void>;
     proceed: () => Promise<void>;
@@ -395,6 +1009,21 @@ declare const lifecycle: {
         delete: (promptId: string) => Promise<void>;
     };
 };
+/**
+ * Timers service for scheduling delayed execution.
+ *
+ * @example
+ * ```typescript
+ * // Set a timer for 30 seconds
+ * const timerId = await timers.set(30, {
+ *   inputPayload: { action: "retry" },
+ *   description: "Retry failed operation"
+ * });
+ *
+ * // Cancel the timer
+ * await timers.unset(timerId);
+ * ```
+ */
 declare const timers: {
     set: (delaySeconds: number, options: {
         inputPayload?: unknown;
@@ -404,6 +1033,23 @@ declare const timers: {
     }) => Promise<string>;
     unset: (id: string) => Promise<void>;
 };
+/**
+ * UI service for managing custom block widgets.
+ *
+ * @example
+ * ```typescript
+ * // Set widget elements
+ * await ui.widget.set({
+ *   elements: [
+ *     { type: "text", content: "Status: Active" },
+ *     { type: "button", label: "Refresh", action: "refresh" }
+ *   ]
+ * });
+ *
+ * // Get current widget
+ * const elements = await ui.widget.get();
+ * ```
+ */
 declare const ui: {
     widget: {
         set: (options: {
@@ -413,6 +1059,50 @@ declare const ui: {
         get: (blockId?: any) => Promise<any[]>;
     };
 };
+/**
+ * Define a Flows app with proper TypeScript typing and validation.
+ *
+ * This function provides type safety and IDE support while developing apps.
+ * It should be the default export of your app module.
+ *
+ * @param app - The app schema defining blocks, configuration, and behaviors
+ * @returns The same app schema for runtime use
+ *
+ * @example
+ * ```typescript
+ * export default defineApp({
+ *   name: "My App",
+ *   installationInstructions: "Configure your API credentials below.",
+ *   config: {
+ *     apiKey: {
+ *       name: "API Key",
+ *       type: "string",
+ *       required: true
+ *     }
+ *   },
+ *   blocks: {
+ *     processor: {
+ *       name: "Data Processor",
+ *       inputs: {
+ *         data: {
+ *           name: "Input Data",
+ *           onEvent: async (input) => {
+ *             // Your processing logic here
+ *             await events.emit(processedData);
+ *           }
+ *         }
+ *       },
+ *       outputs: {
+ *         result: {
+ *           name: "Processed Result",
+ *           default: true
+ *         }
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
+ */
 declare function defineApp(app: AppSchema): AppSchema;
 
-export { type AppBlock, type AppBlockComponentInput, type AppBlockComponentOutput, type AppBlockConfigField, type AppBlockHTTPComponent, type AppBlockSchedule, type AppBlockSignal, type AppBlockUIComponent, type AppConfigField, type AppContext, type AppHTTPComponent, type AppHTTPEndpoint, type AppInput, type AppLifecycleCallbackOutput, type AppLifecycleStatus, type AppOnCreateOutput, type AppOnHTTPRequestInput, type AppOnInternalMessageInput, type AppOnTimerInput, type AppOnTriggerInput, type AppOnUIRequestInput, type AppSchedule, type AppSchema, type AppUIComponent, type EntityContext, type EntityHTTPEndpoint, type EntityInput, type EntityLifecycleCallbackOutput, type EntityLifecycleComponent, type EntityLifecycleStatus, type EntityOnHTTPRequestInput, type EntityOnInternalMessageInput, type EntityOnTimerInput, type EntityOnTriggerInput, type EntityOnUIRequestInput, type EntityView, type EntityViewType, type EventContext, type EventInput, type HTTPRequest, type ScheduleDefinition, type UIRequest, blocks, defineApp, events, getInvocationMetadata, http, kv, lifecycle, messaging, setAppInstallationStatus, timers, ui };
+export { type AppBlock, type AppBlockComponentInput, type AppBlockComponentOutput, type AppBlockConfigField, type AppBlockHTTPComponent, type AppBlockSchedule, type AppBlockSignal, type AppBlockUIComponent, type AppConfigField, type AppContext, type AppHTTPComponent, type AppHTTPEndpoint, type AppInput, type AppLifecycleCallbackOutput, type AppLifecycleStatus, type AppOnCreateOutput, type AppOnHTTPRequestInput, type AppOnInternalMessageInput, type AppOnTimerInput, type AppOnTriggerInput, type AppOnUIRequestInput, type AppSchedule, type AppSchema, type AppSignal, type AppUIComponent, type EntityContext, type EntityHTTPEndpoint, type EntityInput, type EntityLifecycleCallbackOutput, type EntityLifecycleComponent, type EntityLifecycleStatus, type EntityOnHTTPRequestInput, type EntityOnInternalMessageInput, type EntityOnTimerInput, type EntityOnTriggerInput, type EntityOnUIRequestInput, type EntityView, type EntityViewType, type EventContext, type EventInput, type HTTPRequest, type ScheduleDefinition, type UIRequest, blocks, defineApp, events, getInvocationMetadata, http, kv, lifecycle, messaging, timers, ui };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slflows/sdk",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "files": [
     "dist"
   ],
@@ -9,8 +9,8 @@
     "./v1": "./dist/v1/index.d.ts"
   },
   "devDependencies": {
-    "pkgroll": "^2.12.2",
-    "rollup": "^4.41.1",
+    "pkgroll": "^2.13.1",
+    "rollup": "^4.44.1",
     "rollup-plugin-dts": "^6.2.1",
     "typescript": "^5.8.3"
   },