@superblocksteam/sdk-api 0.0.7 → 0.0.9

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,182 @@ 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 });
+      }
+    });
+  });
+
+  describe("restapiintegration responseType gating (real docs)", () => {
+    it("documents text responseType for agents whose sdk-api supports text only", async () => {
+      const docs = await resolveIntegrationDocumentation("restapiintegration", {
+        sdkVersion: "0.0.3",
+      });
+
+      expect(docs).toContain('responseType: "text"');
+      expect(docs).not.toContain('responseType: "binary"');
+      expect(docs).not.toContain("does not support the `responseType`");
+    });
+
+    it("documents binary responseType only for agents whose sdk-api supports it", async () => {
+      const docs = await resolveIntegrationDocumentation("restapiintegration", {
+        sdkVersion: "0.0.4",
+      });
+
+      expect(docs).toContain('responseType: "text"');
+      expect(docs).toContain('responseType: "binary"');
+      expect(docs).not.toContain("does not support the `responseType`");
+    });
+
+    it("notes non-support instead of documenting responseType on older agents", async () => {
+      const docs = await resolveIntegrationDocumentation("restapiintegration", {
+        sdkVersion: "0.0.2",
+      });
+
+      expect(docs).toContain("does not support the `responseType`");
+      expect(docs).not.toContain('responseType: "text"');
+      expect(docs).not.toContain('responseType: "binary"');
+    });
+
+    it("stays silent about responseType when the agent reports no sdk-api version", async () => {
+      const docs = await resolveIntegrationDocumentation("restapiintegration");
+
+      expect(docs).not.toContain("responseType");
+    });
+  });
+
   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;
     }
 

package/src/integrations/graphql/docs.manifest.json

@@ -1,5 +1,10 @@
 {
   "pluginId": "graphql",
   "base": "README.md",
-  "overlays": []
+  "overlays": [
+    {
+      "file": "overlays/dynamic-headers.md",
+      "sdkVersionRange": ">=0.0.2"
+    }
+  ]
 }

package/src/integrations/graphql/overlays/dynamic-headers.md

@@ -0,0 +1,34 @@
+## @replace: Methods
+
+| Method                                                           | Description                                                |
+| ---------------------------------------------------------------- | ---------------------------------------------------------- |
+| `query<T>(query, schema, variables?, metadata?, headers?)`       | Execute a GraphQL query with required schema validation    |
+| `mutation<T>(mutation, schema, variables?, metadata?, headers?)` | Execute a GraphQL mutation with required schema validation |
+
+## @replace: Trace Metadata
+
+All methods accept an optional `metadata` parameter for diagnostics labeling. See the [root SDK README](../../../README.md#trace-metadata) for details.
+
+## Dynamic Headers
+
+Static headers (e.g. a fixed `X-API-Version`) and auth headers (e.g. Bearer tokens, API keys) should be configured on the GraphQL integration in the Superblocks UI so they apply to every call automatically.
+
+For values that change per request — for example a bearer token derived from the API's input or from `ctx.env` — pass an optional `headers` map as the final argument to `query()` or `mutation()`:
+
+```typescript
+const MeResponseSchema = z.object({
+  data: z.object({
+    me: z.object({ id: z.string(), email: z.string() }),
+  }),
+});
+
+const result = await ctx.integrations.graphql.query(
+  `query { me { id email } }`,
+  { response: MeResponseSchema },
+  undefined, // no variables
+  undefined, // no trace metadata
+  { Authorization: `Bearer ${ctx.env.UPSTREAM_TOKEN}` },
+);
+```
+
+Since both `variables` and `metadata` accept plain objects, pass `undefined` for any of them that you do not need.

package/src/integrations/postgres/client.ts

@@ -20,7 +20,7 @@ import type { PostgresClient } from "./types.js";
  * PostgreSQL request type derived from proto definition.
  * Using PartialMessage allows optional fields.
  */
-export type PostgresRequest = PartialMessage<PostgresPlugin>;
+type PostgresRequest = PartialMessage<PostgresPlugin>;
 
 /**
  * Internal implementation of PostgresClient.