@hiliosai/sdk 0.1.0

package/src/middlewares/permissions.middleware.ts

@@ -0,0 +1,162 @@
+import type {ActionSchema, Service} from 'moleculer';
+
+import {PERMISSIONS, ROLE_PERMISSIONS} from '../configs';
+import {isDev} from '../env';
+
+import {PermissionError} from '../errors';
+import type {AppContext} from '../types';
+
+export type Permission =
+  | keyof typeof PERMISSIONS
+  | string
+  | ((ctx: AppContext, action: ActionSchema) => Promise<boolean> | boolean);
+
+// Middleware interface for type safety
+export interface ActionWithPermissions extends ActionSchema {
+  permissions?: Permission | Permission[];
+}
+
+const permissionHandlers = {
+  [PERMISSIONS.AUTHENTICATED]: async (ctx: AppContext) => !!ctx.meta.user?.id,
+
+  [PERMISSIONS.TENANT_OWNER]: async (ctx: AppContext) =>
+    ctx.meta.user?.roles.includes(PERMISSIONS.OWNER) ?? false,
+
+  [PERMISSIONS.TENANT_MEMBER]: async (ctx: AppContext) =>
+    !!(
+      ctx.meta.user?.tenantId &&
+      ctx.meta.tenantId &&
+      ctx.meta.user.tenantId === ctx.meta.tenantId
+    ),
+};
+
+export const PermissionsMiddleware = {
+  // Wrap local action handlers
+  localAction(
+    handler: (...args: unknown[]) => unknown,
+    action: ActionWithPermissions
+  ) {
+    // If permissions are not defined, return original handler
+    if (!action.permissions) {
+      return handler;
+    }
+
+    const permissions = Array.isArray(action.permissions)
+      ? action.permissions
+      : [action.permissions];
+
+    const permissionNames: string[] = [];
+    const permissionFunctions: Array<
+      (ctx: AppContext, action: ActionSchema) => Promise<boolean> | boolean
+    > = [];
+
+    // Process each permission
+    permissions.forEach((permission) => {
+      if (typeof permission === 'function') {
+        // Add custom permission function
+        permissionFunctions.push(permission);
+        return;
+      }
+
+      if (typeof permission === 'string') {
+        // Check if it's a built-in permission handler
+        if (permission in permissionHandlers) {
+          const handler =
+            permissionHandlers[permission as keyof typeof permissionHandlers];
+          permissionFunctions.push(handler);
+          return;
+        }
+
+        // Otherwise, treat as a permission name to check against user roles
+        permissionNames.push(permission);
+        return;
+      }
+    });
+
+    return async function CheckPermissionsMiddleware(
+      this: Service,
+      ctx: AppContext
+    ) {
+      let hasAccess = false;
+
+      // Check if user has OWNER role (super admin within tenant)
+      if (ctx.meta.user?.roles.includes(PERMISSIONS.OWNER)) {
+        hasAccess = true;
+      }
+
+      // REMOVED: DEVELOPER role bypass - security vulnerability
+      // Developers must have explicit permissions like any other role
+
+      // Check custom permission functions
+      if (!hasAccess && permissionFunctions.length > 0) {
+        const results = await Promise.allSettled(
+          permissionFunctions.map((fn) => fn(ctx, action))
+        );
+
+        hasAccess = results.some(
+          (result) => result.status === 'fulfilled' && !!result.value
+        );
+
+        // Log failed permissions without exposing details
+        const failures = results.filter((r) => r.status === 'rejected');
+        if (failures.length > 0) {
+          ctx.broker.logger.warn(
+            `${failures.length} permission functions failed`,
+            {
+              action: action.name,
+              userId: ctx.meta.user?.id,
+            }
+          );
+        }
+      }
+
+      // Check named permissions against user roles
+      if (!hasAccess && permissionNames.length > 0) {
+        const userRoles = ctx.meta.user?.roles ?? [];
+
+        // Check if user has any role that includes the required permissions
+        hasAccess = userRoles.some((role: string) => {
+          const rolePermissions = ROLE_PERMISSIONS[role] ?? [];
+          return permissionNames.some((permName) =>
+            rolePermissions.includes(permName)
+          );
+        });
+      }
+
+      // Throw error if access denied
+      if (!hasAccess) {
+        const user = ctx.meta.user;
+        ctx.broker.logger.warn('Access denied:', {
+          action: action.name,
+          userId: user?.id,
+          userRoles: user?.roles,
+          tenantId: ctx.meta.tenantId,
+          requiredPermissions: permissions,
+        });
+
+        // Sanitize error details for production
+        const errorDetails = isDev
+          ? {
+              action: action.name,
+              requiredPermissions: permissions.map((p) =>
+                typeof p === 'function' ? '[Function]' : String(p)
+              ),
+              userRoles: user?.roles ?? [],
+              userId: user?.id,
+              tenantId: ctx.meta.tenantId,
+            }
+          : {
+              action: action.name,
+            };
+
+        throw new PermissionError(
+          'You do not have permission to perform this action',
+          errorDetails
+        );
+      }
+
+      // Call the original handler
+      return handler.call(this, ctx);
+    };
+  },
+};

