@superblocksteam/sdk-api 2.0.119 → 2.0.120-next.0

package/dist/integrations/graphql/client.test.js

@@ -0,0 +1,148 @@
+/**
+ * Tests for GraphQLClientImpl.
+ *
+ * Validates:
+ * - The proto request built by query()/mutation() matches the
+ *   graphql.v1.Plugin shape expected by the orchestrator.
+ * - Optional per-request headers are forwarded as the proto's repeated
+ *   `headers` field (key/value Property entries) so dynamic values like
+ *   Authorization tokens can be sent from API code.
+ * - Variables are serialized into the proto `custom.variables` Property.
+ * - Trace metadata is passed through to the executeQuery callback.
+ * - Response Zod validation throws RestApiValidationError on mismatch.
+ */
+import { describe, it, expect, vi } from "vitest";
+import { z } from "zod";
+import { RestApiValidationError } from "../../errors.js";
+import { GraphQLClientImpl } from "./client.js";
+const TEST_CONFIG = {
+    id: "graphql-test-id",
+    name: "Test GraphQL",
+    pluginId: "graphqlintegration",
+    configuration: {},
+};
+function createClient(mockResult) {
+    const executeQuery = vi.fn().mockResolvedValue(mockResult);
+    const client = new GraphQLClientImpl(TEST_CONFIG, executeQuery);
+    return { client, executeQuery };
+}
+const UserResponseSchema = z.object({
+    data: z.object({
+        user: z.object({
+            id: z.string(),
+            name: z.string(),
+        }),
+    }),
+});
+const SAMPLE_QUERY = `query GetUser($id: ID!) {
+  user(id: $id) { id name }
+}`;
+const SAMPLE_MUTATION = `mutation CreateUser($name: String!) {
+  createUser(name: $name) { id name }
+}`;
+describe("GraphQLClientImpl", () => {
+    describe("query()", () => {
+        it("returns validated data on a successful response", async () => {
+            const { client } = createClient({
+                data: { user: { id: "u1", name: "Alice" } },
+            });
+            const result = await client.query(SAMPLE_QUERY, { response: UserResponseSchema }, { id: "u1" });
+            expect(result.data.user).toEqual({ id: "u1", name: "Alice" });
+        });
+        it("builds the proto request with body, variables, and defaults", async () => {
+            const { client, executeQuery } = createClient({
+                data: { user: { id: "u1", name: "Alice" } },
+            });
+            await client.query(SAMPLE_QUERY, { response: UserResponseSchema }, { id: "u1" });
+            expect(executeQuery).toHaveBeenCalledOnce();
+            const request = executeQuery.mock.calls[0][0];
+            expect(request.body).toBe(SAMPLE_QUERY);
+            expect(request.verboseHttpOutput).toBe(false);
+            expect(request.failOnGraphqlErrors).toBe(true);
+            expect(request.custom).toEqual({
+                variables: {
+                    key: "variables",
+                    value: JSON.stringify({ id: "u1" }),
+                },
+            });
+            expect(request.headers).toBeUndefined();
+        });
+        it("omits custom when no variables are provided", async () => {
+            const { client, executeQuery } = createClient({
+                data: { user: { id: "u1", name: "Alice" } },
+            });
+            await client.query(SAMPLE_QUERY, { response: UserResponseSchema });
+            const request = executeQuery.mock.calls[0][0];
+            expect(request.custom).toBeUndefined();
+        });
+        it("forwards per-request headers into the proto headers field", async () => {
+            const { client, executeQuery } = createClient({
+                data: { user: { id: "u1", name: "Alice" } },
+            });
+            await client.query(SAMPLE_QUERY, { response: UserResponseSchema }, { id: "u1" }, undefined, {
+                Authorization: "Bearer abc123",
+                "X-Trace-Id": "trace-1",
+            });
+            const request = executeQuery.mock.calls[0][0];
+            expect(request.headers).toEqual([
+                { key: "Authorization", value: "Bearer abc123" },
+                { key: "X-Trace-Id", value: "trace-1" },
+            ]);
+        });
+        it("does not set headers when an empty headers object is passed", async () => {
+            const { client, executeQuery } = createClient({
+                data: { user: { id: "u1", name: "Alice" } },
+            });
+            await client.query(SAMPLE_QUERY, { response: UserResponseSchema }, undefined, undefined, {});
+            const request = executeQuery.mock.calls[0][0];
+            expect(request.headers).toBeUndefined();
+        });
+        it("passes trace metadata through to executeQuery", async () => {
+            const { client, executeQuery } = createClient({
+                data: { user: { id: "u1", name: "Alice" } },
+            });
+            await client.query(SAMPLE_QUERY, { response: UserResponseSchema }, undefined, { label: "graphql.getUser", description: "Fetch a user by id" });
+            expect(executeQuery).toHaveBeenCalledWith(expect.any(Object), undefined, {
+                label: "graphql.getUser",
+                description: "Fetch a user by id",
+            });
+        });
+        it("throws RestApiValidationError when the response fails schema validation", async () => {
+            const { client } = createClient({
+                data: { user: { id: "u1" /* missing name */ } },
+            });
+            await expect(client.query(SAMPLE_QUERY, { response: UserResponseSchema })).rejects.toThrow(RestApiValidationError);
+        });
+    });
+    describe("mutation()", () => {
+        it("returns validated data on a successful response", async () => {
+            const { client } = createClient({
+                data: { createUser: { id: "u2", name: "Bob" } },
+            });
+            const Schema = z.object({
+                data: z.object({
+                    createUser: z.object({ id: z.string(), name: z.string() }),
+                }),
+            });
+            const result = await client.mutation(SAMPLE_MUTATION, { response: Schema }, { name: "Bob" });
+            expect(result.data.createUser).toEqual({ id: "u2", name: "Bob" });
+        });
+        it("forwards per-request headers into the proto headers field", async () => {
+            const { client, executeQuery } = createClient({
+                data: { createUser: { id: "u2", name: "Bob" } },
+            });
+            const Schema = z.object({
+                data: z.object({
+                    createUser: z.object({ id: z.string(), name: z.string() }),
+                }),
+            });
+            await client.mutation(SAMPLE_MUTATION, { response: Schema }, { name: "Bob" }, undefined, { Authorization: "Bearer xyz" });
+            const request = executeQuery.mock.calls[0][0];
+            expect(request.body).toBe(SAMPLE_MUTATION);
+            expect(request.headers).toEqual([
+                { key: "Authorization", value: "Bearer xyz" },
+            ]);
+        });
+    });
+});
+//# sourceMappingURL=client.test.js.map

