@zeroxsolutions/server 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -1,3 +1,25 @@
+## 0.5.2 (2026-09-30)
+
+### 🚀 Features
+
+- **server:** answer a refused request document 409 or 403 ([3792166](https://github.com/zeroxsolutions/zeroxsolutions/commit/3792166))
+
+### ❤️ Thank You
+
+- Claude Opus 5.5 (1M context)
+- Lương Văn Tú
+
+## 0.5.1 (2026-09-29)
+
+### 🚀 Features
+
+- **server:** name accept in vary on every negotiated response ([9978fd6](https://github.com/zeroxsolutions/zeroxsolutions/commit/9978fd6))
+
+### ❤️ Thank You
+
+- Claude Opus 5.5 (1M context)
+- Lương Văn Tú
+
 ## 0.5.0 (2026-09-29)
 
 ### 🩹 Fixes

package/README.md

@@ -80,17 +80,24 @@ why `Content-Type` is read on a write only, and why an empty `Accept` is refused
 
 1. a query the permit-list refused (`QueryNotPermitted`), answered `400` as
    `<namespace>.query_not_permitted`, naming the parameter in `source.parameter`, before `resolve` sees it;
-2. `resolve(err, c)` - where a surface's domain error map answers, through
+2. a request document the route does not accept (`RequestConflict` / `RequestForbidden` from
+   `@zeroxsolutions/response`, which its `requestDocumentSchema` and `readRequestDocument` throw),
+   answered `409` as `<namespace>.request_conflict` or `403` as `<namespace>.request_forbidden`, naming the
+   member in `source.pointer`, before `resolve` sees it;
+3. `resolve(err, c)` - where a surface's domain error map answers, through
    `@zeroxsolutions/response`'s `createDomainErrorResolver`;
-3. a request the validation hook rejected, one error object per issue;
-4. a `JsonApiError`, rendered as it was thrown;
-5. otherwise the status alone - a hono `HTTPException` at its own, anything else as a 500.
+4. a request a guard refused - `Unauthenticated`, answered `401` as `<namespace>.unauthenticated`, or
+   `PermissionRefused`, answered `403` as `<namespace>.forbidden`;
+5. a request the validation hook rejected, one error object per issue;
+6. a `JsonApiError`, rendered as it was thrown;
+7. otherwise the status alone - a hono `HTTPException` at its own, anything else as a 500.
 
 Whichever step answers, the handler writes one `http.error.answered` line under `category` before the
 document goes out, at the level the answered status class decides: a 5xx at error, anything else at
 warn. The line carries the request id, the method, the path, the answered status, the step that claimed
-the failure (`resolve`, `validation`, `jsonapi`, `status`) and the error's type and message. Without it
-a mapped 500 or a guard's 403 reaches the client with nothing in the log for an operator to join it to.
+the failure (`query`, `request`, `resolve`, `auth`, `validation`, `jsonapi`, `status`) and the error's type
+and message. Without it a mapped 500 or a guard's 403 reaches the client with nothing in the log for an
+operator to join it to.
 
 The `requestId` option's value becomes the `id` of each error object that carries none, so a client
 quotes the id the request's log lines carry.

package/dist/content-negotiation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"content-negotiation.d.ts","sourceRoot":"","sources":["../src/content-negotiation.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAC9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,iBAAiB,GAAG;IAAE,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACvE,iBAAiB,CAWnB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAOxB,CAAC"}
+{"version":3,"file":"content-negotiation.d.ts","sourceRoot":"","sources":["../src/content-negotiation.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAC9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,iBAAiB,GAAG;IAAE,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACvE,iBAAiB,CAcnB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAOxB,CAAC"}

package/dist/content-negotiation.js

@@ -20,6 +20,9 @@ import { errorResponse, JSON_API_MEDIA_TYPE } from '@zeroxsolutions/response';
 export function jsonApiContentNegotiation(options) {
     const supported = new Set(options.supportedExtensions ?? []);
     return async (c, next) => {
+        // JSON:API v1.1: a server supporting the ext or profile parameters SHOULD name Accept in Vary. It is set
+        // before the decision so a refusal, which the error handler answers, carries it too.
+        c.header('Vary', 'Accept', { append: true });
         const error = negotiateJsonApi(c.req.header('Content-Type'), c.req.header('Accept'), options.namespace, supported);
         if (error)
             throw error;

package/dist/error-handler.d.ts

@@ -22,9 +22,10 @@ export interface ErrorHandlerOptions extends SurfaceVocabulary {
 }
 /**
  * The one central `onError` a transport installs, rendering every failure as one `application/vnd.api+json`
- * `errors[]` document. It asks, in order: a query the permit-list refused, then `resolve`, then a guard's own
- * refusal, then a request the validation hook rejected, then a {@link JsonApiError} as thrown, then the HTTP
- * status alone.
+ * `errors[]` document. It asks, in order: a query the permit-list refused, then a request document the route does not
+ * accept (`RequestConflict` as 409, `RequestForbidden` as 403, each naming its member in `source.pointer`), then
+ * `resolve`, then a guard's own refusal, then a request the validation hook rejected, then a {@link JsonApiError} as
+ * thrown, then the HTTP status alone.
  *
  * Every answer is written to the log before it goes out, at the level its status class decides: a 5xx at error,
  * because this side went wrong, anything else at warn, because the request was refused. Without the line, a

package/dist/error-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../src/error-handler.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,MAAM,CAAC;AAIlD,OAAO,EAML,KAAK,WAAW,EAChB,KAAK,aAAa,EACnB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AA4BjE,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,WAAW,CAS9F;AAED,iGAAiG;AACjG,MAAM,WAAW,mBAAoB,SAAQ,iBAAiB;IAC5D;;;;OAIG;IACH,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,uGAAuG;IACvG,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,KAAK,aAAa,GAAG,SAAS,CAAC;IAChE,0GAA0G;IAC1G,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;IACtD;;;OAGG;IACH,uBAAuB,EAAE,MAAM,CAAC;CACjC;AAyDD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAkC7E"}
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../src/error-handler.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,MAAM,CAAC;AAIlD,OAAO,EAQL,KAAK,WAAW,EAChB,KAAK,aAAa,EACnB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AA4BjE,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,WAAW,CAS9F;AAED,iGAAiG;AACjG,MAAM,WAAW,mBAAoB,SAAQ,iBAAiB;IAC5D;;;;OAIG;IACH,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,uGAAuG;IACvG,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,KAAK,aAAa,GAAG,SAAS,CAAC;IAChE,0GAA0G;IAC1G,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;IACtD;;;OAGG;IACH,uBAAuB,EAAE,MAAM,CAAC;CACjC;AAsED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAkC7E"}

package/dist/error-handler.js

@@ -1,7 +1,7 @@
 import { getLogger } from '@logtape/logtape';
 import { HTTPException } from 'hono/http-exception';
 import { QueryNotPermitted } from '@zeroxsolutions/query';
-import { BASE_ERROR_CODES, JsonApiError, JSON_API_MEDIA_TYPE, toErrorDocument, toErrorObject, } from '@zeroxsolutions/response';
+import { BASE_ERROR_CODES, JsonApiError, JSON_API_MEDIA_TYPE, RequestConflict, RequestForbidden, toErrorDocument, toErrorObject, } from '@zeroxsolutions/response';
 import { PermissionRefused } from './permission-refused.js';
 import { RequestInvalid } from './request-invalid.js';
 import { Unauthenticated } from './unauthenticated.js';
@@ -25,8 +25,9 @@ export function errorObjectByStatus(err, status, namespace) {
         ...(detail && detail !== meta.title ? { detail } : {}),
     };
 }
-// Asks each step of the dispatch in turn: a query the permit-list refused, `resolve`, a guard's refusal, a request
-// the validation hook rejected, a `JsonApiError` as thrown, the HTTP status alone.
+// Asks each step of the dispatch in turn: a query the permit-list refused, a request document the route does not
+// accept, `resolve`, a guard's refusal, a request the validation hook rejected, a `JsonApiError` as thrown, the HTTP
+// status alone.
 function claimError(err, c, options) {
     if (err instanceof QueryNotPermitted) {
         const error = {
@@ -38,6 +39,18 @@ function claimError(err, c, options) {
         };
         return { claimedBy: 'query', resolved: { status: 400, errors: [error] } };
     }
+    if (err instanceof RequestConflict || err instanceof RequestForbidden) {
+        const conflict = err instanceof RequestConflict;
+        const { status, title } = conflict ? BASE_ERROR_CODES.CONFLICT : BASE_ERROR_CODES.FORBIDDEN;
+        const error = {
+            status: String(status),
+            code: `${options.namespace}.${conflict ? 'request_conflict' : 'request_forbidden'}`,
+            title,
+            detail: err.message,
+            source: { pointer: err.pointer },
+        };
+        return { claimedBy: 'request', resolved: { status, errors: [error] } };
+    }
     const resolved = options.resolve?.(err, c);
     if (resolved) {
         return { claimedBy: 'resolve', resolved };
@@ -81,9 +94,10 @@ function withChallenge(claimed, authenticationChallenge) {
 }
 /**
  * The one central `onError` a transport installs, rendering every failure as one `application/vnd.api+json`
- * `errors[]` document. It asks, in order: a query the permit-list refused, then `resolve`, then a guard's own
- * refusal, then a request the validation hook rejected, then a {@link JsonApiError} as thrown, then the HTTP
- * status alone.
+ * `errors[]` document. It asks, in order: a query the permit-list refused, then a request document the route does not
+ * accept (`RequestConflict` as 409, `RequestForbidden` as 403, each naming its member in `source.pointer`), then
+ * `resolve`, then a guard's own refusal, then a request the validation hook rejected, then a {@link JsonApiError} as
+ * thrown, then the HTTP status alone.
  *
  * Every answer is written to the log before it goes out, at the level its status class decides: a 5xx at error,
  * because this side went wrong, anything else at warn, because the request was refused. Without the line, a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeroxsolutions/server",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "private": false,
   "type": "module",
   "sideEffects": false,
@@ -21,8 +21,8 @@
   },
   "dependencies": {
     "tslib": "^2.3.0",
-    "@zeroxsolutions/jsonapi": "0.13.0",
-    "@zeroxsolutions/response": "0.14.2",
+    "@zeroxsolutions/jsonapi": "0.13.1",
+    "@zeroxsolutions/response": "0.14.3",
     "@zeroxsolutions/query": "0.7.1"
   },
   "peerDependencies": {
@@ -35,7 +35,7 @@
     "@hono/zod-openapi": "^1.4.0",
     "@logtape/logtape": "^2.3.2",
     "hono": "^4.12.27",
-    "zod": "^4.4.3"
+    "zod": "^4.3.6"
   },
   "nx": {
     "name": "@zeroxsolutions/server"