package/src/service/define-integration.ts

@@ -0,0 +1,237 @@
+import type {Context, ServiceSchema} from 'moleculer';
+
+import type {AppContext} from '../types/context';
+import type {IntegrationConfig} from '../types/integration';
+import type {
+  NormalizedMessage,
+  PlatformMessage,
+  WebhookEvent,
+} from '../types/message';
+import type {
+  IntegrationServiceConfig,
+  IntegrationServiceSchema,
+} from '../types/service';
+
+export function defineIntegration<
+  TPlatformMessage extends PlatformMessage = PlatformMessage,
+  TSettings = unknown,
+  TContext extends AppContext = AppContext
+>(
+  config: IntegrationServiceConfig<TPlatformMessage, TSettings, TContext>
+): IntegrationServiceSchema<TPlatformMessage, TSettings> {
+  // Create actions from integration methods
+  const actions: ServiceSchema['actions'] = {
+    'webhook.receive': {
+      rest: {
+        method: 'POST',
+        path: '/webhook',
+      },
+      params: {
+        tenantId: 'string',
+        channelId: 'string',
+        integrationId: 'string',
+        platform: 'string',
+        rawPayload: 'any',
+        rawBody: {type: 'string', optional: true},
+        headers: 'object',
+        timestamp: 'number',
+      },
+      async handler(ctx: Context<WebhookEvent>) {
+        const webhook = ctx.params;
+
+        // Validate webhook if method exists
+        if (config.validateWebhook) {
+          const isValid = await config.validateWebhook(webhook);
+          if (!isValid) {
+            throw new Error('Invalid webhook');
+          }
+        }
+
+        // Validate signature if method exists
+        if (config.validateSignature) {
+          const isValidSignature = config.validateSignature(webhook);
+          if (!isValidSignature) {
+            throw new Error('Invalid webhook signature');
+          }
+        }
+
+        // Normalize the message
+        const normalizedMessages = await config.normalize(webhook);
+
+        // Process each message
+        for (const message of normalizedMessages) {
+          // Emit event for further processing
+          ctx.emit('integration.message.received', {
+            tenantId: webhook.tenantId,
+            channelId: webhook.channelId,
+            integrationId: webhook.integrationId,
+            platform: webhook.platform,
+            message,
+          });
+        }
+
+        return {success: true, messages: normalizedMessages.length};
+      },
+    },
+
+    'message.send': {
+      rest: {
+        method: 'POST',
+        path: '/send',
+      },
+      params: {
+        message: 'object',
+        config: 'object',
+      },
+      async handler(ctx: Context) {
+        const {message, config: integrationConfig} = ctx.params as {
+          message: NormalizedMessage;
+          config: IntegrationConfig;
+        };
+
+        // Transform message if method exists
+        if (config.transform) {
+          await config.transform(message, integrationConfig);
+        }
+
+        // Send the message - cast ctx to expected type
+        const result = await config.sendMessage(
+          ctx as TContext,
+          message,
+          integrationConfig
+        );
+
+        // Emit event based on result
+        if (result.success) {
+          ctx.emit('integration.message.sent', {
+            messageId: result.messageId,
+            platform: config.integration.platform,
+            metadata: result.metadata,
+          });
+        } else {
+          ctx.emit('integration.message.failed', {
+            error: result.error,
+            platform: config.integration.platform,
+            message,
+          });
+        }
+
+        return result;
+      },
+    },
+
+    'health.check': {
+      rest: {
+        method: 'GET',
+        path: '/health',
+      },
+      params: {
+        config: {type: 'object', optional: true},
+      },
+      async handler(ctx: Context<{config?: IntegrationConfig}>) {
+        if (config.checkHealth) {
+          const integrationConfig = ctx.params.config;
+          if (integrationConfig) {
+            return await config.checkHealth(ctx as TContext, integrationConfig);
+          }
+        }
+        return {
+          status: 'healthy',
+          message: 'Integration is running',
+        };
+      },
+    },
+
+    'webhook.verify': {
+      rest: {
+        method: 'GET',
+        path: '/webhook',
+      },
+      params: {
+        mode: 'string',
+        token: 'string',
+        challenge: 'string',
+      },
+      handler(ctx: Context<{mode: string; token: string; challenge: string}>) {
+        if (config.verifyWebhook) {
+          const result = config.verifyWebhook(ctx.params);
+          return result ?? '';
+        }
+        return ctx.params.challenge;
+      },
+    },
+
+    'integration.status': {
+      rest: {
+        method: 'GET',
+        path: '/status',
+      },
+      handler() {
+        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,
+        };
+      },
+    },
+
+    'credentials.validate': {
+      params: {
+        credentials: 'object',
+      },
+      async handler(ctx: Context<{credentials: Record<string, string>}>) {
+        if (config.validateCredentials) {
+          return await config.validateCredentials(ctx.params.credentials);
+        }
+        return true;
+      },
+    },
+  };
+
+  // Add any custom actions
+  if (config.actions) {
+    Object.assign(actions, config.actions);
+  }
+
+  // Create the service schema
+  const serviceSchema: IntegrationServiceSchema<TPlatformMessage, TSettings> = {
+    name: config.name,
+    version: config.version,
+    settings: config.settings as TSettings,
+    dependencies: config.dependencies,
+    metadata: {
+      ...config.metadata,
+      integration: config.integration,
+    },
+    actions,
+    events: config.events ?? {},
+    methods: config.methods ?? {},
+    hooks: config.hooks ?? {},
+    created: config.created,
+    started: config.started,
+    stopped: config.stopped,
+
+    // Integration-specific methods
+    integration: config.integration,
+    normalize: config.normalize,
+    transform: config.transform,
+    validateWebhook: config.validateWebhook,
+    sendMessage: config.sendMessage,
+    verifyWebhook: config.verifyWebhook,
+    checkHealth: config.checkHealth,
+    validateCredentials: config.validateCredentials,
+    validateSignature: config.validateSignature,
+  };
+
+  // Remove undefined properties
+  Object.keys(serviceSchema).forEach((key) => {
+    if (serviceSchema[key as keyof typeof serviceSchema] === undefined) {
+      delete serviceSchema[key as keyof typeof serviceSchema];
+    }
+  });
+
+  return serviceSchema;
+}

