Getting Started

Install the SDK

npm install @escalated-dev/plugin-sdk

For TypeScript projects (recommended), also install the TypeScript compiler:

npm install -D typescript

Create your first plugin

All plugins are defined with definePlugin(). Create src/index.ts:

import { definePlugin } from '@escalated-dev/plugin-sdk'

export default definePlugin({
  name: 'my-plugin',
  version: '0.1.0',
  description: 'My first Escalated plugin',

  // Configuration fields — rendered in Admin UI, stored as JSON
  config: [
    { name: 'api_key', label: 'API Key', type: 'password', required: true },
    { name: 'notify_channel', label: 'Notify Channel', type: 'text' },
  ],

  onActivate: async (ctx) => {
    // Runs when the plugin is activated in the Admin UI
    // Set up defaults, seed initial config, etc.
    const config = await ctx.config.all()
    if (!config.notify_channel) {
      await ctx.config.set({ notify_channel: '#support' })
    }
  },

  onDeactivate: async (ctx) => {
    // Runs when the plugin is deactivated — clean up resources
  },

  actions: {
    'ticket.created': async (event, ctx) => {
      const settings = await ctx.config.all()
      if (!settings.api_key) return
      ctx.log.info('New ticket', { id: event.id, title: event.title })
      // Call your external service here...
    },
  },
})

Config fields

The config array defines the settings form shown in the Admin UI. Each field is stored as JSON and accessible via ctx.config.

Type	Renders as	Example use
text	Text input	Domain, channel name
password	Masked input	API tokens, secrets
number	Number input	Timeout values
boolean	Toggle switch	Enable/disable features
select	Dropdown	{ type: 'select', options: [{value, label}] }
multiselect	Multi-select	Event type selection
textarea	Textarea	Templates, message formats
json	Code editor	Complex configuration objects
url	URL input with validation	Webhook URLs, API base URLs

Example with multiple field types:

config: [
  { name: 'bot_token', label: 'Bot Token', type: 'password', required: true },
  { name: 'channel', label: 'Default Channel', type: 'text' },
  { name: 'notify_on', label: 'Notify On', type: 'multiselect', options: [
    { value: 'ticket.created', label: 'New Ticket' },
    { value: 'ticket.assigned', label: 'Assignment' },
    { value: 'reply.created', label: 'New Reply' },
  ]},
  { name: 'enabled', label: 'Enable Notifications', type: 'boolean' },
],

Testing your plugin locally

Install the runtime alongside the SDK:

npm install @escalated-dev/plugin-runtime

Run your plugin against a local Escalated instance by pointing the bridge at your development directory. For Laravel:

# In your Laravel .env
ESCALATED_PLUGIN_PATH=/path/to/your/plugin-project/node_modules

The runtime loads all packages matching @escalated-dev/plugin-* from the configured path. During development you can symlink your plugin into a local node_modules directory and the runtime will pick it up on next restart.

To run the plugin in isolation and inspect JSON-RPC messages:

npx @escalated-dev/plugin-runtime --dev --verbose

The --dev flag enables source maps and detailed error output. The --verbose flag logs every JSON-RPC message to stderr.

Hooks

Hooks are the primary way plugins interact with Escalated's event system. There are two kinds: actions (fire-and-forget) and filters (data transformation).

Actions

Actions are event handlers that run when something happens in Escalated. They are fire-and-forget — the host dispatches the event and does not wait for a meaningful return value. If an action handler throws, the error is logged but does not affect the host.

actions: {
  'ticket.created': async (event, ctx) => {
    const settings = await ctx.config.all()
    await ctx.http.post('https://example.com/notify', {
      json: { text: `New ticket: ${event.title}` },
    })
  },
  'ticket.assigned': async (event, ctx) => {
    ctx.log.info('Ticket assigned', { ticketId: event.id, agentId: event.assignee_id })
  },
},

Default timeout: 30 seconds. If an action handler exceeds this, a warning is logged and the handler is abandoned.

Filters

Filters intercept data as it flows through Escalated and must return a (possibly modified) value. They are chained sequentially — the output of one plugin's filter feeds into the next.

