Creating Scripts (Portal)

A script is executable code that runs in a sandboxed environment on Mirra's infrastructure. This guide covers everything you need to create, test, and publish scripts on the Mirra Store.

By the end of this guide, you will understand how to write scripts in Node.js or Python, configure execution limits, test your code, implement error handling, and publish your script to the marketplace.

What is a script?

A script is custom code that runs on the Mirra platform to automate tasks, process data, and integrate services. Scripts execute in a secure, isolated environment with configurable resource limits.

How scripts work

When you create a script, you define:

1. Execute function - The main function that processes input parameters
2. Runtime - Node.js 18 (JavaScript/TypeScript) or Python 3.11
3. Execution limits - Timeout, memory, and cost constraints
4. Input parameters - The data your script accepts
5. Return value - The results your script produces

Users execute your script through their agents by providing parameters. The platform runs your code, captures the output, and returns the results.

What scripts can do

Scripts are ideal for:

• Data processing - Transform, analyze, or enrich data between formats
• Task automation - Schedule and execute workflows automatically
• Service integration - Connect multiple APIs into a single operation
• Custom logic - Implement business-specific functionality not available in existing services

Prerequisites

Before creating a script, ensure you have:

• Code to automate - A clear understanding of what your script should do
• Runtime knowledge - Familiarity with JavaScript/TypeScript (Node.js) or Python
• Test data - Sample inputs for testing your script
• Error handling plan - How your script should handle invalid inputs or failures

Supported runtimes

The developer portal supports two runtime environments for scripts.

Contact support to request additional packages for your scripts.

Creating a script

Follow these steps to create and publish a script on the Mirra Store.

{
  "name": "Text Analyzer",
  "description": "Analyzes text and provides detailed statistics including word count, sentence count, character count, and readability metrics",
  "runtime": "nodejs18"
}

/**
 * Text analysis script
 * @param {Object} params - Input parameters
 * @param {string} params.text - Text to analyze
 * @returns {Object} Analysis results
 */
async function execute(params) {
  // Validate input
  if (!params.text) {
    throw new Error('text parameter is required');
  }
 
  const text = params.text;
  
  // Analyze text
  const words = text.split(/\s+/).filter(w => w.length > 0);
  const sentences = text.split(/[.!?]+/).filter(s => s.trim());
  const characters = text.length;
 
  // Calculate statistics
  const avgWordLength = words.reduce((sum, w) => sum + w.length, 0) / words.length;
  const avgSentenceLength = words.length / sentences.length;
 
  // Return results
  return {
    summary: {
      wordCount: words.length,
      sentenceCount: sentences.length,
      characterCount: characters,
      averageWordLength: Math.round(avgWordLength * 100) / 100,
      averageSentenceLength: Math.round(avgSentenceLength * 100) / 100
    },
    timestamp: new Date().toISOString()
  };
}
 
module.exports = { execute };

"""
Text analysis script
"""
from typing import Dict, Any
from datetime import datetime
 
def execute(params: Dict[str, Any]) -> Dict[str, Any]:
    """
    Analyze text and return statistics
    
    Args:
        params: Input parameters with 'text' field
        
    Returns:
        Analysis results with statistics
    """
    # Validate input
    if 'text' not in params:
        raise ValueError('text parameter is required')
    
    text = params['text']
    
    # Analyze text
    words = [w for w in text.split() if w]
    sentences = [s.strip() for s in text.split('.') if s.strip()]
    characters = len(text)
    
    # Calculate statistics
    avg_word_length = sum(len(w) for w in words) / len(words) if words else 0
    avg_sentence_length = len(words) / len(sentences) if sentences else 0
    
    # Return results
    return {
        'summary': {
            'wordCount': len(words),
            'sentenceCount': len(sentences),
            'characterCount': characters,
            'averageWordLength': round(avg_word_length, 2),
            'averageSentenceLength': round(avg_sentence_length, 2)
        },
        'timestamp': datetime.utcnow().isoformat()
    }

{
  "config": {
    "timeout": 30,
    "memory": 256,
    "maxCostPerExecution": 0.10,
    "maxExecutionsPerDay": 1000,
    "allowedResources": ["weather-api", "database-connector"]
  }
}

{
  "triggerConfig": {
    "types": ["event"],
    "eventTypes": ["email.received"],
    "sources": ["gmail"]
  }
}

{
  "scriptVariables": [
    {
      "name": "targetChatId",
      "displayName": "Target Telegram Chat",
      "type": "resource_selector",
      "resourceType": "telegram_chat",
      "resourceMethod": "getChats",
      "required": true,
      "description": "Which Telegram chat should receive notifications?",
      "placeholder": "Select a chat...",
      "helpText": "You can choose any chat, group, or channel"
    }
  ]
}