package/dist/integrations/graphql/client.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.test.js","sourceRoot":"","sources":["../../../src/integrations/graphql/client.test.ts"],"names":[],"mappings":"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"}

package/dist/integrations/graphql/types.d.ts

@@ -59,6 +59,17 @@ import type { TraceMetadata } from "../registry.js";
  *   { response: MutationResponseSchema },
  *   { name: 'John Doe' }
  * );
+ *
+ * // Send per-request headers (e.g. a dynamic Authorization token).
+ * // Static headers and auth configured on the integration apply automatically;
+ * // use this parameter only for values that vary per request.
+ * await graphql.query(
+ *   `query { me { id } }`,
+ *   { response: z.object({ data: z.object({ me: z.object({ id: z.string() }) }) }) },
+ *   undefined,
+ *   undefined,
+ *   { Authorization: `Bearer ${token}` },
+ * );
  * ```
  */
 export interface GraphQLClient extends BaseIntegrationClient {
@@ -71,6 +82,10 @@ export interface GraphQLClient extends BaseIntegrationClient {
      *   `metadata` accept plain objects, pass `undefined` for variables when you only need metadata:
      *   `query(q, schema, undefined, { label: "..." })`
      * @param metadata - Optional trace metadata for observability
+     * @param headers - Optional HTTP headers to include on this request. Static
+     *   headers and auth configured on the integration apply automatically; use
+     *   this parameter only for values that vary per request (e.g. a bearer token
+     *   derived from the API's input).
      * @returns Validated query result
      *
      * @example
@@ -89,7 +104,7 @@ export interface GraphQLClient extends BaseIntegrationClient {
      */
     query<TResponse>(query: string, schema: {
         response: z.ZodSchema<TResponse>;
-    }, variables?: Record<string, unknown>, metadata?: TraceMetadata): Promise<TResponse>;
+    }, variables?: Record<string, unknown>, metadata?: TraceMetadata, headers?: Record<string, string>): Promise<TResponse>;
     /**
      * Execute a GraphQL mutation.
      *
@@ -99,6 +114,10 @@ export interface GraphQLClient extends BaseIntegrationClient {
      *   `metadata` accept plain objects, pass `undefined` for variables when you only need metadata:
      *   `mutation(m, schema, undefined, { label: "..." })`
      * @param metadata - Optional trace metadata for observability
+     * @param headers - Optional HTTP headers to include on this request. Static
+     *   headers and auth configured on the integration apply automatically; use
+     *   this parameter only for values that vary per request (e.g. a bearer token
+     *   derived from the API's input).
      * @returns Validated mutation result
      *
      * @example
@@ -118,6 +137,6 @@ export interface GraphQLClient extends BaseIntegrationClient {
      */
     mutation<TResponse>(mutation: string, schema: {
         response: z.ZodSchema<TResponse>;
-    }, variables?: Record<string, unknown>, metadata?: TraceMetadata): Promise<TResponse>;
+    }, variables?: Record<string, unknown>, metadata?: TraceMetadata, headers?: Record<string, string>): Promise<TResponse>;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/integrations/graphql/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/integrations/graphql/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,MAAM,WAAW,aAAc,SAAQ,qBAAqB;IAC1D;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,KAAK,CAAC,SAAS,EACb,KAAK,EAAE,MAAM,EACb,MAAM,EAAE;QAAE,QAAQ,EAAE,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,CAAA;KAAE,EAC5C,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,QAAQ,CAAC,EAAE,aAAa,GACvB,OAAO,CAAC,SAAS,CAAC,CAAC;IAEtB;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,QAAQ,CAAC,SAAS,EAChB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE;QAAE,QAAQ,EAAE,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,CAAA;KAAE,EAC5C,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,QAAQ,CAAC,EAAE,aAAa,GACvB,OAAO,CAAC,SAAS,CAAC,CAAC;CACvB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/integrations/graphql/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,MAAM,WAAW,aAAc,SAAQ,qBAAqB;IAC1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,KAAK,CAAC,SAAS,EACb,KAAK,EAAE,MAAM,EACb,MAAM,EAAE;QAAE,QAAQ,EAAE,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,CAAA;KAAE,EAC5C,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,QAAQ,CAAC,EAAE,aAAa,EACxB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B,OAAO,CAAC,SAAS,CAAC,CAAC;IAEtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,QAAQ,CAAC,SAAS,EAChB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE;QAAE,QAAQ,EAAE,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,CAAA;KAAE,EAC5C,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,QAAQ,CAAC,EAAE,aAAa,EACxB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B,OAAO,CAAC,SAAS,CAAC,CAAC;CACvB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superblocksteam/sdk-api",
-  "version": "2.0.119",
+  "version": "2.0.120-next.0",
   "description": "Superblocks SDK for TypeScript-based API definitions",
   "license": "Superblocks Community Software License",
   "files": [
@@ -28,8 +28,8 @@
     "eslint": "^9.39.1",
     "eslint-config-prettier": "^10.1.8",
     "tsx": "^4.19.0",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.47.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.59.2",
     "uuid": "^9.0.0",
     "vitest": "^2.0.0"
   },

package/src/integrations/base/graphql-integration-client.ts

@@ -5,8 +5,11 @@
  * Handles proto message construction and response validation.
  */
 
+import type { PartialMessage } from "@bufbuild/protobuf";
 import { z } from "zod";
 
+import type { Property } from "@superblocksteam/types/dist/src/common/v1/plugin_pb";
+
 import { RestApiValidationError } from "../../errors.js";
 import type { QueryExecutor, TraceMetadata } from "../registry.js";
 import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
@@ -19,6 +22,8 @@ import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
  * - Executing queries and mutations through the orchestrator
  * - Required Zod schema validation on full GraphQL response
  * - Variables serialization for parameterized queries
+ * - Optional per-request HTTP headers (in addition to any headers configured
+ *   on the integration)
  */
 export abstract class GraphQLIntegrationClient implements IntegrationClientImpl {
   readonly name: string;
@@ -40,6 +45,7 @@ export abstract class GraphQLIntegrationClient implements IntegrationClientImpl
    * @param schema - Zod schema for full response validation (REQUIRED)
    * @param variables - Optional variables for the query
    * @param metadata - Optional trace metadata for observability
+   * @param headers - Optional HTTP headers to send with the request
    * @returns Validated query result
    */
   async query<TResponse>(
@@ -47,8 +53,9 @@ export abstract class GraphQLIntegrationClient implements IntegrationClientImpl
     schema: { response: z.ZodSchema<TResponse> },
     variables?: Record<string, unknown>,
     metadata?: TraceMetadata,
+    headers?: Record<string, string>,
   ): Promise<TResponse> {
-    return this.executeGraphQL(query, schema, variables, metadata);
+    return this.executeGraphQL(query, schema, variables, metadata, headers);
   }
 
   /**
@@ -58,6 +65,7 @@ export abstract class GraphQLIntegrationClient implements IntegrationClientImpl
    * @param schema - Zod schema for full response validation (REQUIRED)
    * @param variables - Optional variables for the mutation
    * @param metadata - Optional trace metadata for observability
+   * @param headers - Optional HTTP headers to send with the request
    * @returns Validated mutation result
    */
   async mutation<TResponse>(
@@ -65,8 +73,9 @@ export abstract class GraphQLIntegrationClient implements IntegrationClientImpl
     schema: { response: z.ZodSchema<TResponse> },
     variables?: Record<string, unknown>,
     metadata?: TraceMetadata,
+    headers?: Record<string, string>,
   ): Promise<TResponse> {
-    return this.executeGraphQL(mutation, schema, variables, metadata);
+    return this.executeGraphQL(mutation, schema, variables, metadata, headers);
   }
 
   /**
@@ -80,9 +89,17 @@ export abstract class GraphQLIntegrationClient implements IntegrationClientImpl
     schema: { response: z.ZodSchema<TResponse> },
     variables?: Record<string, unknown>,
     metadata?: TraceMetadata,
+    headers?: Record<string, string>,
   ): Promise<TResponse> {
+    const headerProps: PartialMessage<Property>[] = [];
+    if (headers) {
+      for (const [key, value] of Object.entries(headers)) {
+        headerProps.push({ key, value });
+      }
+    }
+
     // Build graphql.v1.Plugin proto message
-    const request = {
+    const request: Record<string, unknown> = {
       body: queryString,
       custom: variables
         ? {
@@ -96,6 +113,10 @@ export abstract class GraphQLIntegrationClient implements IntegrationClientImpl
       failOnGraphqlErrors: true,
     };
 
+    if (headerProps.length > 0) {
+      request.headers = headerProps;
+    }
+
     // Execute query through orchestrator
     const response = await this.executeQuery(request, undefined, metadata);
 

package/src/integrations/documentation-resolver.test.ts

@@ -659,7 +659,27 @@ describe("resolveIntegrationDocumentation", () => {
       }
     });
 
-    it("throws when overlay entry has empty versionRange", async () => {
+    it("throws when overlay entry has neither versionRange nor sdkVersionRange", async () => {
+      const integrationsDirectory = createPluginDocsFixture("dropbox", {
+        "README.md": "base",
+        "docs.manifest.json": JSON.stringify({
+          overlays: [{ file: "overlays/01.md" }],
+        }),
+      });
+
+      try {
+        await expect(
+          resolveIntegrationDocumentation("dropbox", {
+            pluginVersion: "0.4.0",
+            integrationsDirectory,
+          }),
+        ).rejects.toThrowError(/Invalid overlay entry/);
+      } finally {
+        rmSync(integrationsDirectory, { recursive: true, force: true });
+      }
+    });
+
+    it("throws when overlay entry has empty versionRange and no sdkVersionRange", async () => {
       const integrationsDirectory = createPluginDocsFixture("dropbox", {
         "README.md": "base",
         "docs.manifest.json": JSON.stringify({
@@ -680,6 +700,144 @@ describe("resolveIntegrationDocumentation", () => {
     });
   });
 
+  describe("sdkVersionRange", () => {
+    it("applies overlay when sdkVersion matches sdkVersionRange", async () => {
+      const integrationsDirectory = createPluginDocsFixture("graphql", {
+        "README.md": "base-graphql-docs",
+        "docs.manifest.json": JSON.stringify({
+          overlays: [
+            { file: "overlays/headers.md", sdkVersionRange: ">=0.0.2" },
+          ],
+        }),
+        "overlays/headers.md": "dynamic-headers-docs",
+      });
+
+      try {
+        const docs = await resolveIntegrationDocumentation("graphql", {
+          sdkVersion: "0.0.2",
+          integrationsDirectory,
+        });
+        expect(docs).toBe("base-graphql-docs\n\ndynamic-headers-docs");
+      } finally {
+        rmSync(integrationsDirectory, { recursive: true, force: true });
+      }
+    });
+
+    it("skips overlay when sdkVersion does not match sdkVersionRange", async () => {
+      const integrationsDirectory = createPluginDocsFixture("graphql", {
+        "README.md": "base-graphql-docs",
+        "docs.manifest.json": JSON.stringify({
+          overlays: [
+            { file: "overlays/headers.md", sdkVersionRange: ">=0.0.2" },
+          ],
+        }),
+        "overlays/headers.md": "dynamic-headers-docs",
+      });
+
+      try {
+        const docs = await resolveIntegrationDocumentation("graphql", {
+          sdkVersion: "0.0.1",
+          integrationsDirectory,
+        });
+        expect(docs).toBe("base-graphql-docs");
+      } finally {
+        rmSync(integrationsDirectory, { recursive: true, force: true });
+      }
+    });
+
+    it("skips overlay when sdkVersion is not provided", async () => {
+      const integrationsDirectory = createPluginDocsFixture("graphql", {
+        "README.md": "base-graphql-docs",
+        "docs.manifest.json": JSON.stringify({
+          overlays: [
+            { file: "overlays/headers.md", sdkVersionRange: ">=0.0.2" },
+          ],
+        }),
+        "overlays/headers.md": "dynamic-headers-docs",
+      });
+
+      try {
+        const docs = await resolveIntegrationDocumentation("graphql", {
+          pluginVersion: "0.0.10",
+          integrationsDirectory,
+        });
+        expect(docs).toBe("base-graphql-docs");
+      } finally {
+        rmSync(integrationsDirectory, { recursive: true, force: true });
+      }
+    });
+
+    it("requires both versionRange and sdkVersionRange to match when both are specified", async () => {
+      const integrationsDirectory = createPluginDocsFixture("graphql", {
+        "README.md": "base",
+        "docs.manifest.json": JSON.stringify({
+          overlays: [
+            {
+              file: "overlays/both.md",
+              versionRange: ">=0.0.10",
+              sdkVersionRange: ">=0.0.2",
+            },
+          ],
+        }),
+        "overlays/both.md": "both-match-overlay",
+      });
+
+      try {
+        // Both match
+        expect(
+          await resolveIntegrationDocumentation("graphql", {
+            pluginVersion: "0.0.10",
+            sdkVersion: "0.0.2",
+            integrationsDirectory,
+          }),
+        ).toBe("base\n\nboth-match-overlay");
+
+        // Only plugin matches
+        expect(
+          await resolveIntegrationDocumentation("graphql", {
+            pluginVersion: "0.0.10",
+            sdkVersion: "0.0.1",
+            integrationsDirectory,
+          }),
+        ).toBe("base");
+
+        // Only sdk matches
+        expect(
+          await resolveIntegrationDocumentation("graphql", {
+            pluginVersion: "0.0.9",
+            sdkVersion: "0.0.2",
+            integrationsDirectory,
+          }),
+        ).toBe("base");
+      } finally {
+        rmSync(integrationsDirectory, { recursive: true, force: true });
+      }
+    });
+
+    it("allows overlay with only sdkVersionRange (no versionRange)", async () => {
+      const integrationsDirectory = createPluginDocsFixture("graphql", {
+        "README.md": "base",
+        "docs.manifest.json": JSON.stringify({
+          overlays: [
+            { file: "overlays/sdk-only.md", sdkVersionRange: ">=0.0.2" },
+          ],
+        }),
+        "overlays/sdk-only.md": "sdk-gated-overlay",
+      });
+
+      try {
+        // No pluginVersion needed — only sdkVersion matters
+        const docs = await resolveIntegrationDocumentation("graphql", {
+          sdkVersion: "0.0.3",
+          integrationsDirectory,
+        });
+        expect(docs).toBe("base\n\nsdk-gated-overlay");
+      } finally {
+        rmSync(integrationsDirectory, { recursive: true, force: true });
+      }
+    });
+  });
+
   it("blocks overlay paths outside the plugin directory", async () => {
     const integrationsDirectory = createPluginDocsFixture("dropbox", {
       "README.md": "base",

package/src/integrations/documentation.ts

@@ -11,7 +11,13 @@ const DOC_DIRECTORY_ALIASES = {
 
 interface DocumentationOverlay {
   file: string;
-  versionRange: string;
+  versionRange?: string;
+  /** When set, checks against the sdk-api version ("javascriptsdkapi") running
+   *  in the orchestrator instead of the plugin-specific version. Use this to
+   *  gate overlays on sdk-api features that ship independently of plugin
+   *  version bumps. Both versionRange and sdkVersionRange can be specified
+   *  together — the overlay is applied only when all specified ranges match. */
+  sdkVersionRange?: string;
 }
 
 interface DocumentationManifest {
@@ -32,6 +38,7 @@ type OverlayOperation =
 
 export interface ResolveIntegrationDocumentationOptions {
   pluginVersion?: SemVer;
+  sdkVersion?: SemVer;
   integrationsDirectory?: string;
 }
 
@@ -82,16 +89,17 @@ async function parseDocumentationManifest(
         typeof overlay !== "object" ||
         overlay === null ||
         !("file" in overlay) ||
-        !("versionRange" in overlay)
+        (!("versionRange" in overlay) && !("sdkVersionRange" in overlay))
       ) {
         throw new Error(
           `Invalid overlay entry at index ${index} in ${manifestPath}.`,
         );
       }
 
-      const { file, versionRange } = overlay as {
+      const { file, versionRange, sdkVersionRange } = overlay as {
         file: unknown;
         versionRange: unknown;
+        sdkVersionRange: unknown;
       };
 
       if (typeof file !== "string" || file.trim().length === 0) {
@@ -99,18 +107,35 @@ async function parseDocumentationManifest(
           `Invalid "file" for overlay index ${index} in ${manifestPath}.`,
         );
       }
-      if (
-        typeof versionRange !== "string" ||
-        versionRange.trim().length === 0
-      ) {
+
+      const hasVersionRange =
+        typeof versionRange === "string" && versionRange.trim().length > 0;
+      const hasSdkVersionRange =
+        typeof sdkVersionRange === "string" &&
+        sdkVersionRange.trim().length > 0;
+
+      if ("versionRange" in overlay && !hasVersionRange) {
         throw new Error(
           `Invalid "versionRange" for overlay index ${index} in ${manifestPath}.`,
         );
       }
+      if ("sdkVersionRange" in overlay && !hasSdkVersionRange) {
+        throw new Error(
+          `Invalid "sdkVersionRange" for overlay index ${index} in ${manifestPath}.`,
+        );
+      }
+      if (!hasVersionRange && !hasSdkVersionRange) {
+        throw new Error(
+          `Overlay at index ${index} in ${manifestPath} must specify at least one of "versionRange" or "sdkVersionRange".`,
+        );
+      }
 
       return {
         file,
-        versionRange,
+        ...(hasVersionRange ? { versionRange: versionRange as string } : {}),
+        ...(hasSdkVersionRange
+          ? { sdkVersionRange: sdkVersionRange as string }
+          : {}),
       };
     },
   );
@@ -380,11 +405,38 @@ function ensureOverlayPathIsWithinPluginDir(
   }
 }
 
+function overlayMatchesVersions(
+  overlay: DocumentationOverlay,
+  pluginVersion: SemVer | undefined,
+  sdkVersion: SemVer | undefined,
+): boolean {
+  if (
+    overlay.versionRange &&
+    (!pluginVersion ||
+      !versionMatchesRange(pluginVersion, overlay.versionRange))
+  ) {
+    return false;
+  }
+
+  if (
+    overlay.sdkVersionRange &&
+    (!sdkVersion || !versionMatchesRange(sdkVersion, overlay.sdkVersionRange))
+  ) {
+    return false;
+  }
+
+  return true;
+}
+
 export async function resolveIntegrationDocumentation(
   pluginId: string,
   options: ResolveIntegrationDocumentationOptions = {},
 ): Promise<string> {
-  const { pluginVersion, integrationsDirectory = INTEGRATIONS_DIR } = options;
+  const {
+    pluginVersion,
+    sdkVersion,
+    integrationsDirectory = INTEGRATIONS_DIR,
+  } = options;
 
   const pluginDirectory = resolve(
     integrationsDirectory,
@@ -397,13 +449,13 @@ export async function resolveIntegrationDocumentation(
   const baseDocumentationPath = resolve(pluginDirectory, baseFileName);
   const baseDocumentation = await readFile(baseDocumentationPath, "utf8");
 
-  if (!manifest || !pluginVersion) {
+  if (!manifest) {
     return baseDocumentation;
   }
 
   let resolvedDocumentation = baseDocumentation;
   for (const overlay of manifest.overlays) {
-    if (!versionMatchesRange(pluginVersion, overlay.versionRange)) {
+    if (!overlayMatchesVersions(overlay, pluginVersion, sdkVersion)) {
       continue;
     }