AI Scribe Plugin SDK

The AI Scribe Plugin SDK enables developers to create React-based plugins that render document outputs inside secure iframe sandboxes.

Features

• 🔒 Secure Iframe Execution - Plugins run in isolated sandboxes
• 📡 postMessage Communication - Safe communication between host and plugin
• ⚛️ React Integration - Full React support with hooks and context
• 🎨 Auto-resize - Automatic iframe resizing based on content
• 🔧 TypeScript Support - Complete TypeScript typings
• 🚀 Easy Development - Simple API for quick plugin creation

Installation

npm install @aiscribe/web-sdk react react-dom

Quick Start

1. Create a Plugin Component

import React from "react"
import { usePluginData, useAutoResize } from "@aiscribe/web-sdk"

const MyPlugin = () => {
  const pluginData = usePluginData()
  useAutoResize() // Automatically resize iframe to fit content

  if (!pluginData) {
    return <div>Loading...</div>
  }

  return (
    <div>
      <h1>{pluginData.templateName}</h1>
      <pre>{JSON.stringify(pluginData.transformerOutput, null, 2)}</pre>
    </div>
  )
}

2. Initialize Your Plugin

import React from "react"
import { createRoot } from "react-dom/client"
import { PluginProvider, type PluginLifecycle } from "@aiscribe/web-sdk"
import MyPlugin from "./MyPlugin"

const lifecycle: PluginLifecycle = {
  init: async (config) => {
    console.log("Plugin initialized:", config)
  },
  render: async (data) => {
    console.log("Rendering with data:", data)
  },
  cleanup: async () => {
    console.log("Plugin cleanup")
  },
}

document.addEventListener("DOMContentLoaded", () => {
  const container = document.getElementById("root")
  if (container) {
    const root = createRoot(container)
    root.render(
      <PluginProvider lifecycle={lifecycle}>
        <MyPlugin />
      </PluginProvider>
    )
  }
})

Available Hooks

usePluginData()

Access the data sent from the host application.

const pluginData = usePluginData()
// Returns: PluginData | null

usePluginConfig()

Access the plugin configuration.

const config = usePluginConfig()
// Returns: PluginConfig | null

usePluginResize()

Manually trigger iframe resize.

const requestResize = usePluginResize()
requestResize(500) // Resize to specific height
requestResize() // Auto-calculate height

useAutoResize()

Automatically resize iframe when content changes.

useAutoResize() // Observe all changes
useAutoResize([dependency1, dependency2]) // Observe specific dependencies

usePluginReady()

Track plugin initialization and render state.

const { isReady, hasRendered } = usePluginReady()

Plugin Lifecycle

Every plugin must implement the PluginLifecycle interface:

interface PluginLifecycle {
  init: (config: PluginConfig) => void | Promise<void>
  render: (data: PluginData) => void | Promise<void>
  cleanup?: () => void | Promise<void>
}

Data Types

PluginData

Data received from the host application:

interface PluginData {
  templateId: string
  templateName: string
  transformerOutput: TransformerOutput
  metadata?: Record<string, any>
}

TransformerOutput

The transformed data from document processing:

interface TransformerOutput {
  specType: string
  data: Record<string, any>
}

Building Your Plugin

1. Set up your build tooling (webpack, vite, etc.)
2. Configure to output a single HTML file with embedded JS
3. Upload the built plugin to AI Scribe
4. The plugin will be processed by the AI Scribe builder service

Example Package Structure

my-plugin/
├── src/
│   ├── index.tsx
│   └── MyPlugin.tsx
├── public/
│   └── index.html
├── package.json
├── webpack.config.js
└── tsconfig.json

Examples

See the examples/ directory for complete plugin implementations:

• Markdown Key-Value Renderer - Renders transformer outputs as markdown tables

Communication Protocol

The SDK handles secure communication between the host and plugin iframe using postMessage:

Host → Plugin Messages

• PLUGIN_DATA - Sends plugin configuration and data
• RESIZE_REQUEST - Requests plugin to resize
• ERROR - Error notifications

Plugin → Host Messages

• READY - Plugin is initialized and ready
• RESIZE - Request iframe resize
• ERROR - Plugin error notifications

Security

Plugins run in secure iframe sandboxes with:

• No direct DOM access to the host application
• Restricted network access
• Isolated execution context
• Safe postMessage communication only

Development Guidelines

1. Keep plugins focused on a single responsibility
2. Handle loading and error states gracefully
3. Use TypeScript for better development experience
4. Test with various transformer output formats
5. Optimize for performance in iframe context

CLI Support

Use with the AI Scribe CLI:

# Create web plugin
aiscribe-plugin new my-plugin --type web

# Build plugin
cd my-plugin
npm run build

License

MIT