@hiliosai/sdk 0.1.0

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@hiliosai/sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "build": "tsup",
+    "format": "bunx prettier --write ./**/*.{ts,json,md,yaml}"
+  },
+  "dependencies": {
+    "@keyv/redis": "5.1.5",
+    "@ltv/env": "4.0.3",
+    "keyv": "5.5.5",
+    "lodash": "4.17.21",
+    "moleculer": "0.14.35"
+  },
+  "devDependencies": {
+    "@hiliosai/prettier": "workspace:*",
+    "@hiliosai/typescript": "workspace:*",
+    "@pkg/dev-utils": "workspace:*",
+    "@types/lodash": "4.17.21",
+    "bun-types": "latest"
+  },
+  "prettier": "@hiliosai/prettier"
+}

package/src/configs/index.ts

@@ -0,0 +1 @@
+export * from './permissions';

package/src/configs/permissions.ts

@@ -0,0 +1,109 @@
+// Permission constants
+export const PERMISSIONS = {
+  // Authentication required
+  AUTHENTICATED: 'authenticated',
+
+  // Role-based permissions
+  OWNER: 'OWNER',
+  ADMIN: 'ADMIN',
+  MANAGER: 'MANAGER',
+  AGENT: 'AGENT',
+  VIEWER: 'VIEWER',
+  DEVELOPER: 'DEVELOPER',
+
+  // Entity-specific permissions
+  TENANT_OWNER: 'tenant.owner',
+  TENANT_MEMBER: 'tenant.member',
+
+  // Resource permissions
+  'users.read': 'users.read',
+  'users.write': 'users.write',
+  'users.delete': 'users.delete',
+  'tenants.read': 'tenants.read',
+  'tenants.write': 'tenants.write',
+  'tenants.delete': 'tenants.delete',
+  'conversations.read': 'conversations.read',
+  'conversations.write': 'conversations.write',
+  'conversations.delete': 'conversations.delete',
+  'messages.read': 'messages.read',
+  'messages.write': 'messages.write',
+  'settings.read': 'settings.read',
+  'settings.write': 'settings.write',
+  'config.read': 'config.read',
+  'config.write': 'config.write',
+  'billing.read': 'billing.read',
+  'billing.write': 'billing.write',
+} as const;
+
+// Role hierarchy and permissions mapping
+export const ROLE_PERMISSIONS: Record<string, string[]> = {
+  [PERMISSIONS.OWNER]: [
+    PERMISSIONS.AUTHENTICATED,
+    PERMISSIONS['users.read'],
+    PERMISSIONS['users.write'],
+    PERMISSIONS['users.delete'],
+    PERMISSIONS['tenants.read'],
+    PERMISSIONS['tenants.write'],
+    PERMISSIONS['tenants.delete'],
+    PERMISSIONS['conversations.read'],
+    PERMISSIONS['conversations.write'],
+    PERMISSIONS['conversations.delete'],
+    PERMISSIONS['messages.read'],
+    PERMISSIONS['messages.write'],
+    PERMISSIONS['settings.read'],
+    PERMISSIONS['settings.write'],
+    PERMISSIONS['config.read'],
+    PERMISSIONS['config.write'],
+    PERMISSIONS['billing.read'],
+    PERMISSIONS['billing.write'],
+  ],
+  [PERMISSIONS.ADMIN]: [
+    PERMISSIONS.AUTHENTICATED,
+    PERMISSIONS['users.read'],
+    PERMISSIONS['users.write'],
+    PERMISSIONS['users.delete'],
+    PERMISSIONS['tenants.read'],
+    PERMISSIONS['tenants.write'],
+    PERMISSIONS['tenants.delete'],
+    PERMISSIONS['conversations.read'],
+    PERMISSIONS['conversations.write'],
+    PERMISSIONS['conversations.delete'],
+    PERMISSIONS['messages.read'],
+    PERMISSIONS['messages.write'],
+    PERMISSIONS['settings.read'],
+    PERMISSIONS['settings.write'],
+    PERMISSIONS['config.read'],
+    PERMISSIONS['config.write'],
+    PERMISSIONS['billing.read'],
+  ],
+  [PERMISSIONS.MANAGER]: [
+    PERMISSIONS.AUTHENTICATED,
+    PERMISSIONS['users.read'],
+    PERMISSIONS['users.write'],
+    PERMISSIONS['conversations.read'],
+    PERMISSIONS['conversations.write'],
+    PERMISSIONS['messages.read'],
+    PERMISSIONS['messages.write'],
+    PERMISSIONS['settings.read'],
+    PERMISSIONS['settings.write'],
+  ],
+  [PERMISSIONS.AGENT]: [
+    PERMISSIONS.AUTHENTICATED,
+    PERMISSIONS['conversations.read'],
+    PERMISSIONS['conversations.write'],
+    PERMISSIONS['messages.read'],
+    PERMISSIONS['messages.write'],
+  ],
+  [PERMISSIONS.VIEWER]: [
+    PERMISSIONS.AUTHENTICATED,
+    PERMISSIONS['conversations.read'],
+    PERMISSIONS['messages.read'],
+  ],
+  [PERMISSIONS.DEVELOPER]: [
+    PERMISSIONS.AUTHENTICATED,
+    // Only specific debug/development permissions, not full access
+    'system.debug',
+    'health.check',
+    PERMISSIONS['config.read'],
+  ],
+};

