feat: add X-Glean headers for experimental features and deprecation testing

[travis-hoover-glean]

Summary

• Add XGlean beforeRequest hook that sets X-Glean-Exclude-Deprecated-After and X-Glean-Experimental headers
• Introduce new SDK options excludeDeprecatedAfter and includeExperimental with corresponding environment variable support
• Add documentation for testing experimental features and deprecation testing

Test plan

• Verify headers are set correctly when using SDK constructor options
• Verify headers are set correctly when using environment variables
• Confirm environment variables take precedence over SDK options
• Ensure no headers are set when neither option is configured

import { Glean } from "@gleanwork/api-client";

process.env["X_Glean_Exclude_Deprecated_After"] = "2027-10-15";
process.env["X_Glean_Include_Experimental"] = "true";

// Test with SDK options
const glean = new Glean({
  apiToken: process.env["GLEAN_API_TOKEN"] ?? "",
  instance: process.env["GLEAN_INSTANCE"] ?? "",
  excludeDeprecatedAfter: "2026-10-15",
  includeExperimental: true,
  debugLogger: console,
});

async function run() {
  const result = await glean.client.search.query({ query: "test" });
  console.log("Response received:", result);
}

run().catch(console.error);

[rwjblue-glean]

Overall looks good to me, only a few minor inline comments. I would like to see some tests for this though.

[rwjblue-glean]

1/5 (nit, non-blocking)

I think I'd expect all caps for environment variables like this, WDYT?

Suggested change

	// Set environment variables before initializing the SDK
	process.env.X_Glean_Exclude_Deprecated_After = '2026-10-15';
	process.env.X_Glean_Include_Experimental = 'true';
	// Set environment variables before initializing the SDK
	process.env.X_GLEAN_EXCLUDE_DEPRECATED_AFTER = '2026-10-15';
	process.env.X_GLEAN_INCLUDE_EXPERIMENTAL = 'true';

I know the header values are not case-sensitive, but the environment variables are.

I don't feel strongly here at all, so feel free to do whatever you think is best.

[travis-hoover-glean]

Lets do all caps, will update.

[rwjblue-glean]

3/5 (strong opinion: non-blocking)

Can you add a link to the developers.glean.com site for this (I think you've already written a guide that we can link to).

[travis-hoover-glean]

Yep!

[rwjblue-glean]

3/5 (strong opinion: non-blocking)

Same thing here, maybe a link to the website would be great.

[travis-hoover-glean]

Right now we dont have anything on the experimental stuff (not sure if we want to list out experiments or not) but if we do then I will add a link to that here

[rwjblue-glean]

2/5 (minor preference, non-blocking)

This is interesting. I do agree with you that the environment variable should override, but it feels a little bit weird for the constructor arg to be completely ignored without any sort of message, warning, or anything.

Also, is it possible in the current implementation to use the environment variable to disable or only enable? Like, if you pass true to the constructor, how do you unset it via environment variable?

I don't think we fundamentally have to do that, just something I thought about while reviewing.

[travis-hoover-glean]

Ya right now if you pass via the constructor there isn't a way to unset that programmatically. I think for now if you need to be setting/unsetting our suggestion is to use environment vars or just create 2 separate instances (one experimental and one regular one)