export async function handler(event, scriptContext, mirra) {
  // Access the user-configured variable from event.data
  const chatId = event.data.targetChatId;
  
  // Access standardized event fields
  const emailText = event.event.content.text;  // Works for any event type
  const sender = event.event.actor.name;
  
  // Use configured variable in your logic
  await mirra.resources.call({
    resourceId: 'telegram',
    method: 'sendMessage',
    parameters: {
      chatId: chatId,  // User-configured value
      text: `Email from ${sender}: ${emailText}`
    }
  });
}

{
  "uiConfig": {
    "quickSetupAvailable": true,
    "category": "notification",
    "icon": "📧",
    "flowDescription": "Forwards emails to Telegram in real-time",
    "exampleUseCase": "Get instant notifications when important emails arrive"
  }
}

{
  "name": "Email to Telegram Notifications",
  "description": "Forward incoming emails to a Telegram chat",
  "runtime": "nodejs18",
  "config": {
    "allowedResources": ["gmail", "telegram"],
    "timeout": 30,
    "memory": 128
  },
  "triggerConfig": {
    "types": ["event"],
    "eventTypes": ["email.received"],
    "sources": ["gmail"]
  },
  "scriptVariables": [
    {
      "name": "targetChatId",
      "displayName": "Target Telegram Chat",
      "type": "resource_selector",
      "resourceType": "telegram_chat",
      "resourceMethod": "getChats",
      "required": true,
      "description": "Which Telegram chat should receive email notifications?"
    },
    {
      "name": "includeAttachments",
      "displayName": "Include Attachments",
      "type": "boolean",
      "required": false,
      "default": false,
      "description": "Send email attachments to Telegram",
      "helpText": "Large attachments may fail due to Telegram limits"
    }
  ],
  "uiConfig": {
    "quickSetupAvailable": true,
    "category": "notification",
    "icon": "📧",
    "flowDescription": "Forwards emails to Telegram in real-time"
  }
}

{
  "text": "Hello world! This is a test. Testing is important."
}

{
  "summary": {
    "wordCount": 8,
    "sentenceCount": 3,
    "characterCount": 51,
    "averageWordLength": 5.13,
    "averageSentenceLength": 2.67
  },
  "timestamp": "2025-11-15T12:00:00.000Z"
}

Script structure

Understanding the required structure for scripts helps you write code that works correctly with the platform.

Required function signature

Every script must export an execute function with a specific signature:

async function execute(params) {
  // Your code here
  return result;
}
 
module.exports = { execute };

Input parameters

The params object contains user-provided input data. Always validate parameters before processing to ensure your script handles invalid inputs gracefully.

Example input:

{
  "text": "Sample input text",
  "options": {
    "detailed": true,
    "format": "json"
  }
}

Validation pattern:

// Check required parameters
if (!params.text) {
  throw new Error('text parameter is required');
}
 
// Validate parameter types
if (typeof params.text !== 'string') {
  throw new Error('text parameter must be a string');
}
 
// Provide defaults for optional parameters
const options = params.options || {};
const detailed = options.detailed !== false; // default: true

Return values

Return a JSON-serializable object containing your results. The platform converts your return value to JSON and sends it to the user's agent.

Valid return types:

• Objects (dictionaries)
• Arrays (lists)
• Strings
• Numbers
• Booleans
• null

Example return value:

{
  "status": "success",
  "data": {
    "wordCount": 42,
    "sentenceCount": 3
  },
  "metadata": {
    "executionTime": 123,
    "timestamp": "2025-11-15T12:00:00Z"
  }
}

Invalid return types:

• Functions
• Undefined
• Circular references
• Binary data (use base64 encoding instead)

Error handling

Throw descriptive errors for invalid inputs or execution failures. The platform catches exceptions and returns error messages to users.

// Validate required parameters
if (!params.required) {
  throw new Error('required parameter is missing');
}
 
// Handle risky operations
try {
  const result = riskyOperation(params.data);
  return result;
} catch (error) {
  throw new Error(`Operation failed: ${error.message}`);
}

Version control

The developer portal includes version control for scripts, allowing you to track changes and roll back if needed.

Creating a new version

Save a new version of your script when you make significant changes:

1. Edit your script code in the editor
2. Click "Save New Version" in the toolbar
3. Enter a descriptive commit message:

Fix: Handle empty text input correctly
Add: Character frequency analysis feature
Update: Improve performance by 30%

4. The new version is created and saved

Commit message best practices:

• Start with a prefix: Fix:, Add:, Update:, Remove:
• Be specific about what changed
• Keep messages under 72 characters
• Reference issue numbers if applicable

Viewing version history

View all versions of your script and their changes:

1. Click the "Versions" tab in the editor

2. View the version list with:

   • Version number - Sequential version identifier (v1, v2, v3, etc.)
   • Commit message - Description of changes
   • Timestamp - When the version was created
   • Author - Who created the version

