@headless-lms/server 0.1.0

package/dist/http/scope.d.ts

@@ -0,0 +1,22 @@
+import { Container } from "../app/container.js";
+import { StaffRole } from "@headless-lms/core/organizations";
+import { FastifyRequest } from "fastify";
+//#region src/http/scope.d.ts
+interface OrgScope {
+  /** Domain `organizations.id` for the session's active org. */
+  orgId: string;
+  /** Domain `users.id` of the acting person. */
+  userId: string;
+  /** Domain `org_users.id` — the acting org user in this org. */
+  orgUserId: string;
+  /** The role held in this org. */
+  role: StaffRole;
+  /** Better-auth organization id (for writes that go through the auth provider). */
+  authOrgId: string;
+}
+/** Thrown when the session has no resolvable active org / domain user. */
+declare class NoActiveOrgError extends Error {}
+declare function resolveScope(container: Container, req: FastifyRequest): Promise<OrgScope>;
+//#endregion
+export { NoActiveOrgError, OrgScope, resolveScope };
+//# sourceMappingURL=scope.d.ts.map

package/dist/http/scope.js

@@ -0,0 +1,28 @@
+import { isStaffRole } from "@headless-lms/core/organizations";
+//#region src/http/scope.ts
+/** Thrown when the session has no resolvable active org / domain user. */
+var NoActiveOrgError = class extends Error {};
+async function resolveScope(container, req) {
+	const authUser = req.authUser;
+	const authOrgId = req.authOrgId ?? null;
+	if (!authUser) throw new NoActiveOrgError("no authenticated user");
+	if (!authOrgId || !req.orgId) throw new NoActiveOrgError("no active organization in session");
+	const org = await container.organizations.getById(req.orgId);
+	if (!org) throw new NoActiveOrgError("active organization not found");
+	const user = await container.identity.getUserByExternalId(authUser.id);
+	if (!user) throw new NoActiveOrgError("no domain user for the current user");
+	const orgUser = await container.organizations.getOrgUser(org.id, user.id);
+	if (!orgUser || !isStaffRole(orgUser.role)) throw new NoActiveOrgError("not a staff member of the active organization");
+	container.requestContext.set({ orgId: org.id });
+	return {
+		orgId: org.id,
+		userId: user.id,
+		orgUserId: orgUser.id,
+		role: orgUser.role,
+		authOrgId
+	};
+}
+//#endregion
+export { NoActiveOrgError, resolveScope };
+
+//# sourceMappingURL=scope.js.map

