@serve.zone/dcrouter 13.17.9 → 13.19.0

package/ts/email/classes.smartmta-storage-manager.ts

@@ -0,0 +1,108 @@
+import * as plugins from '../plugins.js';
+import type { IStorageManagerLike } from '@push.rocks/smartmta';
+
+export class SmartMtaStorageManager implements IStorageManagerLike {
+  private readonly resolvedRootDir: string;
+
+  constructor(private rootDir: string) {
+    this.resolvedRootDir = plugins.path.resolve(rootDir);
+    plugins.fsUtils.ensureDirSync(this.resolvedRootDir);
+  }
+
+  private normalizeKey(key: string): string {
+    return key.replace(/^\/+/, '').replace(/\\/g, '/');
+  }
+
+  private resolvePathForKey(key: string): string {
+    const normalizedKey = this.normalizeKey(key);
+    const resolvedPath = plugins.path.resolve(this.resolvedRootDir, normalizedKey);
+    if (
+      resolvedPath !== this.resolvedRootDir
+      && !resolvedPath.startsWith(`${this.resolvedRootDir}${plugins.path.sep}`)
+    ) {
+      throw new Error(`Storage key escapes root directory: ${key}`);
+    }
+    return resolvedPath;
+  }
+
+  private toStorageKey(filePath: string): string {
+    const relativePath = plugins.path.relative(this.resolvedRootDir, filePath).split(plugins.path.sep).join('/');
+    return `/${relativePath}`;
+  }
+
+  public async get(key: string): Promise<string | null> {
+    const filePath = this.resolvePathForKey(key);
+    try {
+      return await plugins.fs.promises.readFile(filePath, 'utf8');
+    } catch (error: unknown) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  public async set(key: string, value: string): Promise<void> {
+    const filePath = this.resolvePathForKey(key);
+    await plugins.fs.promises.mkdir(plugins.path.dirname(filePath), { recursive: true });
+    await plugins.fs.promises.writeFile(filePath, value, 'utf8');
+  }
+
+  public async list(prefix: string): Promise<string[]> {
+    const prefixPath = this.resolvePathForKey(prefix);
+    try {
+      const stat = await plugins.fs.promises.stat(prefixPath);
+      if (stat.isFile()) {
+        return [this.toStorageKey(prefixPath)];
+      }
+    } catch (error: unknown) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        return [];
+      }
+      throw error;
+    }
+
+    const results: string[] = [];
+    const walk = async (currentPath: string): Promise<void> => {
+      const entries = await plugins.fs.promises.readdir(currentPath, { withFileTypes: true });
+      for (const entry of entries) {
+        const entryPath = plugins.path.join(currentPath, entry.name);
+        if (entry.isDirectory()) {
+          await walk(entryPath);
+        } else if (entry.isFile()) {
+          results.push(this.toStorageKey(entryPath));
+        }
+      }
+    };
+
+    await walk(prefixPath);
+    return results.sort();
+  }
+
+  public async delete(key: string): Promise<void> {
+    const targetPath = this.resolvePathForKey(key);
+    try {
+      const stat = await plugins.fs.promises.stat(targetPath);
+      if (stat.isDirectory()) {
+        await plugins.fs.promises.rm(targetPath, { recursive: true, force: true });
+      } else {
+        await plugins.fs.promises.unlink(targetPath);
+      }
+    } catch (error: unknown) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        return;
+      }
+      throw error;
+    }
+
+    let currentDir = plugins.path.dirname(targetPath);
+    while (currentDir.startsWith(this.resolvedRootDir) && currentDir !== this.resolvedRootDir) {
+      const entries = await plugins.fs.promises.readdir(currentDir);
+      if (entries.length > 0) {
+        break;
+      }
+      await plugins.fs.promises.rmdir(currentDir);
+      currentDir = plugins.path.dirname(currentDir);
+    }
+  }
+}

package/ts/email/email-dns-records.ts