3. Click on a version to view its code

Rolling back to a previous version

Restore a previous version if you need to undo changes:

1. Select the previous version from the version list
2. Click "Restore This Version"
3. Confirm the action in the dialog
4. The selected version becomes the current version

Version control tips:

• Create versions before major changes
• Test thoroughly before creating a new version
• Use descriptive commit messages
• Keep a changelog of significant changes

Testing strategies

Comprehensive testing ensures your script works correctly for all inputs and edge cases.

Unit testing

Test individual functions and logic in isolation:

// Test helper function
function testWordCount() {
  const result = countWords("hello world");
  if (result !== 2) {
    throw new Error(`Expected 2, got ${result}`);
  }
  console.log("✓ Word count test passed");
}
 
// Run tests
testWordCount();

Unit testing best practices:

• Test each function independently
• Use descriptive test names
• Test both success and failure cases
• Verify edge cases and boundary conditions

Integration testing

Test with real data to verify end-to-end functionality:

const testData = {
  text: "Real sample text from production with multiple sentences. This tests actual usage."
};
 
const result = await execute(testData);
console.log("Integration test result:", result);
 
// Verify result structure
if (!result.summary || !result.summary.wordCount) {
  throw new Error("Invalid result structure");
}

Integration testing best practices:

• Use realistic test data
• Test the complete execute function
• Verify result structure and types
• Test with data from actual use cases

Edge case testing

Test boundary conditions and unusual inputs:

// Empty input
try {
  execute({ text: "" });
  console.log("✓ Empty input handled");
} catch (error) {
  console.log("✗ Empty input failed:", error.message);
}
 
// Very long input (stress test)
execute({ text: "word ".repeat(10000) });
 
// Special characters
execute({ text: "!@#$%^&*()" });
 
// Unicode and emojis
execute({ text: "Hello 世界 🌍" });
 
// Missing parameters
try {
  execute({});
  console.log("✗ Should have thrown error for missing params");
} catch (error) {
  console.log("✓ Missing params handled correctly");
}

Edge case testing checklist:

• ✅ Empty strings and arrays
• ✅ Very long inputs (stress testing)
• ✅ Special characters and punctuation
• ✅ Unicode and emoji characters
• ✅ Missing required parameters
• ✅ Invalid parameter types
• ✅ Null and undefined values
• ✅ Extreme numbers (very large, very small, negative)

Publishing your script

Publishing makes your script available to all users in the marketplace.

Pre-publishing checklist

Before publishing, ensure your script meets these requirements:

• ✅ All tests pass successfully
• ✅ Error handling covers all edge cases
• ✅ Execution limits are appropriate
• ✅ Code is well-documented with comments
• ✅ Description clearly explains functionality
• ✅ Examples demonstrate common use cases

Publishing process

1. Review all configuration and code one final time
2. Test with multiple input scenarios
3. Verify execution time and memory usage
4. Click "Publish" in the editor toolbar
5. Confirm publishing in the dialog
6. Your script goes live immediately

After publishing

Once published, your script is immediately available to users:

• ✅ Script appears in marketplace search results
• ✅ Users can view documentation and examples
• ✅ Users can execute your script through their agents
• ✅ Execution tracking begins automatically
• ✅ Users can submit reviews and ratings
• ✅ Revenue tracking starts (for paid scripts)

Monitor your script's performance and user feedback to identify improvements.

Best practices

Follow these best practices to create high-quality, reliable scripts.

Code quality

Write clean, maintainable code that is easy to understand and modify:

• Use descriptive names - Choose clear variable and function names that explain their purpose
• Add comments - Explain complex logic and non-obvious decisions
• Follow conventions - Use language-specific style guides (ESLint for JavaScript, PEP 8 for Python)
• Keep functions focused - Each function should do one thing well
• Avoid duplication - Extract repeated code into reusable functions

Example:

// Good: Descriptive names and clear logic
function calculateAverageWordLength(words) {
  const totalLength = words.reduce((sum, word) => sum + word.length, 0);
  return words.length > 0 ? totalLength / words.length : 0;
}
 
// Bad: Unclear names and purpose
function calc(w) {
  const t = w.reduce((s, x) => s + x.length, 0);
  return w.length > 0 ? t / w.length : 0;
}

Performance optimization

Optimize your code to reduce execution time and memory usage:

• Choose efficient algorithms - Use appropriate data structures and algorithms for your task
• Avoid unnecessary loops - Combine operations when possible
• Cache repeated calculations - Store results of expensive operations
• Process data in batches - Handle large datasets incrementally
• Monitor resource usage - Track execution time and memory consumption

Example:

// Good: Cache expensive calculations
const cache = new Map();
function expensiveOperation(input) {
  if (cache.has(input)) {
    return cache.get(input);
  }
  const result = /* expensive calculation */;
  cache.set(input, result);
  return result;
}
 
