npm package: @pindownai/mastra-pindown
Description: Mastra workflow integration for Pindown.ai with Firebase Realtime Database PubSub
Author: Pindown.ai
Latest version: 0.1.3

# @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

```bash
npm install @pindownai/mastra-pindown
```

## Usage

### 1. Initialize

```typescript
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

```typescript
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

```typescript
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:**
```json
{
  "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:

```typescript
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