@hiliosai/sdk 0.1.2 → 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
 
@@ -139,9 +139,9 @@ Integration-specific logic is implemented as service methods:
 
 ```typescript
 import {defineIntegration} from '@pkg/sdk';
-import type {BaseIntegration, NormalizedMessage, WebhookEvent} from '@pkg/sdk';
+import type {BaseSpec, NormalizedMessage, WebhookEvent} from '@pkg/sdk';
 
-const whatsappIntegration: BaseIntegration = {
+const whatsappIntegration: BaseSpec = {
   id: 'whatsapp-business',
   name: 'WhatsApp Business',
   platform: 'whatsapp',
@@ -152,13 +152,13 @@ const whatsappIntegration: BaseIntegration = {
 
 export default defineIntegration({
   name: 'whatsapp',
-  integration: whatsappIntegration,
-  
+  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',
@@ -296,13 +296,13 @@ import {WhatsAppDatasource} from './datasources';
 
 export default defineIntegration({
   name: 'whatsapp',
-  integration: whatsappIntegration,
-  
+  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.2",
+  "version": "0.1.4",
   "type": "module",
   "exports": {
     ".": "./src/index.ts"

package/src/service/define-integration.ts

@@ -91,15 +91,11 @@ export function defineIntegration<
     i_receiveWebhook: {
       rest: {
         method: 'POST' as const,
-        path: '/webhook',
+        path: '/:tenantId',
       },
       params: {
         tenantId: 'string',
-        channelId: 'string',
-        integrationId: 'string',
-        platform: 'string',
-        rawPayload: 'any',
-        rawBody: {type: 'string', optional: true},
+        payload: 'object',
         headers: 'object',
         timestamp: 'number',
       },
@@ -181,20 +177,20 @@ export function defineIntegration<
           () => config.sendMessage(ctx, message, integrationConfig),
           3,
           1000,
-          `Send message via ${config.integration.platform}`
+          `Send message via ${config.spec.platform}`
         );
 
         // Emit event based on result
         if (result.success) {
           ctx.emit('integration.message.sent', {
             messageId: result.messageId,
-            platform: config.integration.platform,
+            platform: config.spec.platform,
             metadata: result.metadata,
           });
         } else {
           ctx.emit('integration.message.failed', {
             error: result.error,
-            platform: config.integration.platform,
+            platform: config.spec.platform,
             message,
           });
         }
@@ -224,12 +220,12 @@ export function defineIntegration<
 
           return {
             status: 'healthy',
-            message: `${config.integration.name} integration is running`,
+            message: `${config.spec.name} integration is running`,
             details: {
-              integration: config.integration.id,
-              version: config.integration.version,
+              id: config.spec.id,
+              version: config.spec.version,
               timestamp: new Date().toISOString(),
-              capabilities: config.integration.capabilities,
+              capabilities: config.spec.capabilities,
             },
           };
         } catch (error: unknown) {
@@ -238,7 +234,7 @@ export function defineIntegration<
             status: 'unhealthy',
             message: err.message,
             details: {
-              integration: config.integration.id,
+              id: config.spec.id,
               timestamp: new Date().toISOString(),
             },
           };
@@ -249,9 +245,10 @@ export function defineIntegration<
     i_verifyWebhook: {
       rest: {
         method: 'GET' as const,
-        path: '/webhook',
+        path: '/:tenantId',
       },
       params: {
+        tenantId: 'string',
         mode: 'string',
         token: 'string',
         challenge: 'string',
@@ -259,7 +256,7 @@ export function defineIntegration<
       handler(
         ctx: AppContext<
           TDatasources,
-          {mode: string; token: string; challenge: string}
+          {tenantId: string; mode: string; token: string; challenge: string}
         >
       ): string {
         if (config.verifyWebhook) {
@@ -277,12 +274,12 @@ export function defineIntegration<
       },
       handler(): object {
         return {
-          id: config.integration.id,
-          name: config.integration.name,
-          platform: config.integration.platform,
-          version: config.integration.version,
-          status: config.integration.status,
-          capabilities: config.integration.capabilities,
+          id: config.spec.id,
+          name: config.spec.name,
+          platform: config.spec.platform,
+          version: config.spec.version,
+          status: config.spec.status,
+          capabilities: config.spec.capabilities,
         };
       },
     },
@@ -316,7 +313,7 @@ export function defineIntegration<
     datasources: config.datasources,
     metadata: {
       ...config.metadata,
-      integration: config.integration,
+      spec: config.spec,
     },
     actions,
     events: config.events ?? {},
@@ -338,7 +335,6 @@ export function defineIntegration<
         validateSignature: config.validateSignature,
       }),
     },
-    hooks: config.hooks ?? {},
     created: config.created,
     started: config.started,
     stopped: config.stopped,
@@ -347,7 +343,7 @@ export function defineIntegration<
   // Return the service schema - integration methods are available via service methods
   return {
     ...baseService,
-    // Only add the integration metadata
-    integration: config.integration,
+    // Only add the integration spec
+    spec: config.spec,
   } as IntegrationServiceSchema<TPlatformMessage, TSettings>;
 }

package/src/types/integration.ts

@@ -5,7 +5,7 @@ import type {
   IntegrationStatus,
 } from './platform';
 
-export interface BaseIntegration {
+export interface BaseSpec {
   id: string;
   name: string;
   platform: IntegrationPlatform;

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

package/src/types/service.ts

@@ -9,7 +9,7 @@ import type {
 
 import type {DatasourceConstructorRegistry} from '../middlewares/datasource.middleware';
 import type {AppContext} from './context';
-import type {BaseIntegration, IntegrationConfig} from './integration';
+import type {BaseSpec, IntegrationConfig} from './integration';
 import type {
   NormalizedMessage,
   PlatformMessage,
@@ -134,7 +134,7 @@ export interface IntegrationServiceConfig<
   TDatasources = unknown
 > extends ServiceConfig<TSettings, TDatasources> {
   name: string;
-  integration: BaseIntegration;
+  spec: BaseSpec;
 
   // Core integration methods
   normalize(webhook: WebhookEvent): Promise<NormalizedMessage[]>;
@@ -177,7 +177,7 @@ export interface IntegrationServiceSchema<
   TPlatformMessage extends PlatformMessage = PlatformMessage,
   TSettings = unknown
 > extends MoleculerServiceSchema<TSettings> {
-  integration: BaseIntegration;
+  spec: BaseSpec;
   normalize(webhook: WebhookEvent): Promise<NormalizedMessage[]>;
   transform?(
     message: NormalizedMessage,