MindStudio JavaScript/TypeScript API Library

Client library for MindStudio AI Workers. Easily integrate and execute AI workflows in your applications with type-safe interfaces.

🚀 Quick Start

1. Install the Package

npm install mindstudio

2. Get Your API Key

   • Go to MindStudio Developer Settings
   • Create a new API key

3. Choose Your Usage Pattern

   Option A: Type-Safe Usage (Recommended)

   // Initialize the client
   const client = new MindStudio(process.env.MINDSTUDIO_KEY);
   
   // Execute a workflow
   const { success, result } = await client.workers.myWorker.generateText({
     prompt: "Write a story about a space cat"
   });
   
   // Handle the response
   if (success) {
     console.log(result);
   }

   Option B: Direct Usage

   import { MindStudio } from 'mindstudio';
   
   const client = new MindStudio(process.env.MINDSTUDIO_KEY);
   const { success, result } = await client.run({
     workerId: "your-worker-id",
     workflow: "generateText",
     variables: {
       prompt: "Write a story about a space cat"
     }
   });

Response Format

All workflow executions return a consistent response type:

interface WorkflowResponse<T> {
  success: boolean;
  result?: T;          // The workflow result when success is true
  error?: Error;       // Error details when success is false
  billingCost?: string // Execution cost in credits
}

🛠️ CLI Commands

sync

Synchronize worker configurations and generate type definitions:

npx mindstudio sync

list

List available workers and their workflows:

npx mindstudio list

# Example output:
Available Workers:

• Text Generator (textGenerator)
  └─ Generate Text (generateText)
     ├─ Input: prompt
     └─ Output: text

• Image Generator (imageGenerator)
  └─ Create Image (createImage)
     ├─ Input: description, style
     └─ Output: imageUrl

test

Test a workflow:

npx mindstudio test

🧑‍💻 Team Usage

1. Project Owner:

   npx mindstudio sync
   git add .mindstudio.json
   git commit -m "Add MindStudio configuration"

2. Team Members:

   npm install
   npx mindstudio sync --offline

Optional: Add to package.json for automatic type generation:

{
  "scripts": {
    "postinstall": "npx mindstudio sync --offline"
  }
}

📦 Installation & Setup

Environment Variables

MindStudio requires an API key for authentication. You can provide it in several ways:

# Option 1: In your shell
export MINDSTUDIO_KEY=your-api-key

# Option 2: In your .env file
MINDSTUDIO_KEY=your-api-key
MINDSTUDIO_BASE_URL=https://custom-api-endpoint.com  # Optional

# Option 3: Pass directly to CLI commands
npx mindstudio sync --key your-api-key

For security best practices:

• Never commit API keys to version control
• Add .env to your .gitignore
• Use environment variables in CI/CD environments

TypeScript Configuration

{
  "compilerOptions": {
    "esModuleInterop": true,
    "resolveJsonModule": true
  }
}

❌ Error Handling

// Workflow errors
const { success, result, error } = await client.workers.myWorker.generateText({
  prompt: "Hello"
});

if (!success) {
  console.error('Workflow failed:', error);
  return;
}

// Client errors
try {
  const client = new MindStudio('invalid-key');
} catch (error) {
  if (error instanceof MindStudioError) {
    console.error('Client error:', error.message);
  }
}

💡 Common Issues

1. "Type-safe workers not available"
   Run npx mindstudio sync to generate type definitions

2. "API key is required"
   Ensure MINDSTUDIO_KEY is set in your environment or passed to the constructor

3. "Failed to load configuration"
   Run npx mindstudio sync to create initial configuration

✨ Best Practices

1. API Key Security

   • Store API keys in environment variables
   • Use .env files only for local development
   • Never commit API keys to version control
   • Use secure environment variables in CI/CD

2. Type Safety

   • Use the type-safe pattern when possible
   • Commit .mindstudio.json to version control
   • Run sync after pulling changes

3. Error Handling

   • Always check success before using result
   • Implement proper error handling
   • Use TypeScript for better type safety

License

MIT