Plugin SDK

Cada plugin de Wafle extiende dos capas a la vez: REST y MCP. Si registrás un endpoint REST, Wafle te genera la tool MCP equivalente automáticamente — todo lo que vos escribís queda disponible para que Claude lo use sin glue code.

Status del SDK

Plugin SDK está en beta pública desde v0.4.0. La API puede cambiar entre minor releases hasta v1.0; vamos a marcar breaking changes en el changelog.

Estructura mínima

my-plugin/wafle-plugin.jsonjson

{
  "name": "my-plugin",
  "version": "0.1.0",
  "wafle_compatibility": "^0.4.0",
  "description": "Hello world plugin para Wafle",
  "scopes": ["read"],
  "entry": "index.php"
}

my-plugin/index.phpphp

<?php
/**
 * Plugin Name: My Wafle Plugin
 * Version: 0.1.0
 */

add_action('wafle_register_endpoints', function ($api) {
    $api->register('GET', '/my/hello', function ($req) {
        return ['hello' => $req->get_param('name') ?? 'world'];
    }, [
        'mcp_tool'    => 'my.hello',
        'description' => 'Devuelve un saludo. Útil para test.',
        'input_schema' => [
            'type' => 'object',
            'properties' => [ 'name' => [ 'type' => 'string' ] ],
        ],
    ]);
});

Hooks principales

wafle_register_endpoints — registrar REST + MCP autogen.
wafle_register_mcp_tools — registrar tools que NO mapean a un endpoint REST (ej: tools que orquestan varios endpoints).
wafle_register_resources — registrar recursos MCP custom.
wafle_register_prompts — registrar prompts pre-armados.
wafle_on_order_paid — reaccionar a eventos del core.
wafle_on_product_created, wafle_on_customer_created, etc.
wafle_modify_storefront_meta — alterar SEO meta del storefront managed.
wafle_pixel_extra_event — emitir eventos custom desde server-side.

Registro de tools MCP que no son REST

A veces querés exponer una operación al modelo que no tiene sentido como endpoint REST público (ej: una tool que orquesta tres calls internos):

my-plugin/mcp.phpphp

add_action('wafle_register_mcp_tools', function ($mcp) {
    $mcp->tool('my.report.weekly', [
        'description' => 'Genera y manda por email el reporte semanal con KPIs.',
        'input_schema' => [
            'type' => 'object',
            'properties' => [
                'recipient' => ['type' => 'string', 'format' => 'email'],
                'week_offset' => ['type' => 'integer', 'default' => 0],
            ],
            'required' => ['recipient'],
        ],
        'scopes' => ['orders.read', 'customers.read', 'emails.write'],
        'handler' => function ($args) {
            $report = generate_weekly_report($args['week_offset'] ?? 0);
            wafle_send_email($args['recipient'], 'Weekly KPIs', $report);
            return ['ok' => true, 'period' => $report['period']];
        },
    ]);
});

Resources MCP custom

my-plugin/resources.phpphp

add_action('wafle_register_resources', function ($mcp) {
    $mcp->resource('my-plugin://top-buyers', [
        'name' => 'Top buyers (90 días)',
        'mime_type' => 'application/json',
        'handler' => fn() => json_encode(top_buyers_last_90_days()),
    ]);
});

Reaccionar a eventos del core

my-plugin/hooks.phpphp

add_action('wafle_on_order_paid', function ($order) {
    // Mandar a Slack interno cuando entra una orden > 100k ARS
    if ($order['total'] >= 10000000) { // centavos
        wafle_http_post('https://hooks.slack.com/...', [
            'text' => "Orden grande! ${$order['total']/100} ARS - #{$order['id']}",
        ]);
    }
});

Distribución

Marketplace público — subís tu plugin, lo aprobamos, queda instalable con un click desde el dashboard de cualquier tienda. Cobramos 20% del precio si lo monetizás.
Privado — instalás solo en tus propias tiendas. Sin revisión de marketplace, sin fee. Sube por /admin/account → Plugins privados.
Enterprise — clientes self-host instalan vía CLI: wafle plugin install ./my-plugin.zip.

Testing local

Levantá un Wafle local con wafle dev (CLI gratis) y agregá tu plugin a ./plugins/my-plugin/. El dev server hot-reloadea PHP + regenera la OpenAPI en cada cambio. wafle plugin lint valida schema y compatibility.

Ejemplo end-to-end: “WhatsApp ping”

Plugin que expone una tool MCP whatsapp.ping que le manda un msg al staff cuando entra una orden urgente:

whatsapp-ping/index.phpphp

<?php
/** Plugin Name: WhatsApp Ping */

add_action('wafle_register_mcp_tools', function ($mcp) {
    $mcp->tool('whatsapp.ping', [
        'description' => 'Manda un mensaje de WhatsApp al staff de la tienda.',
        'input_schema' => [
            'type' => 'object',
            'properties' => [
                'message' => ['type' => 'string', 'maxLength' => 500],
                'urgency' => ['type' => 'string', 'enum' => ['low', 'normal', 'high']],
            ],
            'required' => ['message'],
        ],
        'scopes' => ['admin'],
        'handler' => function ($args) {
            $token = wafle_setting('whatsapp.token');
            $to    = wafle_setting('whatsapp.staff_number');
            wafle_http_post("https://graph.facebook.com/v20.0/me/messages", [
                'messaging_product' => 'whatsapp',
                'to' => $to,
                'text' => ['body' => $args['message']],
            ], ['Authorization' => "Bearer $token"]);
            return ['ok' => true];
        },
    ]);
});

add_action('wafle_on_order_paid', function ($order) {
    if ($order['total'] >= 10000000) {
        wafle_mcp_invoke('whatsapp.ping', [
            'message' => "Orden grande #{$order['id']} - $" . ($order['total']/100),
            'urgency' => 'high',
        ]);
    }
});

Siguientes

MCP Server — el catálogo de tools que ya están.
REST API — endpoints del core que tu plugin puede usar.