@hiliosai/sdk 0.1.3 → 0.1.4

package/INTEGRATION_SERVICE.md

@@ -9,7 +9,7 @@ Integration Services are specialized Moleculer services that provide a standardi
 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  
+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
@@ -25,15 +25,15 @@ graph TB
         DC[Discord]
         SL[Slack]
     end
-    
+
     subgraph "Integration Layer"
         subgraph "Integration Services"
             WAS[WhatsApp Service]
-            TGS[Telegram Service] 
+            TGS[Telegram Service]
             DCS[Discord Service]
             SLS[Slack Service]
         end
-        
+
         subgraph "Service Actions"
             RW[i_receiveWebhook]
             SM[i_sendMessage]
@@ -43,20 +43,20 @@ graph TB
             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]
@@ -69,29 +69,29 @@ graph TB
     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
 ```
@@ -109,29 +109,29 @@ graph TB
 
 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 |
+| 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 | ❌ |
+| 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
 
@@ -153,12 +153,12 @@ const whatsappIntegration: BaseSpec = {
 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.rawPayload.entry || []) {
+
+    for (const entry of webhook.payload.entry || []) {
       for (const change of entry.changes || []) {
         if (change.field === 'messages') {
           for (const message of change.value.messages || []) {
@@ -190,7 +190,7 @@ export default defineIntegration({
         }
       }
     }
-    
+
     return messages;
   },
 
@@ -198,7 +198,7 @@ export default defineIntegration({
   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`,
       {
@@ -235,14 +235,14 @@ export default defineIntegration({
   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=' + 
+
+    const expectedSignature = 'sha256=' +
       crypto.createHmac('sha256', secret)
         .update(webhook.rawBody || '')
         .digest('hex');
-    
+
     return SecurityHelpers.secureCompare(signature, expectedSignature);
   },
 
@@ -250,7 +250,7 @@ export default defineIntegration({
   verifyWebhook(params) {
     const { mode, token, challenge } = params;
     const verifyToken = process.env.WHATSAPP_VERIFY_TOKEN;
-    
+
     if (mode === 'subscribe' && token === verifyToken) {
       return challenge;
     }
@@ -268,7 +268,7 @@ export default defineIntegration({
           }
         }
       );
-      
+
       return {
         status: response.ok ? 'healthy' : 'unhealthy',
         message: response.ok ? 'WhatsApp API accessible' : 'WhatsApp API error',
@@ -297,12 +297,12 @@ 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,
@@ -321,20 +321,20 @@ export default defineIntegration({
     // 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;
   }
 });
@@ -345,7 +345,7 @@ export default defineIntegration({
 ### Inbound Message Flow
 
 1. **Webhook Received** → `i_receiveWebhook` action
-2. **Security Validation** → Timestamp, signature, payload checks  
+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
@@ -391,4 +391,4 @@ Integration services automatically inherit:
 - **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.
+This architecture provides a robust, scalable foundation for building messaging platform integrations while maintaining consistency, security, and observability across all platforms.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hiliosai/sdk",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "type": "module",
   "exports": {
     ".": "./src/index.ts"

package/src/service/define-integration.ts

@@ -95,11 +95,7 @@ export function defineIntegration<
       },
       params: {
         tenantId: 'string',
-        channelId: 'string',
-        integrationId: 'string',
-        platform: 'string',
-        rawPayload: 'any',
-        rawBody: {type: 'string', optional: true},
+        payload: 'object',
         headers: 'object',
         timestamp: 'number',
       },
@@ -339,7 +335,6 @@ export function defineIntegration<
         validateSignature: config.validateSignature,
       }),
     },
-    hooks: config.hooks ?? {},
     created: config.created,
     started: config.started,
     stopped: config.stopped,

package/src/types/message.ts

@@ -74,7 +74,7 @@ export interface NormalizedMessage {
 
 export interface PlatformMessage {
   platform: IntegrationPlatform;
-  rawPayload: any;
+  payload: any;
 }
 
 export interface WebhookEvent {
@@ -82,8 +82,7 @@ export interface WebhookEvent {
   channelId: string;
   integrationId: string;
   platform: IntegrationPlatform;
-  rawPayload: any;
-  rawBody?: string;
+  payload: any;
   headers: Record<string, string>;
   timestamp: number;
 }