Treat transient network errors as AbortError instead of BugError

[amcaplan]

Summary

Addresses shop/issues-liquid-storefronts#10783

Fixes 6,941+ production errors that were incorrectly classified as BugError when they should be user-facing AbortError.

The main issue was TLS certificate validation failures (e.g., "Hostname/IP does not match certificate's altnames") being treated as bugs rather than network connectivity issues.

Changes

1. Renamed isARetryableNetworkError → isTransientNetworkError

• Old name was confusing in contexts where retries had already been exhausted
• New name accurately describes what these errors are: transient network issues
• Added comprehensive JSDoc explaining the purpose

2. Exported function for reuse

• Made function available to other modules (previously private)
• Keeps error detection logic DRY

3. Enhanced network error detection

Added patterns for production errors that were being missed:

• 'timeout' - Generic network timeouts
• 'premature close' - Connection closed prematurely
• 'certificate', 'cert', 'tls', 'ssl', 'altnames' - TLS/certificate errors
• 'getaddrinfo' - DNS resolution failures

4. Updated fetchApiVersions error handling

Now checks for transient network errors and classifies them as AbortError with a user-friendly message instead of BugError.

Production Impact

Errors now properly classified as network issues (from Observe data):

• ✅ TLS certificate validation failures (6,941 occurrences - the main issue)
• ✅ ECONNRESET (connection resets)
• ✅ ENOTFOUND (DNS failures)
• ✅ ETIMEDOUT (timeouts)
• ✅ Socket hang ups
• ✅ Premature connection closes
• ✅ TLS handshake failures

Test Plan

• All existing tests pass
• TypeScript compilation succeeds
• Verified all 8 production error patterns are now correctly detected

🤖 Generated with Claude Code

[github-actions]

Coverage report

St.❔	Category	Percentage	Covered / Total
🟡	Statements	79.11% (+0.01% 🔼)	13517/17087
🟡	Branches	72.89% (+0.01% 🔼)	6594/9047
🟡	Functions	79.23% (+0.01% 🔼)	3480/4392
🟡	Lines	79.46% (+0.01% 🔼)	12768/16068

Show files with reduced coverage 🔻

St.❔	File	Statements	Branches	Functions	Lines
🟡	... / admin.ts	72.22% (-2.78% 🔻)	40% (-5.16% 🔻)	90.91%	73.58% (-2.89% 🔻)

Test suite run success

3330 tests passing in 1361 suites.

Report generated by 🧪jest coverage report action from 771d001

[EvilGenius13]

Thanks for the PR @amcaplan!

I like the new error wording explicitly stating it's a network error.

I do want to point out that some of the changes will catch more errors than just transient. For instance, certificate errors can be permanent as well and we will retry for no reason if we only look for the word itself. However, the trade-off might be worth it if we are helping the majority of users having blips in their network.

[amcaplan]

@EvilGenius13 There's definitely a conversation to be had here. Maybe there's a wider category of network errors, and a narrower category of retryable network errors. Cert errors are unlikely to just recover, unless caused by a momentary blip in system clock accuracy. But some others in the list are worth retrying. And I think in all cases, it's correct to treat these as Handled errors since there isn't much we can do.

By the way, I suspect many of these are caused by users who set up SSL certs incorrectly for custom domains.

[plvaldes]

Are these files covered by unit tests that we may want to extend with new checks?

[amcaplan]

I've updated the PR with a lengthy series of tests, as well as distinguishing between transient network errors (should be retried) vs network errors generally (which might not fix themselves but aren't a CLI bug - so should be AbortError not BugError).

[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

We found no new type declarations in this PR

Existing type declarations

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

@@ -11,6 +11,30 @@ type RequestOptions<T> = {
     request: () => Promise<T>;
     url: string;
 } & NetworkRetryBehaviour;
+/**
+ * Checks if an error is a transient network error that is likely to recover with retries.
+ *
+ * Use this function for retry logic. Use isNetworkError for error classification.
+ *
+ * Examples of transient errors (worth retrying):
+ * - Connection timeouts, resets, and aborts
+ * - DNS failures (enotfound, getaddrinfo, eai_again) - can be temporary
+ * - Socket disconnects and hang ups
+ * - Premature connection closes
+ */
+export declare function isTransientNetworkError(error: unknown): boolean;
+/**
+ * Checks if an error is any kind of network-related error (connection issues, timeouts, DNS failures,
+ * TLS/certificate errors, etc.) rather than an application logic error.
+ *
+ * These errors should be reported as user-facing errors (AbortError) rather than bugs (BugError),
+ * regardless of whether they are transient or permanent.
+ *
+ * Examples include:
+ * - Transient: connection timeouts, socket hang ups, temporary DNS failures
+ * - Permanent: certificate validation failures, misconfigured SSL
+ */
+export declare function isNetworkError(error: unknown): boolean;
 export declare function simpleRequestWithDebugLog<T extends {
     headers: Headers;
     status: number;

[EvilGenius13]

Awesome, thanks @amcaplan! 🚀