franchising 0.0.0-stage → 0.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.
Files changed (227) hide show
  1. package/LICENSE +61 -0
  2. package/README.md +88 -2
  3. package/dist/accounts-B4bnTXUd.js +242 -0
  4. package/dist/accounts-B4bnTXUd.js.map +1 -0
  5. package/dist/accounts-TyMPSHM0.cjs +313 -0
  6. package/dist/accounts-TyMPSHM0.cjs.map +1 -0
  7. package/dist/adapters-DM59AJfR.d.cts +216 -0
  8. package/dist/adapters-DM59AJfR.d.ts +216 -0
  9. package/dist/cli/template-assets/api/src/errors/codes.ts +17 -0
  10. package/dist/cli/template-assets/api/src/errors/index.ts +16 -0
  11. package/dist/cli/template-assets/api/src/filters/exception.ts +53 -0
  12. package/dist/cli/template-assets/api/src/main.ts +189 -0
  13. package/dist/cli/template-assets/api/src/modules/health/controller.ts +23 -0
  14. package/dist/cli/template-assets/api/src/modules/health/dto/response.dto.ts +23 -0
  15. package/dist/cli/template-assets/api/src/modules/health/module.ts +12 -0
  16. package/dist/cli/template-assets/api/src/modules/health/service.ts +54 -0
  17. package/dist/cli/template-assets/api/src/modules/messaging/module.ts +7 -0
  18. package/dist/cli/template-assets/api/src/modules/messaging/service.ts +74 -0
  19. package/dist/cli/template-assets/api/src/shared/exceptions.ts +40 -0
  20. package/dist/cli/template-assets/api/src/shared/response.ts +31 -0
  21. package/dist/cli/template-assets/api/src/telemetry.ts +59 -0
  22. package/dist/cli/template-assets/api/src/types.ts +8 -0
  23. package/dist/cli/template-assets/cloudflare/cache.service.ts +23 -0
  24. package/dist/cli/template-assets/cloudflare/queue.service.ts +22 -0
  25. package/dist/cli/template-assets/cloudflare/worker.ts +33 -0
  26. package/dist/cli/template-assets/packages/jobs/src/index.ts +49 -0
  27. package/dist/cli/template-assets/packages/queue-runtime/src/index.ts +54 -0
  28. package/dist/cli/template-assets/root/dot-dockerignore +11 -0
  29. package/dist/cli/template-assets/root/dot-editorconfig +13 -0
  30. package/dist/cli/template-assets/root/dot-oxfmtrc.json +9 -0
  31. package/dist/cli/template-assets/root/dot-oxlintrc.json +47 -0
  32. package/dist/cli/template-assets/root/lefthook.yml +18 -0
  33. package/dist/cli/template-assets/web/postcss.config.mjs +9 -0
  34. package/dist/cli/template-assets/web/src/app/(app)/dashboard/page.tsx +5 -0
  35. package/dist/cli/template-assets/web/src/app/(app)/layout.tsx +25 -0
  36. package/dist/cli/template-assets/web/src/app/(auth)/login/page.tsx +75 -0
  37. package/dist/cli/template-assets/web/src/app/globals.css +48 -0
  38. package/dist/cli/template-assets/web/src/app/layout.tsx +30 -0
  39. package/dist/cli/template-assets/web/src/app/page.tsx +20 -0
  40. package/dist/cli/template-assets/web/src/components/overview/overview-panel.tsx +27 -0
  41. package/dist/cli/template-assets/web/src/components/shell/app-shell.tsx +37 -0
  42. package/dist/cli/template-assets/web/src/components/shell/providers.tsx +22 -0
  43. package/dist/cli/template-assets/web/src/lib/api-client.ts +57 -0
  44. package/dist/cli/template-assets/web/src/lib/auth-client.ts +15 -0
  45. package/dist/cli/template-assets/web/src/lib/server-auth.ts +38 -0
  46. package/dist/cli/template-assets/web/src/types/api.ts +18 -0
  47. package/dist/cli/template-assets/worker/src/app.module.ts +5 -0
  48. package/dist/cli/template-assets/worker/src/env.ts +8 -0
  49. package/dist/cli/template-assets/worker/src/main.ts +25 -0
  50. package/dist/cli/template-assets/worker/src/modules/queue/config.ts +16 -0
  51. package/dist/cli/template-assets/worker/src/modules/queue/module.ts +11 -0
  52. package/dist/cli/template-assets/worker/src/modules/queue/processor.ts +105 -0
  53. package/dist/cli/template-assets/worker/src/modules/queue/repository.ts +16 -0
  54. package/dist/cli/template-assets/worker/src/modules/queue/retry.ts +17 -0
  55. package/dist/cli/template-assets/worker/test/retry.test.ts.tpl +12 -0
  56. package/dist/cli/template-assets/worker-messaging/jobs-messaging.ts +12 -0
  57. package/dist/cli/template-assets/worker-messaging/messaging-api-service.ts +39 -0
  58. package/dist/cli/template-assets/worker-messaging/src/env.ts +14 -0
  59. package/dist/cli/template-assets/worker-messaging/src/modules/messaging/service.ts +59 -0
  60. package/dist/cli/template-assets/worker-messaging/src/modules/queue/module.ts +8 -0
  61. package/dist/cli/template-assets/worker-messaging/src/modules/queue/processor.ts +113 -0
  62. package/dist/cli.js +1218 -0
  63. package/dist/cn-BVOnrSza.js +1 -0
  64. package/dist/constants-C4iP0--i.js +38 -0
  65. package/dist/constants-C4iP0--i.js.map +1 -0
  66. package/dist/constants-rCR-LNSN.cjs +91 -0
  67. package/dist/constants-rCR-LNSN.cjs.map +1 -0
  68. package/dist/decorate-BR5FVX5x.js +14 -0
  69. package/dist/decorate-R-oqksAh.cjs +25 -0
  70. package/dist/decorateParam-BFJPEGKJ.cjs +13 -0
  71. package/dist/decorateParam-CKE7_J1s.js +8 -0
  72. package/dist/define-adapter-Cc0QrfKt.cjs +16 -0
  73. package/dist/define-adapter-Cc0QrfKt.cjs.map +1 -0
  74. package/dist/define-adapter-DRcXno3j.js +11 -0
  75. package/dist/define-adapter-DRcXno3j.js.map +1 -0
  76. package/dist/dispatcher-BsD7cO2w.cjs +84 -0
  77. package/dist/dispatcher-BsD7cO2w.cjs.map +1 -0
  78. package/dist/dispatcher-DA_l1Vkv.js +73 -0
  79. package/dist/dispatcher-DA_l1Vkv.js.map +1 -0
  80. package/dist/errors-DxHoXrLd.d.cts +46 -0
  81. package/dist/errors-DxHoXrLd.d.ts +46 -0
  82. package/dist/http/index.cjs +440 -0
  83. package/dist/http/index.cjs.map +1 -0
  84. package/dist/http/index.d.cts +257 -0
  85. package/dist/http/index.d.ts +257 -0
  86. package/dist/http/index.js +400 -0
  87. package/dist/http/index.js.map +1 -0
  88. package/dist/http/swagger.cjs +122 -0
  89. package/dist/http/swagger.cjs.map +1 -0
  90. package/dist/http/swagger.d.cts +59 -0
  91. package/dist/http/swagger.d.ts +59 -0
  92. package/dist/http/swagger.js +117 -0
  93. package/dist/http/swagger.js.map +1 -0
  94. package/dist/index-B3UOHsA9.d.ts +679 -0
  95. package/dist/index-Bdl0AiNM.d.ts +1262 -0
  96. package/dist/index-By8b4ksT.d.ts +25 -0
  97. package/dist/index-C1KmT8dQ.d.ts +174 -0
  98. package/dist/index-CYT1PFzo.d.cts +679 -0
  99. package/dist/index-Cj-10Q5F.d.cts +174 -0
  100. package/dist/index-DDSaLjXV.d.cts +25 -0
  101. package/dist/index-FTrYdHfq.d.cts +1262 -0
  102. package/dist/index.cjs +1 -0
  103. package/dist/index.d.cts +4 -0
  104. package/dist/index.d.ts +4 -0
  105. package/dist/index.js +1 -0
  106. package/dist/label-BqmJoVE-.cjs +1 -0
  107. package/dist/label-XeChe1Bu.js +1 -0
  108. package/dist/messaging/index.cjs +1 -0
  109. package/dist/messaging/index.d.cts +1775 -0
  110. package/dist/messaging/index.d.ts +1775 -0
  111. package/dist/messaging/index.js +1 -0
  112. package/dist/misc-BpM_lMTx.js +1 -0
  113. package/dist/misc-DkqJOm1V.cjs +1 -0
  114. package/dist/operational-CnxdBwVG.d.cts +13 -0
  115. package/dist/operational-CnxdBwVG.d.ts +13 -0
  116. package/dist/redaction-DhuHTlHA.js +124 -0
  117. package/dist/redaction-DhuHTlHA.js.map +1 -0
  118. package/dist/redaction-uRIQbTwZ.cjs +171 -0
  119. package/dist/redaction-uRIQbTwZ.cjs.map +1 -0
  120. package/dist/rolldown-runtime-auK_WOaK.cjs +1 -0
  121. package/dist/rolldown-runtime-xuxB8TGW.cjs +32 -0
  122. package/dist/runtime-C95UYYLb.cjs +111 -0
  123. package/dist/runtime-C95UYYLb.cjs.map +1 -0
  124. package/dist/runtime-DG2oBFYw.js +88 -0
  125. package/dist/runtime-DG2oBFYw.js.map +1 -0
  126. package/dist/skills-C1uwr9Pp.js +4 -0
  127. package/dist/skills-DuE-XnBp.js +1 -0
  128. package/dist/sso/client.cjs +37 -0
  129. package/dist/sso/client.cjs.map +1 -0
  130. package/dist/sso/client.d.cts +90 -0
  131. package/dist/sso/client.d.ts +90 -0
  132. package/dist/sso/client.js +36 -0
  133. package/dist/sso/client.js.map +1 -0
  134. package/dist/sso/index.cjs +833 -0
  135. package/dist/sso/index.cjs.map +1 -0
  136. package/dist/sso/index.d.cts +3 -0
  137. package/dist/sso/index.d.ts +3 -0
  138. package/dist/sso/index.js +821 -0
  139. package/dist/sso/index.js.map +1 -0
  140. package/dist/sso/nestjs.cjs +169 -0
  141. package/dist/sso/nestjs.cjs.map +1 -0
  142. package/dist/sso/nestjs.d.cts +92 -0
  143. package/dist/sso/nestjs.d.ts +92 -0
  144. package/dist/sso/nestjs.js +151 -0
  145. package/dist/sso/nestjs.js.map +1 -0
  146. package/dist/sso/resource.cjs +124 -0
  147. package/dist/sso/resource.cjs.map +1 -0
  148. package/dist/sso/resource.d.cts +3 -0
  149. package/dist/sso/resource.d.ts +3 -0
  150. package/dist/sso/resource.js +114 -0
  151. package/dist/sso/resource.js.map +1 -0
  152. package/dist/status-CRvlFPIs.js +13 -0
  153. package/dist/status-CRvlFPIs.js.map +1 -0
  154. package/dist/status-DtK6OHtj.cjs +24 -0
  155. package/dist/status-DtK6OHtj.cjs.map +1 -0
  156. package/dist/team-CJVAg4HH.d.cts +157 -0
  157. package/dist/team-CJVAg4HH.d.ts +157 -0
  158. package/dist/telemetry/adapters.cjs +6 -0
  159. package/dist/telemetry/adapters.d.cts +3 -0
  160. package/dist/telemetry/adapters.d.ts +3 -0
  161. package/dist/telemetry/adapters.js +4 -0
  162. package/dist/telemetry/betterstack.cjs +74 -0
  163. package/dist/telemetry/betterstack.cjs.map +1 -0
  164. package/dist/telemetry/betterstack.d.cts +12 -0
  165. package/dist/telemetry/betterstack.d.ts +12 -0
  166. package/dist/telemetry/betterstack.js +71 -0
  167. package/dist/telemetry/betterstack.js.map +1 -0
  168. package/dist/telemetry/index.cjs +1237 -0
  169. package/dist/telemetry/index.cjs.map +1 -0
  170. package/dist/telemetry/index.d.cts +114 -0
  171. package/dist/telemetry/index.d.ts +114 -0
  172. package/dist/telemetry/index.js +1205 -0
  173. package/dist/telemetry/index.js.map +1 -0
  174. package/dist/telemetry/posthog.cjs +72 -0
  175. package/dist/telemetry/posthog.cjs.map +1 -0
  176. package/dist/telemetry/posthog.d.cts +10 -0
  177. package/dist/telemetry/posthog.d.ts +10 -0
  178. package/dist/telemetry/posthog.js +71 -0
  179. package/dist/telemetry/posthog.js.map +1 -0
  180. package/dist/telemetry/register.cjs +6 -0
  181. package/dist/telemetry/register.d.cts +14 -0
  182. package/dist/telemetry/register.d.ts +14 -0
  183. package/dist/telemetry/register.js +3 -0
  184. package/dist/telemetry/testing.cjs +54 -0
  185. package/dist/telemetry/testing.cjs.map +1 -0
  186. package/dist/telemetry/testing.d.cts +15 -0
  187. package/dist/telemetry/testing.d.ts +15 -0
  188. package/dist/telemetry/testing.js +52 -0
  189. package/dist/telemetry/testing.js.map +1 -0
  190. package/dist/telemetry.mock-BSsx7L6S.cjs +45 -0
  191. package/dist/telemetry.mock-BSsx7L6S.cjs.map +1 -0
  192. package/dist/telemetry.mock-BZRpy63c.js +40 -0
  193. package/dist/telemetry.mock-BZRpy63c.js.map +1 -0
  194. package/dist/telemetry.mock-C1wXuf-M.d.cts +4 -0
  195. package/dist/telemetry.mock-CdaxofJ7.d.ts +4 -0
  196. package/dist/ui/chart.cjs +6 -0
  197. package/dist/ui/chart.d.cts +34 -0
  198. package/dist/ui/chart.d.ts +34 -0
  199. package/dist/ui/chart.js +6 -0
  200. package/dist/ui/form.cjs +1 -0
  201. package/dist/ui/form.d.cts +23 -0
  202. package/dist/ui/form.d.ts +23 -0
  203. package/dist/ui/form.js +1 -0
  204. package/dist/ui/hooks.cjs +1 -0
  205. package/dist/ui/hooks.d.cts +66 -0
  206. package/dist/ui/hooks.d.ts +66 -0
  207. package/dist/ui/hooks.js +1 -0
  208. package/dist/ui/index.cjs +1 -0
  209. package/dist/ui/index.d.cts +3 -0
  210. package/dist/ui/index.d.ts +3 -0
  211. package/dist/ui/index.js +1 -0
  212. package/dist/ui/styles.css +2 -0
  213. package/dist/ui/utils.cjs +1 -0
  214. package/dist/ui/utils.d.cts +199 -0
  215. package/dist/ui/utils.d.ts +199 -0
  216. package/dist/ui/utils.js +1 -0
  217. package/dist/use-mobile-BbeIMRgE.cjs +1 -0
  218. package/dist/use-mobile-Cdd4Lp7p.js +1 -0
  219. package/dist/use-mobile-ecpyXWz3.d.cts +10 -0
  220. package/dist/use-mobile-ecpyXWz3.d.ts +10 -0
  221. package/dist/verifier-BIBtPCVi.cjs +119 -0
  222. package/dist/verifier-BIBtPCVi.cjs.map +1 -0
  223. package/dist/verifier-DNdy5Ynw.js +90 -0
  224. package/dist/verifier-DNdy5Ynw.js.map +1 -0
  225. package/dist/version-CPunTYCY.js +1 -0
  226. package/dist/version-CfUi3iAV.cjs +1 -0
  227. package/package.json +523 -5
