Skip to content

Latest commit

 

History

History
169 lines (123 loc) · 6.07 KB

plugin-sdk.md

File metadata and controls

169 lines (123 loc) · 6.07 KB

Plugins

Plugin SDK

Escalated supports framework-agnostic plugins built with the Plugin SDK. Plugins are written once in TypeScript and work across all Escalated backends.

Installing Plugins

The plugin bridge is built into escalated-laravel — no additional PHP package required. Install plugins and the runtime via npm:

npm install @escalated-dev/plugin-runtime
npm install @escalated-dev/plugin-slack
npm install @escalated-dev/plugin-jira

Enabling SDK Plugins

// config/escalated.php
'plugins' => [
    'enabled'     => true,
    'sdk_enabled' => true,  // Enable the Node.js bridge
],

How It Works

SDK plugins run as a Node.js subprocess managed by @escalated-dev/plugin-runtime, communicating with Laravel over JSON-RPC 2.0 via stdio. The escalated_do_action() and escalated_apply_filters() helpers dual-dispatch to both legacy PHP plugins and new SDK plugins simultaneously — no changes to existing hook call sites.

Building Your Own Plugin

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

export default definePlugin({
  name: 'my-plugin',
  version: '1.0.0',
  actions: {
    'ticket.created': async (event, ctx) => {
      ctx.log.info('New ticket!', event)
    },
  },
})

Resources

See the detailed Plugin Bridge section below for the full architecture, auto-generated routes, dual dispatch, and store documentation.

Plugin Bridge (SDK Plugins)

Escalated supports a second generation of plugins written in TypeScript using the @escalated-dev/plugin-sdk. These plugins run as a Node.js subprocess managed by @escalated-dev/plugin-runtime and communicate with Laravel over JSON-RPC 2.0 via stdio.

How It Works

Laravel (PHP)                     Plugin Runtime (Node.js)
┌──────────────────────┐  stdio   ┌──────────────────────┐
│ PluginBridge         │◄────────►│ @escalated-dev/       │
│  - spawns subprocess │  JSON-   │   plugin-runtime      │
│  - dispatches hooks  │  RPC 2.0 │  ┌────────────────┐   │
│  - handles ctx.*     │          │  │ Slack Plugin    │   │
│  - mounts routes     │          │  │ Jira Plugin     │   │
└──────────────────────┘          │  │ ...             │   │
                                  │  └────────────────┘   │
                                  └──────────────────────┘

The bridge spawns the runtime lazily on the first hook dispatch and keeps the process alive across requests (one long-lived subprocess per PHP-FPM worker). If the process crashes it is automatically restarted with exponential backoff.

Requirements

  • Node.js 18+
  • @escalated-dev/plugin-runtime installed in your project:
npm install @escalated-dev/plugin-runtime

Install any SDK plugins the same way:

npm install @escalated-dev/plugin-slack @escalated-dev/plugin-jira

Startup Sequence

  1. EscalatedServiceProvider::boot() calls $bridge->boot()
  2. Bridge spawns node node_modules/@escalated-dev/plugin-runtime/dist/index.js
  3. Protocol handshake confirms version compatibility
  4. Bridge fetches the plugin manifest (pages, hooks, endpoints, webhooks)
  5. Routes are registered in Laravel for plugin pages, API endpoints, and webhooks
  6. Runtime is ready to receive hook dispatches

Auto-generated Routes

For each installed SDK plugin the bridge automatically registers:

Category URL Pattern Auth
Admin pages {prefix}/admin/plugins/{slug}/{route} Admin
Data endpoints {prefix}/api/plugins/{slug}/{path} Admin
Webhook endpoints {prefix}/webhooks/plugins/{slug}/{path} None

{slug} is the plugin name with the leading @ dropped and / replaced by -- (@acme/plugin-crm is acme--plugin-crm). Only active plugins answer; the rest are 404.

Dual Dispatch (Backward Compatibility)

The existing escalated_do_action() and escalated_apply_filters() helper functions dispatch hooks to both old PHP plugins and new SDK plugins simultaneously. No changes are required to existing hook call sites.

// This automatically dispatches to PHP plugins AND SDK plugins:
escalated_do_action('ticket.created', $ticket->toArray());

// Same for filters:
$channels = escalated_apply_filters('notification.channels', []);

Plugin Store

SDK plugins can persist data using ctx.store. This is backed by the escalated_plugin_store table:

php artisan vendor:publish --tag=escalated-migrations
php artisan migrate

Configuration

// config/escalated.php
'plugins' => [
    'enabled'         => true,
    'sdk_enabled'     => true,      // Enable the Node.js bridge
    'runtime_command' => 'node node_modules/@escalated-dev/plugin-runtime/dist/index.js',
    'runtime_cwd'     => base_path(), // Working directory for the subprocess
],

Writing SDK Plugins

See the @escalated-dev/plugin-sdk package for the full TypeScript authoring API. A minimal plugin looks like:

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

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

  actions: {
    'ticket.created': async (event, ctx) => {
      const config = await ctx.config.all()
      // ... do something
    },
  },

  endpoints: {
    'GET /settings': { capability: 'manage_settings', handler: async (ctx) => {
      return await ctx.config.all()
    }},
  },
})