@hed-hog/core 0.0.294 → 0.0.296

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,
+    };
+  }
+}

package/src/integration/services/event-subscriber.registry.ts

@@ -0,0 +1,89 @@
+import { Injectable } from '@nestjs/common';
+import { EventHandler, SubscriberDefinition } from '../types';
+
+@Injectable()
+export class EventSubscriberRegistry {
+  private readonly subscribers = new Map<string, SubscriberDefinition[]>();
+
+  /**
+   * Register a subscriber for an event
+   */
+  registerHandler(definition: SubscriberDefinition): void {
+    const { eventName } = definition;
+
+    if (!this.subscribers.has(eventName)) {
+      this.subscribers.set(eventName, []);
+    }
+
+    this.subscribers.get(eventName)!.push(definition);
+
+    // Sort by priority (higher priority first)
+    const handlers = this.subscribers.get(eventName)!;
+    handlers.sort((a, b) => (b.priority || 0) - (a.priority || 0));
+  }
+
+  /**
+   * Ergonomic registration for module services.
+   */
+  subscribe(
+    eventName: string,
+    consumerName: string,
+    handler: EventHandler,
+    priority = 0,
+  ): void {
+    this.registerHandler({
+      eventName,
+      consumerName,
+      handler,
+      priority,
+    });
+  }
+
+  /**
+   * Register multiple handlers in one call.
+   */
+  subscribeMany(definitions: SubscriberDefinition[]): void {
+    for (const definition of definitions) {
+      this.registerHandler(definition);
+    }
+  }
+
+  /**
+   * Get all handlers for an event, sorted by priority
+   */
+  getHandlers(eventName: string): SubscriberDefinition[] {
+    return this.subscribers.get(eventName) || [];
+  }
+
+  /**
+   * Check if event has any handlers
+   */
+  hasHandlers(eventName: string): boolean {
+    return this.subscribers.has(eventName) && this.subscribers.get(eventName)!.length > 0;
+  }
+
+  /**
+   * Get all registered event names
+   */
+  getEventNames(): string[] {
+    return Array.from(this.subscribers.keys());
+  }
+
+  /**
+   * Get total count of all registered handlers
+   */
+  getHandlerCount(): number {
+    let count = 0;
+    for (const handlers of this.subscribers.values()) {
+      count += handlers.length;
+    }
+    return count;
+  }
+
+  /**
+   * Clear all handlers (useful for testing)
+   */
+  clear(): void {
+    this.subscribers.clear();
+  }
+}

package/src/integration/services/inbox.service.ts

