feat: add API key, documentType alias, and error handling

Author: hackycy

lib/EasyInk.Net/EasyInk.Engine/src/Models/UserDataParams.cs

@@ -1,4 +1,6 @@
-namespace EasyInk.Engine.Models;
+using Newtonsoft.Json;
+
+namespace EasyInk.Engine.Models;
 
 /// <summary>
 /// 用户数据参数
@@ -8,10 +10,25 @@ public class UserDataParams
     /// <summary>
     /// 用户ID
     /// </summary>
-    public string UserId { get; set; } = default!;
+    public string? UserId { get; set; }
 
     /// <summary>
     /// 标签类型
     /// </summary>
-    public string LabelType { get; set; } = default!;
+    public string? LabelType { get; set; }
+
+    /// <summary>
+    /// 文档类型。兼容前端 SDK 使用的 documentType 字段，内部仍映射到审计日志的 LabelType。
+    /// </summary>
+    [JsonProperty("documentType")]
+    public string? DocumentType
+    {
+        get => LabelType;
+        set => LabelType = value;
+    }
+
+    public bool ShouldSerializeDocumentType()
+    {
+        return false;
+    }
 }

lib/EasyInk.Net/EasyInk.Engine/tests/ModelTests.cs

@@ -1,4 +1,7 @@
-using EasyInk.Engine.Models;
+using EasyInk.Engine;
+using EasyInk.Engine.Models;
+using Newtonsoft.Json;
+using Newtonsoft.Json.Linq;
 using Xunit;
 
 namespace EasyInk.Engine.Tests;
@@ -96,3 +99,44 @@ public void Error_SetsErrorInfo()
         Assert.Equal("details", result.ErrorInfo!.Details);
     }
 }
+
+public class UserDataParamsTests
+{
+    [Fact]
+    public void Deserialize_DocumentType_MapsToLabelType()
+    {
+        var userData = JsonConvert.DeserializeObject<UserDataParams>(
+            @"{""userId"":""demo-user"",""documentType"":""receipt""}",
+            JsonConfig.CamelCase);
+
+        Assert.Equal("demo-user", userData!.UserId);
+        Assert.Equal("receipt", userData.LabelType);
+        Assert.Equal("receipt", userData.DocumentType);
+    }
+
+    [Fact]
+    public void Deserialize_LabelType_RemainsSupported()
+    {
+        var userData = JsonConvert.DeserializeObject<UserDataParams>(
+            @"{""userId"":""demo-user"",""labelType"":""shipping""}",
+            JsonConfig.CamelCase);
+
+        Assert.Equal("shipping", userData!.LabelType);
+        Assert.Equal("shipping", userData.DocumentType);
+    }
+
+    [Fact]
+    public void Serialize_OmitsDocumentTypeAlias()
+    {
+        var json = JsonConvert.SerializeObject(new UserDataParams
+        {
+            UserId = "demo-user",
+            LabelType = "receipt"
+        }, JsonConfig.CamelCase);
+        var token = JObject.Parse(json);
+
+        Assert.Equal("demo-user", token["userId"]!.ToString());
+        Assert.Equal("receipt", token["labelType"]!.ToString());
+        Assert.Null(token["documentType"]);
+    }
+}

lib/EasyInk.Net/EasyInk.Printer/src/Server/WebSocketHandler.cs

@@ -23,6 +23,7 @@ public class WebSocketHandler : IDisposable
     private readonly SemaphoreSlim _broadcastLock = new SemaphoreSlim(1, 1);
     private readonly CancellationTokenSource _cts = new CancellationTokenSource();
     private readonly int _maxConnections;
+    private readonly string? _apiKey;
     private readonly Task _pingTask;
     private bool _disposed;
     private WebSocketCommandHandler? _commandHandler;
@@ -31,9 +32,10 @@ public class WebSocketHandler : IDisposable
 
     public event Action? ConnectionCountChanged;
 
-    public WebSocketHandler(int maxConnections = 100)
+    public WebSocketHandler(int maxConnections = 100, string? apiKey = null)
     {
         _maxConnections = maxConnections < 10 ? 10 : maxConnections;
+        _apiKey = apiKey;
         _pingTask = PingLoop();
     }
 
@@ -103,14 +105,15 @@ public async Task HandleConnection(HttpListenerContext context)
             return;
         }
 
+        if (!ValidateApiKey(context.Request))
+        {
+            await WriteJsonError(context.Response, 401, ErrorCode.Unauthorized, LangManager.Get("Api_InvalidApiKey"));
+            return;
+        }
+
         if (_connections.Count >= _maxConnections)
         {
-            context.Response.StatusCode = 429;
-            var bytes = Encoding.UTF8.GetBytes("{\"success\":false,\"errorInfo\":{\"code\":\"TooManyConnections\",\"message\":\"" + LangManager.Get("Ws_ConnectionLimit") + "\"}}");
-            context.Response.ContentType = "application/json";
-            context.Response.ContentLength64 = bytes.Length;
-            await context.Response.OutputStream.WriteAsync(bytes, 0, bytes.Length);
-            context.Response.Close();
+            await WriteJsonError(context.Response, 429, "TooManyConnections", LangManager.Get("Ws_ConnectionLimit"));
             return;
         }
 
@@ -215,6 +218,32 @@ private static async Task SendErrorQuietly(WebSocket ws, string code, string err
         }
     }
 