package/dist/http/scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.js","names":[],"sources":["../../src/http/scope.ts"],"sourcesContent":["import type { FastifyRequest } from 'fastify';\nimport type { Container } from '../app/container.js';\nimport { isStaffRole, type StaffRole } from '@headless-lms/core/organizations';\n\nexport interface OrgScope {\n  /** Domain `organizations.id` for the session's active org. */\n  orgId: string;\n  /** Domain `users.id` of the acting person. */\n  userId: string;\n  /** Domain `org_users.id` — the acting org user in this org. */\n  orgUserId: string;\n  /** The role held in this org. */\n  role: StaffRole;\n  /** Better-auth organization id (for writes that go through the auth provider). */\n  authOrgId: string;\n}\n\n/** Thrown when the session has no resolvable active org / domain user. */\nexport class NoActiveOrgError extends Error {}\n\nexport async function resolveScope(container: Container, req: FastifyRequest): Promise<OrgScope> {\n  const authUser = req.authUser;\n  const authOrgId = req.authOrgId ?? null;\n  if (!authUser) {\n    throw new NoActiveOrgError('no authenticated user');\n  }\n  if (!authOrgId || !req.orgId) {\n    throw new NoActiveOrgError('no active organization in session');\n  }\n  // The session guard already translated the auth org id to the domain org.\n  const org = await container.organizations.getById(req.orgId);\n  if (!org) {\n    throw new NoActiveOrgError('active organization not found');\n  }\n  const user = await container.identity.getUserByExternalId(authUser.id);\n  if (!user) {\n    throw new NoActiveOrgError('no domain user for the current user');\n  }\n  const orgUser = await container.organizations.getOrgUser(org.id, user.id);\n  if (!orgUser || !isStaffRole(orgUser.role)) {\n    throw new NoActiveOrgError('not a staff member of the active organization');\n  }\n  container.requestContext.set({ orgId: org.id });\n  return {\n    orgId: org.id,\n    userId: user.id,\n    orgUserId: orgUser.id,\n    role: orgUser.role,\n    authOrgId,\n  };\n}\n"],"mappings":";;;AAkBA,IAAa,mBAAb,cAAsC,MAAM,CAAC;AAE7C,eAAsB,aAAa,WAAsB,KAAwC;CAC/F,MAAM,WAAW,IAAI;CACrB,MAAM,YAAY,IAAI,aAAa;CACnC,IAAI,CAAC,UACH,MAAM,IAAI,iBAAiB,uBAAuB;CAEpD,IAAI,CAAC,aAAa,CAAC,IAAI,OACrB,MAAM,IAAI,iBAAiB,mCAAmC;CAGhE,MAAM,MAAM,MAAM,UAAU,cAAc,QAAQ,IAAI,KAAK;CAC3D,IAAI,CAAC,KACH,MAAM,IAAI,iBAAiB,+BAA+B;CAE5D,MAAM,OAAO,MAAM,UAAU,SAAS,oBAAoB,SAAS,EAAE;CACrE,IAAI,CAAC,MACH,MAAM,IAAI,iBAAiB,qCAAqC;CAElE,MAAM,UAAU,MAAM,UAAU,cAAc,WAAW,IAAI,IAAI,KAAK,EAAE;CACxE,IAAI,CAAC,WAAW,CAAC,YAAY,QAAQ,IAAI,GACvC,MAAM,IAAI,iBAAiB,+CAA+C;CAE5E,UAAU,eAAe,IAAI,EAAE,OAAO,IAAI,GAAG,CAAC;CAC9C,OAAO;EACL,OAAO,IAAI;EACX,QAAQ,KAAK;EACb,WAAW,QAAQ;EACnB,MAAM,QAAQ;EACd;CACF;AACF"}

package/dist/http/server.d.ts

@@ -0,0 +1,8 @@
+import { Container } from "../app/container.js";
+import { ServerConfig } from "./config.js";
+import { FastifyInstance } from "fastify";
+//#region src/http/server.d.ts
+declare function buildServer(config: ServerConfig, container: Container): Promise<FastifyInstance>;
+//#endregion
+export { buildServer };
+//# sourceMappingURL=server.d.ts.map

package/dist/http/server.js

@@ -0,0 +1,33 @@
+import { registerCors } from "./plugins/cors.js";
+import { registerOpenApi } from "./plugins/openapi.js";
+import { registerAuth } from "./plugins/auth.js";
+import { errorHandler } from "./plugins/error-handler.js";
+import { registerRoutes } from "./routes.js";
+import Fastify from "fastify";
+import { serializerCompiler, validatorCompiler } from "fastify-type-provider-zod";
+//#region src/http/server.ts
+async function buildServer(config, container) {
+	const app = Fastify({
+		loggerInstance: container.loggerInstance,
+		disableRequestLogging: config.requestLogging === false
+	});
+	app.addHook("onRequest", (request, _reply, done) => {
+		container.requestContext.run({ reqId: request.id }, done);
+	});
+	app.setValidatorCompiler(validatorCompiler);
+	app.setSerializerCompiler(serializerCompiler);
+	app.setErrorHandler(errorHandler);
+	registerCors(app, config);
+	registerOpenApi(app, config);
+	registerAuth(app, container);
+	registerRoutes(app, container);
+	app.addHook("onClose", async () => {
+		await container.outboxRelay.stop();
+		await container.automationEngine.stop();
+	});
+	return app;
+}
+//#endregion
+export { buildServer };
+
+//# sourceMappingURL=server.js.map

package/dist/http/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","names":[],"sources":["../../src/http/server.ts"],"sourcesContent":["import Fastify, { type FastifyBaseLogger, type FastifyInstance } from 'fastify';\nimport { serializerCompiler, validatorCompiler } from 'fastify-type-provider-zod';\nimport type { Container } from '../app/container.js';\nimport type { ServerConfig } from './config.js';\nimport { registerCors } from './plugins/cors.js';\nimport { registerOpenApi } from './plugins/openapi.js';\nimport { registerAuth } from './plugins/auth.js';\nimport { errorHandler } from './plugins/error-handler.js';\nimport { registerRoutes } from './routes.js';\n\nexport async function buildServer(\n  config: ServerConfig,\n  container: Container,\n): Promise<FastifyInstance> {\n  // One log stream for the whole process: HTTP shares the container's pino root.\n  // Widened to FastifyBaseLogger so the instance keeps the default logger\n  // generic (a concrete pino type would ripple through every plugin signature).\n  const app = Fastify({\n    loggerInstance: container.loggerInstance as FastifyBaseLogger,\n    // Fastify's own request/response pair per call — noisy in a dev console,\n    // useful as an access log in production. Our own logs are unaffected.\n    disableRequestLogging: config.requestLogging === false,\n  });\n\n  // Enter the request-scoped log context: every line logged inside this\n  // request's async scope carries its reqId (and orgId once resolveScope runs),\n  // wherever it is emitted.\n  app.addHook('onRequest', (request, _reply, done) => {\n    container.requestContext.run({ reqId: request.id }, done);\n  });\n\n  // Validate + serialize request/response bodies from the shared Zod contract.\n  app.setValidatorCompiler(validatorCompiler);\n  app.setSerializerCompiler(serializerCompiler);\n  app.setErrorHandler(errorHandler);\n\n  registerCors(app, config);\n  registerOpenApi(app, config);\n  registerAuth(app, container);\n\n  registerRoutes(app, container);\n\n  // Drain + stop the outbox relay and the automation engine on shutdown.\n  // Harmless when neither was started (gen-openapi boots this app with\n  // ready() + close() only).\n  app.addHook('onClose', async () => {\n    await container.outboxRelay.stop();\n    await container.automationEngine.stop();\n  });\n\n  return app;\n}\n"],"mappings":";;;;;;;;AAUA,eAAsB,YACpB,QACA,WAC0B;CAI1B,MAAM,MAAM,QAAQ;EAClB,gBAAgB,UAAU;EAG1B,uBAAuB,OAAO,mBAAmB;CACnD,CAAC;CAKD,IAAI,QAAQ,cAAc,SAAS,QAAQ,SAAS;EAClD,UAAU,eAAe,IAAI,EAAE,OAAO,QAAQ,GAAG,GAAG,IAAI;CAC1D,CAAC;CAGD,IAAI,qBAAqB,iBAAiB;CAC1C,IAAI,sBAAsB,kBAAkB;CAC5C,IAAI,gBAAgB,YAAY;CAEhC,aAAa,KAAK,MAAM;CACxB,gBAAgB,KAAK,MAAM;CAC3B,aAAa,KAAK,SAAS;CAE3B,eAAe,KAAK,SAAS;CAK7B,IAAI,QAAQ,WAAW,YAAY;EACjC,MAAM,UAAU,YAAY,KAAK;EACjC,MAAM,UAAU,iBAAiB,KAAK;CACxC,CAAC;CAED,OAAO;AACT"}

package/dist/http/web-bridge.d.ts

@@ -0,0 +1,9 @@
+import { FastifyReply, FastifyRequest } from "fastify";
+//#region src/http/web-bridge.d.ts
+/** Builds a Web `Request` from an incoming Fastify request. */
+declare function toWebRequest(request: FastifyRequest): Request;
+/** Copies a Web `Response` back onto a Fastify reply, preserving multiple cookies. */
+declare function bridgeWebResponse(response: Response, reply: FastifyReply): Promise<void>;
+//#endregion
+export { bridgeWebResponse, toWebRequest };
+//# sourceMappingURL=web-bridge.d.ts.map

package/dist/http/web-bridge.js

@@ -0,0 +1,27 @@
+import { fromNodeHeaders } from "better-auth/node";
+//#region src/http/web-bridge.ts
+/** Builds a Web `Request` from an incoming Fastify request. */
+function toWebRequest(request) {
+	const url = new URL(request.url, `http://${request.headers.host}`);
+	const body = request.method !== "GET" && request.method !== "HEAD" && request.method !== "DELETE" ? typeof request.body === "string" ? request.body : request.body ? JSON.stringify(request.body) : void 0 : void 0;
+	return new Request(url.toString(), {
+		method: request.method,
+		headers: fromNodeHeaders(request.headers),
+		body
+	});
+}
+/** Copies a Web `Response` back onto a Fastify reply, preserving multiple cookies. */
+async function bridgeWebResponse(response, reply) {
+	reply.status(response.status);
+	const cookies = response.headers.getSetCookie();
+	if (cookies.length > 0) reply.raw.setHeader("set-cookie", cookies);
+	response.headers.forEach((value, key) => {
+		if (key.toLowerCase() === "set-cookie") return;
+		reply.header(key, value);
+	});
+	reply.send(response.body ? await response.text() : null);
+}
+//#endregion
+export { bridgeWebResponse, toWebRequest };
+
+//# sourceMappingURL=web-bridge.js.map

package/dist/http/web-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-bridge.js","names":[],"sources":["../../src/http/web-bridge.ts"],"sourcesContent":["// Bridges between Fastify's request/reply and the Web `Request`/`Response` that\n// better-auth speaks. The auth catch-all hands a Fastify request to a\n// Web-standard handler and forwards the\n// Web response back, so the conversion lives here once.\nimport type { FastifyReply, FastifyRequest } from 'fastify';\nimport { fromNodeHeaders } from 'better-auth/node';\n\n/** Builds a Web `Request` from an incoming Fastify request. */\nexport function toWebRequest(request: FastifyRequest): Request {\n  const url = new URL(request.url, `http://${request.headers.host}`);\n  // GET/HEAD/DELETE never carry a body; passing one to `Request` throws. For the\n  // rest, forward a string body verbatim and JSON-encode a parsed object.\n  const hasBody =\n    request.method !== 'GET' && request.method !== 'HEAD' && request.method !== 'DELETE';\n  const body = hasBody\n    ? typeof request.body === 'string'\n      ? request.body\n      : request.body\n        ? JSON.stringify(request.body)\n        : undefined\n    : undefined;\n  return new Request(url.toString(), {\n    method: request.method,\n    headers: fromNodeHeaders(request.headers),\n    body,\n  });\n}\n\n/** Copies a Web `Response` back onto a Fastify reply, preserving multiple cookies. */\nexport async function bridgeWebResponse(response: Response, reply: FastifyReply): Promise<void> {\n  reply.status(response.status);\n  // Emit each Set-Cookie value individually — forEach() collapses multiple\n  // Set-Cookie headers into one comma-joined string (undici behaviour), which\n  // corrupts multi-cookie auth responses. getSetCookie() returns them as an\n  // array so each one is forwarded as a separate header.\n  const cookies = response.headers.getSetCookie();\n  if (cookies.length > 0) {\n    reply.raw.setHeader('set-cookie', cookies);\n  }\n  response.headers.forEach((value, key) => {\n    if (key.toLowerCase() === 'set-cookie') {\n      return;\n    } // already handled above\n    reply.header(key, value);\n  });\n  reply.send(response.body ? await response.text() : null);\n}\n"],"mappings":";;;AAQA,SAAgB,aAAa,SAAkC;CAC7D,MAAM,MAAM,IAAI,IAAI,QAAQ,KAAK,UAAU,QAAQ,QAAQ,MAAM;CAKjE,MAAM,OADJ,QAAQ,WAAW,SAAS,QAAQ,WAAW,UAAU,QAAQ,WAAW,WAE1E,OAAO,QAAQ,SAAS,WACtB,QAAQ,OACR,QAAQ,OACN,KAAK,UAAU,QAAQ,IAAI,IAC3B,KAAA,IACJ,KAAA;CACJ,OAAO,IAAI,QAAQ,IAAI,SAAS,GAAG;EACjC,QAAQ,QAAQ;EAChB,SAAS,gBAAgB,QAAQ,OAAO;EACxC;CACF,CAAC;AACH;;AAGA,eAAsB,kBAAkB,UAAoB,OAAoC;CAC9F,MAAM,OAAO,SAAS,MAAM;CAK5B,MAAM,UAAU,SAAS,QAAQ,aAAa;CAC9C,IAAI,QAAQ,SAAS,GACnB,MAAM,IAAI,UAAU,cAAc,OAAO;CAE3C,SAAS,QAAQ,SAAS,OAAO,QAAQ;EACvC,IAAI,IAAI,YAAY,MAAM,cACxB;EAEF,MAAM,OAAO,KAAK,KAAK;CACzB,CAAC;CACD,MAAM,KAAK,SAAS,OAAO,MAAM,SAAS,KAAK,IAAI,IAAI;AACzD"}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import { AuthUser } from "./http/fastify.js";
+import { AdapterOverrides, BuildContainerOptions, Config, Container, LoggingConfig } from "./app/container.js";
+import { loadIntegrations } from "./app/integrations.js";
+import { ServerConfig } from "./http/config.js";
+import { buildServer } from "./http/server.js";
+import { runMigrations } from "@headless-lms/adapter-db";
+import { InlineAutomationEngine } from "@headless-lms/adapter-defaults/workflows";
+import { AutomationEngine } from "@headless-lms/core/automations";
+import { Mailer } from "@headless-lms/core/shared/mailer";
+import { EmailMessage, EmailSender, ObjectStorage } from "@headless-lms/core/shared/ports";
+//#region src/index.d.ts
+declare function createContainer(config: ServerConfig, options?: BuildContainerOptions): Promise<Container>;
+//#endregion
+export { type AdapterOverrides, type AuthUser, type AutomationEngine, type BuildContainerOptions, type Container, type Config as ContainerConfig, type EmailMessage, type EmailSender, InlineAutomationEngine, type LoggingConfig, type Mailer, type ObjectStorage, type ServerConfig, buildServer, createContainer, loadIntegrations, runMigrations };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,16 @@
+import { loadIntegrations } from "./app/integrations.js";
+import { buildContainer } from "./app/container.js";
+import { buildServer } from "./http/server.js";
+import { runMigrations } from "@headless-lms/adapter-db";
+import { InlineAutomationEngine } from "@headless-lms/adapter-defaults/workflows";
+//#region src/index.ts
+async function createContainer(config, options) {
+	return buildContainer({
+		...config.container,
+		deliveryExpirySeconds: config.deliveryExpirySeconds
+	}, options);
+}
+//#endregion
+export { InlineAutomationEngine, buildServer, createContainer, loadIntegrations, runMigrations };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["// Public surface of @headless-lms/server. Installations compose these:\n//   const container = await createContainer(config, { pluginsDir, adapters })\n//   const app = await buildServer(config, container)\nimport {\n  buildContainer,\n  type BuildContainerOptions,\n  type Container,\n} from './app/container.js';\nimport type { ServerConfig } from './http/config.js';\n\nexport { buildServer } from './http/server.js';\nexport { loadIntegrations } from './app/integrations.js';\nexport { InlineAutomationEngine } from '@headless-lms/adapter-defaults/workflows';\n// Operational functions consumed by the @headless-lms/cli bin.\nexport { runMigrations } from '@headless-lms/adapter-db';\nexport type { ServerConfig } from './http/config.js';\n// Re-exporting AuthUser also pulls its module into any program that imports\n// this file (directly or via the workspace path mapping), which is what\n// applies its ambient `declare module \"fastify\"` augmentation\n// (FastifyRequest.authUser/orgId, FastifyInstance.requireOrgSession) —\n// otherwise nothing imports fastify.d.ts and the augmentation never loads.\nexport type { AuthUser } from './http/fastify.js';\nexport type {\n  Config as ContainerConfig,\n  Container,\n  AdapterOverrides,\n  BuildContainerOptions,\n  LoggingConfig,\n} from './app/container.js';\nexport type { EmailSender, EmailMessage, ObjectStorage } from '@headless-lms/core/shared/ports';\nexport type { Mailer } from '@headless-lms/core/shared/mailer';\nexport type { AutomationEngine } from '@headless-lms/core/automations';\n\nexport async function createContainer(\n  config: ServerConfig,\n  options?: BuildContainerOptions,\n): Promise<Container> {\n  return buildContainer(\n    { ...config.container, deliveryExpirySeconds: config.deliveryExpirySeconds },\n    options,\n  );\n}\n"],"mappings":";;;;;;AAiCA,eAAsB,gBACpB,QACA,SACoB;CACpB,OAAO,eACL;EAAE,GAAG,OAAO;EAAW,uBAAuB,OAAO;CAAsB,GAC3E,OACF;AACF"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@headless-lms/server",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@fastify/cors": "^11.2.0",
+    "@fastify/swagger": "^9.7.0",
+    "@fastify/swagger-ui": "^6.0.0",
+    "better-auth": "^1.6.25",
+    "fastify": "^5.2.0",
+    "fastify-type-provider-zod": "^7.0.0",
+    "zod": "4.4.3",
+    "@headless-lms/adapter-auth": "0.1.0",
+    "@headless-lms/adapter-defaults": "0.1.0",
+    "@headless-lms/core": "0.1.0",
+    "@headless-lms/adapter-db": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsdown": "^0.22.9",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "description": "Fastify server and composition root for the headless LMS",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mdwt/headless-lms.git",
+    "directory": "packages/server"
+  },
+  "homepage": "https://github.com/mdwt/headless-lms#readme",
+  "bugs": {
+    "url": "https://github.com/mdwt/headless-lms/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "lint": "eslint src",
+    "format": "prettier --write .",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}