package/src/service/define-service.ts

@@ -0,0 +1,77 @@
+import omit from 'lodash/omit';
+import type {ServiceSchema as MoleculerServiceSchema} from 'moleculer';
+
+import {
+  ContextHelpersMiddleware,
+  MemoizeMixin,
+  PermissionsMiddleware,
+  createDatasourceMiddleware,
+  createCacheMiddleware,
+} from '../middlewares';
+import type {ServiceConfig} from '../types/service';
+
+/**
+ * Define a service
+ *
+ * @example
+ * ```typescript
+ * export default defineService({
+ *   name: 'user',
+ *
+ *   // Per-service cache configuration
+ *   cache: {
+ *     redisUrl: 'redis://localhost:6379',
+ *     ttl: 10 * 60 * 1000, // 10 minutes
+ *     namespace: 'user-service',
+ *   },
+ *
+ *   actions: {
+ *     // Action with schema
+ *     getUser: {
+ *       params: {
+ *         id: 'string'
+ *       },
+ *       handler(ctx) {
+ *         // ctx is typed as AppContext with cache helpers
+ *         const { tenantId } = ctx.meta;
+ *         
+ *         // Use cache helpers
+ *         return ctx.cache.wrap(`user:${ctx.params.id}`, async () => {
+ *           return { id: ctx.params.id, tenantId };
+ *         });
+ *       }
+ *     },
+ *
+ *     // Direct handler
+ *     listUsers(ctx) {
+ *       // ctx is typed as AppContext
+ *       return [];
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export function defineService<TDatasources = unknown, TSettings = unknown>(
+  config: ServiceConfig<TSettings, TDatasources>
+): MoleculerServiceSchema<TSettings> {
+  const serviceSchema = omit(config, [
+    'datasources',
+    'cache',
+  ]) as unknown as MoleculerServiceSchema<TSettings>;
+
+  const datasources = config.datasources ?? {};
+  const cacheOptions = config.cache;
+
+  // TODO: Add mixins config support
+  return {
+    ...serviceSchema,
+    mixins: [
+      createDatasourceMiddleware(datasources),
+      ...(cacheOptions ? [createCacheMiddleware(cacheOptions)] : []),
+      MemoizeMixin(),
+      PermissionsMiddleware,
+      ContextHelpersMiddleware,
+      ...(serviceSchema.mixins ?? []),
+    ],
+  };
+}

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

@@ -0,0 +1,8 @@
+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

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

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

@@ -0,0 +1,31 @@
+import {defineService} from '../define-service';
+import {datasources, type UserDatasourceTypes} from './datasources';
+
+export type GetUserActionInputParams = {
+  id: string;
+};
+
+export default defineService<UserDatasourceTypes>({
+  name: 'test',
+  datasources,
+  cache: {
+    redisUrl: process.env.USER_SERVICE_REDIS_URL,
+    ttl: 5 * 60 * 1000, // 5 minutes
+    namespace: 'user-service',
+  },
+  actions: {
+    user: {
+      params: {
+        id: 'string',
+      },
+      handler(ctx) {
+        const userDs = ctx.datasources.user;
+        
+        // Use cache with wrap pattern
+        return ctx.cache.wrap(`user:${ctx.params.id}`, async () => {
+          return userDs.getUser();
+        });
+      },
+    },
+  },
+});

package/src/types/context.ts

@@ -0,0 +1,41 @@
+import type {Context} from 'moleculer';
+import type {User} from './user';
+import type {Tenant} from './tenant';
+import type {CacheHelpers} from '../middlewares/cache.middleware';
+
+export interface AppMeta {
+  user?: User;
+  tenantId?: string;
+  tenantName?: string;
+  userId?: string;
+  integrationId?: string;
+  channelId?: string;
+  requestId?: string;
+  userAgent?: string;
+  clientIP?: string;
+  [key: string]: unknown;
+}
+
+export interface PermissionHelpers {
+  hasPermission(permission: string): boolean;
+  hasRole(role: string): boolean;
+  isTenantMember(): boolean;
+  isTenantOwner(): boolean;
+  ensureUser(): User;
+  ensureTenant(): Tenant;
+  // New enhanced helpers
+  getUserPermissions(): Promise<string[]>;
+  auditLog(action: string, resource?: unknown, metadata?: Record<string, unknown>): void;
+  createError(message: string, code: string, statusCode?: number): Error;
+}
+
+export type AppContext<
+  TDatasources = unknown,
+  TParams = unknown,
+  TMeta extends AppMeta = AppMeta,
+  TLocals = unknown
+> = Context<TParams, TMeta, TLocals> &
+  PermissionHelpers & {
+    datasources: TDatasources;
+    cache: CacheHelpers;
+  };

package/src/types/datasource.ts

@@ -0,0 +1,23 @@
+/**
+ * Utility types for datasources
+ */
+
+/**
+ * Extract instance types from a datasource constructor registry
+ *
+ * @example
+ * ```typescript
+ * const datasources = {
+ *   user: UserDatasource,
+ *   whatsapp: WhatsAppDatasource,
+ * };
+ *
+ * type MyDatasources = DatasourceInstanceTypes<typeof datasources>;
+ * // Results in: { user: UserDatasource; whatsapp: WhatsAppDatasource; }
+ * ```
+ */
+export type DatasourceInstanceTypes<
+  T extends Record<string, new (...args: unknown[]) => unknown>
+> = {
+  [K in keyof T]: InstanceType<T[K]>;
+};

