@mulmochat-plugin/form 0.1.1 → 0.2.0

package/dist/core/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * MulmoChat Form Plugin - Core (Framework-agnostic)
+ *
+ * This module exports the core plugin logic without UI components.
+ * Import from "@mulmochat-plugin/form" or "@mulmochat-plugin/form/core"
+ */
+export type { BackendType, ToolContextApp, ToolContext, ToolResult, ToolResultComplete, JsonSchemaProperty, ToolDefinition, StartApiResponse, ToolSample, InputHandler, FileInputHandler, ClipboardImageInputHandler, UrlInputHandler, TextInputHandler, FileUploadConfig, ConfigValue, ConfigFieldSchema, PluginConfigSchema, ViewComponentProps, PreviewComponentProps, ToolPluginCore, FieldType, BaseField, TextField, TextareaField, RadioField, DropdownField, CheckboxField, DateField, TimeField, NumberField, FormField, FormData, FormArgs, } from "./types";
+export { TOOL_NAME, TOOL_DEFINITION, SAMPLES, executeForm, pluginCore, } from "./plugin";

package/dist/core/plugin.d.ts

@@ -0,0 +1,12 @@
+/**
+ * MulmoChat Form Plugin Core (Framework-agnostic)
+ *
+ * Contains the plugin logic without UI components.
+ * Can be used by any framework (Vue, React, etc.)
+ */
+import type { ToolPluginCore, ToolContext, ToolResult, ToolDefinition, ToolSample, FormData, FormArgs } from "./types";
+export declare const TOOL_NAME = "presentForm";
+export declare const TOOL_DEFINITION: ToolDefinition;
+export declare const SAMPLES: ToolSample[];
+export declare const executeForm: (_context: ToolContext, args: FormArgs) => Promise<ToolResult<never, FormData>>;
+export declare const pluginCore: ToolPluginCore<never, FormData, FormArgs>;

package/dist/core/types.d.ts

