feat(sdk): support typed documents in http adapters

Author: dqn

.changeset/typed-http-adapter-documents.md

@@ -0,0 +1,5 @@
+---
+"@tailor-platform/sdk": minor
+---
+
+Support `TypedDocumentNode` queries in HTTP adapters and infer `output` response data from them.

packages/sdk/docs/services/http-adapter.md

@@ -7,7 +7,7 @@ HTTP adapters expose REST-style HTTP endpoints on your application by translatin
 Each HTTP adapter is a single file that declares:
 
 - A `pathPattern` (which methods it handles is derived from the `input` keys)
-- An `input` object keyed by lowercase HTTP method (`get`, `post`, `put`, `patch`, `delete`) — each value is a function that converts an incoming HTTP request into a GraphQL request (`query`, `variables`, `operationName`)
+- An `input` object keyed by lowercase HTTP method (`get`, `post`, `put`, `patch`, `delete`) — each value is a function that converts an incoming HTTP request into a GraphQL request (`query`, `variables`, `operationName`). `query` can be a GraphQL string or a generated `TypedDocumentNode`.
 - An optional `output` function — **shared across all methods** — that converts the GraphQL response into an HTTP response (`statusCode`, `headers`, `body`)
 
 Adapters are deployed together with your application. When a request arrives under the `/api/` prefix and matches an adapter, the handler for the request method runs server-side.
@@ -74,6 +74,21 @@ A request to `GET /api/users/abc-123` invokes the `get` handler, runs the result
 
 If `output` is omitted, the raw GraphQL response is returned as JSON.
 
+### Typed GraphQL Documents
+
+`input` handlers can return generated `TypedDocumentNode` values instead of query strings. The SDK uses the document's variables type for `variables`, and passes the document's result type to `output` as `resp.data`.
+
+```typescript
+import { GetUserDocument } from "../generated/graphql";
+
+get: (req) => ({
+  query: GetUserDocument,
+  variables: { id: req.path.split("/")[2] ?? "" },
+});
+```
+
+When multiple methods return different typed documents, `resp.data` is the union of those result types because `output` is shared across the adapter. If a method returns a plain string query, its result type is `unknown`. When extracting an input handler and annotating it separately, pass the document type to `HttpAdapterInputFn` so required variables stay typed.
+
 ### Optional fields
 
 Beyond `name`, `pathPattern`, `input`, and `output`, two optional fields control deploy-time behavior:

packages/sdk/src/cli/services/http-adapter/bundler.test.ts

@@ -1,9 +1,13 @@
 import * as fs from "node:fs";
+import { createRequire } from "node:module";
 import * as os from "node:os";
 import * as path from "pathe";
 import { afterEach, describe, expect, test } from "vitest";
 import { bundleHttpAdapters } from "./bundler";
 