package/src/types/index.ts

@@ -0,0 +1,8 @@
+export * from './platform';
+export * from './message';
+export * from './integration';
+export * from './context';
+export * from './service';
+export * from './user';
+export * from './tenant';
+export * from './datasource';

package/src/types/integration.ts

@@ -0,0 +1,48 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type {
+  IntegrationCapability,
+  IntegrationPlatform,
+  IntegrationStatus,
+} from './platform';
+
+export interface BaseIntegration {
+  id: string;
+  name: string;
+  platform: IntegrationPlatform;
+  version: string;
+  status: IntegrationStatus;
+  capabilities: IntegrationCapability[];
+  description?: string;
+  icon?: string;
+  documentationUrl?: string;
+}
+
+export interface IntegrationConfig {
+  id: string;
+  tenantId: string;
+  integrationId: string;
+  name: string;
+  version: string;
+  status: IntegrationStatus;
+  config: {
+    webhookUrl?: string;
+    autoReply?: boolean;
+    businessHours?: BusinessHoursConfig;
+    [key: string]: any;
+  };
+  credentials: Record<string, string>;
+  metadata?: Record<string, any>;
+  createdAt?: Date;
+  updatedAt?: Date;
+}
+
+export interface BusinessHoursConfig {
+  enabled: boolean;
+  timezone: string;
+  schedule: {
+    [day: string]: {
+      start: string;
+      end: string;
+    };
+  };
+}