webspresso 0.0.99 → 0.0.101

package/plugins/webhooks/index.js

@@ -0,0 +1,263 @@
+/**
+ * Webspresso Webhooks Plugin
+ * Outgoing Webhook Dispatcher, Signature Verification, Event Matching & Admin Inspector
+ * @module plugins/webhooks
+ */
+
+'use strict';
+
+const { generateSecret, safeCompare, signPayload, verifySignature } = require('./crypto');
+const { matchEvent, matchesAnyEvent, normalizeEvents } = require('./matcher');
+const { sendWebhook } = require('./sender');
+const { createWebhookEndpointModel, createWebhookDeliveryModel } = require('./models');
+const { generateWebhooksMigration } = require('./migration-template');
+const { WebhookDispatcher, generateDeliveryId } = require('./dispatcher');
+const { createWebhookApiHandlers } = require('./api-handlers');
+const { generateWebhooksComponent } = require('./admin-component');
+
+/**
+ * Webhooks Plugin Factory
+ * 
+ * @param {Object} [options]
+ * @param {any} [options.db] - Webspresso database or Knex instance
+ * @param {any} [options.knex] - Knex instance
+ * @param {string} [options.endpointsTable='webhook_endpoints']
+ * @param {string} [options.deliveriesTable='webhook_deliveries']
+ * @param {number} [options.maxAttempts=3] - Maximum retry attempts
+ * @param {number} [options.backoffBaseMs=1000] - Base delay for exponential backoff (ms)
+ * @param {number} [options.timeoutMs=10000] - Request timeout (ms)
+ * @param {boolean} [options.wrapPayload=true] - Wrap data in standard event envelope
+ * @param {any} [options.queue] - Webspresso QueueManager instance
+ * @param {Array<Object>} [options.endpoints] - Static in-memory endpoints
+ * @param {string} [options.apiPrefix='/webhooks'] - Admin API prefix
+ * @param {boolean} [options.includeDefaultPage=true] - Register Admin Panel page & menu
+ * @param {string} [options.pageTitle='Webhooks'] - Admin page title
+ * @param {number} [options.menuOrder=92] - Admin sidebar menu order
+ * @returns {Object} Webspresso Plugin Definition
+ */
+function webhooksPlugin(options = {}) {
+  const {
+    endpointsTable = 'webhook_endpoints',
+    deliveriesTable = 'webhook_deliveries',
+    apiPrefix = '/webhooks',
+    includeDefaultPage = true,
+    pageTitle = 'Webhooks',
+    menuOrder = 92,
+  } = options;
+
+  const dispatcher = new WebhookDispatcher({
+    ...options,
+    endpointsTable,
+    deliveriesTable,
+  });
+
+  const apiHandlers = createWebhookApiHandlers(dispatcher, options);
+
+  return {
+    name: 'webhooks',
+    version: '1.0.0',
+    description: 'Outgoing Webhook Dispatcher with HMAC-SHA256 signatures, wildcard matching, retries, and Admin UI',
+    options,
+
+    api: {
+      dispatcher,
+      dispatch: (event, payload, opts) => dispatcher.dispatch(event, payload, opts),
+      pingEndpoint: (id) => dispatcher.pingEndpoint(id),
+      retryDelivery: (id) => dispatcher.retryDelivery(id),
+      createEndpoint: (data) => dispatcher.createEndpoint(data),
+      getEndpoint: (id) => dispatcher.getEndpoint(id),
+      updateEndpoint: (id, data) => dispatcher.updateEndpoint(id, data),
+      deleteEndpoint: (id) => dispatcher.deleteEndpoint(id),
+      listEndpoints: (filters) => dispatcher.listEndpoints(filters),
+      listDeliveries: (filters) => dispatcher.listDeliveries(filters),
+      getDelivery: (id) => dispatcher.getDelivery(id),
+      purgeDeliveries: (opts) => dispatcher.purgeDeliveries(opts),
+      generateSecret,
+      safeCompare,
+      signPayload,
+      verifySignature,
+      matchEvent,
+      matchesAnyEvent,
+      sendWebhook,
+      getMigrationTemplate: (epTable, dlvTable) =>
+        generateWebhooksMigration(epTable || endpointsTable, dlvTable || deliveriesTable),
+      getModels: () => ({
+        WebhookEndpoint: createWebhookEndpointModel(endpointsTable),
+        WebhookDelivery: createWebhookDeliveryModel(deliveriesTable),
+      }),
+    },
+
+    register(ctx) {
+      const db = options.db || (ctx && ctx.db);
+      if (db && typeof db.registerModel === 'function' && typeof db.hasModel === 'function') {
+        if (!db.hasModel('WebhookEndpoint')) {
+          db.registerModel(createWebhookEndpointModel(endpointsTable));
+        }
+        if (!db.hasModel('WebhookDelivery')) {
+          db.registerModel(createWebhookDeliveryModel(deliveriesTable));
+        }
+      }
+
+      // If DB was not passed in plugin options, bind it from ctx
+      if (!dispatcher.db && db) {
+        dispatcher.db = db;
+        dispatcher.knex = db.knex || db;
+      }
+
+      // Attach dispatcher to app and request objects
+      if (ctx.app) {
+        ctx.app.webhooks = dispatcher;
+        ctx.app.use((req, res, next) => {
+          req.webhooks = dispatcher;
+          next();
+        });
+
+        // Register built-in services in app.serviceRegistry if available
+        if (ctx.app.serviceRegistry && typeof ctx.app.serviceRegistry.register === 'function') {
+          if (!ctx.app.serviceRegistry.has('webhook.dispatch')) {
+            ctx.app.serviceRegistry.register('webhook.dispatch', {
+              handler: async (input) => dispatcher.dispatch(input.event, input.payload, input),
+            });
+          }
+          if (!ctx.app.serviceRegistry.has('webhook.ping')) {
+            ctx.app.serviceRegistry.register('webhook.ping', {
+              handler: async (input) => dispatcher.pingEndpoint(input.endpointId),
+            });
+          }
+          if (!ctx.app.serviceRegistry.has('webhook.retry')) {
+            ctx.app.serviceRegistry.register('webhook.retry', {
+              handler: async (input) => dispatcher.retryDelivery(input.deliveryId),
+            });
+          }
+        }
+
+        // Integrate with core/queue if queue is present
+        const queueManager = options.queue || ctx.app.queue;
+        if (queueManager && typeof queueManager.define === 'function') {
+          dispatcher.setQueue(queueManager);
+          if (!queueManager.handlers?.has?.('webhooks.deliver')) {
+            queueManager.define('webhooks.deliver', async (job) => {
+              const { endpointId, deliveryId, event, payload, attempt } = job.data;
+              const endpoint = await dispatcher.getEndpoint(endpointId);
+              if (!endpoint) {
+                throw new Error(`Endpoint #${endpointId} no longer exists.`);
+              }
+              const outcome = await dispatcher.executeDelivery({
+                endpoint,
+                deliveryId,
+                event,
+                payload,
+                attempt: attempt || 1,
+                autoRetry: false, // Let queue handle retries
+              });
+              if (!outcome.success) {
+                throw new Error(outcome.error || `Delivery failed with status ${outcome.statusCode}`);
+              }
+              return outcome;
+            }, {
+              attempts: options.maxAttempts || 3,
+              backoff: { type: 'exponential', delay: options.backoffBaseMs || 1000 },
+              timeout: options.timeoutMs || 10000,
+            });
+          }
+        }
+      }
+
+      return () => {
+        dispatcher.dispose();
+      };
+    },
+
+    dispose() {
+      dispatcher.dispose();
+    },
+
+    shutdown() {
+      dispatcher.dispose();
+    },
+
+    onRoutesReady(ctx) {
+      const adminApi = ctx.usePlugin('admin-panel');
+      if (!adminApi) {
+        return;
+      }
+
+      adminApi.registerModule({
+        id: 'webhooks',
+        title: pageTitle,
+
+        pages: includeDefaultPage
+          ? [{
+              id: 'webhooks',
+              title: pageTitle,
+              path: '/webhooks',
+              icon: 'send',
+              component: generateWebhooksComponent({ apiPrefix }),
+            }]
+          : [],
+
+        menu: includeDefaultPage
+          ? [{
+              id: 'webhooks',
+              label: pageTitle,
+              path: '/webhooks',
+              icon: 'send',
+              order: menuOrder,
+            }]
+          : [],
+
+        api: {
+          prefix: apiPrefix,
+          routes: [
+            { method: 'get', path: '/endpoints', handler: apiHandlers.listEndpointsHandler },
+            { method: 'post', path: '/endpoints', handler: apiHandlers.createEndpointHandler },
+            { method: 'get', path: '/endpoints/:id', handler: apiHandlers.getEndpointHandler },
+            { method: 'put', path: '/endpoints/:id', handler: apiHandlers.updateEndpointHandler },
+            { method: 'patch', path: '/endpoints/:id', handler: apiHandlers.updateEndpointHandler },
+            { method: 'delete', path: '/endpoints/:id', handler: apiHandlers.deleteEndpointHandler },
+            { method: 'post', path: '/endpoints/:id/ping', handler: apiHandlers.pingEndpointHandler },
+            { method: 'get', path: '/deliveries', handler: apiHandlers.listDeliveriesHandler },
+            { method: 'get', path: '/deliveries/:id', handler: apiHandlers.getDeliveryHandler },
+            { method: 'post', path: '/deliveries/:id/retry', handler: apiHandlers.retryDeliveryHandler },
+            { method: 'post', path: '/deliveries/purge', handler: apiHandlers.purgeDeliveriesHandler },
+          ],
+        },
+      });
+    },
+  };
+}
+
+webhooksPlugin.webhooksPlugin = webhooksPlugin;
+webhooksPlugin.WebhookDispatcher = WebhookDispatcher;
+webhooksPlugin.generateSecret = generateSecret;
+webhooksPlugin.safeCompare = safeCompare;
+webhooksPlugin.signPayload = signPayload;
+webhooksPlugin.verifySignature = verifySignature;
+webhooksPlugin.matchEvent = matchEvent;
+webhooksPlugin.matchesAnyEvent = matchesAnyEvent;
+webhooksPlugin.normalizeEvents = normalizeEvents;
+webhooksPlugin.sendWebhook = sendWebhook;
+webhooksPlugin.generateDeliveryId = generateDeliveryId;
+webhooksPlugin.generateWebhooksMigration = generateWebhooksMigration;
+webhooksPlugin.createWebhookEndpointModel = createWebhookEndpointModel;
+webhooksPlugin.createWebhookDeliveryModel = createWebhookDeliveryModel;
+webhooksPlugin.createWebhookApiHandlers = createWebhookApiHandlers;
+webhooksPlugin.generateWebhooksComponent = generateWebhooksComponent;
+
+module.exports = webhooksPlugin;
+module.exports.webhooksPlugin = webhooksPlugin;
+module.exports.WebhookDispatcher = WebhookDispatcher;
+module.exports.generateSecret = generateSecret;
+module.exports.safeCompare = safeCompare;
+module.exports.signPayload = signPayload;
+module.exports.verifySignature = verifySignature;
+module.exports.matchEvent = matchEvent;
+module.exports.matchesAnyEvent = matchesAnyEvent;
+module.exports.normalizeEvents = normalizeEvents;
+module.exports.sendWebhook = sendWebhook;
+module.exports.generateDeliveryId = generateDeliveryId;
+module.exports.generateWebhooksMigration = generateWebhooksMigration;
+module.exports.createWebhookEndpointModel = createWebhookEndpointModel;
+module.exports.createWebhookDeliveryModel = createWebhookDeliveryModel;
+module.exports.createWebhookApiHandlers = createWebhookApiHandlers;
+module.exports.generateWebhooksComponent = generateWebhooksComponent;

