@xfcfam/xf-server-http 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Israel Sanjurjo and the XF contributors
+
+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

@@ -0,0 +1,240 @@
+# `@xfcfam/xf-server-http`
+
+HTTP transport for the **XF Architecture Model** — the [Fastify](https://fastify.dev)
+implementation of the transport-agnostic
+[`@xfcfam/xf-server`](../xf-server) contract. One server, one port,
+four entry-point shapes: **REST**, **WebSocket**, **SSE**, and **GraphQL**.
+
+The package spans two layers, by design:
+
+- **`HttpServerBusiness`** (Business Layer) owns the transport lifecycle
+  (Fastify) and the route registry. Starting a server is infrastructure,
+  not a protocol detail — in XF that belongs to the Business Layer. It
+  lives on `B` (e.g. `B.server`).
+- **`RestService` / `ObjectRestService` / `WebSocketService` /
+  `GraphQLService`** (Interaction Layer) are the entry points. Each
+  registers itself on `B.server` from its own `init()` (the push model).
+
+Sister of `@xfcfam/xf-rest` (outbound HTTP — your app calling someone):
+`xf-server-http` is **inbound HTTP** — someone calling your app.
+
+## Install
+
+```bash
+pnpm add @xfcfam/xf @xfcfam/xf-server @xfcfam/xf-server-http
+```
+
+Fastify, `@fastify/multipart`, `@fastify/websocket`, `mercurius` and the
+rest are bundled as direct dependencies and **lazy-loaded** — you pay for
+multipart / WebSocket / GraphQL only if you use them. The consumer never
+installs or imports the underlying engines.
+
+## What ships here
+
+| Component | Layer · type | Purpose |
+| --- | --- | --- |
+| `HttpServerBusiness` | Business · Generalization | Server orchestrator. Owns the Fastify lifecycle + route registry. Routes pushed via `B.server.get/post/…`, `B.server.ws(...)`, `B.server.graphql(...)`. Start-point calls `listen()` / `close()`. |
+| `RestService` | Interaction · Generalization | Raw-body endpoints (streams / bytes). `wrap(handler)` for the per-service pipeline. |
+| `ObjectRestService` | Interaction · Generalization | Auto parse / serialise by `Content-Type` via `object(handler)`. JSON built-in; XML/CSV/YAML pluggable; developer-chosen date handling (`reviveDates`, `formatDate`). |
+| `WebSocketService` | Interaction · Generalization | Bidirectional channels. Registers connection handlers via `B.server.ws(path, …)`. |
+| `GraphQLService` | Interaction · Generalization | GraphQL endpoint (Mercurius). Supplies schema + resolvers via `B.server.graphql(...)`. |
+| `SseUtils` | Interaction · Utility | Build a `text/event-stream` response from an async event source. |
+| `HttpRequest`, `HttpResponse`, `HttpAddress`, `HttpHandler`, `MultipartPart`, `WebSocketConnection`, `GraphQLConfig` | Business · Transfer | The data crossing the wire. |
+| `HttpException` + 5 typed subclasses | Business · Transfer | Throw inside a handler; the server maps it to the right HTTP status. |
+| `HttpStatusUtils`, `SchemaValidatorUtils`, `FileResponseUtils`, `ResponseUtils` | Interaction · Utility | Status constants, duck-typed validation, file/stream helpers, body-shape classifiers. |
+
+## Quick start (object REST)
+
+```typescript
+import {
+  ObjectRestService, HttpStatusUtils, NotFoundException, BadRequestException,
+  type HttpRequest, type HttpResponse,
+} from '@xfcfam/xf-server-http'
+import { B } from '../../../business/B.js'
+
+export class UsersRestService extends ObjectRestService {
+  override async init(): Promise<void> {
+    B.server.get('/users',      this.object(this.list))
+    B.server.get('/users/:id',  this.object(this.getOne))
+    B.server.post('/users',     this.object(this.create))
+    B.server.del('/users/:id',  this.object(this.remove))
+  }
+
+  private async getOne(req: HttpRequest): Promise<HttpResponse> {
+    const user = await B.user.findById(req.params['id']!)
+    if (user === null) throw new NotFoundException(`User ${req.params['id']}`)
+    return { status: HttpStatusUtils.OK, body: user }
+  }
+  // create / list / remove …
+}
+```
+
+Route helpers on `B.server`: `get`, `post`, `put`, `patch`, `del`, and
+`call(method, path, handler)` for any other verb.
+
+## Server orchestration
+
+The server is a **Business** component (`HttpServerBusiness`) declared on
+`B`. Concrete subclasses set the port and override the global hooks:
+
+```typescript
+import { HttpServerBusiness, ResponseUtils, type HttpRequest, type HttpResponse } from '@xfcfam/xf-server-http'
+
+export class AppServerBusiness extends HttpServerBusiness {
+  constructor() { super({ port: Number.parseInt(process.env['PORT'] ?? '3000', 10) }) }
+
+  override async onRequest(req: HttpRequest): Promise<HttpRequest> {
+    console.log(`${req.method} ${req.path}`); return req
+  }
+  override async onResponse(_req: HttpRequest, res: HttpResponse): Promise<HttpResponse> {
+    if (!ResponseUtils.isObject(res.body)) return res          // streams/files pass through
+    return { ...res, body: { code: '0', description: 'OK', data: res.body } }
+  }
+}
+```
+
+### Lifecycle and initialisation order
+
+`HttpServerBusiness.init()` is a **no-op** — it does not start listening.
+Services register their routes during `A.init()` (after `B.init()`); the
+start-point opens the socket **explicitly** once every route is in:
+
+```typescript
+// main.ts — start-point
+await XF.init()           // R → B → A; services push routes on B.server
+await B.server.listen()   // start Fastify after all routes are in
+// …on shutdown:
+await B.server.close()    // drain in-flight requests
+await XF.terminate()      // A → B → R
+```
+
+Pushing a route after `listen()` raises an error (Fastify freezes its
+routing table once listening) — hence the **push-then-start** ordering.
+
+## WebSocket
+
+A bidirectional channel on the same Fastify instance and port. Extend
+`WebSocketService` and register a connection handler:
+
+```typescript
+import { WebSocketService, type WebSocketConnection } from '@xfcfam/xf-server-http'
+import { B } from '../../../business/B.js'
+
+export class ChatService extends WebSocketService {
+  override async init(): Promise<void> {
+    B.server.ws('/chat', this.accept(this.onConnection))
+  }
+  private onConnection(conn: WebSocketConnection): void {
+    conn.send('welcome')
+    conn.onMessage((data) => conn.send(`echo: ${String(data)}`))
+    conn.onClose(() => {})
+  }
+}
+```
+
+## Server-Sent Events
+
+SSE is plain HTTP (a long-lived `GET` whose body is a stream), so it is
+just a `RestService` route — no plugin. `SseUtils` formats the events:
+
+```typescript
+import { RestService, SseUtils, type HttpResponse, type ServerSentEvent } from '@xfcfam/xf-server-http'
+
+export class ClockService extends RestService {
+  override async init() { B.server.get('/clock', this.wrap(this.clock)) }
+  private async clock(): Promise<HttpResponse> {
+    async function* ticks(): AsyncGenerator<ServerSentEvent> {
+      for (let n = 0; ; n++) {
+        yield { event: 'tick', id: String(n), data: { n, at: new Date().toISOString() } }
+        await new Promise((r) => setTimeout(r, 1000))
+      }
+    }
+    return SseUtils.stream(ticks())
+  }
+}
+```
+
+## GraphQL
+
+A GraphQL API (Mercurius) on the shared instance at `/graphql`. Supply
+schema + resolvers; the resolvers delegate to Business like REST handlers:
+
+```typescript
+import { GraphQLService, type GraphQLConfig } from '@xfcfam/xf-server-http'
+import { B } from '../../../business/B.js'
+
+export class ApiGraphQLService extends GraphQLService {
+  override async init() { B.server.graphql(this.config()) }
+  protected override config(): GraphQLConfig {
+    return {
+      schema: `type User { id: ID!  name: String! }  type Query { users: [User!]! }`,
+      resolvers: { Query: { users: () => B.user.list() } },
+      graphiql: true,
+    }
+  }
+}
+```
+
+## Date handling (object REST)
+
+`ObjectRestService` lets the developer decide how dates cross the wire,
+both directions, with no extra dependency.
+
+- **Serialising** — a `Date` becomes ISO-8601 by default. Pass
+  `formatDate` to choose any format; applied to every `Date` in the body
+  (nested objects and arrays included):
+  ```typescript
+  super({ formatDate: (d) => d.toISOString().slice(0, 10) })  // YYYY-MM-DD
+  ```
+- **Parsing** — set `reviveDates: true` so the JSON parser turns ISO date
+  strings back into real `Date` objects. The reviver is also exposed:
+  `JSON.parse(text, ObjectRestService.dateReviver)`.
+
+## Multipart uploads (opt-in)
+
+Enable on the server with one option — nothing else to install:
+
+```typescript
+super({ port: 3000, multipart: { maxFileSize: 10 * 1024 * 1024, maxFiles: 5 } })
+```
+
+Handlers then see `req.body` as `MultipartPart[]`. The parser is
+lazy-loaded at `listen()` time (only paid for if you opt in).
+
+## Pipeline order
+
+Per request, top to bottom:
+
+1. **`HttpServerBusiness.onRequest`** — global pre-processing.
+2. **`ObjectRestService` parse** — `object(handler)` auto-parses the body.
+3. **`RestService.onRequest`** — per-service pre-processing.
+4. **The matched route handler**.
+5. **`RestService.onResponse`** — per-service post-processing (semantic body).
+6. **`HttpServerBusiness.onResponse`** — global post-processing (envelopes).
+7. **`ObjectRestService` serialise** — object → bytes, last, honouring `formatDate`.
+
+`onResponse` runs **before** serialisation so envelope policies inspect
+the original payload, not an already-encoded `Uint8Array`. `ResponseUtils`
+exposes four disjoint body classifiers — `isStream`, `isBinary`,
+`isTextual`, `isObject` — for "object responses only" policies.
+
+### Error chain
+
+When step 3–5 throws: `RestService.onError` → `HttpServerBusiness.onError`
+→ default (an `HttpException` maps to its `status`/`body`; otherwise
+`500`).
+
+## Full example
+
+See [`examples/03-rest-server`](../../examples/03-rest-server) for a
+complete artefact: `HttpServerBusiness` on `B`; REST, SSE, WebSocket and
+GraphQL services pushing to the one server; multipart uploads; streaming
+downloads; service- and server-level interceptors; graceful shutdown.
+
+```bash
+pnpm --filter @xfcfam-examples/03-rest-server start
+```
+
+## License
+
+MIT.

package/dist/index.d.ts

@@ -0,0 +1,63 @@
+/**
+ * `@xfcfam/xf-server-http` — HTTP transport for the XF Architecture
+ * Model (CFAM). The Fastify implementation of the `@xfcfam/xf-server`
+ * contract.
+ *
+ * Exposes:
+ *
+ * - **{@link HttpServerBusiness}** — Business-Layer orchestrator. Owns
+ *   the Fastify lifecycle and the route registry. Concrete subclasses
+ *   live in the Business Layer; services push routes to it from their
+ *   own `init()` via `B.server.get(path, handler)`.
+ *
+ * - **{@link RestService}** — Interaction Generalization for raw-body
+ *   endpoints (streams or bytes). Provides `wrap(handler)`.
+ *
+ * - **{@link ObjectRestService}** — Same protocol, adds automatic
+ *   request parsing and response serialisation by `Content-Type` via
+ *   `object(handler)`. JSON built-in; XML/CSV/YAML pluggable;
+ *   developer-chosen date handling.
+ *
+ * - **Transfers**: {@link HttpRequest}, {@link HttpResponse},
+ *   {@link HttpAddress}, {@link HttpHandler}, {@link HttpMethod},
+ *   {@link MultipartPart}.
+ *
+ * - **Exceptions**: {@link HttpException} (base) +
+ *   `BadRequestException`, `UnauthorizedException`,
+ *   `ForbiddenException`, `NotFoundException`,
+ *   `InternalServerException`.
+ *
+ * - **Utilities**: {@link HttpStatusUtils}, {@link SchemaValidatorUtils},
+ *   {@link FileResponseUtils}, {@link ResponseUtils}.
+ *
+ * See https://xfcfam.org for the full XF specification.
+ */
+export { HttpServerBusiness } from './src/business/general/HttpServerBusiness.js';
+export type { ServerOptions, MultipartConfig } from './src/business/general/HttpServerBusiness.js';
+export { RestService } from './src/api/general/RestService.js';
+export { ObjectRestService } from './src/api/general/ObjectRestService.js';
+export type { ObjectRestOptions, BodyParser, BodySerializer, } from './src/api/general/ObjectRestService.js';
+export { WebSocketService } from './src/api/general/WebSocketService.js';
+export { GraphQLService } from './src/api/general/GraphQLService.js';
+export type { HttpMethod } from './src/business/transfers/HttpMethod.js';
+export type { HttpRequest } from './src/business/transfers/HttpRequest.js';
+export type { HttpResponse } from './src/business/transfers/HttpResponse.js';
+export type { HttpAddress, HttpHandler } from './src/business/transfers/Route.js';
+export type { MultipartPart } from './src/business/transfers/MultipartPart.js';
+export type { WebSocketConnection, WebSocketHandler } from './src/business/transfers/WebSocketConnection.js';
+export type { GraphQLConfig } from './src/business/transfers/GraphQLConfig.js';
+export { HttpException } from './src/business/transfers/HttpException.js';
+export { BadRequestException } from './src/business/transfers/BadRequestException.js';
+export { UnauthorizedException } from './src/business/transfers/UnauthorizedException.js';
+export { ForbiddenException } from './src/business/transfers/ForbiddenException.js';
+export { NotFoundException } from './src/business/transfers/NotFoundException.js';
+export { InternalServerException } from './src/business/transfers/InternalServerException.js';
+export { HttpStatusUtils } from './src/api/utils/HttpStatusUtils.js';
+export { SchemaValidatorUtils } from './src/api/utils/SchemaValidatorUtils.js';
+export type { Schema, SchemaParseResult } from './src/api/utils/SchemaValidatorUtils.js';
+export { FileResponseUtils } from './src/api/utils/FileResponseUtils.js';
+export type { FileBody } from './src/api/utils/FileResponseUtils.js';
+export { ResponseUtils } from './src/api/utils/ResponseUtils.js';
+export { SseUtils } from './src/api/utils/SseUtils.js';
+export type { ServerSentEvent } from './src/api/utils/SseUtils.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,8CAA8C,CAAA;AACjF,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,8CAA8C,CAAA;AAGlG,OAAO,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAA;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAA;AAC1E,YAAY,EACV,iBAAiB,EACjB,UAAU,EACV,cAAc,GACf,MAAM,wCAAwC,CAAA;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAA;AACxE,OAAO,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAA;AAGpE,YAAY,EAAE,UAAU,EAAE,MAAM,wCAAwC,CAAA;AACxE,YAAY,EAAE,WAAW,EAAE,MAAM,yCAAyC,CAAA;AAC1E,YAAY,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAA;AAC5E,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAA;AACjF,YAAY,EAAE,aAAa,EAAE,MAAM,2CAA2C,CAAA;AAC9E,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,iDAAiD,CAAA;AAC5G,YAAY,EAAE,aAAa,EAAE,MAAM,2CAA2C,CAAA;AAG9E,OAAO,EAAE,aAAa,EAAE,MAAM,2CAA2C,CAAA;AACzE,OAAO,EAAE,mBAAmB,EAAE,MAAM,iDAAiD,CAAA;AACrF,OAAO,EAAE,qBAAqB,EAAE,MAAM,mDAAmD,CAAA;AACzF,OAAO,EAAE,kBAAkB,EAAE,MAAM,gDAAgD,CAAA;AACnF,OAAO,EAAE,iBAAiB,EAAE,MAAM,+CAA+C,CAAA;AACjF,OAAO,EAAE,uBAAuB,EAAE,MAAM,qDAAqD,CAAA;AAG7F,OAAO,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAA;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,yCAAyC,CAAA;AAC9E,YAAY,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,yCAAyC,CAAA;AACxF,OAAO,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAA;AACxE,YAAY,EAAE,QAAQ,EAAE,MAAM,sCAAsC,CAAA;AACpE,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAA;AAChE,OAAO,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAA;AACtD,YAAY,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAA"}

package/dist/index.js

@@ -0,0 +1,55 @@
+/**
+ * `@xfcfam/xf-server-http` — HTTP transport for the XF Architecture
+ * Model (CFAM). The Fastify implementation of the `@xfcfam/xf-server`
+ * contract.
+ *
+ * Exposes:
+ *
+ * - **{@link HttpServerBusiness}** — Business-Layer orchestrator. Owns
+ *   the Fastify lifecycle and the route registry. Concrete subclasses
+ *   live in the Business Layer; services push routes to it from their
+ *   own `init()` via `B.server.get(path, handler)`.
+ *
+ * - **{@link RestService}** — Interaction Generalization for raw-body
+ *   endpoints (streams or bytes). Provides `wrap(handler)`.
+ *
+ * - **{@link ObjectRestService}** — Same protocol, adds automatic
+ *   request parsing and response serialisation by `Content-Type` via
+ *   `object(handler)`. JSON built-in; XML/CSV/YAML pluggable;
+ *   developer-chosen date handling.
+ *
+ * - **Transfers**: {@link HttpRequest}, {@link HttpResponse},
+ *   {@link HttpAddress}, {@link HttpHandler}, {@link HttpMethod},
+ *   {@link MultipartPart}.
+ *
+ * - **Exceptions**: {@link HttpException} (base) +
+ *   `BadRequestException`, `UnauthorizedException`,
+ *   `ForbiddenException`, `NotFoundException`,
+ *   `InternalServerException`.
+ *
+ * - **Utilities**: {@link HttpStatusUtils}, {@link SchemaValidatorUtils},
+ *   {@link FileResponseUtils}, {@link ResponseUtils}.
+ *
+ * See https://xfcfam.org for the full XF specification.
+ */
+// ── Business Generalization ───────────────────────────────
+export { HttpServerBusiness } from './src/business/general/HttpServerBusiness.js';
+// ── Interaction Generalizations ───────────────────────────
+export { RestService } from './src/api/general/RestService.js';
+export { ObjectRestService } from './src/api/general/ObjectRestService.js';
+export { WebSocketService } from './src/api/general/WebSocketService.js';
+export { GraphQLService } from './src/api/general/GraphQLService.js';
+// ── Exceptions ────────────────────────────────────────────
+export { HttpException } from './src/business/transfers/HttpException.js';
+export { BadRequestException } from './src/business/transfers/BadRequestException.js';
+export { UnauthorizedException } from './src/business/transfers/UnauthorizedException.js';
+export { ForbiddenException } from './src/business/transfers/ForbiddenException.js';
+export { NotFoundException } from './src/business/transfers/NotFoundException.js';
+export { InternalServerException } from './src/business/transfers/InternalServerException.js';
+// ── Utilities ─────────────────────────────────────────────
+export { HttpStatusUtils } from './src/api/utils/HttpStatusUtils.js';
+export { SchemaValidatorUtils } from './src/api/utils/SchemaValidatorUtils.js';
+export { FileResponseUtils } from './src/api/utils/FileResponseUtils.js';
+export { ResponseUtils } from './src/api/utils/ResponseUtils.js';
+export { SseUtils } from './src/api/utils/SseUtils.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,6DAA6D;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,8CAA8C,CAAA;AAGjF,6DAA6D;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAA;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAA;AAM1E,OAAO,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAA;AACxE,OAAO,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAA;AAWpE,6DAA6D;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,2CAA2C,CAAA;AACzE,OAAO,EAAE,mBAAmB,EAAE,MAAM,iDAAiD,CAAA;AACrF,OAAO,EAAE,qBAAqB,EAAE,MAAM,mDAAmD,CAAA;AACzF,OAAO,EAAE,kBAAkB,EAAE,MAAM,gDAAgD,CAAA;AACnF,OAAO,EAAE,iBAAiB,EAAE,MAAM,+CAA+C,CAAA;AACjF,OAAO,EAAE,uBAAuB,EAAE,MAAM,qDAAqD,CAAA;AAE7F,6DAA6D;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAA;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,yCAAyC,CAAA;AAE9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAA;AAExE,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAA;AAChE,OAAO,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAA"}

package/dist/src/api/A.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Interaction Layer Injection — placeholder.
+ *
+ * `A` is the canonical injection of the Interaction Layer. `@xfcfam/xf-server`
+ * is a library that contributes Generalizations and Transfer objects to
+ * the Interaction Layer ( `ObjectRestService`,
+ * `HttpServerBusiness`); it does not own any Logical of this layer, so
+ * its own `A` declares no static slots. The class is kept structurally
+ * complete (private constructor + empty `init` / `terminate`) so the
+ * artefact passes XF validation. It is NOT exported from the package —
+ * consumers import `A` from their own artefact.
+ */
+export declare class A {
+    private constructor();
+    static init(): Promise<void>;
+    static terminate(): Promise<void>;
+}
+//# sourceMappingURL=A.d.ts.map

package/dist/src/api/A.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"A.d.ts","sourceRoot":"","sources":["../../../src/api/A.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,qBAAa,CAAC;IACZ,OAAO;WACM,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;WACrB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;CACxC"}

package/dist/src/api/A.js

@@ -0,0 +1,18 @@
+/**
+ * Interaction Layer Injection — placeholder.
+ *
+ * `A` is the canonical injection of the Interaction Layer. `@xfcfam/xf-server`
+ * is a library that contributes Generalizations and Transfer objects to
+ * the Interaction Layer ( `ObjectRestService`,
+ * `HttpServerBusiness`); it does not own any Logical of this layer, so
+ * its own `A` declares no static slots. The class is kept structurally
+ * complete (private constructor + empty `init` / `terminate`) so the
+ * artefact passes XF validation. It is NOT exported from the package —
+ * consumers import `A` from their own artefact.
+ */
+export class A {
+    constructor() { }
+    static async init() { }
+    static async terminate() { }
+}
+//# sourceMappingURL=A.js.map

package/dist/src/api/A.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"A.js","sourceRoot":"","sources":["../../../src/api/A.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,CAAC;IACZ,gBAAuB,CAAC;IACxB,MAAM,CAAC,KAAK,CAAC,IAAI,KAAmB,CAAC;IACrC,MAAM,CAAC,KAAK,CAAC,SAAS,KAAmB,CAAC;CAC3C"}

package/dist/src/api/general/GraphQLService.d.ts

@@ -0,0 +1,48 @@
+import { StatelessService } from '@xfcfam/xf';
+import type { GraphQLConfig } from '../../business/transfers/GraphQLConfig.js';
+/**
+ * Interaction-Layer Generalization for a GraphQL entry point.
+ *
+ * GraphQL rides on HTTP (a single `POST /graphql`), but its dispatch
+ * model — one endpoint, many operations resolved by a schema — differs
+ * from REST routing, so it has its own base. A `GraphQLService`
+ * supplies the schema and resolvers and registers them on the server;
+ * the server mounts the GraphQL engine (Mercurius) on the same Fastify
+ * instance and port as the REST routes.
+ *
+ * Concrete subclasses override {@link config} and register from
+ * `init()` with `B.server.graphql(this.config())`.
+ *
+ * @example
+ * ```ts
+ * import { GraphQLService, type GraphQLConfig } from '@xfcfam/xf-server-http'
+ * import { B } from '../../business/B.js'
+ *
+ * export class ApiGraphQLService extends GraphQLService {
+ *   override async init(): Promise<void> {
+ *     B.server.graphql(this.config())
+ *   }
+ *
+ *   protected override config(): GraphQLConfig {
+ *     return {
+ *       schema: `type Query { hello(name: String): String }`,
+ *       resolvers: {
+ *         Query: { hello: (_: unknown, a: { name?: string }) => `Hi ${a.name ?? 'world'}` },
+ *       },
+ *       graphiql: true,
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class GraphQLService extends StatelessService {
+    init(): Promise<void>;
+    terminate(): Promise<void>;
+    /**
+     * The GraphQL endpoint configuration (schema + resolvers + options).
+     * Override to supply the API; subclasses pass the result to
+     * `B.server.graphql(...)` in `init()`.
+     */
+    protected abstract config(): GraphQLConfig;
+}
+//# sourceMappingURL=GraphQLService.d.ts.map

