@simplysm/service-server 13.0.71 → 13.0.74

package/README.md

@@ -2,78 +2,61 @@
 
 Simplysm package - service module (server)
 
+Provides a full-featured HTTP/WebSocket server built on Fastify for hosting Simplysm services. Includes JWT-based authentication, ORM integration, file upload/static serving, SMTP email, and auto-update capabilities.
+
 ## Installation
 
+```bash
 pnpm add @simplysm/service-server
-
-## Source Index
-
-### Types
-
-| Source | Exports | Description | Test |
-|--------|---------|-------------|------|
-| `src/types/server-options.ts` | `ServiceServerOptions` | Configuration interface for the service server (port, SSL, auth, services) | - |
-
-### Auth
-
-| Source | Exports | Description | Test |
-|--------|---------|-------------|------|
-| `src/auth/auth-token-payload.ts` | `AuthTokenPayload` | JWT payload interface extending JWTPayload with roles and auth data | - |
-| `src/auth/jwt-manager.ts` | `signJwt`, `verifyJwt`, `decodeJwt` | Sign, verify, and decode HS256 JWT tokens using the jose library | - |
-
-### Core
-
-| Source | Exports | Description | Test |
-|--------|---------|-------------|------|
-| `src/core/define-service.ts` | `ServiceContext`, `createServiceContext`, `getServiceAuthPermissions`, `auth`, `ServiceDefinition`, `defineService`, `ServiceMethods` | Define services with typed context, auth wrappers, and method type extraction | `define-service.spec.ts` |
-| `src/core/service-executor.ts` | `runServiceMethod` | Resolve a service method call and enforce auth permission checks | `service-executor.spec.ts` |
-
-### Transport - Socket
-
-| Source | Exports | Description | Test |
-|--------|---------|-------------|------|
-| `src/transport/socket/websocket-handler.ts` | `WebSocketHandler`, `createWebSocketHandler` | Manage multiple WebSocket connections, route messages, and broadcast events | - |
-| `src/transport/socket/service-socket.ts` | `ServiceSocket`, `createServiceSocket` | Manage a single WebSocket connection with protocol encoding and keep-alive | - |
-
-### Transport - HTTP
-
-| Source | Exports | Description | Test |
-|--------|---------|-------------|------|
-| `src/transport/http/http-request-handler.ts` | `handleHttpRequest` | Handle HTTP GET/POST API requests with JWT auth and parameter parsing | - |
-| `src/transport/http/upload-handler.ts` | `handleUpload` | Handle multipart file uploads with JWT auth and UUID-based storage | - |
-| `src/transport/http/static-file-handler.ts` | `handleStaticFile` | Serve static files from the www directory with path traversal protection | - |
-
-### Protocol
-
-| Source | Exports | Description | Test |
-|--------|---------|-------------|------|
-| `src/protocol/protocol-wrapper.ts` | `ProtocolWrapper`, `createProtocolWrapper` | Encode/decode service messages with automatic worker thread offloading | - |
-
-### Services
-
-| Source | Exports | Description | Test |
-|--------|---------|-------------|------|
-| `src/services/orm-service.ts` | `OrmService`, `OrmServiceType` | Built-in service exposing ORM database operations over WebSocket | `orm-service.spec.ts` |
-| `src/services/auto-update-service.ts` | `AutoUpdateService`, `AutoUpdateServiceType` | Built-in service for serving the latest app update package by platform | - |
-
-### Utils
-
-| Source | Exports | Description | Test |
-|--------|---------|-------------|------|
-| `src/utils/config-manager.ts` | `getConfig` | Load and cache JSON config files with live-reload via file watcher | - |
-
-### Legacy
-
-| Source | Exports | Description | Test |
-|--------|---------|-------------|------|
-| `src/legacy/v1-auto-update-handler.ts` | `handleV1Connection` | Handle V1 legacy WebSocket clients for auto-update only | - |
-
-### Main
-
-| Source | Exports | Description | Test |
-|--------|---------|-------------|------|
-| `src/service-server.ts` | `ServiceServer`, `createServiceServer` | Main Fastify-based HTTP/WebSocket server with routing and graceful shutdown | - |
-
-## License
-
-Apache-2.0
+```
+
+## Architecture Overview
+
+The package is organized into four areas:
+
+- **Auth** — JWT token signing, verification, and decoding (`signJwt`, `verifyJwt`, `decodeJwt`, `AuthTokenPayload`).
+- **Services** — Service definition API (`defineService`, `auth`, `ServiceContext`, `runServiceMethod`) and three ready-to-use built-in services (`OrmService`, `AutoUpdateService`, `SmtpClientService`).
+- **Transport** — WebSocket connection management (`WebSocketHandler`, `ServiceSocket`), HTTP route handlers (`handleHttpRequest`, `handleUpload`, `handleStaticFile`), and the binary protocol layer (`ProtocolWrapper`). Also includes the legacy v1 compatibility handler.
+- **Server** — The `ServiceServer` class and `createServiceServer` factory that wire everything together, plus the `getConfig` utility for reading `.config.json`.
+
+## Quick Start
+
+```typescript
+import { createServiceServer, defineService, OrmService } from "@simplysm/service-server";
+
+const GreetService = defineService("Greet", (ctx) => ({
+  hello: (name: string) => `Hello, ${name}!`,
+}));
+
+const server = createServiceServer({
+  rootPath: "./dist",
+  port: 3000,
+  auth: { jwtSecret: "my-secret" },
+  services: [GreetService, OrmService],
+});
+
+await server.listen();
+```
+
+## Exported Types
+
+| Type | Description |
+|---|---|
+| `ServiceServerOptions` | Options object for `ServiceServer` / `createServiceServer` |
+| `AuthTokenPayload<TAuthInfo>` | JWT payload with `roles` and typed `data` |
+| `ServiceContext<TAuthInfo>` | Context injected into every service factory |
+| `ServiceDefinition<TMethods>` | Return type of `defineService` |
+| `ServiceMethods<TDefinition>` | Extracts method map type from a `ServiceDefinition` |
+| `WebSocketHandler` | Manages all active WebSocket connections |
+| `ServiceSocket` | Represents a single active WebSocket connection |
+| `ProtocolWrapper` | Encode/decode service messages with optional worker offload |
+| `OrmServiceType` | Method map type for `OrmService` |
+| `AutoUpdateServiceType` | Method map type for `AutoUpdateService` |
+| `SmtpClientServiceType` | Method map type for `SmtpClientService` |
+
+## Detailed Documentation
+
+- [docs/auth.md](docs/auth.md) — `AuthTokenPayload`, `signJwt`, `verifyJwt`, `decodeJwt`
+- [docs/services.md](docs/services.md) — `defineService`, `auth`, `ServiceContext`, `runServiceMethod`, `OrmService`, `AutoUpdateService`, `SmtpClientService`
+- [docs/transport.md](docs/transport.md) — `WebSocketHandler`, `ServiceSocket`, `handleHttpRequest`, `handleUpload`, `handleStaticFile`, `ProtocolWrapper`, legacy handler
+- [docs/server.md](docs/server.md) — `ServiceServerOptions`, `ServiceServer`, `createServiceServer`, `getConfig`

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export * from "./transport/http/static-file-handler";
 export * from "./protocol/protocol-wrapper";
 export * from "./services/orm-service";
 export * from "./services/auto-update-service";
