@hed-hog/core 0.0.295 → 0.0.296

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';
+

package/src/integration/services/integration-developer-api.service.ts

@@ -0,0 +1,96 @@
+import { Injectable } from '@nestjs/common';
+import {
+    DomainEvent,
+    EventHandler,
+    IntegrationLink,
+    LinkType,
+    OutboxEvent,
+    SubscriberDefinition,
+} from '../types';
+import {
+    DomainEventPublisher,
+    PublishDomainEventInput,
+    PublishDomainEventOptions,
+} from './domain-event.publisher';
+import { EventSubscriberRegistry } from './event-subscriber.registry';
+import {
+    CreateIntegrationLinkDto,
+    IntegrationLinkPersistenceClient,
+    IntegrationLinkService,
+} from './integration-link.service';
+
+export interface IntegrationSubscriptionInput {
+  eventName: string;
+  consumerName: string;
+  handler: EventHandler;
+  priority?: number;
+}
+
+export interface IntegrationLinkQuery {
+  module: string;
+  entityType: string;
+  entityId: string;
+}
+
+@Injectable()
+export class IntegrationDeveloperApiService {
+  constructor(
+    private readonly publisher: DomainEventPublisher,
+    private readonly subscriberRegistry: EventSubscriberRegistry,
+    private readonly linkService: IntegrationLinkService,
+  ) {}
+
+  async publishEvent(
+    input: PublishDomainEventInput,
+    options?: PublishDomainEventOptions,
+  ): Promise<OutboxEvent> {
+    return this.publisher.publishEvent(input, options);
+  }
+
+  async publishEvents(
+    events: Array<DomainEvent | PublishDomainEventInput>,
+    options?: PublishDomainEventOptions,
+  ): Promise<OutboxEvent[]> {
+    return this.publisher.publishEvents(events, options);
+  }
+
+  subscribe(input: IntegrationSubscriptionInput): void {
+    this.subscriberRegistry.subscribe(
+      input.eventName,
+      input.consumerName,
+      input.handler,
+      input.priority || 0,
+    );
+  }
+
+  subscribeMany(definitions: SubscriberDefinition[]): void {
+    this.subscriberRegistry.subscribeMany(definitions);
+  }
+
+  async createLink(
+    dto: CreateIntegrationLinkDto,
+    persistenceClient?: IntegrationLinkPersistenceClient,
+  ): Promise<IntegrationLink> {
+    return this.linkService.createLink(dto, persistenceClient);
+  }
+
+  async findLinksBySource(query: IntegrationLinkQuery): Promise<IntegrationLink[]> {
+    return this.linkService.findOutbound(
+      query.module,
+      query.entityType,
+      query.entityId,
+    );
+  }
+
+  async findLinksByTarget(query: IntegrationLinkQuery): Promise<IntegrationLink[]> {
+    return this.linkService.findInbound(
+      query.module,
+      query.entityType,
+      query.entityId,
+    );
+  }
+
+  async findLinksByType(linkType: LinkType): Promise<IntegrationLink[]> {
+    return this.linkService.findByLinkType(linkType);
+  }
+}

package/src/integration/services/integration-link.service.ts