package/src/env.ts

@@ -0,0 +1,12 @@
+import env from '@ltv/env';
+
+const nodeEnv = env.string('NODE_ENV', 'development');
+
+export const isDev = nodeEnv === 'development';
+export const isTest = nodeEnv === 'test';
+export const isProd = nodeEnv === 'production';
+export const REDIS_URL = env.string('REDIS_URL');
+
+export default env;
+export type Env = typeof env;
+export {nodeEnv};

package/src/errors/auth.error.ts

@@ -0,0 +1,33 @@
+export class AuthenticationError extends Error {
+  public readonly code = 'AUTH_REQUIRED';
+  public readonly statusCode = 401;
+  public readonly data: Record<string, unknown> | undefined;
+
+  constructor(message: string, data?: Record<string, unknown>) {
+    super(message);
+    this.name = 'AuthenticationError';
+    this.data = data;
+
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, AuthenticationError);
+    }
+  }
+}
+
+export class TenantError extends Error {
+  public readonly code = 'TENANT_REQUIRED';
+  public readonly statusCode = 401;
+  public readonly data: Record<string, unknown> | undefined;
+
+  constructor(message: string, data?: Record<string, unknown>) {
+    super(message);
+    this.name = 'TenantError';
+    this.data = data;
+
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, TenantError);
+    }
+  }
+}

package/src/errors/index.ts

@@ -0,0 +1,2 @@
+export * from './permission.error';
+export * from './auth.error';

package/src/errors/permission.error.ts

@@ -0,0 +1,17 @@
+export class PermissionError extends Error {
+  public readonly code = 'PERMISSION_DENIED';
+  public readonly statusCode = 403;
+  public readonly data: Record<string, unknown> | undefined;
+
+  constructor(message: string, data?: Record<string, unknown>) {
+    super(message);
+    this.name = 'PermissionError';
+    this.data = data;
+
+    // Maintains proper stack trace for where our error was thrown (only available on V8)
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, PermissionError);
+    }
+  }
+}

package/src/examples/cache-usage.example.ts