+export * from "./services/smtp-client-service";
 export * from "./utils/config-manager";
 export * from "./legacy/v1-auto-update-handler";
 export * from "./service-server";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["..\\src\\index.ts"],"names":[],"mappings":"AACA,cAAc,wBAAwB,CAAC;AAGvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oBAAoB,CAAC;AAGnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AAGxC,cAAc,sCAAsC,CAAC;AACrD,cAAc,mCAAmC,CAAC;AAGlD,cAAc,uCAAuC,CAAC;AACtD,cAAc,iCAAiC,CAAC;AAChD,cAAc,sCAAsC,CAAC;AAGrD,cAAc,6BAA6B,CAAC;AAG5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,gCAAgC,CAAC;AAG/C,cAAc,wBAAwB,CAAC;AAGvC,cAAc,iCAAiC,CAAC;AAGhD,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["..\\src\\index.ts"],"names":[],"mappings":"AACA,cAAc,wBAAwB,CAAC;AAGvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oBAAoB,CAAC;AAGnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AAGxC,cAAc,sCAAsC,CAAC;AACrD,cAAc,mCAAmC,CAAC;AAGlD,cAAc,uCAAuC,CAAC;AACtD,cAAc,iCAAiC,CAAC;AAChD,cAAc,sCAAsC,CAAC;AAGrD,cAAc,6BAA6B,CAAC;AAG5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,gCAAgC,CAAC;AAG/C,cAAc,wBAAwB,CAAC;AAGvC,cAAc,iCAAiC,CAAC;AAGhD,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -11,6 +11,7 @@ export * from "./transport/http/static-file-handler.js";
 export * from "./protocol/protocol-wrapper.js";
 export * from "./services/orm-service.js";
 export * from "./services/auto-update-service.js";
+export * from "./services/smtp-client-service.js";
 export * from "./utils/config-manager.js";
 export * from "./legacy/v1-auto-update-handler.js";
 export * from "./service-server.js";

package/dist/index.js.map

