@elizaos/plugin-form 2.0.0-alpha.3 → 2.0.0-alpha.4

package/dist/storage.d.ts

@@ -1,228 +0,0 @@
-/**
- * @module storage
- * @description Component-based persistence for form data
- *
- * ## Design Rationale
- *
- * Form data is stored using ElizaOS's Component system because:
- *
- * 1. **Entity-Scoped**: Components belong to entities (users).
- *    This naturally scopes form data per-user.
- *
- * 2. **Typed Storage**: Component type field allows different kinds
- *    of form data (sessions, submissions, autofill).
- *
- * 3. **No Custom Schema**: Uses existing ElizaOS infrastructure,
- *    no need to create database tables.
- *
- * 4. **Room Scoping**: Component type includes roomId for session
- *    isolation across rooms.
- *
- * ## Storage Strategy
- *
- * ### Sessions
- * - Stored as components with type: `form_session:{roomId}`
- * - One active session per user per room
- * - Scoping ensures different rooms have different contexts
- *
- * ### Submissions
- * - Stored as components with type: `form_submission:{formId}:{submissionId}`
- * - Immutable records of completed forms
- * - Multiple submissions per user (if form allows)
- *
- * ### Autofill
- * - Stored as components with type: `form_autofill:{formId}`
- * - One autofill record per user per form
- * - Updated on each submission
- *
- * ## Limitations
- *
- * The current implementation has limitations:
- *
- * 1. **No Cross-Entity Queries**: Can't efficiently find all stale
- *    sessions across all users. This affects nudge system.
- *
- * 2. **No Indexes**: Component queries are sequential scans.
- *    For high-volume usage, consider database-level optimizations.
- *
- * These are acceptable for v1 but noted for future improvement.
- */
-import type { IAgentRuntime, JsonValue, UUID } from "@elizaos/core";
-import type { FormSession, FormSubmission, FormAutofillData } from "./types";
-/**
- * Get active form session for entity in a specific room.
- *
- * WHY room-scoped:
- * - User might chat in multiple rooms simultaneously
- * - Each room conversation should have its own form context
- * - Discord DM form shouldn't interfere with Telegram form
- *
- * WHY active/ready filter:
- * - Stashed, submitted, cancelled, expired sessions are not "active"
- * - User would need to restore stashed sessions
- *
- * @param runtime - Agent runtime for database access
- * @param entityId - User's entity ID
- * @param roomId - The room to check for active session
- * @returns Active session or null if none
- */
-export declare function getActiveSession(runtime: IAgentRuntime, entityId: UUID, roomId: UUID): Promise<FormSession | null>;
-/**
- * Get all active sessions for an entity (across all rooms).
- *
- * WHY this exists:
- * - For "you have forms in progress" notifications
- * - For session management UI
- * - Not commonly used in normal flow
- *
- * @param runtime - Agent runtime for database access
- * @param entityId - User's entity ID
- * @returns Array of active sessions (may be empty)
- */
-export declare function getAllActiveSessions(runtime: IAgentRuntime, entityId: UUID): Promise<FormSession[]>;
-/**
- * Get stashed sessions for an entity.
- *
- * WHY stashed is separate from active:
- * - Stashed sessions are "saved for later"
- * - User must explicitly restore them
- * - Different UX from active sessions
- *
- * @param runtime - Agent runtime for database access
- * @param entityId - User's entity ID
- * @returns Array of stashed sessions (may be empty)
- */
-export declare function getStashedSessions(runtime: IAgentRuntime, entityId: UUID): Promise<FormSession[]>;
-/**
- * Get a session by ID.
- *
- * WHY by ID:
- * - Needed for operations on specific session
- * - Session ID is stable across room changes
- * - Used by stash/restore when session roomId changes
- *
- * @param runtime - Agent runtime for database access
- * @param entityId - User's entity ID
- * @param sessionId - The session ID to find
- * @returns The session or null if not found
- */
-export declare function getSessionById(runtime: IAgentRuntime, entityId: UUID, sessionId: string): Promise<FormSession | null>;
-/**
- * Save a form session.
- *
- * Creates new component if none exists, updates otherwise.
- *
- * WHY upsert pattern:
- * - Session is created once, updated many times
- * - Single function handles both cases
- * - Avoids race conditions
- *
- * @param runtime - Agent runtime for database access
- * @param session - Session to save
- */
-export declare function saveSession(runtime: IAgentRuntime, session: FormSession): Promise<void>;
-/**
- * Delete a session.
- *
- * WHY delete:
- * - Cleanup after submission/cancellation/expiry
- * - Frees up storage
- * - Note: Usually we just change status instead of deleting
- *
- * @param runtime - Agent runtime for database access
- * @param session - Session to delete
- */
-export declare function deleteSession(runtime: IAgentRuntime, session: FormSession): Promise<void>;
-/**
- * Save a form submission.
- *
- * Submissions are immutable records. Always creates new component.
- *
- * WHY new component per submission:
- * - Submissions are immutable
- * - Multiple submissions allowed (if form permits)
- * - Historical record keeping
- *
- * @param runtime - Agent runtime for database access
- * @param submission - Submission to save
- */
-export declare function saveSubmission(runtime: IAgentRuntime, submission: FormSubmission): Promise<void>;
-/**
- * Get submissions for an entity, optionally filtered by form ID.
- *
- * WHY optional formId:
- * - List all submissions: no formId
- * - List submissions for specific form: with formId
- *
- * @param runtime - Agent runtime for database access
- * @param entityId - User's entity ID
- * @param formId - Optional form ID filter
- * @returns Array of submissions, newest first
- */
-export declare function getSubmissions(runtime: IAgentRuntime, entityId: UUID, formId?: string): Promise<FormSubmission[]>;
-/**
- * Get a specific submission by ID.
- *
- * @param runtime - Agent runtime for database access
- * @param entityId - User's entity ID
- * @param submissionId - The submission ID to find
- * @returns The submission or null if not found
- */
-export declare function getSubmissionById(runtime: IAgentRuntime, entityId: UUID, submissionId: string): Promise<FormSubmission | null>;
-/**
- * Get autofill data for a user's form.
- *
- * WHY autofill:
- * - Users filling repeat forms want saved values
- * - Reduces friction for common fields (name, email, address)
- *
- * @param runtime - Agent runtime for database access
- * @param entityId - User's entity ID
- * @param formId - Form definition ID
- * @returns Autofill data or null if none saved
- */
-export declare function getAutofillData(runtime: IAgentRuntime, entityId: UUID, formId: string): Promise<FormAutofillData | null>;
-/**
- * Save autofill data for a user's form.
- *
- * Overwrites existing autofill data for the form.
- *
- * WHY overwrite:
- * - Most recent submission has most current data
- * - User's email might have changed
- * - Only one autofill record per form needed
- *
- * @param runtime - Agent runtime for database access
- * @param entityId - User's entity ID
- * @param formId - Form definition ID
- * @param values - Field values to save for autofill
- */
-export declare function saveAutofillData(runtime: IAgentRuntime, entityId: UUID, formId: string, values: Record<string, JsonValue>): Promise<void>;
-/**
- * Get all stale sessions (for nudge system).
- *
- * LIMITATION: This requires iterating over all entities, which is not
- * efficient with current ElizaOS component system. In production,
- * this would need a database-level query.
- *
- * WHY this is here:
- * - Documents the need for this functionality
- * - Placeholder for future implementation
- * - Nudge system can call this when entity context is available
- *
- * @param runtime - Agent runtime for database access
- * @param afterInactiveMs - Inactivity threshold in milliseconds
- * @returns Array of stale sessions (currently returns empty array)
- */
-export declare function getStaleSessions(runtime: IAgentRuntime, afterInactiveMs: number): Promise<FormSession[]>;
-/**
- * Get sessions expiring within a time window.
- *
- * Same limitation as getStaleSessions.
- *
- * @param runtime - Agent runtime for database access
- * @param withinMs - Time window in milliseconds
- * @returns Array of expiring sessions (currently returns empty array)
- */
-export declare function getExpiringSessions(runtime: IAgentRuntime, withinMs: number): Promise<FormSession[]>;
-//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,KAAK,EAAa,aAAa,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAE/E,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AA0D7E;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,IAAI,EACd,MAAM,EAAE,IAAI,GACX,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAkB7B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,IAAI,GACb,OAAO,CAAC,WAAW,EAAE,CAAC,CAiBxB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,IAAI,GACb,OAAO,CAAC,WAAW,EAAE,CAAC,CAgBxB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,IAAI,EACd,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAe7B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CAyBf;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CAOf;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,aAAa,EACtB,UAAU,EAAE,cAAc,GACzB,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,IAAI,EACd,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,cAAc,EAAE,CAAC,CAqB3B;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,IAAI,EACd,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAehC;AAMD;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,IAAI,EACd,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAOlC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,IAAI,EACd,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAChC,OAAO,CAAC,IAAI,CAAC,CA6Bf;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,aAAa,EACtB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,WAAW,EAAE,CAAC,CAWxB;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,WAAW,EAAE,CAAC,CAKxB"}

