@contractspec/lib.contracts-runtime-server-rest 3.0.0 → 3.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chaman Ventures, SASU
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,166 @@
 # @contractspec/lib.contracts-runtime-server-rest
 
-Split package for REST server adapters.
+REST runtime adapters for exposing ContractSpec operations over HTTP.
+
+Website: https://contractspec.io/
+
+## Why this package exists
+
+This package is the REST adapter layer extracted from `@contractspec/lib.contracts`.
+
+It lets you take an `OperationSpecRegistry` and expose it in multiple server environments with consistent behavior:
+
+- framework-agnostic fetch handler
+- Express adapter
+- Elysia adapter
+- Next.js App Router adapter
+- Next.js Pages Router adapter
+
+## Package boundary (important)
+
+Use this package for:
+
+- HTTP transport projection of operation specs.
+- Shared REST concerns (route derivation, input parsing, CORS, error mapping).
+- Helper utilities reused by GraphQL runtime (`contracts-adapter-input`, `contracts-adapter-hydration`).
+
+Do not use this package for:
+
+- Defining operation contracts (use `@contractspec/lib.contracts-spec`).
+- Building GraphQL schema (use `@contractspec/lib.contracts-runtime-server-graphql`).
+
+## Installation
+
+```bash
+npm install @contractspec/lib.contracts-runtime-server-rest @contractspec/lib.contracts-spec
+# or
+bun add @contractspec/lib.contracts-runtime-server-rest @contractspec/lib.contracts-spec
+```
+
+Install whichever peer framework you use (`express`, `elysia`, `next`).
+
+## Export map
+
+- Generic handler:
+  - `createFetchHandler`
+  - `RestOptions`
+- Framework adapters:
+  - `expressRouter`
+  - `elysiaPlugin`
+  - `makeNextAppHandler`
+  - `makeNextPagesHandler`
+- Shared adapter internals:
+  - `createInputTypeBuilder`
+  - `hydrateResourceIfNeeded`
+  - `parseReturns`
+
+## Quick start (framework-agnostic)
+
+```ts
+import { createFetchHandler } from "@contractspec/lib.contracts-runtime-server-rest";
+import type { HandlerCtx } from "@contractspec/lib.contracts-spec";
+import type { OperationSpecRegistry } from "@contractspec/lib.contracts-spec/operations/registry";
+
+declare const operations: OperationSpecRegistry;
+
+const handler = createFetchHandler(
+  operations,
+  (request): HandlerCtx => ({
+    actor: "user",
+    channel: "web",
+    traceId: request.headers.get("x-trace-id") ?? undefined,
+  }),
+  {
+    basePath: "/api/contracts",
+    cors: true,
+    prettyJson: 2,
+  }
+);
+
+const response = await handler(
+  new Request("https://example.com/api/contracts/workspace/get/v1.0.0")
+);
+console.log(response.status);
+```
+
+## Framework examples
+
+### Express
+
+```ts
+import express from "express";
+import { expressRouter } from "@contractspec/lib.contracts-runtime-server-rest/rest-express";
+
+declare const operations: import("@contractspec/lib.contracts-spec/operations/registry").OperationSpecRegistry;
+
+const app = express();
+app.use(express.json());
+
+app.use(
+  expressRouter(
+    express,
+    operations,
+    () => ({ actor: "user", channel: "web" }),
+    { basePath: "/api/contracts", cors: true }
+  )
+);
+```
+
+### Next.js App Router
+
+```ts
+import { makeNextAppHandler } from "@contractspec/lib.contracts-runtime-server-rest/rest-next-app";
+
+declare const operations: import("@contractspec/lib.contracts-spec/operations/registry").OperationSpecRegistry;
+
+const handler = makeNextAppHandler(
+  operations,
+  () => ({ actor: "user", channel: "web" }),
+  { basePath: "/api/contracts" }
+);
+
+export const GET = handler;
+export const POST = handler;
+export const OPTIONS = handler;
+```
+
+## Runtime behavior details
+
+- Default method mapping:
+  - query -> `GET`
+  - command -> `POST`
+- Default path mapping:
+  - `/<operation.key with dots replaced by slashes>/v<version>`
+- GET input parsing:
+  - if `input` query param exists, parse it as JSON
+  - otherwise use query params as flat object
+- POST input parsing:
+  - supports `application/json` and `application/x-www-form-urlencoded`
+- Error mapping defaults:
+  - validation errors -> `400`
+  - `PolicyDenied*` errors -> `403`
+  - unknown errors -> `500`
+  - unsupported content type -> `415`
+
+You can override error serialization using `RestOptions.onError`.
+
+## AI assistant guidance
+
+When generating code:
+
+- Define operation specs first in `@contractspec/lib.contracts-spec`.
+- Start with `createFetchHandler` for deterministic behavior, then choose framework wrappers.
+- Keep `basePath` explicit to avoid route ambiguity in generated handlers.
+
+When debugging:
+
+- If a route is 404, verify operation key/version and derived path.
+- If input parsing fails on GET, check whether caller sends `input=` JSON vs plain query params.
+
+## Split migration from deprecated monolith
+
+- `@contractspec/lib.contracts/server/rest-generic` -> `@contractspec/lib.contracts-runtime-server-rest/rest-generic`
+- `@contractspec/lib.contracts/server/rest-express` -> `@contractspec/lib.contracts-runtime-server-rest/rest-express`
+- `@contractspec/lib.contracts/server/rest-elysia` -> `@contractspec/lib.contracts-runtime-server-rest/rest-elysia`
+- `@contractspec/lib.contracts/server/rest-next-app` -> `@contractspec/lib.contracts-runtime-server-rest/rest-next-app`
+- `@contractspec/lib.contracts/server/rest-next-pages` -> `@contractspec/lib.contracts-runtime-server-rest/rest-next-pages`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/lib.contracts-runtime-server-rest",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "description": "REST server runtime adapters for ContractSpec contracts",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -19,19 +19,19 @@
     "dev": "contractspec-bun-build dev"
   },
   "dependencies": {
-    "@contractspec/lib.contracts-spec": "3.0.0",
-    "@contractspec/lib.schema": "3.0.0"
+    "@contractspec/lib.contracts-spec": "3.2.0",
+    "@contractspec/lib.schema": "3.2.0"
   },
   "peerDependencies": {
     "@pothos/core": "^4.9.1",
-    "elysia": "^1.4.26",
+    "elysia": "^1.4.27",
     "express": "^5.2.1",
     "next": "16.1.6"
   },
   "devDependencies": {
-    "@contractspec/tool.typescript": "3.0.0",
+    "@contractspec/tool.typescript": "3.2.0",
     "typescript": "^5.9.3",
-    "@contractspec/tool.bun": "3.0.0"
+    "@contractspec/tool.bun": "3.2.0"
   },
   "files": [
     "dist",