Add helper to fetch SDK artifacts directly from Github

[pschutz93]

This PR adds a helper to allow fetching SDK artifacts directly from Github. This helper works inline with other codeSample SDK configs. It takes the standard SDK config with additional parameters to specify repo and version tag and an optional Github token. While I can definitely see use cases where you want a unique token per SDK, this helper also allows defaulting to a token set as the environment variable $GITHUB_TOKEN to avoid getting too verbose when that level of configuration isn't needed.

.It returns a promise to a code sample instance with sdkTarballPath set to a tarball of the SDK repo downloaded directly from Github. I updated the types so this helper can only be used with codeSample types that require an SDK artifact (which right now just means not curl).

To gracefully handle promises to config values and the underlying values themselves, I am using zod's preprocess() function to allow awaiting resolution of the config value before parsing the config with safeParseAsync(). I went with this approach because when reading the docs, I noticed z.promise() is deprecated in the new v4, and I think unwrapping the value before parsing is cleaner anyway and perfectly well supported by preprocess() since it supports async pre-processing functions.

This PR uses octokit.js to download a Tarball archive for the specified SDK repo using the Personal Access Token for auth.

export default {
  spec: "../specs/glean.yaml",
  output: {
    pageOutDir: "./docs/glean/api",
    embedOutDir: "./src/components/glean-embeds",
    framework: "docusaurus",
  },
  display: {
    maxNestingLevel: 2,
  },
  codeSamples: [
    withGithubSdk(
      {
        language: "typescript",
        owner: "gleanwork",
        repo: "api-client-typescript",
        version: "v0.11.2",
        tryItNow: {
          outDir: "./public/glean-try-it-now",
          urlPrefix: "/glean-try-it-now",
        },
      },
      process.env.GITHUB_TOKEN
    ),
    {
      language: "curl",
    },
  ],
};

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
docs-demo-custom-nextjs	Ready	Preview	Comment	Oct 28, 2025 10:35pm
docs-demo-docusaurus	Ready	Preview	Comment	Oct 28, 2025 10:35pm
docs-demo-nextra	Ready	Preview	Comment	Oct 28, 2025 10:35pm

[nebrius]

I know we originally specced out this helper to exist at this level, but now that I see it in practice I'm not sure I love it.

What if instead we did something like this?

export default {
  spec: "../specs/glean.yaml",
  output: {
    pageOutDir: "./docs/glean/api",
    embedOutDir: "./src/components/glean-embeds",
    framework: "docusaurus",
  },
  display: {
    maxNestingLevel: 2,
  },
  codeSamples: [
    withGitHubSdk({
      language: "typescript",
      owner: "gleanwork",
      repo: "api-client-typescript",
      version: "v0.11.2",
      tryItNow: {
        outDir: "./public/glean-try-it-now",
        urlPrefix: "/glean-try-it-now",
      },
    })
  ]
};

This way, we allow more flexibility by scoping the GitHub part just to the code sample in question. Who knows, maybe folks might want to use different providers for different languages...if nothing else GitHub definitely doesn't apply to cURL samples.

We could implement this by changing the signature of codeSamples in the main Settings type to be something like CodeSample | (config: unknown) => Promise<CodeSample> or something

[pschutz93]

Yeah, I like this. And accepting config values (like codeSamples in this case) as promises at the main Settings level adds a lot of flexibility for what customers can do too, which I like.

I'll make those updates and we can go from there!

[pschutz93]

This change is part of the following stack:

• Add helper to fetch SDK artifacts directly from Github #190 ◀
  • Add withGithubSpec() #192

_{Change managed by git-spice.}

[pschutz93]

@nebrius I revised the PR to inline the helper. In particular, I was curious about your thoughts on the pattern I am using to unwrap promise values from the config.

Could you take another pass when you get the chance?

And I'll update the withGithubSpec PR next (it's still just a draft)! Just wanted to get the overall helper pattern nailed down before updating it in the same manner.

[nebrius]

Looks good, just one last little thing

[nebrius]

Suggested change

	throw new InternalError(
	throw new Error(

I bet the most likely reason for this will be stuff like not being able to connect to the server, lookup DNS, etc., which could be due to internet issues on the user's end.

In this case, it's not a bug on our part, and so should be a normal error.