<div align="center">

🔌 Plugin Delivery

AI Function Call Plugins & Tools for SperaxOS

Live: plugin.delivery

📚 Docs • 🚀 Quick Start • 📦 Templates • 🎨 Plugin Types • 🔧 Development

</div>

---

What Is Plugin Delivery?

The official plugin marketplace and SDK for SperaxOS — a crypto/DeFi-focused AI assistant platform.

| Feature | Description | |---------|-------------| | 📋 Plugin Index | JSON registry of AI-discoverable plugins | | ⚡ Gateway Service | Secure proxy routing function calls to plugin APIs | | 🛠️ SDK | TypeScript SDK for building custom plugins | | 🎨 Templates | 6 starter templates for different plugin types | | 🌍 i18n | 18 languages supported out of the box |

How It Works

User: "What's the price of ETH?"
         │
         ▼
┌─────────────────────────────────────────────────────────┐
│  SperaxOS discovers plugin from plugin.delivery index   │
│  AI generates function call: getPrice(coin: "ethereum") │
│  Gateway routes request to CoinGecko API                │
│  Response rendered in chat (JSON, Markdown, or UI)      │
└─────────────────────────────────────────────────────────┘
         │
         ▼
AI: "ETH is currently trading at $3,450..."

---

Plugin Types

SperaxOS supports 4 distinct plugin types, each optimized for different use cases:

| Type | Rendering | Best For | Complexity | |------|-----------|----------|------------| | Default | Server-rendered JSON → AI formats | Data APIs, lookups | ⭐ Simple | | Markdown | Pre-formatted rich text | Documentation, reports | ⭐ Simple | | Standalone | Full React/HTML app in iframe | Interactive dashboards | ⭐⭐⭐ Advanced | | OpenAPI | Auto-generated from spec | Existing APIs | ⭐⭐ Medium |

Default Plugins

Returns JSON data that the AI formats into natural language.

{
  "ui": {
    "mode": "default"
  }
}

Use when: You have an API that returns structured data and want the AI to explain results conversationally.

Markdown Plugins

Returns pre-formatted Markdown that displays directly in chat.

{
  "ui": {
    "mode": "markdown"
  }
}

Use when: You want full control over formatting — tables, code blocks, headers, etc.

Standalone Plugins (Artifacts)

Embeds a full React/HTML application in an iframe within the chat.

{
  "ui": {
    "mode": "standalone",
    "url": "https://your-plugin.com/ui",
    "height": 400
  }
}

Use when: You need rich interactivity — charts, forms, dashboards, embedded apps.

💡 Standalone plugins are SperaxOS's superpower — they enable experiences beyond what ChatGPT plugins can do.

OpenAPI Plugins

Auto-generated from an OpenAPI 3.x specification. No custom code needed.

{
  "openapi": "https://your-api.com/openapi.json"
}

Use when: You already have an OpenAPI spec for your API.

---

Artifacts, Embeds & Interactive UI

What Are Artifacts?

Artifacts are rich interactive content that plugins can render directly in chat. Unlike plain text responses, artifacts can include:

• 📊 Charts & Visualizations (Chart.js, Recharts, D3)
• 📝 Interactive Forms (Input fields, buttons, selectors)
• 🎮 Mini Applications (Games, calculators, tools)
• 📄 Rich Documents (Formatted reports, tables)

HTML Artifacts

Render raw HTML directly:

// In your plugin API response
return {
  type: 'html',
  content: `
    <div style="padding: 20px;">
      <h2>Price Alert</h2>
      <p>ETH crossed $3,500!</p>
    </div>
  `
};

React Artifacts

Render React components (standalone plugins):

// ui/page.tsx
export default function PriceChart({ data }) {
  return (
    <div className="p-4">
      <LineChart data={data}>
        <Line dataKey="price" stroke="#22c55e" />
      </LineChart>
    </div>
  );
}

iframe Embeds

Embed external content:

{
  "ui": {
    "mode": "standalone",
    "url": "https://tradingview.com/chart/?symbol=BTCUSD",
    "height": 500
  }
}

Function Calls from UI

Standalone plugins can trigger additional function calls:

import { speraxOS } from '@sperax/plugin-sdk/client';

// Trigger a new function call from your UI
speraxOS.triggerFunctionCall({
  name: 'getTokenDetails',
  arguments: { token: 'ETH' }
});

---

Plugin Templates

Get started fast with our official templates:

| Template | Type | Description | Use Case | |----------|------|-------------|----------| | basic | Default | Standard plugin with API endpoint | Simple data lookups | | default | Default | Plugin with settings UI | Configurable plugins | | markdown | Markdown | Rich text output | Formatted reports | | openapi | OpenAPI | Auto-generated from spec | Existing APIs | | settings | Default | Plugin with user preferences | Personalized tools | | standalone | Standalone | Full React application | Interactive dashboards |