filters: {
  // Shorthand — priority defaults to 10
  'notification.channels': (channels, ctx) => [
    ...channels,
    { id: 'slack', name: 'Slack', icon: 'slack', enabled: true },
  ],

  // Explicit priority — lower runs first
  'ticket.actions': {
    priority: 5,
    handler: (actions, ctx) => [
      ...actions,
      { id: 'create-jira', label: 'Create Jira Issue', icon: 'jira' },
    ],
  },
},

Filter priority and chaining

Filters with lower priority numbers run first (default is 10). When multiple plugins register for the same filter, the output of each feeds into the next:

Plugin A (priority 5):  channels = handler(channels)  → [email, slack]
Plugin B (priority 10): channels = handler(channels)  → [email, slack, sms]
Plugin C (priority 20): channels = handler(channels)  → [email, slack, sms, whatsapp]

Default timeout: 5 seconds. If a filter handler times out, the unmodified value is passed through and a warning is logged.

Plugin-to-plugin communication

Plugins can emit custom actions that other plugins listen to, enabling cross-plugin workflows:

// In the Jira plugin — emit a custom action after creating an issue
actions: {
  'ticket.created': async (event, ctx) => {
    const issue = await createJiraIssue(event)
    // Emit a custom action — other plugins can listen
    await ctx.emit('jira.issue.created', { ticketId: event.id, issueKey: issue.key })
  },
},

// In the Slack plugin — listen to Jira's custom action
actions: {
  'jira.issue.created': async (event, ctx) => {
    await postToSlack(`Jira issue ${event.issueKey} linked to ticket ${event.ticketId}`)
  },
},

Custom hooks must be namespaced with the plugin name prefix (e.g., jira.*, slack.*). The runtime routes ctx.emit() calls to all plugins that have registered a handler for that hook.

Available hooks

Action hooks

Hook	Event data	Description
ticket.created	{ id, title, status, priority, contact_id, department_id }	New ticket submitted
ticket.assigned	{ id, assignee_id, previous_assignee_id }	Agent assigned or reassigned
ticket.status_changed	{ id, status, previous_status }	Status transition
ticket.priority_changed	{ id, priority, previous_priority }	Priority updated
ticket.resolved	{ id, resolved_at }	Ticket marked resolved
ticket.closed	{ id, closed_at }	Ticket closed
ticket.reopened	{ id }	Ticket moved back to active state
reply.created	{ id, ticket_id, author_id, body, is_private }	Reply or internal note added
ticket.escalated	{ id, rule_id }	Ticket escalated by automation rule
sla.warning	{ ticket_id, policy_id, deadline }	Ticket approaching SLA deadline
sla.breached	{ ticket_id, policy_id, breached_at }	SLA deadline missed

Filter hooks

Hook	Value type	Description
notification.channels	Channel[]	Notification channel list (email, SMS, etc.)
ticket.actions	Action[]	Action buttons in the ticket view
ticket.sidebar_tabs	Tab[]	Tabs shown in the ticket sidebar
dashboard.widgets	Widget[]	Available dashboard widgets
reply.body	string	Reply body before sending (e.g., append signatures)

Pages & Components

Plugins can add entirely new admin or agent pages, inject Vue components into existing page slots, and register dashboard widgets — all declared in the plugin definition and auto-registered by the bridge.

Custom pages

Declare pages in the pages array. The bridge reads the plugin manifest at startup and registers an Inertia route for each page automatically.

pages: [
  {
    route: 'settings',           // Mounted at /admin/plugins/{slug}/settings
    component: 'SlackSettings',  // Vue component name from your frontend bundle
    menu: {
      label: 'Slack',
      section: 'admin',          // 'admin' | 'agent'
      position: 80,              // Sidebar position (lower = higher)
      icon: 'slack',
    },
    capability: 'manage_settings', // Required capability to access the page
    layout: 'admin',               // 'admin' | 'agent' | 'public'
  },
],

The bridge auto-generates a route equivalent to:

