NPM Package

Integrate MindStudio's AI Workers into your Node.js projects.

The MindStudio NPM Package is your toolkit for integrating AI-powered workflows seamlessly into any application. This client library offers type-safe interfaces to help you execute MindStudio AI Workers with ease and confidence.

Quick Start

1. Install the Package

npm install mindstudio

2. Get Your 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

Generate type definitions for type-safe usage:

# With API key in environment
npx mindstudio sync

# With explicit API key
npx mindstudio sync --key your-api-key

# From existing config (CI environments)
npx mindstudio sync --offline

test

Test a workflow from the command line:

npx mindstudio test --worker myWorker --workflow generateText --input '{"prompt":"Hello"}'

list

List available workers and workflows:

# List from existing configuration
npx mindstudio list

# List from API (if no configuration exists)
npx mindstudio list --key your-api-key

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

Option 3: Pass directly to your CLI commands

npx mindstudio sync --key your-api-k

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

"Type-safe workers not available"

Run npx mindstudio sync to generate type definitions

"API key is required"

Ensure MINDSTUDIO_KEY is set in your environment or passed to the constructor

"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

Last updated