Throttle access to Management APIs

[shauns]

WHY are these changes introduced?

Fixes https://github.com/Shopify/develop-app-inner-loop/issues/1996

WHAT is this pull request doing?

• GraphQL requests now automatically retry on a 429-style response
• Refactored the REST-based throttle/retry logic from theme commands into the CLI-Kit proper
• Some light tweaks: in-source vitest tests are now supported and JSDoc requirement is loosened in public but not exported code

How to test your changes?

The most effective approach I've found is get a very big app and do a before/after comparison with these changes.

Post-release steps

n/a

Measuring impact

How do we know this change was effective? Please choose one:

• n/a - this doesn't need measurement, e.g. a linting rule or a bug-fix
• Existing analytics will cater for this addition
• PR includes analytics changes to measure impact

Checklist

• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've considered possible documentation changes

[github-actions]

Coverage report

St.❔	Category	Percentage	Covered / Total
🟡	Statements	72.74% (+0.21% 🔼)	7991/10985
🟡	Branches	69.28% (-0.04% 🔻)	3900/5629
🟡	Functions	71.39% (+0.05% 🔼)	2091/2929
🟡	Lines	73.08% (+0.22% 🔼)	7554/10337

Show new covered files 🐣

St.❔	File	Statements	Branches	Functions	Lines
🟢	... / rest-api-throttler.ts	89.25%	80%	83.33%	92.22%

Show files with reduced coverage 🔻

St.❔	File	Statements	Branches	Functions	Lines
🟢	... / common.ts	87.5%	44.44%	75% (-5% 🔻)	87.5%
🟢	... / common.ts	87.5% (-1.39% 🔻)	88.89%	100%	100%
🟡	... / dev.ts	74.42% (-1.67% 🔻)	56.25% (-8.75% 🔻)	76.47%	69.44% (-3.06% 🔻)
🟢	... / poll-app-logs.ts	87.3% (-6.45% 🔻)	78.13%	76.92%	87.3% (-6.45% 🔻)
🟢	... / usePollAppLogs.ts	93.18% (-0.15% 🔻)	95.24% (-0.41% 🔻)	80% (-1.82% 🔻)	93.02%
🟢	... / select-store.ts	86% (-0.27% 🔻)	81.82%	85.71%	87.23% (-0.27% 🔻)
🔴	... / developer-platform-client.ts	54.84% (-5.16% 🔻)	36.84% (-6.02% 🔻)	77.78% (-2.22% 🔻)	52% (-5.14% 🔻)
🔴	... / app-management-client.ts	17.54% (-2.02% 🔻)	11.11%	17.39% (-2.17% 🔻)	15.38% (-2.23% 🔻)
🔴	... / http.ts	48.15% (-3.85% 🔻)	10%	35.71% (-5.95% 🔻)	50% (-2% 🔻)
🟢	... / graphql.ts	84.62% (-7.05% 🔻)	50%	80% (-20% 🔻)	84.62% (-7.05% 🔻)
🟡	... / api.ts	78% (-0.43% 🔻)	79.17%	75%	78.26% (-0.46% 🔻)

Test suite run success

1803 tests passing in 824 suites.

Report generated by 🧪jest coverage report action from 40a7b12

[karreiro]

Thank you for this PR, @shauns! Excellent refactoring 🔥🚀 LGTM and works as expected on themes as well!

[craigmichaelmartin]

Looks great!

[github-actions]

Differences in type declarations

We detected differences in the type declarations generated by Typescript for this branch compared to the baseline ('main' branch). Please, review them to ensure they are backward-compatible. Here are some important things to keep in mind:

• Some seemingly private modules might be re-exported through public modules.
• If the branch is behind main you might see odd diffs, rebase main into this branch.

New type declarations

packages/cli-kit/dist/public/node/api/rest-api-throttler.d.ts

import { RestResponse } from './admin.js';
/**
 * Throttles a provided action, limiting the number of globally parallel requests, or by the last seen API limit
 * headers.
 *
 * @param request - A function performing a request.
 * @returns - The result of the request, once it eventually runs.
 */
export declare function throttle<T>(request: () => T): Promise<T>;
/**
 * Keep track of the latest API call limit data from a response.
 *
 * @param response - The response object.
 */
export declare function updateApiCallLimitFromResponse(response: RestResponse): void;
/**
 * Retries an operation after a delay specified in the response headers.
 *
 * @param response - The response object.
 * @param operation - The operation to retry.
 * @returns - The response of the operation.
 */
export declare function delayAwareRetry(response: RestResponse, operation: () => Promise<RestResponse>): Promise<RestResponse>;

Existing type declarations

packages/cli-kit/dist/private/node/api.d.ts

@@ -2,11 +2,19 @@ import { Headers } from 'form-data';
 export type API = 'admin' | 'storefront-renderer' | 'partners' | 'business-platform' | 'app-management';
 export declare const allAPIs: API[];
 interface RequestOptions<T> {
-    request: Promise<T>;
+    request: () => Promise<T>;
     url: string;
 }
-export declare function debugLogResponseInfo<T extends {
+export declare function simpleRequestWithDebugLog<T extends {
     headers: Headers;
     status: number;
 }>({ request, url }: RequestOptions<T>, errorHandler?: (error: unknown, requestId: string | undefined) => Error | unknown): Promise<T>;
+export declare function retryAwareRequest<T extends {
+    headers: Headers;
+    status: number;
+}>({ request, url }: RequestOptions<T>, errorHandler?: (error: unknown, requestId: string | undefined) => Error | unknown, retryOptions?: {
+    limitRetriesTo?: number;
+    defaultDelayMs?: number;
+    scheduleDelay: (fn: () => void, delay: number) => void;
+}): Promise<T>;
 export {};
\ No newline at end of file