GET /admin/plugins/slack/settings
→ Inertia::render('Escalated/Plugin/Page', {
    plugin: 'slack',
    component: 'SlackSettings',
    props: <result of GET /settings endpoint>
  })

Capability-based access control

Set capability on any page to restrict access. If the authenticated user does not have the required capability, the bridge returns a 403. Built-in capabilities include manage_settings, escalated-agent, and escalated-admin. Custom capabilities can be registered through the authorization system.

Injecting components into existing pages

Use the components array to inject Vue components into slots on existing Escalated pages, without modifying core templates:

components: [
  {
    page: 'ticket.show',          // The Escalated page to inject into
    slot: 'sidebar',              // The slot within that page
    component: 'SlackThreadPanel',
    props: { pluginSlug: 'slack' }, // Static props passed to the component
    order: 30,                    // Render order within the slot (lower = first)
    capability: 'escalated-agent',
  },
],

Available slots

Page	Slot	Description
ticket.show	sidebar	Ticket detail sidebar panel
ticket.show	actions	Below the ticket action buttons
ticket.show	header	Above the ticket subject
dashboard	top	Top of the dashboard
contacts.show	sidebar	Contact detail sidebar

Dashboard widgets

Widgets appear on the Escalated dashboard. They can include a dynamic badge counter polled by the frontend every 30 seconds:

widgets: [
  {
    component: 'SlackActivityWidget',
    label: 'Slack Activity',
    size: 'half',               // 'full' | 'half' | 'quarter'
    order: 50,
    capability: 'escalated-agent',
    // Optional: badge function polled every 30s
    badge: async (ctx) => {
      const unread = await ctx.store.query('slack_messages', { read: false })
      return unread.length > 0 ? unread.length : null
    },
  },
],

The badge function runs in the plugin process. Return a number to display a counter badge, or null to hide it. The bridge calls the badge endpoint automatically based on the manifest declaration — no manual endpoint registration is needed.

Frontend components (Vue)

Your plugin's Vue components live under frontend/ in your package. The bridge loads frontend/index.js which should export components using defineEscalatedPlugin():

// frontend/index.js
import SlackSettings from './components/SlackSettings.vue'
import SlackThreadPanel from './components/SlackThreadPanel.vue'
import SlackActivityWidget from './components/SlackActivityWidget.vue'

export default defineEscalatedPlugin({
  components: {
    SlackSettings,
    SlackThreadPanel,
    SlackActivityWidget,
  },
})

Components are lazy-loaded — the bridge injects them only on pages where they are declared. Standard Vue 3 Composition API, <script setup>, and the full Escalated UI component library are available inside plugin components.

Endpoints, Webhooks & Cron

Data endpoints

Endpoints expose JSON API routes that your plugin's Vue pages call to fetch or update data. They are declared in the endpoints map using METHOD /path keys. The bridge mounts them at /api/plugins/{slug}{path}.

endpoints: {
  'GET /settings': {
    capability: 'manage_settings',  // Optional access control
    handler: async (ctx) => {
      return await ctx.config.all()
    },
  },
  'PUT /settings': {
    capability: 'manage_settings',
    handler: async (ctx, req) => {
      await ctx.config.set(req.body)
      return { success: true }
    },
  },
  'GET /stats': {
    capability: 'escalated-agent',
    handler: async (ctx, req) => {
      const messages = await ctx.store.query('messages', { status: 'pending' })
      return { pending: messages.length }
    },
  },
},

The req object contains body, params (URL path parameters), query (query string), and headers.

Default timeout: 30 seconds. Exceeding this returns a 504 to the client.

Webhook handlers

Webhooks receive inbound HTTP requests from external services. Unlike endpoints, webhooks are public routes — no Escalated authentication is required. Signature verification is the plugin's responsibility within the handler.

Webhook routes are mounted at /webhooks/plugins/{slug}{path}.