@@ -0,0 +1,53 @@
+import type {
+  IEmailDnsRecord,
+  TDnsRecordStatus,
+} from '../../ts_interfaces/data/email-domain.js';
+
+type TEmailDnsStatusKey = 'mx' | 'spf' | 'dkim' | 'dmarc';
+
+export interface IBuildEmailDnsRecordsOptions {
+  domain: string;
+  hostname: string;
+  selector?: string;
+  dkimValue?: string;
+  mxPriority?: number;
+  dmarcPolicy?: string;
+  dmarcRua?: string;
+  statuses?: Partial<Record<TEmailDnsStatusKey, TDnsRecordStatus>>;
+}
+
+export function buildEmailDnsRecords(options: IBuildEmailDnsRecordsOptions): IEmailDnsRecord[] {
+  const statusFor = (key: TEmailDnsStatusKey): TDnsRecordStatus => options.statuses?.[key] ?? 'unchecked';
+  const selector = options.selector || 'default';
+  const records: IEmailDnsRecord[] = [
+    {
+      type: 'MX',
+      name: options.domain,
+      value: `${options.mxPriority ?? 10} ${options.hostname}`,
+      status: statusFor('mx'),
+    },
+    {
+      type: 'TXT',
+      name: options.domain,
+      value: 'v=spf1 a mx ~all',
+      status: statusFor('spf'),
+    },
+    {
+      type: 'TXT',
+      name: `_dmarc.${options.domain}`,
+      value: `v=DMARC1; p=${options.dmarcPolicy ?? 'none'}; rua=mailto:${options.dmarcRua ?? `dmarc@${options.domain}`}`,
+      status: statusFor('dmarc'),
+    },
+  ];
+
+  if (options.dkimValue) {
+    records.splice(2, 0, {
+      type: 'TXT',
+      name: `${selector}._domainkey.${options.domain}`,
+      value: options.dkimValue,
+      status: statusFor('dkim'),
+    });
+  }
+
+  return records;
+}

package/ts/email/index.ts

@@ -1 +1,3 @@
 export * from './classes.email-domain.manager.js';
+export * from './classes.smartmta-storage-manager.js';
+export * from './email-dns-records.js';

package/ts/opsserver/handlers/email-ops.handler.ts

@@ -48,7 +48,7 @@ export class EmailOpsHandler {
           }
 
           const queue = emailServer.deliveryQueue;
