@pindownai/mastra-pindown

Mastra workflow integration for Pindown.ai - Real-time workflow execution updates via HTTP PubSub.

Overview

@pindownai/mastra-pindown wraps your Mastra workflows and publishes execution events to Pindown.ai backend API. The backend validates your API key, counts requests, and writes events to Firebase for real-time frontend subscriptions.

Installation

Requirements:

• Node.js 22.0.0 or higher
• Mastra 1.0.0 or higher

npm install @pindownai/mastra-pindown

Usage

1. Initialize

import { init } from '@pindownai/mastra-pindown';

// Production (defaults to http://api.pindown.ai)
const { createWorkflow, createStep } = init({
  apiKey: 'pk_live_your_api_key_here',
  pinId: 'pin-abc123', // Target pin for updates
  // OR projectId: 'project-xyz' // Alternative to pinId
});

// Local testing (override backendUrl)
const { createWorkflow, createStep } = init({
  apiKey: 'pk_test_your_api_key_here',
  backendUrl: 'http://localhost:8000', // Override for local dev
  pinId: 'pin-abc123',
});

2. Create Workflow

import { z } from 'zod';

const fetchWeather = createStep({
  id: 'fetch-weather',
  description: 'Fetches weather data',
  inputSchema: z.object({ city: z.string() }),
  outputSchema: z.object({ temp: z.number() }),
  execute: async ({ inputData }) => {
    // Your step logic
    return { temp: 25 };
  },
});

const myWorkflow = createWorkflow({
  id: 'weather-workflow',
  inputSchema: z.object({ city: z.string() }),
  outputSchema: z.object({ temp: z.number() }),
})
  .then(fetchWeather);

3. Execute Workflow

const run = await myWorkflow.createRun();
const result = await run.start({ city: 'New York' });
// Events are automatically published to Pindown.ai backend API

How It Works

┌─────────────────┐
│  User's Code    │
│  (Your Server)  │
│                 │
│  Workflow runs  │──┐
│  @mastra/pindown│  │ HTTP POST with API key
│  publishes      │──┼─────────────────┐
└─────────────────┘  │                 │
                     │                 ▼
              ┌──────────────┐
              │ Pindown.ai   │
              │ Backend API  │
              │              │
              │ - Validates  │
              │   API key    │
              │ - Counts     │
              │   requests   │
              │ - Writes to  │
              │   Firebase   │
              └──────┬───────┘
                     │
                     │ Real-time updates
                     ▼
              ┌──────────────┐
              │   Firebase   │
              │  Realtime DB │
              └──────┬───────┘
                     │
                     │ Subscribe
                     ▼
              ┌──────────────┐
              │  Frontend   │
              │  (React)    │
              └──────────────┘

Backend API Endpoint

The package publishes to: POST /api/workflows/events

Headers:

• Authorization: Bearer {apiKey}
• Content-Type: application/json

Body:

{
  "runId": "run-abc123",
  "workflowId": "weather-workflow",
  "event": {
    "type": "step.completed",
    "stepId": "fetch-weather",
    "output": {...},
    "timestamp": 1234567890
  }
}

Frontend Subscription

Your frontend can subscribe to workflow updates using Firebase:

import { ref, onValue } from 'firebase/database';

const eventsRef = ref(db, `workflow_runs/${runId}/events`);
onValue(eventsRef, (snapshot) => {
  const events = snapshot.val();
  // Handle real-time workflow events
});

Security

• ✅ API key validation on every request
• ✅ Request counting for billing/limits
• ✅ Firebase security rules ensure users only see their own runs
• ✅ No direct Firebase access from user's code

License

MIT