@metamask/ramps-controller 2.0.0 → 3.0.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 (48) hide show
  1. package/CHANGELOG.md +31 -1
  2. package/dist/RampsController.cjs +324 -9
  3. package/dist/RampsController.cjs.map +1 -1
  4. package/dist/RampsController.d.cts +117 -12
  5. package/dist/RampsController.d.cts.map +1 -1
  6. package/dist/RampsController.d.mts +117 -12
  7. package/dist/RampsController.d.mts.map +1 -1
  8. package/dist/RampsController.mjs +324 -9
  9. package/dist/RampsController.mjs.map +1 -1
  10. package/dist/RampsService-method-action-types.cjs.map +1 -1
  11. package/dist/RampsService-method-action-types.d.cts +33 -1
  12. package/dist/RampsService-method-action-types.d.cts.map +1 -1
  13. package/dist/RampsService-method-action-types.d.mts +33 -1
  14. package/dist/RampsService-method-action-types.d.mts.map +1 -1
  15. package/dist/RampsService-method-action-types.mjs.map +1 -1
  16. package/dist/RampsService.cjs +126 -24
  17. package/dist/RampsService.cjs.map +1 -1
  18. package/dist/RampsService.d.cts +178 -1
  19. package/dist/RampsService.d.cts.map +1 -1
  20. package/dist/RampsService.d.mts +178 -1
  21. package/dist/RampsService.d.mts.map +1 -1
  22. package/dist/RampsService.mjs +122 -23
  23. package/dist/RampsService.mjs.map +1 -1
  24. package/dist/RequestCache.cjs +98 -0
  25. package/dist/RequestCache.cjs.map +1 -0
  26. package/dist/RequestCache.d.cts +93 -0
  27. package/dist/RequestCache.d.cts.map +1 -0
  28. package/dist/RequestCache.d.mts +93 -0
  29. package/dist/RequestCache.d.mts.map +1 -0
  30. package/dist/RequestCache.mjs +90 -0
  31. package/dist/RequestCache.mjs.map +1 -0
  32. package/dist/index.cjs +14 -1
  33. package/dist/index.cjs.map +1 -1
  34. package/dist/index.d.cts +8 -4
  35. package/dist/index.d.cts.map +1 -1
  36. package/dist/index.d.mts +8 -4
  37. package/dist/index.d.mts.map +1 -1
  38. package/dist/index.mjs +3 -1
  39. package/dist/index.mjs.map +1 -1
  40. package/dist/selectors.cjs +81 -0
  41. package/dist/selectors.cjs.map +1 -0
  42. package/dist/selectors.d.cts +75 -0
  43. package/dist/selectors.d.cts.map +1 -0
  44. package/dist/selectors.d.mts +75 -0
  45. package/dist/selectors.d.mts.map +1 -0
  46. package/dist/selectors.mjs +77 -0
  47. package/dist/selectors.mjs.map +1 -0
  48. package/package.json +2 -2
@@ -1,7 +1,9 @@
1
1
  import type { ControllerGetStateAction, ControllerStateChangeEvent } from "@metamask/base-controller";
2
2
  import { BaseController } from "@metamask/base-controller";
3
3
  import type { Messenger } from "@metamask/messenger";
4
- import type { RampsServiceGetGeolocationAction } from "./RampsService-method-action-types.cjs";
4
+ import type { Country, Eligibility, TokensResponse } from "./RampsService.cjs";
5
+ import type { RampsServiceGetGeolocationAction, RampsServiceGetCountriesAction, RampsServiceGetEligibilityAction, RampsServiceGetTokensAction } from "./RampsService-method-action-types.cjs";
6
+ import type { RequestCache as RequestCacheType, RequestState, ExecuteRequestOptions } from "./RequestCache.cjs";
5
7
  /**
6
8
  * The name of the {@link RampsController}, used to namespace the
7
9
  * controller's actions and events and to namespace the controller's state data
@@ -13,9 +15,24 @@ export declare const controllerName = "RampsController";
13
15
  */
