@terreno/api 0.29.0 → 0.31.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 (79) hide show
  1. package/CHANGELOG.md +2 -43
  2. package/LICENSE +21 -202
  3. package/dist/actions.js +17 -8
  4. package/dist/actions.openApi.test.js +1 -3
  5. package/dist/actions.test.js +8 -5
  6. package/dist/api.arrayOperations.test.js +16 -8
  7. package/dist/api.coverage.test.js +2 -3
  8. package/dist/api.d.ts +3 -2
  9. package/dist/api.errorPaths.test.js +608 -1
  10. package/dist/api.errors.test.js +9 -0
  11. package/dist/api.js +137 -170
  12. package/dist/api.query.test.js +20 -8
  13. package/dist/api.test.js +12 -6
  14. package/dist/auth.coverage.test.d.ts +1 -0
  15. package/dist/auth.coverage.test.js +202 -0
  16. package/dist/auth.test.js +159 -0
  17. package/dist/betterAuthSetup.d.ts +15 -1
  18. package/dist/betterAuthSetup.js +4 -6
  19. package/dist/configurationPlugin.js +2 -2
  20. package/dist/consentApp.test.js +1 -5
  21. package/dist/docLoader.js +5 -1
  22. package/dist/envConfigurationPlugin.d.ts +1 -1
  23. package/dist/envConfigurationPlugin.js +0 -2
  24. package/dist/errors.d.ts +14 -0
  25. package/dist/errors.js +24 -2
  26. package/dist/errors.test.js +137 -0
  27. package/dist/expressServer.js +11 -5
  28. package/dist/githubAuth.js +1 -4
  29. package/dist/httpClient.js +5 -1
  30. package/dist/openApiBuilder.test.js +0 -2
  31. package/dist/openApiValidator.test.js +34 -0
  32. package/dist/plugins.d.ts +6 -5
  33. package/dist/plugins.js +56 -10
  34. package/dist/plugins.test.js +73 -17
  35. package/dist/populate.test.js +9 -12
  36. package/dist/realtime/realtime.test.js +231 -0
  37. package/dist/realtime/realtimeApp.d.ts +1 -1
  38. package/dist/realtime/realtimeApp.js +6 -2
  39. package/dist/realtime/realtimeAppSetup.test.d.ts +1 -0
  40. package/dist/realtime/realtimeAppSetup.test.js +213 -0
  41. package/dist/realtime/registry.d.ts +3 -2
  42. package/dist/tests/models.d.ts +27 -11
  43. package/dist/tests/models.js +5 -3
  44. package/dist/tests/testHelper.d.ts +9 -3
  45. package/package.json +4 -5
  46. package/src/actions.openApi.test.ts +7 -10
  47. package/src/actions.test.ts +27 -15
  48. package/src/actions.ts +21 -12
  49. package/src/api.arrayOperations.test.ts +16 -8
  50. package/src/api.coverage.test.ts +9 -10
  51. package/src/api.errorPaths.test.ts +360 -4
  52. package/src/api.errors.test.ts +12 -0
  53. package/src/api.query.test.ts +20 -8
  54. package/src/api.test.ts +12 -6
  55. package/src/api.ts +162 -171
  56. package/src/auth.coverage.test.ts +101 -0
  57. package/src/auth.test.ts +125 -2
  58. package/src/betterAuthSetup.ts +7 -7
  59. package/src/configurationPlugin.ts +2 -2
  60. package/src/consentApp.test.ts +12 -12
  61. package/src/docLoader.ts +6 -2
  62. package/src/envConfigurationPlugin.ts +2 -6
  63. package/src/errors.test.ts +106 -1
  64. package/src/errors.ts +25 -1
  65. package/src/expressServer.ts +11 -5
  66. package/src/githubAuth.ts +1 -3
  67. package/src/httpClient.ts +6 -2
  68. package/src/models/versionConfig.ts +1 -1
  69. package/src/openApiBuilder.test.ts +24 -9
  70. package/src/openApiValidator.test.ts +41 -0
  71. package/src/plugins.test.ts +59 -9
  72. package/src/plugins.ts +81 -39
  73. package/src/populate.test.ts +25 -16
  74. package/src/realtime/changeStreamWatcher.ts +8 -1
  75. package/src/realtime/realtime.test.ts +239 -0
  76. package/src/realtime/realtimeApp.ts +8 -5
  77. package/src/realtime/realtimeAppSetup.test.ts +161 -0
  78. package/src/realtime/registry.ts +3 -4
  79. package/src/tests/models.ts +8 -6