@@ -0,0 +1,257 @@
1
+ import { a as ErrorHeaders, c as ErrorOptions, i as ErrorFunction, l as HttpError, n as ErrorCode, o as ErrorInput, r as ErrorDefinition, s as ErrorInputs, t as DefinedErrors } from "../errors-DxHoXrLd.cjs";
2
+ import { ArgumentsHost, DynamicModule, ExceptionFilter, InjectionToken, ModuleMetadata, OptionalFactoryDependency } from "@nestjs/common";
3
+ /**
4
+ * Codes the filter uses for anything that was not raised with `defineErrors`
5
+ * (Nest's own exceptions, a validation pipe, an unexpected `Error`). They also
6
+ * work with the error functions: `notFound(CommonErrors.NotFound)`.
7
+ *
8
+ * Their codes are reserved: `defineErrors` refuses to redefine one.
9
+ */
10
+ export declare const CommonErrors: DefinedErrors<{
11
+ readonly BadRequest: "Bad request";
12
+ readonly InvalidCursor: "Invalid cursor";
13
+ readonly Unauthorized: "Authentication required";
14
+ readonly Forbidden: "Access denied";
15
+ readonly NotFound: "Resource not found";
16
+ readonly MethodNotAllowed: "Method not allowed";
17
+ readonly RequestTimeout: "Request timed out";
18
+ readonly Conflict: "Conflict with the current state";
19
+ readonly Gone: "Resource is gone";
20
+ readonly PayloadTooLarge: "Payload too large";
21
+ readonly UnsupportedMediaType: "Unsupported media type";
22
+ readonly ValidationFailed: "Validation failed";
23
+ readonly TooManyRequests: "Too many requests";
24
+ readonly RequestFailed: "Request failed";
25
+ readonly InternalError: "Internal server error";
26
+ readonly NotImplemented: "Not implemented";
27
+ readonly BadGateway: "Bad gateway";
28
+ readonly ServiceUnavailable: "Service unavailable";
29
+ readonly GatewayTimeout: "Gateway timeout";
30
+ }>;
31
+ /**
32
+ * Declares the errors an API can raise, once. Each key becomes the `code`;
33
+ * a string value is shorthand for `{ message }`. The codes of `CommonErrors`
34
+ * (`NotFound`, `InternalError`...) are reserved and throw a `TypeError`.
35
+ *
36
+ * @example
37
+ * const Errors = defineErrors({
38
+ * InvalidProjectSlug: 'Invalid project slug',
39
+ * ProjectGone: { message: 'Project was removed', status: 410 },
40
+ * });
41
+ */
42
+ export declare function defineErrors<const Inputs extends ErrorInputs>(inputs: Inputs): DefinedErrors<Inputs>;
43
+ /** 400: the request is malformed. */
44
+ export declare const badRequest: ErrorFunction;
45
+ /** 401: authentication is missing or invalid. */
46
+ export declare const unauthorized: ErrorFunction;
47
+ /** 403: authenticated, but not allowed. */
48
+ export declare const forbidden: ErrorFunction;
49
+ /** 404: the resource does not exist. */
50
+ export declare const notFound: ErrorFunction;
51
+ /** 405: the method is not allowed on this route. */
52
+ export declare const methodNotAllowed: ErrorFunction;
53
+ /** 408: the client took too long to send the request. */
54
+ export declare const requestTimeout: ErrorFunction;
55
+ /** 409: conflicts with the current state of the resource. */
56
+ export declare const conflict: ErrorFunction;
57
+ /** 410: the resource existed and is gone for good. */
58
+ export declare const gone: ErrorFunction;
59
+ /** 413: the payload is larger than the API accepts. */
60
+ export declare const payloadTooLarge: ErrorFunction;
61
+ /** 415: the content type is not supported. */
62
+ export declare const unsupportedMediaType: ErrorFunction;
63
+ /** 422: the data is well formed but fails validation (`extra` has the details). */
64
+ export declare const validation: ErrorFunction;
65
+ /** 429: too many requests. */
66
+ export declare const tooManyRequests: ErrorFunction;
67
+ /** 500: something went wrong on our side. */
68
+ export declare const internalError: ErrorFunction;
69
+ /** 501: the operation is not implemented. */
70
+ export declare const notImplemented: ErrorFunction;
71
+ /** 502: a service we depend on answered badly. */
72
+ export declare const badGateway: ErrorFunction;
73
+ /** 503: temporarily unavailable. */
74
+ export declare const serviceUnavailable: ErrorFunction;
75
+ /** 504: a service we depend on timed out. */
76
+ export declare const gatewayTimeout: ErrorFunction;
77
+ /** What the filter knows about an exception it just handled. */
78
+ interface ErrorContext {
79
+ /** The HTTP status that was sent (always 400-599). */
80
+ status: number;
81
+ /** The `code` that was sent. */
82
+ code: string;
83
+ }
84
+ interface ErrorFilterOptions {
85
+ /**
86
+ * Called for every exception the filter handles, after the status and code
87
+ * are decided. Use it to report to telemetry, for example. A throw or
88
+ * rejection here is swallowed: it never changes the response.
89
+ */
90
+ onError?: (exception: unknown, context: ErrorContext) => void | Promise<void>;
91
+ }
92
+ type ErrorsModuleOptions = ErrorFilterOptions;
93
+ /** `ErrorsModule.forRootAsync` options: resolve `ErrorsModuleOptions` with DI. */
94
+ interface ErrorsModuleAsyncOptions {
95
+ /** Modules whose providers `useFactory` needs. */
96
+ imports?: ModuleMetadata['imports'];
97
+ /** Tokens handed to `useFactory`, in order. */
98
+ inject?: Array<InjectionToken | OptionalFactoryDependency>;
99
+ useFactory: (...dependencies: never[]) => ErrorsModuleOptions | Promise<ErrorsModuleOptions>;
100
+ }
101
+ /**
102
+ * Catches anything thrown during an HTTP request and answers with the error
103
+ * envelope, so a response is always `{ ok: true, ... }` or `{ ok: false, ... }`.
104
+ *
105
+ * - `HttpError` (the error functions): sent as built.
106
+ * - Nest's `HttpException`s: mapped to a `CommonErrors` code; a validation pipe
107
+ * failure becomes `ValidationFailed` with its messages in `extra`.
108
+ * - Any other `Error`, and every 5xx: `InternalError`-style generic body. The
109
+ * stack goes to the log only.
110
+ * - The status is always 400-599; an exception with a lower one becomes 500.
111
+ *
112
+ * @example
113
+ * app.useGlobalFilters(new ErrorFilter());
114
+ */
115
+ export declare class ErrorFilter implements ExceptionFilter {
116
+ private readonly logger;
117
+ private readonly options;
118
+ constructor(options?: ErrorFilterOptions);
119
+ catch(exception: unknown, host: ArgumentsHost): void;
120
+ /** Runs `onError`; whatever it does, the response is unaffected. */
121
+ private notify;
122
+ }
123
+ /**
124
+ * Registers the `ErrorFilter` globally, so no `app.useGlobalFilters()` is
125
+ * needed.
126
+ *
127
+ * @example
128
+ * ErrorsModule.forRoot({ onError: (exception, { status }) => report(exception, status) })
129
+ */
130
+ export declare class ErrorsModule {
131
+ static forRoot(options?: ErrorsModuleOptions): DynamicModule;
132
+ /**
133
+ * Like `forRoot`, with the options resolved through DI (to reach the
134
+ * `Telemetry` instance, for one).
135
+ *
136
+ * @example
137
+ * ErrorsModule.forRootAsync({
138
+ * inject: [Telemetry],
139
+ * useFactory: (telemetry: Telemetry) => ({
140
+ * onError: (exception, { status }) => {
141
+ * if (status >= 500) telemetry.captureException(exception);
142
+ * },
143
+ * }),
144
+ * })
145
+ */
146
+ static forRootAsync(options: ErrorsModuleAsyncOptions): DynamicModule;
147
+ private static build;
148
+ }
149
+ /** A value a cursor can carry. Dates go in as ISO strings. */
150
+ type CursorValue = string | number | boolean | null;
151
+ /**
152
+ * What a cursor remembers about the last item of a page, usually the sort keys
153
+ * (`{ createdAt: '2026-11-05T10:00:00.000Z', id: 'usr_1' }`). Flat and
154
+ * JSON-safe: the cursor goes to the client and comes back.
155
+ */
156
+ interface CursorEdge {
157
+ readonly [key: string]: CursorValue;
158
+ }
159
+ interface CursorOptions {
160
+ /**
161
+ * Signs the cursor with HMAC-SHA256. A signed cursor that was edited, or
162
+ * made with another secret, is rejected, so the client cannot walk outside
163
+ * the filters the server applied. Use the same secret to encode and decode.
164
+ */
165
+ secret?: string | undefined;
166
+ /**
167
+ * Longest cursor, in characters. `encodeCursor` refuses to make one longer
168
+ * and `decodeCursor` refuses to read one, so a cursor that was handed out is
169
+ * always accepted back. Use the same value on both sides.
170
+ * @default 2048
171
+ */
172
+ maxLength?: number | undefined;
173
+ }
174
+ interface DecodeCursorOptions<Edge extends CursorEdge = CursorEdge> extends CursorOptions {
175
+ /**
176
+ * Checks the shape of the edge before it reaches a query: a cursor comes
177
+ * from the client, and a wrong value would turn into a 500 (for example an
178
+ * invalid cast in SQL). Return false (or a type guard) to reject it. A
179
+ * validator that throws also rejects the cursor, instead of turning client
180
+ * input into a 500.
181
+ */
182
+ validate?: ((edge: CursorEdge) => edge is Edge) | ((edge: CursorEdge) => boolean) | undefined;
183
+ }
184
+ /**
185
+ * Reads a cursor made by `encodeCursor`. A missing cursor (`undefined`, `null`
186
+ * or an empty string) means the first page and returns `null`. A cursor that
187
+ * is not valid (malformed, edited, signed with another secret, too long, or
188
+ * rejected by `validate`) throws a 400 `CommonErrors.InvalidCursor`, so the
189
+ * `ErrorFilter` answers it: a tampered cursor must not silently restart the
190
+ * listing.
191
+ *
192
+ * @example
193
+ * const edge = decodeCursor<{ createdAt: string; id: string }>(query.cursor, {
194
+ * validate: (edge): edge is { createdAt: string; id: string } =>
195
+ * typeof edge.createdAt === 'string' && typeof edge.id === 'string',
196
+ * });
197
+ */
198
+ export declare function decodeCursor<Edge extends CursorEdge = CursorEdge>(cursor: string | null | undefined, options?: DecodeCursorOptions<Edge>): Edge | null;
199
+ /**
200
+ * Turns the edge of a page (the sort keys of its last item) into an opaque
201
+ * cursor: base64url of the JSON, plus an HMAC signature when `secret` is set.
202
+ * Hand it to the client as `pagination.next`; `decodeCursor` reads it back.
203
+ *
204
+ * It throws a `TypeError` for an edge that `decodeCursor` would not accept
205
+ * (not a flat object, `NaN`, `undefined`, a nested value, a date, a `__proto__`
206
+ * key) or for a cursor longer than `maxLength`: a bug in the caller shows up
207
+ * here, not as a 400 on the next page.
208
+ *
209
+ * @example
210
+ * encodeCursor({ createdAt: last.createdAt.toISOString(), id: last.id });
211
+ */
212
+ export declare function encodeCursor(edge: CursorEdge, options?: CursorOptions): string;
213
+ /** Cursor pagination. `persist` is true while there is more to fetch. */
214
+ interface Pagination {
215
+ /** Cursor of the previous page. */
216
+ before?: string | undefined;
217
+ /** Cursor of the next page. */
218
+ next?: string | undefined;
219
+ /** True when `next` has data, false when this is the last page. */
220
+ persist?: boolean | undefined;
221
+ }
222
+ interface OkResponse<Data> {
223
+ ok: true;
224
+ data: Data;
225
+ pagination?: Pagination;
226
+ }
227
+ interface ErrorBody {
228
+ /** Always a code defined with `defineErrors` (or a `CommonErrors` one). */
229
+ code: string;
230
+ message: string;
231
+ /** Anything extra about the failure, e.g. the validation errors. */
232
+ extra?: unknown;
233
+ }
234
+ interface ErrorResponse {
235
+ ok: false;
236
+ error: ErrorBody;
237
+ }
238
+ /** The envelope every API answers with. */
239
+ type APIResponse<Data> = OkResponse<Data> | ErrorResponse;
240
+ /** Builds the error envelope for `definition`. It carries no HTTP status. */
241
+ export declare function error(definition: Pick<ErrorDefinition, 'code' | 'message'>, extra?: unknown): ErrorResponse;
242
+ /** Whether `response` is a success envelope. */
243
+ export declare function isOk<Data>(response: APIResponse<Data>): response is OkResponse<Data>;
244
+ export declare function isOk(response: unknown): response is OkResponse<unknown>;
245
+ /** Whether `response` is an error envelope. */
246
+ export declare function isError(response: unknown): response is ErrorResponse;
247
+ /**
248
+ * Builds the success envelope. With `pagination`, `persist` is derived from
249
+ * `next` unless you pass it.
250
+ */
251
+ export declare function ok<Data>(data: Data, pagination?: Pagination): OkResponse<Data>;
252
+ /** Header that carries the request id on every API response. */
253
+ export declare const REQUEST_ID_HEADER = "x-request-id";
254
+ /** A new request id (UUID v4). */
255
+ export declare function generateRequestId(): string;
256
+ export { type APIResponse, type CursorEdge, type CursorOptions, type CursorValue, type DecodeCursorOptions, type DefinedErrors, type ErrorBody, type ErrorCode, type ErrorContext, type ErrorDefinition, type ErrorFilterOptions, type ErrorFunction, type ErrorHeaders, type ErrorInput, type ErrorInputs, type ErrorOptions, type ErrorResponse, type ErrorsModuleAsyncOptions, type ErrorsModuleOptions, HttpError, type OkResponse, type Pagination };
257
+ //# sourceMappingURL=index.d.cts.map
@@ -0,0 +1,257 @@
1
+ import { a as ErrorHeaders, c as ErrorOptions, i as ErrorFunction, l as HttpError, n as ErrorCode, o as ErrorInput, r as ErrorDefinition, s as ErrorInputs, t as DefinedErrors } from "../errors-DxHoXrLd.js";
2
+ import { ArgumentsHost, DynamicModule, ExceptionFilter, InjectionToken, ModuleMetadata, OptionalFactoryDependency } from "@nestjs/common";
3
+ /**
4
+ * Codes the filter uses for anything that was not raised with `defineErrors`
5
+ * (Nest's own exceptions, a validation pipe, an unexpected `Error`). They also
6
+ * work with the error functions: `notFound(CommonErrors.NotFound)`.
7
+ *
8
+ * Their codes are reserved: `defineErrors` refuses to redefine one.
9
+ */
10
+ export declare const CommonErrors: DefinedErrors<{
11
+ readonly BadRequest: "Bad request";
12
+ readonly InvalidCursor: "Invalid cursor";
13
+ readonly Unauthorized: "Authentication required";
14
+ readonly Forbidden: "Access denied";
15
+ readonly NotFound: "Resource not found";
16
+ readonly MethodNotAllowed: "Method not allowed";
17
+ readonly RequestTimeout: "Request timed out";
18
+ readonly Conflict: "Conflict with the current state";
19
+ readonly Gone: "Resource is gone";
20
+ readonly PayloadTooLarge: "Payload too large";
21
+ readonly UnsupportedMediaType: "Unsupported media type";
22
+ readonly ValidationFailed: "Validation failed";
23
+ readonly TooManyRequests: "Too many requests";
24
+ readonly RequestFailed: "Request failed";
25
+ readonly InternalError: "Internal server error";
26
+ readonly NotImplemented: "Not implemented";
27
+ readonly BadGateway: "Bad gateway";
28
+ readonly ServiceUnavailable: "Service unavailable";
29
+ readonly GatewayTimeout: "Gateway timeout";
30
+ }>;
31
+ /**
32
+ * Declares the errors an API can raise, once. Each key becomes the `code`;
33
+ * a string value is shorthand for `{ message }`. The codes of `CommonErrors`
34
+ * (`NotFound`, `InternalError`...) are reserved and throw a `TypeError`.
35
+ *
36
+ * @example
37
+ * const Errors = defineErrors({
38
+ * InvalidProjectSlug: 'Invalid project slug',
39
+ * ProjectGone: { message: 'Project was removed', status: 410 },
40
+ * });
41
+ */
42
+ export declare function defineErrors<const Inputs extends ErrorInputs>(inputs: Inputs): DefinedErrors<Inputs>;
43
+ /** 400: the request is malformed. */
44
+ export declare const badRequest: ErrorFunction;
45
+ /** 401: authentication is missing or invalid. */
46
+ export declare const unauthorized: ErrorFunction;
47
+ /** 403: authenticated, but not allowed. */
48
+ export declare const forbidden: ErrorFunction;
49
+ /** 404: the resource does not exist. */
50
+ export declare const notFound: ErrorFunction;
51
+ /** 405: the method is not allowed on this route. */
52
+ export declare const methodNotAllowed: ErrorFunction;
53
+ /** 408: the client took too long to send the request. */
54
+ export declare const requestTimeout: ErrorFunction;
55
+ /** 409: conflicts with the current state of the resource. */
56
+ export declare const conflict: ErrorFunction;
57
+ /** 410: the resource existed and is gone for good. */
58
+ export declare const gone: ErrorFunction;
59
+ /** 413: the payload is larger than the API accepts. */
60
+ export declare const payloadTooLarge: ErrorFunction;
61
+ /** 415: the content type is not supported. */
62
+ export declare const unsupportedMediaType: ErrorFunction;
63
+ /** 422: the data is well formed but fails validation (`extra` has the details). */
64
+ export declare const validation: ErrorFunction;
65
+ /** 429: too many requests. */
66
+ export declare const tooManyRequests: ErrorFunction;
67
+ /** 500: something went wrong on our side. */
68
+ export declare const internalError: ErrorFunction;
69
+ /** 501: the operation is not implemented. */
70
+ export declare const notImplemented: ErrorFunction;
71
+ /** 502: a service we depend on answered badly. */
72
+ export declare const badGateway: ErrorFunction;
73
+ /** 503: temporarily unavailable. */
74
+ export declare const serviceUnavailable: ErrorFunction;
75
+ /** 504: a service we depend on timed out. */
76
+ export declare const gatewayTimeout: ErrorFunction;
77
+ /** What the filter knows about an exception it just handled. */
78
+ interface ErrorContext {
79
+ /** The HTTP status that was sent (always 400-599). */
80
+ status: number;
81
+ /** The `code` that was sent. */
82
+ code: string;
83
+ }
84
+ interface ErrorFilterOptions {
85
+ /**
86
+ * Called for every exception the filter handles, after the status and code
87
+ * are decided. Use it to report to telemetry, for example. A throw or
88
+ * rejection here is swallowed: it never changes the response.
89
+ */
90
+ onError?: (exception: unknown, context: ErrorContext) => void | Promise<void>;
91
+ }
92
+ type ErrorsModuleOptions = ErrorFilterOptions;
93
+ /** `ErrorsModule.forRootAsync` options: resolve `ErrorsModuleOptions` with DI. */
94
+ interface ErrorsModuleAsyncOptions {
95
+ /** Modules whose providers `useFactory` needs. */
96
+ imports?: ModuleMetadata['imports'];
97
+ /** Tokens handed to `useFactory`, in order. */
98
+ inject?: Array<InjectionToken | OptionalFactoryDependency>;
99
+ useFactory: (...dependencies: never[]) => ErrorsModuleOptions | Promise<ErrorsModuleOptions>;
100
+ }
101
+ /**
102
+ * Catches anything thrown during an HTTP request and answers with the error
103
+ * envelope, so a response is always `{ ok: true, ... }` or `{ ok: false, ... }`.
104
+ *
105
+ * - `HttpError` (the error functions): sent as built.
106
+ * - Nest's `HttpException`s: mapped to a `CommonErrors` code; a validation pipe
107
+ * failure becomes `ValidationFailed` with its messages in `extra`.
108
+ * - Any other `Error`, and every 5xx: `InternalError`-style generic body. The
109
+ * stack goes to the log only.
110
+ * - The status is always 400-599; an exception with a lower one becomes 500.
111
+ *
112
+ * @example
113
+ * app.useGlobalFilters(new ErrorFilter());
114
+ */
115
+ export declare class ErrorFilter implements ExceptionFilter {
116
+ private readonly logger;
117
+ private readonly options;
118
+ constructor(options?: ErrorFilterOptions);
119
+ catch(exception: unknown, host: ArgumentsHost): void;
120
+ /** Runs `onError`; whatever it does, the response is unaffected. */
121
+ private notify;
122
+ }
123
+ /**
124
+ * Registers the `ErrorFilter` globally, so no `app.useGlobalFilters()` is
125
+ * needed.
126
+ *
127
+ * @example
128
+ * ErrorsModule.forRoot({ onError: (exception, { status }) => report(exception, status) })
129
+ */
130
+ export declare class ErrorsModule {
131
+ static forRoot(options?: ErrorsModuleOptions): DynamicModule;
132
+ /**
133
+ * Like `forRoot`, with the options resolved through DI (to reach the
134
+ * `Telemetry` instance, for one).
135
+ *
136
+ * @example
137
+ * ErrorsModule.forRootAsync({
138
+ * inject: [Telemetry],
139
+ * useFactory: (telemetry: Telemetry) => ({
140
+ * onError: (exception, { status }) => {
141
+ * if (status >= 500) telemetry.captureException(exception);
142
+ * },
143
+ * }),
144
+ * })
145
+ */
146
+ static forRootAsync(options: ErrorsModuleAsyncOptions): DynamicModule;
147
+ private static build;
148
+ }
149
+ /** A value a cursor can carry. Dates go in as ISO strings. */
150
+ type CursorValue = string | number | boolean | null;
151
+ /**
152
+ * What a cursor remembers about the last item of a page, usually the sort keys
153
+ * (`{ createdAt: '2026-11-05T10:00:00.000Z', id: 'usr_1' }`). Flat and
154
+ * JSON-safe: the cursor goes to the client and comes back.
155
+ */
156
+ interface CursorEdge {
157
+ readonly [key: string]: CursorValue;
158
+ }
159
+ interface CursorOptions {
160
+ /**
161
+ * Signs the cursor with HMAC-SHA256. A signed cursor that was edited, or
162
+ * made with another secret, is rejected, so the client cannot walk outside
163
+ * the filters the server applied. Use the same secret to encode and decode.
164
+ */
165
+ secret?: string | undefined;
166
+ /**
167
+ * Longest cursor, in characters. `encodeCursor` refuses to make one longer
168
+ * and `decodeCursor` refuses to read one, so a cursor that was handed out is
169
+ * always accepted back. Use the same value on both sides.
170
+ * @default 2048
171
+ */
172
+ maxLength?: number | undefined;
173
+ }
174
+ interface DecodeCursorOptions<Edge extends CursorEdge = CursorEdge> extends CursorOptions {
175
+ /**
176
+ * Checks the shape of the edge before it reaches a query: a cursor comes
177
+ * from the client, and a wrong value would turn into a 500 (for example an
178
+ * invalid cast in SQL). Return false (or a type guard) to reject it. A
179
+ * validator that throws also rejects the cursor, instead of turning client
180
+ * input into a 500.
181
+ */
182
+ validate?: ((edge: CursorEdge) => edge is Edge) | ((edge: CursorEdge) => boolean) | undefined;
183
+ }
184
+ /**
185
+ * Reads a cursor made by `encodeCursor`. A missing cursor (`undefined`, `null`
186
+ * or an empty string) means the first page and returns `null`. A cursor that
187
+ * is not valid (malformed, edited, signed with another secret, too long, or
188
+ * rejected by `validate`) throws a 400 `CommonErrors.InvalidCursor`, so the
189
+ * `ErrorFilter` answers it: a tampered cursor must not silently restart the
190
+ * listing.
191
+ *
192
+ * @example
193
+ * const edge = decodeCursor<{ createdAt: string; id: string }>(query.cursor, {
194
+ * validate: (edge): edge is { createdAt: string; id: string } =>
195
+ * typeof edge.createdAt === 'string' && typeof edge.id === 'string',
196
+ * });
197
+ */
198
+ export declare function decodeCursor<Edge extends CursorEdge = CursorEdge>(cursor: string | null | undefined, options?: DecodeCursorOptions<Edge>): Edge | null;
199
+ /**
200
+ * Turns the edge of a page (the sort keys of its last item) into an opaque
201
+ * cursor: base64url of the JSON, plus an HMAC signature when `secret` is set.
202
+ * Hand it to the client as `pagination.next`; `decodeCursor` reads it back.
203
+ *
204
+ * It throws a `TypeError` for an edge that `decodeCursor` would not accept
205
+ * (not a flat object, `NaN`, `undefined`, a nested value, a date, a `__proto__`
206
+ * key) or for a cursor longer than `maxLength`: a bug in the caller shows up
207
+ * here, not as a 400 on the next page.
208
+ *
209
+ * @example
210
+ * encodeCursor({ createdAt: last.createdAt.toISOString(), id: last.id });
211
+ */
212
+ export declare function encodeCursor(edge: CursorEdge, options?: CursorOptions): string;
213
+ /** Cursor pagination. `persist` is true while there is more to fetch. */
214
+ interface Pagination {
215
+ /** Cursor of the previous page. */
216
+ before?: string | undefined;
217
+ /** Cursor of the next page. */
218
+ next?: string | undefined;
219
+ /** True when `next` has data, false when this is the last page. */
220
+ persist?: boolean | undefined;
221
+ }
222
+ interface OkResponse<Data> {
223
+ ok: true;
224
+ data: Data;
225
+ pagination?: Pagination;
226
+ }
227
+ interface ErrorBody {
228
+ /** Always a code defined with `defineErrors` (or a `CommonErrors` one). */
229
+ code: string;
230
+ message: string;
231
+ /** Anything extra about the failure, e.g. the validation errors. */
232
+ extra?: unknown;
233
+ }
234
+ interface ErrorResponse {
235
+ ok: false;
236
+ error: ErrorBody;
237
+ }
238
+ /** The envelope every API answers with. */
239
+ type APIResponse<Data> = OkResponse<Data> | ErrorResponse;
240
+ /** Builds the error envelope for `definition`. It carries no HTTP status. */
241
+ export declare function error(definition: Pick<ErrorDefinition, 'code' | 'message'>, extra?: unknown): ErrorResponse;
242
+ /** Whether `response` is a success envelope. */
243
+ export declare function isOk<Data>(response: APIResponse<Data>): response is OkResponse<Data>;
244
+ export declare function isOk(response: unknown): response is OkResponse<unknown>;
245
+ /** Whether `response` is an error envelope. */
246
+ export declare function isError(response: unknown): response is ErrorResponse;
247
+ /**
248
+ * Builds the success envelope. With `pagination`, `persist` is derived from
249
+ * `next` unless you pass it.
250
+ */
251
+ export declare function ok<Data>(data: Data, pagination?: Pagination): OkResponse<Data>;
252
+ /** Header that carries the request id on every API response. */
253
+ export declare const REQUEST_ID_HEADER = "x-request-id";
254
+ /** A new request id (UUID v4). */
255
+ export declare function generateRequestId(): string;
256
+ export { type APIResponse, type CursorEdge, type CursorOptions, type CursorValue, type DecodeCursorOptions, type DefinedErrors, type ErrorBody, type ErrorCode, type ErrorContext, type ErrorDefinition, type ErrorFilterOptions, type ErrorFunction, type ErrorHeaders, type ErrorInput, type ErrorInputs, type ErrorOptions, type ErrorResponse, type ErrorsModuleAsyncOptions, type ErrorsModuleOptions, HttpError, type OkResponse, type Pagination };
257
+ //# sourceMappingURL=index.d.ts.map