@hed-hog/core 0.0.295 → 0.0.296

package/src/integration/USAGE_EXAMPLE.md

@@ -0,0 +1,279 @@
+/**
+ * EXAMPLE: How a Module Uses the Integration Foundation
+ *
+ * This example shows how the finance or operations module would use
+ * the core integration infrastructure to publish events and handle
+ * events from other modules.
+ */
+
+// ============================================================================
+// STEP 1: Publish a Domain Event from Finance Module
+// ============================================================================
+
+import { Injectable } from '@nestjs/common';
+import { IntegrationDeveloperApiService } from '@hed-hog/core';
+import { PrismaService } from '@hed-hog/api-prisma';
+
+@Injectable()
+export class InvoiceService {
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly integrationApi: IntegrationDeveloperApiService,
+  ) {}
+
+  async createInvoice(data: any): Promise<any> {
+    // Create the invoice
+    const invoice = await this.prisma.invoice.create({ data });
+
+    // Publish event that other modules can subscribe to
+    await this.integrationApi.publishEvent({
+      eventName: 'invoice.created',
+      sourceModule: 'finance',
+      aggregateType: 'Invoice',
+      aggregateId: invoice.id,
+      payload: {
+        invoiceId: invoice.id,
+        amount: invoice.amount,
+        customerId: invoice.customerId,
+      },
+      metadata: {
+        producer: 'finance',
+      },
+    });
+
+    return invoice;
+  }
+
+  async cancelInvoice(invoiceId: string): Promise<void> {
+    await this.prisma.invoice.update({
+      where: { id: invoiceId },
+      data: { status: 'CANCELLED' },
+    });
+
+    // Notify subscribers
+    await this.integrationApi.publishEvent({
+      eventName: 'invoice.cancelled',
+      sourceModule: 'finance',
+      aggregateType: 'Invoice',
+      aggregateId: invoiceId,
+      payload: { invoiceId },
+    });
+  }
+}
+
+// ============================================================================
+// STEP 2: Register Event Handlers in Operations Module
+// ============================================================================
+
+import { Injectable, OnModuleInit} from '@nestjs/common';
+import {
+  IntegrationDeveloperApiService,
+  DomainEvent,
+  SubscriberContext,
+  LinkType,
+} from '@hed-hog/core';
+import { PrismaService } from '@hed-hog/api-prisma';
+
+@Injectable()
+export class OperationsEventHandlers implements OnModuleInit {
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly integrationApi: IntegrationDeveloperApiService,
+  ) {}
+
+  onModuleInit(): void {
+    // Register handler for invoice.created event
+    this.integrationApi.subscribe({
+      eventName: 'invoice.created',
+      consumerName: 'operations-module',
+      priority: 10,
+      handler: async (event: DomainEvent, context: SubscriberContext) => {
+        await this.onInvoiceCreated(event, context);
+      },
+    });
+
+    // Register handler for invoice.cancelled event
+    this.integrationApi.subscribe({
+      eventName: 'invoice.cancelled',
+      consumerName: 'operations-module',
+      priority: 10,
+      handler: async (event: DomainEvent, context: SubscriberContext) => {
+        await this.onInvoiceCancelled(event, context);
+      },
+    });
+  }
+
+  /**
+   * Handle invoice.created event
+   * This might trigger operational workflows, create tasks, etc.
+   */
+  private async onInvoiceCreated(
+    event: DomainEvent,
+    context: SubscriberContext,
+  ): Promise<void> {
+    context.logger.log(`Processing invoice creation: ${event.aggregateId}`);
+
+    const { invoiceId, customerId, amount } = event.payload;
+
+    // Create an operational task
+    const task = await this.prisma.task.create({
+      data: {
+        title: `Process invoice ${invoiceId}`,
+        description: `Invoice for amount ${amount} from customer ${customerId}`,
+        status: 'PENDING',
+      },
+    });
+
+    // Create an integration link between the finance invoice and operations task
+    await context.linkService.createLink({
+      sourceModule: 'finance',
+      sourceEntityType: 'Invoice',
+      sourceEntityId: invoiceId,
+      targetModule: 'operations',
+      targetEntityType: 'Task',
+      targetEntityId: task.id,
+      linkType: LinkType.CASCADE,
+      metadata: {
+        reason: 'workflow_trigger',
+        invoiceAmount: amount,
+      },
+    });
+
+    context.logger.log(
+      `Created task ${task.id} for invoice ${invoiceId}`,
+    );
+  }
+
+  /**
+   * Handle invoice.cancelled event
+   */
+  private async onInvoiceCancelled(
+    event: DomainEvent,
+    context: SubscriberContext,
+  ): Promise<void> {
+    context.logger.log(`Processing invoice cancellation: ${event.aggregateId}`);
+
+    const { invoiceId } = event.payload;
+
+    // Find linked tasks
+    const links = await context.linkService.findOutbound(
+      'finance',
+      'Invoice',
+      invoiceId,
+    );
+
+    for (const link of links) {
+      // Cancel related tasks
+      if (link.targetModule === 'operations' && link.targetEntityType === 'Task') {
+        await this.prisma.task.update({
+          where: { id: link.targetEntityId },
+          data: { status: 'CANCELLED' },
+        });
+
+        context.logger.log(
+          `Cancelled task ${link.targetEntityId} due to invoice cancellation`,
+        );
+      }
+    }
+  }
+}
+
+// ============================================================================
+// STEP 3: Register Handlers in Operations Module DI
+// ============================================================================
+
+import { Module } from '@nestjs/common';
+
+@Module({
+  providers: [OperationsEventHandlers],
+})
+export class OperationsModule {
+  // OperationsEventHandlers will be instantiated and its onModuleInit()
+  // will be called automatically, registering event handlers
+}
+
+// ============================================================================
+// STEP 4: Query Integration Links to Find Related Entities
+// ============================================================================
+
+import { Injectable } from '@nestjs/common';
+import { IntegrationDeveloperApiService, LinkType } from '@hed-hog/core';
+
+@Injectable()
+export class InvoiceQueryService {
+  constructor(
+    private readonly integrationApi: IntegrationDeveloperApiService,
+  ) {}
+
+  /**
+   * Find all operational tasks related to an invoice
+   */
+  async getRelatedTasks(invoiceId: string): Promise<any[]> {
+    const links = await this.integrationApi.findLinksBySource({
+      module: 'finance',
+      entityType: 'Invoice',
+      entityId: invoiceId,
+    });
+
+    const taskLinks = links.filter(
+      (link) => link.targetModule === 'operations' && link.targetEntityType === 'Task',
+    );
+
+    return taskLinks.map((link) => link.targetEntityId);
+  }
+
+  /**
+   * Find the invoice that triggered a task
+   */
+  async getSourceInvoice(taskId: string): Promise<string | null> {
+    const links = await this.integrationApi.findLinksByTarget({
+      module: 'operations',
+      entityType: 'Task',
+      entityId: taskId,
+    });
+
+    const invoiceLink = links.find(
+      (link) => link.sourceModule === 'finance' && link.sourceEntityType === 'Invoice',
+    );
+
+    return invoiceLink?.sourceEntityId || null;
+  }
+}
+
+// ============================================================================
+// ARCHITECTURE NOTES
+// ============================================================================
+
+/**
+ * KEY PRINCIPLES:
+ *
+ * 1. DURABLE OUTBOX
+ *    - Events are written to the database outbox table first
+ *    - In-memory notification wakes up processor (optional acceleration)
+ *    - On crashes/restarts, processor catches up on pending events
+ *    - No events are lost
+ *
+ * 2. IDEMPOTENT PROCESSING
+ *    - Each consumer has an inbox entry per outbox event
+ *    - Unique constraint prevents duplicate processing
+ *    - If a handler crashes mid-execution, retry will recognize it was attempted
+ *    - Handlers must be idempotent at the application logic level
+ *
+ * 3. CROSS-MODULE DECOUPLING
+ *    - Modules publish events but don't depend on other modules' internals
+ *    - Integration links are explicit, queryable, and metadata-rich
+ *    - No direct FK relationships across module boundaries
+ *    - Modules self-register handlers, core doesn't know about them
+ *
+ * 4. CONFIGURABILITY
+ *    - All timing/retry/batch/scope settings are in the core SettingService
+ *    - Operations/infrastructure teams can tune without code changes
+ *    - Settings can be changed at runtime
+ *
+ * 5. FAILURE RECOVERY
+ *    - Exponential backoff on handler failures
+ *    - Configurable max attempts
+ *    - Dead letter queue for poisoned events
+ *    - Processing lease time prevents stuck events
+ *    - Startup drain recovers pending events after restart
+ */