webhooks: {
  'POST /events': async (ctx, req) => {
    // Verify Slack signature
    const signature = req.headers['x-slack-signature']
    if (!verifySlackSignature(signature, req.body)) {
      return { error: 'Invalid signature' }  // Bridge returns 401
    }

    const payload = req.body
    if (payload.type === 'url_verification') {
      // Respond to Slack's challenge during webhook setup
      return { challenge: payload.challenge }
    }

    // Handle the event asynchronously
    if (payload.event?.type === 'message') {
      await ctx.store.insert('slack_messages', {
        channel: payload.event.channel,
        text: payload.event.text,
        ts: payload.event.ts,
        read: false,
      })
    }

    return { ok: true }
  },
  'POST /interactions': async (ctx, req) => {
    // Handle Slack interactive components
    const interaction = JSON.parse(req.body.payload)
    // ...
  },
},

Default timeout: 60 seconds. Exceeding this returns a 504 to the external caller.

Cron schedules

Cron tasks run on a schedule managed by the bridge. Use the every: prefix with a duration unit:

cron: {
  'every:1h': async (ctx) => {
    // Runs every hour — sync data, send digests, clean up state, etc.
    const pending = await ctx.store.query('messages', { status: { $in: ['pending', 'failed'] } })
    for (const msg of pending) {
      await retryDelivery(msg, ctx)
    }
  },
  'every:1d': async (ctx) => {
    // Runs once daily — generate reports, purge old records, etc.
    const cutoff = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString()
    const old = await ctx.store.query('audit_log', { created_at: { $lt: cutoff } })
    for (const entry of old) {
      await ctx.store.delete('audit_log', entry.id)
    }
  },
},

Supported intervals: every:1m, every:5m, every:15m, every:30m, every:1h, every:6h, every:12h, every:1d, every:1w.

Default timeout: 300 seconds (5 minutes). If a cron task exceeds this, the error is logged and the task is marked as failed. The next scheduled run will still execute normally.

Cron tasks receive a ctx object identical to action handlers, but ctx.currentUser() returns null since there is no authenticated user in a scheduled context.

Context API

Every hook handler, endpoint, webhook, and cron task receives a ctx (PluginContext) object. When running in subprocess mode, ctx.* calls are translated to JSON-RPC requests back to the host framework. When running on AdonisJS (in-process mode), they call the native ORM directly. The interface is identical in both modes.

ctx.config

Reads and writes the plugin's configuration, as defined in the config array and managed through the Admin UI.

// Read all config values
const settings = await ctx.config.all()
// → { bot_token: 'xoxb-...', channel: '#support' }

// Read a single key
const token = await ctx.config.get('bot_token')

// Write one or more values (merges with existing config)
await ctx.config.set({ channel: '#general', enabled: true })

Configuration is stored as JSON per plugin in the host database and is scoped to the plugin.

ctx.store

Plugin-scoped key-value document store for persistent plugin state (e.g., Jira issue links, message queues, audit logs). Backed by a single escalated_plugin_store table across all plugins, indexed on (plugin, collection, key).

// Insert a record (auto-generated key)
const link = await ctx.store.insert('jira_links', {
  ticket_id: 123,
  issue_key: 'PROJ-456',
  created_at: new Date().toISOString(),
})

// Read by key
const link = await ctx.store.get('jira_links', '507f1f77bcf86cd799439011')

// Update by key
await ctx.store.update('jira_links', link.id, { synced: true })

// Delete by key
await ctx.store.delete('jira_links', link.id)

// Query with filters
const links = await ctx.store.query('jira_links', { ticket_id: 123 })

// Query with operators and ordering
const recent = await ctx.store.query(
  'audit_log',
  { created_at: { $gt: '2025-01-01' } },
  { limit: 100, orderBy: 'created_at', order: 'desc' }
)

Supported filter operators: $gt, $gte, $lt, $lte, $ne, $in, $nin. Equality filters use plain values (no operator prefix).

The bridge translates filters into native JSON column queries for MySQL, PostgreSQL, and SQLite.

ctx.http

Outbound HTTP client for calling external APIs. Runs in-process inside the plugin (not proxied via JSON-RPC). Wraps fetch() with retry, timeout, and structured error handling.

// GET request
const res = await ctx.http.get('https://api.example.com/data', {
  headers: { Authorization: `Bearer ${token}` },
})