14
16
  export type RampsControllerState = {
15
17
  /**
16
- * The user's country code determined by geolocation.
18
+ * The user's selected region code (e.g., "US-CA").
19
+ * Initially set via geolocation fetch, but can be manually changed by the user.
17
20
  */
18
- geolocation: string | null;
21
+ userRegion: string | null;
22
+ /**
23
+ * Eligibility information for the user's current region.
24
+ */
25
+ eligibility: Eligibility | null;
26
+ /**
27
+ * Tokens fetched for the current region and action.
28
+ * Contains topTokens and allTokens arrays.
29
+ */
30
+ tokens: TokensResponse | null;
31
+ /**
32
+ * Cache of request states, keyed by cache key.
33
+ * This stores loading, success, and error states for API requests.
34
+ */
35
+ requests: RequestCacheType;
19
36
  };
20
37
  /**
21
38
  * Constructs the default {@link RampsController} state. This allows
@@ -37,7 +54,7 @@ export type RampsControllerActions = RampsControllerGetStateAction;
37
54
  /**
38
55
  * Actions from other messengers that {@link RampsController} calls.
39
56
  */
40
- type AllowedActions = RampsServiceGetGeolocationAction;
57
+ type AllowedActions = RampsServiceGetGeolocationAction | RampsServiceGetCountriesAction | RampsServiceGetEligibilityAction | RampsServiceGetTokensAction;
41
58
  /**
42
59
  * Published when the state of {@link RampsController} changes.
43
60
  */
@@ -55,10 +72,24 @@ type AllowedEvents = never;
55
72
  * {@link RampsController}.
56
73
  */
57
74
  export type RampsControllerMessenger = Messenger<typeof controllerName, RampsControllerActions | AllowedActions, RampsControllerEvents | AllowedEvents>;
75
+ /**
76
+ * Configuration options for the RampsController.
77
+ */
78
+ export type RampsControllerOptions = {
79
+ /** The messenger suited for this controller. */
80
+ messenger: RampsControllerMessenger;
81
+ /** The desired state with which to initialize this controller. */
82
+ state?: Partial<RampsControllerState>;
83
+ /** Time to live for cached requests in milliseconds. Defaults to 15 minutes. */
84
+ requestCacheTTL?: number;
85
+ /** Maximum number of entries in the request cache. Defaults to 250. */
86
+ requestCacheMaxSize?: number;
87
+ };
58
88
  /**
59
89
  * Manages cryptocurrency on/off ramps functionality.
60
90
  */
