@hiliosai/sdk 0.1.4 → 0.1.6

package/src/datasources/prisma.datasource.ts

@@ -0,0 +1,325 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import {isDev, isTest} from '../env';
+import type {AppContext} from '../types/context';
+import {AbstractDatasource} from './base.datasource';
+
+// Generic Prisma Client interface - will be provided by generated client
+interface PrismaClientLike {
+  $connect(): Promise<void>;
+  $disconnect(): Promise<void>;
+  $queryRaw(
+    query: TemplateStringsArray,
+    ...values: unknown[]
+  ): Promise<unknown>;
+  $transaction<T>(
+    fn: (client: PrismaClientLike) => Promise<T>,
+    options?: {
+      maxWait?: number;
+      timeout?: number;
+    }
+  ): Promise<T>;
+  $extends<T>(extension: T): PrismaClientLike & T;
+  [key: string]: unknown;
+}
+
+// Extension interfaces for common production patterns
+export interface SoftDeleteExtension {
+  // Adds soft delete functionality to models
+  softDelete: {
+    [model: string]: {
+      delete: (args: any) => Promise<any>;
+      deleteMany: (args: any) => Promise<any>;
+      restore: (args: any) => Promise<any>;
+    };
+  };
+}
+
+export interface AuditTrailExtension {
+  // Adds audit trail functionality
+  $auditTrail: {
+    getHistory: (model: string, id: string) => Promise<any[]>;
+    getChanges: (
+      model: string,
+      id: string,
+      from?: Date,
+      to?: Date
+    ) => Promise<any[]>;
+  };
+}
+
+export interface TenantExtension {
+  // Adds multi-tenant filtering
+  $tenant: {
+    setContext: (tenantId: string) => void;
+    getCurrentTenant: () => string | null;
+  };
+}
+
+// Global singleton pattern for Prisma Client
+declare global {
+  var __prisma: PrismaClientLike | undefined;
+}
+
+/**
+ * Prisma datasource that follows singleton pattern and best practices
+ * Supports both provided client instances and automatic initialization
+ *
+ * @example
+ * ```typescript
+ * // Option 1: Let datasource create singleton client
+ * datasources: {
+ *   prisma: PrismaDatasource
+ * }
+ *
+ * // Option 2: Provide custom client
+ * const customClient = new PrismaClient({...});
+ * datasources: {
+ *   prisma: () => new PrismaDatasource(customClient)
+ * }
+ * ```
+ */
+export class PrismaDatasource<
+  TPrismaClient extends PrismaClientLike = PrismaClientLike,
+  TContext = AppContext
+> extends AbstractDatasource<TContext> {
+  readonly name = 'prisma';
+  private _client: TPrismaClient | null = null;
+  private providedClient: TPrismaClient | null = null;
+
+  constructor(prismaClient?: TPrismaClient) {
+    super();
+    this.providedClient = prismaClient ?? null;
+  }
+
+  /**
+   * Get Prisma client instance (singleton pattern)
+   */
+  get client(): TPrismaClient {
+    this._client ??= this.initializePrismaClient();
+
+    // Update tenant context from current service context
+    this.updateTenantFromContext();
+
+    return this._client;
+  }
+
+  /**
+   * Initialize Prisma client using singleton pattern or provided instance
+   */
+  private initializePrismaClient(): TPrismaClient {
+    // Option 1: Use provided client instance
+    if (this.providedClient) {
+      this.broker.logger.info('Using provided PrismaClient instance');
+      return this.providedClient;
+    }
+
+    // Option 2: Use global singleton (recommended for most cases)
+    if (!globalThis.__prisma) {
+      this.broker.logger.info('Creating new PrismaClient singleton');
+      const baseClient = this.createClient();
+      globalThis.__prisma = this.applyExtensions(baseClient);
+    } else {
+      this.broker.logger.info('Using existing PrismaClient singleton');
+    }
+
+    return globalThis.__prisma as TPrismaClient;
+  }
+
+  /**
+   * Create a new Prisma client instance
+   * Override this method in subclasses to provide the actual PrismaClient
+   */
+  protected createClient(): TPrismaClient {
+    throw new Error(
+      'createClient() must be implemented by subclass or provide PrismaClient in constructor. ' +
+        'Example: class MyPrismaDataSource extends PrismaDatasource { ' +
+        'protected createClient() { return new PrismaClient(); } }'
+    );
+  }
+
+  /**
+   * Apply extensions to the Prisma client
+   * Override this method to add production extensions like soft delete, audit trails, etc.
+   */
+  protected applyExtensions(client: TPrismaClient): TPrismaClient {
+    // Base implementation returns client as-is
+    // Override in subclass to add extensions:
+    // return client.$extends(softDeleteExtension).$extends(auditExtension)
+    return client;
+  }
+
+  /**
+   * Get extended client with all applied extensions
+   */
+  get extendedClient(): TPrismaClient {
+    return this.applyExtensions(this.client);
+  }
+
+  /**
+   * Initialize datasource - called after broker injection
+   */
+  async init(): Promise<void> {
+    this.broker.logger.info('Initializing Prisma datasource');
+  }
+
+  /**
+   * Called automatically when context is injected
+   * Sets tenant context from service context if available
+   */
+  private updateTenantFromContext(): void {
+    const tenantId = (this.context as any)?.meta?.tenantId;
+    if (tenantId && typeof tenantId === 'string') {
+      this.setTenantContext(tenantId);
+    }
+  }
+
+  /**
+   * Connect to database - called when service starts
+   */
+  async connect(): Promise<void> {
+    try {
+      this.broker.logger.info('Connecting to database via Prisma');
+      await this.client.$connect();
+      this.broker.logger.info('Successfully connected to database');
+    } catch (error) {
+      this.broker.logger.error('Failed to connect to database:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Disconnect from database - called when service stops
+   */
+  async disconnect(): Promise<void> {
+    try {
+      this.broker.logger.info('Disconnecting from database');
+      await this.client.$disconnect();
+      this.broker.logger.info('Successfully disconnected from database');
+    } catch (error) {
+      this.broker.logger.error('Error disconnecting from database:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Health check - verify database connectivity
+   */
+  async healthCheck(): Promise<boolean> {
+    try {
+      this.broker.logger.info('Running Prisma health check');
+
+      // Simple connectivity test
+      await this.client.$queryRaw`SELECT 1`;
+
+      this.broker.logger.info('Prisma health check passed');
+      return true;
+    } catch (error) {
+      this.broker.logger.error('Prisma health check failed:', error);
+      return false;
+    }
+  }
+
+  /**
+   * Clear/reset data - useful for testing
+   */
+  async clear(): Promise<void> {
+    if (isTest || isDev) {
+      this.broker.logger.warn(
+        'Clearing database (only allowed in test/dev mode)'
+      );
+
+      // Get all model names dynamically
+      const modelNames = Object.keys(this.client).filter(
+        (key) => !key.startsWith('_') && !key.startsWith('$')
+      );
+
+      // Delete all data in reverse order (to handle foreign keys)
+      for (const modelName of modelNames.reverse()) {
+        try {
+          const model = this.client[modelName as keyof TPrismaClient] as {
+            deleteMany?: () => Promise<unknown>;
+          };
+          if (model.deleteMany) {
+            await model.deleteMany();
+          }
+        } catch (error) {
+          // Some models might not support deleteMany, skip them
+          this.broker.logger.debug(`Could not clear ${modelName}:`, error);
+        }
+      }
+    } else {
+      throw new Error(
+        'Database clear is only allowed in test/development environments'
+      );
+    }
+  }
+
+  /**
+   * Transaction wrapper with proper error handling
+   */
+  async transaction<T>(
+    fn: (tx: TPrismaClient) => Promise<T>,
+    options?: {
+      maxWait?: number;
+      timeout?: number;
+    }
+  ): Promise<T> {
+    try {
+      return await this.client.$transaction(
+        (tx) => fn(tx as TPrismaClient),
+        options
+      );
+    } catch (error) {
+      this.broker.logger.error('Transaction failed:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Set tenant context for multi-tenant applications
+   * Requires tenant extension to be applied
+   */
+  setTenantContext(tenantId: string): void {
+    const tenantClient = this.client as any;
+    if (tenantClient.$setTenant) {
+      tenantClient.$setTenant(tenantId);
+      this.broker.logger.debug('Tenant context set:', {tenantId});
+    } else {
+      this.broker.logger.warn(
+        'Tenant extension not available - setTenantContext ignored'
+      );
+    }
+  }
+
+  /**
+   * Get current tenant context
+   */
+  getCurrentTenant(): string | null {
+    const tenantClient = this.client as any;
+    if (tenantClient.$getCurrentTenant) {
+      return tenantClient.$getCurrentTenant();
+    }
+    return null;
+  }
+
+  /**
+   * Execute with tenant context (automatically restores previous context)
+   */
+  async withTenant<T>(tenantId: string, fn: () => Promise<T>): Promise<T> {
+    const previousTenant = this.getCurrentTenant();
+
+    try {
+      this.setTenantContext(tenantId);
+      return await fn();
+    } finally {
+      if (previousTenant) {
+        this.setTenantContext(previousTenant);
+      } else {
+        const tenantClient = this.client as any;
+        if (tenantClient.$clearTenant) {
+          tenantClient.$clearTenant();
+        }
+      }
+    }
+  }
+}

package/src/mixins/datasource.mixin.ts

@@ -59,6 +59,11 @@ export function DatasourceMixin(
      * Initialize datasources and store on service
      */
     async created() {
+      // Inject broker into datasources
+      for (const [, datasource] of Object.entries(datasourceInstances)) {
+        (datasource as any).broker = this.broker;
+      }
+
       // Call init() on datasources that have it
       for (const [, datasource] of Object.entries(datasourceInstances)) {
         if (typeof (datasource as any).init === 'function') {
@@ -102,8 +107,15 @@ export function DatasourceMixin(
     hooks: {
       before: {
         '*': function injectDatasources(ctx) {
+          const datasources = (this as any).$datasources ?? {};
+
+          // Inject current context into all datasources
+          for (const [, datasource] of Object.entries(datasources)) {
+            (datasource as any).context = ctx;
+          }
+
           // Inject datasources into the context
-          (ctx as AppContext).datasources = (this as any).$datasources ?? {};
+          (ctx as AppContext).datasources = datasources;
         },
       },
     },

package/src/service/define-integration.ts

@@ -1,18 +1,25 @@
 import crypto from 'crypto';
 
-import {defineService} from './define-service';
+import {CHANNEL_CONFIG, INTEGRATION_CHANNELS} from '../configs/constants';
+import type {DatasourceConstructorRegistry} from '../middlewares/datasource.middleware';
+import {
+  type IntegrationMessageFailedPayload,
+  type IntegrationMessageReceivedPayload,
+  type IntegrationMessageSentPayload,
+} from '../types/channels';
 import type {AppContext} from '../types/context';
 import type {IntegrationConfig} from '../types/integration';
 import type {
   NormalizedMessage,
-  PlatformMessage,
   SendResult,
   WebhookEvent,
 } from '../types/message';
+import type {DatasourceInstanceTypes} from '../types/datasource';
 import type {
   IntegrationServiceConfig,
   IntegrationServiceSchema,
 } from '../types/service';
+import {defineService} from './define-service';
 
 /**
  * Security helpers for webhook validation
@@ -38,13 +45,6 @@ const SecurityHelpers = {
   validateTimestamp(timestamp: number, maxAgeMs = 5 * 60 * 1000): boolean {
     return Date.now() - timestamp <= maxAgeMs;
   },
-
-  /**
-   * Generate correlation ID for request tracking
-   */
-  generateCorrelationId(): string {
-    return crypto.randomUUID();
-  },
 };
 
 /**
@@ -76,37 +76,52 @@ async function executeWithRetry<T>(
 }
 
 export function defineIntegration<
-  TPlatformMessage extends PlatformMessage = PlatformMessage,
   TSettings = unknown,
-  TDatasources = unknown
+  TDatasourceConstructors extends DatasourceConstructorRegistry = DatasourceConstructorRegistry
 >(
-  config: IntegrationServiceConfig<
-    TPlatformMessage,
-    TSettings,
-    AppContext<TDatasources>
-  >
-): IntegrationServiceSchema<TPlatformMessage, TSettings> {
+  config: IntegrationServiceConfig<TSettings, TDatasourceConstructors>
+): IntegrationServiceSchema<TSettings> {
+  // Type alias for inferred datasource instances
+  type TDatasources = DatasourceInstanceTypes<TDatasourceConstructors>;
+
   // Create actions from integration methods
   const actions = {
     i_receiveWebhook: {
       rest: {
         method: 'POST' as const,
-        path: '/:tenantId',
+        path: '/:channelId',
       },
       params: {
-        tenantId: 'string',
+        channelId: 'string',
         payload: 'object',
         headers: 'object',
         timestamp: 'number',
       },
       async handler(
-        ctx: AppContext<TDatasources, WebhookEvent>
-      ): Promise<{success: boolean; messages: number}> {
-        const webhook = ctx.params;
-        const correlationId = SecurityHelpers.generateCorrelationId();
+        ctx: AppContext<
+          TDatasources,
+          {
+            channelId: string;
+            payload: object;
+            headers: object;
+            timestamp: number;
+          }
+        >
+      ): Promise<{success: boolean; messages: number; failed: number}> {
+        const {channelId, payload, headers, timestamp} = ctx.params;
+
+        // TODO: Look up channel configuration by channelId
+        // const channel = await getChannelConfig(channelId);
+        // For now, we'll construct webhook from meta
 
-        // Add correlation ID to context for tracking
-        ctx.meta.correlationId = correlationId;
+        const webhook: WebhookEvent = {
+          tenantId: ctx.meta.tenantId ?? 'unknown', // Should come from channel lookup
+          channelId,
+          platform: config.spec.platform,
+          payload, // Raw webhook payload from gateway
+          headers: headers as Record<string, string>,
+          timestamp,
+        };
 
         // Validate timestamp to prevent replay attacks
         if (!SecurityHelpers.validateTimestamp(webhook.timestamp)) {
@@ -130,25 +145,49 @@ export function defineIntegration<
         }
 
         // Normalize the message
-        const normalizedMessages: NormalizedMessage[] = await config.normalize(
-          webhook
+        const normalizedMessages = await config.normalize(webhook);
+
+        // Process each message with reliable delivery (parallel)
+        const results = await Promise.allSettled(
+          normalizedMessages.map(async (message) => {
+            const payload: IntegrationMessageReceivedPayload = {
+              tenantId: webhook.tenantId,
+              channelId: webhook.channelId,
+              platform: webhook.platform,
+              message,
+              timestamp: Date.now(),
+            };
+
+            // Send to reliable message channel (NATS JetStream)
+            return ctx.broker.sendToChannel(
+              INTEGRATION_CHANNELS.MESSAGE_RECEIVED,
+              payload,
+              CHANNEL_CONFIG.HIGH_PRIORITY
+            );
+          })
         );
 
-        // Process each message
-        for (const message of normalizedMessages) {
-          // Emit event for further processing with correlation ID
-          ctx.emit('integration.message.received', {
-            correlationId,
-            tenantId: webhook.tenantId,
-            channelId: webhook.channelId,
-            integrationId: webhook.integrationId,
-            platform: webhook.platform,
-            message,
-            timestamp: Date.now(),
-          });
+        // Count successful vs failed messages
+        const successful = results.filter(
+          (result) => result.status === 'fulfilled'
+        ).length;
+        const failed = results.filter(
+          (result) => result.status === 'rejected'
+        ).length;
+
+        // Log failures for monitoring (but don't fail the entire webhook)
+        if (failed > 0) {
+          const failures = results
+            .filter((result) => result.status === 'rejected')
+            .map((result) => (result as PromiseRejectedResult).reason);
+
+          ctx.broker.logger.warn(
+            `Webhook processing partial failure: ${failed}/${normalizedMessages.length} messages failed`,
+            {failures}
+          );
         }
 
-        return {success: true, messages: normalizedMessages.length};
+        return {success: true, messages: successful, failed};
       },
     },
 
@@ -159,20 +198,26 @@ export function defineIntegration<
       },
       params: {
         message: 'object',
-        config: 'object',
+        channelId: 'string',
       },
-      async handler(ctx: AppContext<TDatasources>): Promise<unknown> {
-        const {message, config: integrationConfig} = ctx.params as {
-          message: NormalizedMessage;
-          config: IntegrationConfig;
-        };
+      async handler(
+        ctx: AppContext<
+          TDatasources,
+          {
+            message: NormalizedMessage;
+            channelId: string;
+          }
+        >
+      ): Promise<SendResult> {
+        const {message, channelId} = ctx.params;
 
-        // Transform message if method exists
-        if (config.transform) {
-          await config.transform(message, integrationConfig);
+        // Load channel configuration
+        const integrationConfig = await config.getChannelConfig(ctx, channelId);
+        if (!integrationConfig) {
+          throw new Error(`Channel configuration not found: ${channelId}`);
         }
 
-        // Send the message with retry mechanism
+        // Send the message with retry mechanism (transformation happens inside sendMessage)
         const result: SendResult = await executeWithRetry(
           () => config.sendMessage(ctx, message, integrationConfig),
           3,
@@ -180,18 +225,49 @@ export function defineIntegration<
           `Send message via ${config.spec.platform}`
         );
 
-        // Emit event based on result
-        if (result.success) {
-          ctx.emit('integration.message.sent', {
+        // Send reliable events based on result (with error handling)
+        try {
+          if (result.success) {
+            const sentPayload: IntegrationMessageSentPayload = {
+              tenantId: integrationConfig.tenantId,
+              channelId,
+              platform: config.spec.platform,
+              messageId: result.messageId,
+              metadata: result.metadata,
+              timestamp: Date.now(),
+            };
+
+            await ctx.broker.sendToChannel(
+              INTEGRATION_CHANNELS.MESSAGE_SENT,
+              sentPayload,
+              CHANNEL_CONFIG.DEFAULTS
+            );
+          } else {
+            const failedPayload: IntegrationMessageFailedPayload = {
+              tenantId: integrationConfig.tenantId,
+              channelId,
+              platform: config.spec.platform,
+              error: result.error?.message ?? 'Unknown error',
+              message,
+              timestamp: Date.now(),
+            };
+
+            await ctx.broker.sendToChannel(
+              INTEGRATION_CHANNELS.MESSAGE_FAILED,
+              failedPayload,
+              CHANNEL_CONFIG.DEFAULTS
+            );
+          }
+        } catch (channelError: unknown) {
+          // Log channel error but don't fail the send operation
+          const err =
+            channelError instanceof Error
+              ? channelError
+              : new Error(String(channelError));
+          ctx.broker.logger.warn('Failed to send message event to channel', {
+            error: err.message,
             messageId: result.messageId,
             platform: config.spec.platform,
-            metadata: result.metadata,
-          });
-        } else {
-          ctx.emit('integration.message.failed', {
-            error: result.error,
-            platform: config.spec.platform,
-            message,
           });
         }
 
@@ -267,23 +343,6 @@ export function defineIntegration<
       },
     },
 
-    i_status: {
-      rest: {
-        method: 'GET' as const,
-        path: '/status',
-      },
-      handler(): object {
-        return {
-          id: config.spec.id,
-          name: config.spec.name,
-          platform: config.spec.platform,
-          version: config.spec.version,
-          status: config.spec.status,
-          capabilities: config.spec.capabilities,
-        };
-      },
-    },
-
     i_validateCredentials: {
       params: {
         credentials: 'object',
@@ -305,7 +364,7 @@ export function defineIntegration<
   }
 
   // Use defineService to get all the mixins and proper setup
-  const baseService = defineService<TDatasources, TSettings>({
+  const baseService = defineService<TSettings, TDatasourceConstructors>({
     name: config.name,
     version: config.version,
     settings: config.settings as TSettings,
@@ -320,12 +379,12 @@ export function defineIntegration<
     methods: {
       ...(config.methods ?? {}),
       // Add integration-specific methods to the service methods (filter out undefined)
-      // normalize is required, no need for conditional
+      // Required methods - no need for conditional
       normalize: config.normalize,
-      ...(config.transform && {transform: config.transform}),
-      ...(config.validateWebhook && {validateWebhook: config.validateWebhook}),
-      // sendMessage is required, no need for conditional
+      getChannelConfig: config.getChannelConfig,
       sendMessage: config.sendMessage,
+      // Optional methods
+      ...(config.validateWebhook && {validateWebhook: config.validateWebhook}),
       ...(config.verifyWebhook && {verifyWebhook: config.verifyWebhook}),
       ...(config.checkHealth && {checkHealth: config.checkHealth}),
       ...(config.validateCredentials && {
@@ -345,5 +404,5 @@ export function defineIntegration<
     ...baseService,
     // Only add the integration spec
     spec: config.spec,
-  } as IntegrationServiceSchema<TPlatformMessage, TSettings>;
+  } as IntegrationServiceSchema<TSettings>;
 }