raffel 0.1.2 → 0.2.2

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 (268) hide show
  1. package/README.md +314 -346
  2. package/dist/adapters/index.d.ts +3 -1
  3. package/dist/adapters/index.d.ts.map +1 -1
  4. package/dist/adapters/index.js +3 -1
  5. package/dist/adapters/index.js.map +1 -1
  6. package/dist/adapters/s3db/adapter.d.ts.map +1 -1
  7. package/dist/adapters/s3db/adapter.js +0 -3
  8. package/dist/adapters/s3db/adapter.js.map +1 -1
  9. package/dist/adapters/udp.d.ts +83 -0
  10. package/dist/adapters/udp.d.ts.map +1 -0
  11. package/dist/adapters/udp.int.test.d.ts +5 -0
  12. package/dist/adapters/udp.int.test.d.ts.map +1 -0
  13. package/dist/adapters/udp.int.test.js +397 -0
  14. package/dist/adapters/udp.int.test.js.map +1 -0
  15. package/dist/adapters/udp.js +391 -0
  16. package/dist/adapters/udp.js.map +1 -0
  17. package/dist/cache/drivers/file.d.ts.map +1 -1
  18. package/dist/cache/drivers/file.js +13 -1
  19. package/dist/cache/drivers/file.js.map +1 -1
  20. package/dist/cache/drivers/memory.d.ts.map +1 -1
  21. package/dist/cache/drivers/memory.js +1 -0
  22. package/dist/cache/drivers/memory.js.map +1 -1
  23. package/dist/cache/types.d.ts +1 -0
  24. package/dist/cache/types.d.ts.map +1 -1
  25. package/dist/docs/generators/http-generator.d.ts.map +1 -1
  26. package/dist/docs/generators/http-generator.js +0 -1
  27. package/dist/docs/generators/http-generator.js.map +1 -1
  28. package/dist/graphql/graphql.int.test.d.ts +10 -0
  29. package/dist/graphql/graphql.int.test.d.ts.map +1 -0
  30. package/dist/graphql/graphql.int.test.js +698 -0
  31. package/dist/graphql/graphql.int.test.js.map +1 -0
  32. package/dist/graphql/schema-generator.d.ts.map +1 -1
  33. package/dist/graphql/schema-generator.js +20 -7
  34. package/dist/graphql/schema-generator.js.map +1 -1
  35. package/dist/http/auth.d.ts.map +1 -1
  36. package/dist/http/auth.js +15 -1
  37. package/dist/http/auth.js.map +1 -1
  38. package/dist/http/http.int.test.d.ts +7 -0
  39. package/dist/http/http.int.test.d.ts.map +1 -0
  40. package/dist/http/http.int.test.js +604 -0
  41. package/dist/http/http.int.test.js.map +1 -0
  42. package/dist/http/index.d.ts +2 -0
  43. package/dist/http/index.d.ts.map +1 -1
  44. package/dist/http/index.js +2 -0
  45. package/dist/http/index.js.map +1 -1
  46. package/dist/http/oauth2.d.ts.map +1 -1
  47. package/dist/http/oauth2.js +39 -0
  48. package/dist/http/oauth2.js.map +1 -1
  49. package/dist/http/oidc.d.ts.map +1 -1
  50. package/dist/http/oidc.js +9 -1
  51. package/dist/http/oidc.js.map +1 -1
  52. package/dist/http/session-redis.d.ts +187 -0
  53. package/dist/http/session-redis.d.ts.map +1 -0
  54. package/dist/http/session-redis.int.test.d.ts +8 -0
  55. package/dist/http/session-redis.int.test.d.ts.map +1 -0
  56. package/dist/http/session-redis.int.test.js +492 -0
  57. package/dist/http/session-redis.int.test.js.map +1 -0
  58. package/dist/http/session-redis.js +320 -0
  59. package/dist/http/session-redis.js.map +1 -0
  60. package/dist/index.d.ts +2 -1
  61. package/dist/index.d.ts.map +1 -1
  62. package/dist/index.js +25 -0
  63. package/dist/index.js.map +1 -1
  64. package/dist/mcp/cli.js +2 -1
  65. package/dist/mcp/cli.js.map +1 -1
  66. package/dist/mcp/docs/adapters.d.ts.map +1 -1
  67. package/dist/mcp/docs/adapters.js +175 -145
  68. package/dist/mcp/docs/adapters.js.map +1 -1
  69. package/dist/mcp/docs/interceptors.d.ts +1 -1
  70. package/dist/mcp/docs/interceptors.d.ts.map +1 -1
  71. package/dist/mcp/docs/interceptors.js +231 -305
  72. package/dist/mcp/docs/interceptors.js.map +1 -1
  73. package/dist/mcp/docs/patterns.d.ts.map +1 -1
  74. package/dist/mcp/docs/patterns.js +20 -18
  75. package/dist/mcp/docs/patterns.js.map +1 -1
  76. package/dist/mcp/docs/quickstart.d.ts +1 -1
  77. package/dist/mcp/docs/quickstart.d.ts.map +1 -1
  78. package/dist/mcp/docs/quickstart.js +48 -46
  79. package/dist/mcp/docs/quickstart.js.map +1 -1
  80. package/dist/mcp/server.d.ts +1 -1
  81. package/dist/mcp/server.d.ts.map +1 -1
  82. package/dist/mcp/server.js +6 -7
  83. package/dist/mcp/server.js.map +1 -1
  84. package/dist/mcp/version.d.ts +7 -0
  85. package/dist/mcp/version.d.ts.map +1 -0
  86. package/dist/mcp/version.js +20 -0
  87. package/dist/mcp/version.js.map +1 -0
  88. package/dist/middleware/auth/oauth2.d.ts +294 -0
  89. package/dist/middleware/auth/oauth2.d.ts.map +1 -0
  90. package/dist/middleware/auth/oauth2.int.test.d.ts +2 -0
  91. package/dist/middleware/auth/oauth2.int.test.d.ts.map +1 -0
  92. package/dist/middleware/auth/oauth2.int.test.js +714 -0
  93. package/dist/middleware/auth/oauth2.int.test.js.map +1 -0
  94. package/dist/middleware/auth/oauth2.js +671 -0
  95. package/dist/middleware/auth/oauth2.js.map +1 -0
  96. package/dist/middleware/auth.d.ts +2 -0
  97. package/dist/middleware/auth.d.ts.map +1 -1
  98. package/dist/middleware/auth.js +16 -0
  99. package/dist/middleware/auth.js.map +1 -1
  100. package/dist/middleware/index.d.ts +5 -2
  101. package/dist/middleware/index.d.ts.map +1 -1
  102. package/dist/middleware/index.js +4 -0
  103. package/dist/middleware/index.js.map +1 -1
  104. package/dist/middleware/interceptors/circuit-breaker.d.ts.map +1 -1
  105. package/dist/middleware/interceptors/circuit-breaker.js +0 -1
  106. package/dist/middleware/interceptors/circuit-breaker.js.map +1 -1
  107. package/dist/middleware/interceptors/envelope.d.ts +176 -0
  108. package/dist/middleware/interceptors/envelope.d.ts.map +1 -0
  109. package/dist/middleware/interceptors/envelope.int.test.d.ts +5 -0
  110. package/dist/middleware/interceptors/envelope.int.test.d.ts.map +1 -0
  111. package/dist/middleware/interceptors/envelope.int.test.js +409 -0
  112. package/dist/middleware/interceptors/envelope.int.test.js.map +1 -0
  113. package/dist/middleware/interceptors/envelope.js +294 -0
  114. package/dist/middleware/interceptors/envelope.js.map +1 -0
  115. package/dist/middleware/interceptors/index.d.ts +2 -0
  116. package/dist/middleware/interceptors/index.d.ts.map +1 -1
  117. package/dist/middleware/interceptors/index.js +2 -0
  118. package/dist/middleware/interceptors/index.js.map +1 -1
  119. package/dist/middleware/types.d.ts +25 -0
  120. package/dist/middleware/types.d.ts.map +1 -1
  121. package/dist/rate-limit/drivers/drivers.int.test.d.ts +7 -0
  122. package/dist/rate-limit/drivers/drivers.int.test.d.ts.map +1 -0
  123. package/dist/rate-limit/drivers/drivers.int.test.js +466 -0
  124. package/dist/rate-limit/drivers/drivers.int.test.js.map +1 -0
  125. package/dist/server/builder.d.ts.map +1 -1
  126. package/dist/server/builder.int.test.js +41 -0
  127. package/dist/server/builder.int.test.js.map +1 -1
  128. package/dist/server/builder.js +72 -15
  129. package/dist/server/builder.js.map +1 -1
  130. package/dist/server/channel-utils.d.ts +4 -1
  131. package/dist/server/channel-utils.d.ts.map +1 -1
  132. package/dist/server/channel-utils.js +12 -2
  133. package/dist/server/channel-utils.js.map +1 -1
  134. package/dist/server/errors.d.ts.map +1 -1
  135. package/dist/server/errors.js +0 -22
  136. package/dist/server/errors.js.map +1 -1
  137. package/dist/server/fs-routes/watcher.js +1 -1
  138. package/dist/server/fs-routes/watcher.js.map +1 -1
  139. package/dist/server/index.d.ts +1 -1
  140. package/dist/server/index.d.ts.map +1 -1
  141. package/dist/server/index.js.map +1 -1
  142. package/dist/server/types.d.ts +37 -33
  143. package/dist/server/types.d.ts.map +1 -1
  144. package/dist/tracing/interceptor.d.ts.map +1 -1
  145. package/dist/tracing/interceptor.js +4 -5
  146. package/dist/tracing/interceptor.js.map +1 -1
  147. package/dist/types/envelope.d.ts +1 -1
  148. package/dist/types/envelope.d.ts.map +1 -1
  149. package/dist/types/envelope.js.map +1 -1
  150. package/dist/types/handlers.d.ts +8 -0
  151. package/dist/types/handlers.d.ts.map +1 -1
  152. package/dist/ui/core/index.d.ts +7 -0
  153. package/dist/ui/core/index.d.ts.map +1 -0
  154. package/dist/ui/docs/generators/content-types.d.ts +10 -0
  155. package/dist/ui/docs/generators/content-types.d.ts.map +1 -0
  156. package/dist/ui/docs/generators/errors-types.d.ts +409 -0
  157. package/dist/ui/docs/generators/errors-types.d.ts.map +1 -0
  158. package/dist/ui/docs/generators/errors.d.ts +88 -0
  159. package/dist/ui/docs/generators/errors.d.ts.map +1 -0
  160. package/dist/ui/docs/generators/grpc-generator.d.ts +53 -0
  161. package/dist/ui/docs/generators/grpc-generator.d.ts.map +1 -0
  162. package/dist/ui/docs/generators/http-generator.d.ts +49 -0
  163. package/dist/ui/docs/generators/http-generator.d.ts.map +1 -0
  164. package/dist/ui/docs/generators/index.d.ts +17 -0
  165. package/dist/ui/docs/generators/index.d.ts.map +1 -0
  166. package/dist/ui/docs/generators/jsonrpc-generator.d.ts +53 -0
  167. package/dist/ui/docs/generators/jsonrpc-generator.d.ts.map +1 -0
  168. package/dist/ui/docs/generators/schema-converter.d.ts +117 -0
  169. package/dist/ui/docs/generators/schema-converter.d.ts.map +1 -0
  170. package/dist/ui/docs/generators/streams-generator.d.ts +85 -0
  171. package/dist/ui/docs/generators/streams-generator.d.ts.map +1 -0
  172. package/dist/ui/docs/generators/tcp-generator.d.ts +133 -0
  173. package/dist/ui/docs/generators/tcp-generator.d.ts.map +1 -0
  174. package/dist/ui/docs/generators/udp-generator.d.ts +119 -0
  175. package/dist/ui/docs/generators/udp-generator.d.ts.map +1 -0
  176. package/dist/ui/docs/generators/usd-generator.d.ts +182 -0
  177. package/dist/ui/docs/generators/usd-generator.d.ts.map +1 -0
  178. package/dist/ui/docs/generators/websocket-generator.d.ts +49 -0
  179. package/dist/ui/docs/generators/websocket-generator.d.ts.map +1 -0
  180. package/dist/ui/docs/index.d.ts +31 -0
  181. package/dist/ui/docs/index.d.ts.map +1 -0
  182. package/dist/ui/docs/usd-middleware.d.ts +157 -0
  183. package/dist/ui/docs/usd-middleware.d.ts.map +1 -0
  184. package/dist/ui/errors/factories.d.ts +142 -0
  185. package/dist/ui/errors/factories.d.ts.map +1 -0
  186. package/dist/ui/errors/index.d.ts +9 -0
  187. package/dist/ui/errors/index.d.ts.map +1 -0
  188. package/dist/ui/server/fs-routes/index.d.ts +66 -0
  189. package/dist/ui/server/fs-routes/index.d.ts.map +1 -0
  190. package/dist/ui/server/fs-routes/loader.d.ts +28 -0
  191. package/dist/ui/server/fs-routes/loader.d.ts.map +1 -0
  192. package/dist/ui/server/fs-routes/middleware-processor.d.ts +19 -0
  193. package/dist/ui/server/fs-routes/middleware-processor.d.ts.map +1 -0
  194. package/dist/ui/server/fs-routes/resources/index.d.ts +8 -0
  195. package/dist/ui/server/fs-routes/resources/index.d.ts.map +1 -0
  196. package/dist/ui/server/fs-routes/resources/loader.d.ts +16 -0
  197. package/dist/ui/server/fs-routes/resources/loader.d.ts.map +1 -0
  198. package/dist/ui/server/fs-routes/resources/types.d.ts +256 -0
  199. package/dist/ui/server/fs-routes/resources/types.d.ts.map +1 -0
  200. package/dist/ui/server/fs-routes/rest/index.d.ts +8 -0
  201. package/dist/ui/server/fs-routes/rest/index.d.ts.map +1 -0
  202. package/dist/ui/server/fs-routes/rest/loader.d.ts +11 -0
  203. package/dist/ui/server/fs-routes/rest/loader.d.ts.map +1 -0
  204. package/dist/ui/server/fs-routes/rest/types.d.ts +288 -0
  205. package/dist/ui/server/fs-routes/rest/types.d.ts.map +1 -0
  206. package/dist/ui/server/fs-routes/tcp/index.d.ts +8 -0
  207. package/dist/ui/server/fs-routes/tcp/index.d.ts.map +1 -0
  208. package/dist/ui/server/fs-routes/tcp/loader.d.ts +15 -0
  209. package/dist/ui/server/fs-routes/tcp/loader.d.ts.map +1 -0
  210. package/dist/ui/server/fs-routes/tcp/types.d.ts +215 -0
  211. package/dist/ui/server/fs-routes/tcp/types.d.ts.map +1 -0
  212. package/dist/ui/server/fs-routes/types.d.ts +437 -0
  213. package/dist/ui/server/fs-routes/types.d.ts.map +1 -0
  214. package/dist/ui/server/fs-routes/udp/index.d.ts +8 -0
  215. package/dist/ui/server/fs-routes/udp/index.d.ts.map +1 -0
  216. package/dist/ui/server/fs-routes/udp/loader.d.ts +15 -0
  217. package/dist/ui/server/fs-routes/udp/loader.d.ts.map +1 -0
  218. package/dist/ui/server/fs-routes/udp/types.d.ts +164 -0
  219. package/dist/ui/server/fs-routes/udp/types.d.ts.map +1 -0
  220. package/dist/ui/server/fs-routes/watcher.d.ts +34 -0
  221. package/dist/ui/server/fs-routes/watcher.d.ts.map +1 -0
  222. package/dist/ui/types/envelope.d.ts +1 -1
  223. package/dist/ui/types/envelope.d.ts.map +1 -1
  224. package/dist/ui/types/handlers.d.ts +8 -0
  225. package/dist/ui/types/handlers.d.ts.map +1 -1
  226. package/dist/ui/usd/builder/document.d.ts.map +1 -1
  227. package/dist/ui/usd/export/openapi.d.ts.map +1 -1
  228. package/dist/ui/usd/parser/normalize.d.ts.map +1 -1
  229. package/dist/ui/usd/spec/types.d.ts +14 -20
  230. package/dist/ui/usd/spec/types.d.ts.map +1 -1
  231. package/dist/ui/usd/utils/refs.d.ts.map +1 -1
  232. package/dist/ui/usd/validator/index.d.ts.map +1 -1
  233. package/dist/ui/usd/validator/schema.d.ts.map +1 -1
  234. package/dist/ui/usd/validator/semantic.d.ts.map +1 -1
  235. package/dist/ui/utils/logger.d.ts +15 -0
  236. package/dist/ui/utils/logger.d.ts.map +1 -0
  237. package/dist/usd/builder/document.d.ts.map +1 -1
  238. package/dist/usd/builder/document.js.map +1 -1
  239. package/dist/usd/export/openapi.d.ts.map +1 -1
  240. package/dist/usd/export/openapi.js +2 -4
  241. package/dist/usd/export/openapi.js.map +1 -1
  242. package/dist/usd/parser/normalize.d.ts.map +1 -1
  243. package/dist/usd/parser/normalize.js +0 -1
  244. package/dist/usd/parser/normalize.js.map +1 -1
  245. package/dist/usd/usd.int.test.d.ts +10 -0
  246. package/dist/usd/usd.int.test.d.ts.map +1 -0
  247. package/dist/usd/usd.int.test.js +719 -0
  248. package/dist/usd/usd.int.test.js.map +1 -0
  249. package/dist/usd/utils/refs.d.ts.map +1 -1
  250. package/dist/usd/validator/index.d.ts.map +1 -1
  251. package/dist/usd/validator/index.js.map +1 -1
  252. package/dist/usd/validator/schema.d.ts.map +1 -1
  253. package/dist/usd/validator/schema.js.map +1 -1
  254. package/dist/usd/validator/semantic.d.ts.map +1 -1
  255. package/dist/usd/validator/semantic.js.map +1 -1
  256. package/package.json +1 -1
  257. package/dist/middleware/rate-limit.d.ts +0 -105
  258. package/dist/middleware/rate-limit.d.ts.map +0 -1
  259. package/dist/middleware/rate-limit.int.test.d.ts +0 -5
  260. package/dist/middleware/rate-limit.int.test.d.ts.map +0 -1
  261. package/dist/middleware/rate-limit.int.test.js +0 -350
  262. package/dist/middleware/rate-limit.int.test.js.map +0 -1
  263. package/dist/middleware/rate-limit.js +0 -206
  264. package/dist/middleware/rate-limit.js.map +0 -1
  265. package/dist/openapi/index.d.ts +0 -9
  266. package/dist/openapi/index.d.ts.map +0 -1
  267. package/dist/openapi/index.js +0 -9
  268. package/dist/openapi/index.js.map +0 -1
