@hiliosai/sdk 0.1.4 → 0.1.6

package/src/service/define-service.ts

@@ -2,6 +2,7 @@ import omit from 'lodash/omit';
 import type {ServiceSchema as MoleculerServiceSchema} from 'moleculer';
 
 import {MemoizeMixin} from '../middlewares';
+import type {DatasourceConstructorRegistry} from '../middlewares/datasource.middleware';
 import {DatasourceMixin} from '../mixins';
 import type {ServiceConfig} from '../types/service';
 
@@ -34,8 +35,11 @@ import type {ServiceConfig} from '../types/service';
  * });
  * ```
  */
-export function defineService<TDatasources = unknown, TSettings = unknown>(
-  config: ServiceConfig<TSettings, TDatasources>
+export function defineService<
+  TSettings = unknown,
+  TDatasourceConstructors extends DatasourceConstructorRegistry = DatasourceConstructorRegistry
+>(
+  config: ServiceConfig<TSettings, TDatasourceConstructors>
 ): MoleculerServiceSchema<TSettings> {
   const propsToOmit = ['datasources'];
   const serviceSchema = omit(

package/src/types/channels.ts

@@ -0,0 +1,60 @@
+import type {IntegrationPlatform} from './platform';
+import type {NormalizedMessage} from './message';
+
+/**
+ * Channel event payload types for reliable messaging via @moleculer/channels
+ */
+
+// Integration message events
+export interface IntegrationMessageReceivedPayload {
+  tenantId: string;
+  channelId: string;
+  platform: IntegrationPlatform;
+  message: NormalizedMessage;
+  timestamp: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface IntegrationMessageSentPayload {
+  tenantId: string;
+  channelId: string;
+  platform: IntegrationPlatform;
+  messageId?: string;
+  metadata?: Record<string, unknown>;
+  timestamp: number;
+}
+
+export interface IntegrationMessageFailedPayload {
+  tenantId: string;
+  channelId: string;
+  platform: IntegrationPlatform;
+  error: string; // Serialized error message
+  message?: NormalizedMessage;
+  timestamp: number;
+  retryCount?: number;
+  metadata?: Record<string, unknown>;
+}
+
+// System events
+export interface IntegrationRegisteredPayload {
+  tenantId: string;
+  channelId: string;
+  platform: IntegrationPlatform;
+  config: Record<string, unknown>;
+  timestamp: number;
+}
+
+export interface IntegrationUnregisteredPayload {
+  tenantId: string;
+  channelId: string;
+  platform: IntegrationPlatform;
+  timestamp: number;
+}
+
+// Re-export constants to avoid duplication
+export {
+  CHANNELS,
+  INTEGRATION_CHANNELS,
+  NAMESPACE,
+  type IntegrationChannelName,
+} from '../configs/constants';

package/src/types/context.ts

@@ -2,15 +2,32 @@ import type {Context} from 'moleculer';
 import type {Tenant} from './tenant';
 import type {User} from './user';
 
+// Moleculer Channels types
+export interface ChannelSendOptions {
+  group?: string;
+  maxInFlight?: number;
+  maxRetries?: number;
+  deadLettering?: {
+    enabled?: boolean;
+    queueName?: string;
+  };
+}
+
+export interface SendToChannelMethod {
+  (
+    channelName: string,
+    payload: unknown,
+    options?: ChannelSendOptions
+  ): Promise<void>;
+}
+
 export interface AppMeta {
   user?: User;
   tenantId?: string;
   tenantName?: string;
   userId?: string;
-  integrationId?: string;
   channelId?: string;
   requestId?: string;
-  correlationId?: string;
   userAgent?: string;
   clientIP?: string;
   [key: string]: unknown;
@@ -41,4 +58,7 @@ export type AppContext<
 > = Context<TParams, TMeta, TLocals> &
   PermissionHelpers & {
     datasources: TDatasources;
+    broker: Context['broker'] & {
+      sendToChannel: SendToChannelMethod;
+    };
   };

package/src/types/index.ts

@@ -6,3 +6,4 @@ export * from './service';
 export * from './user';
 export * from './tenant';
 export * from './datasource';
+export * from './channels';

package/src/types/integration.ts

@@ -20,7 +20,6 @@ export interface BaseSpec {
 export interface IntegrationConfig {
   id: string;
   tenantId: string;
-  integrationId: string;
   name: string;
   version: string;
   status: IntegrationStatus;

package/src/types/message.ts

@@ -77,12 +77,11 @@ export interface PlatformMessage {
   payload: any;
 }
 
-export interface WebhookEvent {
+export interface WebhookEvent<TPayload = any> {
   tenantId: string;
   channelId: string;
-  integrationId: string;
   platform: IntegrationPlatform;
-  payload: any;
+  payload: TPayload;
   headers: Record<string, string>;
   timestamp: number;
 }

package/src/types/service.ts

@@ -9,13 +9,10 @@ import type {
 
 import type {DatasourceConstructorRegistry} from '../middlewares/datasource.middleware';
 import type {AppContext} from './context';
+import type {DatasourceInstanceTypes} from './datasource';
 import type {BaseSpec, IntegrationConfig} from './integration';
-import type {
-  NormalizedMessage,
-  PlatformMessage,
-  SendResult,
-  WebhookEvent,
-} from './message';
+import type {NormalizedMessage, SendResult, WebhookEvent} from './message';
+
 
 // Type to infer TypeScript types from Moleculer parameter schemas
 type InferParamsType<T> = T extends Record<string, any>
@@ -121,28 +118,34 @@ export interface ServiceSchema<TSettings = unknown, TDatasources = unknown>
 // ServiceConfig is what users provide to defineService
 export type ServiceConfig<
   TSettings = unknown,
-  TDatasources = unknown
-> = ServiceSchema<TSettings, TDatasources> & {
-  datasources?: DatasourceConstructorRegistry;
+  TDatasourceConstructors extends DatasourceConstructorRegistry = DatasourceConstructorRegistry
+> = ServiceSchema<
+  TSettings,
+  DatasourceInstanceTypes<TDatasourceConstructors>
+> & {
+  datasources?: TDatasourceConstructors;
 };
 
 // Integration-specific types
 export interface IntegrationServiceConfig<
-  TPlatformMessage extends PlatformMessage = PlatformMessage,
   TSettings = unknown,
-  TContext extends AppContext = AppContext,
-  TDatasources = unknown
-> extends ServiceConfig<TSettings, TDatasources> {
+  TDatasourceConstructors extends DatasourceConstructorRegistry = DatasourceConstructorRegistry,
+  TContext extends AppContext<
+    DatasourceInstanceTypes<TDatasourceConstructors>
+  > = AppContext<DatasourceInstanceTypes<TDatasourceConstructors>>
+> extends ServiceConfig<TSettings, TDatasourceConstructors> {
   name: string;
   spec: BaseSpec;
 
   // Core integration methods
-  normalize(webhook: WebhookEvent): Promise<NormalizedMessage[]>;
-  transform?(
-    message: NormalizedMessage,
-    config: IntegrationConfig
-  ): Promise<TPlatformMessage>;
-  validateWebhook?(webhook: WebhookEvent): boolean;
+  normalize<TPayload = any>(
+    webhook: WebhookEvent<TPayload>
+  ): Promise<NormalizedMessage[]>;
+  getChannelConfig(
+    ctx: TContext,
+    channelId: string
+  ): Promise<IntegrationConfig | null>;
+  validateWebhook?<TPayload = any>(webhook: WebhookEvent<TPayload>): boolean;
   sendMessage(
     ctx: TContext,
     message: NormalizedMessage,
@@ -170,20 +173,20 @@ export interface IntegrationServiceConfig<
   validateCredentials?(credentials: Record<string, string>): Promise<boolean>;
 
   // Optional signature validation
-  validateSignature?(webhook: WebhookEvent): boolean;
+  validateSignature?<TPayload = any>(webhook: WebhookEvent<TPayload>): boolean;
 }
 
-export interface IntegrationServiceSchema<
-  TPlatformMessage extends PlatformMessage = PlatformMessage,
-  TSettings = unknown
-> extends MoleculerServiceSchema<TSettings> {
+export interface IntegrationServiceSchema<TSettings = unknown>
+  extends MoleculerServiceSchema<TSettings> {
   spec: BaseSpec;
-  normalize(webhook: WebhookEvent): Promise<NormalizedMessage[]>;
-  transform?(
-    message: NormalizedMessage,
-    config: IntegrationConfig
-  ): Promise<TPlatformMessage>;
-  validateWebhook?(webhook: WebhookEvent): boolean;
+  normalize<TPayload = any>(
+    webhook: WebhookEvent<TPayload>
+  ): Promise<NormalizedMessage[]>;
+  getChannelConfig(
+    ctx: AppContext,
+    channelId: string
+  ): Promise<IntegrationConfig | null>;
+  validateWebhook?<TPayload = any>(webhook: WebhookEvent<TPayload>): boolean;
   sendMessage(
     ctx: AppContext,
     message: NormalizedMessage,
@@ -203,5 +206,5 @@ export interface IntegrationServiceSchema<
     details?: Record<string, any>;
   }>;
   validateCredentials?(credentials: Record<string, string>): Promise<boolean>;
-  validateSignature?(webhook: WebhookEvent): boolean;
+  validateSignature?<TPayload = any>(webhook: WebhookEvent<TPayload>): boolean;
 }

package/src/types/user.ts

@@ -3,8 +3,8 @@ export const UserRole = {
   ADMIN: 'ADMIN',
   MANAGER: 'MANAGER',
   AGENT: 'AGENT',
-  VIEWER: 'VIEWER'
-} as const
+  VIEWER: 'VIEWER',
+} as const;
 
 export interface User {
   id: string;

package/INTEGRATION_SERVICE.md

@@ -1,394 +0,0 @@
-# Integration Service Architecture
-
-## Overview
-
-Integration Services are specialized Moleculer services that provide a standardized way to connect external messaging platforms (WhatsApp, Telegram, Discord, etc.) with the application. They handle webhook reception, message normalization, and platform-specific communication patterns.
-
-## Purpose
-
-The Integration Service pattern solves several key challenges:
-
-1. **Platform Abstraction**: Provides unified interface for different messaging platforms
-2. **Webhook Security**: Implements signature validation and replay attack prevention
-3. **Message Normalization**: Converts platform-specific messages to unified format
-4. **Retry Logic**: Handles transient failures with exponential backoff
-5. **Event Broadcasting**: Emits standardized events for message processing
-6. **Health Monitoring**: Provides health checks and status reporting
-
-## Architecture
-
-```mermaid
-graph TB
-    subgraph "External Platforms"
-        WA[WhatsApp]
-        TG[Telegram]
-        DC[Discord]
-        SL[Slack]
-    end
-
-    subgraph "Integration Layer"
-        subgraph "Integration Services"
-            WAS[WhatsApp Service]
-            TGS[Telegram Service]
-            DCS[Discord Service]
-            SLS[Slack Service]
-        end
-
-        subgraph "Service Actions"
-            RW[i_receiveWebhook]
-            SM[i_sendMessage]
-            HC[i_healthCheck]
-            VW[i_verifyWebhook]
-            ST[i_status]
-            VC[i_validateCredentials]
-        end
-    end
-
-    subgraph "Core Application"
-        subgraph "Message Processing"
-            MP[Message Processor]
-            MR[Message Router]
-            MS[Message Store]
-        end
-
-        subgraph "Event System"
-            EB[Event Bus]
-            EH[Event Handlers]
-        end
-    end
-
-    subgraph "Infrastructure"
-        DS[Datasources]
-        CA[Cache]
-        PE[Permissions]
-        CH[Context Helpers]
-    end
-
-    %% External webhook flows
-    WA -->|Webhook| WAS
-    TG -->|Webhook| TGS
-    DC -->|Webhook| DCS
-    SL -->|Webhook| SLS
-
-    %% Integration service actions
-    WAS --> RW
-    WAS --> SM
-    WAS --> HC
-
-    %% Service infrastructure
-    WAS --> DS
-    TGS --> CA
-    DCS --> PE
-    SLS --> CH
-
-    %% Event flows
-    RW -->|integration.message.received| EB
-    SM -->|integration.message.sent| EB
-    SM -->|integration.message.failed| EB
-
-    %% Processing flows
-    EB --> EH
-    EH --> MP
-    MP --> MR
-    MR --> MS
-
-    %% Response flows
-    MP -->|Send Response| SM
-```
-
-## Integration Service Structure
-
-### Core Components
-
-1. **defineIntegration()** - Factory function that creates integration services
-2. **Security Helpers** - Webhook validation, timestamp checking, correlation IDs
-3. **Retry Mechanism** - Exponential backoff for failed operations
-4. **Standard Actions** - Predefined actions for common integration operations
-
-### Standard Actions
-
-All integration services automatically get these actions:
-
-| Action                  | REST Endpoint    | Purpose                               |
-| ----------------------- | ---------------- | ------------------------------------- |
-| `i_receiveWebhook`      | `POST /webhook`  | Receive and process incoming webhooks |
-| `i_sendMessage`         | `POST /send`     | Send messages to external platform    |
-| `i_healthCheck`         | `GET /health`    | Check integration health status       |
-| `i_verifyWebhook`       | `GET /webhook`   | Verify webhook subscriptions          |
-| `i_status`              | `GET /status`    | Get integration status information    |
-| `i_validateCredentials` | `POST /validate` | Validate platform credentials         |
-
-### Service Methods
-
-Integration-specific logic is implemented as service methods:
-
-| Method                  | Purpose                                       | Required |
-| ----------------------- | --------------------------------------------- | -------- |
-| `normalize()`           | Convert platform message to unified format    | ✅        |
-| `sendMessage()`         | Send message to platform                      | ✅        |
-| `transform()`           | Transform outbound message to platform format | ❌        |
-| `validateWebhook()`     | Validate webhook payload structure            | ❌        |
-| `validateSignature()`   | Validate webhook signature                    | ❌        |
-| `verifyWebhook()`       | Handle webhook verification challenge         | ❌        |
-| `checkHealth()`         | Custom health check logic                     | ❌        |
-| `validateCredentials()` | Validate platform credentials                 | ❌        |
-
-## Usage Example
-
-### Basic WhatsApp Integration
-
-```typescript
-import {defineIntegration} from '@pkg/sdk';
-import type {BaseSpec, NormalizedMessage, WebhookEvent} from '@pkg/sdk';
-
-const whatsappIntegration: BaseSpec = {
-  id: 'whatsapp-business',
-  name: 'WhatsApp Business',
-  platform: 'whatsapp',
-  version: '1.0.0',
-  status: 'ACTIVE',
-  capabilities: ['SEND_MESSAGE', 'RECEIVE_MESSAGE', 'WEBHOOK_VALIDATION']
-};
-
-export default defineIntegration({
-  name: 'whatsapp',
-  spec: whatsappIntegration,
-
-  // Required: Convert WhatsApp webhook to normalized message
-  async normalize(webhook: WebhookEvent): Promise<NormalizedMessage[]> {
-    const messages: NormalizedMessage[] = [];
-
-    for (const entry of webhook.payload.entry || []) {
-      for (const change of entry.changes || []) {
-        if (change.field === 'messages') {
-          for (const message of change.value.messages || []) {
-            messages.push({
-              id: message.id,
-              conversationId: message.from,
-              from: {
-                id: message.from,
-                name: change.value.contacts?.[0]?.profile?.name,
-              },
-              to: {
-                id: webhook.tenantId,
-              },
-              content: {
-                type: message.type === 'text' ? 'TEXT' : 'FILE',
-                text: message.text?.body,
-                media: message.image ? {
-                  url: message.image.id,
-                  mimeType: message.image.mime_type
-                } : undefined
-              },
-              timestamp: parseInt(message.timestamp) * 1000,
-              platform: 'whatsapp',
-              metadata: {
-                phoneNumberId: change.value.metadata.phone_number_id
-              }
-            });
-          }
-        }
-      }
-    }
-
-    return messages;
-  },
-
-  // Required: Send message to WhatsApp
-  async sendMessage(ctx, message, config) {
-    const phoneNumberId = config.credentials.phoneNumberId;
-    const accessToken = config.credentials.accessToken;
-
-    const response = await fetch(
-      `https://graph.facebook.com/v18.0/${phoneNumberId}/messages`,
-      {
-        method: 'POST',
-        headers: {
-          'Authorization': `Bearer ${accessToken}`,
-          'Content-Type': 'application/json'
-        },
-        body: JSON.stringify({
-          messaging_product: 'whatsapp',
-          to: message.to.id,
-          text: { body: message.content.text }
-        })
-      }
-    );
-
-    if (!response.ok) {
-      const error = await response.text();
-      return {
-        success: false,
-        error: new Error(`WhatsApp API error: ${error}`)
-      };
-    }
-
-    const result = await response.json();
-    return {
-      success: true,
-      messageId: result.messages[0].id,
-      metadata: { phoneNumberId }
-    };
-  },
-
-  // Optional: Validate webhook signature
-  validateSignature(webhook) {
-    const signature = webhook.headers['x-hub-signature-256'];
-    const secret = process.env.WHATSAPP_WEBHOOK_SECRET;
-
-    if (!signature || !secret) return false;
-
-    const expectedSignature = 'sha256=' +
-      crypto.createHmac('sha256', secret)
-        .update(webhook.rawBody || '')
-        .digest('hex');
-
-    return SecurityHelpers.secureCompare(signature, expectedSignature);
-  },
-
-  // Optional: Handle webhook verification
-  verifyWebhook(params) {
-    const { mode, token, challenge } = params;
-    const verifyToken = process.env.WHATSAPP_VERIFY_TOKEN;
-
-    if (mode === 'subscribe' && token === verifyToken) {
-      return challenge;
-    }
-    return null;
-  },
-
-  // Optional: Custom health check
-  async checkHealth(ctx, config) {
-    try {
-      const response = await fetch(
-        `https://graph.facebook.com/v18.0/${config.credentials.phoneNumberId}`,
-        {
-          headers: {
-            'Authorization': `Bearer ${config.credentials.accessToken}`
-          }
-        }
-      );
-
-      return {
-        status: response.ok ? 'healthy' : 'unhealthy',
-        message: response.ok ? 'WhatsApp API accessible' : 'WhatsApp API error',
-        details: {
-          statusCode: response.status,
-          timestamp: new Date().toISOString()
-        }
-      };
-    } catch (error) {
-      return {
-        status: 'unhealthy',
-        message: error.message,
-        details: { timestamp: new Date().toISOString() }
-      };
-    }
-  }
-});
-```
-
-### Advanced Integration with Datasources and Cache
-
-```typescript
-import {defineIntegration} from '@pkg/sdk';
-import {WhatsAppDatasource} from './datasources';
-
-export default defineIntegration({
-  name: 'whatsapp',
-  spec: whatsappIntegration,
-
-  // Configure per-service datasources
-  datasources: {
-    whatsapp: WhatsAppDatasource
-  },
-
-  // Configure per-service cache
-  cache: {
-    redisUrl: process.env.WHATSAPP_REDIS_URL,
-    ttl: 5 * 60 * 1000, // 5 minutes
-    namespace: 'whatsapp'
-  },
-
-  async normalize(webhook) {
-    // Access datasource via context in actions
-    // this.datasources is not available in methods
-    // Use dependency injection pattern instead
-    return await this.processWebhookMessages(webhook);
-  },
-
-  async sendMessage(ctx, message, config) {
-    // Use cache for rate limiting
-    const rateLimitKey = `rate_limit:${config.credentials.phoneNumberId}`;
-    const currentCount = await ctx.cache.get(rateLimitKey) || 0;
-
-    if (currentCount >= 1000) {
-      return {
-        success: false,
-        error: new Error('Rate limit exceeded')
-      };
-    }
-
-    // Send message...
-    const result = await this.sendToWhatsApp(message, config);
-
-    // Update rate limit counter
-    await ctx.cache.set(rateLimitKey, currentCount + 1, 60 * 60 * 1000);
-
-    return result;
-  }
-});
-```
-
-## Event Flow
-
-### Inbound Message Flow
-
-1. **Webhook Received** → `i_receiveWebhook` action
-2. **Security Validation** → Timestamp, signature, payload checks
-3. **Message Normalization** → Convert to unified format
-4. **Event Emission** → `integration.message.received` event
-5. **Message Processing** → Application-specific logic
-6. **Response Generation** → Optional automated responses
-
-### Outbound Message Flow
-
-1. **Send Request** → `i_sendMessage` action
-2. **Message Transformation** → Convert to platform format
-3. **Retry Logic** → Exponential backoff for failures
-4. **Platform API Call** → Send via platform API
-5. **Event Emission** → `integration.message.sent` or `integration.message.failed`
-6. **Status Tracking** → Update message delivery status
-
-## Security Features
-
-### Webhook Validation
-
-- **Signature Verification**: HMAC-SHA256 validation using platform secrets
-- **Replay Attack Prevention**: Timestamp validation (5-minute window)
-- **Timing Attack Protection**: Constant-time string comparison
-- **Correlation IDs**: Request tracking for debugging and audit trails
-
-### Best Practices
-
-1. **Always validate webhook signatures** in production
-2. **Use environment variables** for secrets and tokens
-3. **Implement proper error handling** with structured errors
-4. **Add correlation IDs** for request tracking
-5. **Use retry logic** for transient failures
-6. **Monitor health endpoints** for platform availability
-7. **Cache frequently accessed data** to reduce API calls
-
-## Infrastructure Integration
-
-Integration services automatically inherit:
-
-- **Datasource Access**: Database connections, external APIs
-- **Cache Layer**: Redis/in-memory caching with TTL
-- **Permission System**: Role-based access control
-- **Context Helpers**: Common utilities and operations
-- **Memoization**: Action result caching
-- **Health Monitoring**: Automated health checks
-- **Event System**: Pub/sub event broadcasting
-
-This architecture provides a robust, scalable foundation for building messaging platform integrations while maintaining consistency, security, and observability across all platforms.

package/src/service/example-user/datasources/index.ts

@@ -1,8 +0,0 @@
-import type {DatasourceInstanceTypes} from '../../../types';
-import {UserDatasource} from './user.datasource';
-
-export const datasources = {
-  user: UserDatasource,
-};
-
-export type UserDatasourceTypes = DatasourceInstanceTypes<typeof datasources>;

package/src/service/example-user/datasources/user.datasource.ts

@@ -1,7 +0,0 @@
-import type {User} from '../../../types';
-
-export class UserDatasource {
-  getUser(): User {
-    return {} as User;
-  }
-}