package/src/integration/index.ts

@@ -0,0 +1,4 @@
+export * from './integration.module';
+export * from './services';
+export * from './types';
+

package/src/integration/integration-api.validation.ts

@@ -0,0 +1,154 @@
+import { strict as assert } from 'assert';
+import { DomainEventPublisher } from './services/domain-event.publisher';
+import { EventSubscriberRegistry } from './services/event-subscriber.registry';
+import { InboxService } from './services/inbox.service';
+import { IntegrationLinkService } from './services/integration-link.service';
+import { LinkType } from './types';
+
+async function validatePublisher(): Promise<void> {
+  const createdEvent = {
+    id: 'evt-1',
+    eventName: 'operations.project.billing_ready',
+    sourceModule: 'operations',
+    aggregateType: 'project',
+    aggregateId: 'prj-1',
+    payload: { projectId: 'prj-1' },
+    status: 'pending',
+    attemptCount: 0,
+    lastError: null,
+    availableAt: new Date(),
+    processedAt: null,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  };
+
+  const outboxService = {
+    createEvent: async () => createdEvent,
+  };
+
+  let notified = 0;
+  const notifier = {
+    notifyEventWritten: () => {
+      notified += 1;
+    },
+  };
+
+  const publisher = new DomainEventPublisher(
+    outboxService as any,
+    notifier as any,
+  );
+
+  const result = await publisher.publishEvent({
+    eventName: 'operations.project.billing_ready',
+    sourceModule: 'operations',
+    aggregateType: 'project',
+    aggregateId: 'prj-1',
+    payload: { projectId: 'prj-1' },
+  });
+
+  assert.equal(result.id, 'evt-1');
+  assert.equal(notified, 1);
+}
+
+async function validateRegistry(): Promise<void> {
+  const registry = new EventSubscriberRegistry();
+
+  registry.subscribe(
+    'operations.contract.payable_generated',
+    'consumer-low',
+    async () => undefined,
+    1,
+  );
+  registry.subscribe(
+    'operations.contract.payable_generated',
+    'consumer-high',
+    async () => undefined,
+    10,
+  );
+
+  const handlers = registry.getHandlers('operations.contract.payable_generated');
+  assert.equal(handlers.length, 2);
+  const firstHandler = handlers[0];
+  assert.ok(firstHandler);
+  assert.equal(firstHandler.consumerName, 'consumer-high');
+}
+
+async function validateLinks(): Promise<void> {
+  const link = {
+    id: 'link-1',
+    sourceModule: 'operations',
+    sourceEntityType: 'project',
+    sourceEntityId: 'prj-1',
+    targetModule: 'finance',
+    targetEntityType: 'payable',
+    targetEntityId: 'pay-1',
+    linkType: LinkType.REFERENCE,
+    metadata: null,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  };
+
+  const prisma = {
+    integrationLink: {
+      create: async () => link,
+      findMany: async () => [link],
+    },
+  };
+
+  const service = new IntegrationLinkService(prisma as any);
+  const created = await service.createLink({
+    sourceModule: 'operations',
+    sourceEntityType: 'project',
+    sourceEntityId: 'prj-1',
+    targetModule: 'finance',
+    targetEntityType: 'payable',
+    targetEntityId: 'pay-1',
+    linkType: LinkType.REFERENCE,
+  });
+
+  const outbound = await service.findOutbound('operations', 'project', 'prj-1');
+  assert.equal(created.id, 'link-1');
+  assert.equal(outbound.length, 1);
+}
+
+async function validateInboxIdempotency(): Promise<void> {
+  const existing = {
+    id: 1,
+    outbox_event_id: 1,
+    consumer_name: 'finance-module',
+    status: 'processed',
+    attempt_count: 1,
+    last_error: null,
+    processed_at: new Date(),
+    created_at: new Date(),
+    updated_at: new Date(),
+  };
+
+  const prisma = {
+    inbox_event: {
+      findFirst: async () => existing,
+      create: async () => {
+        throw new Error('create should not be called for existing inbox item');
+      },
+    },
+  };
+
+  const inbox = new InboxService(prisma as any);
+  const result = await inbox.getOrCreate('1', 'finance-module');
+  assert.equal(result.id, '1');
+}
+
+async function main(): Promise<void> {
+  await validatePublisher();
+  await validateRegistry();
+  await validateLinks();
+  await validateInboxIdempotency();
+  // eslint-disable-next-line no-console
+  console.log('Integration API validation passed');
+}
+
+main().catch((error) => {
+  // eslint-disable-next-line no-console
+  console.error('Integration API validation failed', error);
+  process.exit(1);
+});