@@ -0,0 +1,182 @@
1
+ /**
2
+ * USD Generator - Main Orchestrator
3
+ *
4
+ * Generates complete USD (Universal Service Documentation) documents
5
+ * by coordinating all protocol-specific sub-generators.
6
+ *
7
+ * USD extends OpenAPI 3.1 with an x-usd namespace for multi-protocol support.
8
+ */
9
+ import type { USDDocument, USDInfo, USDServer, USDTag, USDSchema, USDProtocol, USDComponents, USDSecurityScheme, USDExternalDocs, USDContentTypes } from '../../usd/index.js';
10
+ import type { Registry } from '../../core/registry.js';
11
+ import type { SchemaRegistry } from '../../validation/index.js';
12
+ import type { LoadedChannel, LoadedRestResource } from '../../server/fs-routes/index.js';
13
+ import { type HttpGeneratorOptions } from './http-generator.js';
14
+ import { type WebSocketGeneratorOptions } from './websocket-generator.js';
15
+ import { type StreamsGeneratorOptions } from './streams-generator.js';
16
+ import { type TcpGeneratorOptions, type LoadedTcpHandler } from './tcp-generator.js';
17
+ import { type UdpGeneratorOptions, type LoadedUdpHandler } from './udp-generator.js';
18
+ import { type JsonRpcGeneratorOptions } from './jsonrpc-generator.js';
19
+ import { type GrpcGeneratorOptions } from './grpc-generator.js';
20
+ /**
21
+ * USD generation options
22
+ */
23
+ export interface USDGeneratorOptions {
24
+ /** API information */
25
+ info: {
26
+ title: string;
27
+ version: string;
28
+ description?: string;
29
+ termsOfService?: string;
30
+ contact?: {
31
+ name?: string;
32
+ url?: string;
33
+ email?: string;
34
+ };
35
+ license?: {
36
+ name: string;
37
+ url?: string;
38
+ identifier?: string;
39
+ };
40
+ summary?: string;
41
+ };
42
+ /** Server definitions */
43
+ servers?: USDServer[];
44
+ /** Protocols to include (auto-detected if not specified) */
45
+ protocols?: USDProtocol[];
46
+ /** Global content types */
47
+ contentTypes?: USDContentTypes;
48
+ /** HTTP generation options */
49
+ http?: HttpGeneratorOptions;
50
+ /** WebSocket generation options */
51
+ websocket?: WebSocketGeneratorOptions;
52
+ /** Streams generation options */
53
+ streams?: StreamsGeneratorOptions;
54
+ /** JSON-RPC generation options */
55
+ jsonrpc?: JsonRpcGeneratorOptions;
56
+ /** gRPC generation options */
57
+ grpc?: GrpcGeneratorOptions;
58
+ /** TCP generation options */
59
+ tcp?: TcpGeneratorOptions;
60
+ /** UDP generation options */
61
+ udp?: UdpGeneratorOptions;
62
+ /** Security schemes */
63
+ securitySchemes?: Record<string, USDSecurityScheme>;
64
+ /** Default security requirement */
65
+ defaultSecurity?: Array<Record<string, string[]>>;
66
+ /** Tags for grouping */
67
+ tags?: USDTag[];
68
+ /** External documentation */
69
+ externalDocs?: USDExternalDocs;
70
+ /** Include standard error schemas */
71
+ includeErrorSchemas?: boolean;
72
+ /** Include stream event schemas */
73
+ includeStreamEventSchemas?: boolean;
74
+ }
75
+ /**
76
+ * USD generation context
77
+ */
78
+ export interface USDGeneratorContext {
79
+ /** Handler registry for procedures, streams, events */
80
+ registry: Registry;
81
+ /** Schema registry for input/output validation schemas */
82
+ schemaRegistry?: SchemaRegistry;
83
+ /** WebSocket channels (from discovery or manual registration) */
84
+ channels?: Map<string, LoadedChannel> | LoadedChannel[];
85
+ /** REST resources (from discovery or manual registration) */
86
+ restResources?: LoadedRestResource[];
87
+ /** TCP handlers (from discovery or manual registration) */
88
+ tcpHandlers?: LoadedTcpHandler[];
89
+ /** UDP handlers (from discovery or manual registration) */
90
+ udpHandlers?: LoadedUdpHandler[];
91
+ /** Protocol configuration (for jsonrpc/grpc detection) */
92
+ protocolConfig?: USDGeneratorProtocolConfig;
93
+ }
94
+ export interface USDGeneratorProtocolConfig {
95
+ jsonrpc?: {
96
+ enabled?: boolean;
97
+ options?: {
98
+ path?: string;
99
+ };
100
+ };
101
+ grpc?: {
102
+ enabled?: boolean;
103
+ options?: {
104
+ packageName?: string;
105
+ };
106
+ };
107
+ }
108
+ /**
109
+ * USD generation result
110
+ */
111
+ export interface USDGeneratorResult {
112
+ /** Complete USD document */
113
+ document: USDDocument;
114
+ /** Detected protocols */
115
+ protocols: USDProtocol[];
116
+ /** All tags used across protocols */
117
+ tags: string[];
118
+ }
119
+ /**
120
+ * Generate a complete USD document from the provided context
121
+ *
122
+ * @example
123
+ * ```ts
124
+ * const result = generateUSD(
125
+ * {
126
+ * registry: server.getRegistry(),
127
+ * schemaRegistry: server.getSchemaRegistry(),
128
+ * channels: server.getChannels(),
129
+ * restResources: server.getRestResources(),
130
+ * },
131
+ * {
132
+ * info: {
133
+ * title: 'My API',
134
+ * version: '1.0.0',
135
+ * },
136
+ * }
137
+ * )
138
+ * ```
139
+ */
140
+ export declare function generateUSD(ctx: USDGeneratorContext, options: USDGeneratorOptions): USDGeneratorResult;
141
+ /**
142
+ * Create a minimal USD document for a simple HTTP API
143
+ */
144
+ export declare function createHttpOnlyUSD(ctx: Pick<USDGeneratorContext, 'registry' | 'schemaRegistry' | 'restResources'>, info: {
145
+ title: string;
146
+ version: string;
147
+ description?: string;
148
+ }): USDDocument;
149
+ /**
150
+ * Create a minimal USD document for WebSocket-only API
151
+ */
152
+ export declare function createWebSocketOnlyUSD(channels: Map<string, LoadedChannel> | LoadedChannel[], info: {
153
+ title: string;
154
+ version: string;
155
+ description?: string;
156
+ }, wsOptions?: WebSocketGeneratorOptions): USDDocument;
157
+ /**
158
+ * Create a minimal USD document for Streams-only API
159
+ */
160
+ export declare function createStreamsOnlyUSD(ctx: Pick<USDGeneratorContext, 'registry' | 'schemaRegistry'>, info: {
161
+ title: string;
162
+ version: string;
163
+ description?: string;
164
+ }): USDDocument;
165
+ /**
166
+ * Create a minimal USD document for TCP-only API
167
+ */
168
+ export declare function createTcpOnlyUSD(handlers: LoadedTcpHandler[], info: {
169
+ title: string;
170
+ version: string;
171
+ description?: string;
172
+ }, tcpOptions?: TcpGeneratorOptions): USDDocument;
173
+ /**
174
+ * Create a minimal USD document for UDP-only API
175
+ */
176
+ export declare function createUdpOnlyUSD(handlers: LoadedUdpHandler[], info: {
177
+ title: string;
178
+ version: string;
179
+ description?: string;
180
+ }, udpOptions?: UdpGeneratorOptions): USDDocument;
181
+ export type { USDDocument, USDInfo, USDServer, USDTag, USDSchema, USDProtocol, USDComponents, USDSecurityScheme, USDExternalDocs, LoadedTcpHandler, LoadedUdpHandler, };
182
+ //# sourceMappingURL=usd-generator.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"usd-generator.d.ts","sourceRoot":"","sources":["../../../../src/docs/generators/usd-generator.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,49 @@
1
+ /**
2
+ * WebSocket Generator for USD
3
+ *
4
+ * Converts Raffel channels to USD WebSocket specification (x-usd.websocket).
5
+ */
6
+ import type { USDWebSocket, USDSchema, USDContentTypes } from '../../usd/index.js';
7
+ import type { LoadedChannel } from '../../server/fs-routes/index.js';
8
+ /**
9
+ * WebSocket generation options
10
+ */
11
+ export interface WebSocketGeneratorOptions {
12
+ /** WebSocket endpoint path */
13
+ path?: string;
14
+ /** Protocol content types */
15
+ contentTypes?: USDContentTypes;
16
+ /** Include protocol documentation */
17
+ includeProtocol?: boolean;
18
+ /** Include authentication info */
19
+ includeAuthentication?: boolean;
20
+ /** Authentication location */
21
+ authIn?: 'query' | 'header' | 'cookie';
22
+ /** Authentication parameter name */
23
+ authName?: string;
24
+ }
25
+ /**
26
+ * WebSocket generation context
27
+ */
28
+ export interface WebSocketGeneratorContext {
29
+ /** Loaded channels from discovery or manual registration */
30
+ channels: Map<string, LoadedChannel> | LoadedChannel[];
31
+ }
32
+ /**
33
+ * WebSocket generation result
34
+ */
35
+ export interface WebSocketGeneratorResult {
36
+ /** USD WebSocket specification */
37
+ websocket: USDWebSocket;
38
+ /** Component schemas used */
39
+ schemas: Record<string, USDSchema>;
40
+ }
41
+ /**
42
+ * Generate USD WebSocket specification from channels
43
+ */
44
+ export declare function generateWebSocket(ctx: WebSocketGeneratorContext, options?: WebSocketGeneratorOptions): WebSocketGeneratorResult;
45
+ /**
46
+ * Generate channel component schemas for reuse
47
+ */
48
+ export declare function generateChannelSchemas(channels: Map<string, LoadedChannel> | LoadedChannel[]): Record<string, USDSchema>;
49
+ //# sourceMappingURL=websocket-generator.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"websocket-generator.d.ts","sourceRoot":"","sources":["../../../../src/docs/generators/websocket-generator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,YAAY,EAA8B,SAAS,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAE9G,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAA;AAGpE;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,6BAA6B;IAC7B,YAAY,CAAC,EAAE,eAAe,CAAA;IAC9B,qCAAqC;IACrC,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,kCAAkC;IAClC,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B,8BAA8B;IAC9B,MAAM,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAA;IACtC,oCAAoC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,4DAA4D;IAC5D,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,aAAa,EAAE,CAAA;CACvD;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,kCAAkC;IAClC,SAAS,EAAE,YAAY,CAAA;IACvB,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;CACnC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,yBAAyB,EAC9B,OAAO,GAAE,yBAA8B,GACtC,wBAAwB,CA8C1B;AA2RD;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,aAAa,EAAE,GACrD,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAkB3B"}
@@ -0,0 +1,31 @@
1
+ /**
2
+ * USD (Universal Service Documentation) Module
3
+ *
4
+ * A unified documentation format that extends OpenAPI 3.1 with the x-usd namespace
5
+ * to support multiple protocols in a single document.
6
+ *
7
+ * Supported protocols:
8
+ * - HTTP (standard OpenAPI paths)
9
+ * - WebSocket (x-usd.websocket)
10
+ * - Streams/SSE (x-usd.streams)
11
+ * - JSON-RPC (x-usd.jsonrpc)
12
+ * - gRPC (x-usd.grpc)
13
+ * - TCP (x-usd.tcp)
14
+ * - UDP (x-usd.udp)
15
+ *
16
+ * @example
17
+ * ```typescript
18
+ * import { createServer } from 'raffel'
19
+ *
20
+ * const server = createServer({ port: 3000 })
21
+ * .enableWebSocket()
22
+ * .enableUSD({
23
+ * info: { title: 'My API', version: '1.0.0' },
24
+ * ui: { theme: 'auto' },
25
+ * })
26
+ * ```
27
+ */
28
+ export { generateUSD, createHttpOnlyUSD, createWebSocketOnlyUSD, createStreamsOnlyUSD, createTcpOnlyUSD, createUdpOnlyUSD, type USDGeneratorOptions, type USDGeneratorContext, type USDGeneratorResult, type USDGeneratorProtocolConfig, generateHttpPaths, type HttpGeneratorOptions, type HttpGeneratorContext, type HttpGeneratorResult, generateWebSocket, generateChannelSchemas, type WebSocketGeneratorOptions, type WebSocketGeneratorContext, type WebSocketGeneratorResult, generateStreams, generateStreamEvents, createSSEStreamConfig, createBidiStreamConfig, type StreamsGeneratorOptions, type StreamsGeneratorContext, type StreamsGeneratorResult, generateTcp, generateTcpSchemas, createTcpServerConfig, type TcpHandlerDocs, type LoadedTcpHandler, type TcpGeneratorOptions, type TcpGeneratorContext, type TcpGeneratorResult, generateUdp, generateUdpSchemas, createUdpEndpointConfig, type UdpHandlerDocs, type LoadedUdpHandler, type UdpGeneratorOptions, type UdpGeneratorContext, type UdpGeneratorResult, convertSchema, createSchemaRegistry, isZodSchema, isJsonSchema, convertAndRegister, extractParameters, generateSchemaName, createRef, createArraySchema, createPaginatedSchema, createErrorSchema, type SchemaConversionOptions, type ConvertedSchemaRegistry, type ExtractedParameters, generateErrorsSpec, registerErrorCode, getErrorCodes, clearCustomErrorCodes, getHttpStatus, getGrpcCode, getGrpcName, getWebSocketClose, getJsonRpcCode, isRetryable, type ErrorRegistryEntry, type GenerateErrorsOptions, } from './generators/index.js';
29
+ export { createUSDHandlers, type USDMiddlewareConfig, type USDHandlers, type USDMiddlewareContext, } from './usd-middleware.js';
30
+ export { generateOpenAPI, generateOpenAPIJson, generateOpenAPIYaml, type OpenAPIDocument, type OpenAPIInfo, type OpenAPIServer, type OpenAPIPathItem, type OpenAPIOperation, type OpenAPIResponse, type OpenAPISecurityScheme, type OpenAPITag, type GeneratorOptions, type OpenAPIRestResource, type OpenAPIRestRoute, } from './openapi/index.js';
31
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/docs/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAMH,OAAO,EAEL,WAAW,EACX,iBAAiB,EACjB,sBAAsB,EACtB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,0BAA0B,EAG/B,iBAAiB,EACjB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EAGxB,iBAAiB,EACjB,sBAAsB,EACtB,KAAK,yBAAyB,EAC9B,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAG7B,eAAe,EACf,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAG3B,WAAW,EACX,kBAAkB,EAClB,qBAAqB,EACrB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EAGvB,WAAW,EACX,kBAAkB,EAClB,uBAAuB,EACvB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EAGvB,aAAa,EACb,oBAAoB,EACpB,WAAW,EACX,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,SAAS,EACT,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,EACjB,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EAGxB,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,qBAAqB,EACrB,aAAa,EACb,WAAW,EACX,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,WAAW,EACX,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,GAC3B,MAAM,uBAAuB,CAAA;AAM9B,OAAO,EACL,iBAAiB,EACjB,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,oBAAoB,GAC1B,MAAM,qBAAqB,CAAA;AAM5B,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,GACtB,MAAM,oBAAoB,CAAA"}
@@ -0,0 +1,157 @@
1
+ /**
2
+ * USD Documentation Middleware
3
+ *
4
+ * Creates HTTP handlers for serving USD documentation.
5
+ *
6
+ * Security Note: The UI HTML generation uses innerHTML for rendering
7
+ * documentation from the trusted spec object (generated by our own code).
8
+ * User-provided content is properly escaped with escapeHtml().
9
+ */
10
+ import type { Registry } from '../core/index.js';
11
+ import type { SchemaRegistry } from '../validation/index.js';
12
+ import type { LoadedChannel, LoadedRestResource } from '../server/fs-routes/index.js';
13
+ import type { USDDocument } from '../usd/index.js';
14
+ import type { OpenAPIDocument } from '../usd/export/openapi.js';
15
+ import { type USDGeneratorOptions, type USDGeneratorProtocolConfig } from './generators/usd-generator.js';
16
+ import type { LoadedTcpHandler } from './generators/tcp-generator.js';
17
+ import type { LoadedUdpHandler } from './generators/udp-generator.js';
18
+ /**
19
+ * USD middleware configuration
20
+ */
21
+ export interface USDMiddlewareConfig {
22
+ /** Base path for documentation endpoints (default: '/docs') */
23
+ basePath?: string;
24
+ /** API information */
25
+ info?: {
26
+ title?: string;
27
+ version?: string;
28
+ description?: string;
29
+ termsOfService?: string;
30
+ contact?: {
31
+ name?: string;
32
+ url?: string;
33
+ email?: string;
34
+ };
35
+ license?: {
36
+ name: string;
37
+ url?: string;
38
+ identifier?: string;
39
+ };
40
+ summary?: string;
41
+ };
42
+ /** Server definitions */
43
+ servers?: USDGeneratorOptions['servers'];
44
+ /** Protocols to include (auto-detected if not specified) */
45
+ protocols?: USDGeneratorOptions['protocols'];
46
+ /** Global content types */
47
+ contentTypes?: USDGeneratorOptions['contentTypes'];
48
+ /** Security schemes */
49
+ securitySchemes?: USDGeneratorOptions['securitySchemes'];
50
+ /** Default security requirement */
51
+ defaultSecurity?: USDGeneratorOptions['defaultSecurity'];
52
+ /** Tags for grouping */
53
+ tags?: USDGeneratorOptions['tags'];
54
+ /** External documentation */
55
+ externalDocs?: USDGeneratorOptions['externalDocs'];
56
+ /** Tag groups for hierarchical organization (like Redoc) */
57
+ tagGroups?: Array<{
58
+ name: string;
59
+ tags: string[];
60
+ description?: string;
61
+ expanded?: boolean;
62
+ }>;
63
+ /** UI configuration */
64
+ ui?: {
65
+ theme?: 'light' | 'dark' | 'auto';
66
+ primaryColor?: string;
67
+ logo?: string;
68
+ favicon?: string;
69
+ tryItOut?: boolean;
70
+ codeGeneration?: {
71
+ enabled?: boolean;
72
+ languages?: ('typescript' | 'python' | 'go' | 'curl')[];
73
+ };
74
+ /** Hero section (landing page header) */
75
+ hero?: {
76
+ /** Main title (defaults to API title) */
77
+ title?: string;
78
+ /** Subtitle/tagline */
79
+ tagline?: string;
80
+ /** Background style */
81
+ background?: 'gradient' | 'solid' | 'pattern' | 'image';
82
+ /** Background image URL (if background is 'image') */
83
+ backgroundImage?: string;
84
+ /** Call-to-action buttons */
85
+ buttons?: Array<{
86
+ text: string;
87
+ href?: string;
88
+ primary?: boolean;
89
+ }>;
90
+ /** Quick links section */
91
+ quickLinks?: Array<{
92
+ title: string;
93
+ description?: string;
94
+ href: string;
95
+ icon?: string;
96
+ }>;
97
+ };
98
+ /** Sidebar configuration */
99
+ sidebar?: {
100
+ /** Show search */
101
+ search?: boolean;
102
+ /** Expand all groups by default */
103
+ expandAll?: boolean;
104
+ /** Show endpoint count badges */
105
+ showCounts?: boolean;
106
+ };
107
+ };
108
+ /** Include standard error schemas */
109
+ includeErrorSchemas?: boolean;
110
+ /** Include stream event schemas */
111
+ includeStreamEventSchemas?: boolean;
112
+ /** JSON-RPC generation options */
113
+ jsonrpc?: USDGeneratorOptions['jsonrpc'];
114
+ /** gRPC generation options */
115
+ grpc?: USDGeneratorOptions['grpc'];
116
+ }
117
+ /**
118
+ * USD documentation handlers
119
+ */
120
+ export interface USDHandlers {
121
+ /** Serve the main documentation UI */
122
+ serveUI: () => Response;
123
+ /** Serve USD document as JSON */
124
+ serveUSD: () => Response;
125
+ /** Serve USD document as YAML */
126
+ serveUSDYaml: () => Response;
127
+ /** Serve pure OpenAPI 3.1 JSON (for Swagger UI compatibility) */
128
+ serveOpenAPI: () => Response;
129
+ /** Get the USD document */
130
+ getUSDDocument: () => USDDocument;
131
+ /** Get the OpenAPI document */
132
+ getOpenAPIDocument: () => OpenAPIDocument;
133
+ }
134
+ /**
135
+ * Context for USD middleware
136
+ */
137
+ export interface USDMiddlewareContext {
138
+ /** Handler registry */
139
+ registry: Registry;
140
+ /** Schema registry */
141
+ schemaRegistry: SchemaRegistry;
142
+ /** WebSocket channels */
143
+ channels?: Map<string, LoadedChannel>;
144
+ /** REST resources */
145
+ restResources?: LoadedRestResource[];
146
+ /** TCP handlers */
147
+ tcpHandlers?: LoadedTcpHandler[];
148
+ /** UDP handlers */
149
+ udpHandlers?: LoadedUdpHandler[];
150
+ /** Protocol configuration (jsonrpc/grpc detection) */
151
+ protocolConfig?: USDGeneratorProtocolConfig;
152
+ }
153
+ /**
154
+ * Create USD documentation handlers
155
+ */
156
+ export declare function createUSDHandlers(ctx: USDMiddlewareContext, config?: USDMiddlewareConfig): USDHandlers;
157
+ //# sourceMappingURL=usd-middleware.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"usd-middleware.d.ts","sourceRoot":"","sources":["../../../src/docs/usd-middleware.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,142 @@
1
+ /**
2
+ * Error Factories
3
+ *
4
+ * Pre-built error helpers for common error scenarios.
5
+ * Each factory creates a RaffelError with both string code and numeric status.
6
+ */
7
+ import { RaffelError } from '../core/router.js';
8
+ /**
9
+ * Pre-built error factories for consistent error handling
10
+ *
11
+ * All factories create errors with both string code and numeric status.
12
+ *
13
+ * @example
14
+ * ```typescript
15
+ * throw Errors.notFound('User', userId)
16
+ * // Creates: { code: 'NOT_FOUND', status: 404, message: "User 'abc' not found" }
17
+ *
18
+ * throw Errors.validation('email', 'must be valid')
19
+ * // Creates: { code: 'VALIDATION_ERROR', status: 400, message: "email: must be valid" }
20
+ * ```
21
+ */
22
+ export declare const Errors: {
23
+ /**
24
+ * Resource not found
25
+ * @param resource - Name of the resource (e.g., 'User', 'Order')
26
+ * @param id - Optional resource identifier
27
+ */
28
+ readonly notFound: (resource: string, id?: string | number) => RaffelError;
29
+ /**
30
+ * Validation error
31
+ * @param field - Field name that failed validation
32
+ * @param reason - Why validation failed
33
+ * @param value - Optional offending value
34
+ */
35
+ readonly validation: (field: string, reason: string, value?: unknown) => RaffelError;
36
+ /**
37
+ * Multiple validation errors
38
+ * @param errors - Array of field errors
39
+ */
40
+ readonly validationMultiple: (errors: Array<{
41
+ field: string;
42
+ reason: string;
43
+ }>) => RaffelError;
44
+ /**
45
+ * Authentication required
46
+ * @param reason - Optional reason
47
+ */
48
+ readonly unauthorized: (reason?: string) => RaffelError;
49
+ /**
50
+ * Permission denied
51
+ * @param reason - Why permission was denied
52
+ */
53
+ readonly forbidden: (reason?: string) => RaffelError;
54
+ /**
55
+ * Rate limit exceeded
56
+ * @param retryAfter - Optional seconds until retry is allowed
57
+ */
58
+ readonly rateLimit: (retryAfter?: number) => RaffelError;
59
+ /**
60
+ * Request timeout
61
+ * @param operation - What operation timed out
62
+ */
63
+ readonly timeout: (operation?: string) => RaffelError;
64
+ /**
65
+ * Internal server error
66
+ * @param message - Error message
67
+ * @param details - Optional additional details
68
+ */
69
+ readonly internal: (message?: string, details?: unknown) => RaffelError;
70
+ /**
71
+ * Bad request / invalid argument
72
+ * @param message - What was wrong with the request
73
+ */
74
+ readonly badRequest: (message: string) => RaffelError;
75
+ /**
76
+ * Resource already exists
77
+ * @param resource - Name of the resource
78
+ * @param identifier - What makes it duplicate
79
+ */
80
+ readonly alreadyExists: (resource: string, identifier?: string) => RaffelError;
81
+ /**
82
+ * Precondition failed
83
+ * @param condition - What condition was not met
84
+ */
85
+ readonly preconditionFailed: (condition: string) => RaffelError;
86
+ /**
87
+ * Resource exhausted (quota, disk space, etc.)
88
+ * @param resource - What resource is exhausted
89
+ */
90
+ readonly resourceExhausted: (resource: string) => RaffelError;
91
+ /**
92
+ * Operation cancelled
93
+ * @param operation - What was cancelled
94
+ */
95
+ readonly cancelled: (operation?: string) => RaffelError;
96
+ /**
97
+ * Feature not implemented
98
+ * @param feature - What feature is not implemented
99
+ */
100
+ readonly unimplemented: (feature?: string) => RaffelError;
101
+ /**
102
+ * Service unavailable
103
+ * @param service - What service is unavailable
104
+ */
105
+ readonly unavailable: (service?: string) => RaffelError;
106
+ /**
107
+ * Unprocessable entity - semantically invalid request
108
+ *
109
+ * Use for business logic validation (e.g., "can't delete user with active orders")
110
+ * vs validation() for schema/syntactic validation.
111
+ *
112
+ * @param reason - Why the entity cannot be processed
113
+ * @param details - Optional additional details
114
+ */
115
+ readonly unprocessable: (reason: string, details?: unknown) => RaffelError;
116
+ /**
117
+ * Bad gateway - upstream service returned invalid response
118
+ * @param upstream - Name of the upstream service
119
+ * @param details - Optional error details
120
+ */
121
+ readonly badGateway: (upstream?: string, details?: unknown) => RaffelError;
122
+ /**
123
+ * Gateway timeout - upstream service did not respond in time
124
+ * @param upstream - Name of the upstream service
125
+ * @param timeoutMs - Optional timeout value in milliseconds
126
+ */
127
+ readonly gatewayTimeout: (upstream?: string, timeoutMs?: number) => RaffelError;
128
+ /**
129
+ * Data loss / corruption detected
130
+ * @param message - What happened
131
+ */
132
+ readonly dataLoss: (message: string) => RaffelError;
133
+ /**
134
+ * Create a custom error
135
+ * @param code - Error code
136
+ * @param message - Error message
137
+ * @param details - Optional details
138
+ * @param status - Optional custom status code
139
+ */
140
+ readonly custom: (code: string, message: string, details?: unknown, status?: number) => RaffelError;
141
+ };
142
+ //# sourceMappingURL=factories.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"factories.d.ts","sourceRoot":"","sources":["../../../src/errors/factories.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE/C;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,MAAM;IACjB;;;;OAIG;kCACgB,MAAM,OAAO,MAAM,GAAG,MAAM,KAAG,WAAW;IAK7D;;;;;OAKG;iCACe,MAAM,UAAU,MAAM,UAAU,OAAO,KAAG,WAAW;IAQvE;;;OAGG;0CACwB,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,KAAG,WAAW;IAKjF;;;OAGG;qCACmB,MAAM,KAAG,WAAW;IAO1C;;;OAGG;kCACgB,MAAM,KAAG,WAAW;IAOvC;;;OAGG;sCACoB,MAAM,KAAG,WAAW;IAQ3C;;;OAGG;mCACiB,MAAM,KAAG,WAAW;IAKxC;;;;OAIG;kCACgB,MAAM,YAAY,OAAO,KAAG,WAAW;IAQ1D;;;OAGG;mCACiB,MAAM,KAAG,WAAW;IAIxC;;;;OAIG;uCACqB,MAAM,eAAe,MAAM,KAAG,WAAW;IAOjE;;;OAGG;6CAC2B,MAAM,KAAG,WAAW;IAIlD;;;OAGG;2CACyB,MAAM,KAAG,WAAW;IAIhD;;;OAGG;qCACmB,MAAM,KAAG,WAAW;IAK1C;;;OAGG;uCACqB,MAAM,KAAG,WAAW;IAK5C;;;OAGG;qCACmB,MAAM,KAAG,WAAW;IAK1C;;;;;;;;OAQG;qCACmB,MAAM,YAAY,OAAO,KAAG,WAAW;IAI7D;;;;OAIG;qCACmB,MAAM,YAAY,OAAO,KAAG,WAAW;IAO7D;;;;OAIG;yCACuB,MAAM,cAAc,MAAM,KAAG,WAAW;IAUlE;;;OAGG;iCACe,MAAM,KAAG,WAAW;IAItC;;;;;;OAMG;4BACU,MAAM,WAAW,MAAM,YAAY,OAAO,WAAW,MAAM,KAAG,WAAW;CAG9E,CAAA"}
@@ -0,0 +1,9 @@
1
+ /**
2
+ * Error Module
3
+ *
4
+ * Pre-built error factories, error types, and error code definitions.
5
+ */
6
+ export { Errors } from './factories.js';
7
+ export { ErrorCodes, type ErrorCode, type ErrorCodeDef, getErrorCode, getStatusForCode, isClientError, isServerError, isRetryable, } from './codes.js';
8
+ export { RaffelError } from '../core/router.js';
9
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/errors/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAGvC,OAAO,EACL,UAAU,EACV,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,WAAW,GACZ,MAAM,YAAY,CAAA;AAGnB,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA"}