-          const item = queue.getItem(dataArg.emailId);
+          const item = emailServer.getQueueItem(dataArg.emailId);
 
           if (!item) {
             return { success: false, error: 'Email not found in queue' };
@@ -82,22 +82,10 @@ export class EmailOpsHandler {
    */
   private getAllQueueEmails(): interfaces.requests.IEmail[] {
     const emailServer = this.opsServerRef.dcRouterRef.emailServer;
-    if (!emailServer?.deliveryQueue) {
+    if (!emailServer) {
       return [];
     }
-
-    const queue = emailServer.deliveryQueue;
-    const queueMap = (queue as any).queue as Map<string, any>;
-
-    if (!queueMap) {
-      return [];
-    }
-
-    const emails: interfaces.requests.IEmail[] = [];
-
-    for (const [id, item] of queueMap.entries()) {
-      emails.push(this.mapQueueItemToEmail(item));
-    }
+    const emails = emailServer.getQueueItems().map((item) => this.mapQueueItemToEmail(item));
 
     // Sort by createdAt descending (newest first)
     emails.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
@@ -110,12 +98,10 @@ export class EmailOpsHandler {
    */
   private getEmailDetail(emailId: string): interfaces.requests.IEmailDetail | null {
     const emailServer = this.opsServerRef.dcRouterRef.emailServer;
-    if (!emailServer?.deliveryQueue) {
+    if (!emailServer) {
       return null;
     }
-
-    const queue = emailServer.deliveryQueue;
-    const item = queue.getItem(emailId);
+    const item = emailServer.getQueueItem(emailId);
 
     if (!item) {
       return null;

package/ts/opsserver/handlers/route-management.handler.ts

@@ -87,12 +87,12 @@ export class RouteManagementHandler {
           if (!manager) {
             return { success: false, message: 'Route management not initialized' };
           }
-          const ok = await manager.updateRoute(dataArg.id, {
+          const result = await manager.updateRoute(dataArg.id, {
             route: dataArg.route as any,
             enabled: dataArg.enabled,
             metadata: dataArg.metadata,
           });
-          return { success: ok, message: ok ? undefined : 'Route not found' };
+          return result;
         },
       ),
     );
@@ -107,8 +107,7 @@ export class RouteManagementHandler {
           if (!manager) {
             return { success: false, message: 'Route management not initialized' };
           }
-          const ok = await manager.deleteRoute(dataArg.id);
-          return { success: ok, message: ok ? undefined : 'Route not found' };
+          return manager.deleteRoute(dataArg.id);
         },
       ),
     );
@@ -123,8 +122,7 @@ export class RouteManagementHandler {
           if (!manager) {
             return { success: false, message: 'Route management not initialized' };
           }
-          const ok = await manager.toggleRoute(dataArg.id, dataArg.enabled);
-          return { success: ok, message: ok ? undefined : 'Route not found' };
+          return manager.toggleRoute(dataArg.id, dataArg.enabled);
         },
       ),
     );

package/ts/opsserver/handlers/stats.handler.ts

@@ -530,13 +530,49 @@ export class StatsHandler {
       nextRetry?: number;
     }>;
   }> {
-    // TODO: Implement actual queue status collection
+    const emailServer = this.opsServerRef.dcRouterRef.emailServer;
+    if (!emailServer) {
+      return {
+        pending: 0,
+        active: 0,
+        failed: 0,
+        retrying: 0,
+        items: [],
+      };
+    }
+
+    const queueStats = emailServer.getQueueStats();
+    const items = emailServer.getQueueItems()
+      .sort((a, b) => {
+        const left = a.createdAt instanceof Date ? a.createdAt.getTime() : new Date(a.createdAt).getTime();
+        const right = b.createdAt instanceof Date ? b.createdAt.getTime() : new Date(b.createdAt).getTime();
+        return right - left;
+      })
+      .slice(0, 50)
+      .map((item) => {
+        const emailLike = item.processingResult;
+        const recipients = Array.isArray(emailLike?.to)
+          ? emailLike.to
+          : Array.isArray(emailLike?.email?.to)
+            ? emailLike.email.to
+            : [];
+        const subject = emailLike?.subject || emailLike?.email?.subject || '';
+        return {
+          id: item.id,
+          recipient: recipients[0] || '',
+          subject,
+          status: item.status,
+          attempts: item.attempts,
+          nextRetry: item.nextAttempt instanceof Date ? item.nextAttempt.getTime() : undefined,
+        };
+      });
+
     return {
-      pending: 0,
-      active: 0,
-      failed: 0,
-      retrying: 0,
-      items: [],
+      pending: queueStats.status.pending,
+      active: queueStats.status.processing,
+      failed: queueStats.status.failed,
+      retrying: queueStats.status.deferred,
+      items,
     };
   }
   
@@ -600,4 +636,4 @@ export class StatsHandler {
       ],
     };
   }
-}
+}

package/ts_apiclient/readme.md

@@ -1,8 +1,8 @@
 # @serve.zone/dcrouter-apiclient
 
-A typed, object-oriented API client for DcRouter with a fluent builder pattern. 🔧
+Typed, object-oriented API client for operating a running dcrouter instance. 🔧
 
-Programmatically manage your DcRouter instance — routes, certificates, API tokens, remote ingress edges, RADIUS, email operations, and more — all with full TypeScript type safety and an intuitive OO interface.
+Use this package when you want a clean TypeScript client instead of manually firing TypedRequest calls. It wraps the OpsServer API in resource managers and resource classes such as routes, certificates, tokens, edges, emails, stats, logs, config, and RADIUS.
 
 ## Issue Reporting and Security
 
