katanakit-js 6.4.3 → 6.7.1

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.
Files changed (93) hide show
  1. package/README.md +4 -3
  2. package/dist/adapters/express/server.d.ts +133 -1
  3. package/dist/adapters/express/server.d.ts.map +1 -1
  4. package/dist/adapters/express/server.js +199 -97
  5. package/dist/adapters/express/server.js.map +1 -1
  6. package/dist/adapters/insforge/insforge.service.d.ts +139 -4
  7. package/dist/adapters/insforge/insforge.service.d.ts.map +1 -1
  8. package/dist/adapters/insforge/insforge.service.js +383 -213
  9. package/dist/adapters/insforge/insforge.service.js.map +1 -1
  10. package/dist/adapters/notion/notion.service.d.ts +130 -144
  11. package/dist/adapters/notion/notion.service.d.ts.map +1 -1
  12. package/dist/adapters/notion/notion.service.js +330 -341
  13. package/dist/adapters/notion/notion.service.js.map +1 -1
  14. package/dist/adapters/telegram/telegram.service.d.ts +82 -13
  15. package/dist/adapters/telegram/telegram.service.d.ts.map +1 -1
  16. package/dist/adapters/telegram/telegram.service.js +133 -55
  17. package/dist/adapters/telegram/telegram.service.js.map +1 -1
  18. package/dist/adapters/wordpress/wordpress.service.d.ts +181 -110
  19. package/dist/adapters/wordpress/wordpress.service.d.ts.map +1 -1
  20. package/dist/adapters/wordpress/wordpress.service.js +556 -465
  21. package/dist/adapters/wordpress/wordpress.service.js.map +1 -1
  22. package/dist/core/services/access.service.d.ts +167 -4
  23. package/dist/core/services/access.service.d.ts.map +1 -1
  24. package/dist/core/services/access.service.js +241 -31
  25. package/dist/core/services/access.service.js.map +1 -1
  26. package/dist/core/services/agent.service.d.ts +182 -27
  27. package/dist/core/services/agent.service.d.ts.map +1 -1
  28. package/dist/core/services/agent.service.js +296 -164
  29. package/dist/core/services/agent.service.js.map +1 -1
  30. package/dist/core/services/assistant.service.d.ts +96 -5
  31. package/dist/core/services/assistant.service.d.ts.map +1 -1
  32. package/dist/core/services/assistant.service.js +171 -66
  33. package/dist/core/services/assistant.service.js.map +1 -1
  34. package/dist/core/services/dates.service.d.ts +183 -11
  35. package/dist/core/services/dates.service.d.ts.map +1 -1
  36. package/dist/core/services/dates.service.js +256 -57
  37. package/dist/core/services/dates.service.js.map +1 -1
  38. package/dist/core/services/http.service.d.ts +172 -133
  39. package/dist/core/services/http.service.d.ts.map +1 -1
  40. package/dist/core/services/http.service.js +381 -310
  41. package/dist/core/services/http.service.js.map +1 -1
  42. package/dist/core/services/logger.service.d.ts +96 -34
  43. package/dist/core/services/logger.service.d.ts.map +1 -1
  44. package/dist/core/services/logger.service.js +128 -41
  45. package/dist/core/services/logger.service.js.map +1 -1
  46. package/dist/core/services/query.service.d.ts +101 -0
  47. package/dist/core/services/query.service.d.ts.map +1 -1
  48. package/dist/core/services/query.service.js +131 -14
  49. package/dist/core/services/query.service.js.map +1 -1
  50. package/dist/core/services/utils.service.d.ts +286 -131
  51. package/dist/core/services/utils.service.d.ts.map +1 -1
  52. package/dist/core/services/utils.service.js +417 -227
  53. package/dist/core/services/utils.service.js.map +1 -1
  54. package/dist/core/services/validation.service.d.ts +48 -3
  55. package/dist/core/services/validation.service.d.ts.map +1 -1
  56. package/dist/core/services/validation.service.js +75 -23
  57. package/dist/core/services/validation.service.js.map +1 -1
  58. package/dist/infrastructure/decorators/cache.decorator.d.ts +53 -0
  59. package/dist/infrastructure/decorators/cache.decorator.d.ts.map +1 -0
  60. package/dist/infrastructure/decorators/cache.decorator.js +47 -0
  61. package/dist/infrastructure/decorators/cache.decorator.js.map +1 -0
  62. package/dist/infrastructure/decorators/index.d.ts +4 -0
  63. package/dist/infrastructure/decorators/index.d.ts.map +1 -0
  64. package/dist/infrastructure/decorators/index.js +4 -0
  65. package/dist/infrastructure/decorators/index.js.map +1 -0
  66. package/dist/infrastructure/decorators/logger.decorator.d.ts +38 -0
  67. package/dist/infrastructure/decorators/logger.decorator.d.ts.map +1 -0
  68. package/dist/infrastructure/decorators/logger.decorator.js +66 -0
  69. package/dist/infrastructure/decorators/logger.decorator.js.map +1 -0
  70. package/dist/infrastructure/decorators/retry.decorator.d.ts +37 -0
  71. package/dist/infrastructure/decorators/retry.decorator.d.ts.map +1 -0
  72. package/dist/infrastructure/decorators/retry.decorator.js +54 -0
  73. package/dist/infrastructure/decorators/retry.decorator.js.map +1 -0
  74. package/dist/infrastructure/dom/dom.service.d.ts +11 -5
  75. package/dist/infrastructure/dom/dom.service.d.ts.map +1 -1
  76. package/dist/infrastructure/dom/dom.service.js +20 -6
  77. package/dist/infrastructure/dom/dom.service.js.map +1 -1
  78. package/dist/infrastructure/index.d.ts +1 -0
  79. package/dist/infrastructure/index.d.ts.map +1 -1
  80. package/dist/infrastructure/index.js +1 -0
  81. package/dist/infrastructure/index.js.map +1 -1
  82. package/dist/prisma/schema.json +17 -13
  83. package/dist/styles.css +2 -0
  84. package/package.json +32 -38
  85. package/scss/_flags.scss +179 -0
  86. package/scss/_functions.scss +168 -0
  87. package/scss/_mixins.scss +658 -0
  88. package/scss/_reset.scss +275 -0
  89. package/scss/_utilities.scss +449 -0
  90. package/scss/_variables.scss +539 -0
  91. package/scss/components/_index.scss +50 -0
  92. package/scss/demo.scss +12 -0
  93. package/scss/main.scss +56 -0