// POST with JSON body
const res = await ctx.http.post('https://slack.com/api/chat.postMessage', {
  headers: { Authorization: `Bearer ${botToken}` },
  json: { channel: '#support', text: 'Hello from Escalated' },
})

// PUT and DELETE
await ctx.http.put('https://api.example.com/resource/1', { json: { status: 'done' } })
await ctx.http.delete('https://api.example.com/resource/1')

The host has no visibility into outbound HTTP calls — plugins make external API calls directly.

ctx.broadcast

Real-time broadcast to connected clients via the host WebSocket infrastructure (Laravel Echo, etc.).

// Broadcast to a named channel
await ctx.broadcast.toChannel('slack-activity', 'new-message', { text: 'Hello', ts: '...' })

// Broadcast to a specific user
await ctx.broadcast.toUser(userId, 'plugin.notification', { message: 'Sync complete' })

// Broadcast to all users watching a ticket
await ctx.broadcast.toTicket(ticketId, 'jira.linked', { issueKey: 'PROJ-123' })

ctx.log

Structured logging that writes to the host's log system (Laravel Log, Python logging, Rails logger, etc.).

ctx.log.info('Notification sent', { channel: '#support', ts: '1234567890.123' })
ctx.log.warn('Rate limit approaching', { remaining: 10, resetAt: '...' })
ctx.log.error('Delivery failed', { error: err.message, attempt: 3 })
ctx.log.debug('Raw payload', { body: req.body })

ctx.emit

Emit a custom action for plugin-to-plugin communication. The runtime routes the event to all plugins that have registered an action handler for the given hook name.

await ctx.emit('jira.issue.created', { ticketId: event.id, issueKey: 'PROJ-123' })

Custom hook names must be namespaced with the emitting plugin's name (e.g., jira.*).

ctx.currentUser

Returns the authenticated Escalated user in the current request context, or null in webhook handlers and cron tasks.

const user = await ctx.currentUser()
if (user) {
  ctx.log.info(`Request from agent ${user.id}`)
}

Data repositories

These repositories proxy to the host ORM via JSON-RPC (or direct ORM calls on AdonisJS).

ctx.tickets

const ticket = await ctx.tickets.find(123)
const open = await ctx.tickets.query({ status: 'open', department_id: 5 })
const ticket = await ctx.tickets.create({ title: 'Help needed', contact_id: 42 })
await ctx.tickets.update(123, { status: 'resolved' })

ctx.replies

const reply = await ctx.replies.find(456)
const replies = await ctx.replies.query({ ticket_id: 123 })
await ctx.replies.create({ ticket_id: 123, body: 'Thanks for reaching out!', is_private: false })

ctx.contacts

const contact = await ctx.contacts.find(42)
const contact = await ctx.contacts.findByEmail('user@example.com')
const contact = await ctx.contacts.create({ name: 'Jane Doe', email: 'jane@example.com' })

ctx.tags

const all = await ctx.tags.all()
const tag = await ctx.tags.create({ name: 'billing' })

ctx.departments

const all = await ctx.departments.all()
const dept = await ctx.departments.find(3)

ctx.agents

const all = await ctx.agents.all()
const agent = await ctx.agents.find(7)

Timeouts

All ctx.* calls have a 10-second default timeout. If the host does not respond in time, the promise rejects with a TimeoutError. Design your handlers to fail gracefully when context calls time out.

Framework Bridges

Each framework runs plugins through a thin bridge that handles subprocess management, route registration, and context proxying. This page documents the bridge configuration and behavior for each framework.

How bridges work

Escalated plugins run in a shared Node.js subprocess communicating with the host framework over JSON-RPC 2.0 via stdio. The bridge package spawns and manages this process, reads the plugin manifest, registers routes and menu items, and proxies all ctx.* calls (database queries, config reads, broadcasts) back to the native ORM.

Host Framework              Plugin Process (Node.js)
┌──────────────────┐  JSON-RPC  ┌──────────────────────┐
│ Bridge Package   │◄──────────►│ Plugin Runtime       │
│                  │   stdio    │                      │
│ - Spawn runtime  │            │ ┌──────────────────┐ │
│ - Register routes│            │ │ Slack Plugin    │ │
│ - Proxy ctx.*    │            │ │ Jira Plugin     │ │
│ - Handle events  │            │ │ ... more        │ │
└──────────────────┘            │ └──────────────────┘ │
                                └──────────────────────┘

