diff --git a/package.json b/package.json index 547666e..5358523 100644 --- a/package.json +++ b/package.json @@ -25,6 +25,7 @@ }, "dependencies": { "@api.global/typedrequest": "^3.0.19", + "@api.global/typedrequest-interfaces": "^3.0.19", "@api.global/typedserver": "^3.0.74", "@api.global/typedsocket": "^3.0.0", "@apiclient.xyz/cloudflare": "^6.4.1", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 943eb0b..8ef0ce0 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -11,6 +11,9 @@ importers: '@api.global/typedrequest': specifier: ^3.0.19 version: 3.1.10 + '@api.global/typedrequest-interfaces': + specifier: ^3.0.19 + version: 3.0.19 '@api.global/typedserver': specifier: ^3.0.74 version: 3.0.74 @@ -5353,8 +5356,10 @@ snapshots: '@push.rocks/taskbuffer': 3.1.7 transitivePeerDependencies: - '@nuxt/kit' + - bufferutil - react - supports-color + - utf-8-validate - vue '@hapi/hoek@9.3.0': {} @@ -5695,7 +5700,6 @@ snapshots: - '@mongodb-js/zstd' - '@nuxt/kit' - aws-crt - - bufferutil - encoding - gcp-metadata - kerberos @@ -5704,7 +5708,6 @@ snapshots: - snappy - socks - supports-color - - utf-8-validate - vue '@push.rocks/smartarchive@3.0.8': diff --git a/readme.example.md b/readme.example.md deleted file mode 100644 index ec63271..0000000 --- a/readme.example.md +++ /dev/null @@ -1,494 +0,0 @@ -# DCRouter Email Configuration Example - -This document provides a comprehensive example of configuring the UnifiedEmailServer in DCRouter for various email routing scenarios. - -## Basic Configuration - -Here's a complete example of a email configuration for the UnifiedEmailServer: - -```typescript -import { IEmailConfig, EmailProcessingMode, IDomainRule } from './ts/config/email.config.js'; - -const emailConfig: IEmailConfig = { - // Basic server settings - useEmail: true, - behindSmartProxy: false, - hostname: "mail.example.com", - ports: [25, 587, 465], - - // Default processing settings - defaultMode: "forward" as EmailProcessingMode, - defaultServer: "smtp.internal-relay.example.com", - defaultPort: 25, - defaultTls: true, - - // TLS configuration - tls: { - certPath: "/path/to/tls/certificate.pem", - keyPath: "/path/to/tls/key.pem", - caPath: "/path/to/tls/ca.pem", - minVersion: "TLSv1.2", - ciphers: "HIGH:!aNULL:!MD5:!RC4" - }, - - // Email size and connection limits - maxMessageSize: 25 * 1024 * 1024, // 25MB - - // Authentication settings - auth: { - required: true, - methods: ["PLAIN", "LOGIN"], - users: [ - { username: "user1", password: "securepassword1" }, - { username: "user2", password: "securepassword2" } - ] - }, - - // Domain routing rules - domainRules: [ - // Process emails for your primary domain via MTA - { - pattern: "*@example.com", - mode: "mta" as EmailProcessingMode, - mtaOptions: { - domain: "example.com", - dkimSign: true, - dkimOptions: { - domainName: "example.com", - keySelector: "mail" - } - } - }, - - // Forward support emails to help desk - { - pattern: "*@support.example.com", - mode: "forward" as EmailProcessingMode, - target: { - server: "helpdesk.example.com", - port: 25, - useTls: true - } - }, - - // Scan marketing emails for content and attachments - { - pattern: "*@marketing.example.com", - mode: "process" as EmailProcessingMode, - contentScanning: true, - scanners: [ - { - type: "attachment", - action: "reject", - blockedExtensions: [".exe", ".zip", ".js", ".vbs", ".bat"] - }, - { - type: "spam", - threshold: 5.0, - action: "tag" - } - ], - transformations: [ - { - type: "addHeader", - header: "X-Scanned-By", - value: "DCRouter Content Scanner" - } - ] - }, - - // Forward all other emails to a backup server - { - pattern: "*@*", - mode: "forward" as EmailProcessingMode, - target: { - server: "backup-smtp.example.com", - port: 587, - useTls: true - } - } - ], - - // Queue configuration - queue: { - storageType: "memory", - ttl: 86400000, // 24 hours - maxItems: 10000, - checkInterval: 60000 // 1 minute - }, - - // Template configuration - templateConfig: { - from: "noreply@example.com", - replyTo: "support@example.com", - footerHtml: "

This is an automated message from Example Inc.

", - footerText: "This is an automated message from Example Inc." - }, - - // IP warmup configuration - serverConfig: { - delivery: { - concurrency: 10, - rateLimit: { - rate: 100, - interval: 60000 // 1 minute - }, - retries: { - max: 3, - delay: 300000, // 5 minutes - useBackoff: true - } - }, - security: { - useDkim: true, - verifyDkim: true, - verifySpf: true, - verifyDmarc: true, - enforceDmarc: true, - useTls: true, - requireValidCerts: true, - securityLogLevel: "info", - checkIPReputation: true, - scanContent: true, - maliciousContentAction: "tag", - threatScoreThreshold: 7.0 - } - } -}; -``` - -## Initializing the UnifiedEmailServer - -Here's how to initialize the UnifiedEmailServer with the configuration: - -```typescript -import { UnifiedEmailServer, IUnifiedEmailServerOptions } from './ts/mail/routing/classes.unified.email.server.js'; - -// Convert EmailConfig to UnifiedEmailServerOptions -const serverOptions: IUnifiedEmailServerOptions = { - ports: emailConfig.ports || [25], - hostname: emailConfig.hostname || 'localhost', - banner: `${emailConfig.hostname} ESMTP DCRouter`, - - // Authentication - auth: emailConfig.auth, - - // TLS - tls: emailConfig.tls, - - // Message limits - maxMessageSize: emailConfig.maxMessageSize || 10 * 1024 * 1024, // 10MB default - maxClients: 100, - - // Domain routing - domainRules: emailConfig.domainRules || [], - defaultMode: emailConfig.defaultMode || 'forward', - defaultServer: emailConfig.defaultServer, - defaultPort: emailConfig.defaultPort, - defaultTls: emailConfig.defaultTls, - - // Deliverability options - ipWarmupConfig: { - enabled: true, - ipAddresses: ['198.51.100.1', '198.51.100.2', '198.51.100.3'], - targetDomains: ['gmail.com', 'yahoo.com', 'outlook.com'], - allocationPolicy: 'balanced' - }, - - reputationMonitorConfig: { - enabled: true, - domains: ['example.com', 'marketing.example.com'], - alertThresholds: { - bounceRate: 0.05, // 5% - complaintRate: 0.001 // 0.1% - } - } -}; - -// Create and start the server -const emailServer = new UnifiedEmailServer(serverOptions); -emailServer.start().then(() => { - console.log('UnifiedEmailServer started successfully'); -}).catch((error) => { - console.error('Failed to start UnifiedEmailServer:', error); -}); -``` - -## Use Case Examples - -### 1. Forwarding Email Gateway (SMTP Proxy) - -Configure DCRouter to forward emails for specific domains to internal mail servers: - -```typescript -const forwardingRules: IDomainRule[] = [ - // Main corporate domain - forward to Exchange - { - pattern: "*@corp.example.com", - mode: "forward" as EmailProcessingMode, - target: { - server: "exchange.internal", - port: 25, - useTls: true - } - }, - // Marketing domain - forward to Marketing mail server - { - pattern: "*@marketing.example.com", - mode: "forward" as EmailProcessingMode, - target: { - server: "marketing-mail.internal", - port: 25, - useTls: false - } - } -]; -``` - -### 2. Outbound MTA with DKIM Signing and IP Warmup - -Configure DCRouter as an outbound mail transfer agent with DKIM signing and IP warmup: - -```typescript -// MTA configuration with DKIM signing -const mtaRule: IDomainRule = { - pattern: "*@outbound.example.com", - mode: "mta" as EmailProcessingMode, - mtaOptions: { - domain: "outbound.example.com", - dkimSign: true, - dkimOptions: { - domainName: "outbound.example.com", - keySelector: "mail2023" - } - } -}; - -// IP Warmup configuration -const ipWarmupConfig = { - enabled: true, - ipAddresses: ['203.0.113.1', '203.0.113.2'], - targetDomains: ['gmail.com', 'yahoo.com', 'hotmail.com', 'aol.com'], - allocationPolicy: 'progressive', - fallbackPercentage: 20 -}; -``` - -### 3. Content Scanning and Security Gateway - -Configure DCRouter to scan emails for malicious content and enforce security policies: - -```typescript -const securityRule: IDomainRule = { - pattern: "*@*", - mode: "process" as EmailProcessingMode, - contentScanning: true, - scanners: [ - // Scan for malicious attachments - { - type: "attachment", - action: "reject", - blockedExtensions: [".exe", ".dll", ".bat", ".vbs", ".js", ".cmd", ".scr", ".com", ".pif"] - }, - // Scan for spam - { - type: "spam", - threshold: 6.0, - action: "tag" - }, - // Scan for viruses - { - type: "virus", - action: "reject" - } - ], - transformations: [ - // Add scanning headers - { - type: "addHeader", - header: "X-Security-Scanned", - value: "DCRouter Security Gateway" - } - ] -}; - -// Configure security settings -const securityConfig = { - useDkim: true, - verifyDkim: true, - verifySpf: true, - verifyDmarc: true, - enforceDmarc: true, - checkIPReputation: true, - scanContent: true, - maliciousContentAction: "quarantine", - threatScoreThreshold: 5.0, - rejectHighRiskIPs: true, - securityLogLevel: "warn" -}; -``` - -### 4. Multi-Tenant Email Server - -Configure DCRouter to handle emails for multiple domains with different processing rules: - -```typescript -const multiTenantRules: IDomainRule[] = [ - // Tenant 1: Process locally - { - pattern: "*@tenant1.example.org", - mode: "mta" as EmailProcessingMode, - mtaOptions: { - domain: "tenant1.example.org", - dkimSign: true, - dkimOptions: { - domainName: "tenant1.example.org", - keySelector: "t1mail" - } - } - }, - // Tenant 2: Forward to their server - { - pattern: "*@tenant2.example.org", - mode: "forward" as EmailProcessingMode, - target: { - server: "mail.tenant2.com", - port: 587, - useTls: true - } - }, - // Tenant 3: Process with content scanning - { - pattern: "*@tenant3.example.org", - mode: "process" as EmailProcessingMode, - contentScanning: true, - scanners: [ - { - type: "attachment", - action: "tag", - blockedExtensions: [".zip", ".rar", ".7z"] - } - ] - } -]; -``` - -## Using the Bounce Management System - -DCRouter includes a sophisticated bounce management system. Here's how to use it: - -```typescript -// Get an instance of the UnifiedEmailServer -const emailServer = new UnifiedEmailServer(serverOptions); - -// Check if an email is on the suppression list -const isSuppressed = emailServer.isEmailSuppressed('user@example.com'); - -// Get suppression information -const suppressionInfo = emailServer.getSuppressionInfo('user@example.com'); -if (suppressionInfo) { - console.log(`Suppressed due to: ${suppressionInfo.reason}`); - console.log(`Suppressed since: ${new Date(suppressionInfo.timestamp)}`); - if (suppressionInfo.expiresAt) { - console.log(`Suppression expires: ${new Date(suppressionInfo.expiresAt)}`); - } else { - console.log('Suppression is permanent'); - } -} - -// Add an email to the suppression list -emailServer.addToSuppressionList( - 'problem-user@example.com', - 'Manual suppression due to user request', - Date.now() + (30 * 24 * 60 * 60 * 1000) // Expires in 30 days -); - -// Remove an email from the suppression list -emailServer.removeFromSuppressionList('reactivated-user@example.com'); - -// Get all suppressed emails -const suppressionList = emailServer.getSuppressionList(); -console.log(`There are ${suppressionList.length} suppressed email addresses`); -``` - -## Using the IP Warmup System - -DCRouter's IP warmup system helps gradually build sender reputation for new IP addresses: - -```typescript -// Add a new IP to warmup -emailServer.addIPToWarmup('198.51.100.4'); - -// Get warmup status for all IPs -const warmupStatus = emailServer.getIPWarmupStatus(); -console.log('IP Warmup Status:', warmupStatus); - -// Get warmup status for a specific IP -const specificIPStatus = emailServer.getIPWarmupStatus('198.51.100.1'); -console.log(`Warmup day: ${specificIPStatus.day}`); -console.log(`Daily limit: ${specificIPStatus.dailyLimit}`); -console.log(`Emails sent today: ${specificIPStatus.sentToday}`); - -// Update IP metrics based on feedback from mailbox providers -emailServer.updateIPWarmupMetrics('198.51.100.1', { - openRate: 0.25, // 25% open rate - bounceRate: 0.02, // 2% bounce rate - complaintRate: 0.001 // 0.1% complaint rate -}); - -// Check if an IP can send more emails today -if (emailServer.canIPSendMoreToday('198.51.100.1')) { - console.log('IP can send more emails today'); -} else { - console.log('IP has reached its daily sending limit'); -} - -// Change the IP allocation policy -emailServer.setIPAllocationPolicy('volume-based'); -``` - -## Sender Reputation Monitoring - -Monitor and manage your domain reputation with these features: - -```typescript -// Add a domain to monitoring -emailServer.addDomainToMonitoring('newdomain.example.com'); - -// Get reputation data for a specific domain -const reputationData = emailServer.getDomainReputationData('example.com'); -console.log(`Reputation score: ${reputationData.score}`); -console.log(`Bounce rate: ${reputationData.bounceRate}`); -console.log(`Complaint rate: ${reputationData.complaintRate}`); - -// Get a summary of all domains -const summary = emailServer.getReputationSummary(); -console.log('Domain reputation summary:', summary); - -// Record a custom engagement event -emailServer.recordReputationEvent('example.com', { - type: 'open', - count: 15 -}); -``` - -## Updating Configuration at Runtime - -DCRouter allows updating configurations dynamically without restarting: - -```typescript -// Update domain rules -const newRules: IDomainRule[] = [ - // New rules here -]; -emailServer.updateDomainRules(newRules); - -// Update server options -emailServer.updateOptions({ - maxMessageSize: 50 * 1024 * 1024, // 50MB - maxClients: 200, - defaultServer: 'new-relay.example.com' -}); -``` - -This example configuration covers a wide range of use cases from simple forwarding to advanced security scanning, IP warmup, and reputation management, showcasing DCRouter's versatility as an email routing and processing solution. \ No newline at end of file diff --git a/readme.opsserver.md b/readme.opsserver.md new file mode 100644 index 0000000..31d6431 --- /dev/null +++ b/readme.opsserver.md @@ -0,0 +1,308 @@ +# DCRouter OpsServer Implementation Plan + +**Command to reread CLAUDE.md: `cat /home/philkunz/.claude/CLAUDE.md`** + +## Overview + +This document outlines the implementation plan for adding a TypedRequest-based API to the DCRouter OpsServer, following the patterns established in the cloudly project. The goal is to create a type-safe, reactive management dashboard with real-time statistics and monitoring capabilities. + +## Architecture Overview + +The implementation follows a clear separation of concerns: +- **Backend**: TypedRequest handlers in OpsServer +- **Frontend**: Reactive web components with Smartstate +- **Communication**: Type-safe requests via TypedRequest pattern +- **State Management**: Centralized state with reactive updates + +## Implementation Phases + +### Phase 1: Interface Definition ✓ + +Create TypeScript interfaces for all API operations: + +#### Directory Structure ✓ +``` +ts_interfaces/ + plugins.ts # TypedRequest interfaces import + data/ # Data type definitions + auth.ts # IIdentity interface + stats.ts # Server, Email, DNS, Security types + index.ts # Exports + requests/ # Request interfaces + admin.ts # Authentication requests + config.ts # Configuration management + logs.ts # Log retrieval with IVirtualStream + stats.ts # Statistics endpoints + index.ts # Exports +``` + +#### Key Interfaces Defined ✓ +- **Server Statistics** + - [x] `IReq_GetServerStatistics` - Server metrics with history + +- **Email Operations** + - [x] `IReq_GetEmailStatistics` - Email delivery stats + - [x] `IReq_GetQueueStatus` - Queue monitoring + +- **DNS Management** + - [x] `IReq_GetDnsStatistics` - DNS query metrics + +- **Rate Limiting** + - [x] `IReq_GetRateLimitStatus` - Rate limit info + +- **Security Metrics** + - [x] `IReq_GetSecurityMetrics` - Security stats and trends + - [x] `IReq_GetActiveConnections` - Connection monitoring + +- **Logging** + - [x] `IReq_GetRecentLogs` - Paginated log retrieval + - [x] `IReq_GetLogStream` - Real-time log streaming with IVirtualStream + +- **Configuration** + - [x] `IReq_GetConfiguration` - Read config + - [x] `IReq_UpdateConfiguration` - Update config + +- **Authentication** + - [x] `IReq_AdminLoginWithUsernameAndPassword` - Admin login + - [x] `IReq_AdminLogout` - Logout + - [x] `IReq_VerifyIdentity` - Token verification + +- **Health Check** + - [x] `IReq_GetHealthStatus` - Service health monitoring + +### Phase 2: Backend Implementation + +#### 2.1 Enhance OpsServer (`ts/opsserver/classes.opsserver.ts`) + +- [ ] Add TypedRouter initialization +- [ ] Use TypedServer's built-in typedrouter +- [ ] CORS is already handled by TypedServer +- [ ] Add handler registration method + +```typescript +// Example structure following cloudly pattern +public typedrouter = new plugins.typedrequest.TypedRouter(); + +constructor(private dcRouterRef: DcRouter) { + // Add our typedrouter to the dcRouter's main typedrouter + this.dcRouterRef.typedrouter.addTypedRouter(this.typedrouter); +} + +public async start() { + // TypedServer already has a built-in typedrouter at /typedrequest + this.server = new plugins.typedserver.utilityservers.UtilityWebsiteServer({ + domain: 'localhost', + feedMetadata: null, + serveDir: paths.distServe, + }); + + // The server's typedrouter is automatically available + // Add the main dcRouter typedrouter to the server's typedrouter + this.server.typedrouter.addTypedRouter(this.dcRouterRef.typedrouter); + + this.setupHandlers(); + await this.server.start(3000); +} +``` + +**Note**: TypedServer automatically provides the `/typedrequest` endpoint with its built-in typedrouter. We just need to add our routers to it using the `addTypedRouter()` method. + +#### Hierarchical TypedRouter Structure + +Following cloudly's pattern, we'll use a hierarchical router structure: + +``` +TypedServer (built-in typedrouter at /typedrequest) + └── DcRouter.typedrouter (main router) + └── OpsServer.typedrouter (ops-specific handlers) + ├── StatsHandler.typedrouter + ├── ConfigHandler.typedrouter + └── SecurityHandler.typedrouter +``` + +This allows clean separation of concerns while keeping all handlers accessible through the single `/typedrequest` endpoint. + +#### 2.2 Create Handler Classes + +Create modular handlers in `ts/opsserver/handlers/`: + +- [ ] `stats.handler.ts` - Server and performance statistics +- [ ] `email.handler.ts` - Email-related operations +- [ ] `dns.handler.ts` - DNS management statistics +- [ ] `security.handler.ts` - Security and reputation metrics +- [ ] `config.handler.ts` - Configuration management + +Each handler should: +- Have its own typedrouter that gets added to OpsServer's router +- Access the main DCRouter instance +- Register handlers using TypedHandler instances +- Format responses according to interfaces +- Handle errors gracefully + +Example handler structure: +```typescript +export class StatsHandler { + public typedrouter = new plugins.typedrequest.TypedRouter(); + + constructor(private opsServerRef: OpsServer) { + // Add this handler's router to the parent + this.opsServerRef.typedrouter.addTypedRouter(this.typedrouter); + this.registerHandlers(); + } + + private registerHandlers() { + this.typedrouter.addTypedHandler( + new plugins.typedrequest.TypedHandler( + 'getServerStatistics', + async (dataArg, toolsArg) => { + const stats = await this.collectServerStats(); + return stats; + } + ) + ); + } +} +``` + +### Phase 3: Frontend State Management + +#### 3.1 Set up Smartstate (`ts_web/appstate.ts`) + +- [ ] Initialize Smartstate instance +- [ ] Create state parts with appropriate persistence +- [ ] Define initial state structures + +```typescript +// State structure example +interface IStatsState { + serverStats: IRes_ServerStatistics | null; + emailStats: IRes_EmailStatistics | null; + dnsStats: IRes_DnsStatistics | null; + lastUpdated: number; + isLoading: boolean; + error: string | null; +} +``` + +#### 3.2 State Parts to Create + +- [ ] `statsState` - Runtime statistics (soft persistence) +- [ ] `configState` - Configuration data (soft persistence) +- [ ] `uiState` - UI preferences (persistent) +- [ ] `loginState` - Authentication state (persistent) *if needed* + +### Phase 4: Frontend Integration + +#### 4.1 API Client Setup (`ts_web/api/clients.ts`) + +- [ ] Create TypedRequest instances for each endpoint +- [ ] Configure base URL handling +- [ ] Add error interceptors +- [ ] Implement retry logic + +#### 4.2 Create Actions (`ts_web/state/actions.ts`) + +- [ ] `fetchAllStatsAction` - Batch fetch all statistics +- [ ] `refreshServerStatsAction` - Update server stats only +- [ ] `refreshEmailStatsAction` - Update email stats only +- [ ] `setAutoRefreshAction` - Toggle auto-refresh +- [ ] Error handling actions + +#### 4.3 Update Dashboard Component (`ts_web/elements/ops-dashboard.ts`) + +- [ ] Subscribe to state changes +- [ ] Implement reactive UI updates +- [ ] Add refresh controls +- [ ] Create sub-components for different stat types +- [ ] Implement auto-refresh timer + +### Phase 5: Component Structure + +Create modular components in `ts_web/elements/components/`: + +- [ ] `server-stats.ts` - Server statistics display +- [ ] `email-stats.ts` - Email metrics visualization +- [ ] `dns-stats.ts` - DNS statistics +- [ ] `rate-limit-display.ts` - Rate limiting status +- [ ] `security-metrics.ts` - Security dashboard +- [ ] `log-viewer.ts` - Real-time log display + +### Phase 6: Optional Enhancements + +#### 6.1 Authentication (if required) +- [ ] Simple token-based authentication +- [ ] Login component +- [ ] Protected route handling +- [ ] Session management + +#### 6.2 Real-time Updates (future) +- [ ] WebSocket integration for live stats +- [ ] Push notifications for critical events +- [ ] Event streaming for logs + +## Technical Stack + +### Dependencies to Use +- `@api.global/typedserver` - Server with built-in typedrouter at `/typedrequest` +- `@api.global/typedrequest` - TypedRouter and TypedHandler classes +- `@design.estate/dees-domtools` - Frontend TypedRequest client +- `@push.rocks/smartstate` - State management +- `@design.estate/dees-element` - Web components +- `@design.estate/dees-catalog` - UI components + +### Existing Dependencies to Leverage +- Current DCRouter instance and statistics +- Existing error handling patterns +- Logger infrastructure +- Security modules + +## Development Workflow + +1. **Start with interfaces** - Define all types first +2. **Implement one handler** - Start with server stats +3. **Create minimal frontend** - Test with one endpoint +4. **Iterate** - Add more handlers and UI components +5. **Polish** - Add error handling, loading states, etc. + +## Testing Strategy + +- [ ] Unit tests for handlers +- [ ] Integration tests for API endpoints +- [ ] Frontend component tests +- [ ] End-to-end testing with real DCRouter instance + +## Success Criteria + +- Type-safe communication between frontend and backend +- Real-time statistics display +- Responsive and reactive UI +- Clean, maintainable code structure +- Consistent with cloudly patterns +- Easy to extend with new features + +## Notes + +- Follow existing code conventions in the project +- Use pnpm for all package management +- Ensure all tests pass before marking complete +- Document any deviations from the plan + +--- + +## Progress Status + +### Completed ✓ +- **Phase 1: Interface Definition** - All TypedRequest interfaces created following cloudly pattern + - Created proper TypedRequest interfaces with `method`, `request`, and `response` properties + - Used `IVirtualStream` for log streaming + - Added `@api.global/typedrequest-interfaces` dependency + - All interfaces compile successfully + +### Next Steps +- Phase 2: Backend Implementation - Enhance OpsServer and create handlers +- Phase 3: Frontend State Management - Set up Smartstate +- Phase 4: Frontend Integration - Create API clients and update dashboard + +--- + +*This plan is a living document. Update it as implementation progresses.* \ No newline at end of file diff --git a/ts_interfaces/index.ts b/ts_interfaces/index.ts index e69de29..2ce88cb 100644 --- a/ts_interfaces/index.ts +++ b/ts_interfaces/index.ts @@ -0,0 +1,9 @@ +export * from './plugins.js'; + +// Data types +import * as data from './data/index.js'; +export { data }; + +// Request interfaces +import * as requests from './requests/index.js'; +export { requests }; \ No newline at end of file diff --git a/ts_interfaces/plugins.ts b/ts_interfaces/plugins.ts new file mode 100644 index 0000000..8a4965b --- /dev/null +++ b/ts_interfaces/plugins.ts @@ -0,0 +1,6 @@ +// @apiglobal scope +import * as typedrequestInterfaces from '@api.global/typedrequest-interfaces'; + +export { + typedrequestInterfaces +} \ No newline at end of file diff --git a/ts_interfaces/requests/admin.ts b/ts_interfaces/requests/admin.ts new file mode 100644 index 0000000..0876b84 --- /dev/null +++ b/ts_interfaces/requests/admin.ts @@ -0,0 +1,46 @@ +import * as plugins from '../plugins.js'; +import * as authInterfaces from '../data/auth.js'; + +// Admin Login +export interface IReq_AdminLoginWithUsernameAndPassword extends plugins.typedrequestInterfaces.implementsTR< + plugins.typedrequestInterfaces.ITypedRequest, + IReq_AdminLoginWithUsernameAndPassword +> { + method: 'adminLoginWithUsernameAndPassword'; + request: { + username: string; + password: string; + }; + response: { + identity?: authInterfaces.IIdentity; + }; +} + +// Admin Logout +export interface IReq_AdminLogout extends plugins.typedrequestInterfaces.implementsTR< + plugins.typedrequestInterfaces.ITypedRequest, + IReq_AdminLogout +> { + method: 'adminLogout'; + request: { + identity: authInterfaces.IIdentity; + }; + response: { + success: boolean; + }; +} + +// Verify Identity +export interface IReq_VerifyIdentity extends plugins.typedrequestInterfaces.implementsTR< + plugins.typedrequestInterfaces.ITypedRequest, + IReq_VerifyIdentity +> { + method: 'verifyIdentity'; + request: { + identity: authInterfaces.IIdentity; + }; + response: { + valid: boolean; + identity?: authInterfaces.IIdentity; + }; +} \ No newline at end of file diff --git a/ts_interfaces/requests/config.ts b/ts_interfaces/requests/config.ts new file mode 100644 index 0000000..b5d42a3 --- /dev/null +++ b/ts_interfaces/requests/config.ts @@ -0,0 +1,35 @@ +import * as plugins from '../plugins.js'; +import * as authInterfaces from '../data/auth.js'; + +// Get Configuration +export interface IReq_GetConfiguration extends plugins.typedrequestInterfaces.implementsTR< + plugins.typedrequestInterfaces.ITypedRequest, + IReq_GetConfiguration +> { + method: 'getConfiguration'; + request: { + identity?: authInterfaces.IIdentity; + section?: string; + }; + response: { + config: any; + section?: string; + }; +} + +// Update Configuration +export interface IReq_UpdateConfiguration extends plugins.typedrequestInterfaces.implementsTR< + plugins.typedrequestInterfaces.ITypedRequest, + IReq_UpdateConfiguration +> { + method: 'updateConfiguration'; + request: { + identity?: authInterfaces.IIdentity; + section: string; + config: any; + }; + response: { + updated: boolean; + config: any; + }; +} \ No newline at end of file diff --git a/ts_interfaces/requests/index.ts b/ts_interfaces/requests/index.ts new file mode 100644 index 0000000..9c8485e --- /dev/null +++ b/ts_interfaces/requests/index.ts @@ -0,0 +1,4 @@ +export * from './admin.js'; +export * from './config.js'; +export * from './logs.js'; +export * from './stats.js'; \ No newline at end of file diff --git a/ts_interfaces/requests/logs.ts b/ts_interfaces/requests/logs.ts new file mode 100644 index 0000000..911efc8 --- /dev/null +++ b/ts_interfaces/requests/logs.ts @@ -0,0 +1,44 @@ +import * as plugins from '../plugins.js'; +import * as authInterfaces from '../data/auth.js'; +import * as statsInterfaces from '../data/stats.js'; + +// Get Recent Logs +export interface IReq_GetRecentLogs extends plugins.typedrequestInterfaces.implementsTR< + plugins.typedrequestInterfaces.ITypedRequest, + IReq_GetRecentLogs +> { + method: 'getRecentLogs'; + request: { + identity?: authInterfaces.IIdentity; + level?: 'debug' | 'info' | 'warn' | 'error'; + category?: 'smtp' | 'dns' | 'security' | 'system' | 'email'; + limit?: number; + offset?: number; + search?: string; + timeRange?: '1h' | '6h' | '24h' | '7d' | '30d'; + }; + response: { + logs: statsInterfaces.ILogEntry[]; + total: number; + hasMore: boolean; + }; +} + +// Get Log Stream +export interface IReq_GetLogStream extends plugins.typedrequestInterfaces.implementsTR< + plugins.typedrequestInterfaces.ITypedRequest, + IReq_GetLogStream +> { + method: 'getLogStream'; + request: { + identity?: authInterfaces.IIdentity; + follow?: boolean; + filters?: { + level?: string[]; + category?: string[]; + }; + }; + response: { + logStream: plugins.typedrequestInterfaces.IVirtualStream; + }; +} \ No newline at end of file diff --git a/ts_interfaces/requests/stats.ts b/ts_interfaces/requests/stats.ts new file mode 100644 index 0000000..b7afe28 --- /dev/null +++ b/ts_interfaces/requests/stats.ts @@ -0,0 +1,162 @@ +import * as plugins from '../plugins.js'; +import * as authInterfaces from '../data/auth.js'; +import * as statsInterfaces from '../data/stats.js'; + +// Server Statistics +export interface IReq_GetServerStatistics extends plugins.typedrequestInterfaces.implementsTR< + plugins.typedrequestInterfaces.ITypedRequest, + IReq_GetServerStatistics +> { + method: 'getServerStatistics'; + request: { + identity?: authInterfaces.IIdentity; + includeHistory?: boolean; + timeRange?: '1h' | '6h' | '24h' | '7d' | '30d'; + }; + response: { + stats: statsInterfaces.IServerStats; + history?: Array<{ + timestamp: number; + value: number; + }>; + }; +} + +// Email Statistics +export interface IReq_GetEmailStatistics extends plugins.typedrequestInterfaces.implementsTR< + plugins.typedrequestInterfaces.ITypedRequest, + IReq_GetEmailStatistics +> { + method: 'getEmailStatistics'; + request: { + identity?: authInterfaces.IIdentity; + timeRange?: '1h' | '6h' | '24h' | '7d' | '30d'; + domain?: string; + includeDetails?: boolean; + }; + response: { + stats: statsInterfaces.IEmailStats; + domainBreakdown?: { + [domain: string]: statsInterfaces.IEmailStats; + }; + }; +} + +// DNS Statistics +export interface IReq_GetDnsStatistics extends plugins.typedrequestInterfaces.implementsTR< + plugins.typedrequestInterfaces.ITypedRequest, + IReq_GetDnsStatistics +> { + method: 'getDnsStatistics'; + request: { + identity?: authInterfaces.IIdentity; + timeRange?: '1h' | '6h' | '24h' | '7d' | '30d'; + domain?: string; + includeQueryTypes?: boolean; + }; + response: { + stats: statsInterfaces.IDnsStats; + domainBreakdown?: { + [domain: string]: statsInterfaces.IDnsStats; + }; + }; +} + +// Rate Limit Status +export interface IReq_GetRateLimitStatus extends plugins.typedrequestInterfaces.implementsTR< + plugins.typedrequestInterfaces.ITypedRequest, + IReq_GetRateLimitStatus +> { + method: 'getRateLimitStatus'; + request: { + identity?: authInterfaces.IIdentity; + domain?: string; + ip?: string; + includeBlocked?: boolean; + }; + response: { + limits: statsInterfaces.IRateLimitInfo[]; + globalLimit?: { + current: number; + limit: number; + remaining: number; + }; + }; +} + +// Security Metrics +export interface IReq_GetSecurityMetrics extends plugins.typedrequestInterfaces.implementsTR< + plugins.typedrequestInterfaces.ITypedRequest, + IReq_GetSecurityMetrics +> { + method: 'getSecurityMetrics'; + request: { + identity?: authInterfaces.IIdentity; + timeRange?: '1h' | '6h' | '24h' | '7d' | '30d'; + includeDetails?: boolean; + }; + response: { + metrics: statsInterfaces.ISecurityMetrics; + trends?: { + spam: Array<{ timestamp: number; value: number }>; + malware: Array<{ timestamp: number; value: number }>; + phishing: Array<{ timestamp: number; value: number }>; + }; + }; +} + +// Active Connections +export interface IReq_GetActiveConnections extends plugins.typedrequestInterfaces.implementsTR< + plugins.typedrequestInterfaces.ITypedRequest, + IReq_GetActiveConnections +> { + method: 'getActiveConnections'; + request: { + identity?: authInterfaces.IIdentity; + protocol?: 'smtp' | 'smtps' | 'http' | 'https'; + state?: string; + }; + response: { + connections: statsInterfaces.IConnectionInfo[]; + summary: { + total: number; + byProtocol: { + [protocol: string]: number; + }; + byState: { + [state: string]: number; + }; + }; + }; +} + +// Queue Status +export interface IReq_GetQueueStatus extends plugins.typedrequestInterfaces.implementsTR< + plugins.typedrequestInterfaces.ITypedRequest, + IReq_GetQueueStatus +> { + method: 'getQueueStatus'; + request: { + identity?: authInterfaces.IIdentity; + queueName?: string; + }; + response: { + queues: statsInterfaces.IQueueStatus[]; + totalItems: number; + }; +} + +// Health Check +export interface IReq_GetHealthStatus extends plugins.typedrequestInterfaces.implementsTR< + plugins.typedrequestInterfaces.ITypedRequest, + IReq_GetHealthStatus +> { + method: 'getHealthStatus'; + request: { + identity?: authInterfaces.IIdentity; + detailed?: boolean; + }; + response: { + health: statsInterfaces.IHealthStatus; + }; +} \ No newline at end of file