@@ -0,0 +1,154 @@
+import { PrismaService } from '@hed-hog/api-prisma';
+import { Injectable } from '@nestjs/common';
+import { IntegrationLink, LinkType } from '../types';
+
+export interface CreateIntegrationLinkDto {
+  sourceModule: string;
+  sourceEntityType: string;
+  sourceEntityId: string;
+  targetModule: string;
+  targetEntityType: string;
+  targetEntityId: string;
+  linkType: LinkType;
+  metadata?: Record<string, any>;
+}
+
+export interface IntegrationLinkPersistenceClient {
+  integrationLink: PrismaService['integrationLink'];
+}
+
+@Injectable()
+export class IntegrationLinkService {
+  constructor(private readonly prisma: PrismaService) {}
+
+  /**
+   * Create a link between entities from different modules
+   */
+  async createLink(
+    dto: CreateIntegrationLinkDto,
+    persistenceClient?: IntegrationLinkPersistenceClient,
+  ): Promise<IntegrationLink> {
+    const client = persistenceClient ?? this.prisma;
+
+    return client.integrationLink.create({
+      data: {
+        sourceModule: dto.sourceModule,
+        sourceEntityType: dto.sourceEntityType,
+        sourceEntityId: dto.sourceEntityId,
+        targetModule: dto.targetModule,
+        targetEntityType: dto.targetEntityType,
+        targetEntityId: dto.targetEntityId,
+        linkType: dto.linkType,
+        metadata: dto.metadata || null,
+      },
+    });
+  }
+
+  /**
+   * Find all links originating from a source entity
+   */
+  async findOutbound(
+    sourceModule: string,
+    sourceEntityType: string,
+    sourceEntityId: string,
+  ): Promise<IntegrationLink[]> {
+    return this.prisma.integrationLink.findMany({
+      where: {
+        sourceModule,
+        sourceEntityType,
+        sourceEntityId,
+      },
+    });
+  }
+
+  /**
+   * Find all links terminating at a target entity
+   */
+  async findInbound(
+    targetModule: string,
+    targetEntityType: string,
+    targetEntityId: string,
+  ): Promise<IntegrationLink[]> {
+    return this.prisma.integrationLink.findMany({
+      where: {
+        targetModule,
+        targetEntityType,
+        targetEntityId,
+      },
+    });
+  }
+
+  /**
+   * Find links of a specific type
+   */
+  async findByLinkType(linkType: LinkType): Promise<IntegrationLink[]> {
+    return this.prisma.integrationLink.findMany({
+      where: { linkType },
+    });
+  }
+
+  /**
+   * Delete a link
+   */
+  async deleteLink(linkId: string): Promise<IntegrationLink> {
+    return this.prisma.integrationLink.delete({
+      where: { id: linkId },
+    });
+  }
+
+  /**
+   * Get link by ID
+   */
+  async getById(linkId: string): Promise<IntegrationLink | null> {
+    return this.prisma.integrationLink.findUnique({
+      where: { id: linkId },
+    });
+  }
+
+  /**
+   * Find bidirectional link between two entities
+   */
+  async findBidirectional(
+    module1: string,
+    entity1Type: string,
+    entity1Id: string,
+    module2: string,
+    entity2Type: string,
+    entity2Id: string,
+  ): Promise<IntegrationLink | null> {
+    // Look for forward or reverse direction
+    const link = await this.prisma.integrationLink.findFirst({
+      where: {
+        OR: [
+          {
+            sourceModule: module1,
+            sourceEntityType: entity1Type,
+            sourceEntityId: entity1Id,
+            targetModule: module2,
+            targetEntityType: entity2Type,
+            targetEntityId: entity2Id,
+          },
+          {
+            sourceModule: module2,
+            sourceEntityType: entity2Type,
+            sourceEntityId: entity2Id,
+            targetModule: module1,
+            targetEntityType: entity1Type,
+            targetEntityId: entity1Id,
+          },
+        ],
+      },
+    });
+
+    return link;
+  }
+
+  /**
+   * Count links from a module
+   */
+  async countFromModule(sourceModule: string): Promise<number> {
+    return this.prisma.integrationLink.count({
+      where: { sourceModule },
+    });
+  }
+}

package/src/integration/services/integration-settings.service.ts

