@theokit/http 1.2.0 → 2.1.0-next.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.
package/dist/index.d.ts CHANGED
@@ -1,6 +1,8 @@
1
1
  import { z } from 'zod';
2
2
  import { D as DiContainer, M as MiddlewareConsumerImpl } from './middleware-consumer-DcaksawH.js';
3
3
  export { a as MiddlewareConfigProxy, b as MiddlewareFn, N as NestMiddleware, R as ResolvedMiddleware, m as middlewareMatchesPath, r as resolveOrNew, c as runMiddleware } from './middleware-consumer-DcaksawH.js';
4
+ import { A as AccessDecision, U as UndeclaredRoutePolicy } from './route-access-Bq7eKXIc.js';
5
+ export { c as classifyAccess, u as undeclaredRouteRefusal, a as undeclaredRouteWarning } from './route-access-Bq7eKXIc.js';
4
6
  import { S as ServerHandle } from './types-CGthbcon.js';
5
7
  export { ReadinessCheck, TheoApp, TheoAppOptions } from './app.js';
6
8
  import * as ReactTypes from 'react';
@@ -411,6 +413,19 @@ interface WalkResult {
411
413
  guards: Function[];
412
414
  interceptors: Function[];
413
415
  filters: Function[];
416
+ /**
417
+ * What this route said about who may call it — decided HERE, once (usetheokit/theokit#576).
418
+ *
419
+ * Every controller dispatcher in this package consumes a `WalkResult`: `TheoApp`,
420
+ * `createDecoratorHandler` (which the framework's own controller dispatch reuses) and
421
+ * `httpDecoratorsPlugin`. Only the first of them classified access, and it did so by re-reading
422
+ * the metadata itself — so the other two served an undeclared route no matter what the app had
423
+ * configured, and a fourth dispatcher would have shipped with the same hole.
424
+ *
425
+ * Computing it on the walk is what makes "a route nobody declared is refused" a property of the
426
+ * package rather than of whichever dispatcher someone remembered to patch.
427
+ */
428
+ access: AccessDecision;
414
429
  /**
415
430
  * M47 — set when the member is bound via `@Expose(agent, opts)`. The dispatcher delegates such routes to
416
431
  * the agent runtime (`mountAgent`) instead of invoking a JSON handler. `undefined` for normal verb routes.
@@ -513,6 +528,17 @@ interface CreateDecoratorServerOptions {
513
528
  configure?: (consumer: MiddlewareConsumerImpl) => void;
514
529
  /** M47 — required when any controller `@Expose`-binds an agent; serves the agent route. */
515
530
  serveAgent?: ServeAgent;
531
+ /**
532
+ * What to do with a controller route that declared no access decision (#576).
533
+ *
534
+ * `'deny'` (default) refuses with 403. `'warn'` serves it after saying so once per route.
535
+ *
536
+ * This seam is where least privilege has to hold, not only `TheoApp`: the framework's own
537
+ * controller dispatch reuses this handler, `theokit dev` never runs the build gate that refuses
538
+ * an undeclared controller, and `@theokit/http` is published on its own. A gate that lives in one
539
+ * of three dispatchers is a lint, which is exactly what #576 reported.
540
+ */
541
+ undeclaredRoutes?: UndeclaredRoutePolicy;
516
542
  }
517
543
  /**
518
544
  * A pure Web-Standard controller handler: callable as `(request) => Response | null`
@@ -548,11 +574,31 @@ declare function createDecoratorServer(controllersOrOpts: Function[] | CreateDec
548
574
  interface HttpExceptionOptions {
549
575
  cause?: Error;
550
576
  description?: string;
577
+ /**
578
+ * Response headers that belong to THIS refusal (usetheokit/theokit#612).
579
+ *
580
+ * Some statuses are not complete without them. `429` without `Retry-After` tells a client it went
581
+ * too fast and not when it may return, so a well-behaved client can only guess and a badly
582
+ * behaved one retries immediately. The same holds for `401` + `WWW-Authenticate`, `405` + `Allow`
583
+ * and `503` + `Retry-After`: the header is not decoration, it is the half of the answer that says
584
+ * what to do next.
585
+ *
586
+ * Before this existed, a guard computing `X-RateLimit-*` had nowhere to put them — `canActivate`
587
+ * returns a boolean and owns no response — so the numbers were discarded at the boundary and the
588
+ * caller received a bare `403`.
589
+ *
590
+ * `content-type` is set by the dispatcher and is not overridable here: the body is always the
591
+ * `toJSON()` shape, and letting a header claim otherwise would describe a body that does not
592
+ * exist.
593
+ */
594
+ headers?: Readonly<Record<string, string>>;
551
595
  }