// Bad: Recalculate every time
function expensiveOperation(input) {
  return /* expensive calculation */;
}

Security considerations

Protect your script and users from security vulnerabilities:

• Validate all inputs - Check types, ranges, and formats before processing
• Sanitize user data - Remove or escape potentially dangerous content
• Avoid eval() or exec() - Never execute user-provided code
• Don't log sensitive data - Avoid logging passwords, API keys, or personal information
• Use approved packages - Only use packages approved by the platform

Example:

// Good: Validate and sanitize input
function processUserInput(input) {
  if (typeof input !== 'string') {
    throw new Error('Input must be a string');
  }
  const sanitized = input.replace(/[<>]/g, ''); // Remove dangerous characters
  return sanitized;
}
 
// Bad: No validation or sanitization
function processUserInput(input) {
  return input; // Potentially dangerous
}

Error handling best practices

Implement robust error handling to improve user experience:

• Catch all exceptions - Handle both expected and unexpected errors
• Provide helpful messages - Explain what went wrong and how to fix it
• Log errors for debugging - Include context and stack traces in logs
• Don't expose internals - Avoid revealing implementation details in error messages
• Return consistent formats - Use a standard error response structure

Example:

// Good: Descriptive error with context
if (!params.email || !params.email.includes('@')) {
  throw new Error('Invalid email address. Please provide a valid email in the format: user@example.com');
}
 
// Bad: Vague error message
if (!params.email || !params.email.includes('@')) {
  throw new Error('Invalid input');
}

Documentation practices

Document your script to help users understand how to use it:

• Document parameters - Explain what each parameter does and its expected format
• Explain return values - Describe the structure and meaning of return data
• Provide usage examples - Show common use cases with sample inputs and outputs
• List dependencies - Note any required resources or external services
• Include troubleshooting tips - Help users resolve common issues

Troubleshooting

Common issues when creating scripts and their solutions.

Timeout errors

Problem: Your script exceeds the execution time limit.

Solutions:

• Optimize your code - Reduce algorithmic complexity and eliminate unnecessary operations
• Process data incrementally - Handle large datasets in smaller chunks
• Cache expensive operations - Store and reuse results of repeated calculations
• Request higher limits - Contact support to increase timeout limits for your account
• Split into smaller scripts - Break complex operations into multiple scripts

Example optimization:

// Bad: O(n²) complexity
for (let i = 0; i < items.length; i++) {
  for (let j = 0; j < items.length; j++) {
    // comparison
  }
}
 
// Good: O(n) complexity with Set
const itemSet = new Set(items);
for (const item of items) {
  if (itemSet.has(item)) {
    // comparison
  }
}

Memory errors

Problem: Your script runs out of memory.

Solutions:

• Process data in chunks - Handle large datasets incrementally instead of loading everything at once
• Release unused variables - Set large variables to null when no longer needed
• Use efficient data structures - Choose appropriate data structures for your use case
• Stream data - Process data as it arrives instead of buffering everything
• Request more memory - Contact support to increase memory limits

Example:

// Bad: Load everything into memory
const allData = await fetchLargeDataset();
const results = allData.map(process);
 
// Good: Process in chunks
const chunkSize = 1000;
const results = [];
for (let i = 0; i < totalItems; i += chunkSize) {
  const chunk = await fetchChunk(i, chunkSize);
  results.push(...chunk.map(process));
}

Import errors

Problem: Cannot import required packages.

Solutions:

• Use approved packages only - Check the list of available packages for your runtime
• Verify package names - Ensure you're using the correct package name and import syntax
• Contact support - Request new packages to be added to the approved list
• Use built-in modules - Prefer standard library modules when possible

Available packages:

• Node.js: lodash, axios, date-fns, uuid, crypto-js
• Python: requests, pandas, numpy, dateutil, pydantic

Execution errors

Problem: Script fails during execution with unexpected errors.

Solutions:

• Add comprehensive error handling - Catch and handle all possible exceptions
• Validate inputs thoroughly - Check all parameters before processing
• Test with edge cases - Verify your script handles unusual inputs correctly
• Check execution logs - Review logs for detailed error messages and stack traces
• Add defensive programming - Check for null/undefined values before accessing properties

Next steps

Now that you understand how to create scripts, explore these related topics:

• Managing Your Profile - Optimize your developer profile
• Handling Reviews - Engage with users and respond to feedback
• Best Practices - Tips for building successful integrations
• Creating Resources - Build API integrations that your scripts can use

See also

• Core Concepts: Scripts - Understanding scripts in depth
• Examples: Scripts - Working script examples with complete code
• Core Concepts: Script Events - Using event-driven scripts
• Getting Started Guide - Complete developer portal walkthrough
• Developer Portal Introduction - Overview of the developer portal