61
91
  export declare class RampsController extends BaseController<typeof controllerName, RampsControllerState, RampsControllerMessenger> {
92
+ #private;
62
93
  /**
63
94
  * Constructs a new {@link RampsController}.
64
95
  *
@@ -66,17 +97,91 @@ export declare class RampsController extends BaseController<typeof controllerNam
66
97
  * @param args.messenger - The messenger suited for this controller.
67
98
  * @param args.state - The desired state with which to initialize this
68
99
  * controller. Missing properties will be filled in with defaults.
100
+ * @param args.requestCacheTTL - Time to live for cached requests in milliseconds.
101
+ * @param args.requestCacheMaxSize - Maximum number of entries in the request cache.
69
102
  */
70
- constructor({ messenger, state, }: {
71
- messenger: RampsControllerMessenger;
72
- state?: Partial<RampsControllerState>;
73
- });
103
+ constructor({ messenger, state, requestCacheTTL, requestCacheMaxSize, }: RampsControllerOptions);
74
104
  /**
75
- * Updates the user's geolocation.
76
- * This method calls the RampsService to get the geolocation
77
- * and stores the result in state.
105
+ * Executes a request with caching and deduplication.
106
+ *
107
+ * If a request with the same cache key is already in flight, returns the
108
+ * existing promise. If valid cached data exists, returns it without making
109
+ * a new request.
110
+ *
111
+ * @param cacheKey - Unique identifier for this request.
112
+ * @param fetcher - Function that performs the actual fetch. Receives an AbortSignal.
113
+ * @param options - Options for cache behavior.
114
+ * @returns The result of the request.
115
+ */
116
+ executeRequest<TResult>(cacheKey: string, fetcher: (signal: AbortSignal) => Promise<TResult>, options?: ExecuteRequestOptions): Promise<TResult>;
117
+ /**
118
+ * Aborts a pending request if one exists.
119
+ *
120
+ * @param cacheKey - The cache key of the request to abort.
121
+ * @returns True if a request was aborted.
122
+ */
123
+ abortRequest(cacheKey: string): boolean;
124
+ /**
125
+ * Gets the state of a specific cached request.
126
+ *
127
+ * @param cacheKey - The cache key to look up.
128
+ * @returns The request state, or undefined if not cached.
129
+ */
130
+ getRequestState(cacheKey: string): RequestState | undefined;
131
+ /**
132
+ * Updates the user's region by fetching geolocation and eligibility.
133
+ * This method calls the RampsService to get the geolocation,
134
+ * then automatically fetches eligibility for that region.
135
+ *
136
+ * @param options - Options for cache behavior.
137
+ * @returns The user region string.
138
+ */
139
+ updateUserRegion(options?: ExecuteRequestOptions): Promise<string>;
140
+ /**
141
+ * Sets the user's region manually (without fetching geolocation).
142
+ * This allows users to override the detected region.
143
+ *
144
+ * @param region - The region code to set (e.g., "US-CA").
145
+ * @param options - Options for cache behavior when fetching eligibility.
146
+ * @returns The eligibility information for the region.
147
+ */
148
+ setUserRegion(region: string, options?: ExecuteRequestOptions): Promise<Eligibility>;
149
+ /**
150
+ * Initializes the controller by fetching the user's region from geolocation.
151
+ * This should be called once at app startup to set up the initial region.
152
+ * After the region is set and eligibility is determined, tokens are fetched
153
+ * and saved to state.
154
+ *
155
+ * @param options - Options for cache behavior.
156
+ * @returns Promise that resolves when initialization is complete.
157
+ */
158
+ init(options?: ExecuteRequestOptions): Promise<void>;
159
+ /**
160
+ * Updates the eligibility information for a given region.
161
+ *
162
+ * @param isoCode - The ISO code for the region (e.g., "us", "fr", "us-ny").
163
+ * @param options - Options for cache behavior.
164
+ * @returns The eligibility information.
165
+ */
166
+ updateEligibility(isoCode: string, options?: ExecuteRequestOptions): Promise<Eligibility>;
167
+ /**
168
+ * Fetches the list of supported countries for a given ramp action.
169
+ *
170
+ * @param action - The ramp action type ('buy' or 'sell').
171
+ * @param options - Options for cache behavior.
172
+ * @returns An array of countries with their eligibility information.
173
+ */
174
+ getCountries(action?: 'buy' | 'sell', options?: ExecuteRequestOptions): Promise<Country[]>;
175
+ /**
176
+ * Fetches the list of available tokens for a given region and action.
177
+ * The tokens are saved in the controller state once fetched.
178
+ *
179
+ * @param region - The region code (e.g., "us", "fr", "us-ny"). If not provided, uses the user's region from controller state.
180
+ * @param action - The ramp action type ('buy' or 'sell').
181
+ * @param options - Options for cache behavior.
182
+ * @returns The tokens response containing topTokens and allTokens.
78
183
  */
79
- updateGeolocation(): Promise<void>;
184
+ getTokens(region?: string, action?: 'buy' | 'sell', options?: ExecuteRequestOptions): Promise<TokensResponse>;
80
185
  }
81
186
  export {};
82
187
  //# sourceMappingURL=RampsController.d.cts.map