Using a Template

# Clone template to new directory
cp -r templates/standalone my-plugin
cd my-plugin

# Install dependencies
bun install

# Start development
bun dev

Template Structure

templates/standalone/
├── public/
│   └── manifest.json    # Plugin manifest
├── src/
│   ├── api/            # API endpoints
│   │   └── index.ts    # Main handler
│   └── ui/             # React UI (standalone only)
│       └── page.tsx    # UI component
├── package.json
└── README.md

---

Quick Start

1. Install the SDK

bun add @sperax/plugin-sdk
# or
npm install @sperax/plugin-sdk

2. Create manifest.json

{
  "$schema": "https://plugin.delivery/schema.json",
  "identifier": "my-crypto-plugin",
  "api": [
    {
      "name": "getPrice",
      "description": "Get cryptocurrency price",
      "url": "https://my-plugin.vercel.app/api/price",
      "parameters": {
        "type": "object",
        "properties": {
          "coin": {
            "type": "string",
            "description": "Coin ID (e.g., bitcoin, ethereum)"
          }
        },
        "required": ["coin"]
      }
    }
  ],
  "meta": {
    "title": "My Crypto Plugin",
    "description": "Get real-time crypto prices",
    "avatar": "🪙",
    "tags": ["crypto", "prices"]
  }
}

3. Create API Handler

// api/price.ts
export default async function handler(req: Request) {
  const { coin } = await req.json();
  
  const res = await fetch(
    `https://api.coingecko.com/api/v3/simple/price?ids=${coin}&vs_currencies=usd`
  );
  const data = await res.json();
  
  return Response.json({
    coin,
    price: data[coin]?.usd,
    timestamp: new Date().toISOString()
  });
}

4. Deploy & Register

# Deploy to Vercel
vercel --prod

# Add to plugin index (submit PR or use Plugin Store)

---

Documentation

| Guide | Description | |-------|-------------| | 📖 Plugin Development Guide | Complete development walkthrough | | 📋 Plugin Manifest Reference | Full manifest.json specification | | 🎨 Plugin Types Guide | Default, Markdown, Standalone explained | | 🔌 SDK API Reference | Client SDK documentation | | 🌐 OpenAPI Integration | Using OpenAPI specs | | 💬 Communication Guide | Plugin ↔ Host messaging | | 🎭 Artifacts Guide | Rich UI components | | ⚡ Complete Guide | Everything in one doc |

---

Available Plugins

Production

| Plugin | Description | Type | API | |--------|-------------|------|-----| | 🪙 CoinGecko Crypto | Prices, trends, market data for 1M+ tokens | OpenAPI | Free | | 🦙 DeFiLlama Analytics | TVL, yields, stablecoins, protocol metrics | Default | Free |

Coming Soon

| Plugin | Description | Status | |--------|-------------|--------| | 📊 DexScreener | DEX pairs, volume, liquidity | Planned | | 💼 Portfolio Tracker | Multi-chain wallet aggregation | Planned | | ⛓️ Chain Explorer | Transaction lookup, gas prices | Planned |

---

Development

Prerequisites

• Bun 1.0+ (recommended) or Node.js 18+
• Git

Setup

# Clone
git clone https://github.com/nirholas/plugin.delivery.git
cd plugins

# Install
bun install

# Dev server
bun dev

Commands

| Command | Description | |---------|-------------| | bun dev | Start local dev server | | bun run format | Generate i18n translations (requires OpenAI API key) | | bun run build | Build plugin index | | bun test | Run tests | | bun lint | Lint code |

---

Adding a New Plugin

Step-by-Step Workflow

⚠️ CRITICAL: You MUST create both files or the build will fail:

1. src/[plugin-name].json - Plugin definition
2. locales/[plugin-name].en-US.json - Locale file (REQUIRED)

1. Create plugin definition in src/[plugin-name].json:

{
  "author": "Your Name",
  "createdAt": "2025-12-29",
  "homepage": "https://example.com",
  "identifier": "my-plugin",
  "manifest": "https://plugin.delivery/my-plugin/manifest.json",
  "meta": {
    "avatar": "🔌",
    "description": "What your plugin does",
    "tags": ["tag1", "tag2"],
    "title": "My Plugin",
    "category": "stocks-finance"
  },
  "schemaVersion": 1
}

2. Create locale file in locales/[plugin-name].en-US.json (REQUIRED):

{
  "meta": {
    "title": "My Plugin",
    "description": "What your p