@@ -1,6 +1,6 @@
 {
   "version": 3,
   "sources": ["../src/index.ts"],
-  "mappings": "AACA,cAAc;AAGd,cAAc;AACd,cAAc;AAGd,cAAc;AACd,cAAc;AAGd,cAAc;AACd,cAAc;AAGd,cAAc;AACd,cAAc;AACd,cAAc;AAGd,cAAc;AAGd,cAAc;AACd,cAAc;AAGd,cAAc;AAGd,cAAc;AAGd,cAAc;",
+  "mappings": "AACA,cAAc;AAGd,cAAc;AACd,cAAc;AAGd,cAAc;AACd,cAAc;AAGd,cAAc;AACd,cAAc;AAGd,cAAc;AACd,cAAc;AACd,cAAc;AAGd,cAAc;AAGd,cAAc;AACd,cAAc;AACd,cAAc;AAGd,cAAc;AAGd,cAAc;AAGd,cAAc;",
   "names": []
 }

package/dist/services/smtp-client-service.d.ts

@@ -0,0 +1,8 @@
+import { type ServiceMethods } from "../core/define-service";
+import type { SmtpClientSendByDefaultOption, SmtpClientSendOption } from "@simplysm/service-common";
+export declare const SmtpClientService: import("..").ServiceDefinition<{
+    send(options: SmtpClientSendOption): Promise<string>;
+    sendByConfig(configName: string, options: SmtpClientSendByDefaultOption): Promise<string>;
+}>;
+export type SmtpClientServiceType = ServiceMethods<typeof SmtpClientService>;
+//# sourceMappingURL=smtp-client-service.d.ts.map

package/dist/services/smtp-client-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"smtp-client-service.d.ts","sourceRoot":"","sources":["..\\..\\src\\services\\smtp-client-service.ts"],"names":[],"mappings":"AACA,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC5E,OAAO,KAAK,EAEV,6BAA6B,EAC7B,oBAAoB,EACrB,MAAM,0BAA0B,CAAC;AAElC,eAAO,MAAM,iBAAiB;kBACR,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC;6BA6B3B,MAAM,WAAW,6BAA6B,GAAG,OAAO,CAAC,MAAM,CAAC;EAkB9F,CAAC;AAEJ,MAAM,MAAM,qBAAqB,GAAG,cAAc,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/services/smtp-client-service.js

@@ -0,0 +1,46 @@
+import nodemailer from "nodemailer";
+import { defineService } from "../core/define-service.js";
+const SmtpClientService = defineService("SmtpClient", (ctx) => ({
+  async send(options) {
+    return new Promise((resolve, reject) => {
+      const transport = nodemailer.createTransport({
+        host: options.host,
+        port: options.port,
+        secure: options.secure,
+        auth: options.user != null ? {
+          user: options.user,
+          pass: options.pass
+        } : void 0,
+        tls: {
+          rejectUnauthorized: false
+        }
+      });
+      transport.sendMail(options, (err, info) => {
+        if (err) {
+          reject(err);
+          return;
+        }
+        resolve(info.messageId);
+      });
+    });
+  },
+  async sendByConfig(configName, options) {
+    const config = (await ctx.getConfig("smtp"))[configName];
+    if (config == null) {
+      throw new Error(`SMTP config not found: ${configName}`);
+    }
+    return this.send({
+      user: config.user,
+      pass: config.pass,
+      host: config.host,
+      port: config.port,
+      secure: config.secure,
+      from: `"${config.senderName}" <${config.senderEmail ?? config.user}>`,
+      ...options
+    });
+  }
+}));
+export {
+  SmtpClientService
+};
+//# sourceMappingURL=smtp-client-service.js.map

package/dist/services/smtp-client-service.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../src/services/smtp-client-service.ts"],
+  "mappings": "AAAA,OAAO,gBAAgB;AACvB,SAAS,qBAA0C;AAO5C,MAAM,oBAAoB,cAAc,cAAc,CAAC,SAAS;AAAA,EACrE,MAAM,KAAK,SAAgD;AACzD,WAAO,IAAI,QAAgB,CAAC,SAAS,WAAW;AAC9C,YAAM,YAAY,WAAW,gBAAgB;AAAA,QAC3C,MAAM,QAAQ;AAAA,QACd,MAAM,QAAQ;AAAA,QACd,QAAQ,QAAQ;AAAA,QAChB,MACE,QAAQ,QAAQ,OACZ;AAAA,UACE,MAAM,QAAQ;AAAA,UACd,MAAM,QAAQ;AAAA,QAChB,IACA;AAAA,QACN,KAAK;AAAA,UACH,oBAAoB;AAAA,QACtB;AAAA,MACF,CAAC;AAED,gBAAU,SAAS,SAAuC,CAAC,KAAK,SAAS;AACvE,YAAI,KAAK;AACP,iBAAO,GAAG;AACV;AAAA,QACF;AAEA,gBAAQ,KAAK,SAAS;AAAA,MACxB,CAAC;AAAA,IACH,CAAC;AAAA,EACH;AAAA,EAEA,MAAM,aAAa,YAAoB,SAAyD;AAC9F,UAAM,UACJ,MAAM,IAAI,UAA+D,MAAM,GAC/E,UAAU;AACZ,QAAI,UAAU,MAAM;AAClB,YAAM,IAAI,MAAM,0BAA0B,UAAU,EAAE;AAAA,IACxD;AAEA,WAAO,KAAK,KAAK;AAAA,MACf,MAAM,OAAO;AAAA,MACb,MAAM,OAAO;AAAA,MACb,MAAM,OAAO;AAAA,MACb,MAAM,OAAO;AAAA,MACb,QAAQ,OAAO;AAAA,MACf,MAAM,IAAI,OAAO,UAAU,MAAM,OAAO,eAAe,OAAO,IAAI;AAAA,MAClE,GAAG;AAAA,IACL,CAAC;AAAA,EACH;AACF,EAAE;",
+  "names": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/service-server",
-  "version": "13.0.71",
+  "version": "13.0.74",
   "description": "Simplysm package - service module (server)",
   "author": "simplysm",
   "license": "Apache-2.0",