Plugins declare what they need in a manifest (plugin.json), and the bridge reads this at startup to register routes, menu items, permissions, and event subscriptions automatically — no manual wiring required.

Plugin store table

Every Escalated installation has a shared escalated_plugin_store table (regardless of framework) that persists plugin configuration and metadata:

Column	Type	Purpose
id	int	Primary key
slug	string	Plugin identifier (must be unique)
name	string	Display name
description	string	Short description
enabled	boolean	Whether the plugin is active
config	json	Plugin settings (key-value pairs)
manifest	json	Cached plugin manifest
created_at	timestamp	Installation time
updated_at	timestamp	Last modified time

Configuration values are stored as JSON and accessed in plugins via ctx.config.get() and ctx.config.set(). The Admin UI renders config fields based on the config array in your plugin definition.

---

Laravel Bridge

Package: escalated/plugin-bridge (Composer)

The Laravel bridge spawns the Node.js plugin runtime as a subprocess managed by the service container. It communicates with the runtime via JSON-RPC over stdio.

Installation

composer require escalated/plugin-bridge
php artisan vendor:publish --provider="Escalated\PluginBridge\PluginBridgeServiceProvider"

Configuration

Configuration is set in config/escalated.php:

'plugins' => [
    // Path where npm packages are installed
    'path' => env('ESCALATED_PLUGIN_PATH', base_path('node_modules')),

    // Enable or disable plugin support
    'enabled' => env('ESCALATED_PLUGINS_ENABLED', true),

    // Node.js executable (useful if not in PATH)
    'node_binary' => env('ESCALATED_NODE_BIN', 'node'),

    // Plugin runtime log level
    'log_level' => env('ESCALATED_PLUGIN_LOG_LEVEL', 'info'),
],

Enabling plugins

Set in your .env:

ESCALATED_PLUGINS_ENABLED=true
ESCALATED_PLUGIN_PATH=/path/to/node_modules

If ESCALATED_PLUGINS_ENABLED=false, the bridge won't spawn the runtime and all plugin hooks are skipped — useful for testing or disabling plugins without uninstalling them.

Dual dispatch

The Laravel bridge implements dual dispatch: when a plugin emits an action (e.g., ctx.broadcast('ticket.created')), the bridge both:

1. Broadcasts to active connections via Laravel's broadcast() helper (WebSocket, Server-Sent Events)
2. Queues job to Escalated's job queue for persistence and reliable delivery

This ensures UI updates are immediate (real-time) while background tasks are resilient.

// In your Laravel event listener
Event::listen(TicketCreated::class, function ($event) {
    // Bridge automatically broadcasts to plugin subscribers
    // and queues any plugin actions
});

---

Django Bridge

Package: escalated-plugin-bridge (PyPI)

The Django bridge spawns the Node.js runtime as a subprocess and manages it via the Django application lifecycle.

Installation

pip install escalated-plugin-bridge

Add to INSTALLED_APPS in settings.py:

INSTALLED_APPS = [
    # ...
    'escalated',
    'escalated_plugin_bridge',
]

Configuration

Configuration is set in settings.py:

ESCALATED_PLUGINS = {
    'enabled': os.environ.get('ESCALATED_PLUGINS_ENABLED', True),

    # Path where npm packages are installed
    'path': os.environ.get('ESCALATED_PLUGIN_PATH', os.path.join(BASE_DIR, 'node_modules')),

    # Node.js executable
    'node_binary': os.environ.get('ESCALATED_NODE_BIN', 'node'),

    # Plugin runtime log level
    'log_level': os.environ.get('ESCALATED_PLUGIN_LOG_LEVEL', 'info'),
}

SDK_ENABLED setting

The SDK_ENABLED flag controls whether the bridge spawns the runtime:

# settings.py
ESCALATED_PLUGINS['enabled'] = True  # Enable plugins

