@owlmeans/server-api 0.1.18-rc.43 → 0.1.18-rc.45

package/README.md

@@ -10,7 +10,7 @@ only when composing a context without that package. WebSocket routes belong to
 ## Installation
 
 ```bash
-bun add @owlmeans/server-api@^0.1.18-rc.43
+bun add @owlmeans/server-api@^0.1.18-rc.45
 ```
 
 ## Concepts
@@ -240,7 +240,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills@^0.1.18-rc.40
+npx @owlmeans/agent-skills@^0.1.18-rc.42
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/server-api",
-  "version": "0.1.18-rc.43",
-  "generatedAt": "2026-09-25T21:19:37.929Z",
+  "version": "0.1.18-rc.45",
+  "generatedAt": "2026-09-29T08:01:58.109Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/server-api/SKILL.md

@@ -7,7 +7,7 @@ user-invocable: false
 
 # @owlmeans/server-api
 
-**Install:** `bun add @owlmeans/server-api@^0.1.18-rc.43`
+**Install:** `bun add @owlmeans/server-api@^0.1.18-rc.45`
 
 Make handlers from the protocol declaration so input and output types stay coupled to the shared
 contract:
@@ -74,6 +74,9 @@ exposure) and a status from `errorStatus(error)` (`./utils`), resolved in this o
   that is understood and refused — and a missing configuration, a broken peer, a timeout or a bug
   stays 500, because monitoring, logs, proxies and retry logic read a 5xx as the server failing.
   The table and the leaf-class rule are the `error` skill's.
+- The storage refusals of `@owlmeans/resource` declare theirs: `UnknownRecordError` answers 404,
+  `RecordExists` 409, every other `ResourceError` 500 — so a handler that lets a `get()` miss
+  escape answers 404, and one reading a row the request did not address uses `load` instead.
 - Declare it on the class: `public static httpStatus = 409` (`override` only when an ancestor
   already declares one). The declaration is structural — the package declaring an error never
   imports `@owlmeans/server-api` — and a static property is inherited, so a subclass answers its

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/server-api",
-  "version": "0.1.18-rc.43",
+  "version": "0.1.18-rc.45",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -33,14 +33,14 @@
     "@fastify/helmet": "^13.1.0",
     "@fastify/middie": "^9.0.2",
     "@fastify/multipart": "^9.0.1",
-    "@owlmeans/api": "^0.1.18-rc.39",
+    "@owlmeans/api": "^0.1.18-rc.41",
     "@owlmeans/auth": "^0.1.18-rc.36",
-    "@owlmeans/auth-common": "^0.1.18-rc.39",
+    "@owlmeans/auth-common": "^0.1.18-rc.41",
     "@owlmeans/context": "^0.1.18-rc.32",
     "@owlmeans/error": "^0.1.18-rc.36",
     "@owlmeans/entrypoint": "^0.1.18-rc.37",
     "@owlmeans/route": "^0.1.18-rc.33",
-    "@owlmeans/server-context": "^0.1.18-rc.37",
+    "@owlmeans/server-context": "^0.1.18-rc.38",
     "@owlmeans/server-entrypoint": "^0.1.18-rc.36",
     "ajv-errors": "^3.0.0",
     "fastify": "^5.0.0",
@@ -53,6 +53,7 @@
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",
+    "@owlmeans/resource": "^0.1.18-rc.37",
     "@types/bun": "^1.4.0",
     "@types/node": "^26.1.0",
     "nodemon": "^3.1.14",

package/tests/error-status.spec.ts

@@ -7,7 +7,11 @@ import { provideResponse } from '@owlmeans/entrypoint'
 import { errorExposure, errorStatus, handleError, INCIDENT_ID_HEADER } from '../src/utils/error.js'
 import { executeResponse } from '../src/utils/payload.js'
 import { AccessError, AuthFailedError } from '../src/errors.js'
-import { DENIAL_KIND_HEADER, ACCESS_DENIED_KIND } from '@owlmeans/api'
+import { DENIAL_KIND_HEADER, ACCESS_DENIED_KIND, httpStatusOf } from '@owlmeans/api'
+import {
+  MigrationError, MisshapedRecord, RecordExists, RecordUpdateFailed, UnknownRecordError,
+  UnsupportedArgumentError, UnsupportedMethodError,
+} from '@owlmeans/resource'
 
 class OutOfCredit extends ResilientError {
   public static override typeName = 'ServerApiSpecOutOfCredit'
@@ -180,7 +184,7 @@ const answer = async (error: unknown, path: string = '/handle') => {
   return {
     status: reply.statusCode,
     body: reply.body,
-    incidentId: reply.headers[INCIDENT_ID_HEADER.toLowerCase()],
+    incidentId: reply.headers[INCIDENT_ID_HEADER.toLowerCase()] as string,
     retryAfter: reply.headers['retry-after'],
     denialKind: reply.headers[DENIAL_KIND_HEADER.toLowerCase()],
   }
@@ -294,3 +298,45 @@ describe('@owlmeans/server-api — auth status across a rebuild and duplicate mo
     expect((await answer(new ForeignEntitlementRefusal())).status).toBe(403)
   })
 })
+
+describe('@owlmeans/server-api — storage refusals of @owlmeans/resource', () => {
+  test('an absent record answers 404 and a taken id or key 409 — as thrown and after a marshal hop', async () => {
+    expect((await answer(new UnknownRecordError('shelf/3'))).status).toBe(404)
+    expect((await answer(new RecordExists('id-present'))).status).toBe(409)
+    expect((await answer(ResilientError.marshal(new UnknownRecordError('shelf/3')))).status).toBe(404)
+    expect((await answer(ResilientError.marshal(new RecordExists('isbn')))).status).toBe(409)
+    expect((await answer(new UnknownRecordError('shelf/3'), '/execute')).status).toBe(404)
+  })
+
+  test('a storage fault still answers 500', async () => {
+    for (const fault of [
+      new MisshapedRecord('x'), new RecordUpdateFailed('x'), new UnsupportedArgumentError('ttl'),
+      new UnsupportedMethodError('watch'), new MigrationError('x'),
+    ]) {
+      expect([fault.type, (await answer(fault)).status]).toEqual([fault.type, 500])
+    }
+  })
+
+  test('a development body rebuilds into the same class, and the status the client stamps agrees with it', async () => {
+    for (const [error, status] of [
+      [new UnknownRecordError('shelf/3'), 404], [new RecordExists('isbn'), 409],
+    ] as const) {
+      const response = await answer(error, '/handle-development')
+      expect(response.status).toBe(status)
+      // What `@owlmeans/api` does with a non-2xx body carrying the separator.
+      const rebuilt = Object.assign(ResilientError.ensure(response.body, true), { responseStatus: response.status })
+      expect(rebuilt.constructor).toBe(error.constructor)
+      expect(rebuilt.message).toBe(error.message)
+      expect(httpStatusOf(rebuilt)).toBe(status)
+    }
+    const rebuilt = ResilientError.ensure((await answer(new UnknownRecordError('shelf/3'), '/handle-development')).body, true)
+    expect((rebuilt as UnknownRecordError).id).toBe('shelf/3')
+  })
+
+  test('a production body is the incident id alone, under the declared status', async () => {
+    const response = await answer(new UnknownRecordError('shelf/3'))
+    expect(response.status).toBe(404)
+    expect(response.body).toBe(response.incidentId)
+    expect(response.body).not.toContain('shelf')
+  })
+})