+const nodeRequire = createRequire(import.meta.url);
+const graphqlWebModule = nodeRequire.resolve("@0no-co/graphql.web");
+
 describe("bundleHttpAdapters", () => {
   let tmpDir: string | undefined;
 
@@ -27,13 +31,16 @@ describe("bundleHttpAdapters", () => {
       sourceFile,
       `
 import { createHttpAdapter } from "@tailor-platform/sdk";
+import { parse } from ${JSON.stringify(graphqlWebModule)};
+
+const getUserDocument = parse("query U($id: ID!) { user(id: $id) { id name } }");
 
 export default createHttpAdapter({
   name: "get-user",
   pathPattern: "/users/*",
   input: {
     get: (req) => ({
-      query: "query U($id: ID!) { user(id: $id) { id name } }",
+      query: getUserDocument,
       variables: { id: req.path.split("/")[2] },
     }),
   },
@@ -59,6 +66,18 @@ export default createHttpAdapter({
     // either double quotes or backticks for the case literal).
     expect(inputCode).toMatch(/case\s*[`"]GET[`"]/);
     expect(outputCode).toContain("globalThis.transform");
+
+    const runtime: {
+      transform?: (req: { method: string; path: string }) => {
+        query: string;
+        variables: { id: string | undefined };
+      };
+    } = {};
+    new Function("globalThis", inputCode!).call(runtime, runtime);
+    const request = runtime.transform!({ method: "GET", path: "/users/user-1" });
+    expect(request.query).toContain("query U");
+    expect(request.query).toContain("user(id: $id)");
+    expect(request.variables.id).toBe("user-1");
   });
 
   test("dispatches to the matching method handler at runtime", async () => {

packages/sdk/src/cli/services/http-adapter/bundler.ts

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import { createRequire } from "node:module";
 import { parseSync } from "oxc-parser";
 import * as path from "pathe";
 import { resolveTSConfig } from "pkg-types";
@@ -15,6 +16,8 @@ import type { LogLevel } from "#/configure/config/types";
 
 const ADAPTER_BUNDLE_WARN_BYTES = 64 * 1024;
 const ADAPTER_BUNDLE_ERROR_BYTES = 256 * 1024;
+const nodeRequire = createRequire(import.meta.url);
+const GRAPHQL_WEB_MODULE = nodeRequire.resolve("@0no-co/graphql.web");
 
 export interface HttpAdapterBundleInput {
   name: string;
@@ -101,7 +104,7 @@ async function bundleAdapterScript(
     tsconfig,
     inlineSourcemap: false,
     bundleLogLevel,
-    prefix: kind,
+    prefix: `${kind}:document-query-normalize-v1`,
   });
 
   const code = await withCache({
@@ -114,12 +117,6 @@ async function bundleAdapterScript(
       const entryPath = path.join(outputDir, `${adapter.name}.${kind}.entry.js`);
       const absoluteSourcePath = path.resolve(adapter.sourceFile);
 
-      const entryContent =
-        kind === "input"
-          ? buildInputEntry(absoluteSourcePath, adapter.methods)
-          : buildOutputEntry(absoluteSourcePath);
-      fs.writeFileSync(entryPath, entryContent);
-
       const rejectNodeImports: rolldown.Plugin = {
         name: "http-adapter-reject-node-imports",
         resolveId(source) {
@@ -154,6 +151,11 @@ async function bundleAdapterScript(
 
       let bundled: string;
       try {
+        const entryContent =
+          kind === "input"
+            ? buildInputEntry(absoluteSourcePath, adapter.methods, GRAPHQL_WEB_MODULE)
+            : buildOutputEntry(absoluteSourcePath);
+        fs.writeFileSync(entryPath, entryContent);
         const result = await rolldown.build({
           input: entryPath,
           write: false,
@@ -206,12 +208,28 @@ async function bundleAdapterScript(
   return [adapter.name, kind, code];
 }
 
-function buildInputEntry(absoluteSourcePath: string, methods: HttpMethodKey[]): string {
+function buildInputEntry(
+  absoluteSourcePath: string,
+  methods: HttpMethodKey[],
+  graphqlPrinterModule: string,
+): string {
   const cases = methods
-    .map((method) => `    case "${HTTP_METHODS[method]}": return __adapter.input.${method}(req);`)
+    .map((method) => {
+      const result = `__adapter.input.${method}(req)`;
+      const expression = `__normalizeHttpAdapterGraphQLRequest(${result})`;
+      return `    case "${HTTP_METHODS[method]}": return ${expression};`;
+    })
     .join("\n");
   const supported = methods.map((m) => HTTP_METHODS[m]).join(", ");
-  return `import __adapter from ${JSON.stringify(absoluteSourcePath)};
+  const documentNormalizer = `import { print as __printHttpAdapterDocument } from ${JSON.stringify(graphqlPrinterModule)};
+function __normalizeHttpAdapterGraphQLRequest(result) {
+  if (typeof result.query === "string") {
+    return result;
+  }
+  return { ...result, query: __printHttpAdapterDocument(result.query) };
+}
+`;
+  return `${documentNormalizer}import __adapter from ${JSON.stringify(absoluteSourcePath)};
 globalThis.transform = function(req) {
   switch (req.method) {
 ${cases}

packages/sdk/src/configure/services/http-adapter/http-adapter.test.ts

@@ -1,6 +1,11 @@
-import { describe, expect, test } from "vitest";
+import { describe, expect, expectTypeOf, test } from "vitest";
 import { SDK_BRAND, isSdkBranded } from "#/utils/brand";
-import { createHttpAdapter } from "./http-adapter";
+import {
+  createHttpAdapter,
+  type HttpAdapterInputFn,
+  type HttpAdapterTypedDocumentNode,
+} from "./http-adapter";
+import type { TypedQueryDocumentNode } from "graphql";
 
 describe("createHttpAdapter", () => {
   test("returns a branded HTTP adapter object", () => {
@@ -60,4 +65,75 @@ describe("createHttpAdapter", () => {
     expect(typeof adapter.input.post).toBe("function");
     expect(typeof adapter.input.delete).toBe("function");
   });
+
+  test("infers output data and variables from typed document nodes", () => {
+    type GetUserData = { user: { id: string; name: string } | null };
+    type GetUserVariables = { id: string };
+    const getUserDocument = {} as HttpAdapterTypedDocumentNode<GetUserData, GetUserVariables>;
+    const get: HttpAdapterInputFn<typeof getUserDocument> = (req) => ({
+      query: getUserDocument,
+      variables: { id: req.path.split("/")[2] ?? "" },
+    });
+
+    createHttpAdapter({
+      name: "typed-user",
+      pathPattern: "/users/*",
+      input: {
+        get,
+      },
+      output: (resp) => {
+        expectTypeOf(resp.data).toEqualTypeOf<GetUserData | null | undefined>();
+        expectTypeOf(resp.data?.user?.name).toEqualTypeOf<string | undefined>();
+        return { body: JSON.stringify(resp.data?.user ?? null) };
+      },
+    });
+
+    createHttpAdapter({
+      name: "typed-missing-variables",
+      pathPattern: "/users/*",
+      input: {
+        // @ts-expect-error - typed document variables require variables.id
+        get: () => ({
+          query: getUserDocument,
+        }),
+      },
+    });
+
+    createHttpAdapter({
+      name: "typed-wrong-variables",
+      pathPattern: "/users/*",
+      input: {
+        // @ts-expect-error - typed document variables require an id string
+        get: () => ({
+          query: getUserDocument,
+          variables: { slug: "alice" },
+        }),
+      },
+    });
+  });
+
+  test("unions output data from multiple typed document methods", () => {
+    type GetData = { getUser: { id: string } | null };
+    type PostData = { createUser: { id: string } };
+    const getDocument = {} as HttpAdapterTypedDocumentNode<GetData>;
+    const postDocument = {} as TypedQueryDocumentNode<PostData, { name: string }>;
+
+    createHttpAdapter({
+      name: "typed-union",
+      pathPattern: "/users/*",
+      input: {
+        get: () => ({
+          query: getDocument,
+        }),
+        post: () => ({
+          query: postDocument,
+          variables: { name: "Alice" },
+        }),
+      },
+      output: (resp) => {
+        expectTypeOf(resp.data).toEqualTypeOf<GetData | PostData | null | undefined>();
+        return { body: JSON.stringify(resp.data ?? null) };
+      },
+    });
+  });
 });