@wthek/koa-middleware 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -9,12 +9,13 @@ _Built for applications powered by [http-error-kit][http-error-kit], this middle
9
9
  ![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/skillnter/wthek-koa-middleware/main.yml)
10
10
  [![npm version](https://img.shields.io/npm/v/%40wthek%2Fkoa-middleware?color=brightgreen)](https://www.npmjs.com/package/@wthek/koa-middleware)
11
11
  [![GitHub license](https://img.shields.io/github/license/skillnter/wthek-koa-middleware?color=brightgreen)](LICENSE)
12
+ ![NPM Type Definitions](https://img.shields.io/npm/types/%40wthek%2Fkoa-middleware)
12
13
  [![GitHub Issues](https://img.shields.io/github/issues/Skillnter/wthek-koa-middleware)](https://github.com/Skillnter/wthek-koa-middleware/issues)
13
14
  ![npm](https://img.shields.io/npm/dy/%40wthek%2Fkoa-middleware)
14
15
  [![Bundle Size](https://img.shields.io/bundlephobia/minzip/%40wthek%2Fkoa-middleware)](https://bundlephobia.com/package/%40wthek%2Fkoa-middleware)
15
16
  [![Codacy Badge](https://app.codacy.com/project/badge/Grade/8cb84abac51c4e67b0e8c7a0730d1a40)](https://app.codacy.com/gh/Skillnter/wthek-koa-middleware/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
16
17
  [![Codacy Badge](https://app.codacy.com/project/badge/Coverage/8cb84abac51c4e67b0e8c7a0730d1a40)](https://app.codacy.com/gh/Skillnter/wthek-koa-middleware/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage)
17
- [![Socket Badge](https://socket.dev/api/badge/npm/package/@wthek/koa-middleware/1.0.0)](https://socket.dev/npm/package/@wthek/koa-middleware/overview/1.0.0)
18
+ [![Socket Badge](https://socket.dev/api/badge/npm/package/@wthek/koa-middleware/)](https://socket.dev/npm/package/@wthek/koa-middleware/overview/)
18
19
  [![Github Sponsors](https://img.shields.io/badge/GitHub%20Sponsors-30363D?&logo=GitHub-Sponsors&logoColor=EA4AAA)](https://github.com/sponsors/Skillnter)
19
20
  [![Open Collective](https://img.shields.io/badge/Open%20Collective-3385FF?logo=open-collective&logoColor=white)](https://opencollective.com/skillnter)
20
21
  [![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?&logo=buy-me-a-coffee&logoColor=black)](https://www.buymeacoffee.com/skillnter)
@@ -37,6 +38,7 @@ _Built for applications powered by [http-error-kit][http-error-kit], this middle
37
38
  - [Usage](#usage)
38
39
  - [Options](#options)
39
40
  - [Custom Formatting with KitHttpErrorConfig](#custom-formatting-with-kithttperrorconfig)
41
+ - [AI Agent Integration](#ai-agent-integration)
40
42
  - [Explore More WTHek Extensions](#explore-more-wthek-extensions)
41
43
  - [People](#people)
42
44
  - [Donations](#donations)
@@ -142,6 +144,17 @@ KitHttpErrorConfig.configureFormatter(
142
144
  );
143
145
  ```
144
146
 
147
+ ## AI Agent Integration
148
+
149
+ When building with AI coding assistants (Claude Code, Cursor, GitHub Copilot, Antigravity, Devin), add the following directive to your project's `.cursorrules`, `.github/copilot-instructions.md`, or system prompt:
150
+
151
+ ```markdown
152
+ ### Koa Error Handling Rule
153
+ - Always throw semantic error classes from `http-error-kit` (e.g., `BadRequestError`, `NotFoundError`, `UnauthorizedError`) inside downstream Koa middleware and routes.
154
+ - In Koa bootstrap, register `@wthek/koa-middleware` at the top of the middleware stack: `KitKoaMiddleware(app, { handleUnknownErrors: true })`.
155
+ - If using centralized monitoring (Sentry, Datadog), enable `emitAppError: true` so `app.on("error")` continues to receive errors.
156
+ ```
157
+
145
158
  ## Explore More WTHek Extensions
146
159
 
147
160
  The WTHek ecosystem continues to grow with new extensions to simplify error handling across various frameworks and libraries. Stay updated with the latest tools that integrate seamlessly with `http-error-kit`.
package/dist/index.d.ts CHANGED
@@ -1,6 +1,15 @@
1
1
  import type { Context, default as Koa, Middleware } from "koa";
2
2
  /**
3
3
  * Configuration options for KitKoaMiddleware.
4
+ *
5
+ * @example
6
+ * ```typescript
7
+ * const options: IKitKoaMiddlewareOptions = {
8
+ * log: true,
9
+ * handleUnknownErrors: true,
10
+ * emitAppError: true,
11
+ * };
12
+ * ```
4
13
  */
5
14
  export interface IKitKoaMiddlewareOptions {
6
15
  /**
package/llms.txt ADDED
@@ -0,0 +1,56 @@
1
+ # @wthek/koa-middleware
2
+
3
+ > Production-safe Koa error-handling middleware for `http-error-kit`.
4
+
5
+ ## Overview
6
+ `@wthek/koa-middleware` catches `KitHttpError` and `KitGeneralError` instances thrown in Koa downstream middleware and routes, automatically setting the HTTP status code and serializing the error into a structured JSON payload. It respects Koa's onion architecture, guards against header-sent errors (`ctx.headerSent`), provides configurable logging, optionally emits Koa `error` events for central telemetry, and handles unknown exceptions.
7
+
8
+ ## Installation
9
+ ```bash
10
+ npm install @wthek/koa-middleware http-error-kit http-response-status-code
11
+ ```
12
+
13
+ ## Quick Start
14
+ ```typescript
15
+ import Koa from "koa";
16
+ import { KitKoaMiddleware } from "@wthek/koa-middleware";
17
+ import { BadRequestError, NotFoundError } from "http-error-kit";
18
+
19
+ const app = new Koa();
20
+
21
+ // Pattern 1: Direct registration (app passed as first argument)
22
+ KitKoaMiddleware(app, { log: true, handleUnknownErrors: true, emitAppError: true });
23
+
24
+ // Pattern 2: Standard Koa app.use()
25
+ // app.use(KitKoaMiddleware({ log: true, handleUnknownErrors: true }));
26
+
27
+ app.use(async (ctx) => {
28
+ if (ctx.path === "/api/users") {
29
+ throw new BadRequestError("Query parameter missing");
30
+ }
31
+ throw new NotFoundError("Route not found");
32
+ });
33
+
34
+ app.listen(3000);
35
+ ```
36
+
37
+ ## API Reference
38
+
39
+ ### `KitKoaMiddleware(appOrOptions?: Koa | IKitKoaMiddlewareOptions, options?: IKitKoaMiddlewareOptions)`
40
+ Returns or registers a Koa middleware: `(ctx: Context, next: Next) => Promise<void>`.
41
+ - If a Koa app is passed as the first parameter, it calls `app.use()` automatically.
42
+ - Otherwise, returns standard middleware for `app.use(KitKoaMiddleware(options))`.
43
+
44
+ #### Options (`IKitKoaMiddlewareOptions`)
45
+ - `log` (`boolean | ((error: unknown, ctx: Context) => void)`, default: `false`):
46
+ When `true`, logs via `console.error`. When a function is provided, calls custom logger.
47
+ - `handleUnknownErrors` (`boolean`, default: `false`):
48
+ When `true`, catches non-Kit errors and assigns a structured 500 JSON response instead of re-throwing downstream.
49
+ - `emitAppError` (`boolean`, default: `false`):
50
+ When `true`, emits `ctx.app.emit("error", error, ctx)` for central error listeners (Sentry, Datadog).
51
+
52
+ ## Safety Rules for AI Agents
53
+ 1. Place `app.use(KitKoaMiddleware(...))` at the very beginning of the middleware pipeline to wrap all downstream handlers.
54
+ 2. Throw errors directly from `http-error-kit` (e.g., `throw new NotFoundError(...)`) inside downstream handlers.
55
+ 3. Koa async functions automatically catch thrown errors and return control up the onion stack.
56
+
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wthek/koa-middleware",
3
- "version": "1.0.0",
3
+ "version": "1.1.0",
4
4
  "description": "Production-safe Koa error-handling middleware for http-error-kit. Maps KitHttpError instances to structured JSON responses with correct HTTP status codes and optional logging.",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
@@ -38,6 +38,15 @@
38
38
  "status-codes",
39
39
  "api-error",
40
40
  "json-error",
41
+ "rfc-7807",
42
+ "rfc-9457",
43
+ "structured-errors",
44
+ "api-error-response",
45
+ "ai-agent",
46
+ "agent-skill",
47
+ "antigravity",
48
+ "cursor",
49
+ "copilot",
41
50
  "typescript",
42
51
  "middleware",
43
52
  "wthek",
@@ -53,8 +62,8 @@
53
62
  },
54
63
  "homepage": "https://github.com/Skillnter/wthek-koa-middleware#readme",
55
64
  "dependencies": {
56
- "http-error-kit": "^1.2.0",
57
- "http-response-status-code": "^1.8.0"
65
+ "http-error-kit": "^1.5.0",
66
+ "http-response-status-code": "^1.9.0"
58
67
  },
59
68
  "peerDependencies": {
60
69
  "koa": "^2.0.0 || ^3.0.0"
@@ -81,6 +90,7 @@
81
90
  "files": [
82
91
  "dist/index.js",
83
92
  "dist/index.d.ts",
93
+ "llms.txt",
84
94
  "LICENSE"
85
95
  ],
86
96
  "funding": [