@@ -14,7 +14,7 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 pnpm add @serve.zone/dcrouter-apiclient
 ```
 
-Or import directly from the main package:
+Or import through the main package:
 
 ```typescript
 import { DcRouterApiClient } from '@serve.zone/dcrouter/apiclient';
@@ -23,239 +23,113 @@ import { DcRouterApiClient } from '@serve.zone/dcrouter/apiclient';
 ## Quick Start
 
 ```typescript
-import { DcRouterApiClient } from '@serve.zone/dcrouter/apiclient';
+import { DcRouterApiClient } from '@serve.zone/dcrouter-apiclient';
 
-const client = new DcRouterApiClient({ baseUrl: 'https://dcrouter.example.com' });
+const client = new DcRouterApiClient({
+  baseUrl: 'https://dcrouter.example.com',
+});
 
-// Authenticate
 await client.login('admin', 'password');
 
-// List routes
-const { routes, warnings } = await client.routes.list();
-console.log(`${routes.length} routes, ${warnings.length} warnings`);
+const { routes } = await client.routes.list();
+console.log(routes.map((route) => `${route.origin}:${route.name}`));
 
-// Check health
-const { health } = await client.stats.getHealth();
-console.log(`Healthy: ${health.healthy}`);
+await client.routes.build()
+  .setName('api-gateway')
+  .setMatch({ ports: 443, domains: ['api.example.com'] })
+  .setAction({ type: 'forward', targets: [{ host: '127.0.0.1', port: 8080 }] })
+  .save();
 ```
 
-## Usage
+## Authentication Modes
 
-### 🔐 Authentication
+| Mode | How it works |
+| --- | --- |
+| Admin login | Call `login(username, password)` and the client stores the returned identity for later requests |
+| API token | Pass `apiToken` into the constructor for token-based automation |
 
 ```typescript
-// Login with credentials — identity is stored and auto-injected into all subsequent requests
-const identity = await client.login('admin', 'password');
-
-// Verify current session
-const { valid } = await client.verifyIdentity();
-
-// Logout
-await client.logout();
-
-// Or use an API token for programmatic access (route management only)
 const client = new DcRouterApiClient({
   baseUrl: 'https://dcrouter.example.com',
   apiToken: 'dcr_your_token_here',
 });
 ```
 
-### 🌐 Routes — OO Resources + Builder
+## Main Managers
 
-Routes are returned as `Route` instances with methods for update, delete, toggle, and overrides:
+| Manager | Purpose |
+| --- | --- |
+| `client.routes` | List routes and create API-managed routes |
+| `client.certificates` | Inspect and operate on certificate records |
+| `client.apiTokens` | Create, list, toggle, roll, revoke API tokens |
+| `client.remoteIngress` | Manage registered remote ingress edges |
+| `client.stats` | Read operational metrics and health data |
+| `client.config` | Read current configuration view |
+| `client.logs` | Read recent logs or stream them |
+| `client.emails` | List emails and trigger resend flows |
+| `client.radius` | Operate on RADIUS clients, VLANs, sessions, and accounting |
 
-```typescript
-// List all routes (hardcoded + programmatic)
-const { routes, warnings } = await client.routes.list();
+## Route Behavior
 
-// Inspect a route
-const route = routes[0];
-console.log(route.name, route.source, route.enabled);
+Routes are returned as `Route` instances with:
 
-// Modify a programmatic route
-await route.update({ name: 'renamed-route' });
-await route.toggle(false);
-await route.delete();
+- `id`
+- `name`
+- `enabled`
+- `origin`
 
-// Override a hardcoded route (disable it)
-const hardcodedRoute = routes.find(r => r.source === 'hardcoded');
-await hardcodedRoute.setOverride(false);
-await hardcodedRoute.removeOverride();
-```
+Important behavior:
 