package/dist/tasks/nudge.d.ts

@@ -1,89 +0,0 @@
-/**
- * @module tasks/nudge
- * @description Background task for nudging stale form sessions
- *
- * ## Purpose
- *
- * Users start forms and forget about them. The nudge system sends
- * gentle reminders:
- *
- * 1. **Stale Sessions**: "You have an unfinished registration form..."
- * 2. **Expiring Sessions**: "Your form will expire in 24 hours..."
- * 3. **Expired Sessions**: Mark as expired, trigger onExpire hook
- *
- * ## Architecture
- *
- * The nudge system has two components:
- *
- * ### 1. Task Worker (formNudgeWorker)
- *
- * A background task that periodically checks for stale sessions.
- *
- * **Limitation**: The current ElizaOS component system doesn't support
- * efficient cross-entity queries. The worker needs to know which entities
- * to check.
- *
- * ### 2. Per-Entity Processing (processEntityNudges)
- *
- * Called with a specific entity ID to process that user's sessions.
- * This can be triggered:
- * - After any form interaction (opportunistic)
- * - By a scheduled job with known entity IDs
- * - By admin action
- *
- * ## Nudge Rules
- *
- * 1. Only nudge stashed sessions (not active ones)
- * 2. Wait configurable hours before first nudge (default: 48)
- * 3. Maximum nudges per session (default: 3)
- * 4. At least 24 hours between nudges
- *
- * ## Expiration Warnings
- *
- * Before a session expires, we warn the user:
- * - 24 hours before expiration
- * - Only warn once per session (expirationWarned flag)
- *
- * ## Sending Messages
- *
- * The nudge system uses `runtime.sendMessageToRoom` if available.
- * Not all runtimes support this - it's a best-effort feature.
- *
- * ## Future Improvements
- *
- * 1. Database-level query for stale sessions
- * 2. Integration with notification system
- * 3. User preferences for nudge frequency
- */
-import type { IAgentRuntime, TaskWorker } from "@elizaos/core";
-/**
- * Nudge Task Worker
- *
- * Periodically checks for stale form sessions and:
- * 1. Sends nudge messages for inactive sessions
- * 2. Sends expiration warnings for sessions about to expire
- * 3. Cleans up expired sessions
- *
- * WHY a task worker:
- * - Runs independently of user interaction
- * - Can be scheduled to run periodically
- * - Handles multiple entities efficiently
- */
-export declare const formNudgeWorker: TaskWorker;
-/**
- * Process nudges and expirations for a specific entity.
- *
- * This function can be called when we have an entity context.
- * For example, it could be triggered after any form interaction.
- *
- * WHY separate function:
- * - Can be called opportunistically
- * - Avoids cross-entity query limitation
- * - Easy to test with specific entity
- *
- * @param runtime - Agent runtime for service access
- * @param entityId - The entity to process
- */
-export declare function processEntityNudges(runtime: IAgentRuntime, entityId: string): Promise<void>;
-export default formNudgeWorker;
-//# sourceMappingURL=nudge.d.ts.map

