@majkapp/plugin-kit 3.2.1 → 3.3.0

package/docs/SERVICES.md

@@ -0,0 +1,350 @@
+# Services
+
+Services group related functions together for better organization and discovery.
+
+## Basic Service
+
+```typescript
+// src/index.ts
+import { definePlugin } from '@majkapp/plugin-kit';
+
+const plugin = definePlugin('my-plugin', 'My Plugin', '1.0.0')
+  .pluginRoot(__dirname)
+
+  // Define functions first
+  .function('health', { /* ... */, tags: ['monitoring'] })
+  .function('getStats', { /* ... */, tags: ['monitoring'] })
+  .function('getMetrics', { /* ... */, tags: ['monitoring'] })
+
+  // Group into service
+  .service('plugin:my-plugin:monitoring', {
+    type: '@my-plugin/monitoring',
+    metadata: {
+      name: 'Monitoring Service',
+      description: 'Health checks and system metrics',
+      version: '1.0.0'
+    },
+    discoverable: true  // Make service discoverable by other plugins
+  })
+    .withFunction('health', {
+      examples: ['Check plugin health status'],
+      tags: ['health', 'status']
+    })
+    .withFunction('getStats', {
+      examples: ['Get system statistics'],
+      tags: ['stats', 'metrics']
+    })
+    .withFunction('getMetrics', {
+      examples: ['Get detailed metrics'],
+      tags: ['metrics', 'monitoring']
+    })
+  .endService()
+
+  .build();
+```
+
+## Real Example from full-featured
+
+```typescript
+// samples/full-featured/src/index.ts
+
+// Define monitoring functions
+.function('health', {
+  description: 'Returns plugin health status',
+  input: { /* ... */ },
+  output: { /* ... */ },
+  handler: async (input, ctx) => {
+    return {
+      status: 'ok',
+      timestamp: new Date().toISOString()
+    };
+  },
+  tags: ['monitoring']
+})
+
+.function('getStats', {
+  description: 'Get plugin statistics',
+  input: { /* ... */ },
+  output: { /* ... */ },
+  handler: async (input, ctx) => {
+    const conversations = await ctx.majk.conversations.list();
+    const teammates = await ctx.majk.teammates.list();
+
+    return {
+      conversationCount: conversations.length,
+      teammateCount: teammates.length,
+      timestamp: new Date().toISOString()
+    };
+  },
+  tags: ['monitoring']
+})
+
+// Group into service
+.service('plugin:full-featured:monitoring', {
+  type: '@full-featured/monitoring',
+  metadata: {
+    name: 'Full Featured Monitoring',
+    description: 'Health checks and statistics for the Full Featured plugin',
+    version: '1.0.0',
+    author: 'Full Featured Team'
+  },
+  discoverable: true
+})
+  .withFunction('health', {
+    examples: [
+      'Get current health status',
+      'Check if plugin is running correctly'
+    ],
+    tags: ['health', 'status', 'monitoring']
+  })
+  .withFunction('getStats', {
+    examples: [
+      'Get conversation and teammate counts',
+      'View system statistics'
+    ],
+    tags: ['stats', 'metrics', 'monitoring']
+  })
+.endService()
+```
+
+## Service with Multiple Functions
+
+```typescript
+// Events management service
+.function('getEvents', {
+  description: 'Get all logged events from the event bus',
+  input: { /* ... */ },
+  output: { /* ... */ },
+  handler: async (input, ctx) => {
+    const events = await ctx.storage.get('events') || [];
+    return { events, count: events.length };
+  },
+  tags: ['events']
+})
+
+.function('clearEvents', {
+  description: 'Clear the event log',
+  input: { /* ... */ },
+  output: { /* ... */ },
+  handler: async (input, ctx) => {
+    const events = await ctx.storage.get('events') || [];
+    await ctx.storage.set('events', []);
+    return { success: true, clearedCount: events.length };
+  },
+  tags: ['events', 'mutations']
+})
+
+.service('plugin:my-plugin:events', {
+  type: '@my-plugin/events',
+  metadata: {
+    name: 'Event Management',
+    description: 'Manage and monitor system events',
+    version: '1.0.0'
+  }
+})
+  .withFunction('getEvents', {
+    examples: ['List all logged events', 'View event history'],
+    tags: ['read', 'query']
+  })
+  .withFunction('clearEvents', {
+    examples: ['Clear event log', 'Reset event history'],
+    tags: ['write', 'mutation']
+  })
+.endService()
+```
+
+## Multiple Services
+
+Organize functions into logical groups:
+
+```typescript
+const plugin = definePlugin('my-plugin', 'My Plugin', '1.0.0')
+  .pluginRoot(__dirname)
+
+  // Monitoring functions
+  .function('health', { /* ... */, tags: ['monitoring'] })
+  .function('getStats', { /* ... */, tags: ['monitoring'] })
+
+  // Analytics functions
+  .function('getAnalytics', { /* ... */, tags: ['analytics'] })
+  .function('getChartData', { /* ... */, tags: ['analytics'] })
+
+  // User management functions
+  .function('getUsers', { /* ... */, tags: ['users'] })
+  .function('getUserDetail', { /* ... */, tags: ['users'] })
+
+  // Monitoring service
+  .service('plugin:my-plugin:monitoring', {
+    type: '@my-plugin/monitoring',
+    metadata: {
+      name: 'Monitoring Service',
+      description: 'Health and statistics',
+      version: '1.0.0'
+    }
+  })
+    .withFunction('health')
+    .withFunction('getStats')
+  .endService()
+
+  // Analytics service
+  .service('plugin:my-plugin:analytics', {
+    type: '@my-plugin/analytics',
+    metadata: {
+      name: 'Analytics Service',
+      description: 'Usage analytics and reporting',
+      version: '1.0.0'
+    }
+  })
+    .withFunction('getAnalytics')
+    .withFunction('getChartData')
+  .endService()
+
+  // User service
+  .service('plugin:my-plugin:users', {
+    type: '@my-plugin/users',
+    metadata: {
+      name: 'User Service',
+      description: 'User data and management',
+      version: '1.0.0'
+    }
+  })
+    .withFunction('getUsers')
+    .withFunction('getUserDetail')
+  .endService()
+
+  .build();
+```
+
+## Service Metadata
+
+Service metadata helps with discovery and documentation:
+
+```typescript
+.service('plugin:my-plugin:service-name', {
+  type: '@my-plugin/service-type',  // Unique type identifier
+  metadata: {
+    name: 'Human-Readable Service Name',
+    description: 'Detailed description of what this service does',
+    version: '1.0.0',
+    author: 'Team Name',  // Optional
+    homepage: 'https://docs.example.com/service',  // Optional
+    tags: ['tag1', 'tag2']  // Optional
+  },
+  discoverable: true  // Allow other plugins to discover this service
+})
+```
+
+## Function Enrichment
+
+Add service-specific metadata to functions:
+
+```typescript
+.withFunction('functionName', {
+  examples: [
+    'Example use case 1',
+    'Example use case 2'
+  ],
+  tags: ['tag1', 'tag2'],  // Additional tags for this function in service context
+  metadata: {  // Optional custom metadata
+    rateLimit: 100,
+    requiresAuth: true
+  }
+})
+```
+
+## Best Practices
+
+### 1. Organize by Domain
+
+```typescript
+// Good: Functions grouped by business domain
+.service('plugin:my-plugin:analytics', { /* ... */ })
+  .withFunction('getAnalytics')
+  .withFunction('getChartData')
+  .withFunction('exportReport')
+.endService()
+
+.service('plugin:my-plugin:notifications', { /* ... */ })
+  .withFunction('sendNotification')
+  .withFunction('getNotificationHistory')
+.endService()
+```
+
+### 2. Keep Services Focused
+
+```typescript
+// Good: Focused service with related functions
+.service('plugin:my-plugin:events', { /* ... */ })
+  .withFunction('getEvents')
+  .withFunction('clearEvents')
+  .withFunction('filterEvents')
+.endService()
+
+// Bad: Too broad, unrelated functions
+.service('plugin:my-plugin:everything', { /* ... */ })
+  .withFunction('getEvents')
+  .withFunction('sendEmail')  // Unrelated
+  .withFunction('calculateTax')  // Unrelated
+.endService()
+```
+
+### 3. Use Descriptive Metadata
+
+```typescript
+.service('plugin:my-plugin:monitoring', {
+  type: '@my-plugin/monitoring',
+  metadata: {
+    name: 'System Monitoring',  // Clear name
+    description: 'Provides health checks, system statistics, and performance metrics for the plugin',  // Detailed description
+    version: '1.0.0'
+  }
+})
+```
+
+## Service Naming Convention
+
+**Format:** `plugin:{plugin-id}:{service-name}`
+
+Examples:
+- `plugin:my-plugin:monitoring`
+- `plugin:my-plugin:analytics`
+- `plugin:my-plugin:data-management`
+- `plugin:full-featured:events`
+
+## Testing Services
+
+Services are tested through their functions:
+
+```typescript
+// tests/plugin/functions/unit/monitoring.test.js
+import { test, invoke, mock } from '@majkapp/plugin-test';
+import assert from 'assert';
+
+test('monitoring service - health check', async () => {
+  const context = mock().build();
+  const result = await invoke('health', {}, { context });
+
+  assert.strictEqual(result.status, 'ok');
+  assert.ok(result.timestamp);
+});
+
+test('monitoring service - get stats', async () => {
+  const context = mock()
+    .withMajkData({
+      conversations: [{ id: '1' }, { id: '2' }],
+      teammates: [{ id: 't1' }]
+    })
+    .build();
+
+  const result = await invoke('getStats', {}, { context });
+
+  assert.strictEqual(result.conversationCount, 2);
+  assert.strictEqual(result.teammateCount, 1);
+});
+```
+
+## Next Steps
+
+Run `npx @majkapp/plugin-kit --functions` - Define functions for services
+Run `npx @majkapp/plugin-kit --testing` - Test your services
+Run `npx @majkapp/plugin-kit --lifecycle` - Service initialization with onReady