@tatara/http 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohammed Bageri
+
+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,3 @@
-# Temporary Holding Version
+# @tatara/http
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Part of [tatara](https://github.com/mohammed-bageri/tatara-cli).

package/dist/index.d.mts

@@ -0,0 +1,171 @@
+import { Hook, OpenAPIHono, z } from "@hono/zod-openapi";
+import { CoreLogger } from "@tatara/core";
+import { Context, MiddlewareHandler } from "hono";
+import { ContentfulStatusCode } from "hono/utils/http-status";
+//#region src/errors.d.ts
+export declare class AppError extends Error {
+  readonly status: ContentfulStatusCode;
+  readonly code: string;
+  readonly details?: unknown;
+  /** True when the message is generic, so the response may replace it with `errors.<code>` in the caller's language. */
+  readonly translatable: boolean;
+  constructor(status: ContentfulStatusCode, code: string, message: string, details?: unknown, translatable?: boolean);
+}
+export declare class ValidationError extends AppError {
+  constructor(message?: string, details?: unknown);
+}
+export declare class BusinessRuleError extends AppError {
+  constructor(code: string, message: string, details?: unknown);
+}
+export declare class UnauthorizedError extends AppError {
+  constructor(message?: string);
+}
+export declare class ForbiddenError extends AppError {
+  constructor(message?: string);
+}
+export declare class NotFoundError extends AppError {
+  constructor(resource?: string);
+}
+export declare class ConflictError extends AppError {
+  constructor(message?: string, details?: unknown);
+}
+//#endregion
+//#region src/app.d.ts
+/** Variables every tatara app has; apps extend them with their own (principal, language, …). */
+interface HttpEnv {
+  Variables: {
+    requestId: string;
+    logger: CoreLogger;
+  };
+}
+type Defaults<E extends HttpEnv> = Partial<Omit<E["Variables"], "requestId" | "logger">>;
+/** Sets requestId, a request-scoped logger and default variables; logs one line per request. */
+export declare function requestContext<E extends HttpEnv>(logger: CoreLogger, defaults?: Defaults<E>): MiddlewareHandler<E, string, {}, Response>;
+interface CreateAppOptions<E extends HttpEnv> {
+  logger: CoreLogger;
+  cors: {
+    origins: string[];
+    exposeHeaders?: string[];
+    allowHeaders?: string[];
+  };
+  bodyLimitBytes: number;
+  /** initial values for the app's own variables, e.g. `{ principal: null, language: "en" }` */
+  defaults?: Defaults<E>;
+}
+/** A plain OpenAPIHono app with request context, secure headers, CORS, body limit, /health and /ready. */
+export declare function createApp<E extends HttpEnv>(options: CreateAppOptions<E>): OpenAPIHono<E>;
+interface RouteDefinition<A extends string = string, E extends HttpEnv = HttpEnv> {
+  /** which HTTP app serves these routes */
+  app: A;
+  /** mounted under the prefix + basePath, e.g. "/notes" */
+  basePath: string;
+  router: OpenAPIHono<E>;
+}
+/** Default export of every `routes/*.routes.ts`; discovered by `tatara sync`. */
+export declare function defineRoutes<D extends RouteDefinition<string, any>>(definition: D): D;
+/** A router for one routes file. Attach middleware per route or per path, never `use("*")`. */
+export declare function createRouter<E extends HttpEnv>(): OpenAPIHono<E>;
+/** Mounts the discovered routes that belong to `app` under `prefix`. */
+export declare function mountRoutes<E extends HttpEnv>(app: OpenAPIHono<E>, routes: readonly RouteDefinition<string, any>[], options: {
+  app: string;
+  prefix: string;
+}): void;
+type OpenApiDocument = ReturnType<OpenAPIHono["getOpenAPI31Document"]>;
+/** `/openapi.json` (built per request so `extend` can add to it) and the Scalar UI at `/docs`. */
+export declare function serveOpenApi<E extends HttpEnv>(app: OpenAPIHono<E>, options: {
+  title: string;
+  version?: string;
+  extend?: (document: OpenApiDocument) => void | Promise<void>;
+}): void;
+/** The error envelope for every error, plus a 404 for unknown routes. */
+export declare function handleErrors<E extends HttpEnv>(app: OpenAPIHono<E>, options?: {
+  message?: (err: AppError, c: Context<E>) => string;
+}): void;
+//#endregion
+//#region src/response.d.ts
+export declare const errorSchema: z.ZodObject<{
+  success: z.ZodLiteral<false>;
+  error: z.ZodString;
+  code: z.ZodString;
+  details: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+export declare const paginationMetaSchema: z.ZodObject<{
+  page: z.ZodNumber;
+  pageSize: z.ZodNumber;
+  total: z.ZodNumber;
+  totalPages: z.ZodNumber;
+}, z.core.$strip>;
+export declare const paginationQuerySchema: z.ZodObject<{
+  page: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+  pageSize: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export type PaginationQuery = z.infer<typeof paginationQuerySchema>;
+export declare function successSchema<T extends z.ZodType>(data: T): z.ZodObject<{
+  success: z.ZodLiteral<true>;
+  data: T;
+}, z.core.$strip>;
+export declare function paginatedSchema<T extends z.ZodType>(item: T): z.ZodObject<{
+  success: z.ZodLiteral<true>;
+  data: z.ZodArray<T>;
+  meta: z.ZodObject<{
+    page: z.ZodNumber;
+    pageSize: z.ZodNumber;
+    total: z.ZodNumber;
+    totalPages: z.ZodNumber;
+  }, z.core.$strip>;
+}, z.core.$strip>;
+export declare function success<T>(data: T): {
+  success: true;
+  data: T;
+};
+export declare function paginated<T>(data: T[], page: number, pageSize: number, total: number): {
+  success: true;
+  data: T[];
+  meta: {
+    page: number;
+    pageSize: number;
+    total: number;
+    totalPages: number;
+  };
+};
+export declare function jsonContent<T extends z.ZodType>(schema: T, description: string): {
+  content: {
+    "application/json": {
+      schema: T;
+    };
+  };
+  description: string;
+};
+/** A required JSON request body. Without `required`, a request with no body skips validation. */
+export declare function jsonBody<T extends z.ZodType>(schema: T, description: string): {
+  content: {
+    "application/json": {
+      schema: T;
+    };
+  };
+  description: string;
+  required: boolean;
+};
+declare const ERROR_DESCRIPTIONS: {
+  readonly 400: "Invalid request";
+  readonly 401: "Authentication required";
+  readonly 403: "Forbidden";
+  readonly 404: "Not found";
+  readonly 409: "Conflict";
+};
+type ErrorStatus = keyof typeof ERROR_DESCRIPTIONS;
+/** OpenAPI error responses for the given statuses, all using the shared error envelope. */
+export declare function errorResponses<const S extends ErrorStatus[]>(...statuses: S): { [K in S[number]]: ReturnType<typeof jsonContent<typeof errorSchema>>; };
+//#endregion
+//#region src/server.d.ts
+/** Starts an HTTP app; on shutdown stops accepting connections and drains in-flight requests. */
+export declare function startServer<E extends HttpEnv>(app: OpenAPIHono<E>, options: {
+  port: number;
+  name: string;
+  logger: CoreLogger;
+}): import("@hono/node-server").ServerType;
+//#endregion
+//#region src/validation.d.ts
+export declare const validationHook: Hook<any, any, any, any>;
+//#endregion
+export type { CreateAppOptions, HttpEnv, RouteDefinition };

package/dist/index.mjs

@@ -0,0 +1,270 @@
+import { OpenAPIHono, z } from "@hono/zod-openapi";
+import { Scalar } from "@scalar/hono-api-reference";
+import { handleSignals, onShutdown, runReadinessChecks } from "@tatara/core";
+import { bodyLimit } from "hono/body-limit";
+import { cors } from "hono/cors";
+import { createMiddleware } from "hono/factory";
+import { HTTPException } from "hono/http-exception";
+import { secureHeaders } from "hono/secure-headers";
+import { serve } from "@hono/node-server";
+//#region src/errors.ts
+var AppError = class extends Error {
+	status;
+	code;
+	details;
+	/** True when the message is generic, so the response may replace it with `errors.<code>` in the caller's language. */
+	translatable;
+	constructor(status, code, message, details, translatable = false) {
+		super(message);
+		this.name = new.target.name;
+		this.status = status;
+		this.code = code;
+		this.details = details;
+		this.translatable = translatable;
+	}
+};
+var ValidationError = class extends AppError {
+	constructor(message, details) {
+		super(400, "VALIDATION_ERROR", message ?? "Invalid request", details, message === void 0);
+	}
+};
+var BusinessRuleError = class extends AppError {
+	constructor(code, message, details) {
+		super(400, code, message, details, true);
+	}
+};
+var UnauthorizedError = class extends AppError {
+	constructor(message) {
+		super(401, "UNAUTHORIZED", message ?? "Authentication required", void 0, message === void 0);
+	}
+};
+var ForbiddenError = class extends AppError {
+	constructor(message) {
+		super(403, "FORBIDDEN", message ?? "You do not have permission to do this", void 0, message === void 0);
+	}
+};
+var NotFoundError = class extends AppError {
+	constructor(resource) {
+		super(404, "NOT_FOUND", `${resource ?? "Resource"} not found`, void 0, resource === void 0);
+	}
+};
+var ConflictError = class extends AppError {
+	constructor(message, details) {
+		super(409, "CONFLICT", message ?? "Resource already exists", details, message === void 0);
+	}
+};
+//#endregion
+//#region src/validation.ts
+const validationHook = (result) => {
+	if (!result.success) throw new ValidationError(void 0, result.error.issues.map((issue) => ({
+		path: issue.path.join("."),
+		message: issue.message,
+		code: issue.code
+	})));
+};
+//#endregion
+//#region src/app.ts
+const REQUEST_ID = /^[\w-]{8,128}$/;
+/** Sets requestId, a request-scoped logger and default variables; logs one line per request. */
+function requestContext(logger, defaults = {}) {
+	return createMiddleware(async (c, next) => {
+		const incoming = c.req.header("x-request-id");
+		const requestId = incoming && REQUEST_ID.test(incoming) ? incoming : crypto.randomUUID();
+		const log = logger.child({ requestId });
+		const set = c.set;
+		set("requestId", requestId);
+		set("logger", log);
+		for (const [key, value] of Object.entries(defaults)) set(key, value);
+		c.header("x-request-id", requestId);
+		const start = performance.now();
+		await next();
+		const ms = Math.round(performance.now() - start);
+		const status = c.res.status;
+		const entry = {
+			method: c.req.method,
+			path: c.req.path,
+			status,
+			ms
+		};
+		if (status >= 500) log.error(entry, "request failed");
+		else log.info(entry, "request");
+	});
+}
+/** A plain OpenAPIHono app with request context, secure headers, CORS, body limit, /health and /ready. */
+function createApp(options) {
+	const app = new OpenAPIHono({ defaultHook: validationHook });
+	app.use(requestContext(options.logger, options.defaults));
+	app.use(secureHeaders());
+	app.use(cors({
+		origin: options.cors.origins,
+		credentials: true,
+		allowHeaders: options.cors.allowHeaders ?? [
+			"Content-Type",
+			"Authorization",
+			"X-Request-Id",
+			"Accept-Language"
+		],
+		exposeHeaders: options.cors.exposeHeaders ?? ["X-Request-Id"]
+	}));
+	app.use(bodyLimit({ maxSize: options.bodyLimitBytes }));
+	app.get("/health", (c) => c.json({ status: "ok" }));
+	app.get("/ready", async (c) => {
+		const result = await runReadinessChecks();
+		return c.json(result, result.ready ? 200 : 503);
+	});
+	return app;
+}
+/** Default export of every `routes/*.routes.ts`; discovered by `tatara sync`. */
+function defineRoutes(definition) {
+	return definition;
+}
+/** A router for one routes file. Attach middleware per route or per path, never `use("*")`. */
+function createRouter() {
+	return new OpenAPIHono({ defaultHook: validationHook });
+}
+/** Mounts the discovered routes that belong to `app` under `prefix`. */
+function mountRoutes(app, routes, options) {
+	for (const definition of routes) if (definition.app === options.app) app.route(`${options.prefix}${definition.basePath}`, definition.router);
+}
+/** `/openapi.json` (built per request so `extend` can add to it) and the Scalar UI at `/docs`. */
+function serveOpenApi(app, options) {
+	const config = {
+		openapi: "3.1.0",
+		info: {
+			title: options.title,
+			version: options.version ?? "1.0.0"
+		}
+	};
+	app.get("/openapi.json", async (c) => {
+		const document = app.getOpenAPI31Document(config);
+		await options.extend?.(document);
+		return c.json(document);
+	});
+	app.get("/docs", Scalar({
+		url: "/openapi.json",
+		pageTitle: options.title
+	}));
+}
+/** The error envelope for every error, plus a 404 for unknown routes. */
+function handleErrors(app, options = {}) {
+	app.onError((err, c) => {
+		if (err instanceof AppError) {
+			const message = options.message ? options.message(err, c) : err.message;
+			return c.json({
+				success: false,
+				error: message,
+				code: err.code,
+				...err.details === void 0 ? {} : { details: err.details }
+			}, err.status);
+		}
+		if (err instanceof HTTPException) return c.json({
+			success: false,
+			error: err.message || "Request failed",
+			code: "HTTP_ERROR"
+		}, err.status);
+		c.get("logger").error({ err }, "unhandled error");
+		return c.json({
+			success: false,
+			error: "Something went wrong",
+			code: "INTERNAL_ERROR"
+		}, 500);
+	});
+	app.notFound((c) => c.json({
+		success: false,
+		error: "Route not found",
+		code: "NOT_FOUND"
+	}, 404));
+}
+//#endregion
+//#region src/response.ts
+const errorSchema = z.object({
+	success: z.literal(false),
+	error: z.string(),
+	code: z.string(),
+	details: z.unknown().optional()
+}).openapi("Error");
+const paginationMetaSchema = z.object({
+	page: z.number().int(),
+	pageSize: z.number().int(),
+	total: z.number().int(),
+	totalPages: z.number().int()
+}).openapi("PaginationMeta");
+const paginationQuerySchema = z.object({
+	page: z.coerce.number().int().min(1).default(1),
+	pageSize: z.coerce.number().int().min(1).max(100).default(20)
+});
+function successSchema(data) {
+	return z.object({
+		success: z.literal(true),
+		data
+	});
+}
+function paginatedSchema(item) {
+	return z.object({
+		success: z.literal(true),
+		data: z.array(item),
+		meta: paginationMetaSchema
+	});
+}
+function success(data) {
+	return {
+		success: true,
+		data
+	};
+}
+function paginated(data, page, pageSize, total) {
+	return {
+		success: true,
+		data,
+		meta: {
+			page,
+			pageSize,
+			total,
+			totalPages: Math.max(1, Math.ceil(total / pageSize))
+		}
+	};
+}
+function jsonContent(schema, description) {
+	return {
+		content: { "application/json": { schema } },
+		description
+	};
+}
+/** A required JSON request body. Without `required`, a request with no body skips validation. */
+function jsonBody(schema, description) {
+	return {
+		...jsonContent(schema, description),
+		required: true
+	};
+}
+const ERROR_DESCRIPTIONS = {
+	400: "Invalid request",
+	401: "Authentication required",
+	403: "Forbidden",
+	404: "Not found",
+	409: "Conflict"
+};
+/** OpenAPI error responses for the given statuses, all using the shared error envelope. */
+function errorResponses(...statuses) {
+	return Object.fromEntries(statuses.map((status) => [status, jsonContent(errorSchema, ERROR_DESCRIPTIONS[status])]));
+}
+//#endregion
+//#region src/server.ts
+/** Starts an HTTP app; on shutdown stops accepting connections and drains in-flight requests. */
+function startServer(app, options) {
+	const { port, name, logger } = options;
+	const server = serve({
+		fetch: app.fetch,
+		port
+	}, (info) => {
+		logger.info({
+			port: info.port,
+			app: name
+		}, `${name} listening on http://localhost:${info.port}`);
+	});
+	onShutdown(`${name}-http`, () => new Promise((resolve) => server.close(() => resolve())));
+	handleSignals(logger);
+	return server;
+}
+//#endregion
+export { AppError, BusinessRuleError, ConflictError, ForbiddenError, NotFoundError, UnauthorizedError, ValidationError, createApp, createRouter, defineRoutes, errorResponses, errorSchema, handleErrors, jsonBody, jsonContent, mountRoutes, paginated, paginatedSchema, paginationMetaSchema, paginationQuerySchema, requestContext, serveOpenApi, startServer, success, successSchema, validationHook };

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@tatara/http",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "tatara HTTP: Hono app setup, errors, envelope, OpenAPI docs and route mounting",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "peerDependencies": {
+    "hono": "^4.13.13",
+    "@hono/zod-openapi": "^1.6.3",
+    "@hono/node-server": "^2.1.5",
+    "@scalar/hono-api-reference": "^0.12.12",
+    "@tatara/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "hono": "^4.13.13",
+    "@hono/zod-openapi": "^1.6.3",
+    "@hono/node-server": "^2.1.5",
+    "@scalar/hono-api-reference": "^0.12.12",
+    "@tatara/core": "^0.1.0",
+    "pino": "^10.4.0",
+    "zod": "^4.6.7"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mohammed-bageri/tatara-cli.git",
+    "directory": "packages/http"
+  },
+  "homepage": "https://github.com/mohammed-bageri/tatara-cli#readme",
+  "bugs": {
+    "url": "https://github.com/mohammed-bageri/tatara-cli/issues"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  }
 }