552
596
  declare class HttpException extends Error {
553
597
  readonly statusCode: number;
554
598
  readonly code: string;
555
599
  readonly description?: string;
600
+ /** Headers this refusal carries. Empty unless the thrower supplied some. See {@link HttpExceptionOptions.headers}. */
601
+ readonly headers: Readonly<Record<string, string>>;
556
602
  constructor(message: string, statusCode: number, options?: HttpExceptionOptions);
557
603
  toJSON(): {
558
604
  error: {
@@ -563,529 +609,79 @@ declare class HttpException extends Error {
563
609
  };
564
610
  };
565
611
  }
566
- declare const BadRequestException_base: {
567
- new (message?: string, options?: HttpExceptionOptions): {
568
- readonly statusCode: number;
569
- readonly code: string;
570
- readonly description?: string;
571
- toJSON(): {
572
- error: {
573
- description?: string | undefined;
574
- code: string;
575
- message: string;
576
- statusCode: number;
577
- };
578
- };
579
- name: string;
580
- message: string;
581
- stack?: string;
582
- cause?: unknown;
583
- };
584
- isError(error: unknown): error is Error;
585
- captureStackTrace(targetObject: object, constructorOpt?: Function): void;
586
- prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
587
- stackTraceLimit: number;
588
- };
612
+ /**
613
+ * The constructor shape every status-named exception shares.
614
+ *
615
+ * Declared explicitly (usetheokit/theokit#612) because inference erased it where it mattered most.
616
+ * Without a return type, `tsup` emitted each subclass's base as an ANONYMOUS structural object —
617
+ * `{ new (): { statusCode: number; name: string; message: string; stack?: string } }` — so
618
+ * `TooManyRequestsException` was, to a consumer's type checker, no longer an `Error`. Every app
619
+ * writing `throw new UnauthorizedException()` therefore tripped `@typescript-eslint/only-throw-error`
620
+ * against the framework's own exceptions, and the honest reading of that lint was correct: the
621
+ * published types no longer said these were errors.
622
+ */
623
+ type HttpExceptionConstructor = new (message?: string, options?: HttpExceptionOptions) => HttpException;
624
+ declare const BadRequestException_base: HttpExceptionConstructor;
589
625
  declare class BadRequestException extends BadRequestException_base {
590
626
  }
591
- declare const UnauthorizedException_base: {
592
- new (message?: string, options?: HttpExceptionOptions): {
593
- readonly statusCode: number;
594
- readonly code: string;
595
- readonly description?: string;
596
- toJSON(): {
597
- error: {
598
- description?: string | undefined;
599
- code: string;
600
- message: string;
601
- statusCode: number;
602
- };
603
- };
604
- name: string;
605
- message: string;
606
- stack?: string;
607
- cause?: unknown;
608
- };
609
- isError(error: unknown): error is Error;
610
- captureStackTrace(targetObject: object, constructorOpt?: Function): void;
611
- prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
612
- stackTraceLimit: number;
613
- };
627
+ declare const UnauthorizedException_base: HttpExceptionConstructor;
614
628
  declare class UnauthorizedException extends UnauthorizedException_base {
615
629
  }
616
- declare const ForbiddenException_base: {
617
- new (message?: string, options?: HttpExceptionOptions): {
618
- readonly statusCode: number;
619
- readonly code: string;
620
- readonly description?: string;
621
- toJSON(): {
622
- error: {
623
- description?: string | undefined;
624
- code: string;
625
- message: string;
626
- statusCode: number;
627
- };
628
- };
629
- name: string;
630
- message: string;
631
- stack?: string;
632
- cause?: unknown;
633
- };
634
- isError(error: unknown): error is Error;
635
- captureStackTrace(targetObject: object, constructorOpt?: Function): void;
636
- prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
637
- stackTraceLimit: number;
638
- };
630
+ declare const ForbiddenException_base: HttpExceptionConstructor;
639
631
  declare class ForbiddenException extends ForbiddenException_base {
640
632
  }
641
- declare const NotFoundException_base: {
642
- new (message?: string, options?: HttpExceptionOptions): {
643
- readonly statusCode: number;
644
- readonly code: string;
645
- readonly description?: string;
646
- toJSON(): {
647
- error: {
648
- description?: string | undefined;
649
- code: string;
650
- message: string;
651
- statusCode: number;
652
- };
653
- };
654
- name: string;
655
- message: string;
656
- stack?: string;
657
- cause?: unknown;
658
- };
659
- isError(error: unknown): error is Error;
660
- captureStackTrace(targetObject: object, constructorOpt?: Function): void;
661
- prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
662
- stackTraceLimit: number;
663
- };
633
+ declare const NotFoundException_base: HttpExceptionConstructor;
664
634
  declare class NotFoundException extends NotFoundException_base {
665
635
  }
666
- declare const MethodNotAllowedException_base: {
667
- new (message?: string, options?: HttpExceptionOptions): {
668
- readonly statusCode: number;
669
- readonly code: string;
670
- readonly description?: string;
671
- toJSON(): {
672
- error: {
673
- description?: string | undefined;
674
- code: string;
675
- message: string;
676
- statusCode: number;
677
- };
678
- };
679
- name: string;
680
- message: string;
681
- stack?: string;
682
- cause?: unknown;
683
- };
684
- isError(error: unknown): error is Error;
685
- captureStackTrace(targetObject: object, constructorOpt?: Function): void;
686
- prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
687
- stackTraceLimit: number;
688
- };
636
+ declare const MethodNotAllowedException_base: HttpExceptionConstructor;
689
637
  declare class MethodNotAllowedException extends MethodNotAllowedException_base {
690
638
  }
691
- declare const NotAcceptableException_base: {
692
- new (message?: string, options?: HttpExceptionOptions): {
693
- readonly statusCode: number;
694
- readonly code: string;
695
- readonly description?: string;
696
- toJSON(): {
697
- error: {
698
- description?: string | undefined;
699
- code: string;
700
- message: string;
701
- statusCode: number;
702
- };
703
- };
704
- name: string;
705
- message: string;
706
- stack?: string;
707
- cause?: unknown;
708
- };
709
- isError(error: unknown): error is Error;
710
- captureStackTrace(targetObject: object, constructorOpt?: Function): void;
711
- prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
712
- stackTraceLimit: number;
713
- };
639
+ declare const NotAcceptableException_base: HttpExceptionConstructor;
714
640
  declare class NotAcceptableException extends NotAcceptableException_base {
715
641
  }
716
- declare const RequestTimeoutException_base: {
717
- new (message?: string, options?: HttpExceptionOptions): {
718
- readonly statusCode: number;
719
- readonly code: string;
720
- readonly description?: string;
721
- toJSON(): {
722
- error: {
723
- description?: string | undefined;
724
- code: string;
725
- message: string;
726
- statusCode: number;
727
- };
728
- };
729
- name: string;
730
- message: string;
731
- stack?: string;
732
- cause?: unknown;
733
- };
734
- isError(error: unknown): error is Error;
735
- captureStackTrace(targetObject: object, constructorOpt?: Function): void;
736
- prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
737
- stackTraceLimit: number;
738
- };
642
+ declare const RequestTimeoutException_base: HttpExceptionConstructor;
739
643
  declare class RequestTimeoutException extends RequestTimeoutException_base {
740
644
  }
741
- declare const ConflictException_base: {
742
- new (message?: string, options?: HttpExceptionOptions): {
743
- readonly statusCode: number;
744
- readonly code: string;
745
- readonly description?: string;
746
- toJSON(): {
747
- error: {
748
- description?: string | undefined;
749
- code: string;
750
- message: string;
751
- statusCode: number;
752
- };
753
- };
754
- name: string;
755
- message: string;
756
- stack?: string;
757
- cause?: unknown;
758
- };
759
- isError(error: unknown): error is Error;
760
- captureStackTrace(targetObject: object, constructorOpt?: Function): void;
761
- prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
762
- stackTraceLimit: number;
763
- };
645
+ declare const ConflictException_base: HttpExceptionConstructor;
764
646
  declare class ConflictException extends ConflictException_base {
765
647
  }
766
- declare const GoneException_base: {
767
- new (message?: string, options?: HttpExceptionOptions): {
768
- readonly statusCode: number;
769
- readonly code: string;
770
- readonly description?: string;
771
- toJSON(): {
772
- error: {
773
- description?: string | undefined;
774
- code: string;
775
- message: string;
776
- statusCode: number;
777
- };
778
- };
779
- name: string;
780
- message: string;
781
- stack?: string;
782
- cause?: unknown;
783
- };
784
- isError(error: unknown): error is Error;
785
- captureStackTrace(targetObject: object, constructorOpt?: Function): void;
786
- prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
787
- stackTraceLimit: number;
788
- };
648
+ declare const GoneException_base: HttpExceptionConstructor;
789
649
  declare class GoneException extends GoneException_base {
790
650
  }
791
- declare const PreconditionFailedException_base: {
792
- new (message?: string, options?: HttpExceptionOptions): {
793
- readonly statusCode: number;
794
- readonly code: string;
795
- readonly description?: string;
796
- toJSON(): {
797
- error: {
798
- description?: string | undefined;
799
- code: string;
800
- message: string;
801
- statusCode: number;
802
- };
803
- };
804
- name: string;
805
- message: string;
806
- stack?: string;
807
- cause?: unknown;
808
- };
809
- isError(error: unknown): error is Error;
810
- captureStackTrace(targetObject: object, constructorOpt?: Function): void;
811
- prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
812
- stackTraceLimit: number;
813
- };
651
+ declare const PreconditionFailedException_base: HttpExceptionConstructor;
814
652
  declare class PreconditionFailedException extends PreconditionFailedException_base {
815
653
  }
816
- declare const PayloadTooLargeException_base: {
817
- new (message?: string, options?: HttpExceptionOptions): {
818
- readonly statusCode: number;
819
- readonly code: string;
820
- readonly description?: string;
821
- toJSON(): {
822
- error: {
823
- description?: string | undefined;
824
- code: string;
825
- message: string;
826
- statusCode: number;
827
- };
828
- };
829
- name: string;
830
- message: string;
831
- stack?: string;
832
- cause?: unknown;
833
- };
834
- isError(error: unknown): error is Error;
835
- captureStackTrace(targetObject: object, constructorOpt?: Function): void;
836
- prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
837
- stackTraceLimit: number;
838
- };
654
+ declare const PayloadTooLargeException_base: HttpExceptionConstructor;
839
655
  declare class PayloadTooLargeException extends PayloadTooLargeException_base {
840
656
  }
841
- declare const UnsupportedMediaTypeException_base: {
842
- new (message?: string, options?: HttpExceptionOptions): {
843
- readonly statusCode: number;
844
- readonly code: string;
845
- readonly description?: string;
846
- toJSON(): {
847
- error: {
848
- description?: string | undefined;
849
- code: string;
850
- message: string;
851
- statusCode: number;
852
- };
853
- };
854
- name: string;
855
- message: string;
856
- stack?: string;
857
- cause?: unknown;
858
- };
859
- isError(error: unknown): error is Error;
860
- captureStackTrace(targetObject: object, constructorOpt?: Function): void;
861
- prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
862
- stackTraceLimit: number;
863
- };
657
+ declare const UnsupportedMediaTypeException_base: HttpExceptionConstructor;
864
658
  declare class UnsupportedMediaTypeException extends UnsupportedMediaTypeException_base {
865
659
  }
866
- declare const ImATeapotException_base: {
867
- new (message?: string, options?: HttpExceptionOptions): {
868
- readonly statusCode: number;
869
- readonly code: string;
870
- readonly description?: string;
871
- toJSON(): {
872
- error: {
873
- description?: string | undefined;
874
- code: string;
875
- message: string;
876
- statusCode: number;
877
- };
878
- };
879
- name: string;
880
- message: string;
881
- stack?: string;
882
- cause?: unknown;
883
- };
884
- isError(error: unknown): error is Error;
885
- captureStackTrace(targetObject: object, constructorOpt?: Function): void;
886
- prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
887
- stackTraceLimit: number;
888
- };
660
+ declare const ImATeapotException_base: HttpExceptionConstructor;
889
661
  declare class ImATeapotException extends ImATeapotException_base {
890
662
  }
891
- declare const UnprocessableEntityException_base: {
892
- new (message?: string, options?: HttpExceptionOptions): {
893
- readonly statusCode: number;
894
- readonly code: string;
895
- readonly description?: string;
896
- toJSON(): {
897
- error: {
898
- description?: string | undefined;
899
- code: string;
900
- message: string;
901
- statusCode: number;
902
- };
903
- };
904
- name: string;
905
- message: string;
906
- stack?: string;
907
- cause?: unknown;
908
- };
909
- isError(error: unknown): error is Error;
910
- captureStackTrace(targetObject: object, constructorOpt?: Function): void;
911
- prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
912
- stackTraceLimit: number;
913
- };
663
+ declare const UnprocessableEntityException_base: HttpExceptionConstructor;
914
664
  declare class UnprocessableEntityException extends UnprocessableEntityException_base {
915
665
  }
916
- declare const InternalServerErrorException_base: {
917
- new (message?: string, options?: HttpExceptionOptions): {
918
- readonly statusCode: number;
919
- readonly code: string;
920
- readonly description?: string;
921
- toJSON(): {
922
- error: {
923
- description?: string | undefined;
924
- code: string;
925
- message: string;
926
- statusCode: number;
927
- };
928
- };
929
- name: string;
930
- message: string;
931
- stack?: string;
932
- cause?: unknown;
933
- };
934
- isError(error: unknown): error is Error;
935
- captureStackTrace(targetObject: object, constructorOpt?: Function): void;
936
- prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
937
- stackTraceLimit: number;
938
- };
666
+ declare const InternalServerErrorException_base: HttpExceptionConstructor;
939
667
  declare class InternalServerErrorException extends InternalServerErrorException_base {
940
668
  }
941
- declare const NotImplementedException_base: {
942
- new (message?: string, options?: HttpExceptionOptions): {
943
- readonly statusCode: number;
944
- readonly code: string;
945
- readonly description?: string;
946
- toJSON(): {
947
- error: {
948
- description?: string | undefined;
949
- code: string;
950
- message: string;
951
- statusCode: number;
952
- };
953
- };
954
- name: string;
955
- message: string;
956
- stack?: string;
957
- cause?: unknown;
958
- };
959
- isError(error: unknown): error is Error;
960
- captureStackTrace(targetObject: object, constructorOpt?: Function): void;
961
- prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
962
- stackTraceLimit: number;
963
- };
669
+ declare const NotImplementedException_base: HttpExceptionConstructor;
964
670
  declare class NotImplementedException extends NotImplementedException_base {
965
671
  }
966
- declare const BadGatewayException_base: {
967
- new (message?: string, options?: HttpExceptionOptions): {
968
- readonly statusCode: number;
969
- readonly code: string;
970
- readonly description?: string;
971
- toJSON(): {
972
- error: {
973
- description?: string | undefined;
974
- code: string;
975
- message: string;
976
- statusCode: number;
977
- };
978
- };
979
- name: string;
980
- message: string;
981
- stack?: string;
982
- cause?: unknown;
983
- };
984
- isError(error: unknown): error is Error;
985
- captureStackTrace(targetObject: object, constructorOpt?: Function): void;
986
- prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
987
- stackTraceLimit: number;
988
- };
672
+ declare const BadGatewayException_base: HttpExceptionConstructor;
989
673
  declare class BadGatewayException extends BadGatewayException_base {
990
674
  }
991
- declare const ServiceUnavailableException_base: {
992
- new (message?: string, options?: HttpExceptionOptions): {
993
- readonly statusCode: number;
994
- readonly code: string;
995
- readonly description?: string;
996
- toJSON(): {
997
- error: {
998
- description?: string | undefined;
999
- code: string;
1000
- message: string;
1001
- statusCode: number;
1002
- };
1003
- };
1004
- name: string;
1005
- message: string;
1006
- stack?: string;
1007
- cause?: unknown;
1008
- };
1009
- isError(error: unknown): error is Error;
1010
- captureStackTrace(targetObject: object, constructorOpt?: Function): void;
1011
- prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
1012
- stackTraceLimit: number;
1013
- };
675
+ declare const ServiceUnavailableException_base: HttpExceptionConstructor;
1014
676
  declare class ServiceUnavailableException extends ServiceUnavailableException_base {
1015
677
  }
1016
- declare const GatewayTimeoutException_base: {
1017
- new (message?: string, options?: HttpExceptionOptions): {
1018
- readonly statusCode: number;
1019
- readonly code: string;
1020
- readonly description?: string;
1021
- toJSON(): {
1022
- error: {
1023
- description?: string | undefined;
1024
- code: string;
1025
- message: string;
1026
- statusCode: number;
1027
- };
1028
- };
1029
- name: string;
1030
- message: string;
1031
- stack?: string;
1032
- cause?: unknown;
1033
- };
1034
- isError(error: unknown): error is Error;
1035
- captureStackTrace(targetObject: object, constructorOpt?: Function): void;
1036
- prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
1037
- stackTraceLimit: number;
1038
- };
678
+ declare const GatewayTimeoutException_base: HttpExceptionConstructor;
1039
679
  declare class GatewayTimeoutException extends GatewayTimeoutException_base {
1040
680
  }
1041
- declare const HttpVersionNotSupportedException_base: {
1042
- new (message?: string, options?: HttpExceptionOptions): {
1043
- readonly statusCode: number;
1044
- readonly code: string;
1045
- readonly description?: string;
1046
- toJSON(): {
1047
- error: {
1048
- description?: string | undefined;
1049
- code: string;
1050
- message: string;
1051
- statusCode: number;
1052
- };
1053
- };
1054
- name: string;
1055
- message: string;
1056
- stack?: string;
1057
- cause?: unknown;
1058
- };
1059
- isError(error: unknown): error is Error;
1060
- captureStackTrace(targetObject: object, constructorOpt?: Function): void;
1061
- prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
1062
- stackTraceLimit: number;
1063
- };
681
+ declare const HttpVersionNotSupportedException_base: HttpExceptionConstructor;
1064
682
  declare class HttpVersionNotSupportedException extends HttpVersionNotSupportedException_base {
1065
683
  }
1066
- declare const TooManyRequestsException_base: {
1067
- new (message?: string, options?: HttpExceptionOptions): {
1068
- readonly statusCode: number;
1069
- readonly code: string;
1070
- readonly description?: string;
1071
- toJSON(): {
1072
- error: {
1073
- description?: string | undefined;
1074
- code: string;
1075
- message: string;
1076
- statusCode: number;
1077
- };
1078
- };
1079
- name: string;
1080
- message: string;
1081
- stack?: string;
1082
- cause?: unknown;
1083
- };
1084
- isError(error: unknown): error is Error;
1085
- captureStackTrace(targetObject: object, constructorOpt?: Function): void;
1086
- prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
1087
- stackTraceLimit: number;
1088
- };
684
+ declare const TooManyRequestsException_base: HttpExceptionConstructor;
1089
685
  declare class TooManyRequestsException extends TooManyRequestsException_base {
1090
686
  }
1091
687
  /**
@@ -1136,6 +732,34 @@ declare const HttpStatus: {
1136
732
  };
1137
733
  type HttpStatusCode = (typeof HttpStatus)[keyof typeof HttpStatus];
1138
734
 
735
+ /**
736
+ * The one place an `HttpException` becomes a `Response` (usetheokit/theokit#612).
737
+ *
738
+ * There were four: `app.ts` (twice), `theokit-plugin.ts`, `create-server.ts` and
739
+ * `exception-filter-chain.ts` each built `new Response(JSON.stringify(ex.toJSON()), …)` by hand
740
+ * with `content-type` as the only header. Four copies of one decision is four places to forget
741
+ * something, and when `HttpException` grew headers, three of them would have kept discarding them —
742
+ * which is the same defect as the guard contract dropping them, one layer down.
743
+ *
744
+ * This module is that decision, once. It is deliberately NOT a method on `HttpException`: the
745
+ * exception is a domain value that a CLI, a queue consumer or a test can raise and inspect without
746
+ * a `Response` existing anywhere, and giving it a `toResponse()` would put the HTTP transport
747
+ * inside the error type. The transport owns the transport.
748
+ */
749
+
750
+ /**
751
+ * Render an `HttpException` as the response it describes.
752
+ *
753
+ * The body is always `exception.toJSON()`. `content-type` is written first so a caller-supplied
754
+ * header can never claim the body is something it is not, and every other header the exception
755
+ * carries is applied on top — `Retry-After` on a 429, `WWW-Authenticate` on a 401, `Allow` on a
756
+ * 405.
757
+ *
758
+ * @param exception the refusal to render
759
+ * @returns a JSON response with the exception's status and headers
760
+ */
761
+ declare function httpExceptionToResponse(exception: HttpException): Response;
762
+
1139
763
  /**
1140
764
  * Typed Client — end-to-end type inference from route contracts.
1141
765
  *
@@ -1454,4 +1078,4 @@ declare function revalidatePath(path: string): void;
1454
1078
  */
1455
1079
  declare function getRevalidationSignals(): RevalidationSignal[];
1456
1080
 
1457
- export { All, type ArgumentsHost, BadGatewayException, BadRequestException, Body, CATCH_EXCEPTIONS, CONTROLLER_PREFIX, type CanActivate, Catch, ConflictException, Controller, type ControllerMeta, type ControllerOptions, type CreateDecoratorServerOptions, type DecoratorHandler, Delete, DiContainer, type DigestedError, EXPOSE_AGENT, type ErrorContext, type ExceptionFilter, type ExecutionContext, Expose, type ExposeEntry, type ExposeOptions, ForbiddenException, GatewayTimeoutException, Get, GoneException, Head, Header, Headers, HostParam, HttpCode, HttpDecoratorsConfigError, HttpException, type HttpExceptionOptions, HttpStatus, type HttpStatusCode, type HttpVerb, HttpVersionNotSupportedException, ImATeapotException, type Interceptor, InternalServerErrorException, Ip, type MetadataKey, MethodNotAllowedException, MiddlewareConsumerImpl, NotAcceptableException, NotFoundException, NotImplementedException, Options, PUBLIC_ROUTE_METADATA, Param, type ParamEntry, type ParamSource, Patch, PayloadTooLargeException, Post, PreconditionFailedException, Public, Put, Query, ROUTE_HEADERS, ROUTE_METHODS, ROUTE_PARAMS, ROUTE_REDIRECT, ROUTE_STATUS, Redirect, type RedirectMeta, Reflector, Req, RequestTimeoutException, Res, type RevalidationSignal, type RouteDefinition, type RouteMap, type RouteMethodEntry, type RouteRegistration, type RouteTree, type ServeAgent, ServiceUnavailableException, Session, SetMetadata, SkipThrottle, type StaticOptions, type StreamRenderOptions, type StreamRenderResult, type SwcCore, type TheoRequestContext, Throttle, type ThrottleOptions, TooManyRequestsException, type TypedClient, TypedClientError, USE_FILTERS, USE_GUARDS, USE_INTERCEPTORS, UnauthorizedException, UnprocessableEntityException, UnsupportedMediaTypeException, UseFilters, UseGuards, UseInterceptors, type WalkResult, composeComponentTree, contract, createDecorator, createDecoratorHandler, createDecoratorServer, createExecutionContext, createStaticHandler, createTypedClient, digestError, getMeta, getMimeType, getRequestContext, getRevalidationSignals, getThrottleOptions, isControllerClass, isSafePath, isThrottleSkipped, joinPath, loadControllerWithSwc, loadControllersFromGlob, registerControllers, renderToStream, resolveDtoSchema, revalidatePath, revalidateTag, runExceptionFilters, runInterceptors, setMeta, streamToResponse, transformControllerSource, tryGetRequestContext, walkControllerMetadata };
1081
+ export { AccessDecision, All, type ArgumentsHost, BadGatewayException, BadRequestException, Body, CATCH_EXCEPTIONS, CONTROLLER_PREFIX, type CanActivate, Catch, ConflictException, Controller, type ControllerMeta, type ControllerOptions, type CreateDecoratorServerOptions, type DecoratorHandler, Delete, DiContainer, type DigestedError, EXPOSE_AGENT, type ErrorContext, type ExceptionFilter, type ExecutionContext, Expose, type ExposeEntry, type ExposeOptions, ForbiddenException, GatewayTimeoutException, Get, GoneException, Head, Header, Headers, HostParam, HttpCode, HttpDecoratorsConfigError, HttpException, type HttpExceptionOptions, HttpStatus, type HttpStatusCode, type HttpVerb, HttpVersionNotSupportedException, ImATeapotException, type Interceptor, InternalServerErrorException, Ip, type MetadataKey, MethodNotAllowedException, MiddlewareConsumerImpl, NotAcceptableException, NotFoundException, NotImplementedException, Options, PUBLIC_ROUTE_METADATA, Param, type ParamEntry, type ParamSource, Patch, PayloadTooLargeException, Post, PreconditionFailedException, Public, Put, Query, ROUTE_HEADERS, ROUTE_METHODS, ROUTE_PARAMS, ROUTE_REDIRECT, ROUTE_STATUS, Redirect, type RedirectMeta, Reflector, Req, RequestTimeoutException, Res, type RevalidationSignal, type RouteDefinition, type RouteMap, type RouteMethodEntry, type RouteRegistration, type RouteTree, type ServeAgent, ServiceUnavailableException, Session, SetMetadata, SkipThrottle, type StaticOptions, type StreamRenderOptions, type StreamRenderResult, type SwcCore, type TheoRequestContext, Throttle, type ThrottleOptions, TooManyRequestsException, type TypedClient, TypedClientError, USE_FILTERS, USE_GUARDS, USE_INTERCEPTORS, UnauthorizedException, UndeclaredRoutePolicy, UnprocessableEntityException, UnsupportedMediaTypeException, UseFilters, UseGuards, UseInterceptors, type WalkResult, composeComponentTree, contract, createDecorator, createDecoratorHandler, createDecoratorServer, createExecutionContext, createStaticHandler, createTypedClient, digestError, getMeta, getMimeType, getRequestContext, getRevalidationSignals, getThrottleOptions, httpExceptionToResponse, isControllerClass, isSafePath, isThrottleSkipped, joinPath, loadControllerWithSwc, loadControllersFromGlob, registerControllers, renderToStream, resolveDtoSchema, revalidatePath, revalidateTag, runExceptionFilters, runInterceptors, setMeta, streamToResponse, transformControllerSource, tryGetRequestContext, walkControllerMetadata };