@@ -0,0 +1,293 @@
+/**
+ * Example of how to use the cache middleware in a Moleculer service
+ * This file demonstrates various caching patterns and best practices
+ */
+
+import type {AppContext} from '../types';
+import {CacheMiddleware} from '../middlewares/cache.middleware';
+import {REDIS_URL} from '../env';
+
+// Initialize cache on application start
+export function initializeCache() {
+  CacheMiddleware.init({
+    redisUrl: REDIS_URL, // Falls back to in-memory if not set
+    ttl: 10 * 60 * 1000, // 10 minutes default TTL
+    namespace: 'app', // Namespace for cache keys
+  });
+}
+
+/**
+ * Example 1: Simple get/set pattern
+ */
+export async function getUserWithCache(ctx: AppContext, userId: string) {
+  const cacheKey = `user:${userId}`;
+
+  // Try to get from cache
+  const cached = await ctx.cache.get(cacheKey);
+  if (cached) {
+    return cached;
+  }
+
+  // Cache miss - fetch from database
+  const user = await fetchUserFromDatabase(userId);
+
+  // Store in cache for 5 minutes
+  await ctx.cache.set(cacheKey, user, 5 * 60 * 1000);
+
+  return user;
+}
+
+/**
+ * Example 2: Using the wrap pattern (recommended)
+ * Automatically handles get/set logic
+ */
+export async function getUserWithWrap(ctx: AppContext, userId: string) {
+  return ctx.cache.wrap(
+    `user:${userId}`,
+    async () => {
+      // This function only runs if cache miss
+      return fetchUserFromDatabase(userId);
+    },
+    5 * 60 * 1000 // TTL
+  );
+}
+
+/**
+ * Example 3: Caching complex calculations
+ */
+export async function getUserPermissions(ctx: AppContext, userId: string) {
+  return ctx.cache.wrap(
+    `permissions:${userId}`,
+    async () => {
+      // Complex permission calculation
+      const user = await fetchUserFromDatabase(userId);
+      const roles = await fetchUserRoles(userId);
+      const permissions = calculatePermissions(user, roles);
+      return permissions;
+    },
+    10 * 60 * 1000 // Cache for 10 minutes
+  );
+}
+
+/**
+ * Example 4: Batch operations
+ */
+export async function getUsersBatch(ctx: AppContext, userIds: string[]) {
+  // Generate cache keys
+  const cacheKeys = userIds.map((id) => `user:${id}`);
+
+  // Get all from cache at once
+  const cachedUsers = await ctx.cache.mget(...cacheKeys);
+
+  // Find missing users
+  const result: Array<Record<string, unknown>> = [];
+  const missingIds: string[] = [];
+
+  cachedUsers.forEach((user, index) => {
+    if (user !== undefined && user !== null) {
+      result[index] = user as Record<string, unknown>;
+    } else {
+      const userId = userIds[index];
+      if (userId !== undefined) {
+        missingIds.push(userId);
+      }
+    }
+  });
+
+  // Fetch missing users from database
+  if (missingIds.length > 0) {
+    const missingUsers = await fetchUsersFromDatabase(missingIds);
+
+    // Prepare batch cache update
+    const cacheEntries: Record<string, unknown> = {};
+    missingUsers.forEach((user) => {
+      cacheEntries[`user:${user.id}`] = user;
+      // Add to result
+      const index = userIds.indexOf(user.id);
+      if (index !== -1) {
+        result[index] = user;
+      }
+    });
+
+    // Set all at once
+    await ctx.cache.mset(cacheEntries, 5 * 60 * 1000);
+  }
+
+  return result;
+}
+
+/**
+ * Example 5: Cache invalidation after update
+ */
+export async function updateUser(
+  ctx: AppContext,
+  userId: string,
+  updates: Record<string, unknown>
+) {
+  // Update in database
+  const updatedUser = await updateUserInDatabase(userId, updates);
+
+  // Invalidate all related caches
+  await ctx.cache.mdel(
+    `user:${userId}`,
+    `permissions:${userId}`,
+    `profile:${userId}`
+  );
+
+  // Optionally, pre-populate cache with new data
+  await ctx.cache.set(`user:${userId}`, updatedUser, 5 * 60 * 1000);
+
+  return updatedUser;
+}
+
+/**
+ * Example 6: Check if key exists
+ */
+export async function isUserCached(ctx: AppContext, userId: string) {
+  return ctx.cache.has(`user:${userId}`);
+}
+
+/**
+ * Example 7: Clear entire cache namespace
+ */
+export async function clearAllCache(ctx: AppContext) {
+  await ctx.cache.clear();
+}
+
+/**
+ * Example 8: Cache with dynamic TTL based on data
+ */
+interface CacheableData {
+  type: 'static' | 'volatile' | 'normal';
+  [key: string]: unknown;
+}
+
+export async function cacheWithDynamicTTL(
+  ctx: AppContext,
+  key: string,
+  data: CacheableData
+) {
+  // Determine TTL based on data characteristics
+  let ttl = 5 * 60 * 1000; // 5 minutes default
+
+  if (data.type === 'static') {
+    ttl = 60 * 60 * 1000; // 1 hour for static data
+  } else if (data.type === 'volatile') {
+    ttl = 60 * 1000; // 1 minute for volatile data
+  }
+
+  await ctx.cache.set(key, data, ttl);
+}
+
+/**
+ * Example 9: Cache status check
+ */
+export async function checkCacheHealth(ctx: AppContext) {
+  const testKey = 'health:check';
+  const testValue = {timestamp: Date.now(), random: Math.random()};
+
+  try {
+    // Test set
+    const setResult = await ctx.cache.set(testKey, testValue, 1000);
+
+    // Test get
+    const getResult = await ctx.cache.get(testKey);
+
+    // Test has
+    const hasResult = await ctx.cache.has(testKey);
+
+    // Test delete
+    const deleteResult = await ctx.cache.delete(testKey);
+
+    return {
+      healthy: true,
+      type: REDIS_URL ? 'Redis' : 'In-Memory',
+      operations: {
+        set: setResult,
+        get: JSON.stringify(getResult) === JSON.stringify(testValue),
+        has: hasResult,
+        delete: deleteResult,
+      },
+    };
+  } catch (error) {
+    return {
+      healthy: false,
+      error: error instanceof Error ? error.message : 'Unknown error',
+    };
+  }
+}
+
+// Mock database functions for example purposes
+async function fetchUserFromDatabase(userId: string) {
+  return {
+    id: userId,
+    name: `User ${userId}`,
+    email: `user${userId}@example.com`,
+    createdAt: new Date(),
+  };
+}
+
+async function fetchUsersFromDatabase(userIds: string[]) {
+  return userIds.map((id) => ({
+    id,
+    name: `User ${id}`,
+    email: `user${id}@example.com`,
+    createdAt: new Date(),
+  }));
+}
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+async function fetchUserRoles(_userId: string) {
+  return ['user', 'member'];
+}
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  createdAt: Date;
+}
+
+function calculatePermissions(_user: User, roles: string[]) {
+  return {
+    canRead: true,
+    canWrite: roles.includes('admin'),
+    canDelete: roles.includes('admin'),
+  };
+}
+
+async function updateUserInDatabase(
+  userId: string,
+  updates: Record<string, unknown>
+) {
+  return {
+    id: userId,
+    ...updates,
+    updatedAt: new Date(),
+  };
+}
+
+/**
+ * Usage in a Moleculer service:
+ *
+ * export default {
+ *   name: 'users',
+ *   middlewares: [CacheMiddleware],
+ *
+ *   started() {
+ *     initializeCache();
+ *   },
+ *
+ *   stopped() {
+ *     return CacheMiddleware.stopped();
+ *   },
+ *
+ *   actions: {
+ *     get: {
+ *       async handler(ctx) {
+ *         return getUserWithWrap(ctx, ctx.params.id);
+ *       }
+ *     }
+ *   }
+ * }
+ */

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './middlewares';
+export * from './service/define-service';
+export * from './types';
+export * from './configs';
+export * from './env';