package/dist/tasks/nudge.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"nudge.d.ts","sourceRoot":"","sources":["../../src/tasks/nudge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAK/D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe,EAAE,UA4C7B,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CA+Df;AAoED,eAAe,eAAe,CAAC"}

package/dist/template.d.ts

@@ -1,10 +0,0 @@
-/**
- * @module template
- * @description Simple template resolution for form-controlled prompts
- */
-import type { FormControl, FormSession } from "./types";
-export type TemplateValues = Record<string, string>;
-export declare function buildTemplateValues(session: FormSession): TemplateValues;
-export declare function renderTemplate(template: string | undefined, values: TemplateValues): string | undefined;
-export declare function resolveControlTemplates(control: FormControl, values: TemplateValues): FormControl;
-//# sourceMappingURL=template.d.ts.map

package/dist/template.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../src/template.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAExD,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAIpD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,WAAW,GAAG,cAAc,CAwBxE;AAED,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,MAAM,EAAE,cAAc,GACrB,MAAM,GAAG,SAAS,CASpB;AAED,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,cAAc,GACrB,WAAW,CAuBb"}

package/dist/ttl.d.ts

@@ -1,144 +0,0 @@
-/**
- * @module ttl
- * @description Smart TTL (Time-To-Live) management for form sessions
- *
- * ## Design Philosophy
- *
- * Traditional form systems delete abandoned forms after a fixed time.
- * This fails users who invest significant effort:
- *
- * - User A: Opens form, immediately abandons → 24h retention is fine
- * - User B: Spends 2 hours filling complex form → 24h retention loses their work!
- *
- * ## Effort-Based TTL
- *
- * This module calculates TTL based on user effort:
- *
- * ```
- * TTL = clamp(minDays, effortDays, maxDays)
- *
- * where:
- *   effortDays = minutesSpent * effortMultiplier
- * ```
- *
- * Default values:
- * - minDays: 14 (two weeks minimum)
- * - maxDays: 90 (three months maximum)
- * - effortMultiplier: 0.5 (10 minutes = 5 extra days)
- *
- * ## Examples
- *
- * | Time Spent | Extra Days | Total TTL |
- * |------------|------------|-----------|
- * | 0 min      | 0          | 14 days   |
- * | 10 min     | 5          | 14 days   |
- * | 30 min     | 15         | 15 days   |
- * | 2 hours    | 60         | 60 days   |
- * | 4 hours    | 120        | 90 days   |
- *
- * ## Nudge System
- *
- * The nudge system sends reminders for stale forms:
- *
- * 1. After 48 hours of inactivity (configurable)
- * 2. Maximum 3 nudges (configurable)
- * 3. At least 24 hours between nudges
- *
- * ## Expiration Warnings
- *
- * Before a session expires, we warn the user:
- *
- * - 24 hours before expiration
- * - "Your form will expire in 1 day. Say 'resume' to keep working."
- *
- * This gives users a chance to save their work.
- */
-import type { FormDefinition, FormSession } from "./types";
-/**
- * Calculate TTL based on user effort.
- *
- * The more time a user spends on a form, the longer we keep it.
- * This prevents losing significant work while still cleaning up abandoned forms.
- *
- * WHY effort-based:
- * - Respects user investment
- * - Automatic cleanup of abandoned forms
- * - No manual expiration management needed
- *
- * @param session - Current session with effort tracking
- * @param form - Form definition with TTL configuration
- * @returns Expiration timestamp (milliseconds since epoch)
- */
-export declare function calculateTTL(session: FormSession, form?: FormDefinition): number;
-/**
- * Check if session should be nudged.
- *
- * Nudges are gentle reminders for stashed or inactive forms.
- *
- * WHY nudge:
- * - Users forget about forms they started
- * - Gentle reminders increase completion
- * - But too many nudges are annoying
- *
- * @param session - Session to check
- * @param form - Form definition with nudge configuration
- * @returns true if a nudge should be sent
- */
-export declare function shouldNudge(session: FormSession, form?: FormDefinition): boolean;
-/**
- * Check if session is expiring soon.
- *
- * Used to send expiration warnings before session is deleted.
- *
- * @param session - Session to check
- * @param withinMs - Time window in milliseconds
- * @returns true if session expires within the window
- */
-export declare function isExpiringSoon(session: FormSession, withinMs: number): boolean;
-/**
- * Check if session has expired.
- *
- * @param session - Session to check
- * @returns true if session has passed its expiration time
- */
-export declare function isExpired(session: FormSession): boolean;
-/**
- * Check if we should confirm before canceling.
- *
- * High-effort sessions deserve a confirmation before abandonment.
- *
- * WHY confirm:
- * - Prevent accidental loss of significant work
- * - "Are you sure?" for forms user invested in
- *
- * @param session - Session to check
- * @returns true if cancel should require confirmation
- */
-export declare function shouldConfirmCancel(session: FormSession): boolean;
-/**
- * Format remaining time for user display.
- *
- * Produces human-readable strings like:
- * - "14 days"
- * - "3 hours"
- * - "45 minutes"
- * - "expired"
- *
- * @param session - Session to format
- * @returns Human-readable time remaining
- */
-export declare function formatTimeRemaining(session: FormSession): string;
-/**
- * Format effort for user display.
- *
- * Produces human-readable strings like:
- * - "just started"
- * - "5 minutes"
- * - "2 hours"
- * - "1h 30m"
- *
- * @param session - Session to format
- * @returns Human-readable effort description
- */
-export declare function formatEffort(session: FormSession): string;
-//# sourceMappingURL=ttl.d.ts.map

package/dist/ttl.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ttl.d.ts","sourceRoot":"","sources":["../src/ttl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAG3D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,WAAW,EACpB,IAAI,CAAC,EAAE,cAAc,GACpB,MAAM,CAwBR;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,WAAW,EACpB,IAAI,CAAC,EAAE,cAAc,GACpB,OAAO,CAsCT;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,MAAM,GACf,OAAO,CAET;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAEvD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAKjE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAuBhE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAmBzD"}