package/README.md CHANGED
@@ -29,7 +29,7 @@ In the browser, use jsDelivr **`/+esm`** so named exports and dependencies resol
29
29
  | **esm.sh** | `https://esm.sh/katanakit-js` |
30
30
  | **Raw ESM file** | `https://cdn.jsdelivr.net/npm/katanakit-js/dist/index.js` (needs bundler or import map) |
31
31
 
32
- Pin a version in production (e.g. `@6.4.3/+esm`). There is no IIFE/UMD build.
32
+ Pin a version in production (e.g. `@6.7.1/+esm`). There is no IIFE/UMD build.
33
33
 
34
34
  ## Quick Start
35
35
 
@@ -361,11 +361,12 @@ const stop = useKatanaWatch(newProduct, () => checkValidations(), { deep: true }
361
361
  - **Zod validation everywhere** — `types/` is the single source of truth, inferred from Zod schemas via `z.infer`; `useValidate()` turns any schema into a Safe Result and API adapters validate every response at the boundary
362
362
  - **Zero side effects** — importing any module is safe. No `fetch` calls, no `console.log`, no storage writes
363
363
  - **Hexagonal architecture** — pure core, infrastructure adapters, framework adapters
364
- - **Tree-shakeable** — destructured re-exports from Singleton facades
364
+ - **Design patterns** — services are Singleton classes (`getInstance()`) with swappable Strategy implementations (`AccessService`, `AgentService`), a `QueryClientFactory` for per-request SSR clients, and composable Decorators exported from the main barrel: `RetryDecorator`, `CacheDecorator` (TTL memoization) and `LoggerDecorator` (timing traces)
365
+ - **Tree-shakeable** — stable `use*` wrapper functions over the Singleton facades
365
366
  - **SSR-safe** — all infrastructure adapters guard or fall back gracefully in server environments
366
367
  - **Filesystem (Node/Bun)** — `useReadFile`, `useWriteFile`, `useReadJsonFile`, `useReadModuleJson`, `useHashFile` and friends return Safe Results with native errno codes, loaded lazily through dynamic `import()` and guarded by `useIsNode()`
367
368
  - **Fake data (optional)** — `useFakeVehicle`, `useFakeEmail`, `useFakeList`, … via an optional, lazy-loaded `@faker-js/faker` peer
368
- - **Katana UI** — framework-agnostic component foundations (`useButton`, `useInput`, `useCard`, `useBadge`, `useAlert`) live in the private `@katanakit/ui` workspace, styled with `katanakit-css` (see [UI Kit](https://docs.senseikatana.com/ui-kit/))
369
+ - **Katana UI** — framework-agnostic component foundations (`useButton`, `useInput`, `useCard`, `useBadge`, `useAlert`) live in the private `@katanakit/ui` workspace, styled with the SCSS framework vendored in `katanakit-js` (see [UI Kit](https://docs.senseikatana.com/ui-kit/))
369
370
 
370
371
  ## Filesystem (Node/Bun)
371
372
 
@@ -1,4 +1,136 @@
1
1
  import { type Application, type Request } from "express";
2
+ /**
3
+ * ExpressService - Singleton para el servidor Express.
4
+ *
5
+ * Aplica el patrón Singleton: una única instancia centraliza la creación,
6
+ * configuración de middlewares, rutas, manejo de errores y ciclo de vida del
7
+ * servidor HTTP (start/stop). Idempotente: crear, finalizar y arrancar son
8
+ * operaciones seguras de repetir.
9
+ *
10
+ * @example
11
+ * ```ts
12
+ * const app = ExpressService.getInstance().useCreate();
13
+ * app.use("/assistant", useCreateAssistantRouter());
14
+ * ExpressService.getInstance().useStart(3000, "localhost");
15
+ * ```
16
+ */
17
+ export declare class ExpressService {
18
+ private static instance;
19
+ /** Express application instance. */
20
+ private app;
21
+ /** Whether the HTTP server has been started. */
22
+ private started;
23
+ /** Whether the error handler / 404 catch-all has been registered. */
24
+ private finalized;
25
+ /**
26
+ * Constructor privado - enforce singleton.
27
+ */
28
+ private constructor();
29
+ /**
30
+ * Obtiene la instancia única del ExpressService (Singleton).
31
+ *
32
+ * @returns La instancia única de {@link ExpressService}.
33
+ */
34
+ static getInstance(): ExpressService;
35
+ /**
36
+ * Returns the raw request body buffer captured by the JSON parser, if any.
37
+ * Needed to verify webhook signatures (e.g. `X-Hub-Signature-256`).
38
+ *
39
+ * @param request - The Express request.
40
+ * @returns The raw body buffer, or `undefined` when not available.
41
+ */
42
+ useGetRawBody(request: Request): Buffer | undefined;
43
+ /**
44
+ * Set up CORS, JSON body parser and URL-encoded middleware.
45
+ * The JSON parser also captures the raw body for signature verification.
46
+ *
47
+ * @param expressApp - Express application instance
48
+ *
49
+ * @example
50
+ * ```ts
51
+ * const expressApp = express();
52
+ * useExpressSetupMiddlewares(expressApp);
53
+ * ```
54
+ */
55
+ private useSetupMiddlewares;
56
+ /**
57
+ * Set up health check and application routes.
58
+ *
59
+ * @param expressApp - Express application instance
60
+ *
61
+ * @example
62
+ * ```ts
63
+ * useExpressSetupRoutes(expressApp);
64
+ * // GET /health returns { status: "ok", timestamp: "..." }
65
+ * ```
66
+ */
67
+ private useSetupRoutes;
68
+ /**
69
+ * Set up global error handling and 404 fallback. Register this AFTER all
70
+ * channel routers are mounted so it does not shadow them.
71
+ *
72
+ * @param expressApp - Express application instance
73
+ *
74
+ * @example
75
+ * ```ts
76
+ * useExpressSetupErrorHandling(expressApp);
77
+ * // Unhandled errors return 500, unknown routes return 404
78
+ * ```
79
+ */
80
+ private useSetupErrorHandling;
81
+ /**
82
+ * Create and configure the Express application. Mount channel routers on the
83
+ * returned app BEFORE calling {@link useFinalize} / {@link useStart},
84
+ * otherwise the 404 catch-all will shadow them.
85
+ *
86
+ * @returns Configured Express Application instance
87
+ *
88
+ * @example
89
+ * ```ts
90
+ * const expressApp = ExpressService.getInstance().useCreate();
91
+ * expressApp.use("/assistant", useCreateAssistantRouter());
92
+ * ```
93
+ */
94
+ useCreate(): Application;
95
+ /**
96
+ * Registers the error handler and 404 catch-all. Idempotent. Call this after
97
+ * mounting every channel router so it runs last. {@link useStart}
98
+ * invokes it automatically.
99
+ *
100
+ * @example
101
+ * ```ts
102
+ * ExpressService.getInstance().useGetApp().use("/assistant", useCreateAssistantRouter());
103
+ * ExpressService.getInstance().useFinalize();
104
+ * ```
105
+ */
106
+ useFinalize(): void;
107
+ /**
108
+ * Start the Express HTTP server. Idempotent - subsequent calls are no-ops.
109
+ * Finalizes error handling before listening.
110
+ *
111
+ * @param port - Port to listen on (default: 3000)
112
+ * @param host - Host to bind to (default: "localhost")
113
+ *
114
+ * @example
115
+ * ```ts
116
+ * ExpressService.getInstance().useStart(3000, "localhost");
117
+ * // Server running on http://localhost:3000
118
+ * ```
119
+ */
120
+ useStart(port?: number, host?: string): void;
121
+ /**
122
+ * Get the Express application instance. Creates it if it doesn't exist.
123
+ *
124
+ * @returns Express Application instance
125
+ *
126
+ * @example
127
+ * ```ts
128
+ * const expressApp = ExpressService.getInstance().useGetApp();
129
+ * expressApp.get("/custom", (req, res) => res.json({ ok: true }));
130
+ * ```
131
+ */
132
+ useGetApp(): Application;
133
+ }
2
134
  /**
3
135
  * Returns the raw request body buffer captured by the JSON parser, if any.
4
136
  * Needed to verify webhook signatures (e.g. `X-Hub-Signature-256`).
@@ -35,7 +167,7 @@ export declare const useExpressCreate: () => Application;
35
167
  */
36
168
  export declare const useExpressFinalize: () => void;
37
169
  /**
38
- * Start the Express HTTP server. Idempotent — subsequent calls are no-ops.
170
+ * Start the Express HTTP server. Idempotent - subsequent calls are no-ops.
39
171
  * Finalizes error handling before listening.
40
172
  *
41
173
  * @param port - Port to listen on (default: 3000)
@@ -1 +1 @@
1
- {"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/adapters/express/server.ts"],"names":[],"mappings":"AAGA,OAAgB,EAAE,KAAK,WAAW,EAAqB,KAAK,OAAO,EAAiB,MAAM,SAAS,CAAC;AAapG;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAElE;AAkFD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB,QAAO,WAQnC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,QAAO,IAIrC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe,GAAI,aAAW,EAAE,aAAkB,KAAG,IAUjE,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,QAAO,WAAiC,CAAC"}
1
+ {"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/adapters/express/server.ts"],"names":[],"mappings":"AAGA,OAAgB,EAAE,KAAK,WAAW,EAAqB,KAAK,OAAO,EAAiB,MAAM,SAAS,CAAC;AAQpG;;;;;;;;;;;;;;GAcG;AACH,qBAAa,cAAc;IAC1B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAiB;IAExC,oCAAoC;IACpC,OAAO,CAAC,GAAG,CAA4B;IACvC,gDAAgD;IAChD,OAAO,CAAC,OAAO,CAAS;IACxB,qEAAqE;IACrE,OAAO,CAAC,SAAS,CAAS;IAE1B;;OAEG;IACH,OAAO;IAEP;;;;OAIG;IACH,MAAM,CAAC,WAAW,IAAI,cAAc;IAOpC;;;;;;OAMG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS;IAInD;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,mBAAmB;IAuB3B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,cAAc;IAWtB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,qBAAqB;IAW7B;;;;;;;;;;;;OAYG;IACH,SAAS,IAAI,WAAW;IAUxB;;;;;;;;;;OAUG;IACH,WAAW,IAAI,IAAI;IAMnB;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,IAAI,SAAO,EAAE,IAAI,SAAc,GAAG,IAAI;IAY/C;;;;;;;;;;OAUG;IACH,SAAS,IAAI,WAAW;CAGxB;AAMD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAElE;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB,QAAO,WAAuD,CAAC;AAE5F;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,QAAO,IAAkD,CAAC;AAEzF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe,GAAI,aAAW,EAAE,aAAkB,KAAG,IAChB,CAAC;AAEnD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,QAAO,WAAuD,CAAC"}
@@ -2,89 +2,212 @@ import cors from "cors";
2
2
  import express from "express";
3
3
  import { useLogger } from "../../core/services/logger.service.js";
4
4
  import router from "./router.js";
5
- /** Module-level state for the Express server. */
6
- let app = null;
7
- let started = false;
8
- let finalized = false;
9
5
  /**
10
- * Returns the raw request body buffer captured by the JSON parser, if any.
11
- * Needed to verify webhook signatures (e.g. `X-Hub-Signature-256`).
6
+ * ExpressService - Singleton para el servidor Express.
12
7
  *
13
- * @param request - The Express request.
14
- * @returns The raw body buffer, or `undefined` when not available.
15
- */
16
- export function useGetRawBody(request) {
17
- return request.rawBody;
18
- }
19
- /**
20
- * Set up CORS, JSON body parser and URL-encoded middleware.
21
- * The JSON parser also captures the raw body for signature verification.
22
- *
23
- * @param expressApp - Express application instance
8
+ * Aplica el patrón Singleton: una única instancia centraliza la creación,
9
+ * configuración de middlewares, rutas, manejo de errores y ciclo de vida del
10
+ * servidor HTTP (start/stop). Idempotente: crear, finalizar y arrancar son
11
+ * operaciones seguras de repetir.
24
12
  *
25
13
  * @example
26
14
  * ```ts
27
- * const expressApp = express();
28
- * useExpressSetupMiddlewares(expressApp);
15
+ * const app = ExpressService.getInstance().useCreate();
16
+ * app.use("/assistant", useCreateAssistantRouter());
17
+ * ExpressService.getInstance().useStart(3000, "localhost");
29
18
  * ```
30
19
  */
31
- function useExpressSetupMiddlewares(expressApp) {
32
- const origins = (process.env.CORS_ORIGINS?.split(",") ?? ["http://localhost:3000"])
33
- .map((origin) => origin.trim())
34
- .filter(Boolean);
35
- expressApp.use(cors({
36
- origin: origins,
37
- methods: ["GET", "POST", "PUT", "DELETE"],
38
- }));
39
- expressApp.disable("x-powered-by");
40
- expressApp.use(express.json({
41
- limit: "100kb",
42
- verify: (req, _res, buf) => {
43
- req.rawBody = buf;
44
- },
45
- }));
46
- expressApp.use(express.urlencoded({ extended: true, limit: "100kb" }));
47
- }
48
- /**
49
- * Set up health check and application routes.
50
- *
51
- * @param expressApp - Express application instance
52
- *
53
- * @example
54
- * ```ts
55
- * useExpressSetupRoutes(expressApp);
56
- * // GET /health returns { status: "ok", timestamp: "..." }
57
- * ```
58
- */
59
- function useExpressSetupRoutes(expressApp) {
60
- expressApp.get("/health", (_request, response) => {
61
- return response.json({
62
- status: "ok",
63
- timestamp: new Date().toISOString(),
20
+ export class ExpressService {
21
+ static instance;
22
+ /** Express application instance. */
23
+ app = null;
24
+ /** Whether the HTTP server has been started. */
25
+ started = false;
26
+ /** Whether the error handler / 404 catch-all has been registered. */
27
+ finalized = false;
28
+ /**
29
+ * Constructor privado - enforce singleton.
30
+ */
31
+ constructor() { }
32
+ /**
33
+ * Obtiene la instancia única del ExpressService (Singleton).
34
+ *
35
+ * @returns La instancia única de {@link ExpressService}.
36
+ */
37
+ static getInstance() {
38
+ if (!ExpressService.instance) {
39
+ ExpressService.instance = new ExpressService();
40
+ }
41
+ return ExpressService.instance;
42
+ }
43
+ /**
44
+ * Returns the raw request body buffer captured by the JSON parser, if any.
45
+ * Needed to verify webhook signatures (e.g. `X-Hub-Signature-256`).
46
+ *
47
+ * @param request - The Express request.
48
+ * @returns The raw body buffer, or `undefined` when not available.
49
+ */
50
+ useGetRawBody(request) {
51
+ return request.rawBody;
52
+ }
53
+ /**
54
+ * Set up CORS, JSON body parser and URL-encoded middleware.
55
+ * The JSON parser also captures the raw body for signature verification.
56
+ *
57
+ * @param expressApp - Express application instance
58
+ *
59
+ * @example
60
+ * ```ts
61
+ * const expressApp = express();
62
+ * useExpressSetupMiddlewares(expressApp);
63
+ * ```
64
+ */
65
+ useSetupMiddlewares(expressApp) {
66
+ const origins = (process.env.CORS_ORIGINS?.split(",") ?? ["http://localhost:3000"])
67
+ .map((origin) => origin.trim())
68
+ .filter(Boolean);
69
+ expressApp.use(cors({
70
+ origin: origins,
71
+ methods: ["GET", "POST", "PUT", "DELETE"],
72
+ }));
73
+ expressApp.disable("x-powered-by");
74
+ expressApp.use(express.json({
75
+ limit: "100kb",
76
+ verify: (req, _res, buf) => {
77
+ req.rawBody = buf;
78
+ },
79
+ }));
80
+ expressApp.use(express.urlencoded({ extended: true, limit: "100kb" }));
81
+ }
82
+ /**
83
+ * Set up health check and application routes.
84
+ *
85
+ * @param expressApp - Express application instance
86
+ *
87
+ * @example
88
+ * ```ts
89
+ * useExpressSetupRoutes(expressApp);
90
+ * // GET /health returns { status: "ok", timestamp: "..." }
91
+ * ```
92
+ */
93
+ useSetupRoutes(expressApp) {
94
+ expressApp.get("/health", (_request, response) => {
95
+ return response.json({
96
+ status: "ok",
97
+ timestamp: new Date().toISOString(),
98
+ });
99
+ });
100
+ expressApp.use("/", router);
101
+ }
102
+ /**
103
+ * Set up global error handling and 404 fallback. Register this AFTER all
104
+ * channel routers are mounted so it does not shadow them.
105
+ *
106
+ * @param expressApp - Express application instance
107
+ *
108
+ * @example
109
+ * ```ts
110
+ * useExpressSetupErrorHandling(expressApp);
111
+ * // Unhandled errors return 500, unknown routes return 404
112
+ * ```
113
+ */
114
+ useSetupErrorHandling(expressApp) {
115
+ expressApp.use((err, _req, res, _next) => {
116
+ useLogger("Unhandled error:", err, "error");
117
+ res.status(500).json({ error: "Internal Server Error" });
118
+ });
119
+ expressApp.use((_req, res) => {
120
+ res.status(404).json({ error: "Not Found" });
64
121
  });
65
- });
66
- expressApp.use("/", router);
122
+ }
123
+ /**
124
+ * Create and configure the Express application. Mount channel routers on the
125
+ * returned app BEFORE calling {@link useFinalize} / {@link useStart},
126
+ * otherwise the 404 catch-all will shadow them.
127
+ *
128
+ * @returns Configured Express Application instance
129
+ *
130
+ * @example
131
+ * ```ts
132
+ * const expressApp = ExpressService.getInstance().useCreate();
133
+ * expressApp.use("/assistant", useCreateAssistantRouter());
134
+ * ```
135
+ */
136
+ useCreate() {
137
+ if (this.app)
138
+ return this.app;
139
+ this.app = express();
140
+ this.useSetupMiddlewares(this.app);
141
+ this.useSetupRoutes(this.app);
142
+ return this.app;
143
+ }
144
+ /**
145
+ * Registers the error handler and 404 catch-all. Idempotent. Call this after
146
+ * mounting every channel router so it runs last. {@link useStart}
147
+ * invokes it automatically.
148
+ *
149
+ * @example
150
+ * ```ts
151
+ * ExpressService.getInstance().useGetApp().use("/assistant", useCreateAssistantRouter());
152
+ * ExpressService.getInstance().useFinalize();
153
+ * ```
154
+ */
155
+ useFinalize() {
156
+ if (this.finalized)
157
+ return;
158
+ this.finalized = true;
159
+ this.useSetupErrorHandling(this.useCreate());
160
+ }
161
+ /**
162
+ * Start the Express HTTP server. Idempotent - subsequent calls are no-ops.
163
+ * Finalizes error handling before listening.
164
+ *
165
+ * @param port - Port to listen on (default: 3000)
166
+ * @param host - Host to bind to (default: "localhost")
167
+ *
168
+ * @example
169
+ * ```ts
170
+ * ExpressService.getInstance().useStart(3000, "localhost");
171
+ * // Server running on http://localhost:3000
172
+ * ```
173
+ */
174
+ useStart(port = 3000, host = "localhost") {
175
+ if (this.started)
176
+ return;
177
+ this.started = true;
178
+ this.useFinalize();
179
+ const expressApp = this.useCreate();
180
+ expressApp.listen(port, host, () => {
181
+ useLogger(`Server running on http://${host}:${port}`);
182
+ });
183
+ }
184
+ /**
185
+ * Get the Express application instance. Creates it if it doesn't exist.
186
+ *
187
+ * @returns Express Application instance
188
+ *
189
+ * @example
190
+ * ```ts
191
+ * const expressApp = ExpressService.getInstance().useGetApp();
192
+ * expressApp.get("/custom", (req, res) => res.json({ ok: true }));
193
+ * ```
194
+ */
195
+ useGetApp() {
196
+ return this.useCreate();
197
+ }
67
198
  }
199
+ /* -------------------------------------------------------------------------- */
200
+ /* Wrappers (backward compatibility) */
201
+ /* -------------------------------------------------------------------------- */
68
202
  /**
69
- * Set up global error handling and 404 fallback. Register this AFTER all
70
- * channel routers are mounted so it does not shadow them.
71
- *
72
- * @param expressApp - Express application instance
203
+ * Returns the raw request body buffer captured by the JSON parser, if any.
204
+ * Needed to verify webhook signatures (e.g. `X-Hub-Signature-256`).
73
205
  *
74
- * @example
75
- * ```ts
76
- * useExpressSetupErrorHandling(expressApp);
77
- * // Unhandled errors return 500, unknown routes return 404
78
- * ```
206
+ * @param request - The Express request.
207
+ * @returns The raw body buffer, or `undefined` when not available.
79
208
  */
80
- function useExpressSetupErrorHandling(expressApp) {
81
- expressApp.use((err, _req, res, _next) => {
82
- useLogger("Unhandled error:", err, "error");
83
- res.status(500).json({ error: "Internal Server Error" });
84
- });
85
- expressApp.use((_req, res) => {
86
- res.status(404).json({ error: "Not Found" });
87
- });
209
+ export function useGetRawBody(request) {
210
+ return ExpressService.getInstance().useGetRawBody(request);
88
211
  }
89
212
  /**
90
213
  * Create and configure the Express application. Mount channel routers on the
@@ -100,14 +223,7 @@ function useExpressSetupErrorHandling(expressApp) {
100
223
  * useExpressStart();
101
224
  * ```
102
225
  */
103
- export const useExpressCreate = () => {
104
- if (app)
105
- return app;
106
- app = express();
107
- useExpressSetupMiddlewares(app);
108
- useExpressSetupRoutes(app);
109
- return app;
110
- };
226
+ export const useExpressCreate = () => ExpressService.getInstance().useCreate();
111
227
  /**
112
228
  * Registers the error handler and 404 catch-all. Idempotent. Call this after
113
229
  * mounting every channel router so it runs last. {@link useExpressStart}
@@ -119,14 +235,9 @@ export const useExpressCreate = () => {
119
235
  * useExpressFinalize();
120
236
  * ```
121
237
  */
122
- export const useExpressFinalize = () => {
123
- if (finalized)
124
- return;
125
- finalized = true;
126
- useExpressSetupErrorHandling(useExpressCreate());
127
- };
238
+ export const useExpressFinalize = () => ExpressService.getInstance().useFinalize();
128
239
  /**
129
- * Start the Express HTTP server. Idempotent — subsequent calls are no-ops.
240
+ * Start the Express HTTP server. Idempotent - subsequent calls are no-ops.
130
241
  * Finalizes error handling before listening.
131
242
  *
132
243
  * @param port - Port to listen on (default: 3000)
@@ -138,16 +249,7 @@ export const useExpressFinalize = () => {
138
249
  * // Server running on http://localhost:3000
139
250
  * ```
140
251
  */
141
- export const useExpressStart = (port = 3000, host = "localhost") => {
142
- if (started)
143
- return;
144
- started = true;
145
- useExpressFinalize();
146
- const expressApp = useExpressCreate();
147
- expressApp.listen(port, host, () => {
148
- useLogger(`Server running on http://${host}:${port}`);
149
- });
150
- };
252
+ export const useExpressStart = (port = 3000, host = "localhost") => ExpressService.getInstance().useStart(port, host);
151
253
  /**
152
254
  * Get the Express application instance. Creates it if it doesn't exist.
153
255
  *
@@ -159,5 +261,5 @@ export const useExpressStart = (port = 3000, host = "localhost") => {
159
261
  * expressApp.get("/custom", (req, res) => res.json({ ok: true }));
160
262
  * ```
161
263
  */
162
- export const useExpressGetApp = () => useExpressCreate();
264
+ export const useExpressGetApp = () => ExpressService.getInstance().useGetApp();
163
265
  //# sourceMappingURL=server.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"server.js","sourceRoot":"","sources":["../../../src/adapters/express/server.ts"],"names":[],"mappings":"AAEA,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,OAA6E,MAAM,SAAS,CAAC;AAEpG,OAAO,EAAE,SAAS,EAAE,MAAM,uCAAuC,CAAC;AAClE,OAAO,MAAM,MAAM,aAAa,CAAC;AAEjC,iDAAiD;AACjD,IAAI,GAAG,GAAuB,IAAI,CAAC;AACnC,IAAI,OAAO,GAAG,KAAK,CAAC;AACpB,IAAI,SAAS,GAAG,KAAK,CAAC;AAKtB;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC7C,OAAQ,OAAyC,CAAC,OAAO,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAS,0BAA0B,CAAC,UAAuB;IAC1D,MAAM,OAAO,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;SACjF,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;SAC9B,MAAM,CAAC,OAAO,CAAC,CAAC;IAElB,UAAU,CAAC,GAAG,CACb,IAAI,CAAC;QACJ,MAAM,EAAE,OAAO;QACf,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC;KACzC,CAAC,CACF,CAAC;IACF,UAAU,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IACnC,UAAU,CAAC,GAAG,CACb,OAAO,CAAC,IAAI,CAAC;QACZ,KAAK,EAAE,OAAO;QACd,MAAM,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;YACzB,GAA0B,CAAC,OAAO,GAAG,GAAG,CAAC;QAC3C,CAAC;KACD,CAAC,CACF,CAAC;IACF,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;AACxE,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,qBAAqB,CAAC,UAAuB;IACrD,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,QAAiB,EAAE,QAAkB,EAAE,EAAE;QACnE,OAAO,QAAQ,CAAC,IAAI,CAAC;YACpB,MAAM,EAAE,IAAI;YACZ,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACnC,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAS,4BAA4B,CAAC,UAAuB;IAC5D,UAAU,CAAC,GAAG,CAAC,CAAC,GAAU,EAAE,IAAa,EAAE,GAAa,EAAE,KAAmB,EAAE,EAAE;QAChF,SAAS,CAAC,kBAAkB,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;QAC5C,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,uBAAuB,EAAE,CAAC,CAAC;IAC1D,CAAC,CAAC,CAAC;IAEH,UAAU,CAAC,GAAG,CAAC,CAAC,IAAa,EAAE,GAAa,EAAE,EAAE;QAC/C,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAgB,EAAE;IACjD,IAAI,GAAG;QAAE,OAAO,GAAG,CAAC;IAEpB,GAAG,GAAG,OAAO,EAAE,CAAC;IAChB,0BAA0B,CAAC,GAAG,CAAC,CAAC;IAChC,qBAAqB,CAAC,GAAG,CAAC,CAAC;IAE3B,OAAO,GAAG,CAAC;AACZ,CAAC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAS,EAAE;IAC5C,IAAI,SAAS;QAAE,OAAO;IACtB,SAAS,GAAG,IAAI,CAAC;IACjB,4BAA4B,CAAC,gBAAgB,EAAE,CAAC,CAAC;AAClD,CAAC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,IAAI,GAAG,IAAI,EAAE,IAAI,GAAG,WAAW,EAAQ,EAAE;IACxE,IAAI,OAAO;QAAE,OAAO;IACpB,OAAO,GAAG,IAAI,CAAC;IAEf,kBAAkB,EAAE,CAAC;IACrB,MAAM,UAAU,GAAG,gBAAgB,EAAE,CAAC;IAEtC,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE;QAClC,SAAS,CAAC,4BAA4B,IAAI,IAAI,IAAI,EAAE,CAAC,CAAC;IACvD,CAAC,CAAC,CAAC;AACJ,CAAC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAgB,EAAE,CAAC,gBAAgB,EAAE,CAAC"}
1
+ {"version":3,"file":"server.js","sourceRoot":"","sources":["../../../src/adapters/express/server.ts"],"names":[],"mappings":"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"}