-**Builder pattern** for creating new routes:
+- API routes can be created, updated, deleted, and toggled.
+- System routes can be listed and toggled, but not edited or deleted.
+- A system route is any route whose `origin !== 'api'`.
 
 ```typescript
-const newRoute = await client.routes.build()
-  .setName('api-gateway')
-  .setMatch({ ports: 443, domains: ['api.example.com'] })
-  .setAction({ type: 'forward', targets: [{ host: 'backend', port: 8080 }] })
-  .setTls({ mode: 'terminate', certificate: 'auto' })
-  .setEnabled(true)
-  .save();
+const { routes } = await client.routes.list();
 
-// Or use quick creation
-const route = await client.routes.create(routeConfig);
+for (const route of routes) {
+  if (route.origin !== 'api') {
+    await route.toggle(false);
+  }
+}
 ```
 
-### 🔑 API Tokens
+## Builder Example
 
 ```typescript
-// List existing tokens
-const tokens = await client.apiTokens.list();
-
-// Create with builder
-const token = await client.apiTokens.build()
-  .setName('ci-pipeline')
-  .setScopes(['routes:read', 'routes:write'])
-  .addScope('config:read')
-  .setExpiresInDays(90)
+const route = await client.routes.build()
+  .setName('internal-app')
+  .setMatch({
+    ports: 80,
+    domains: ['internal.example.com'],
+  })
+  .setAction({
+    type: 'forward',
+    targets: [{ host: '127.0.0.1', port: 3000 }],
+  })
+  .setEnabled(true)
   .save();
 
-console.log(token.tokenValue); // Only available at creation time!
-
-// Manage tokens
-await token.toggle(false);       // Disable
-const newValue = await token.roll(); // Regenerate secret
-await token.revoke();            // Delete
+await route.toggle(false);
 ```
 
-### 🔐 Certificates
+## Example: Certificates and Stats
 
 ```typescript
 const { certificates, summary } = await client.certificates.list();
-console.log(`${summary.valid} valid, ${summary.expiring} expiring, ${summary.failed} failed`);
-
-// Operate on individual certificates
-const cert = certificates[0];
-await cert.reprovision();
-const exported = await cert.export();
-await cert.delete();
-
-// Import a certificate
-await client.certificates.import({
-  id: 'cert-id',
-  domainName: 'example.com',
-  created: Date.now(),
-  validUntil: Date.now() + 90 * 24 * 3600 * 1000,
-  privateKey: '...',
-  publicKey: '...',
-  csr: '...',
-});
-```
+console.log(summary.valid, summary.failed);
 
-### 🌍 Remote Ingress
-
-```typescript
-// List edges and their statuses
-const edges = await client.remoteIngress.list();
-const statuses = await client.remoteIngress.getStatuses();
-
-// Create with builder
-const edge = await client.remoteIngress.build()
-  .setName('edge-nyc-01')
-  .setListenPorts([80, 443])
-  .setAutoDerivePorts(true)
-  .setTags(['us-east'])
-  .save();
-
-// Manage an edge
-await edge.update({ name: 'edge-nyc-02' });
-const newSecret = await edge.regenerateSecret();
-const token = await edge.getConnectionToken();
-await edge.delete();
-```
-
-### 📊 Statistics (Read-Only)
-
-```typescript
-const serverStats = await client.stats.getServer({ timeRange: '24h', includeHistory: true });
-const emailStats = await client.stats.getEmail({ domain: 'example.com' });
-const dnsStats = await client.stats.getDns();
-const security = await client.stats.getSecurity({ includeDetails: true });
-const connections = await client.stats.getConnections({ protocol: 'https' });
-const queues = await client.stats.getQueues();
-const health = await client.stats.getHealth(true);
-const network = await client.stats.getNetwork();
-const combined = await client.stats.getCombined({ server: true, email: true });
-```
-
-### ⚙️ Configuration & Logs
-
-```typescript
-// Read-only configuration
-const config = await client.config.get();
-const emailSection = await client.config.get('email');
-
-// Logs
-const { logs, total, hasMore } = await client.logs.getRecent({
-  level: 'error',
-  category: 'smtp',
-  limit: 50,
-});
-```
-
-### 📧 Email Operations
-
-```typescript
-const emails = await client.emails.list();
-const email = emails[0];
-const detail = await email.getDetail();
-await email.resend();
-
-// Or use the manager directly
-const detail2 = await client.emails.getDetail('email-id');
-await client.emails.resend('email-id');
-```
-
-### 📡 RADIUS
-
-```typescript
-// Client management
-const clients = await client.radius.clients.list();
-await client.radius.clients.set({
-  name: 'switch-1',
-  ipRange: '192.168.1.0/24',
-  secret: 'shared-secret',
-  enabled: true,
-});
-await client.radius.clients.remove('switch-1');
-
-// VLAN management
-const { mappings, config: vlanConfig } = await client.radius.vlans.list();
-await client.radius.vlans.set({ mac: 'aa:bb:cc:dd:ee:ff', vlan: 10, enabled: true });
-const result = await client.radius.vlans.testAssignment('aa:bb:cc:dd:ee:ff');
-await client.radius.vlans.updateConfig({ defaultVlan: 200 });
-
-// Sessions
-const { sessions } = await client.radius.sessions.list({ vlanId: 10 });
-await client.radius.sessions.disconnect('session-id', 'Admin disconnect');
-
-// Statistics & Accounting
-const stats = await client.radius.getStatistics();
-const summary = await client.radius.getAccountingSummary(startTime, endTime);
+const health = await client.stats.getHealth();
+const recentLogs = await client.logs.getRecent({ level: 'error', limit: 20 });
 ```
 
