Improve intelisense and docs

[AllanOricil]

@panva

First of all, thank you for all the effort in this library. Your patience and passion for it are out of this word.

I'm having a really hard time using v6. None of the AIs seem to know about it. Their examples are all about v5. I spent quite some time figuring out how to use a client with a local keycloak instance running over HTTP. Thankfully I found an issue where there was an example. Another issue I had was while using jwks cache. I had to open the code and analyze it to understand why I was getting "can't read x from undefined". It was only after reading the code that I made it work. So could you invest time writing a page with more examples? I'm thinking about refactoring salesforce's most used oauth library to use openid-client. It would be really helpful.

Thank you again for all your work.

[panva]

Hello @AllanOricil, could you be specific?

I'm of the belief that

None of the AIs seem to know about it. Their examples are all about v5.

Is not a problem for me to care about or solve. It'll get solved over time by itself as LLMs get better and ingest the up to date typings, examples, and codebase.

So could you invest time writing a page with more examples?

Most of the commonly used paths are well documented with inline examples that the docs directory is also generated from. Can you be specific in what you think is missing?

[AllanOricil]

Hi @panva . Please, don't read the following as a critic to your amazing work. I'm just trying to describe the pain points I had while experimenting your library.

I had to spend quite some time reading the code and googling how to bypass the https protection during development. Thankfully someone who was also using local keycloak instance had the same issue and helped me with a discovery configuration to bypass https during development

const idpUrl = new URL(process.env.IDP_URL);

    const config = await client.discovery(
      idpUrl,
      process.env.IDP_CLIENT_ID,
      process.env.IDP_CLIENT_SECRET,
      undefined,
      {
        execute:
          process.env.NODE_ENV === "development" ||
          process.env.MODE === "docker"
            ? [client.allowInsecureRequests]
            : undefined,
      },
    );

src: #737

Another issue I had, which I was only able to fix after reading the source code, was related to how the JKS cache methods are used. I had to find out how to use them after iterating through the lib using a debugger. I don't have the exact implementation to share with you right now because I'm not in my computer, but I remember I had to add another method to the discovery method because without it the jkws caching was failing.

const config = await client.discovery(
      idpUrl,
      process.env.IDP_CLIENT_ID,
      process.env.IDP_CLIENT_SECRET,
      undefined,
      {
        execute:
          process.env.NODE_ENV === "development" ||
          process.env.MODE === "docker"
            ? [client.allowInsecureRequests, client.SOME_OTHER_FUNCTION]
            : undefined,
      },
    );

And while I was doing this experiment, I remember I had quite some issues with intelisense not helping me. Once I'm back to the code I will share what I had to write, which I didn't find anywhere, and even LLMs couldn't figure it out. They were all biased towards an older version of your library.

[panva]

I don't believe there's anything actionable here.