package/dist/src/api/general/GraphQLService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphQLService.d.ts","sourceRoot":"","sources":["../../../../src/api/general/GraphQLService.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2CAA2C,CAAA;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,8BAAsB,cAAe,SAAQ,gBAAgB;IAC5C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAEzC;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,MAAM,IAAI,aAAa;CAC3C"}

package/dist/src/api/general/GraphQLService.js

@@ -0,0 +1,43 @@
+import { StatelessService } from '@xfcfam/xf';
+/**
+ * Interaction-Layer Generalization for a GraphQL entry point.
+ *
+ * GraphQL rides on HTTP (a single `POST /graphql`), but its dispatch
+ * model — one endpoint, many operations resolved by a schema — differs
+ * from REST routing, so it has its own base. A `GraphQLService`
+ * supplies the schema and resolvers and registers them on the server;
+ * the server mounts the GraphQL engine (Mercurius) on the same Fastify
+ * instance and port as the REST routes.
+ *
+ * Concrete subclasses override {@link config} and register from
+ * `init()` with `B.server.graphql(this.config())`.
+ *
+ * @example
+ * ```ts
+ * import { GraphQLService, type GraphQLConfig } from '@xfcfam/xf-server-http'
+ * import { B } from '../../business/B.js'
+ *
+ * export class ApiGraphQLService extends GraphQLService {
+ *   override async init(): Promise<void> {
+ *     B.server.graphql(this.config())
+ *   }
+ *
+ *   protected override config(): GraphQLConfig {
+ *     return {
+ *       schema: `type Query { hello(name: String): String }`,
+ *       resolvers: {
+ *         Query: { hello: (_: unknown, a: { name?: string }) => `Hi ${a.name ?? 'world'}` },
+ *       },
+ *       graphiql: true,
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export class GraphQLService extends StatelessService {
+    async init() {
+        // Subclasses override and call B.server.graphql(this.config()) inside.
+    }
+    async terminate() { }
+}
+//# sourceMappingURL=GraphQLService.js.map

package/dist/src/api/general/GraphQLService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphQLService.js","sourceRoot":"","sources":["../../../../src/api/general/GraphQLService.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAG7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,OAAgB,cAAe,SAAQ,gBAAgB;IAClD,KAAK,CAAC,IAAI;QACjB,uEAAuE;IACzE,CAAC;IAEQ,KAAK,CAAC,SAAS,KAAmB,CAAC;CAQ7C"}