@@ -0,0 +1,218 @@
+import { PrismaService } from '@hed-hog/api-prisma';
+import { Injectable } from '@nestjs/common';
+import { InboxEvent, InboxEventStatus } from '../types';
+
+interface InboxEventRecord {
+  id: number;
+  outbox_event_id: number;
+  consumer_name: string;
+  status: InboxEventStatus;
+  attempt_count: number;
+  last_error: string | null;
+  processed_at: Date | null;
+  created_at: Date;
+  updated_at: Date;
+}
+
+@Injectable()
+export class InboxService {
+  constructor(private readonly prisma: PrismaService) {}
+
+  private toDomainEvent(record: InboxEventRecord): InboxEvent {
+    return {
+      id: String(record.id),
+      outboxEventId: String(record.outbox_event_id),
+      consumerName: record.consumer_name,
+      status: record.status,
+      attemptCount: record.attempt_count,
+      lastError: record.last_error,
+      processedAt: record.processed_at,
+      createdAt: record.created_at,
+      updatedAt: record.updated_at,
+    };
+  }
+
+  private toDatabaseId(eventId: string | number): number {
+    return typeof eventId === 'number' ? eventId : Number(eventId);
+  }
+
+  private toDatabaseUpdate(
+    partialUpdate?: {
+      attemptCount?: number;
+      lastError?: string | null;
+      processedAt?: Date | null;
+    },
+  ) {
+    if (!partialUpdate) {
+      return undefined;
+    }
+
+    return {
+      attempt_count: partialUpdate.attemptCount,
+      last_error: partialUpdate.lastError,
+      processed_at: partialUpdate.processedAt,
+    };
+  }
+
+  /**
+   * Get or create inbox event for idempotency tracking
+   * Returns existing if already processed, otherwise creates new
+   */
+  async getOrCreate(
+    outboxEventId: string | number,
+    consumerName: string,
+  ): Promise<InboxEvent> {
+    // Try to find existing
+    let inboxEvent = await this.prisma.inbox_event.findFirst({
+      where: {
+        outbox_event_id: this.toDatabaseId(outboxEventId),
+        consumer_name: consumerName,
+      },
+    });
+
+    // Create if doesn't exist
+    if (!inboxEvent) {
+      inboxEvent = await this.prisma.inbox_event.create({
+        data: {
+          outbox_event_id: this.toDatabaseId(outboxEventId),
+          consumer_name: consumerName,
+          status: InboxEventStatus.RECEIVED,
+          attempt_count: 0,
+        },
+      });
+    }
+
+    return this.toDomainEvent(inboxEvent as InboxEventRecord);
+  }
+
+  /**
+   * Update inbox event status
+   */
+  async updateStatus(
+    inboxEventId: string | number,
+    status: InboxEventStatus,
+    partialUpdate?: {
+      attemptCount?: number;
+      lastError?: string | null;
+      processedAt?: Date | null;
+    },
+  ): Promise<InboxEvent> {
+    const inboxEvent = await this.prisma.inbox_event.update({
+      where: { id: this.toDatabaseId(inboxEventId) },
+      data: {
+        status,
+        ...this.toDatabaseUpdate(partialUpdate),
+      },
+    });
+
+    return this.toDomainEvent(inboxEvent as InboxEventRecord);
+  }
+
+  /**
+   * Mark inbox event as processing
+   */
+  async markProcessing(inboxEventId: string | number): Promise<InboxEvent> {
+    return this.updateStatus(inboxEventId, InboxEventStatus.PROCESSING);
+  }
+
+  /**
+   * Mark inbox event as successfully processed
+   */
+  async markProcessed(inboxEventId: string | number): Promise<InboxEvent> {
+    return this.updateStatus(inboxEventId, InboxEventStatus.PROCESSED, {
+      processedAt: new Date(),
+    });
+  }
+
+  /**
+   * Mark inbox event as failed
+   */
+  async markFailed(
+    inboxEventId: string | number,
+    error: string,
+  ): Promise<InboxEvent> {
+    const record = await this.prisma.inbox_event.findUnique({
+      where: { id: this.toDatabaseId(inboxEventId) },
+    });
+    if (!record) {
+      throw new Error(`Inbox event ${inboxEventId} not found`);
+    }
+
+    const inboxEvent = this.toDomainEvent(record as InboxEventRecord);
+
+    return this.updateStatus(inboxEventId, InboxEventStatus.FAILED, {
+      attemptCount: inboxEvent.attemptCount + 1,
+      lastError: error,
+    });
+  }
+
+  /**
+   * Mark inbox event as skipped
+   */
+  async markSkipped(inboxEventId: string | number): Promise<InboxEvent> {
+    return this.updateStatus(inboxEventId, InboxEventStatus.SKIPPED);
+  }
+
+  /**
+   * Increment attempt count
+   */
+  async incrementAttempt(inboxEventId: string | number): Promise<InboxEvent> {
+    const record = await this.prisma.inbox_event.findUnique({
+      where: { id: this.toDatabaseId(inboxEventId) },
+    });
+    if (!record) {
+      throw new Error(`Inbox event ${inboxEventId} not found`);
+    }
+
+    const inboxEvent = this.toDomainEvent(record as InboxEventRecord);
+
+    return this.updateStatus(inboxEventId, inboxEvent.status, {
+      attemptCount: inboxEvent.attemptCount + 1,
+    });
+  }
+
+  /**
+   * Get inbox event by ID
+   */
+  async getById(inboxEventId: string | number): Promise<InboxEvent | null> {
+    const inboxEvent = await this.prisma.inbox_event.findUnique({
+      where: { id: this.toDatabaseId(inboxEventId) },
+    });
+
+    return inboxEvent ? this.toDomainEvent(inboxEvent as InboxEventRecord) : null;
+  }
+
+  /**
+   * Check if event was already processed by consumer
+   */
+  async isProcessed(
+    outboxEventId: string | number,
+    consumerName: string,
+  ): Promise<boolean> {
+    const inboxEvent = await this.prisma.inbox_event.findFirst({
+      where: {
+        outbox_event_id: this.toDatabaseId(outboxEventId),
+        consumer_name: consumerName,
+      },
+    });
+
+    return (
+      inboxEvent !== null &&
+      (inboxEvent as InboxEventRecord).status === InboxEventStatus.PROCESSED
+    );
+  }
+
+  /**
+   * Count unprocessed items for a consumer
+   */
+  async countUnprocessed(consumerName: string): Promise<number> {
+    return this.prisma.inbox_event.count({
+      where: {
+        consumer_name: consumerName,
+        status: {
+          notIn: [InboxEventStatus.PROCESSED, InboxEventStatus.SKIPPED],
+        },
+      },
+    });
+  }
+}

package/src/integration/services/index.ts

@@ -0,0 +1,12 @@
+export * from './domain-event.publisher';
+export * from './event-subscriber.registry';
+export * from './inbox.service';
+export * from './integration-developer-api.service';
+export * from './integration-link.service';
+export * from './integration-settings.service';
+export * from './outbox-polling.coordinator';
+export * from './outbox.notifier';
+export * from './outbox.processor';
+export * from './outbox.processor.job';
+export * from './outbox.service';
+