package/plugins/webhooks/matcher.js

@@ -0,0 +1,113 @@
+/**
+ * Webhooks Event Pattern Matcher
+ * Supports wildcard matching (*, user.*, order.item.*)
+ * @module plugins/webhooks/matcher
+ */
+
+'use strict';
+
+/**
+ * Normalize an event filter into an array of strings
+ * 
+ * @param {string|string[]|any} events 
+ * @returns {string[]}
+ */
+function normalizeEvents(events) {
+  if (!events) {
+    return ['*'];
+  }
+
+  if (Array.isArray(events)) {
+    return events
+      .map((e) => (typeof e === 'string' ? e.trim() : ''))
+      .filter(Boolean);
+  }
+
+  if (typeof events === 'string') {
+    const trimmed = events.trim();
+    if (!trimmed) return ['*'];
+
+    // If JSON array string like '["user.*", "order.created"]'
+    if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+      try {
+        const parsed = JSON.parse(trimmed);
+        if (Array.isArray(parsed)) {
+          return parsed.map((e) => (typeof e === 'string' ? e.trim() : '')).filter(Boolean);
+        }
+      } catch (err) {
+        // Fall back to comma-separated
+      }
+    }
+
+    return trimmed
+      .split(',')
+      .map((e) => e.trim())
+      .filter(Boolean);
+  }
+
+  return ['*'];
+}
+
+/**
+ * Test whether an event pattern matches an actual event name
+ * 
+ * @param {string} pattern - E.g. '*', 'user.*', 'order.created', 'billing.invoice.paid'
+ * @param {string} eventName - E.g. 'user.created', 'order.created'
+ * @returns {boolean}
+ */
+function matchEvent(pattern, eventName) {
+  if (!pattern || !eventName) {
+    return false;
+  }
+
+  const p = pattern.trim();
+  const e = eventName.trim();
+
+  // 1. Wildcard matches all
+  if (p === '*') {
+    return true;
+  }
+
+  // 2. Exact match
+  if (p === e) {
+    return true;
+  }
+
+  // 3. Glob / Wildcard conversion
+  // Convert 'user.*' to regular expression '^user\.[^.]+$' or '^user\..+$'
+  // Support prefix, middle, or suffix wildcards safely
+  const escaped = p
+    .replace(/[.+?^${}()|[\]\\]/g, '\\$&') // escape regex specials except *
+    .replace(/\*/g, '.*');
+
+  const regex = new RegExp(`^${escaped}$`, 'i');
+  return regex.test(e);
+}
+
+/**
+ * Check if an event name matches any pattern in a list
+ * 
+ * @param {string|string[]} patterns 
+ * @param {string} eventName 
+ * @returns {boolean}
+ */
+function matchesAnyEvent(patterns, eventName) {
+  const list = normalizeEvents(patterns);
+  if (list.length === 0) {
+    return false;
+  }
+
+  for (const pattern of list) {
+    if (matchEvent(pattern, eventName)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+module.exports = {
+  normalizeEvents,
+  matchEvent,
+  matchesAnyEvent,
+};

package/plugins/webhooks/migration-template.js

@@ -0,0 +1,75 @@
+/**
+ * Migration template for webhook_endpoints and webhook_deliveries tables
+ * @module plugins/webhooks/migration-template
+ */
+
+'use strict';
+
+/**
+ * Generate migration file content for webhooks tables
+ * 
+ * @param {string} [endpointsTable='webhook_endpoints']
+ * @param {string} [deliveriesTable='webhook_deliveries']
+ * @returns {string}
+ */
+function generateWebhooksMigration(
+  endpointsTable = 'webhook_endpoints',
+  deliveriesTable = 'webhook_deliveries'
+) {
+  return `/**
+ * Migration: Create ${endpointsTable} and ${deliveriesTable} tables
+ * Auto-generated by webhooks plugin
+ */
+
+exports.up = async function(knex) {
+  const hasEndpoints = await knex.schema.hasTable('${endpointsTable}');
+  if (!hasEndpoints) {
+    await knex.schema.createTable('${endpointsTable}', (table) => {
+      table.increments('id').primary();
+      table.string('name', 255).notNullable();
+      table.string('url', 2048).notNullable();
+      table.string('secret', 255).notNullable();
+      table.text('events').notNullable().defaultTo('["*"]');
+      table.boolean('is_active').notNullable().defaultTo(true).index();
+      table.string('description', 1000).nullable();
+      table.text('headers').nullable();
+      table.text('metadata').nullable();
+      table.timestamp('created_at').defaultTo(knex.fn.now()).notNullable().index();
+      table.timestamp('updated_at').defaultTo(knex.fn.now()).notNullable();
+    });
+  }
+
+  const hasDeliveries = await knex.schema.hasTable('${deliveriesTable}');
+  if (!hasDeliveries) {
+    await knex.schema.createTable('${deliveriesTable}', (table) => {
+      table.increments('id').primary();
+      table.integer('endpoint_id').unsigned().notNullable().index();
+      table.string('event', 255).notNullable().index();
+      table.text('payload').notNullable();
+      table.integer('status_code').nullable();
+      table.boolean('success').notNullable().defaultTo(false).index();
+      table.integer('duration_ms').nullable();
+      table.text('error').nullable();
+      table.text('response_body').nullable();
+      table.integer('attempt').notNullable().defaultTo(1);
+      table.integer('max_attempts').notNullable().defaultTo(3);
+      table.timestamp('next_retry_at').nullable().index();
+      table.timestamp('created_at').defaultTo(knex.fn.now()).notNullable().index();
+      table.timestamp('updated_at').defaultTo(knex.fn.now()).notNullable();
+
+      table.index(['endpoint_id', 'created_at']);
+      table.index(['event', 'success']);
+    });
+  }
+};
+
+exports.down = async function(knex) {
+  await knex.schema.dropTableIfExists('${deliveriesTable}');
+  await knex.schema.dropTableIfExists('${endpointsTable}');
+};
+`;
+}
+
+module.exports = {
+  generateWebhooksMigration,
+};

package/plugins/webhooks/models.js

@@ -0,0 +1,98 @@
+/**
+ * Webhooks ORM Models
+ * Webspresso ORM model definitions for WebhookEndpoint and WebhookDelivery
+ * @module plugins/webhooks/models
+ */
+
+'use strict';
+
+const { defineModel } = require('../../core/orm/model');
+const { zdb } = require('../../core/orm');
+
+/**
+ * Create WebhookEndpoint model definition
+ * 
+ * @param {string} [tableName='webhook_endpoints']
+ * @returns {import('../../core/orm/types').ModelDefinition}
+ */
+function createWebhookEndpointModel(tableName = 'webhook_endpoints') {
+  const schema = zdb.schema({
+    id: zdb.id(),
+    name: zdb.string({ maxLength: 255 }),
+    url: zdb.string({ maxLength: 2048 }),
+    secret: zdb.string({ maxLength: 255 }),
+    events: zdb.text({ default: '["*"]' }),
+    is_active: zdb.boolean({ default: true }),
+    description: zdb.string({ maxLength: 1000, nullable: true }),
+    headers: zdb.json({ nullable: true }),
+    metadata: zdb.json({ nullable: true }),
+    created_at: zdb.timestamp({ auto: 'create' }),
+    updated_at: zdb.timestamp({ auto: 'update' }),
+  });
+
+  return defineModel({
+    name: 'WebhookEndpoint',
+    table: tableName,
+    schema,
+    scopes: {
+      timestamps: true,
+      active: (query) => query.where('is_active', true),
+    },
+    hidden: ['secret'], // Protect signing secret from serialization leaks
+    relations: {
+      deliveries: {
+        type: 'hasMany',
+        model: () => 'WebhookDelivery',
+        foreignKey: 'endpoint_id',
+      },
+    },
+  });
+}
+
+/**
+ * Create WebhookDelivery model definition
+ * 
+ * @param {string} [tableName='webhook_deliveries']
+ * @returns {import('../../core/orm/types').ModelDefinition}
+ */
+function createWebhookDeliveryModel(tableName = 'webhook_deliveries') {
+  const schema = zdb.schema({
+    id: zdb.id(),
+    endpoint_id: zdb.integer(),
+    event: zdb.string({ maxLength: 255 }),
+    payload: zdb.text(),
+    status_code: zdb.integer({ nullable: true }),
+    success: zdb.boolean({ default: false }),
+    duration_ms: zdb.integer({ nullable: true }),
+    error: zdb.text({ nullable: true }),
+    response_body: zdb.text({ nullable: true }),
+    attempt: zdb.integer({ default: 1 }),
+    max_attempts: zdb.integer({ default: 3 }),
+    next_retry_at: zdb.timestamp({ nullable: true }),
+    created_at: zdb.timestamp({ auto: 'create' }),
+    updated_at: zdb.timestamp({ auto: 'update' }),
+  });
+
+  return defineModel({
+    name: 'WebhookDelivery',
+    table: tableName,
+    schema,
+    scopes: {
+      timestamps: true,
+      successful: (query) => query.where('success', true),
+      failed: (query) => query.where('success', false),
+    },
+    relations: {
+      endpoint: {
+        type: 'belongsTo',
+        model: () => 'WebhookEndpoint',
+        foreignKey: 'endpoint_id',
+      },
+    },
+  });
+}
+
+module.exports = {
+  createWebhookEndpointModel,
+  createWebhookDeliveryModel,
+};