@classytic/arc 2.11.4 → 2.13.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 (166) hide show
  1. package/README.md +16 -12
  2. package/dist/{BaseController-swXruJ2_.mjs → BaseController-DX_T-bDB.mjs} +388 -423
  3. package/dist/EventTransport-CT_52aWU.d.mts +34 -0
  4. package/dist/EventTransport-DLWoUMHy.mjs +103 -0
  5. package/dist/{ResourceRegistry-DkAeAuTX.mjs → ResourceRegistry-CTERg_2x.mjs} +139 -66
  6. package/dist/audit/index.d.mts +2 -2
  7. package/dist/audit/index.mjs +1 -1
  8. package/dist/auth/audit.d.mts +199 -0
  9. package/dist/auth/audit.mjs +288 -0
  10. package/dist/auth/index.d.mts +3 -3
  11. package/dist/auth/index.mjs +117 -191
  12. package/dist/{betterAuthOpenApi-DwxtK3uG.mjs → betterAuthOpenApi--M_i87dQ.mjs} +1 -1
  13. package/dist/buildHandler-olo-gt94.mjs +610 -0
  14. package/dist/cache/index.mjs +3 -3
  15. package/dist/cli/commands/describe.d.mts +89 -13
  16. package/dist/cli/commands/describe.mjs +56 -2
  17. package/dist/cli/commands/docs.mjs +2 -2
  18. package/dist/cli/commands/generate.mjs +147 -48
  19. package/dist/cli/commands/init.d.mts +13 -0
  20. package/dist/cli/commands/init.mjs +130 -87
  21. package/dist/cli/commands/introspect.mjs +8 -1
  22. package/dist/context/index.mjs +1 -1
  23. package/dist/core/index.d.mts +3 -3
  24. package/dist/core/index.mjs +5 -5
  25. package/dist/core-D72ia0EH.mjs +1399 -0
  26. package/dist/{createActionRouter-CIKOcNA7.mjs → createActionRouter-CEvzKcy8.mjs} +7 -20
  27. package/dist/createAggregationRouter-CyecOxnO.mjs +114 -0
  28. package/dist/{createApp-C9bRrqlX.mjs → createApp-XX2-N0Yd.mjs} +28 -22
  29. package/dist/{defineEvent-D1Ky9M1D.mjs → defineEvent-D5h7EvAx.mjs} +1 -1
  30. package/dist/docs/index.d.mts +1 -1
  31. package/dist/docs/index.mjs +2 -2
  32. package/dist/{elevation-DOFoxoDs.mjs → elevation-DgoeTyfX.mjs} +1 -1
  33. package/dist/errorHandler-Bk-AGhkU.mjs +174 -0
  34. package/dist/errorHandler-DFr45ZG4.d.mts +45 -0
  35. package/dist/errors-j4aJm1Wg.mjs +184 -0
  36. package/dist/{eventPlugin-Cts2-Tfj.mjs → eventPlugin-CaKTYkYM.mjs} +28 -4
  37. package/dist/{eventPlugin-DDJoNEPL.d.mts → eventPlugin-qXpqTebY.d.mts} +24 -1
  38. package/dist/events/index.d.mts +6 -6
  39. package/dist/events/index.mjs +11 -35
  40. package/dist/events/transports/redis-stream-entry.d.mts +1 -1
  41. package/dist/events/transports/redis.d.mts +1 -1
  42. package/dist/factory/index.d.mts +2 -2
  43. package/dist/factory/index.mjs +2 -2
  44. package/dist/{fields-BRjxOAFp.d.mts → fields-COhcH3fk.d.mts} +23 -2
  45. package/dist/hooks/index.d.mts +1 -1
  46. package/dist/hooks/index.mjs +1 -1
  47. package/dist/idempotency/index.d.mts +1 -1
  48. package/dist/idempotency/index.mjs +1 -20
  49. package/dist/idempotency/redis.mjs +1 -1
  50. package/dist/{index-rHjXmJar.d.mts → index-BTqLEvhu.d.mts} +163 -3
  51. package/dist/{index-CXXRbnf8.d.mts → index-BtW7qYwa.d.mts} +660 -326
  52. package/dist/{index-m8mOOlFW.d.mts → index-Ds61mrJE.d.mts} +50 -4
  53. package/dist/{index-D9t1KNaB.d.mts → index-Dz5IKsrE.d.mts} +360 -219
  54. package/dist/index.d.mts +6 -7
  55. package/dist/index.mjs +9 -10
  56. package/dist/integrations/event-gateway.d.mts +1 -1
  57. package/dist/integrations/event-gateway.mjs +1 -1
  58. package/dist/integrations/index.d.mts +1 -1
  59. package/dist/integrations/mcp/index.d.mts +2 -2
  60. package/dist/integrations/mcp/index.mjs +1 -1
  61. package/dist/integrations/mcp/testing.d.mts +1 -1
  62. package/dist/integrations/mcp/testing.mjs +1 -1
  63. package/dist/integrations/streamline.d.mts +60 -11
  64. package/dist/integrations/streamline.mjs +75 -85
  65. package/dist/integrations/websocket.mjs +2 -8
  66. package/dist/middleware/index.d.mts +1 -1
  67. package/dist/middleware/index.mjs +2 -2
  68. package/dist/migrations/index.d.mts +23 -3
  69. package/dist/migrations/index.mjs +0 -7
  70. package/dist/{multipartBody-CvTR1Un6.mjs → multipartBody-BOvVSVCD.mjs} +11 -8
  71. package/dist/{openapi-D7G1V7ex.mjs → openapi-CiOMVW1p.mjs} +143 -13
  72. package/dist/org/index.d.mts +2 -2
  73. package/dist/org/index.mjs +1 -1
  74. package/dist/permissions/index.d.mts +3 -3
  75. package/dist/permissions/index.mjs +3 -3
  76. package/dist/{permissions-gd_aUWrR.mjs → permissions-ohQyv50e.mjs} +404 -176
  77. package/dist/{pipe-DVoIheVC.mjs → pipe-Zr0KXjQe.mjs} +1 -1
  78. package/dist/pipeline/index.d.mts +1 -1
  79. package/dist/pipeline/index.mjs +1 -1
  80. package/dist/plugins/index.d.mts +16 -31
  81. package/dist/plugins/index.mjs +33 -13
  82. package/dist/plugins/response-cache.mjs +1 -1
  83. package/dist/plugins/tracing-entry.mjs +1 -1
  84. package/dist/presets/filesUpload.d.mts +4 -4
  85. package/dist/presets/filesUpload.mjs +6 -9
  86. package/dist/presets/index.d.mts +1 -1
  87. package/dist/presets/index.mjs +1 -1
  88. package/dist/presets/multiTenant.d.mts +1 -1
  89. package/dist/presets/multiTenant.mjs +2 -2
  90. package/dist/presets/search.d.mts +2 -2
  91. package/dist/presets/search.mjs +6 -8
  92. package/dist/{presets-Z7P5w4gF.mjs → presets-BbkjdPeH.mjs} +6 -28
  93. package/dist/{queryCachePlugin-Bq6bO6vc.mjs → queryCachePlugin-m1XsgAIJ.mjs} +3 -3
  94. package/dist/{redis-stream-xTGxB2bm.d.mts → redis-stream-D6HzR1Z_.d.mts} +1 -1
  95. package/dist/registry/index.d.mts +1 -1
  96. package/dist/registry/index.mjs +2 -2
  97. package/dist/{replyHelpers-ByllIXXV.mjs → replyHelpers-CK-FNO8E.mjs} +3 -21
  98. package/dist/{resourceToTools-CxNmI6xF.mjs → resourceToTools-C5coh64w.mjs} +224 -71
  99. package/dist/{routerShared-BqLRb5l7.mjs → routerShared-D6_fEGHh.mjs} +40 -36
  100. package/dist/{schemaIR-Dy2p4MxS.mjs → schemaIR-7Vl611Qs.mjs} +1 -1
  101. package/dist/schemas/index.d.mts +100 -30
  102. package/dist/schemas/index.mjs +86 -29
  103. package/dist/scim/index.d.mts +264 -0
  104. package/dist/scim/index.mjs +963 -0
  105. package/dist/scope/index.d.mts +3 -3
  106. package/dist/scope/index.mjs +4 -4
  107. package/dist/{sse-V7aXc3bW.mjs → sse-Bz-5ZeTt.mjs} +1 -1
  108. package/dist/{store-helpers-Cp4uKC1U.mjs → store-helpers-BkIN9-vu.mjs} +1 -1
  109. package/dist/testing/index.d.mts +2 -8
  110. package/dist/testing/index.mjs +16 -24
  111. package/dist/types/index.d.mts +4 -4
  112. package/dist/{types-D7KpfiL1.d.mts → types-BvqwCCSx.d.mts} +73 -25
  113. package/dist/{types-DDyTPc6y.d.mts → types-CTYvcwHe.d.mts} +195 -1
  114. package/dist/{types-AOD8fxIw.mjs → types-C_s5moIu.mjs} +117 -1
  115. package/dist/{types-BQ9TJQNy.d.mts → types-DQHFc8PM.d.mts} +1 -1
  116. package/dist/utils/index.d.mts +2 -2
  117. package/dist/utils/index.mjs +5 -5
  118. package/dist/{utils-CcYTj09l.mjs → utils-_h9B3c57.mjs} +1269 -1334
  119. package/dist/{versioning-DsglKfM_.d.mts → versioning-DTTvc80y.d.mts} +1 -1
  120. package/package.json +24 -34
  121. package/skills/arc/SKILL.md +147 -51
  122. package/skills/arc/references/agent-auth.md +238 -0
  123. package/skills/arc/references/api-reference.md +187 -0
  124. package/skills/arc/references/auth.md +354 -7
  125. package/skills/arc/references/enterprise-auth.md +94 -0
  126. package/skills/arc/references/events.md +8 -6
  127. package/skills/arc/references/mcp.md +2 -2
  128. package/skills/arc/references/multi-tenancy.md +11 -2
  129. package/skills/arc/references/production.md +10 -9
  130. package/skills/arc/references/scim.md +247 -0
  131. package/skills/arc/references/testing.md +1 -1
  132. package/skills/arc-code-review/SKILL.md +141 -0
  133. package/skills/arc-code-review/references/anti-patterns.md +911 -0
  134. package/skills/arc-code-review/references/arc-cheatsheet.md +380 -0
  135. package/skills/arc-code-review/references/migration-recipes.md +700 -0
  136. package/skills/arc-code-review/references/mongokit-migration.md +386 -0
  137. package/skills/arc-code-review/references/scaffolding.md +230 -0
  138. package/skills/arc-code-review/references/severity.md +127 -0
  139. package/dist/EventTransport-BFQjw9pB.mjs +0 -133
  140. package/dist/EventTransport-CYNUXdCJ.d.mts +0 -293
  141. package/dist/adapters/index.d.mts +0 -3
  142. package/dist/adapters/index.mjs +0 -2
  143. package/dist/adapters-DUUiiimH.mjs +0 -964
  144. package/dist/auth/mongoose.d.mts +0 -191
  145. package/dist/auth/mongoose.mjs +0 -73
  146. package/dist/core-CbcQRIch.mjs +0 -1054
  147. package/dist/errorHandler-BQm8ZxTK.mjs +0 -173
  148. package/dist/errorHandler-DEWmGWPz.d.mts +0 -114
  149. package/dist/errors-D5c-5BJL.mjs +0 -232
  150. package/dist/index-Rg8axYPz.d.mts +0 -370
  151. /package/dist/{HookSystem-CGsMd6oK.mjs → HookSystem-Iiebom92.mjs} +0 -0
  152. /package/dist/{actionPermissions-sUUKDhtP.mjs → actionPermissions-CyUkQu6O.mjs} +0 -0
  153. /package/dist/{caching-CheW3m-S.mjs → caching-SM8gghN6.mjs} +0 -0
  154. /package/dist/{constants-BhY1OHoH.mjs → constants-Cxde4rpC.mjs} +0 -0
  155. /package/dist/{elevation-BQQXZ_VR.d.mts → elevation-BXOWoGCF.d.mts} +0 -0
  156. /package/dist/{keys-CARyUjiR.mjs → keys-CGcCbNyu.mjs} +0 -0
  157. /package/dist/{loadResources-CPpkyKfM.mjs → loadResources-DBMQg_Aj.mjs} +0 -0
  158. /package/dist/{memory-DikHSvWa.mjs → memory-UBydS5ku.mjs} +0 -0
  159. /package/dist/{metrics-Csh4nsvv.mjs → metrics-Qnvwc-LQ.mjs} +0 -0
  160. /package/dist/{pluralize-CWP6MB39.mjs → pluralize-DQgqgifU.mjs} +0 -0
  161. /package/dist/{registry-D63ee7fl.mjs → registry-I-ogLgL9.mjs} +0 -0
  162. /package/dist/{requestContext-C5XeK3VA.mjs → requestContext-SSaaTgW8.mjs} +0 -0
  163. /package/dist/{schemaConverter-B0oKLuqI.mjs → schemaConverter-De34B1ZG.mjs} +0 -0
  164. /package/dist/{typeGuards-CcFZXgU7.mjs → typeGuards-BzkXkvVv.mjs} +0 -0
  165. /package/dist/{types-DV9WDfeg.mjs → types-D57iXYb8.mjs} +0 -0
  166. /package/dist/{versioning-CGPjkqAg.mjs → versioning-BUrT5aP4.mjs} +0 -0
