BREAKING CHANGE(mta): migrate internal MTA to @push.rocks/smartmta and remove legacy mail/deliverability implementation
This commit is contained in:
@@ -1,8 +1,8 @@
|
||||
# @serve.zone/dcrouter-interfaces
|
||||
|
||||
TypeScript interfaces and type definitions for the DCRouter OpsServer API. 📡
|
||||
TypeScript interfaces and type definitions for the DcRouter OpsServer API. 📡
|
||||
|
||||
This module provides strongly-typed interfaces for communicating with the DCRouter OpsServer via TypedRequest. Use these interfaces for type-safe API interactions in your frontend applications or integration code.
|
||||
This module provides strongly-typed interfaces for communicating with the DcRouter OpsServer via [TypedRequest](https://code.foss.global/api.global/typedrequest). Use these interfaces for type-safe API interactions in your frontend applications or integration code.
|
||||
|
||||
## Issue Reporting and Security
|
||||
|
||||
@@ -11,11 +11,15 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
npm install @serve.zone/dcrouter-interfaces --save
|
||||
# or
|
||||
pnpm add @serve.zone/dcrouter-interfaces
|
||||
```
|
||||
|
||||
Or import directly from the main package:
|
||||
|
||||
```typescript
|
||||
import { data, requests } from '@serve.zone/dcrouter/interfaces';
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```typescript
|
||||
@@ -31,112 +35,8 @@ const identity: data.IIdentity = {
|
||||
};
|
||||
|
||||
// Use request interfaces for API calls
|
||||
const statsRequest: requests.IReq_GetServerStatistics = {
|
||||
method: 'getServerStatistics',
|
||||
request: {
|
||||
identity,
|
||||
includeHistory: true,
|
||||
timeRange: '24h'
|
||||
},
|
||||
response: null // Will be populated by the response
|
||||
};
|
||||
```
|
||||
|
||||
## Module Structure
|
||||
|
||||
### Data Interfaces (`data`)
|
||||
|
||||
Core data types used throughout the DCRouter system:
|
||||
|
||||
#### `IIdentity`
|
||||
Authentication identity for API requests:
|
||||
```typescript
|
||||
interface IIdentity {
|
||||
jwt: string; // JWT token for authentication
|
||||
userId: string; // Unique user identifier
|
||||
name: string; // Display name
|
||||
expiresAt: number; // Token expiration timestamp
|
||||
role?: string; // User role (e.g., 'admin')
|
||||
type?: string; // Identity type
|
||||
}
|
||||
```
|
||||
|
||||
#### Statistics Interfaces
|
||||
- `IServerStats` - Overall server statistics
|
||||
- `IEmailStats` - Email throughput and delivery metrics
|
||||
- `IDnsStats` - DNS query statistics
|
||||
- `IRateLimitInfo` - Rate limiting status
|
||||
- `ISecurityMetrics` - Security event metrics
|
||||
- `IConnectionInfo` - Active connection details
|
||||
- `IQueueStatus` - Email queue status
|
||||
- `IHealthStatus` - System health information
|
||||
|
||||
### Request Interfaces (`requests`)
|
||||
|
||||
TypedRequest interfaces for the OpsServer API:
|
||||
|
||||
#### Statistics Requests
|
||||
| Interface | Method | Description |
|
||||
|-----------|--------|-------------|
|
||||
| `IReq_GetServerStatistics` | `getServerStatistics` | Get overall server stats |
|
||||
| `IReq_GetEmailStatistics` | `getEmailStatistics` | Get email throughput stats |
|
||||
| `IReq_GetDnsStatistics` | `getDnsStatistics` | Get DNS query stats |
|
||||
| `IReq_GetRateLimitStatus` | `getRateLimitStatus` | Check rate limit status |
|
||||
| `IReq_GetSecurityMetrics` | `getSecurityMetrics` | Get security event metrics |
|
||||
| `IReq_GetActiveConnections` | `getActiveConnections` | List active connections |
|
||||
| `IReq_GetQueueStatus` | `getQueueStatus` | Get email queue status |
|
||||
| `IReq_GetHealthStatus` | `getHealthStatus` | System health check |
|
||||
|
||||
#### Admin Requests
|
||||
| Interface | Method | Description |
|
||||
|-----------|--------|-------------|
|
||||
| `IReq_AdminLogin` | `adminLogin` | Authenticate as admin |
|
||||
| `IReq_AdminLogout` | `adminLogout` | End admin session |
|
||||
| `IReq_VerifyIdentity` | `verifyIdentity` | Verify JWT token |
|
||||
|
||||
#### Configuration Requests
|
||||
| Interface | Method | Description |
|
||||
|-----------|--------|-------------|
|
||||
| `IReq_GetConfiguration` | `getConfiguration` | Get current config (read-only) |
|
||||
|
||||
#### Log Requests
|
||||
| Interface | Method | Description |
|
||||
|-----------|--------|-------------|
|
||||
| `IReq_GetLogs` | `getLogs` | Retrieve system logs |
|
||||
|
||||
#### RADIUS Requests
|
||||
| Interface | Method | Description |
|
||||
|-----------|--------|-------------|
|
||||
| `IReq_GetRadiusSessions` | `getRadiusSessions` | List RADIUS sessions |
|
||||
| `IReq_GetRadiusClients` | `getRadiusClients` | List RADIUS clients |
|
||||
|
||||
#### Email Operations
|
||||
| Interface | Method | Description |
|
||||
|-----------|--------|-------------|
|
||||
| `IReq_GetEmailQueues` | `getEmailQueues` | Get email queue details |
|
||||
| `IReq_RetryEmail` | `retryEmail` | Retry failed email |
|
||||
|
||||
## Example: Complete API Integration
|
||||
|
||||
```typescript
|
||||
import * as typedrequest from '@api.global/typedrequest';
|
||||
import { data, requests } from '@serve.zone/dcrouter-interfaces';
|
||||
|
||||
// Create typed request client
|
||||
const client = new typedrequest.TypedRequest<requests.IReq_AdminLogin>(
|
||||
'https://your-dcrouter:3000/typedrequest',
|
||||
'adminLogin'
|
||||
);
|
||||
|
||||
// Login to get identity
|
||||
const loginResponse = await client.fire({
|
||||
username: 'admin',
|
||||
password: 'your-password'
|
||||
});
|
||||
|
||||
const identity = loginResponse.identity;
|
||||
|
||||
// Now use identity for authenticated requests
|
||||
const statsClient = new typedrequest.TypedRequest<requests.IReq_GetServerStatistics>(
|
||||
'https://your-dcrouter:3000/typedrequest',
|
||||
'getServerStatistics'
|
||||
@@ -147,9 +47,140 @@ const stats = await statsClient.fire({
|
||||
includeHistory: true,
|
||||
timeRange: '24h'
|
||||
});
|
||||
```
|
||||
|
||||
console.log('Server stats:', stats.stats);
|
||||
console.log('History:', stats.history);
|
||||
## Module Structure
|
||||
|
||||
### Data Interfaces (`data`)
|
||||
|
||||
Core data types used throughout the DcRouter system:
|
||||
|
||||
#### `IIdentity`
|
||||
Authentication identity for API requests:
|
||||
```typescript
|
||||
interface IIdentity {
|
||||
jwt: string; // JWT token
|
||||
userId: string; // Unique user ID
|
||||
name: string; // Display name
|
||||
expiresAt: number; // Token expiration timestamp
|
||||
role?: string; // User role (e.g., 'admin')
|
||||
type?: string; // Identity type
|
||||
}
|
||||
```
|
||||
|
||||
#### Statistics Interfaces
|
||||
| Interface | Description |
|
||||
|-----------|-------------|
|
||||
| `IServerStats` | Uptime, memory, CPU, connection counts |
|
||||
| `IEmailStats` | Sent/received/bounced/queued/failed, delivery & bounce rates |
|
||||
| `IDnsStats` | Total queries, cache hits/misses, query types |
|
||||
| `IRateLimitInfo` | Domain rate limit status (current rate, limit, remaining) |
|
||||
| `ISecurityMetrics` | Blocked IPs, spam/malware/phishing counts |
|
||||
| `IConnectionInfo` | Connection ID, remote address, protocol, state, bytes |
|
||||
| `IQueueStatus` | Queue name, size, processing/failed/retrying counts |
|
||||
| `IHealthStatus` | Healthy flag, uptime, per-service status map |
|
||||
| `INetworkMetrics` | Bandwidth, connection counts, top endpoints |
|
||||
| `ILogEntry` | Timestamp, level, category, message, metadata |
|
||||
|
||||
### Request Interfaces (`requests`)
|
||||
|
||||
TypedRequest interfaces for the OpsServer API, organized by domain:
|
||||
|
||||
#### 🔐 Authentication
|
||||
| Interface | Method | Description |
|
||||
|-----------|--------|-------------|
|
||||
| `IReq_AdminLoginWithUsernameAndPassword` | `adminLogin` | Authenticate as admin |
|
||||
| `IReq_AdminLogout` | `adminLogout` | End admin session |
|
||||
| `IReq_VerifyIdentity` | `verifyIdentity` | Verify JWT token validity |
|
||||
|
||||
#### 📊 Statistics
|
||||
| Interface | Method | Description |
|
||||
|-----------|--------|-------------|
|
||||
| `IReq_GetServerStatistics` | `getServerStatistics` | Overall server stats |
|
||||
| `IReq_GetEmailStatistics` | `getEmailStatistics` | Email throughput metrics |
|
||||
| `IReq_GetDnsStatistics` | `getDnsStatistics` | DNS query stats |
|
||||
| `IReq_GetRateLimitStatus` | `getRateLimitStatus` | Rate limit status |
|
||||
| `IReq_GetSecurityMetrics` | `getSecurityMetrics` | Security event metrics |
|
||||
| `IReq_GetActiveConnections` | `getActiveConnections` | Active connection list |
|
||||
| `IReq_GetQueueStatus` | `getQueueStatus` | Email queue status |
|
||||
| `IReq_GetHealthStatus` | `getHealthStatus` | System health check |
|
||||
| `IReq_GetCombinedMetrics` | `getCombinedMetrics` | All metrics in one request |
|
||||
|
||||
#### ⚙️ Configuration
|
||||
| Interface | Method | Description |
|
||||
|-----------|--------|-------------|
|
||||
| `IReq_GetConfiguration` | `getConfiguration` | Current config (read-only) |
|
||||
|
||||
#### 📜 Logs
|
||||
| Interface | Method | Description |
|
||||
|-----------|--------|-------------|
|
||||
| `IReq_GetRecentLogs` | `getLogs` | Retrieve system logs |
|
||||
| `IReq_GetLogStream` | `getLogStream` | Stream live logs |
|
||||
|
||||
#### 📧 Email Operations
|
||||
| Interface | Method | Description |
|
||||
|-----------|--------|-------------|
|
||||
| `IReq_GetQueuedEmails` | `getQueuedEmails` | List queued emails |
|
||||
| `IReq_GetSentEmails` | `getSentEmails` | List delivered emails |
|
||||
| `IReq_GetFailedEmails` | `getFailedEmails` | List failed emails |
|
||||
| `IReq_ResendEmail` | `resendEmail` | Re-queue a failed email |
|
||||
| `IReq_GetSecurityIncidents` | `getSecurityIncidents` | Security events |
|
||||
| `IReq_GetBounceRecords` | `getBounceRecords` | Bounce records |
|
||||
| `IReq_RemoveFromSuppressionList` | `removeFromSuppressionList` | Unsuppress an address |
|
||||
|
||||
#### 📡 RADIUS
|
||||
| Interface | Method | Description |
|
||||
|-----------|--------|-------------|
|
||||
| `IReq_GetRadiusClients` | `getRadiusClients` | List NAS clients |
|
||||
| `IReq_SetRadiusClient` | `setRadiusClient` | Add/update a NAS client |
|
||||
| `IReq_RemoveRadiusClient` | `removeRadiusClient` | Remove a NAS client |
|
||||
| `IReq_GetVlanMappings` | `getVlanMappings` | List VLAN mappings |
|
||||
| `IReq_SetVlanMapping` | `setVlanMapping` | Add/update VLAN mapping |
|
||||
| `IReq_RemoveVlanMapping` | `removeVlanMapping` | Remove VLAN mapping |
|
||||
| `IReq_TestVlanAssignment` | `testVlanAssignment` | Test what VLAN a MAC gets |
|
||||
| `IReq_GetRadiusSessions` | `getRadiusSessions` | List active sessions |
|
||||
| `IReq_DisconnectRadiusSession` | `disconnectRadiusSession` | Force disconnect |
|
||||
| `IReq_GetRadiusStatistics` | `getRadiusStatistics` | RADIUS stats |
|
||||
| `IReq_GetRadiusAccountingSummary` | `getRadiusAccountingSummary` | Accounting summary |
|
||||
|
||||
## Example: Full API Integration
|
||||
|
||||
```typescript
|
||||
import * as typedrequest from '@api.global/typedrequest';
|
||||
import { data, requests } from '@serve.zone/dcrouter-interfaces';
|
||||
|
||||
// 1. Login
|
||||
const loginClient = new typedrequest.TypedRequest<requests.IReq_AdminLoginWithUsernameAndPassword>(
|
||||
'https://your-dcrouter:3000/typedrequest',
|
||||
'adminLogin'
|
||||
);
|
||||
|
||||
const loginResponse = await loginClient.fire({
|
||||
username: 'admin',
|
||||
password: 'your-password'
|
||||
});
|
||||
const identity = loginResponse.identity;
|
||||
|
||||
// 2. Fetch combined metrics
|
||||
const metricsClient = new typedrequest.TypedRequest<requests.IReq_GetCombinedMetrics>(
|
||||
'https://your-dcrouter:3000/typedrequest',
|
||||
'getCombinedMetrics'
|
||||
);
|
||||
|
||||
const metrics = await metricsClient.fire({ identity });
|
||||
console.log('Server:', metrics.serverStats);
|
||||
console.log('Email:', metrics.emailStats);
|
||||
console.log('DNS:', metrics.dnsStats);
|
||||
console.log('Security:', metrics.securityMetrics);
|
||||
|
||||
// 3. Check email queues
|
||||
const queueClient = new typedrequest.TypedRequest<requests.IReq_GetQueuedEmails>(
|
||||
'https://your-dcrouter:3000/typedrequest',
|
||||
'getQueuedEmails'
|
||||
);
|
||||
|
||||
const queued = await queueClient.fire({ identity });
|
||||
console.log('Queued emails:', queued.emails.length);
|
||||
```
|
||||
|
||||
## License and Legal Information
|
||||
|
||||
Reference in New Issue
Block a user