@hiliosai/sdk 0.1.3 → 0.1.5

package/package.json

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

package/src/configs/constants.ts

@@ -66,6 +66,19 @@ export const CHANNELS = {
   },
 } as const;
 
+/**
+ * Integration-specific channel names
+ */
+export const INTEGRATION_CHANNELS = {
+  // Message events
+  MESSAGE_RECEIVED: `${NAMESPACE}.processing.message.received`,
+  MESSAGE_SENT: `${NAMESPACE}.processing.message.sent`,
+  MESSAGE_FAILED: `${NAMESPACE}.processing.message.failed`,
+} as const;
+
+export type IntegrationChannelName =
+  (typeof INTEGRATION_CHANNELS)[keyof typeof INTEGRATION_CHANNELS];
+
 /**
  * Channel Configuration Constants
  */

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,41 +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',
-        integrationId: 'string',
-        platform: 'string',
-        rawPayload: 'any',
-        rawBody: {type: 'string', optional: true},
+        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)) {
@@ -134,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};
       },
     },
 
@@ -163,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,
@@ -184,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,
           });
         }
 
@@ -271,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',
@@ -309,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,
@@ -324,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 && {
@@ -339,7 +394,6 @@ export function defineIntegration<
         validateSignature: config.validateSignature,
       }),
     },
-    hooks: config.hooks ?? {},
     created: config.created,
     started: config.started,
     stopped: config.stopped,
@@ -350,5 +404,5 @@ export function defineIntegration<
     ...baseService,
     // Only add the integration spec
     spec: config.spec,
-  } as IntegrationServiceSchema<TPlatformMessage, TSettings>;
+  } as IntegrationServiceSchema<TSettings>;
 }

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

@@ -74,16 +74,14 @@ export interface NormalizedMessage {
 
 export interface PlatformMessage {
   platform: IntegrationPlatform;
-  rawPayload: any;
+  payload: any;
 }
 
-export interface WebhookEvent {
+export interface WebhookEvent<TPayload = any> {
   tenantId: string;
   channelId: string;
-  integrationId: string;
   platform: IntegrationPlatform;
-  rawPayload: any;
-  rawBody?: string;
+  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.rawPayload.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;
-  }
-}

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

@@ -1,23 +0,0 @@
-import {defineService} from '../define-service';
-import {datasources, type UserDatasourceTypes} from './datasources';
-
-export type GetUserActionInputParams = {
-  id: string;
-};
-
-export default defineService<UserDatasourceTypes>({
-  name: 'test',
-  datasources,
-  actions: {
-    user: {
-      params: {
-        id: 'string',
-      },
-      handler(ctx) {
-        const userDs = ctx.datasources.user;
-
-        return userDs.getUser();
-      },
-    },
-  },
-});