@@ -0,0 +1,311 @@
+/**
+ * MulmoChat Plugin Core Types (Framework-agnostic)
+ *
+ * These types can be used by any framework implementation (Vue, React, etc.)
+ */
+/**
+ * Backend types that plugins can declare they use.
+ * App layer manages actual provider/model settings for each type.
+ */
+export type BackendType = "textLLM" | "imageGen" | "audio" | "search" | "browse" | "map" | "mulmocast";
+/**
+ * App interface provided to plugins via context.app
+ * Contains backend functions and config accessors
+ */
+export interface ToolContextApp extends Record<string, (...args: any[]) => any> {
+    getConfig: <T = unknown>(key: string) => T | undefined;
+    setConfig: (key: string, value: unknown) => void;
+}
+/**
+ * Context passed to plugin execute function
+ */
+export interface ToolContext {
+    currentResult?: ToolResult<unknown> | null;
+    app?: ToolContextApp;
+}
+/**
+ * Result returned from plugin execution
+ */
+export interface ToolResult<T = unknown, J = unknown> {
+    toolName?: string;
+    uuid?: string;
+    message: string;
+    title?: string;
+    jsonData?: J;
+    instructions?: string;
+    instructionsRequired?: boolean;
+    updating?: boolean;
+    cancelled?: boolean;
+    data?: T;
+    viewState?: Record<string, unknown>;
+}
+/**
+ * Complete tool result with required fields
+ */
+export interface ToolResultComplete<T = unknown, J = unknown> extends ToolResult<T, J> {
+    toolName: string;
+    uuid: string;
+}
+/**
+ * JSON Schema property definition for tool parameters
+ */
+export interface JsonSchemaProperty {
+    type?: string;
+    description?: string;
+    enum?: string[];
+    items?: JsonSchemaProperty;
+    minimum?: number;
+    maximum?: number;
+    minItems?: number;
+    maxItems?: number;
+    properties?: Record<string, JsonSchemaProperty>;
+    required?: string[];
+    additionalProperties?: boolean;
+    oneOf?: JsonSchemaProperty[];
+    [key: string]: unknown;
+}
+/**
+ * Tool definition for OpenAI-compatible function calling
+ */
+export interface ToolDefinition {
+    type: "function";
+    name: string;
+    description: string;
+    parameters?: {
+        type: "object";
+        properties: Record<string, JsonSchemaProperty>;
+        required: string[];
+        additionalProperties?: boolean;
+    };
+}
+/**
+ * API response from server start endpoint
+ */
+export interface StartApiResponse {
+    hasOpenAIApiKey?: boolean;
+    hasAnthropicApiKey?: boolean;
+    hasGoogleApiKey?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Sample arguments for testing
+ */
+export interface ToolSample {
+    name: string;
+    args: Record<string, unknown>;
+}
+/**
+ * File input handler
+ */
+export interface FileInputHandler {
+    type: "file";
+    acceptedTypes: string[];
+    handleInput: (fileData: string, fileName: string) => ToolResult<unknown, unknown>;
+}
+/**
+ * Clipboard image input handler
+ */
+export interface ClipboardImageInputHandler {
+    type: "clipboard-image";
+    handleInput: (imageData: string) => ToolResult<unknown, unknown>;
+}
+/**
+ * URL input handler
+ */
+export interface UrlInputHandler {
+    type: "url";
+    patterns?: string[];
+    handleInput: (url: string) => ToolResult<unknown, unknown>;
+}
+/**
+ * Text input handler
+ */
+export interface TextInputHandler {
+    type: "text";
+    patterns?: string[];
+    handleInput: (text: string) => ToolResult<unknown, unknown>;
+}
+/**
+ * Union of all input handler types
+ */
+export type InputHandler = FileInputHandler | ClipboardImageInputHandler | UrlInputHandler | TextInputHandler;
+/**
+ * Legacy file upload config (for backward compatibility)
+ * @deprecated Use InputHandler instead
+ */
+export interface FileUploadConfig {
+    acceptedTypes: string[];
+    handleUpload: (fileData: string, fileName: string, ...args: unknown[]) => ToolResult<unknown, unknown>;
+}
+export type ConfigValue = string | number | boolean | string[];
+interface BaseFieldSchema {
+    label: string;
+    description?: string;
+    required?: boolean;
+}
+export interface StringFieldSchema extends BaseFieldSchema {
+    type: "string";
+    placeholder?: string;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+}
+export interface NumberFieldSchema extends BaseFieldSchema {
+    type: "number";
+    min?: number;
+    max?: number;
+    step?: number;
+}
+export interface BooleanFieldSchema extends BaseFieldSchema {
+    type: "boolean";
+}
+export interface SelectOption {
+    value: string;
+    label: string;
+    description?: string;
+    disabled?: boolean;
+}
+export interface SelectFieldSchema extends BaseFieldSchema {
+    type: "select";
+    options: SelectOption[];
+}
+export interface MultiSelectFieldSchema extends BaseFieldSchema {
+    type: "multiselect";
+    options: SelectOption[];
+    minItems?: number;
+    maxItems?: number;
+}
+export type ConfigFieldSchema = StringFieldSchema | NumberFieldSchema | BooleanFieldSchema | SelectFieldSchema | MultiSelectFieldSchema;
+/**
+ * Plugin configuration schema (JSON Schema based)
+ */
+export interface PluginConfigSchema {
+    key: string;
+    defaultValue: ConfigValue;
+    schema: ConfigFieldSchema;
+}
+/**
+ * Standard props for View components
+ */
+export interface ViewComponentProps<T = unknown, J = unknown> {
+    selectedResult: ToolResultComplete<T, J>;
+    sendTextMessage: (text?: string) => void;
+    onUpdateResult?: (result: Partial<ToolResult<T, J>>) => void;
+    pluginConfigs?: Record<string, unknown>;
+}
+/**
+ * Standard props for Preview components
+ */
+export interface PreviewComponentProps<T = unknown, J = unknown> {
+    result: ToolResultComplete<T, J>;
+    isSelected?: boolean;
+    onSelect?: () => void;
+}
+/**
+ * Core plugin interface - framework agnostic
+ * Does not include UI components
+ */
+export interface ToolPluginCore<T = unknown, J = unknown, A extends object = object> {
+    toolDefinition: ToolDefinition;
+    execute: (context: ToolContext, args: A) => Promise<ToolResult<T, J>>;
+    generatingMessage: string;
+    waitingMessage?: string;
+    uploadMessage?: string;
+    isEnabled: (startResponse?: StartApiResponse | null) => boolean;
+    delayAfterExecution?: number;
+    systemPrompt?: string;
+    inputHandlers?: InputHandler[];
+    /** @deprecated Use inputHandlers instead */
+    fileUpload?: FileUploadConfig;
+    /** New JSON Schema based config (framework-agnostic) */
+    configSchema?: PluginConfigSchema;
+    samples?: ToolSample[];
+    backends?: BackendType[];
+}
+/** Field type discriminator */
+export type FieldType = "text" | "textarea" | "radio" | "dropdown" | "checkbox" | "date" | "time" | "number";
+/** Base field interface */
+export interface BaseField {
+    id: string;
+    type: FieldType;
+    label: string;
+    description?: string;
+    required?: boolean;
+    maxLength?: number;
+}
+/** Text field */
+export interface TextField extends BaseField {
+    type: "text";
+    placeholder?: string;
+    validation?: "email" | "url" | "phone" | string;
+    defaultValue?: string;
+    minLength?: number;
+    maxLength?: number;
+}
+/** Textarea field */
+export interface TextareaField extends BaseField {
+    type: "textarea";
+    placeholder?: string;
+    minLength?: number;
+    maxLength?: number;
+    rows?: number;
+    defaultValue?: string;
+}
+/** Radio field */
+export interface RadioField extends BaseField {
+    type: "radio";
+    choices: string[];
+    defaultValue?: string;
+}
+/** Dropdown field */
+export interface DropdownField extends BaseField {
+    type: "dropdown";
+    choices: string[];
+    searchable?: boolean;
+    defaultValue?: string;
+}
+/** Checkbox field */
+export interface CheckboxField extends BaseField {
+    type: "checkbox";
+    choices: string[];
+    minSelections?: number;
+    maxSelections?: number;
+    defaultValue?: string[];
+}
+/** Date field */
+export interface DateField extends BaseField {
+    type: "date";
+    minDate?: string;
+    maxDate?: string;
+    format?: string;
+    defaultValue?: string;
+}
+/** Time field */
+export interface TimeField extends BaseField {
+    type: "time";
+    format?: "12hr" | "24hr";
+    defaultValue?: string;
+}
+/** Number field */
+export interface NumberField extends BaseField {
+    type: "number";
+    min?: number;
+    max?: number;
+    step?: number;
+    defaultValue?: number;
+}
+/** Union type for all fields */
+export type FormField = TextField | TextareaField | RadioField | DropdownField | CheckboxField | DateField | TimeField | NumberField;
+/** Form data stored in result.jsonData */
+export interface FormData {
+    title?: string;
+    description?: string;
+    fields: FormField[];
+}
+/** Arguments passed to the form tool */
+export interface FormArgs {
+    title?: string;
+    description?: string;
+    fields: FormField[];
+}
+export {};

package/dist/core.cjs

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const n="presentForm",s={type:"function",name:n,description:"Create a structured form to collect information from the user. Supports various field types including text input, textarea, multiple choice (radio), dropdown menus, checkboxes, date/time pickers, and number inputs. Each field can have validation rules and help text.",parameters:{type:"object",properties:{title:{type:"string",description:"Optional title for the form (e.g., 'User Registration')"},description:{type:"string",description:"Optional description explaining the purpose of the form"},fields:{type:"array",description:"Array of form fields with various types and configurations",items:{type:"object",properties:{id:{type:"string",description:"Unique identifier for the field (e.g., 'email', 'birthdate'). This will be the key in the JSON response. Use descriptive camelCase or snake_case names."},type:{type:"string",enum:["text","textarea","radio","dropdown","checkbox","date","time","number"],description:"Field type: 'text' for short text, 'textarea' for long text, 'radio' for 2-6 choices, 'dropdown' for many choices, 'checkbox' for multiple selections, 'date' for date picker, 'time' for time picker, 'number' for numeric input"},label:{type:"string",description:"Field label shown to the user"},description:{type:"string",description:"Optional help text explaining the field"},required:{type:"boolean",description:"Whether the field is required (default: false)"},placeholder:{type:"string",description:"Placeholder text for text/textarea fields"},validation:{type:"string",description:"For text fields: 'email', 'url', 'phone', or a regex pattern"},minLength:{type:"number",description:"Minimum character length for textarea fields"},maxLength:{type:"number",description:"Maximum character length for textarea fields"},rows:{type:"number",description:"Number of visible rows for textarea (default: 4)"},choices:{type:"array",items:{type:"string"},description:"Array of choices for radio/dropdown/checkbox fields. Radio should have 2-6 choices, dropdown for 7+ choices."},searchable:{type:"boolean",description:"Make dropdown searchable (for large lists)"},minSelections:{type:"number",description:"Minimum number of selections for checkbox fields"},maxSelections:{type:"number",description:"Maximum number of selections for checkbox fields"},minDate:{type:"string",description:"Minimum date (ISO format: YYYY-MM-DD)"},maxDate:{type:"string",description:"Maximum date (ISO format: YYYY-MM-DD)"},format:{type:"string",description:"Format for time fields: '12hr' or '24hr'"},min:{type:"number",description:"Minimum value for number fields"},max:{type:"number",description:"Maximum value for number fields"},step:{type:"number",description:"Step increment for number fields"},defaultValue:{description:"Optional default/pre-filled value for the field. Type varies by field: string for text/textarea/radio/dropdown/date/time, number for number fields, array of strings for checkbox fields. For radio/dropdown, must be one of the choices. For checkbox, must be a subset of choices."}},required:["id","type","label"]},minItems:1}},required:["fields"]}},l=[{name:"Contact Form",args:{title:"Contact Us",description:"Please fill out the form below to get in touch.",fields:[{id:"name",type:"text",label:"Full Name",required:!0,placeholder:"John Doe"},{id:"email",type:"text",label:"Email Address",required:!0,placeholder:"john@example.com",validation:"email"},{id:"subject",type:"dropdown",label:"Subject",choices:["General Inquiry","Technical Support","Sales","Feedback"],required:!0},{id:"message",type:"textarea",label:"Message",required:!0,minLength:10,maxLength:500,rows:5}]}},{name:"Survey Form",args:{title:"Customer Satisfaction Survey",fields:[{id:"satisfaction",type:"radio",label:"How satisfied are you with our service?",choices:["Very Satisfied","Satisfied","Neutral","Dissatisfied","Very Dissatisfied"],required:!0},{id:"features",type:"checkbox",label:"Which features do you use most?",choices:["Dashboard","Reports","Analytics","API","Integrations"],minSelections:1,maxSelections:3},{id:"recommendation",type:"number",label:"How likely are you to recommend us? (0-10)",min:0,max:10,step:1}]}},{name:"Event Registration",args:{title:"Event Registration",description:"Register for our upcoming conference.",fields:[{id:"attendeeName",type:"text",label:"Attendee Name",required:!0},{id:"eventDate",type:"date",label:"Preferred Date",required:!0,minDate:"2025-01-01",maxDate:"2025-12-31"},{id:"sessionTime",type:"time",label:"Session Time",format:"12hr"},{id:"dietaryRestrictions",type:"checkbox",label:"Dietary Restrictions",choices:["Vegetarian","Vegan","Gluten-Free","Halal","Kosher"]}]}}],d=async(g,c)=>{try{const{title:i,description:u,fields:t}=c;if(!t||!Array.isArray(t)||t.length===0)throw new Error("At least one field is required");const o=new Set;for(let r=0;r<t.length;r++){const e=t[r];if(!e.id||typeof e.id!="string")throw new Error(`Field ${r+1} must have a valid 'id' property`);if(!e.type||typeof e.type!="string")throw new Error(`Field ${r+1} must have a valid 'type' property`);if(!e.label||typeof e.label!="string")throw new Error(`Field ${r+1} must have a valid 'label' property`);if(o.has(e.id))throw new Error(`Duplicate field ID: '${e.id}'`);switch(o.add(e.id),e.type){case"text":case"textarea":if(e.minLength!==void 0&&e.maxLength!==void 0&&e.minLength>e.maxLength)throw new Error(`Field '${e.id}': minLength cannot be greater than maxLength`);break;case"radio":if(!Array.isArray(e.choices)||e.choices.length<2)throw new Error(`Field '${e.id}': radio fields must have at least 2 choices`);e.choices.length>6&&console.warn(`Field '${e.id}': radio fields with more than 6 choices should use 'dropdown' type instead`);break;case"dropdown":case"checkbox":if(!Array.isArray(e.choices)||e.choices.length<1)throw new Error(`Field '${e.id}': ${e.type} fields must have at least 1 choice`);break;case"number":if(e.min!==void 0&&e.max!==void 0&&e.min>e.max)throw new Error(`Field '${e.id}': min cannot be greater than max`);break;case"date":if(e.minDate&&e.maxDate&&e.minDate>e.maxDate)throw new Error(`Field '${e.id}': minDate cannot be after maxDate`);break;case"time":break;default:{const a=e;throw new Error(`Field '${a.id}': unknown field type '${a.type}'`)}}if(e.type==="checkbox"){if(e.minSelections!==void 0&&e.maxSelections!==void 0&&e.minSelections>e.maxSelections)throw new Error(`Field '${e.id}': minSelections cannot be greater than maxSelections`);if(e.maxSelections!==void 0&&e.maxSelections>e.choices.length)throw new Error(`Field '${e.id}': maxSelections cannot exceed number of choices`)}if(e.defaultValue!==void 0)switch(e.type){case"text":case"textarea":if(typeof e.defaultValue!="string")throw new Error(`Field '${e.id}': defaultValue must be a string`);if(e.minLength!==void 0&&e.defaultValue.length<e.minLength)throw new Error(`Field '${e.id}': defaultValue length is less than minLength`);if(e.maxLength!==void 0&&e.defaultValue.length>e.maxLength)throw new Error(`Field '${e.id}': defaultValue length exceeds maxLength`);break;case"radio":case"dropdown":if(typeof e.defaultValue!="string")throw new Error(`Field '${e.id}': defaultValue must be a string`);if(!e.choices.includes(e.defaultValue))throw new Error(`Field '${e.id}': defaultValue '${e.defaultValue}' is not in choices`);break;case"checkbox":if(!Array.isArray(e.defaultValue))throw new Error(`Field '${e.id}': defaultValue must be an array`);for(const a of e.defaultValue)if(!e.choices.includes(a))throw new Error(`Field '${e.id}': defaultValue contains '${a}' which is not in choices`);if(e.minSelections!==void 0&&e.defaultValue.length<e.minSelections)throw new Error(`Field '${e.id}': defaultValue has fewer selections than minSelections`);if(e.maxSelections!==void 0&&e.defaultValue.length>e.maxSelections)throw new Error(`Field '${e.id}': defaultValue has more selections than maxSelections`);break;case"number":if(typeof e.defaultValue!="number")throw new Error(`Field '${e.id}': defaultValue must be a number`);if(e.min!==void 0&&e.defaultValue<e.min)throw new Error(`Field '${e.id}': defaultValue is less than min`);if(e.max!==void 0&&e.defaultValue>e.max)throw new Error(`Field '${e.id}': defaultValue is greater than max`);break;case"date":if(typeof e.defaultValue!="string")throw new Error(`Field '${e.id}': defaultValue must be a string (ISO date format)`);if(e.minDate!==void 0&&e.defaultValue<e.minDate)throw new Error(`Field '${e.id}': defaultValue is before minDate`);if(e.maxDate!==void 0&&e.defaultValue>e.maxDate)throw new Error(`Field '${e.id}': defaultValue is after maxDate`);break;case"time":if(typeof e.defaultValue!="string")throw new Error(`Field '${e.id}': defaultValue must be a string`);break}}const f={title:i,description:u,fields:t},m=`${t.length} field${t.length>1?"s":""}`,h=i?`: ${i}`:"";return{message:`Form created with ${m}${h}`,jsonData:f,instructions:"The form has been presented to the user. Wait for the user to fill out and submit the form. They will send their responses as a JSON message."}}catch(i){return console.error(`ERR: exception
+ Form creation error`,i),{message:`Form error: ${i instanceof Error?i.message:"Unknown error"}`,instructions:"Acknowledge that there was an error creating the form and suggest trying again with corrected field definitions."}}},p={toolDefinition:s,execute:d,generatingMessage:"Preparing form...",isEnabled:()=>!0,samples:l};exports.SAMPLES=l;exports.TOOL_DEFINITION=s;exports.TOOL_NAME=n;exports.executeForm=d;exports.pluginCore=p;