+    private bool ValidateApiKey(HttpListenerRequest request)
+    {
+        return ValidateApiKeyCore(_apiKey, request.QueryString["apiKey"], request.Headers["X-API-Key"]);
+    }
+
+    internal static bool ValidateApiKeyCore(string? configuredKey, string? queryApiKey, string? headerApiKey)
+    {
+        return Router.ValidateApiKeyCore(configuredKey, queryApiKey)
+            || Router.ValidateApiKeyCore(configuredKey, headerApiKey);
+    }
+
+    private static async Task WriteJsonError(HttpListenerResponse response, int statusCode, string code, string message)
+    {
+        var json = JsonConvert.SerializeObject(new
+        {
+            success = false,
+            errorInfo = new { code, message }
+        });
+        var bytes = Encoding.UTF8.GetBytes(json);
+        response.StatusCode = statusCode;
+        response.ContentType = "application/json";
+        response.ContentLength64 = bytes.Length;
+        await response.OutputStream.WriteAsync(bytes, 0, bytes.Length);
+        response.Close();
+    }
+
     public async Task Broadcast(string message)
     {
         var bytes = Encoding.UTF8.GetBytes(message);

lib/EasyInk.Net/EasyInk.Printer/src/ServiceConfig.cs

@@ -55,7 +55,7 @@ public static ServiceProvider Configure(HostConfig config)
         services.AddSingleton<HttpServer>(sp =>
             new HttpServer(config.HttpPort, config.MaxConcurrentRequests));
         services.AddSingleton<WebSocketHandler>(sp =>
-            new WebSocketHandler(config.MaxWebSocketConnections));
+            new WebSocketHandler(config.MaxWebSocketConnections, config.ApiKey));
         services.AddSingleton<WebSocketCommandHandler>();
         services.AddSingleton<Router>();
 

lib/EasyInk.Net/EasyInk.Printer/tests/WebSocketHandlerTests.cs

@@ -26,6 +26,18 @@ public void ConnectionCountChanged_EventCanBeSubscribed()
         Assert.False(fired);
     }
 
+    [Theory]
+    [InlineData(null, null, null, true)]
+    [InlineData("secret", "secret", null, true)]
+    [InlineData("secret", null, "secret", true)]
+    [InlineData("secret", "wrong", "secret", true)]
+    [InlineData("secret", "wrong", null, false)]
+    [InlineData("secret", null, null, false)]
+    public void ValidateApiKeyCore_AcceptsQueryOrHeaderKey(string? configuredKey, string? queryKey, string? headerKey, bool expected)
+    {
+        Assert.Equal(expected, WebSocketHandler.ValidateApiKeyCore(configuredKey, queryKey, headerKey));
+    }
+
     [Theory]
     [InlineData(64)]
     [InlineData(995)]

packages/print/integration-easyink-printer/src/client.test.ts

@@ -112,6 +112,29 @@ describe('easy ink printer client', () => {
     await assertion
   })
 
+  it('rejects printer list service errors instead of treating them as an empty list', async () => {
+    Object.defineProperty(globalThis, 'fetch', {
+      configurable: true,
+      value: vi.fn(async () => new Response(JSON.stringify({
+        success: false,
+        errorInfo: {
+          code: 'INTERNAL_ERROR',
+          message: 'printer backend failed',
+        },
+      }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      })),
+    })
+    const client = new EasyInkPrinterClient()
+
+    await expect(client.refreshPrinters()).rejects.toMatchObject({
+      code: 'INTERNAL_ERROR',
+      message: 'printer backend failed',
+    })
+    expect(client.devices).toEqual([])
+  })
+
   it('rejects immediately when WebSocket send fails', async () => {
     const client = new EasyInkPrinterClient({ responseTimeoutMs: 1000 })
     const socket = await connectClient(client)

packages/print/integration-easyink-printer/src/client.ts

@@ -216,6 +216,12 @@ interface PrinterResultMessage {
   errorInfo?: { code?: string, message?: string, details?: string }
 }
 
+interface PrinterHttpResult {
+  success?: boolean
+  data?: unknown
+  errorInfo?: { code?: string, message?: string, details?: string }
+}
+
 export class EasyInkPrinterClient {
   serviceUrl: string
   apiKey?: string
@@ -378,8 +384,8 @@ export class EasyInkPrinterClient {
       if (!response.ok)
         throw new EasyInkPrintError(`获取打印机列表失败: HTTP ${response.status}`, 'PRINTER_LIST_FAILED')
 
-      const payload = await response.json() as { data?: unknown }
-      const devices = normalizePrinterDevices(payload.data ?? payload)
+      const payload = await response.json() as PrinterHttpResult
+      const devices = normalizePrinterDevices(unwrapPrinterResultData(payload))
       this.devices = devices
       this.ensureSelectedPrinter(devices)
       return devices
@@ -883,6 +889,22 @@ function normalizePrinterDevices(data: unknown): EasyInkPrinterDevice[] {
     .filter(device => device.name.length > 0) as EasyInkPrinterDevice[]
 }
 
+function unwrapPrinterResultData(payload: unknown): unknown {
+  if (!isRecord(payload))
+    return payload
+
+  if (payload.success === false) {
+    const errorInfo = isRecord(payload.errorInfo) ? payload.errorInfo : undefined
+    throw new EasyInkPrintError(
+      toOptionalString(errorInfo?.message) ?? '打印服务请求失败',
+      toOptionalString(errorInfo?.code) ?? 'PRINTER_REQUEST_FAILED',
+      errorInfo,
+    )
+  }
+
+  return 'data' in payload ? payload.data : payload
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null
 }