When disabled, plugin hooks are skipped but configured plugins remain in the database — useful for temporary deactivation.

# .env
ESCALATED_PLUGINS_ENABLED=true
ESCALATED_PLUGIN_PATH=/path/to/node_modules

---

AdonisJS Bridge

Package: @escalated-dev/plugin-bridge (npm)

AdonisJS is unique: plugins load in-process directly into the main application. No subprocess, no JSON-RPC, no interprocess overhead.

Installation

npm install @escalated-dev/plugin-bridge

Register the provider in start/app.ts:

import { configure } from '@adonisjs/core/app'

export const plugins = await configure({
  providers: [
    () => import('@escalated-dev/plugin-bridge/providers/plugin_provider'),
  ],
})

In-process mode

In-process plugins have full access to the AdonisJS application instance. They load directly via ES modules:

// In your plugin src/index.ts
import { definePlugin } from '@escalated-dev/plugin-sdk'

export default definePlugin({
  name: 'my-plugin',

  // AdonisJS plugins can import native modules directly
  onActivate: async (ctx) => {
    // ctx.app is the AdonisJS application instance
    const db = ctx.app.container.make('lucid.db')
    // Can query directly without JSON-RPC serialization
  },
})

Native context & zero overhead

The PluginContext interface is identical across all frameworks, but AdonisJS's implementation calls Lucid ORM directly instead of proxying via JSON-RPC. This means:

• Zero serialization overhead — no JSON encoding/decoding of ORM calls
• Direct database access — use Lucid models and query builder natively
• Full transaction support — participate in application transactions
• Type safety — TypeScript types are preserved end-to-end

// AdonisJS plugin — direct ORM access
const tickets = await ctx.models.Ticket.where('status', 'open').fetch()

// Same code in Laravel/Django/Rails gets serialized to JSON-RPC
// but produces identical results

Plugin behavior is guaranteed identical across all modes — the context contract ensures this.

---

Rails Bridge

Package: escalated-plugin-bridge (RubyGems)

The Rails bridge spawns the Node.js plugin runtime and manages its lifecycle via Rails initializers and job queue integration.

Installation

bundle add escalated-plugin-bridge

Configuration

Configuration is set in config/escalated.yml or via environment variables:

# config/initializers/escalated.rb
Escalated::PluginBridge.configure do |config|
  # Path where npm packages are installed
  config.plugin_path = ENV.fetch('ESCALATED_PLUGIN_PATH', Rails.root.join('node_modules').to_s)

  # Enable or disable plugin support
  config.enabled = ENV.fetch('ESCALATED_PLUGINS_ENABLED', true)

  # Node.js executable
  config.node_binary = ENV.fetch('ESCALATED_NODE_BIN', 'node')

  # Plugin runtime log level
  config.log_level = ENV.fetch('ESCALATED_PLUGIN_LOG_LEVEL', 'info')
end

sdk_plugins_enabled setting

The sdk_plugins_enabled setting controls whether the bridge spawns the runtime. When set to false, plugins are loaded from the database but the runtime is not spawned — useful for disabling plugins without removing them:

# .env
ESCALATED_PLUGINS_ENABLED=true
ESCALATED_PLUGIN_PATH=/path/to/node_modules

Or in code:

Escalated::PluginBridge.configure do |config|
  config.enabled = ENV['ESCALATED_PLUGINS_ENABLED'].present?
end

Event handling

The Rails bridge uses Active Job to queue plugin actions and ensure reliable delivery:

# In your Rails event
EscalatedBus.publish('ticket.created', ticket_data)

# Bridge queues this to ActiveJob, which persists to the job queue
# and the runtime processes it asynchronously

Broadcasts are sent immediately via ActionCable, while durable actions go to the job queue.

Publishing

Package structure

Escalated plugins are standard npm packages. The recommended structure separates backend logic (src/) from Vue frontend components (frontend/):