@@ -21,7 +21,7 @@
   "dependencies": {
     "@fastify/cors": "^11.2.0",
     "@fastify/helmet": "^13.0.2",
-    "@fastify/middie": "^9.1.0",
+    "@fastify/middie": "^9.2.0",
     "@fastify/multipart": "^9.4.0",
     "@fastify/reply-from": "^12.6.0",
     "@fastify/static": "^9.0.0",
@@ -31,16 +31,18 @@
     "fastify": "^5.7.4",
     "jose": "^6.1.3",
     "mime": "^4.1.0",
+    "nodemailer": "^8.0.1",
     "semver": "^7.7.4",
     "utf-8-validate": "^6.0.6",
     "ws": "^8.19.0",
-    "@simplysm/core-node": "13.0.71",
-    "@simplysm/core-common": "13.0.71",
-    "@simplysm/orm-common": "13.0.71",
-    "@simplysm/orm-node": "13.0.71",
-    "@simplysm/service-common": "13.0.71"
+    "@simplysm/core-common": "13.0.74",
+    "@simplysm/core-node": "13.0.74",
+    "@simplysm/orm-common": "13.0.74",
+    "@simplysm/orm-node": "13.0.74",
+    "@simplysm/service-common": "13.0.74"
   },
   "devDependencies": {
+    "@types/nodemailer": "^6.4.23",
     "@types/semver": "^7.7.1",
     "@types/ws": "^8.18.1"
   }

package/src/index.ts

@@ -24,6 +24,7 @@ export * from "./protocol/protocol-wrapper";
 // Services
 export * from "./services/orm-service";
 export * from "./services/auto-update-service";
+export * from "./services/smtp-client-service";
 
 // Utils
 export * from "./utils/config-manager";

package/src/services/smtp-client-service.ts

@@ -0,0 +1,59 @@
+import nodemailer from "nodemailer";
+import { defineService, type ServiceMethods } from "../core/define-service";
+import type {
+  SmtpClientDefaultConfig,
+  SmtpClientSendByDefaultOption,
+  SmtpClientSendOption,
+} from "@simplysm/service-common";
+
+export const SmtpClientService = defineService("SmtpClient", (ctx) => ({
+  async send(options: SmtpClientSendOption): Promise<string> {
+    return new Promise<string>((resolve, reject) => {
+      const transport = nodemailer.createTransport({
+        host: options.host,
+        port: options.port,
+        secure: options.secure,
+        auth:
+          options.user != null
+            ? {
+                user: options.user,
+                pass: options.pass,
+              }
+            : undefined,
+        tls: {
+          rejectUnauthorized: false,
+        },
+      });
+
+      transport.sendMail(options as nodemailer.SendMailOptions, (err, info) => {
+        if (err) {
+          reject(err);
+          return;
+        }
+
+        resolve(info.messageId);
+      });
+    });
+  },
+
+  async sendByConfig(configName: string, options: SmtpClientSendByDefaultOption): Promise<string> {
+    const config = (
+      await ctx.getConfig<Record<string, SmtpClientDefaultConfig | undefined>>("smtp")
+    )[configName];
+    if (config == null) {
+      throw new Error(`SMTP config not found: ${configName}`);
+    }
+
+    return this.send({
+      user: config.user,
+      pass: config.pass,
+      host: config.host,
+      port: config.port,
+      secure: config.secure,
+      from: `"${config.senderName}" <${config.senderEmail ?? config.user}>`,
+      ...options,
+    });
+  },
+}));
+
+export type SmtpClientServiceType = ServiceMethods<typeof SmtpClientService>;