refactor: shared types package, outbox events, TanStack Query, plugin system (#541)

Author: Dannyswiss1

.github/workflows/types-contract.yml

@@ -0,0 +1,34 @@
+name: Types Contract
+
+on:
+  pull_request:
+    paths:
+      - 'packages/types/**'
+      - 'backend/prisma/schema.prisma'
+      - 'backend/src/**'
+      - 'frontend/**'
+      - 'packages/sdk/src/**'
+  push:
+    branches: [main]
+    paths:
+      - 'packages/types/**'
+      - 'backend/prisma/schema.prisma'
+
+jobs:
+  shared-types:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run generate:prisma-types --workspace @agenticpay/types
+      - run: npm run build --workspace @agenticpay/types
+      - run: npm run check:duplicates --workspace @agenticpay/types
+      - run: TYPE_API_BASE_REF=origin/main npm run check:breaking --workspace @agenticpay/types
+      - run: npm run changelog --workspace @agenticpay/types
+      - run: npm run migration-guide --workspace @agenticpay/types

backend/package.json

@@ -34,6 +34,7 @@
     "generate:vapid-keys": "node scripts/generate-vapid-keys.js"
   },
   "dependencies": {
+    "@agenticpay/types": "*",
     "@prisma/client": "^5.22.0",
     "@sentry/node": "^10.50.0",
     "@sentry/profiling-node": "^10.50.0",

backend/prisma/migrations/20260626010000_outbox_plugins/down.sql

@@ -0,0 +1,6 @@
+DROP TABLE IF EXISTS "plugin_audit_logs";
+DROP TABLE IF EXISTS "plugin_configs";
+DROP TABLE IF EXISTS "plugins";
+DROP TABLE IF EXISTS "outbox_events";
+DROP TYPE IF EXISTS "PluginStatus";
+DROP TYPE IF EXISTS "OutboxEventStatus";

backend/prisma/migrations/20260626010000_outbox_plugins/migration.sql

@@ -0,0 +1,95 @@
+-- CreateEnum
+CREATE TYPE "OutboxEventStatus" AS ENUM ('pending', 'publishing', 'published', 'dead_letter');
+
+-- CreateEnum
+CREATE TYPE "PluginStatus" AS ENUM ('installed', 'enabled', 'disabled', 'error');
+
+-- CreateTable
+CREATE TABLE "outbox_events" (
+    "id" TEXT NOT NULL,
+    "aggregate_type" TEXT NOT NULL,
+    "aggregate_id" TEXT NOT NULL,
+    "event_type" TEXT NOT NULL,
+    "payload" JSONB NOT NULL,
+    "status" "OutboxEventStatus" NOT NULL DEFAULT 'pending',
+    "attempts" INTEGER NOT NULL DEFAULT 0,
+    "last_error" TEXT,
+    "published_at" TIMESTAMP(3),
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "outbox_events_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "plugins" (
+    "id" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "version" TEXT NOT NULL,
+    "source" TEXT NOT NULL,
+    "status" "PluginStatus" NOT NULL DEFAULT 'installed',
+    "compatibility" JSONB NOT NULL,
+    "health" JSONB NOT NULL,
+    "installed_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+    "disabled_at" TIMESTAMP(3),
+
+    CONSTRAINT "plugins_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "plugin_configs" (
+    "id" TEXT NOT NULL,
+    "plugin_id" TEXT NOT NULL,
+    "environment" TEXT NOT NULL DEFAULT 'default',
+    "config" JSONB NOT NULL,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "plugin_configs_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "plugin_audit_logs" (
+    "id" TEXT NOT NULL,
+    "plugin_id" TEXT NOT NULL,
+    "actor_id" TEXT,
+    "action" TEXT NOT NULL,
+    "details" JSONB,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "plugin_audit_logs_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "outbox_events_status_created_at_idx" ON "outbox_events"("status", "created_at");
+
+-- CreateIndex
+CREATE INDEX "outbox_events_aggregate_type_aggregate_id_idx" ON "outbox_events"("aggregate_type", "aggregate_id");
+
+-- CreateIndex
+CREATE INDEX "outbox_events_event_type_idx" ON "outbox_events"("event_type");
+
+-- CreateIndex
+CREATE INDEX "outbox_events_published_at_idx" ON "outbox_events"("published_at");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "plugins_name_key" ON "plugins"("name");
+
+-- CreateIndex
+CREATE INDEX "plugins_status_idx" ON "plugins"("status");
+
+-- CreateIndex
+CREATE INDEX "plugins_name_version_idx" ON "plugins"("name", "version");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "plugin_configs_plugin_id_environment_key" ON "plugin_configs"("plugin_id", "environment");
+
+-- CreateIndex
+CREATE INDEX "plugin_audit_logs_plugin_id_created_at_idx" ON "plugin_audit_logs"("plugin_id", "created_at");
+
+-- AddForeignKey
+ALTER TABLE "plugin_configs" ADD CONSTRAINT "plugin_configs_plugin_id_fkey" FOREIGN KEY ("plugin_id") REFERENCES "plugins"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "plugin_audit_logs" ADD CONSTRAINT "plugin_audit_logs_plugin_id_fkey" FOREIGN KEY ("plugin_id") REFERENCES "plugins"("id") ON DELETE CASCADE ON UPDATE CASCADE;

backend/prisma/schema.prisma

@@ -73,6 +73,20 @@ enum PaymentLinkStatus {
   disabled
 }
 
+enum OutboxEventStatus {
+  pending
+  publishing
+  published
+  dead_letter
+}
+
+enum PluginStatus {
+  installed
+  enabled
+  disabled
+  error
+}
+
 // ─── Models ───────────────────────────────────────────────────────────────────
 
 model User {
@@ -268,6 +282,74 @@ model AuditLog {
   @@map("audit_logs")
 }
 
+model OutboxEvent {
+  id            String            @id @default(uuid())
+  aggregateType String            @map("aggregate_type")
+  aggregateId   String            @map("aggregate_id")
+  eventType     String            @map("event_type")
+  payload       Json
+  status        OutboxEventStatus @default(pending)
+  attempts      Int               @default(0)
+  lastError     String?           @map("last_error")
+  publishedAt   DateTime?         @map("published_at")
+  createdAt     DateTime          @default(now()) @map("created_at")
+  updatedAt     DateTime          @updatedAt @map("updated_at")
+
+  @@index([status, createdAt])
+  @@index([aggregateType, aggregateId])
+  @@index([eventType])
+  @@index([publishedAt])
+  @@map("outbox_events")
+}
+
+model Plugin {
+  id            String       @id @default(uuid())
+  name          String       @unique
+  version       String
+  source        String
+  status        PluginStatus @default(installed)
+  compatibility Json
+  health        Json
+  installedAt   DateTime     @default(now()) @map("installed_at")
+  updatedAt     DateTime     @updatedAt @map("updated_at")
+  disabledAt    DateTime?    @map("disabled_at")
+
+  configs   PluginConfig[]
+  auditLogs PluginAuditLog[]
+
+  @@index([status])
+  @@index([name, version])
+  @@map("plugins")
+}
+
+model PluginConfig {
+  id          String   @id @default(uuid())
+  pluginId    String   @map("plugin_id")
+  environment String   @default("default")
+  config      Json
+  createdAt   DateTime @default(now()) @map("created_at")
+  updatedAt   DateTime @updatedAt @map("updated_at")
+
+  plugin Plugin @relation(fields: [pluginId], references: [id], onDelete: Cascade)
+
+  @@unique([pluginId, environment])
+  @@map("plugin_configs")
+}
+
+model PluginAuditLog {
+  id        String   @id @default(uuid())
+  pluginId  String   @map("plugin_id")
+  actorId   String?  @map("actor_id")
+  action    String
+  details   Json?
+  createdAt DateTime @default(now()) @map("created_at")
+
+  plugin Plugin @relation(fields: [pluginId], references: [id], onDelete: Cascade)
+
+  @@index([pluginId, createdAt])
+  @@map("plugin_audit_logs")
+}
+
 model AuditAnchor {
   id              String   @id @default(uuid())
   latestHash      String   @map("latest_hash")

backend/src/events/event-types.ts

@@ -1,51 +1,12 @@
-export type DomainEventType =
-  | 'payment.created'
-  | 'payment.executed'
-  | 'payment.failed'
-  | 'payment.cancelled'
-  | 'project.created'
-  | 'project.funded'
-  | 'project.work_submitted'
-  | 'project.work_approved'
-  | 'project.disputed'
-  | 'project.cancelled'
-  | 'project.completed'
-  | 'verification.requested'
-  | 'verification.passed'
-  | 'verification.failed'
-  | 'invoice.generated'
-  | 'receipt.minted'
-  | 'receipt.transferred'
-  | 'receipt.burned'
-  | 'refund.requested'
-  | 'refund.approved'
-  | 'refund.rejected'
-  | 'split.created'
-  | 'split.executed';
+export type {
+  DomainEvent,
+  DomainEventType,
+  EventHandler,
+  EventMetadata,
+  StoredEvent,
+} from '@agenticpay/types/events';
 
-export interface DomainEvent<T = unknown> {
-  id: string;
-  type: DomainEventType;
-  aggregateId: string;
-  aggregateType: string;
-  version: number;
-  payload: T;
-  metadata: EventMetadata;
-  occurredAt: string;
-}
-
-export interface EventMetadata {
-  correlationId?: string;
-  causationId?: string;
-  userId?: string;
-  ipAddress?: string;
-  userAgent?: string;
-}
-
-export interface StoredEvent<T = unknown> extends DomainEvent<T> {
-  sequenceNumber: number;
-  streamId: string;
-}
+import type { StoredEvent } from '@agenticpay/types/events';
 
 export interface EventStream {
   streamId: string;
@@ -57,8 +18,6 @@ export interface EventStream {
   updatedAt: string;
 }
 
-export type EventHandler<T = unknown> = (event: StoredEvent<T>) => void | Promise<void>;
-
 export interface PaymentCreatedPayload {
   from: string;
   to: string;

backend/src/index.ts

@@ -109,6 +109,9 @@ import { rateLimitAnalyticsRouter } from './routes/rate-limit-analytics.js';
 import { startScheduledRotation, stopScheduledRotation } from './config/credential-rotation.js';
 import devDevRouter from './routes/dev/reload.js';
 import { sessionsRouter } from './routes/sessions.js';
+import { pluginsRouter } from './routes/plugins.js';
+import { outboxRouter } from './routes/outbox.js';
+import { startOutboxPublisher, stopOutboxPublisher } from './outbox/index.js';
 
 // Validate environment variables at startup
 validateEnv();
@@ -244,6 +247,7 @@ apiV1Router.use('/catalog', catalogRouter);
 apiV1Router.use('/jobs', jobsRouter);
 apiV1Router.use('/queue', queueRouter);
 apiV1Router.use('/queue', bullMQMonitorRouter);
+apiV1Router.use('/outbox', outboxRouter);
 apiV1Router.use('/sla', slaRouter);
 apiV1Router.use('/onboarding', onboardingRouter);
 apiV1Router.use('/legacy', legacyRouter);
@@ -328,6 +332,9 @@ app.use('/api/v1/payment-links', paymentLinksRouter);
 // Merchant tax report generation (summary, 1099-K, VAT, nexus, CSV export)
 app.use('/api/v1/tax', taxRouter);
 
+// Third-party backend plugins
+app.use('/api/v1/admin/plugins', pluginsRouter);
+
 // Project + milestone delivery approval workflow
 app.use('/api/v1/projects', projectsRouter);
 
@@ -412,6 +419,7 @@ if (config.queue.enabled) {
   paymentQueue.start();
 }
 startWebhookWorker();
+startOutboxPublisher({ useBullMQ: Boolean(process.env.REDIS_URL) });
 
 // Auto-escalation cron
 setInterval(async () => {
@@ -477,6 +485,7 @@ server.listen(config.server.port, () => {
 
     // Webhook worker
     startWebhookWorker();
+    startOutboxPublisher({ useBullMQ: Boolean(process.env.REDIS_URL) });
 
     // Auto-escalation cron
     setInterval(async () => {
@@ -535,6 +544,7 @@ const shutdown = (signal: string) => {
       messageQueue.stop();
       paymentQueue.stop();
       stopWebhookWorker();
+      void stopOutboxPublisher();
       console.log('Message queue stopped.');
     } catch (err) {
       console.error('Error stopping message queue:', err);

backend/src/outbox/index.ts

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './writer.js';
+export * from './publisher.js';
+export * from './metrics.js';