package/src/integration/integration.module.ts

@@ -0,0 +1,53 @@
+import { PrismaModule } from '@hed-hog/api-prisma';
+import { Global, Module, forwardRef } from '@nestjs/common';
+import { ScheduleModule } from '@nestjs/schedule';
+import { SettingModule } from '../setting/setting.module';
+import {
+    DomainEventPublisher,
+    EventSubscriberRegistry,
+    InboxService,
+    IntegrationDeveloperApiService,
+    IntegrationLinkService,
+    IntegrationSettingsService,
+    OutboxNotifier,
+    OutboxPollingCoordinator,
+    OutboxProcessor,
+    OutboxProcessorJob,
+    OutboxService,
+} from './services';
+
+@Global()
+@Module({
+  imports: [
+    ScheduleModule.forRoot(),
+    PrismaModule,
+    forwardRef(() => SettingModule),
+  ],
+  providers: [
+    OutboxNotifier,
+    OutboxService,
+    InboxService,
+    IntegrationLinkService,
+    EventSubscriberRegistry,
+    IntegrationDeveloperApiService,
+    IntegrationSettingsService,
+    DomainEventPublisher,
+    OutboxProcessor,
+    OutboxPollingCoordinator,
+    OutboxProcessorJob,
+  ],
+  exports: [
+    OutboxNotifier,
+    OutboxService,
+    InboxService,
+    IntegrationLinkService,
+    EventSubscriberRegistry,
+    IntegrationDeveloperApiService,
+    IntegrationSettingsService,
+    DomainEventPublisher,
+    OutboxProcessor,
+    OutboxPollingCoordinator,
+    OutboxProcessorJob,
+  ],
+})
+export class IntegrationModule {}

