Add option to provide a custom predicate to decide whether to retry

[mbg]

This is a first attempt at adding a new option shouldRetry to RetryOptions, which accepts a function of type (state: RetryState, error: RequestError | Error) => boolean. Setting this overrides the default logic for determining whether a request should be retried based on the outcome of the last attempt. By default, this is set to the existing implementation of:

export function defaultShouldRetry(
  state: RetryState,
  error: RequestError | Error,
): boolean {
  if (!isRequestError(error) || !error?.request.request) {
    // address https://github.com/octokit/plugin-retry.js/issues/8
    throw error;
  }

  return error.status >= 400 && !state.doNotRetry.includes(error.status);
}

By setting shouldRetry to something else, requests can be retried based on criteria other than the status code. For example, to make the decision based on the error message:

const octokit = new MyOctokit({
  auth: "secret123",
  retry: {
    shouldRetry: (retryState: RetryState, error: any) => {
      if (isRequestError(error)) {
        return error.message.includes("Intermittent problem");
      }
      return false;
    },
  },
});

This will probably need some polish (particularly around typing extensions to RequestRequestOptions), but should be good for a first round of review. Best reviewed commit-by-commit.

A few notes:

• e1fcc27 adds the new option and starts using it, but restricted to just RequestError errors.
• dc1a8bd then lifts that restriction by changing retryRequest to transform the options rather than the error. A new RequestError is then constructed based on that. For non-RequestError errors, we don't have a status code, so I use 500 instead similar to what happens in requestWithGraphqlErrorHandling.
• I played around with introducing a new error type for "retry requests" that doesn't have this requirement, but it added a bunch more complexity, so I left it like this for now.

---

Before the change?

• Requests will only be retried based on >= 400 status codes.

After the change?

• No change if shouldRetry is not customised.
• If shouldRetry is customised, then requests can be retried on custom criteria.

Pull request checklist

• Tests for the changes have been added (for bug fixes / features)
• Docs have been reviewed and added / updated if needed (for bug fixes / features)

Does this introduce a breaking change?

Please see our docs on breaking changes to help!

• Yes
• No

There should be no breaking change since shouldRetry is optional in RetryOptions and uses the previous implementation by default.

---

[github-actions]

👋 Hi! Thank you for this contribution! Just to let you know, our GitHub SDK team does a round of issue and PR reviews twice a week, every Monday and Friday! We have a process in place for prioritizing and responding to your input. Because you are a part of this community please feel free to comment, add to, or pick up any issues/PRs that are labeled with Status: Up for grabs. You & others like you are the reason all of this works! So thank you & happy coding! 🚀

[mbg]

@wolfy1339 any chance you can review this or any high-level thoughts on the direction / whether this is something you'd want to have in this library / this way?

[wolfy1339]

This is something that has been requested by the community in #499 and #299

At first glance it looks good.
I'll look deeper into it later