@bubblelab/bubble-core 0.1.0

package/dist/bubbles/tool-bubble/get-bubble-details-tool.js

@@ -0,0 +1,645 @@
+import { z } from 'zod';
+import { ToolBubble } from '../../types/tool-bubble-class.js';
+import { CredentialType } from '@bubblelab/shared-schemas';
+import { BubbleFactory } from '../../bubble-factory.js';
+// Define the parameters schema
+const GetBubbleDetailsToolParamsSchema = z.object({
+    bubbleName: z
+        .string()
+        .min(1, 'Bubble name is required')
+        .describe('The name of the bubble to get details about'),
+    credentials: z
+        .record(z.nativeEnum(CredentialType), z.string())
+        .optional()
+        .describe('Object mapping credential types to values (injected at runtime)'),
+});
+// Result schema for validation
+const GetBubbleDetailsToolResultSchema = z.object({
+    name: z.string().describe('Name of the bubble'),
+    alias: z.string().optional().describe('Short alias for the bubble'),
+    outputSchema: z
+        .string()
+        .describe('String representation of the output schema types'),
+    usageExample: z
+        .string()
+        .describe('Code example showing how to use the bubble'),
+    success: z.boolean().describe('Whether the operation was successful'),
+    error: z.string().describe('Error message if operation failed'),
+});
+export class GetBubbleDetailsTool extends ToolBubble {
+    static type = 'tool';
+    static bubbleName = 'get-bubble-details-tool';
+    static schema = GetBubbleDetailsToolParamsSchema;
+    static resultSchema = GetBubbleDetailsToolResultSchema;
+    static shortDescription = 'Provides detailed information about a specific bubble, including schema, parameters, and documentation';
+    static longDescription = `
+    A tool bubble that retrieves comprehensive information about any registered bubble in the system.
+    
+    Returns detailed information including:
+    - Complete schema with parameter types and descriptions
+    - Result schema for expected outputs
+    - Credential requirements
+    - AI-formatted documentation
+    - Usage examples
+    
+    Use cases:
+    - AI agent understanding of specific bubble capabilities
+    - Parameter validation before bubble instantiation
+    - Documentation generation and help systems
+    - Dynamic form generation for bubble configuration
+  `;
+    static alias = 'details';
+    factory;
+    constructor(params, context) {
+        super(params, context);
+        this.factory = new BubbleFactory();
+    }
+    async performAction(context) {
+        void context; // Context available but not currently used
+        await this.factory.registerDefaults();
+        const metadata = this.factory.getMetadata(this.params.bubbleName);
+        if (!metadata) {
+            throw new Error(`Bubble '${this.params.bubbleName}' not found in registry`);
+        }
+        // Format schema for AI consumption
+        // const schemaProperties = JSON.stringify(zodToJsonSchema(metadata.schema));
+        // const resultSchemaProperties = JSON.stringify(
+        //   zodToJsonSchema(metadata.resultSchema!)
+        // );
+        // Create formatted description for AI agents
+        const usageExample = this.generateUsageExample({
+            name: metadata.name,
+            schema: metadata.schema,
+            resultSchema: metadata.resultSchema,
+        });
+        // Generate string representation of output schema
+        const outputSchemaString = this.generateOutputSchemaString(metadata.resultSchema);
+        return {
+            name: metadata.name,
+            alias: metadata.alias,
+            outputSchema: outputSchemaString,
+            usageExample,
+            success: true,
+            error: '',
+        };
+    }
+    generateOutputSchemaString(resultSchema) {
+        if (!resultSchema) {
+            return 'No output schema defined';
+        }
+        try {
+            if (resultSchema &&
+                typeof resultSchema === 'object' &&
+                'shape' in resultSchema) {
+                const shape = resultSchema.shape;
+                const outputFields = [];
+                for (const [key, value] of Object.entries(shape)) {
+                    if (value && typeof value === 'object' && '_def' in value) {
+                        const zodType = value;
+                        const typeInfo = this.generateTypeInfo(zodType);
+                        const description = this.getParameterDescription(zodType);
+                        if (typeInfo) {
+                            let fieldLine = `${key}: ${typeInfo}`;
+                            if (description) {
+                                fieldLine += ` // ${description}`;
+                            }
+                            outputFields.push(fieldLine);
+                        }
+                    }
+                }
+                if (outputFields.length > 0) {
+                    return `{\n  ${outputFields.join(',\n  ')}\n}`;
+                }
+            }
+            return 'Complex schema - see usage example for structure';
+        }
+        catch {
+            return 'Unable to parse output schema';
+        }
+    }
+    generateTypeInfo(zodType) {
+        const def = zodType._def;
+        if (def.typeName === 'ZodString') {
+            return 'string';
+        }
+        else if (def.typeName === 'ZodNumber') {
+            return 'number';
+        }
+        else if (def.typeName === 'ZodBoolean') {
+            return 'boolean';
+        }
+        else if (def.typeName === 'ZodArray') {
+            const elementType = def.type;
+            if (elementType) {
+                const elementTypeInfo = this.generateTypeInfo(elementType);
+                if (elementTypeInfo) {
+                    return `${elementTypeInfo}[]`;
+                }
+            }
+            return 'unknown[]';
+        }
+        else if (def.typeName === 'ZodObject') {
+            if ('shape' in zodType) {
+                const shape = zodType.shape;
+                const properties = [];
+                for (const [key, value] of Object.entries(shape)) {
+                    if (value && typeof value === 'object' && '_def' in value) {
+                        const zodValue = value;
+                        const typeInfo = this.generateTypeInfo(zodValue);
+                        if (typeInfo) {
+                            properties.push(`${key}: ${typeInfo}`);
+                        }
+                    }
+                }
+                if (properties.length > 0) {
+                    return `{ ${properties.join(', ')} }`;
+                }
+            }
+            return 'object';
+        }
+        else if (def.typeName === 'ZodOptional') {
+            const innerType = this.generateTypeInfo(def.innerType);
+            return innerType ? `${innerType} | undefined` : 'unknown | undefined';
+        }
+        else if (def.typeName === 'ZodDefault') {
+            return this.generateTypeInfo(def.innerType);
+        }
+        else if (def.typeName === 'ZodEnum') {
+            const enumValues = def.values;
+            return enumValues.map((v) => `"${v}"`).join(' | ');
+        }
+        else if (def.typeName === 'ZodLiteral') {
+            return typeof def.value === 'string'
+                ? `"${def.value}"`
+                : String(def.value);
+        }
+        else if (def.typeName === 'ZodRecord') {
+            const valueType = def.valueType;
+            if (valueType) {
+                const valueTypeInfo = this.generateTypeInfo(valueType);
+                if (valueTypeInfo) {
+                    return `Record<string, ${valueTypeInfo}>`;
+                }
+            }
+            return 'Record<string, unknown>';
+        }
+        else if (def.typeName === 'ZodDiscriminatedUnion') {
+            return 'DiscriminatedUnion'; // Simplified for complex unions
+        }
+        return 'unknown';
+    }
+    generateUsageExample(metadata) {
+        const lines = [];
+        // Check if this is a discriminated union (multiple operations)
+        const isDiscriminatedUnion = this.isDiscriminatedUnion(metadata.schema);
+        if (isDiscriminatedUnion) {
+            // Generate separate examples for each operation
+            const operationExamples = this.generateOperationExamples(metadata);
+            if (operationExamples.length > 0) {
+                lines.push(...operationExamples);
+            }
+            else {
+                // Fallback to original format if operation parsing fails
+                lines.push(...this.generateSingleExample(metadata));
+            }
+        }
+        else {
+            // Generate single example for non-discriminated schemas
+            lines.push(...this.generateSingleExample(metadata));
+        }
+        return lines.join('\n');
+    }
+    isDiscriminatedUnion(schema) {
+        if (schema && typeof schema === 'object' && '_def' in schema) {
+            const zodSchema = schema;
+            return zodSchema._def.typeName === 'ZodDiscriminatedUnion';
+        }
+        return false;
+    }
+    generateOperationExamples(metadata) {
+        const lines = [];
+        if (metadata.schema &&
+            typeof metadata.schema === 'object' &&
+            '_def' in metadata.schema) {
+            const zodSchema = metadata.schema;
+            const def = zodSchema._def;
+            if (def.typeName === 'ZodDiscriminatedUnion') {
+                const options = def.options;
+                const discriminatorKey = def.discriminator;
+                // Limit to first 4 operations to avoid overwhelming output
+                const maxOperations = 4;
+                const operationsToShow = options.slice(0, maxOperations);
+                operationsToShow.forEach((option, index) => {
+                    if (option && typeof option === 'object' && 'shape' in option) {
+                        const shape = option.shape;
+                        // Get the operation name from discriminator
+                        const discriminatorValue = shape[discriminatorKey];
+                        if (discriminatorValue &&
+                            typeof discriminatorValue === 'object' &&
+                            '_def' in discriminatorValue) {
+                            const literalDef = discriminatorValue._def;
+                            if (literalDef.typeName === 'ZodLiteral') {
+                                const operationName = literalDef.value;
+                                // Add spacing between operations
+                                if (index > 0) {
+                                    lines.push('');
+                                }
+                                // Add operation-specific comment
+                                const operationComment = this.formatOperationComment(operationName);
+                                lines.push(`// ${operationComment}`);
+                                // Create variable name with operation suffix
+                                const variableName = `${this.toCamelCase(metadata.name)}_${operationName.replace(/[^a-zA-Z0-9]/g, '_')}`;
+                                lines.push(`const ${variableName} = new ${this.toPascalCase(metadata.name)}Bubble({`);
+                                // Generate parameters for this specific operation
+                                const operationParams = [];
+                                Object.entries(shape).forEach(([key, value]) => {
+                                    if (key === 'credentials')
+                                        return; // Skip credentials
+                                    if (value && typeof value === 'object' && '_def' in value) {
+                                        const zodType = value;
+                                        const example = this.generateExampleValue(zodType);
+                                        const description = this.getParameterDescription(zodType);
+                                        if (example !== null) {
+                                            const paramLine = `  ${key}: ${example}`;
+                                            if (description) {
+                                                operationParams.push(`${paramLine}, // ${description}`);
+                                            }
+                                            else {
+                                                operationParams.push(`${paramLine},`);
+                                            }
+                                        }
+                                    }
+                                });
+                                if (operationParams.length > 0) {
+                                    lines.push(...operationParams);
+                                }
+                                else {
+                                    lines.push('  // Add required parameters here');
+                                }
+                                lines.push('});');
+                                lines.push('');
+                                lines.push(`const result = await ${variableName}.action();`);
+                            }
+                        }
+                    }
+                });
+                // Add common result handling code once at the end
+                if (operationsToShow.length > 0) {
+                    lines.push('');
+                    lines.push('// Always check success status before using data');
+                    lines.push('if (!result.success) {');
+                    lines.push(`  throw new Error(\`${metadata.name} failed: \${result.error}\`);`);
+                    lines.push('}');
+                    lines.push('');
+                    // Add output schema information
+                    if (metadata.resultSchema) {
+                        const outputExample = this.generateOutputExample(metadata.resultSchema);
+                        if (outputExample) {
+                            lines.push('// Expected output structure in result.data:');
+                            lines.push(`// ${outputExample}`);
+                            lines.push('');
+                        }
+                    }
+                    lines.push('// Access the actual data');
+                    lines.push('const actualData = result.data;');
+                    lines.push('console.log(actualData);');
+                    // Add note if there are more operations
+                    if (options.length > maxOperations) {
+                        lines.push('');
+                        lines.push(`// ... and ${options.length - maxOperations} more operations available`);
+                    }
+                }
+            }
+        }
+        return lines;
+    }
+    generateSingleExample(metadata) {
+        const lines = [];
+        lines.push(`// Example usage of ${metadata.name} bubble`);
+        // Try to extract example parameters from schema
+        const exampleParams = this.generateExampleParams(metadata.schema);
+        lines.push(`const ${this.toCamelCase(metadata.name)} = new ${this.toPascalCase(metadata.name)}Bubble({`);
+        if (exampleParams.length > 0) {
+            lines.push(...exampleParams.map((param) => `  ${param},`));
+        }
+        else {
+            lines.push('  // Add required parameters here');
+        }
+        lines.push('});');
+        lines.push('');
+        lines.push(`const result = await ${this.toCamelCase(metadata.name)}.action();`);
+        lines.push('');
+        lines.push('// Always check success status before using data');
+        lines.push('if (!result.success) {');
+        lines.push('  throw new Error(`${metadata.name} failed: ${result.error}`);');
+        lines.push('}');
+        lines.push('');
+        // Add output schema information
+        if (metadata.resultSchema) {
+            const outputExample = this.generateOutputExample(metadata.resultSchema);
+            if (outputExample) {
+                lines.push('// Expected output structure in result.data:');
+                lines.push(`// ${outputExample}`);
+                lines.push('');
+            }
+        }
+        lines.push('// Access the actual data');
+        lines.push('const actualData = result.data;');
+        lines.push('console.log(actualData);');
+        return lines;
+    }
+    formatOperationComment(operationName) {
+        // Convert operation name to readable format
+        return (operationName
+            .split('_')
+            .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+            .join(' ') + ' example');
+    }
+    generateOutputExample(resultSchema) {
+        try {
+            // Try to generate a meaningful example of the output structure
+            if (resultSchema &&
+                typeof resultSchema === 'object' &&
+                'shape' in resultSchema) {
+                const shape = resultSchema.shape;
+                const outputFields = [];
+                for (const [key, value] of Object.entries(shape)) {
+                    if (value && typeof value === 'object' && '_def' in value) {
+                        const zodType = value;
+                        const example = this.generateExampleValue(zodType);
+                        const description = this.getParameterDescription(zodType);
+                        if (example !== null) {
+                            let fieldLine = `${key}: ${example}`;
+                            if (description) {
+                                fieldLine += ` // ${description}`;
+                            }
+                            outputFields.push(fieldLine);
+                        }
+                    }
+                }
+                if (outputFields.length > 0) {
+                    return `{ ${outputFields.join(', ')} }`;
+                }
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Extracts the description from a Zod schema type
+     */
+    getParameterDescription(zodType) {
+        try {
+            const def = zodType._def;
+            // Check if the schema has a description
+            if (def.description) {
+                return def.description;
+            }
+            // For optional types, check the inner type
+            if (def.typeName === 'ZodOptional' && def.innerType) {
+                return this.getParameterDescription(def.innerType);
+            }
+            // For default types, check the inner type
+            if (def.typeName === 'ZodDefault' && def.innerType) {
+                return this.getParameterDescription(def.innerType);
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    generateExampleParams(schema) {
+        const params = [];
+        if (schema && typeof schema === 'object' && '_def' in schema) {
+            const zodSchema = schema;
+            const def = zodSchema._def;
+            // Handle discriminated unions
+            if (def.typeName === 'ZodDiscriminatedUnion') {
+                // For discriminated unions, show examples for all operations
+                const options = def.options;
+                const discriminatorKey = def.discriminator;
+                options.forEach((option, index) => {
+                    if (option && typeof option === 'object' && 'shape' in option) {
+                        const shape = option.shape;
+                        // Get the discriminator value for this option
+                        const discriminatorValue = shape[discriminatorKey];
+                        if (discriminatorValue &&
+                            typeof discriminatorValue === 'object' &&
+                            '_def' in discriminatorValue) {
+                            const literalDef = discriminatorValue._def;
+                            if (literalDef.typeName === 'ZodLiteral') {
+                                const operationName = literalDef.value;
+                                // Add operation header
+                                if (index > 0)
+                                    params.push(''); // Add spacing between operations
+                                params.push(`// Operation: ${operationName}`);
+                                // Add parameters for this operation
+                                Object.entries(shape).forEach(([key, value]) => {
+                                    if (key === 'credentials' || key === discriminatorKey)
+                                        return; // Skip credentials and discriminator
+                                    if (value && typeof value === 'object' && '_def' in value) {
+                                        const zodType = value;
+                                        const example = this.generateExampleValue(zodType);
+                                        const description = this.getParameterDescription(zodType);
+                                        if (example !== null) {
+                                            const paramLine = `  ${key}: ${example}`;
+                                            if (description) {
+                                                params.push(`${paramLine}, // ${description}`);
+                                            }
+                                            else {
+                                                params.push(`${paramLine},`);
+                                            }
+                                        }
+                                    }
+                                });
+                            }
+                        }
+                    }
+                });
+            }
+            // Handle regular objects
+            else if ('shape' in schema) {
+                const zodSchema = schema;
+                const shape = zodSchema.shape;
+                Object.entries(shape).forEach(([key, value]) => {
+                    if (key === 'credentials')
+                        return; // Skip credentials in examples
+                    if (value && typeof value === 'object' && '_def' in value) {
+                        const zodType = value;
+                        const example = this.generateExampleValue(zodType);
+                        const description = this.getParameterDescription(zodType);
+                        if (example !== null) {
+                            const paramLine = `${key}: ${example}`;
+                            if (description) {
+                                params.push(`${paramLine}, // ${description}`);
+                            }
+                            else {
+                                params.push(`${paramLine},`);
+                            }
+                        }
+                    }
+                });
+            }
+        }
+        return params;
+    }
+    generateExampleValue(zodType) {
+        const def = zodType._def;
+        if (def.typeName === 'ZodString') {
+            return '"example string"';
+        }
+        else if (def.typeName === 'ZodNumber') {
+            return '42';
+        }
+        else if (def.typeName === 'ZodBoolean') {
+            return 'true';
+        }
+        else if (def.typeName === 'ZodArray') {
+            // Generate example for array element type
+            const elementType = def.type;
+            if (elementType) {
+                const elementExample = this.generateExampleValue(elementType);
+                if (elementExample) {
+                    return `[${elementExample}]`;
+                }
+            }
+            return '[]';
+        }
+        else if (def.typeName === 'ZodObject') {
+            // Generate example object with its properties
+            if ('shape' in zodType) {
+                const shape = zodType.shape;
+                const properties = [];
+                // Limit properties to avoid too verbose examples
+                let count = 0;
+                for (const [key, value] of Object.entries(shape)) {
+                    if (value && typeof value === 'object' && '_def' in value) {
+                        const zodValue = value;
+                        const exampleValue = this.generateExampleValue(zodValue);
+                        const description = this.getParameterDescription(zodValue);
+                        if (exampleValue !== null) {
+                            let propertyLine = `${key}: ${exampleValue}`;
+                            if (description) {
+                                propertyLine += ` // ${description}`;
+                            }
+                            properties.push(propertyLine);
+                            count++;
+                        }
+                    }
+                }
+                if (properties.length > 0) {
+                    return `{ ${properties.join(', ')} }`;
+                }
+            }
+            return '{}';
+        }
+        else if (def.typeName === 'ZodOptional') {
+            return this.generateExampleValue(def.innerType);
+        }
+        else if (def.typeName === 'ZodDefault') {
+            // For defaults, show the example structure of the inner type if it's complex, otherwise show default
+            const innerExample = this.generateExampleValue(def.innerType);
+            const defaultValue = def.defaultValue();
+            // If the default is an empty array but the inner type is complex, show example
+            if (Array.isArray(defaultValue) &&
+                defaultValue.length === 0 &&
+                innerExample &&
+                innerExample !== '[]') {
+                return `${innerExample} // example for array`;
+            }
+            // If the default is a complex object and we have a meaningful inner example, show structure
+            if (typeof defaultValue === 'object' &&
+                defaultValue !== null &&
+                !Array.isArray(defaultValue) &&
+                innerExample &&
+                innerExample !== '{}' &&
+                innerExample.includes(':') // Has properties
+            ) {
+                return `${innerExample} // structure`;
+            }
+            // If the inner type is an enum with multiple options, show the enum options instead of just default
+            if (def.innerType &&
+                def.innerType._def &&
+                def.innerType._def.typeName === 'ZodEnum') {
+                return innerExample; // This will include the enum options
+            }
+            // If the inner type is ZodOptional containing an enum, drill down further
+            if (def.innerType &&
+                def.innerType._def &&
+                def.innerType._def.typeName === 'ZodOptional') {
+                const optionalInner = def.innerType._def.innerType;
+                if (optionalInner &&
+                    optionalInner._def &&
+                    optionalInner._def.typeName === 'ZodEnum') {
+                    return this.generateExampleValue(optionalInner); // Generate example for the enum
+                }
+            }
+            return `${JSON.stringify(defaultValue)} // default`;
+        }
+        else if (def.typeName === 'ZodEnum') {
+            // Show all enum options, not just the first one
+            const enumValues = def.values;
+            if (enumValues.length > 1) {
+                // Show first value as primary with all options listed
+                return `"${enumValues[0]}" // options: ${enumValues.map((v) => `"${v}"`).join(', ')}`;
+            }
+            return `"${enumValues[0]}"`;
+        }
+        else if (def.typeName === 'ZodDiscriminatedUnion') {
+            // For discriminated unions, generate a proper example object from the first option
+            const options = def.options;
+            if (options.length > 0) {
+                const firstOption = options[0];
+                if (firstOption &&
+                    typeof firstOption === 'object' &&
+                    '_def' in firstOption &&
+                    'shape' in firstOption) {
+                    const firstOptionDef = firstOption._def;
+                    if (firstOptionDef.typeName === 'ZodObject') {
+                        const shape = firstOption.shape;
+                        const properties = [];
+                        for (const [key, value] of Object.entries(shape)) {
+                            if (value && typeof value === 'object' && '_def' in value) {
+                                const zodValue = value;
+                                const exampleValue = this.generateExampleValue(zodValue);
+                                if (exampleValue !== null) {
+                                    properties.push(`${key}: ${exampleValue}`);
+                                }
+                            }
+                        }
+                        if (properties.length > 0) {
+                            return `{ ${properties.join(', ')} }`;
+                        }
+                    }
+                }
+            }
+            return '"first_option" // discriminated union';
+        }
+        else if (def.typeName === 'ZodLiteral') {
+            return JSON.stringify(def.value);
+        }
+        else if (def.typeName === 'ZodRecord') {
+            // For records, show an example with a key-value pair
+            const valueType = def.valueType;
+            if (valueType) {
+                const valueExample = this.generateExampleValue(valueType);
+                if (valueExample) {
+                    return `{ "example_key": ${valueExample} } // record/object with string keys`;
+                }
+            }
+            return '{} // record/object with string keys';
+        }
+        return null;
+    }
+    toCamelCase(str) {
+        return str.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+    }
+    toPascalCase(str) {
+        const camelCase = this.toCamelCase(str);
+        return camelCase.charAt(0).toUpperCase() + camelCase.slice(1);
+    }
+}
+//# sourceMappingURL=get-bubble-details-tool.js.map