package/src/api.ts CHANGED
@@ -18,10 +18,15 @@ import {
18
18
  import {authenticateMiddleware, type User} from "./auth";
19
19
  import {
20
20
  APIError,
21
+ type APIErrorOptions,
21
22
  apiErrorMiddleware,
22
- errorMessage,
23
+ BadRequestError,
24
+ errorDetail,
25
+ ForbiddenError,
23
26
  getDisableExternalErrorTracking,
24
27
  isAPIError,
28
+ mongooseErrorToAPIError,
29
+ NotFoundError,
25
30
  } from "./errors";
26
31
  import {logger} from "./logger";
27
32
  import {
@@ -49,6 +54,10 @@ import {
49
54
  } from "./transformers";
50
55
  import {isValidObjectId} from "./utils";
51
56
 
57
+ // noExplicitAny: Framework routers accept consumer models with arbitrary query helpers, methods, virtuals, and hydrated document types
58
+ // biome-ignore lint/suspicious/noExplicitAny: Framework routers accept consumer models with arbitrary query helpers, methods, virtuals, and hydrated document types
59
+ type ModelLike<T> = Model<T, any, any, any, any, any>;
60
+
52
61
  export type JSONPrimitive = string | number | boolean | null;
53
62
  export interface JSONArray extends Array<JSONValue> {}
54
63
  export interface JSONObject {
@@ -56,6 +65,39 @@ export interface JSONObject {
56
65
  }
57
66
  export type JSONValue = JSONPrimitive | JSONObject | JSONArray;
58
67
 
68
+ /**
69
+ * Picks the error to throw for something caught in a hook, transformer, or Mongoose middleware.
70
+ * An `APIError` is passed through untouched so its status, code, detail, and meta reach the client;
71
+ * anything else is wrapped in the given framework error. `wrapper` may override any field,
72
+ * including `detail`, which defaults to the caught error's text.
73
+ */
74
+ const passthroughOrWrap = (error: unknown, wrapper: APIErrorOptions): APIError => {
75
+ if (isAPIError(error)) {
76
+ return error;
77
+ }
78
+ return new APIError({
79
+ cause: error,
80
+ detail: errorDetail(error),
81
+ disableExternalErrorTracking: getDisableExternalErrorTracking(error),
82
+ ...wrapper,
83
+ });
84
+ };
85
+
86
+ /**
87
+ * `passthroughOrWrap` for write paths (`model.create`, `doc.save`). Mongoose validation and cast
88
+ * errors are converted first so their per-field messages survive as `meta.fields` instead of being
89
+ * flattened into the wrapper's `detail`.
90
+ */
91
+ const passthroughOrWrapWrite = (error: unknown, wrapper: APIErrorOptions): APIError => {
92
+ if (!isAPIError(error) && error instanceof Error) {
93
+ const converted = mongooseErrorToAPIError(error);
94
+ if (converted) {
95
+ return converted;
96
+ }
97
+ }
98
+ return passthroughOrWrap(error, wrapper);
99
+ };
100
+
59
101
  export const addPopulateToQuery = (
60
102
  // noExplicitAny: mongoose Query type parameters vary widely across populated/unpopulated documents — caller passes concrete types
61
103
  // biome-ignore lint/suspicious/noExplicitAny: mongoose Query type parameters vary widely across populated/unpopulated documents — caller passes concrete types
@@ -350,9 +392,11 @@ export interface ModelRouterOptions<T> {
350
392
  const parseDateRangeBound = (rawValue: unknown, queryKey: string): Date => {
351
393
  const parsed = DateTime.fromISO(String(rawValue), {zone: "utc"});
352
394
  if (!parsed.isValid) {
353
- throw new APIError({
354
- status: 400,
355
- title: `Invalid date for query parameter ${queryKey}`,
395
+ throw new BadRequestError({
396
+ code: "invalid-date-query-parameter",
397
+ detail: `Invalid date for query parameter ${queryKey}`,
398
+ source: {parameter: queryKey},
399
+ title: "Invalid date query parameter",
356
400
  });
357
401
  }
358
402
  return parsed.toJSDate();
@@ -363,7 +407,7 @@ const parseDateRangeBound = (rawValue: unknown, queryKey: string): Date => {
363
407
  * so admin changelist date-range filters map to valid Mongoose range queries.
364
408
  */
365
409
  const mergeDateRangeQueryParams = <T>(
366
- model: Model<T>,
410
+ model: ModelLike<T>,
367
411
  query: Record<string, unknown>
368
412
  ): Record<string, unknown> => {
369
413
  const schema = model.schema;
@@ -431,9 +475,11 @@ const checkQueryParamAllowed = (
431
475
  return;
432
476
  }
433
477
  if (!queryFields.includes(queryParam)) {
434
- throw new APIError({
435
- status: 400,
436
- title: `${queryParam} is not allowed as a query param.`,
478
+ throw new BadRequestError({
479
+ code: "query-param-not-allowed",
480
+ detail: `${queryParam} is not allowed as a query param.`,
481
+ source: {parameter: queryParam},
482
+ title: "Query parameter not allowed",
437
483
  });
438
484
  }
439
485
  };
@@ -484,7 +530,7 @@ const shouldValidate = <T>(
484
530
 
485
531
  // Get body validation middleware if validation is enabled
486
532
  const getBodyValidationMiddleware = <T>(
487
- model: Model<T>,
533
+ model: ModelLike<T>,
488
534
  options: ModelRouterOptions<T>,
489
535
  operation: "create" | "update"
490
536
  ): ((req: Request, res: Response, next: NextFunction) => void) => {
@@ -514,7 +560,7 @@ const getBodyValidationMiddleware = <T>(
514
560
 
515
561
  // Get query validation middleware if validation is enabled
516
562
  const getQueryValidationMiddleware = <T>(
517
- model: Model<T>,
563
+ model: ModelLike<T>,
518
564
  options: ModelRouterOptions<T>
519
565
  ): ((req: Request, res: Response, next: NextFunction) => void) => {
520
566
  const querySchema = buildQuerySchemaFromFields(model, options.queryFields);
@@ -565,22 +611,22 @@ export interface ModelRouterRegistration {
565
611
  */
566
612
  export function modelRouter<T>(
567
613
  path: string,
568
- model: Model<T>,
614
+ model: ModelLike<T>,
569
615
  options: ModelRouterOptions<T>
570
616
  ): ModelRouterRegistration;
571
- export function modelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>): express.Router;
617
+ export function modelRouter<T>(model: ModelLike<T>, options: ModelRouterOptions<T>): express.Router;
572
618
  export function modelRouter<T>(
573
- pathOrModel: string | Model<T>,
574
- modelOrOptions: Model<T> | ModelRouterOptions<T>,
619
+ pathOrModel: string | ModelLike<T>,
620
+ modelOrOptions: ModelLike<T> | ModelRouterOptions<T>,
575
621
  maybeOptions?: ModelRouterOptions<T>
576
622
  ): express.Router | ModelRouterRegistration {
577
- let model: Model<T>;
623
+ let model: ModelLike<T>;
578
624
  let options: ModelRouterOptions<T>;
579
625
  let path: string | undefined;
580
626
 
581
627
  if (typeof pathOrModel === "string") {
582
628
  path = pathOrModel;
583
- model = modelOrOptions as Model<T>;
629
+ model = modelOrOptions as ModelLike<T>;
584
630
  options = maybeOptions as ModelRouterOptions<T>;
585
631
  } else {
586
632
  model = pathOrModel;
@@ -596,7 +642,7 @@ export function modelRouter<T>(
596
642
  collectionName: model.collection.collectionName,
597
643
  config: options.realtime,
598
644
  modelName: model.modelName,
599
- options,
645
+ options: options as unknown as ModelRouterOptions<unknown>,
600
646
  routePath: path,
601
647
  });
602
648
  }
@@ -619,7 +665,10 @@ export function modelRouter<T>(
619
665
  return router;
620
666
  }
621
667
 
622
- function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>): express.Router {
668
+ const _buildModelRouter = <T>(
669
+ model: ModelLike<T>,
670
+ options: ModelRouterOptions<T>
671
+ ): express.Router => {
623
672
  const router = express.Router();
624
673
 
625
674
  assertNoActionCollisions(model, options);
@@ -650,14 +699,8 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
650
699
  try {
651
700
  body = transform<T>(options, req.body, "create", req.user);
652
701
  } catch (error: unknown) {
653
- if (isAPIError(error)) {
654
- throw error;
655
- }
656
- throw new APIError({
657
- cause: error,
702
+ throw passthroughOrWrap(error, {
658
703
  code: "transform-error",
659
- detail: errorMessage(error),
660
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
661
704
  status: 400,
662
705
  title: "Transform error",
663
706
  });
@@ -666,37 +709,31 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
666
709
  try {
667
710
  body = await options.preCreate(body, req);
668
711
  } catch (error: unknown) {
669
- if (isAPIError(error)) {
670
- throw error;
671
- }
672
- throw new APIError({
673
- cause: error,
712
+ throw passthroughOrWrap(error, {
674
713
  code: "pre-create-hook-error",
675
- detail: errorMessage(error),
676
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
677
714
  status: 400,
678
715
  title: "preCreate hook error",
679
716
  });
680
717
  }
681
718
  if (body === undefined) {
682
- throw new APIError({
719
+ throw new ForbiddenError({
720
+ code: "create-not-allowed",
683
721
  detail: "A body must be returned from preCreate",
684
- status: 403,
685
722
  title: "Create not allowed",
686
723
  });
687
724
  }
688
725
  if (body === null) {
689
- throw new APIError({
726
+ throw new ForbiddenError({
727
+ code: "create-not-allowed",
690
728
  detail: "preCreate hook returned null",
691
- status: 403,
692
729
  title: "Create not allowed",
693
730
  });
694
731
  }
695
732
  }
696
733
  if (body === undefined) {
697
- throw new APIError({
734
+ throw new BadRequestError({
735
+ code: "invalid-request-body",
698
736
  detail: "Body is undefined",
699
- status: 400,
700
737
  title: "Invalid request body",
701
738
  });
702
739
  }
@@ -704,11 +741,8 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
704
741
  try {
705
742
  data = (await model.create(body as T)) as Document<unknown, unknown, unknown> & T;
706
743
  } catch (error: unknown) {
707
- throw new APIError({
708
- cause: error,
744
+ throw passthroughOrWrapWrite(error, {
709
745
  code: "create-error",
710
- detail: errorMessage(error),
711
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
712
746
  status: 400,
713
747
  title: "Create error",
714
748
  });
@@ -722,11 +756,8 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
722
756
  populateQuery = addPopulateToQuery(populateQuery, options.populatePaths);
723
757
  data = await populateQuery.exec();
724
758
  } catch (error: unknown) {
725
- throw new APIError({
726
- cause: error,
759
+ throw passthroughOrWrap(error, {
727
760
  code: "populate-error",
728
- detail: errorMessage(error),
729
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
730
761
  status: 400,
731
762
  title: "Populate error",
732
763
  });
@@ -737,11 +768,8 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
737
768
  try {
738
769
  await options.postCreate(data, req);
739
770
  } catch (error: unknown) {
740
- throw new APIError({
741
- cause: error,
771
+ throw passthroughOrWrap(error, {
742
772
  code: "post-create-hook-error",
743
- detail: errorMessage(error),
744
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
745
773
  status: 400,
746
774
  title: "postCreate hook error",
747
775
  });
@@ -751,11 +779,8 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
751
779
  const serialized = await responseHandler(data, "create", req, options);
752
780
  return res.status(201).json({data: serialized});
753
781
  } catch (error: unknown) {
754
- throw new APIError({
755
- cause: error,
782
+ throw passthroughOrWrap(error, {
756
783
  code: "response-handler-error",
757
- detail: errorMessage(error),
758
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
759
784
  title: "responseHandler error",
760
785
  });
761
786
  }
@@ -810,11 +835,8 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
810
835
  try {
811
836
  queryFilter = await options.queryFilter(req.user, query);
812
837
  } catch (error: unknown) {
813
- throw new APIError({
814
- cause: error,
838
+ throw passthroughOrWrap(error, {
815
839
  code: "query-filter-error",
816
- detail: String(error),
817
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
818
840
  status: 400,
819
841
  title: "Query filter error",
820
842
  });
@@ -843,9 +865,11 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
843
865
  const total = await model.countDocuments(query);
844
866
  if (req.query.page) {
845
867
  if (Number(req.query.page) === 0 || Number.isNaN(Number(req.query.page))) {
846
- throw new APIError({
847
- status: 400,
848
- title: `Invalid page: ${req.query.page}`,
868
+ throw new BadRequestError({
869
+ code: "invalid-page",
870
+ detail: `Invalid page: ${req.query.page}`,
871
+ source: {parameter: "page"},
872
+ title: "Invalid page",
849
873
  });
850
874
  }
851
875
  builtQuery = builtQuery.skip((Number(req.query.page) - 1) * limit);
@@ -864,11 +888,8 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
864
888
  try {
865
889
  data = (await populatedQuery.exec()) as (Document<unknown, unknown, unknown> & T)[];
866
890
  } catch (error: unknown) {
867
- throw new APIError({
868
- cause: error,
891
+ throw passthroughOrWrap(error, {
869
892
  code: "list-error",
870
- detail: errorMessage(error),
871
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
872
893
  title: "List error",
873
894
  });
874
895
  }
@@ -878,11 +899,8 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
878
899
  try {
879
900
  serialized = await responseHandler(data, "list", req, options);
880
901
  } catch (error: unknown) {
881
- throw new APIError({
882
- cause: error,
902
+ throw passthroughOrWrap(error, {
883
903
  code: "response-handler-error",
884
- detail: errorMessage(error),
885
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
886
904
  title: "responseHandler error",
887
905
  });
888
906
  }
@@ -915,11 +933,8 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
915
933
  }
916
934
  return res.json({data: serialized});
917
935
  } catch (error: unknown) {
918
- throw new APIError({
919
- cause: error,
936
+ throw passthroughOrWrap(error, {
920
937
  code: "serialization-error",
921
- detail: errorMessage(error),
922
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
923
938
  title: "Serialization error",
924
939
  });
925
940
  }
@@ -940,11 +955,8 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
940
955
  const serialized = await responseHandler(data, "read", req, options);
941
956
  return res.json({data: serialized});
942
957
  } catch (error: unknown) {
943
- throw new APIError({
944
- cause: error,
958
+ throw passthroughOrWrap(error, {
945
959
  code: "response-handler-error",
946
- detail: errorMessage(error),
947
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
948
960
  title: "responseHandler error",
949
961
  });
950
962
  }
@@ -957,6 +969,8 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
957
969
  asyncHandler(async (_req: Request, _res: Response) => {
958
970
  // Patch is what we want 90% of the time
959
971
  throw new APIError({
972
+ code: "put-not-supported",
973
+ detail: "Use PATCH to update a document.",
960
974
  title: "PUT is not supported.",
961
975
  });
962
976
  })
@@ -978,14 +992,9 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
978
992
  try {
979
993
  body = transform<T>(options, req.body, "update", req.user) as Partial<T>;
980
994
  } catch (error: unknown) {
981
- if (isAPIError(error)) {
982
- throw error;
983
- }
984
- throw new APIError({
985
- cause: error,
995
+ throw passthroughOrWrap(error, {
986
996
  code: "transform-error",
987
- detail: `PATCH failed on ${req.params.id} for user ${req.user?.id}: ${errorMessage(error)}`,
988
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
997
+ detail: `PATCH failed on ${req.params.id} for user ${req.user?.id}: ${errorDetail(error)}`,
989
998
  status: 403,
990
999
  title: "PATCH failed",
991
1000
  });
@@ -1002,29 +1011,24 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1002
1011
  try {
1003
1012
  body = await options.preUpdate(body, req);
1004
1013
  } catch (error: unknown) {
1005
- if (isAPIError(error)) {
1006
- throw error;
1007
- }
1008
- throw new APIError({
1009
- cause: error,
1014
+ throw passthroughOrWrap(error, {
1010
1015
  code: "pre-update-hook-error",
1011
- detail: `preUpdate hook error on ${req.params.id}: ${errorMessage(error)}`,
1012
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
1016
+ detail: `preUpdate hook error on ${req.params.id}: ${errorDetail(error)}`,
1013
1017
  status: 400,
1014
1018
  title: "preUpdate hook error",
1015
1019
  });
1016
1020
  }
1017
1021
  if (body === undefined) {
1018
- throw new APIError({
1022
+ throw new ForbiddenError({
1023
+ code: "update-not-allowed",
1019
1024
  detail: "A body must be returned from preUpdate",
1020
- status: 403,
1021
1025
  title: "Update not allowed",
1022
1026
  });
1023
1027
  }
1024
1028
  if (body === null) {
1025
- throw new APIError({
1029
+ throw new ForbiddenError({
1030
+ code: "update-not-allowed",
1026
1031
  detail: `preUpdate hook on ${req.params.id} returned null`,
1027
- status: 403,
1028
1032
  title: "Update not allowed",
1029
1033
  });
1030
1034
  }
@@ -1050,13 +1054,13 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1050
1054
  : DateTime.fromISO(bodyUpdatedAt);
1051
1055
 
1052
1056
  if (!clientTimestamp.isValid) {
1053
- throw new APIError({
1057
+ throw new BadRequestError({
1058
+ code: "invalid-conflict-detection-timestamp",
1054
1059
  detail: usingPreciseHeader
1055
1060
  ? "X-Unmodified-Since-ISO header could not be parsed as an ISO date"
1056
1061
  : usingHttpHeader
1057
1062
  ? "If-Unmodified-Since header could not be parsed as an HTTP date"
1058
1063
  : "_updatedAt body field could not be parsed as an ISO date",
1059
- status: 400,
1060
1064
  title: "Invalid conflict-detection timestamp",
1061
1065
  });
1062
1066
  }
@@ -1071,9 +1075,9 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1071
1075
  }
1072
1076
 
1073
1077
  if (serverTimestamp && !serverTimestamp.isValid) {
1074
- throw new APIError({
1078
+ throw new BadRequestError({
1079
+ code: "invalid-server-timestamp",
1075
1080
  detail: "Document timestamp could not be parsed as a date",
1076
- status: 400,
1077
1081
  title: "Invalid server timestamp",
1078
1082
  });
1079
1083
  }
@@ -1097,11 +1101,9 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1097
1101
  doc.set(body);
1098
1102
  await doc.save();
1099
1103
  } catch (error: unknown) {
1100
- throw new APIError({
1101
- cause: error,
1104
+ throw passthroughOrWrapWrite(error, {
1102
1105
  code: "update-save-error",
1103
- detail: `preUpdate hook save error on ${req.params.id}: ${errorMessage(error)}`,
1104
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
1106
+ detail: `preUpdate hook save error on ${req.params.id}: ${errorDetail(error)}`,
1105
1107
  status: 400,
1106
1108
  title: "preUpdate hook save error",
1107
1109
  });
@@ -1119,11 +1121,9 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1119
1121
  try {
1120
1122
  await options.postUpdate(doc, body, req, prevDoc);
1121
1123
  } catch (error: unknown) {
1122
- throw new APIError({
1123
- cause: error,
1124
+ throw passthroughOrWrap(error, {
1124
1125
  code: "post-update-hook-error",
1125
- detail: `postUpdate hook error on ${req.params.id}: ${errorMessage(error)}`,
1126
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
1126
+ detail: `postUpdate hook error on ${req.params.id}: ${errorDetail(error)}`,
1127
1127
  status: 400,
1128
1128
  title: "postUpdate hook error",
1129
1129
  });
@@ -1134,11 +1134,8 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1134
1134
  const serialized = await responseHandler(doc, "update", req, options);
1135
1135
  return res.json({data: serialized});
1136
1136
  } catch (error: unknown) {
1137
- throw new APIError({
1138
- cause: error,
1137
+ throw passthroughOrWrap(error, {
1139
1138
  code: "response-handler-error",
1140
- detail: errorMessage(error),
1141
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
1142
1139
  title: "responseHandler error",
1143
1140
  });
1144
1141
  }
@@ -1162,29 +1159,24 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1162
1159
  try {
1163
1160
  body = await options.preDelete(doc, req);
1164
1161
  } catch (error: unknown) {
1165
- if (isAPIError(error)) {
1166
- throw error;
1167
- }
1168
- throw new APIError({
1169
- cause: error,
1162
+ throw passthroughOrWrap(error, {
1170
1163
  code: "pre-delete-hook-error",
1171
- detail: `preDelete hook error on ${req.params.id}: ${errorMessage(error)}`,
1172
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
1164
+ detail: `preDelete hook error on ${req.params.id}: ${errorDetail(error)}`,
1173
1165
  status: 403,
1174
1166
  title: "preDelete hook error",
1175
1167
  });
1176
1168
  }
1177
1169
  if (body === undefined) {
1178
- throw new APIError({
1170
+ throw new ForbiddenError({
1171
+ code: "delete-not-allowed",
1179
1172
  detail: "A body must be returned from preDelete",
1180
- status: 403,
1181
1173
  title: "Delete not allowed",
1182
1174
  });
1183
1175
  }
1184
1176
  if (body === null) {
1185
- throw new APIError({
1177
+ throw new ForbiddenError({
1178
+ code: "delete-not-allowed",
1186
1179
  detail: `preDelete hook for ${req.params.id} returned null`,
1187
- status: 403,
1188
1180
  title: "Delete not allowed",
1189
1181
  });
1190
1182
  }
@@ -1202,11 +1194,8 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1202
1194
  try {
1203
1195
  await doc.deleteOne();
1204
1196
  } catch (error: unknown) {
1205
- throw new APIError({
1206
- cause: error,
1197
+ throw passthroughOrWrap(error, {
1207
1198
  code: "delete-error",
1208
- detail: errorMessage(error),
1209
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
1210
1199
  status: 400,
1211
1200
  title: "Delete error",
1212
1201
  });
@@ -1217,11 +1206,8 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1217
1206
  try {
1218
1207
  await options.postDelete(req, doc);
1219
1208
  } catch (error: unknown) {
1220
- throw new APIError({
1221
- cause: error,
1209
+ throw passthroughOrWrap(error, {
1222
1210
  code: "post-delete-hook-error",
1223
- detail: errorMessage(error),
1224
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
1225
1211
  status: 400,
1226
1212
  title: "postDelete hook error",
1227
1213
  });
@@ -1241,8 +1227,11 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1241
1227
 
1242
1228
  if (!(await checkPermissions("update", options.permissions.update, req.user))) {
1243
1229
  throw new APIError({
1230
+ code: "array-update-not-allowed",
1231
+ detail: `Access to PATCH on ${model.modelName} denied for ${req.user?.id}`,
1232
+ meta: {method: "PATCH", model: model.modelName},
1244
1233
  status: 405,
1245
- title: `Access to PATCH on ${model.modelName} denied for ${req.user?.id}`,
1234
+ title: "Access denied",
1246
1235
  });
1247
1236
  }
1248
1237
 
@@ -1250,16 +1239,20 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1250
1239
  // Make a copy for passing pre-saved values to hooks.
1251
1240
  const prevDoc = cloneDeep(doc);
1252
1241
  if (!doc) {
1253
- throw new APIError({
1254
- status: 404,
1255
- title: `Could not find document to PATCH: ${req.params.id}`,
1242
+ throw new NotFoundError({
1243
+ code: "document-not-found",
1244
+ detail: `Could not find document to PATCH: ${req.params.id}`,
1245
+ meta: {model: model.modelName},
1246
+ title: "Document not found",
1256
1247
  });
1257
1248
  }
1258
1249
 
1259
1250
  if (!(await checkPermissions("update", options.permissions.update, req.user, doc))) {
1260
- throw new APIError({
1261
- status: 403,
1262
- title: `Patch not allowed for user ${req.user?.id} on doc ${doc._id}`,
1251
+ throw new ForbiddenError({
1252
+ code: "update-not-allowed",
1253
+ detail: `Patch not allowed for user ${req.user?.id} on doc ${doc._id}`,
1254
+ meta: {model: model.modelName},
1255
+ title: "Update not allowed",
1263
1256
  });
1264
1257
  }
1265
1258
 
@@ -1269,11 +1262,13 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1269
1262
  // We apply the operation *before* the hooks. As far as the callers are concerned, this should
1270
1263
  // be like PATCHing the field and replacing the whole thing.
1271
1264
  if (operation !== "DELETE" && req.body[field] === undefined) {
1272
- throw new APIError({
1273
- status: 400,
1274
- title: `Malformed body, array operations should have a single, top level key, got: ${Object.keys(
1265
+ throw new BadRequestError({
1266
+ code: "malformed-array-operation-body",
1267
+ detail: `Malformed body, array operations should have a single, top level key, got: ${Object.keys(
1275
1268
  req.body
1276
1269
  ).join(",")}`,
1270
+ meta: {field},
1271
+ title: "Malformed array operation body",
1277
1272
  });
1278
1273
  }
1279
1274
 
@@ -1289,9 +1284,11 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1289
1284
  index = array.indexOf(itemId);
1290
1285
  }
1291
1286
  if (index === -1) {
1292
- throw new APIError({
1293
- status: 404,
1294
- title: `Could not find ${field}/${itemId}`,
1287
+ throw new NotFoundError({
1288
+ code: "array-item-not-found",
1289
+ detail: `Could not find ${field}/${itemId}`,
1290
+ meta: {field, itemId},
1291
+ title: "Array item not found",
1295
1292
  });
1296
1293
  }
1297
1294
  // For PATCHing an item by ID, we need to merge the objects so we don't override the _id or
@@ -1305,9 +1302,11 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1305
1302
  array.splice(index, 1);
1306
1303
  }
1307
1304
  } else {
1308
- throw new APIError({
1309
- status: 400,
1310
- title: `Invalid array operation: ${operation}`,
1305
+ throw new BadRequestError({
1306
+ code: "invalid-array-operation",
1307
+ detail: `Invalid array operation: ${operation}`,
1308
+ meta: {operation},
1309
+ title: "Invalid array operation",
1311
1310
  });
1312
1311
  }
1313
1312
  let body: Partial<T> | null = {[field]: array} as unknown as Partial<T>;
@@ -1315,14 +1314,8 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1315
1314
  try {
1316
1315
  body = transform<T>(options, body, "update", req.user) as Partial<T>;
1317
1316
  } catch (error: unknown) {
1318
- if (isAPIError(error)) {
1319
- throw error;
1320
- }
1321
- throw new APIError({
1322
- cause: error,
1317
+ throw passthroughOrWrap(error, {
1323
1318
  code: "transform-error",
1324
- detail: errorMessage(error),
1325
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
1326
1319
  status: 403,
1327
1320
  title: "Transform error",
1328
1321
  });
@@ -1332,26 +1325,24 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1332
1325
  try {
1333
1326
  body = await options.preUpdate(body, req);
1334
1327
  } catch (error: unknown) {
1335
- throw new APIError({
1336
- cause: error,
1328
+ throw passthroughOrWrap(error, {
1337
1329
  code: "pre-update-hook-error",
1338
- detail: `preUpdate hook error on ${req.params.id}: ${errorMessage(error)}`,
1339
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
1330
+ detail: `preUpdate hook error on ${req.params.id}: ${errorDetail(error)}`,
1340
1331
  status: 400,
1341
1332
  title: "preUpdate hook error",
1342
1333
  });
1343
1334
  }
1344
1335
  if (body === undefined) {
1345
- throw new APIError({
1336
+ throw new ForbiddenError({
1337
+ code: "update-not-allowed",
1346
1338
  detail: "A body must be returned from preUpdate",
1347
- status: 403,
1348
1339
  title: "Update not allowed",
1349
1340
  });
1350
1341
  }
1351
1342
  if (body === null) {
1352
- throw new APIError({
1343
+ throw new ForbiddenError({
1344
+ code: "update-not-allowed",
1353
1345
  detail: `preUpdate hook on ${req.params.id} returned null`,
1354
- status: 403,
1355
1346
  title: "Update not allowed",
1356
1347
  });
1357
1348
  }
@@ -1363,11 +1354,9 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1363
1354
  Object.assign(doc, body);
1364
1355
  await doc.save();
1365
1356
  } catch (error: unknown) {
1366
- throw new APIError({
1367
- cause: error,
1357
+ throw passthroughOrWrapWrite(error, {
1368
1358
  code: "update-save-error",
1369
- detail: `PATCH Pre Update error on ${req.params.id}: ${errorMessage(error)}`,
1370
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
1359
+ detail: `PATCH Pre Update error on ${req.params.id}: ${errorDetail(error)}`,
1371
1360
  status: 400,
1372
1361
  title: "PATCH Pre Update error",
1373
1362
  });
@@ -1382,11 +1371,9 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1382
1371
  prevDoc as unknown as T
1383
1372
  );
1384
1373
  } catch (error: unknown) {
1385
- throw new APIError({
1386
- cause: error,
1374
+ throw passthroughOrWrap(error, {
1387
1375
  code: "post-update-hook-error",
1388
- detail: `PATCH Post Update error on ${req.params.id}: ${errorMessage(error)}`,
1389
- disableExternalErrorTracking: getDisableExternalErrorTracking(error),
1376
+ detail: `PATCH Post Update error on ${req.params.id}: ${errorDetail(error)}`,
1390
1377
  status: 400,
1391
1378
  title: "PATCH Post Update error",
1392
1379
  });
@@ -1409,7 +1396,11 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1409
1396
  return arrayOperation(req, res, "DELETE");
1410
1397
  };
1411
1398
  // Set up routes for managing array fields. Check if there any array fields to add this for.
1412
- if (Object.values(model.schema.paths).find((config) => config.instance === "Array")) {
1399
+ if (
1400
+ (Object.values(model.schema.paths) as mongoose.SchemaType[]).find(
1401
+ (config) => config.instance === "Array"
1402
+ )
1403
+ ) {
1413
1404
  router.post(
1414
1405
  "/:id/:field",
1415
1406
  authenticateMiddleware(options.allowAnonymous),
@@ -1429,7 +1420,7 @@ function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>):
1429
1420
  router.use(apiErrorMiddleware);
1430
1421
 
1431
1422
  return router;
1432
- }
1423
+ };
1433
1424
 
1434
1425
  /**
1435
1426
  * Options for the asyncHandler function.