package/src/integration/services/domain-event.publisher.ts

@@ -0,0 +1,136 @@
+import { Injectable } from '@nestjs/common';
+import { DomainEvent, OutboxEvent } from '../types';
+import { OutboxNotifier } from './outbox.notifier';
+import { OutboxEventPersistenceClient, OutboxService } from './outbox.service';
+
+export interface PublishDomainEventInput {
+  eventName: string;
+  sourceModule: string;
+  aggregateType: string;
+  aggregateId: string;
+  payload?: Record<string, any>;
+  metadata?: Record<string, any>;
+}
+
+export interface PublishDomainEventOptions {
+  persistenceClient?: OutboxEventPersistenceClient;
+}
+
+@Injectable()
+export class DomainEventPublisher {
+  constructor(
+    private readonly outboxService: OutboxService,
+    private readonly outboxNotifier: OutboxNotifier,
+  ) {}
+
+  /**
+   * Publish a domain event
+   * Writes to durable outbox and notifies processor for immediate wakeup
+   */
+  async publishEvent(
+    input: PublishDomainEventInput,
+    options?: PublishDomainEventOptions,
+  ): Promise<OutboxEvent>;
+
+  async publishEvent(
+    eventName: string,
+    sourceModule: string,
+    aggregateType: string,
+    aggregateId: string,
+    payload?: Record<string, any>,
+    metadata?: Record<string, any>,
+    options?: PublishDomainEventOptions,
+  ): Promise<OutboxEvent>;
+
+  async publishEvent(
+    eventOrName: PublishDomainEventInput | string,
+    sourceModuleOrOptions?: string | PublishDomainEventOptions,
+    aggregateType?: string,
+    aggregateId?: string,
+    payload?: Record<string, any>,
+    metadata?: Record<string, any>,
+    options?: PublishDomainEventOptions,
+  ): Promise<OutboxEvent> {
+    const payloadData = payload || {};
+    const input =
+      typeof eventOrName === 'string'
+        ? {
+            eventName: eventOrName,
+            sourceModule: sourceModuleOrOptions as string,
+            aggregateType: aggregateType as string,
+            aggregateId: aggregateId as string,
+            payload: payloadData,
+            metadata,
+          }
+        : eventOrName;
+
+    const publishOptions =
+      typeof eventOrName === 'string'
+        ? options
+        : (sourceModuleOrOptions as PublishDomainEventOptions | undefined);
+
+    const persistedPayload = this.enrichPayloadWithMetadata(
+      input.payload || {},
+      input.metadata,
+    );
+
+    // Write to outbox (durable, authoritative)
+    const outboxEvent = await this.outboxService.createEvent(
+      {
+        eventName: input.eventName,
+        sourceModule: input.sourceModule,
+        aggregateType: input.aggregateType,
+        aggregateId: input.aggregateId,
+        payload: persistedPayload,
+      },
+      publishOptions?.persistenceClient,
+    );
+
+    // Notify processor for immediate wakeup (best-effort, not guaranteed)
+    this.outboxNotifier.notifyEventWritten();
+
+    return outboxEvent;
+  }
+
+  /**
+   * Publish multiple events in sequence
+   */
+  async publishEvents(
+    events: Array<DomainEvent | PublishDomainEventInput>,
+    options?: PublishDomainEventOptions,
+  ): Promise<OutboxEvent[]> {
+    const published: OutboxEvent[] = [];
+
+    for (const event of events) {
+      published.push(
+        await this.publishEvent(
+          {
+            eventName: event.eventName,
+            sourceModule: event.sourceModule,
+            aggregateType: event.aggregateType,
+            aggregateId: event.aggregateId,
+            payload: event.payload,
+            metadata: (event as PublishDomainEventInput).metadata,
+          },
+          options,
+        ),
+      );
+    }
+
+    return published;
+  }
+
+  private enrichPayloadWithMetadata(
+    payload: Record<string, any>,
+    metadata?: Record<string, any>,
+  ): Record<string, any> {
+    if (!metadata) {
+      return payload;
+    }
+
+    return {
+      ...payload,
+      _integrationMeta: metadata,
+    };
+  }
+}