@@ -1,63 +1,37 @@
1
- import { $ as OpenApiSchemas, Pt as AnyRecord, S as QueryParserInterface, at as ResourceConfig, b as ParsedQuery, zt as UserLike } from "./index-CXXRbnf8.mjs";
2
- import { n as ErrorMapper } from "./errorHandler-DEWmGWPz.mjs";
1
+ import { $ as OpenApiSchemas, S as QueryParserInterface, Wt as AnyRecord, Yt as UserLike, at as ResourceConfig, b as ParsedQuery } from "./index-BtW7qYwa.mjs";
2
+ import { n as ErrorMapper } from "./errorHandler-DFr45ZG4.mjs";
3
+ import { HttpError, errorContractSchema as errorContractSchema$1, errorDetailSchema as errorDetailSchema$1 } from "@classytic/repo-core/errors";
3
4
  import { FastifyInstance, FastifyReply, FastifyRequest, RouteHandlerMethod } from "fastify";
4
5
 
5
6
  //#region src/utils/errors.d.ts
6
- /**
7
- * Error Classes
8
- *
9
- * Standard error types for the Arc framework.
10
- */
11
- interface ErrorDetails {
7
+ interface ErrorOptions {
12
8
  code?: string;
13
9
  statusCode?: number;
14
10
  details?: Record<string, unknown>;
15
11
  cause?: Error;
16
- requestId?: string;
17
12
  }
18
13
  /**
19
- * Base Arc Error
20
- *
21
- * All Arc errors extend this class and produce a consistent error envelope:
22
- * {
23
- * success: false,
24
- * error: "Human-readable message",
25
- * code: "MACHINE_CODE",
26
- * requestId: "uuid", // For tracing
27
- * timestamp: "ISO date", // When error occurred
28
- * details: { ... } // Additional context
29
- * }
14
+ * Base Arc Error. Implements the canonical `HttpError` contract — `status`
15
+ * mirrors `statusCode` and `meta` mirrors `details`, so consumers reading
16
+ * either name see the same value without adapter glue.
30
17
  */
31
- declare class ArcError extends Error {
18
+ declare class ArcError extends Error implements HttpError {
32
19
  name: string;
33
20
  readonly code: string;
34
21
  readonly statusCode: number;
35
22
  readonly details?: Record<string, unknown>;
36
23
  readonly cause?: Error;
37
- readonly timestamp: string;
38
- requestId?: string;
39
- constructor(message: string, options?: ErrorDetails);
40
- /**
41
- * Set request ID (typically from request context)
42
- */
43
- withRequestId(requestId: string): this;
44
- /**
45
- * Convert to JSON response.
46
- * Includes cause chain when present for debugging visibility.
47
- */
48
- toJSON(): Record<string, unknown>;
24
+ constructor(message: string, options?: ErrorOptions);
25
+ /** `HttpError.status` mirror — repo-core's `toErrorContract` reads this. */
26
+ get status(): number;
27
+ /** `HttpError.meta` mirror — `details` under the canonical name. */
28
+ get meta(): Record<string, unknown> | undefined;
49
29
  }
50
- /**
51
- * Not Found Error - 404
52
- */
53
30
  declare class NotFoundError extends ArcError {
54
31
  constructor(resource: string, identifier?: string);
55
32
  }
56
- /**
57
- * Validation Error - 400
58
- */
59
33
  declare class ValidationError extends ArcError {
60
- readonly errors: Array<{
34
+ readonly errors: ReadonlyArray<{
61
35
  field: string;
62
36
  message: string;
63
37
  }>;
@@ -66,29 +40,17 @@ declare class ValidationError extends ArcError {
66
40
  message: string;
67
41
  }>);
68
42
  }
69
- /**
70
- * Unauthorized Error - 401
71
- */
72
43
  declare class UnauthorizedError extends ArcError {
73
44
  constructor(message?: string);
74
45
  }
75
- /**
76
- * Forbidden Error - 403
77
- */
78
46
  declare class ForbiddenError extends ArcError {
79
47
  constructor(message?: string);
80
48
  }
81
- /**
82
- * Conflict Error - 409
83
- */
84
49
  declare class ConflictError extends ArcError {
85
50
  constructor(message: string, field?: string);
86
51
  }
87
- /**
88
- * Organization Required Error - 403
89
- */
90
52
  declare class OrgRequiredError extends ArcError {
91
- readonly organizations?: Array<{
53
+ readonly organizations?: ReadonlyArray<{
92
54
  id: string;
93
55
  roles?: string[];
94
56
  }>;
@@ -97,48 +59,36 @@ declare class OrgRequiredError extends ArcError {
97
59
  roles?: string[];
98
60
  }>);
99
61
  }
100
- /**
101
- * Organization Access Denied Error - 403
102
- */
103
62
  declare class OrgAccessDeniedError extends ArcError {
104
63
  constructor(orgId?: string);
105
64
  }
106
- /**
107
- * Rate Limit Error - 429
108
- */
109
65
  declare class RateLimitError extends ArcError {
110
66
  readonly retryAfter?: number;
111
67
  constructor(message?: string, retryAfter?: number);
112
68
  }
113
- /**
114
- * Service Unavailable Error - 503
115
- */
116
69
  declare class ServiceUnavailableError extends ArcError {
117
70
  constructor(message?: string);
118
71
  }
119
72
  /**
120
- * Create error from status code
73
+ * Quick `ArcError` constructor when the bundled subclasses don't fit.
74
+ *
75
+ * If `details.code` is a string, it's lifted to the top-level `error.code`
76
+ * (the canonical wire slot for business signals — `'ORG_CONTEXT_REQUIRED'`,
77
+ * `'ALL_FIELDS_STRIPPED'`, etc). The same code stays in `details` so
78
+ * in-process consumers reading `error.details.code` still work. Without
79
+ * this lift, business codes get buried in `details` and the wire envelope
80
+ * carries only the status-derived `arc.forbidden` / `arc.bad_request`
81
+ * fallback — `repo-core`'s `toErrorContract` doesn't surface free-form
82
+ * `details` objects (its `details[]` array is reserved for validation /
83
+ * duplicate-key items).
121
84
  */
122
85
  declare function createError(statusCode: number, message: string, details?: Record<string, unknown>): ArcError;
123
86
  /**
124
- * Create a domain-specific error with automatic HTTP status mapping.
125
- *
126
- * Eliminates manual `if (err.code === 'X') return status` boilerplate.
127
- * Arc's error handler automatically maps `statusCode` to HTTP response.
128
- *
129
- * @example
130
- * ```typescript
131
- * import { createDomainError } from '@classytic/arc';
132
- *
133
- * throw createDomainError('MEMBER_NOT_FOUND', 'Member does not exist', 404);
134
- * throw createDomainError('SELF_REFERRAL', 'Cannot refer yourself', 422);
135
- * throw createDomainError('INSUFFICIENT_BALANCE', 'Not enough credits', 402, { balance: 0 });
136
- * ```
87
+ * Domain-error escape hatch. Use a hierarchical code that scopes the error
88
+ * to your package (`'commerce.cart.locked'`, `'payment.gateway.timeout'`).
137
89
  */
138
90
  declare function createDomainError(code: string, message: string, statusCode?: number, details?: Record<string, unknown>): ArcError;
139
- /**
140
- * Check if error is an Arc error
141
- */
91
+ /** Type guard. */
142
92
  declare function isArcError(error: unknown): error is ArcError;
143
93
  //#endregion
144
94
  //#region src/core/validateResourceConfig.d.ts
@@ -510,40 +460,13 @@ interface Guard<T> {
510
460
  */
511
461
  declare function defineGuard<T>(config: GuardConfig<T>): Guard<T>;
512
462
  //#endregion
513
- //#region src/utils/envelope.d.ts
514
- /**
515
- * Standard response envelope helper.
516
- *
517
- * Wraps a handler return value in arc's `{ success: true, data, ...meta }`
518
- * shape. Pure utility — no types module coupling, no runtime dependencies.
519
- *
520
- * @example
521
- * ```ts
522
- * import { envelope } from '@classytic/arc';
523
- *
524
- * handler: async (req, reply) => {
525
- * const results = await search(req.query.q);
526
- * return envelope(results, { took: performance.now() - t0 });
527
- * }
528
- * ```
529
- */
530
- /**
531
- * Wrap data in arc's standard `{ success: true, data }` envelope, with
532
- * optional top-level meta keys merged in.
533
- */
534
- declare function envelope<T>(data: T, meta?: Record<string, unknown>): {
535
- success: true;
536
- data: T;
537
- [key: string]: unknown;
538
- };
539
- //#endregion
540
463
  //#region src/utils/handleRaw.d.ts
541
464
  /**
542
- * Wrap a raw Fastify handler with Arc's response envelope and error handling.
465
+ * Wrap a raw Fastify handler with Arc's response shape and error handling.
543
466
  *
544
467
  * @param handler - Async function that receives `(request, reply)` and returns data.
545
- * The return value is sent as `{ success: true, data }`. If it returns
546
- * `undefined` or `null`, `{ success: true }` is sent (no `data` field).
468
+ * The return value is sent raw (no envelope). If it returns `undefined`,
469
+ * the response body is empty (HTTP status only).
547
470
  * @param statusCode - HTTP status code for successful responses (default: 200)
548
471
  */
549
472
  declare function handleRaw<T>(handler: (request: FastifyRequest, reply: FastifyReply) => Promise<T>, statusCode?: number): (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
@@ -654,23 +577,24 @@ declare function createQueryParser(options?: ArcQueryParserOptions): ArcQueryPar
654
577
  //#endregion
655
578
  //#region src/utils/responseSchemas.d.ts
656
579
  interface JsonSchema {
657
- type: string;
580
+ /**
581
+ * Optional because JSON Schema allows top-level combinator-only schemas
582
+ * (`{ oneOf: [...] }`, `{ anyOf: [...] }`, `{ allOf: [...] }`) — see
583
+ * `listResponse()`, which emits a `oneOf` of the four canonical list
584
+ * shapes with no top-level `type`.
585
+ */
586
+ type?: string | string[];
658
587
  properties?: Record<string, JsonSchema | AnyRecord>;
659
588
  required?: string[];
660
589
  items?: JsonSchema | AnyRecord;
661
590
  additionalProperties?: boolean | JsonSchema;
662
591
  description?: string;
663
592
  example?: unknown;
593
+ oneOf?: JsonSchema[];
594
+ anyOf?: JsonSchema[];
595
+ allOf?: JsonSchema[];
664
596
  [key: string]: unknown;
665
597
  }
666
- /**
667
- * Base success response schema
668
- */
669
- declare const successResponseSchema: JsonSchema;
670
- /**
671
- * Error response schema
672
- */
673
- declare const errorResponseSchema: JsonSchema;
674
598
  /**
675
599
  * Pagination schema - matches MongoKit/Arc runtime format
676
600
  *
@@ -679,33 +603,29 @@ declare const errorResponseSchema: JsonSchema;
679
603
  */
680
604
  declare const paginationSchema: JsonSchema;
681
605
  /**
682
- * Wrap a data schema in a success response
683
- */
684
- declare function wrapResponse(dataSchema: JsonSchema): JsonSchema;
685
- /**
686
- * Create a list response schema with pagination - matches MongoKit/Arc runtime format
687
- *
688
- * Runtime format:
689
- * { success, docs: [...], page, limit, total, pages, hasNext, hasPrev }
606
+ * List response schema full union of every wire shape `toCanonicalList`
607
+ * can emit. Hosts who know their endpoint only ever produces one variant
608
+ * can pin to a narrower helper:
609
+ * - `offsetListResponse(item)` — `{ method: 'offset', data, page, limit, total, pages, hasNext, hasPrev }`
610
+ * - `keysetListResponse(item)` `{ method: 'keyset', data, limit, hasMore, next: string|null }`
611
+ * - `aggregateListResponse(item)` — `{ method: 'aggregate', ...offset fields }`
612
+ * - `bareListResponse(item)` — `{ data }`
690
613
  *
691
- * Note: Uses 'docs' array (not 'data') with flat pagination fields
614
+ * The default `listResponse(item)` is the union (`oneOf`) of all four so
615
+ * Fastify validation accepts any canonical kit shape — pre-2.13 this only
616
+ * modelled offset and rejected keyset/aggregate/bare lists at the
617
+ * response-schema gate.
692
618
  */
693
619
  declare function listResponse(itemSchema: JsonSchema): JsonSchema;
694
- /**
695
- * Create a single item response schema
696
- *
697
- * Runtime format: { success, data: {...} }
698
- */
699
- declare function itemResponse(itemSchema: JsonSchema): JsonSchema;
700
- /**
701
- * Create a create/update response schema
702
- */
703
- declare function mutationResponse(itemSchema: JsonSchema): JsonSchema;
704
- /**
705
- * Create a delete response schema
706
- *
707
- * Runtime format: { success, data: { message, id?, soft? } }
708
- */
620
+ /** Offset variant — `{ method: 'offset', data, page, limit, total, pages, hasNext, hasPrev }`. */
621
+ declare function offsetListResponse(itemSchema: JsonSchema): JsonSchema;
622
+ /** Keyset variant — `{ method: 'keyset', data, limit, hasMore, next: string | null }`. */
623
+ declare function keysetListResponse(itemSchema: JsonSchema): JsonSchema;
624
+ /** Aggregate variant — same shape as offset, discriminated by `method: 'aggregate'`. */
625
+ declare function aggregateListResponse(itemSchema: JsonSchema): JsonSchema;
626
+ /** Bare variant — `{ data }`, no `method` discriminant. */
627
+ declare function bareListResponse(itemSchema: JsonSchema): JsonSchema;
628
+ /** Delete response — flat shape mirroring the canonical delete envelope. */
709
629
  declare function deleteResponse(): JsonSchema;
710
630
  declare const responses: {
711
631
  200: (schema: JsonSchema) => {
@@ -720,7 +640,24 @@ declare const responses: {
720
640
  description: string;
721
641
  content: {
722
642
  "application/json": {
723
- schema: JsonSchema;
643
+ schema: {
644
+ additionalProperties: boolean;
645
+ /**
646
+ * Optional because JSON Schema allows top-level combinator-only schemas
647
+ * (`{ oneOf: [...] }`, `{ anyOf: [...] }`, `{ allOf: [...] }`) — see
648
+ * `listResponse()`, which emits a `oneOf` of the four canonical list
649
+ * shapes with no top-level `type`.
650
+ */
651
+ type?: string | string[];
652
+ properties?: Record<string, JsonSchema | AnyRecord>;
653
+ required?: string[];
654
+ items?: JsonSchema | AnyRecord;
655
+ description?: string;
656
+ example?: unknown;
657
+ oneOf?: JsonSchema[];
658
+ anyOf?: JsonSchema[];
659
+ allOf?: JsonSchema[];
660
+ };
724
661
  };
725
662
  };
726
663
  };
@@ -729,37 +666,54 @@ declare const responses: {
729
666
  content: {
730
667
  "application/json": {
731
668
  schema: {
732
- properties: {
733
- code: {
734
- type: string;
735
- example: string;
669
+ readonly type: "object";
670
+ readonly properties: {
671
+ readonly code: {
672
+ readonly type: "string";
673
+ readonly description: "Hierarchical machine-readable code (e.g. 'arc.not_found').";
674
+ };
675
+ readonly message: {
676
+ readonly type: "string";
677
+ readonly description: "Human-readable, safe-for-client message.";
736
678
  };
737
- details: {
738
- type: string;
739
- properties: {
740
- errors: {
741
- type: string;
742
- items: {
743
- type: string;
744
- properties: {
745
- field: {
746
- type: string;
747
- };
748
- message: {
749
- type: string;
750
- };
751
- };
679
+ readonly status: {
680
+ readonly type: "integer";
681
+ readonly description: "Suggested HTTP status code (hosts may override).";
682
+ };
683
+ readonly details: {
684
+ readonly type: "array";
685
+ readonly description: "Field-scoped structured details (validation failures, duplicate keys, multi-code domain errors).";
686
+ readonly items: {
687
+ readonly type: "object";
688
+ readonly properties: {
689
+ readonly path: {
690
+ readonly type: "string";
691
+ readonly description: "Dot-path to the offending field, e.g. 'lines.0.quantity'.";
692
+ };
693
+ readonly code: {
694
+ readonly type: "string";
695
+ };
696
+ readonly message: {
697
+ readonly type: "string";
698
+ };
699
+ readonly meta: {
700
+ readonly type: "object";
701
+ readonly description: "Non-PII per-detail diagnostics (safe to log + return).";
752
702
  };
753
703
  };
704
+ readonly required: readonly ["code", "message"];
754
705
  };
755
706
  };
707
+ readonly correlationId: {
708
+ readonly type: "string";
709
+ readonly description: "Request id for support lookups.";
710
+ };
711
+ readonly meta: {
712
+ readonly type: "object";
713
+ readonly description: "Non-PII diagnostics (safe to log + return).";
714
+ };
756
715
  };
757
- type: string;
758
- required?: string[];
759
- items?: JsonSchema | AnyRecord;
760
- additionalProperties?: boolean | JsonSchema;
761
- description?: string;
762
- example?: unknown;
716
+ readonly required: readonly ["code", "message"];
763
717
  };
764
718
  };
765
719
  };
@@ -769,18 +723,54 @@ declare const responses: {
769
723
  content: {
770
724
  "application/json": {
771
725
  schema: {
772
- properties: {
773
- code: {
774
- type: string;
775
- example: string;
726
+ readonly type: "object";
727
+ readonly properties: {
728
+ readonly code: {
729
+ readonly type: "string";
730
+ readonly description: "Hierarchical machine-readable code (e.g. 'arc.not_found').";
731
+ };
732
+ readonly message: {
733
+ readonly type: "string";
734
+ readonly description: "Human-readable, safe-for-client message.";
735
+ };
736
+ readonly status: {
737
+ readonly type: "integer";
738
+ readonly description: "Suggested HTTP status code (hosts may override).";
739
+ };
740
+ readonly details: {
741
+ readonly type: "array";
742
+ readonly description: "Field-scoped structured details (validation failures, duplicate keys, multi-code domain errors).";
743
+ readonly items: {
744
+ readonly type: "object";
745
+ readonly properties: {
746
+ readonly path: {
747
+ readonly type: "string";
748
+ readonly description: "Dot-path to the offending field, e.g. 'lines.0.quantity'.";
749
+ };
750
+ readonly code: {
751
+ readonly type: "string";
752
+ };
753
+ readonly message: {
754
+ readonly type: "string";
755
+ };
756
+ readonly meta: {
757
+ readonly type: "object";
758
+ readonly description: "Non-PII per-detail diagnostics (safe to log + return).";
759
+ };
760
+ };
761
+ readonly required: readonly ["code", "message"];
762
+ };
763
+ };
764
+ readonly correlationId: {
765
+ readonly type: "string";
766
+ readonly description: "Request id for support lookups.";
767
+ };
768
+ readonly meta: {
769
+ readonly type: "object";
770
+ readonly description: "Non-PII diagnostics (safe to log + return).";
776
771
  };
777
772
  };
778
- type: string;
779
- required?: string[];
780
- items?: JsonSchema | AnyRecord;
781
- additionalProperties?: boolean | JsonSchema;
782
- description?: string;
783
- example?: unknown;
773
+ readonly required: readonly ["code", "message"];
784
774
  };
785
775
  };
786
776
  };
@@ -790,18 +780,54 @@ declare const responses: {
790
780
  content: {
791
781
  "application/json": {
792
782
  schema: {
793
- properties: {
794
- code: {
795
- type: string;
796
- example: string;
783
+ readonly type: "object";
784
+ readonly properties: {
785
+ readonly code: {
786
+ readonly type: "string";
787
+ readonly description: "Hierarchical machine-readable code (e.g. 'arc.not_found').";
788
+ };
789
+ readonly message: {
790
+ readonly type: "string";
791
+ readonly description: "Human-readable, safe-for-client message.";
792
+ };
793
+ readonly status: {
794
+ readonly type: "integer";
795
+ readonly description: "Suggested HTTP status code (hosts may override).";
796
+ };
797
+ readonly details: {
798
+ readonly type: "array";
799
+ readonly description: "Field-scoped structured details (validation failures, duplicate keys, multi-code domain errors).";
800
+ readonly items: {
801
+ readonly type: "object";
802
+ readonly properties: {
803
+ readonly path: {
804
+ readonly type: "string";
805
+ readonly description: "Dot-path to the offending field, e.g. 'lines.0.quantity'.";
806
+ };
807
+ readonly code: {
808
+ readonly type: "string";
809
+ };
810
+ readonly message: {
811
+ readonly type: "string";
812
+ };
813
+ readonly meta: {
814
+ readonly type: "object";
815
+ readonly description: "Non-PII per-detail diagnostics (safe to log + return).";
816
+ };
817
+ };
818
+ readonly required: readonly ["code", "message"];
819
+ };
820
+ };
821
+ readonly correlationId: {
822
+ readonly type: "string";
823
+ readonly description: "Request id for support lookups.";
824
+ };
825
+ readonly meta: {
826
+ readonly type: "object";
827
+ readonly description: "Non-PII diagnostics (safe to log + return).";
797
828
  };
798
829
  };
799
- type: string;
800
- required?: string[];
801
- items?: JsonSchema | AnyRecord;
802
- additionalProperties?: boolean | JsonSchema;
803
- description?: string;
804
- example?: unknown;
830
+ readonly required: readonly ["code", "message"];
805
831
  };
806
832
  };
807
833
  };
@@ -811,18 +837,54 @@ declare const responses: {
811
837
  content: {
812
838
  "application/json": {
813
839
  schema: {
814
- properties: {
815
- code: {
816
- type: string;
817
- example: string;
840
+ readonly type: "object";
841
+ readonly properties: {
842
+ readonly code: {
843
+ readonly type: "string";
844
+ readonly description: "Hierarchical machine-readable code (e.g. 'arc.not_found').";
845
+ };
846
+ readonly message: {
847
+ readonly type: "string";
848
+ readonly description: "Human-readable, safe-for-client message.";
849
+ };
850
+ readonly status: {
851
+ readonly type: "integer";
852
+ readonly description: "Suggested HTTP status code (hosts may override).";
853
+ };
854
+ readonly details: {
855
+ readonly type: "array";
856
+ readonly description: "Field-scoped structured details (validation failures, duplicate keys, multi-code domain errors).";
857
+ readonly items: {
858
+ readonly type: "object";
859
+ readonly properties: {
860
+ readonly path: {
861
+ readonly type: "string";
862
+ readonly description: "Dot-path to the offending field, e.g. 'lines.0.quantity'.";
863
+ };
864
+ readonly code: {
865
+ readonly type: "string";
866
+ };
867
+ readonly message: {
868
+ readonly type: "string";
869
+ };
870
+ readonly meta: {
871
+ readonly type: "object";
872
+ readonly description: "Non-PII per-detail diagnostics (safe to log + return).";
873
+ };
874
+ };
875
+ readonly required: readonly ["code", "message"];
876
+ };
877
+ };
878
+ readonly correlationId: {
879
+ readonly type: "string";
880
+ readonly description: "Request id for support lookups.";
881
+ };
882
+ readonly meta: {
883
+ readonly type: "object";
884
+ readonly description: "Non-PII diagnostics (safe to log + return).";
818
885
  };
819
886
  };
820
- type: string;
821
- required?: string[];
822
- items?: JsonSchema | AnyRecord;
823
- additionalProperties?: boolean | JsonSchema;
824
- description?: string;
825
- example?: unknown;
887
+ readonly required: readonly ["code", "message"];
826
888
  };
827
889
  };
828
890
  };
@@ -832,18 +894,54 @@ declare const responses: {
832
894
  content: {
833
895
  "application/json": {
834
896
  schema: {
835
- properties: {
836
- code: {
837
- type: string;
838
- example: string;
897
+ readonly type: "object";
898
+ readonly properties: {
899
+ readonly code: {
900
+ readonly type: "string";
901
+ readonly description: "Hierarchical machine-readable code (e.g. 'arc.not_found').";
902
+ };
903
+ readonly message: {
904
+ readonly type: "string";
905
+ readonly description: "Human-readable, safe-for-client message.";
906
+ };
907
+ readonly status: {
908
+ readonly type: "integer";
909
+ readonly description: "Suggested HTTP status code (hosts may override).";
910
+ };
911
+ readonly details: {
912
+ readonly type: "array";
913
+ readonly description: "Field-scoped structured details (validation failures, duplicate keys, multi-code domain errors).";
914
+ readonly items: {
915
+ readonly type: "object";
916
+ readonly properties: {
917
+ readonly path: {
918
+ readonly type: "string";
919
+ readonly description: "Dot-path to the offending field, e.g. 'lines.0.quantity'.";
920
+ };
921
+ readonly code: {
922
+ readonly type: "string";
923
+ };
924
+ readonly message: {
925
+ readonly type: "string";
926
+ };
927
+ readonly meta: {
928
+ readonly type: "object";
929
+ readonly description: "Non-PII per-detail diagnostics (safe to log + return).";
930
+ };
931
+ };
932
+ readonly required: readonly ["code", "message"];
933
+ };
934
+ };
935
+ readonly correlationId: {
936
+ readonly type: "string";
937
+ readonly description: "Request id for support lookups.";
938
+ };
939
+ readonly meta: {
940
+ readonly type: "object";
941
+ readonly description: "Non-PII diagnostics (safe to log + return).";
839
942
  };
840
943
  };
841
- type: string;
842
- required?: string[];
843
- items?: JsonSchema | AnyRecord;
844
- additionalProperties?: boolean | JsonSchema;
845
- description?: string;
846
- example?: unknown;
944
+ readonly required: readonly ["code", "message"];
847
945
  };
848
946
  };
849
947
  };
@@ -853,18 +951,54 @@ declare const responses: {
853
951
  content: {
854
952
  "application/json": {
855
953
  schema: {
856
- properties: {
857
- code: {
858
- type: string;
859
- example: string;
954
+ readonly type: "object";
955
+ readonly properties: {
956
+ readonly code: {
957
+ readonly type: "string";
958
+ readonly description: "Hierarchical machine-readable code (e.g. 'arc.not_found').";
959
+ };
960
+ readonly message: {
961
+ readonly type: "string";
962
+ readonly description: "Human-readable, safe-for-client message.";
963
+ };
964
+ readonly status: {
965
+ readonly type: "integer";
966
+ readonly description: "Suggested HTTP status code (hosts may override).";
967
+ };
968
+ readonly details: {
969
+ readonly type: "array";
970
+ readonly description: "Field-scoped structured details (validation failures, duplicate keys, multi-code domain errors).";
971
+ readonly items: {
972
+ readonly type: "object";
973
+ readonly properties: {
974
+ readonly path: {
975
+ readonly type: "string";
976
+ readonly description: "Dot-path to the offending field, e.g. 'lines.0.quantity'.";
977
+ };
978
+ readonly code: {
979
+ readonly type: "string";
980
+ };
981
+ readonly message: {
982
+ readonly type: "string";
983
+ };
984
+ readonly meta: {
985
+ readonly type: "object";
986
+ readonly description: "Non-PII per-detail diagnostics (safe to log + return).";
987
+ };
988
+ };
989
+ readonly required: readonly ["code", "message"];
990
+ };
991
+ };
992
+ readonly correlationId: {
993
+ readonly type: "string";
994
+ readonly description: "Request id for support lookups.";
995
+ };
996
+ readonly meta: {
997
+ readonly type: "object";
998
+ readonly description: "Non-PII diagnostics (safe to log + return).";
860
999
  };
861
1000
  };
862
- type: string;
863
- required?: string[];
864
- items?: JsonSchema | AnyRecord;
865
- additionalProperties?: boolean | JsonSchema;
866
- description?: string;
867
- example?: unknown;
1001
+ readonly required: readonly ["code", "message"];
868
1002
  };
869
1003
  };
870
1004
  };
@@ -923,6 +1057,13 @@ declare function getListQueryParams(): AnyRecord;
923
1057
  */
924
1058
  declare function getDefaultCrudSchemas(): Record<string, Record<string, unknown>>;
925
1059
  //#endregion
1060
+ //#region src/utils/runtime.d.ts
1061
+ /**
1062
+ * Portable "run on next tick" scheduler. `setImmediate` is Node-only — not
1063
+ * available in Bun workers, Deno, Cloudflare Workers, or edge runtimes.
1064
+ */
1065
+ declare const scheduleBackground: (cb: () => void) => void;
1066
+ //#endregion
926
1067
  //#region src/utils/schemaConverter.d.ts
927
1068
  /**
928
1069
  * Supported JSON Schema output targets for Zod v4's `toJSONSchema()`.
@@ -1176,4 +1317,4 @@ declare function hasEvents(instance: FastifyInstance): instance is FastifyInstan
1176
1317
  */
1177
1318
  declare function getUserId(user: UserLike | null | undefined): string | undefined;
1178
1319
  //#endregion
1179
- export { ValidationResult as $, handleRaw as A, CompensationStep as B, queryParams as C, ArcQueryParser as D, wrapResponse as E, defineErrorMapper as F, CircuitBreakerOptions as G, withCompensation as H, CompensationDefinition as I, CircuitState as J, CircuitBreakerRegistry as K, CompensationError as L, Guard as M, GuardConfig as N, ArcQueryParserOptions as O, defineGuard as P, ValidateOptions as Q, CompensationHooks as R, paginationSchema as S, successResponseSchema as T, CircuitBreaker as U, defineCompensation as V, CircuitBreakerError as W, createCircuitBreakerRegistry as X, createCircuitBreaker as Y, ConfigError as Z, getDefaultCrudSchemas as _, TransitionConfig as a, ErrorDetails as at, listResponse as b, JsonSchemaTarget as c, OrgAccessDeniedError as ct, isJsonSchema as d, ServiceUnavailableError as dt, assertValidConfig as et, isZodSchema as f, UnauthorizedError as ft, errorResponseSchema as g, isArcError as gt, deleteResponse as h, createError as ht, StateMachine as i, ConflictError as it, envelope as j, createQueryParser as k, convertOpenApiSchemas as l, OrgRequiredError as lt, JsonSchema as m, createDomainError as mt, EventsDecorator as n, validateResourceConfig as nt, createStateMachine as o, ForbiddenError as ot, toJsonSchema as p, ValidationError as pt, CircuitBreakerStats as q, hasEvents as r, ArcError as rt, simpleEqualityMatcher as s, NotFoundError as st, getUserId as t, formatValidationErrors as tt, convertRouteSchema as u, RateLimitError as ut, getListQueryParams as v, responses as w, mutationResponse as x, itemResponse as y, CompensationResult as z };
1320
+ export { ValidateOptions as $, ArcQueryParserOptions as A, CompensationResult as B, keysetListResponse as C, queryParams as D, paginationSchema as E, defineGuard as F, CircuitBreakerError as G, defineCompensation as H, defineErrorMapper as I, CircuitBreakerStats as J, CircuitBreakerOptions as K, CompensationDefinition as L, handleRaw as M, Guard as N, responses as O, GuardConfig as P, ConfigError as Q, CompensationError as R, getListQueryParams as S, offsetListResponse as T, withCompensation as U, CompensationStep as V, CircuitBreaker as W, createCircuitBreaker as X, CircuitState as Y, createCircuitBreakerRegistry as Z, bareListResponse as _, isArcError as _t, TransitionConfig as a, ConflictError as at, errorDetailSchema$1 as b, JsonSchemaTarget as c, NotFoundError as ct, isJsonSchema as d, RateLimitError as dt, ValidationResult as et, isZodSchema as f, ServiceUnavailableError as ft, aggregateListResponse as g, createError as gt, JsonSchema as h, createDomainError as ht, StateMachine as i, ArcError as it, createQueryParser as j, ArcQueryParser as k, convertOpenApiSchemas as l, OrgAccessDeniedError as lt, scheduleBackground as m, ValidationError as mt, EventsDecorator as n, formatValidationErrors as nt, createStateMachine as o, ErrorOptions as ot, toJsonSchema as p, UnauthorizedError as pt, CircuitBreakerRegistry as q, hasEvents as r, validateResourceConfig as rt, simpleEqualityMatcher as s, ForbiddenError as st, getUserId as t, assertValidConfig as tt, convertRouteSchema as u, OrgRequiredError as ut, deleteResponse as v, listResponse as w, getDefaultCrudSchemas as x, errorContractSchema$1 as y, CompensationHooks as z };