@@ -0,0 +1,128 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { SettingService } from '../../setting/setting.service';
+
+export interface IntegrationRuntimeSettings {
+  outboxEnabled: boolean;
+  outboxProcessorEnabled: boolean;
+  startupDrainEnabled: boolean;
+  pollingIntervalMs: number;
+  idlePollingIntervalMs: number;
+  batchSize: number;
+  startupDrainBatchSize: number;
+  maxAttempts: number;
+  processingLeaseMs: number;
+  retryBaseDelayMs: number;
+  deadLetterEnabled: boolean;
+}
+
+@Injectable()
+export class IntegrationSettingsService {
+  private readonly logger = new Logger(IntegrationSettingsService.name);
+
+  constructor(private readonly settingService: SettingService) {}
+
+  async getRuntimeSettings(): Promise<IntegrationRuntimeSettings> {
+    const values = await this.settingService.getSettingValues([
+      'outbox-enabled',
+      'outbox-processor-enabled',
+      'outbox-startup-drain-enabled',
+      'outbox-polling-interval-ms',
+      'outbox-idle-polling-interval-ms',
+      'outbox-batch-size',
+      'outbox-startup-drain-batch-size',
+      'outbox-max-attempts',
+      'outbox-processing-lease-ms',
+      'outbox-retry-base-delay-ms',
+      'outbox-dead-letter-enabled',
+    ]);
+
+    const pollingIntervalMs = this.getPositiveInt(
+      values['outbox-polling-interval-ms'],
+      5000,
+      100,
+      'outbox-polling-interval-ms',
+    );
+
+    let idlePollingIntervalMs = this.getPositiveInt(
+      values['outbox-idle-polling-interval-ms'],
+      30000,
+      100,
+      'outbox-idle-polling-interval-ms',
+    );
+
+    if (idlePollingIntervalMs < pollingIntervalMs) {
+      this.logger.warn(
+        `Setting outbox-idle-polling-interval-ms (${idlePollingIntervalMs}) is lower than outbox-polling-interval-ms (${pollingIntervalMs}). Using ${pollingIntervalMs}.`,
+      );
+      idlePollingIntervalMs = pollingIntervalMs;
+    }
+
+    return {
+      outboxEnabled: this.getBoolean(values['outbox-enabled'], true),
+      outboxProcessorEnabled: this.getBoolean(
+        values['outbox-processor-enabled'],
+        true,
+      ),
+      startupDrainEnabled: this.getBoolean(
+        values['outbox-startup-drain-enabled'],
+        true,
+      ),
+      pollingIntervalMs,
+      idlePollingIntervalMs,
+      batchSize: this.getPositiveInt(values['outbox-batch-size'], 10, 1, 'outbox-batch-size'),
+      startupDrainBatchSize: this.getPositiveInt(
+        values['outbox-startup-drain-batch-size'],
+        50,
+        1,
+        'outbox-startup-drain-batch-size',
+      ),
+      maxAttempts: this.getPositiveInt(values['outbox-max-attempts'], 3, 1, 'outbox-max-attempts'),
+      processingLeaseMs: this.getPositiveInt(
+        values['outbox-processing-lease-ms'],
+        30000,
+        1000,
+        'outbox-processing-lease-ms',
+      ),
+      retryBaseDelayMs: this.getPositiveInt(
+        values['outbox-retry-base-delay-ms'],
+        1000,
+        100,
+        'outbox-retry-base-delay-ms',
+      ),
+      deadLetterEnabled: this.getBoolean(values['outbox-dead-letter-enabled'], true),
+    };
+  }
+
+  private getPositiveInt(
+    value: unknown,
+    fallback: number,
+    min: number,
+    slug: string,
+  ): number {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed < min) {
+      this.logger.warn(
+        `Invalid ${slug} setting value (${String(value)}). Using fallback ${fallback}.`,
+      );
+      return fallback;
+    }
+
+    return Math.floor(parsed);
+  }
+
+  private getBoolean(value: unknown, fallback: boolean): boolean {
+    if (typeof value === 'boolean') {
+      return value;
+    }
+
+    if (value === 'true' || value === '1') {
+      return true;
+    }
+
+    if (value === 'false' || value === '0') {
+      return false;
+    }
+
+    return fallback;
+  }
+}