@@ -1 +1 @@
1
- {"version":3,"file":"RampsController.d.cts","sourceRoot":"","sources":["../src/RampsController.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EACxB,0BAA0B,EAE3B,kCAAkC;AACnC,OAAO,EAAE,cAAc,EAAE,kCAAkC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,4BAA4B;AAErD,OAAO,KAAK,EAAE,gCAAgC,EAAE,+CAA2C;AAI3F;;;;GAIG;AACH,eAAO,MAAM,cAAc,oBAAoB,CAAC;AAIhD;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC;;OAEG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,CAAC;AAcF;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,IAAI,oBAAoB,CAIrE;AAID;;GAEG;AACH,MAAM,MAAM,6BAA6B,GAAG,wBAAwB,CAClE,OAAO,cAAc,EACrB,oBAAoB,CACrB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,6BAA6B,CAAC;AAEnE;;GAEG;AACH,KAAK,cAAc,GAAG,gCAAgC,CAAC;AAEvD;;GAEG;AACH,MAAM,MAAM,+BAA+B,GAAG,0BAA0B,CACtE,OAAO,cAAc,EACrB,oBAAoB,CACrB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,+BAA+B,CAAC;AAEpE;;GAEG;AACH,KAAK,aAAa,GAAG,KAAK,CAAC;AAE3B;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG,SAAS,CAC9C,OAAO,cAAc,EACrB,sBAAsB,GAAG,cAAc,EACvC,qBAAqB,GAAG,aAAa,CACtC,CAAC;AAIF;;GAEG;AACH,qBAAa,eAAgB,SAAQ,cAAc,CACjD,OAAO,cAAc,EACrB,oBAAoB,EACpB,wBAAwB,CACzB;IACC;;;;;;;OAOG;gBACS,EACV,SAAS,EACT,KAAU,GACX,EAAE;QACD,SAAS,EAAE,wBAAwB,CAAC;QACpC,KAAK,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;KACvC;IAYD;;;;OAIG;IACG,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;CASzC"}
1
+ {"version":3,"file":"RampsController.d.cts","sourceRoot":"","sources":["../src/RampsController.ts"],"names":[],"mappings":"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"}
@@ -1,7 +1,9 @@
1
1
  import type { ControllerGetStateAction, ControllerStateChangeEvent } from "@metamask/base-controller";
2
2
  import { BaseController } from "@metamask/base-controller";
3
3
  import type { Messenger } from "@metamask/messenger";
4
- import type { RampsServiceGetGeolocationAction } from "./RampsService-method-action-types.mjs";
4
+ import type { Country, Eligibility, TokensResponse } from "./RampsService.mjs";
5
+ import type { RampsServiceGetGeolocationAction, RampsServiceGetCountriesAction, RampsServiceGetEligibilityAction, RampsServiceGetTokensAction } from "./RampsService-method-action-types.mjs";
6
+ import type { RequestCache as RequestCacheType, RequestState, ExecuteRequestOptions } from "./RequestCache.mjs";
5
7
  /**
6
8
  * The name of the {@link RampsController}, used to namespace the
7
9
  * controller's actions and events and to namespace the controller's state data
@@ -13,9 +15,24 @@ export declare const controllerName = "RampsController";
13
15
  */
14
16
  export type RampsControllerState = {
15
17
  /**
16
- * The user's country code determined by geolocation.
18
+ * The user's selected region code (e.g., "US-CA").
19
+ * Initially set via geolocation fetch, but can be manually changed by the user.
17
20
  */
18
- geolocation: string | null;
21
+ userRegion: string | null;
22
+ /**
23
+ * Eligibility information for the user's current region.
24
+ */
25
+ eligibility: Eligibility | null;
26
+ /**
27
+ * Tokens fetched for the current region and action.
28
+ * Contains topTokens and allTokens arrays.
29
+ */
30
+ tokens: TokensResponse | null;
31
+ /**
32
+ * Cache of request states, keyed by cache key.
33
+ * This stores loading, success, and error states for API requests.
34
+ */
35
+ requests: RequestCacheType;
19
36
  };
20
37
  /**
21
38
  * Constructs the default {@link RampsController} state. This allows
@@ -37,7 +54,7 @@ export type RampsControllerActions = RampsControllerGetStateAction;
37
54
  /**
38
55
  * Actions from other messengers that {@link RampsController} calls.
39
56
  */
40
- type AllowedActions = RampsServiceGetGeolocationAction;
57
+ type AllowedActions = RampsServiceGetGeolocationAction | RampsServiceGetCountriesAction | RampsServiceGetEligibilityAction | RampsServiceGetTokensAction;
41
58
  /**
42
59
  * Published when the state of {@link RampsController} changes.
43
60
  */
@@ -55,10 +72,24 @@ type AllowedEvents = never;
55
72
  * {@link RampsController}.
56
73
  */
57
74
  export type RampsControllerMessenger = Messenger<typeof controllerName, RampsControllerActions | AllowedActions, RampsControllerEvents | AllowedEvents>;
75
+ /**
76
+ * Configuration options for the RampsController.
77
+ */
78
+ export type RampsControllerOptions = {
79
+ /** The messenger suited for this controller. */
80
+ messenger: RampsControllerMessenger;
81
+ /** The desired state with which to initialize this controller. */
82
+ state?: Partial<RampsControllerState>;
83
+ /** Time to live for cached requests in milliseconds. Defaults to 15 minutes. */
84
+ requestCacheTTL?: number;
85
+ /** Maximum number of entries in the request cache. Defaults to 250. */
86
+ requestCacheMaxSize?: number;
87
+ };
58
88
  /**
59
89
  * Manages cryptocurrency on/off ramps functionality.
60
90
  */
61
91
  export declare class RampsController extends BaseController<typeof controllerName, RampsControllerState, RampsControllerMessenger> {
92
+ #private;
62
93
  /**
63
94
  * Constructs a new {@link RampsController}.
64
95
  *
@@ -66,17 +97,91 @@ export declare class RampsController extends BaseController<typeof controllerNam
66
97
  * @param args.messenger - The messenger suited for this controller.
67
98
  * @param args.state - The desired state with which to initialize this
68
99
  * controller. Missing properties will be filled in with defaults.
100
+ * @param args.requestCacheTTL - Time to live for cached requests in milliseconds.
101
+ * @param args.requestCacheMaxSize - Maximum number of entries in the request cache.
69
102
  */
70
- constructor({ messenger, state, }: {
71
- messenger: RampsControllerMessenger;
72
- state?: Partial<RampsControllerState>;
73
- });
103
+ constructor({ messenger, state, requestCacheTTL, requestCacheMaxSize, }: RampsControllerOptions);
74
104
  /**
75
- * Updates the user's geolocation.
76
- * This method calls the RampsService to get the geolocation
77
- * and stores the result in state.
105
+ * Executes a request with caching and deduplication.
106
+ *
107
+ * If a request with the same cache key is already in flight, returns the
108
+ * existing promise. If valid cached data exists, returns it without making
109
+ * a new request.
110
+ *
111
+ * @param cacheKey - Unique identifier for this request.
112
+ * @param fetcher - Function that performs the actual fetch. Receives an AbortSignal.
113
+ * @param options - Options for cache behavior.
114
+ * @returns The result of the request.
115
+ */
116
+ executeRequest<TResult>(cacheKey: string, fetcher: (signal: AbortSignal) => Promise<TResult>, options?: ExecuteRequestOptions): Promise<TResult>;
117
+ /**
118
+ * Aborts a pending request if one exists.
119
+ *
120
+ * @param cacheKey - The cache key of the request to abort.
121
+ * @returns True if a request was aborted.
122
+ */
123
+ abortRequest(cacheKey: string): boolean;
124
+ /**
125
+ * Gets the state of a specific cached request.
126
+ *
127
+ * @param cacheKey - The cache key to look up.
128
+ * @returns The request state, or undefined if not cached.
129
+ */
130
+ getRequestState(cacheKey: string): RequestState | undefined;
131
+ /**
132
+ * Updates the user's region by fetching geolocation and eligibility.
133
+ * This method calls the RampsService to get the geolocation,
134
+ * then automatically fetches eligibility for that region.
135
+ *
136
+ * @param options - Options for cache behavior.
137
+ * @returns The user region string.
138
+ */
139
+ updateUserRegion(options?: ExecuteRequestOptions): Promise<string>;
140
+ /**
141
+ * Sets the user's region manually (without fetching geolocation).
142
+ * This allows users to override the detected region.
143
+ *
144
+ * @param region - The region code to set (e.g., "US-CA").
145
+ * @param options - Options for cache behavior when fetching eligibility.
146
+ * @returns The eligibility information for the region.
147
+ */
148
+ setUserRegion(region: string, options?: ExecuteRequestOptions): Promise<Eligibility>;
149
+ /**
150
+ * Initializes the controller by fetching the user's region from geolocation.
151
+ * This should be called once at app startup to set up the initial region.
152
+ * After the region is set and eligibility is determined, tokens are fetched
153
+ * and saved to state.
154
+ *
155
+ * @param options - Options for cache behavior.
156
+ * @returns Promise that resolves when initialization is complete.
157
+ */
158
+ init(options?: ExecuteRequestOptions): Promise<void>;
159
+ /**
160
+ * Updates the eligibility information for a given region.
161
+ *
162
+ * @param isoCode - The ISO code for the region (e.g., "us", "fr", "us-ny").
163
+ * @param options - Options for cache behavior.
164
+ * @returns The eligibility information.
165
+ */
166
+ updateEligibility(isoCode: string, options?: ExecuteRequestOptions): Promise<Eligibility>;
167
+ /**
168
+ * Fetches the list of supported countries for a given ramp action.
169
+ *
170
+ * @param action - The ramp action type ('buy' or 'sell').
171
+ * @param options - Options for cache behavior.
172
+ * @returns An array of countries with their eligibility information.
173
+ */
174
+ getCountries(action?: 'buy' | 'sell', options?: ExecuteRequestOptions): Promise<Country[]>;
175
+ /**
176
+ * Fetches the list of available tokens for a given region and action.
177
+ * The tokens are saved in the controller state once fetched.
178
+ *
179
+ * @param region - The region code (e.g., "us", "fr", "us-ny"). If not provided, uses the user's region from controller state.
180
+ * @param action - The ramp action type ('buy' or 'sell').
181
+ * @param options - Options for cache behavior.
182
+ * @returns The tokens response containing topTokens and allTokens.
78
183
  */
79
- updateGeolocation(): Promise<void>;
184
+ getTokens(region?: string, action?: 'buy' | 'sell', options?: ExecuteRequestOptions): Promise<TokensResponse>;
80
185
  }
81
186
  export {};
82
187
  //# sourceMappingURL=RampsController.d.mts.map
@@ -1 +1 @@
1
- {"version":3,"file":"RampsController.d.mts","sourceRoot":"","sources":["../src/RampsController.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EACxB,0BAA0B,EAE3B,kCAAkC;AACnC,OAAO,EAAE,cAAc,EAAE,kCAAkC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,4BAA4B;AAErD,OAAO,KAAK,EAAE,gCAAgC,EAAE,+CAA2C;AAI3F;;;;GAIG;AACH,eAAO,MAAM,cAAc,oBAAoB,CAAC;AAIhD;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC;;OAEG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,CAAC;AAcF;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,IAAI,oBAAoB,CAIrE;AAID;;GAEG;AACH,MAAM,MAAM,6BAA6B,GAAG,wBAAwB,CAClE,OAAO,cAAc,EACrB,oBAAoB,CACrB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,6BAA6B,CAAC;AAEnE;;GAEG;AACH,KAAK,cAAc,GAAG,gCAAgC,CAAC;AAEvD;;GAEG;AACH,MAAM,MAAM,+BAA+B,GAAG,0BAA0B,CACtE,OAAO,cAAc,EACrB,oBAAoB,CACrB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,+BAA+B,CAAC;AAEpE;;GAEG;AACH,KAAK,aAAa,GAAG,KAAK,CAAC;AAE3B;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG,SAAS,CAC9C,OAAO,cAAc,EACrB,sBAAsB,GAAG,cAAc,EACvC,qBAAqB,GAAG,aAAa,CACtC,CAAC;AAIF;;GAEG;AACH,qBAAa,eAAgB,SAAQ,cAAc,CACjD,OAAO,cAAc,EACrB,oBAAoB,EACpB,wBAAwB,CACzB;IACC;;;;;;;OAOG;gBACS,EACV,SAAS,EACT,KAAU,GACX,EAAE;QACD,SAAS,EAAE,wBAAwB,CAAC;QACpC,KAAK,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;KACvC;IAYD;;;;OAIG;IACG,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;CASzC"}
1
+ {"version":3,"file":"RampsController.d.mts","sourceRoot":"","sources":["../src/RampsController.ts"],"names":[],"mappings":"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"}