-## API Surface
-
-| Manager | Methods |
-|---------|---------|
-| `client.login()` / `logout()` / `verifyIdentity()` | Authentication |
-| `client.routes` | `list()`, `create()`, `build()` → Route: `update()`, `delete()`, `toggle()`, `setOverride()`, `removeOverride()` |
-| `client.certificates` | `list()`, `import()` → Certificate: `reprovision()`, `delete()`, `export()` |
-| `client.apiTokens` | `list()`, `create()`, `build()` → ApiToken: `revoke()`, `roll()`, `toggle()` |
-| `client.remoteIngress` | `list()`, `getStatuses()`, `create()`, `build()` → RemoteIngress: `update()`, `delete()`, `regenerateSecret()`, `getConnectionToken()` |
-| `client.stats` | `getServer()`, `getEmail()`, `getDns()`, `getRateLimits()`, `getSecurity()`, `getConnections()`, `getQueues()`, `getHealth()`, `getNetwork()`, `getCombined()` |
-| `client.config` | `get(section?)` |
-| `client.logs` | `getRecent()`, `getStream()` |
-| `client.emails` | `list()`, `getDetail()`, `resend()` → Email: `getDetail()`, `resend()` |
-| `client.radius` | `.clients.list/set/remove()`, `.vlans.list/set/remove/updateConfig/testAssignment()`, `.sessions.list/disconnect()`, `getStatistics()`, `getAccountingSummary()` |
-
-## Architecture
+## What This Package Does Not Do
 
-The client uses HTTP-based [TypedRequest](https://code.foss.global/api.global/typedrequest) for transport. All requests are sent as POST to `{baseUrl}/typedrequest`. Authentication (JWT identity and/or API token) is automatically injected into every request payload via `buildRequestPayload()`.
+- It does not start dcrouter.
+- It does not embed the dashboard.
+- It does not replace the request interfaces package if you only need raw types.
 
-Resource classes (`Route`, `Certificate`, `ApiToken`, `RemoteIngress`, `Email`) hold a reference to the client and provide instance methods that fire the appropriate TypedRequest operations. Builder classes (`RouteBuilder`, `ApiTokenBuilder`, `RemoteIngressBuilder`) use fluent chaining and a terminal `.save()` method.
+Use `@serve.zone/dcrouter` to run the server, `@serve.zone/dcrouter-web` for the dashboard bundle/components, and `@serve.zone/dcrouter-interfaces` for raw API contracts.
 
 ## License and Legal Information
 

package/ts_web/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/dcrouter',
-  version: '13.17.9',
+  version: '13.19.0',
   description: 'A multifaceted routing service handling mail and SMS delivery functions.'
 }