@escalated-dev/plugin-slack/
├── package.json
├── src/
│   ├── index.ts          # definePlugin() — backend definition (main entry)
│   ├── client.ts         # External API client (e.g., SlackClient)
│   └── handlers.ts       # Shared handler logic
├── frontend/
│   ├── index.js          # defineEscalatedPlugin() — Vue frontend entry
│   └── components/
│       ├── SlackSettings.vue
│       ├── SlackThreadPanel.vue
│       └── SlackActivityWidget.vue
└── README.md

package.json should declare both entry points:

{
  "name": "@escalated-dev/plugin-slack",
  "version": "0.1.0",
  "main": "dist/index.js",
  "exports": {
    ".": "./dist/index.js",
    "./frontend": "./frontend/index.js"
  },
  "scripts": {
    "build": "tsc",
    "dev": "tsc --watch"
  },
  "peerDependencies": {
    "@escalated-dev/plugin-sdk": "^1.0.0"
  }
}

Naming convention

Official and community Escalated plugins follow the @escalated-dev/plugin-{name} naming convention on npm. The runtime auto-discovers all packages installed under node_modules/@escalated-dev/plugin-*, so naming your package correctly is all that is required for it to be loaded.

# Publish to npm under the @escalated-dev scope (official plugins)
npm publish --access public

# Community plugins can use any scope but should follow the plugin-* naming:
# @your-org/plugin-my-integration

Community plugins using a different npm scope can be loaded by adding the scope to the runtime's discovery configuration.

Backend entry point (src/index.ts)

The default export of src/index.ts must be the definePlugin() call. This is what the runtime loads and introspects for the manifest.

import { definePlugin } from '@escalated-dev/plugin-sdk'
import { SlackClient } from './client'
import { handleTicketCreated } from './handlers'

export default definePlugin({
  name: 'slack',
  version: '0.1.0',
  // ...
  actions: {
    'ticket.created': handleTicketCreated,
  },
})

Frontend entry point (frontend/index.js)

The frontend/index.js entry exports Vue components using defineEscalatedPlugin(). The bridge loads this file via the Inertia asset pipeline.

import SlackSettings from './components/SlackSettings.vue'
import SlackThreadPanel from './components/SlackThreadPanel.vue'

export default defineEscalatedPlugin({
  components: {
    SlackSettings,
    SlackThreadPanel,
  },
})

Component names must match exactly what is declared in the pages[].component and components[].component fields of definePlugin().

Vue components

Plugin Vue components have access to the full Escalated UI component library and Vue 3 Composition API. Use <script setup> for the cleanest syntax:

<template>
  <EscalatedCard title="Slack Settings">
    <form @submit.prevent="save">
      <EscalatedInput v-model="form.channel" label="Default Channel" />
      <EscalatedButton type="submit">Save</EscalatedButton>
    </form>
  </EscalatedCard>
</template>

<script setup>
import { ref } from 'vue'
import { usePluginEndpoint } from '@escalated-dev/plugin-sdk/vue'

const { data, save } = usePluginEndpoint('slack', '/settings')
const form = ref({ channel: data.value?.channel ?? '' })
</script>

TypeScript compilation

Compile your backend before publishing:

npm run build
# Outputs to dist/

Add a tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "declaration": true
  },
  "include": ["src"]
}

Do not compile the frontend/ directory — Vue components are consumed as source by the Inertia build pipeline.

Migration from the PHP plugin system

If you are converting an existing PHP plugin to the SDK format, the following mapping covers the most common patterns:

PHP	SDK equivalent
escalated_add_action('ticket.created', $handler)	actions: { 'ticket.created': handler }
escalated_apply_filters('notification.channels', $channels)	filters: { 'notification.channels': handler }
escalated_register_page(...)	pages: [{ route, component, menu }]
escalated_add_page_component(...)	components: [{ page, slot, component }]
escalated_register_dashboard_widget(...)	widgets: [{ component, label, size }]
escalated_broadcast(...)	ctx.broadcast.toChannel(...)
escalated_do_action('plugin.*', ...)	ctx.emit('plugin.*', ...)
Support/Config.php JSON storage	ctx.config
Custom JSON file storage	ctx.store
Services/*Client.php	TypeScript class in src/client.ts using ctx.http