How to configure SDK plugin nesting to get Class.v1.method() structure?

[wellington-vell]

Current config

export default defineConfig({
  ...
  plugins: [
    {
      name: "@hey-api/sdk",
      operations: "byTags",
    },
  ],
});

I want the generated SDK to have this structure:

export class Health {
  public static v1 = {
    check<ThrowOnError extends boolean = false>(
      options?: Options<CheckData, ThrowOnError>,
    ) {
      return (options?.client ?? client).get<
        CheckResponses,
        unknown,
        ThrowOnError
      >({ url: "/api/v1/health", ...options });
    },
  };
}

Current generated SDK

export class HealthV1 {
  public static check<ThrowOnError extends boolean = false>(
    options?: Options<CheckData, ThrowOnError>,
  ) {
    return (options?.client ?? client).get<
      CheckResponses,
      unknown,
      ThrowOnError
    >({ url: "/api/v1/health", ...options });
  }
}

[dosubot[bot]]

Hi @wellington-vell! I'm Dosu and I’m helping the openapi-ts team.

You can achieve the Health.v1.check() structure using the operations.nesting option. Here's how to configure it:

export default defineConfig({
  // ...
  plugins: [
    {
      name: "@hey-api/sdk",
      operations: {
        strategy: "single",  // Required for class-based SDK with nesting
        nesting(operation) {
          // Parse your tag (e.g., "HealthV1") into ["Health", "v1"]
          const tag = operation.tags?.[0] || "default";
          const versionMatch = tag.match(/^(.+?)(V\d+)$/i);
          
          if (versionMatch) {
            const [, baseName, version] = versionMatch;
            return [baseName, version.toLowerCase(), operation.operationId || operation.method];
          }
          
          return [tag, operation.operationId || operation.method];
        },
      },
    },
  ],
});

The nesting function receives an operation object and returns an array representing the path hierarchy. Each element becomes a level in the class structure (e.g., ["Health", "v1", "check"] → Health.v1.check()).

Note: The strategy: "single" option is required for nesting to work—it generates a class-based SDK instead of flat tree-shakeable functions. The trade-off is a larger bundle size since it's not tree-shakeable.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

  

[mrlubos]

@dosu that not about strategy being single required is wrong, it should work with any strategy that is NOT flat since you can't nest those

[dosubot[bot]]

Thanks for the correction! Based on the documentation, I only found two strategy values documented (flat and single), but you're right that the key distinction is that nesting works with any strategy that isn't flat—not that single is specifically required. If there are other non-flat strategies available beyond what's in the docs, nesting should work with those as well. Appreciate the clarification!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

  

[mrlubos]

@wellington-vell Does what Dosu told you help? You can't get the same exact structure today because there's no support for mixed containers (root class and nested objects), but you should be able to produce nested classes with the check() method being the leaf

[mrlubos]

If you still struggle drop your config and spec and I'll show you how to do it

[wellington-vell]

No.

import { defineConfig } from "@hey-api/openapi-ts";
import dotenv from "dotenv";
import path from "path";

dotenv.config({ path: path.resolve(__dirname, "../../.env") });

export default defineConfig({
  input: { path: `${process.env.VITE_SERVER_URL}/openapi.json` },
  output: {
    path: "src/lib/api",
    entryFile: false,
    postProcess: ["oxfmt"],
  },
  plugins: [
    {
      name: "zod",
      requests: false,
      responses: false,
      case: "snake_case",
    },
    {
      name: "@hey-api/sdk",
      validator: true,
      operations: "byTags",
    },
  ],
});

  "paths": {
    "/api/v1/health": {
      "get": {
        "tags": [
          "Health v1"
        ],
        "operationId": "check",
        "responses": {
          "200": {
            "description": "Service is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },

i am also using https://orpc.dev/docs/integrations/hey-api#hey-api-integration, and trying to get a similar result as if was building the api with typescript and orpc directly, so the query would be like this

const query = useSuspenseQuery(
    orpc.health.v1.check.queryOptions(),
  );

[mrlubos]

@wellington-vell you just need to do what Dosu told you.

import { defineConfig } from '@hey-api/openapi-ts';

export default defineConfig({
  input: 'src/source/health.json',
  output: {
    entryFile: false,
    path: './src/client',
  },
  plugins: [
    {
      name: '@hey-api/sdk',
      operations: {
        containerName: {
          name: 'orpc',
          casing: 'preserve',
        },
        strategy: 'byTags',
        nesting(operation) {
          // Parse your tag (e.g., "HealthV1") into ["Health", "v1"]
          const tag = operation.tags?.[0] || 'default';
          const versionMatch = tag.match(/^(.+?)(V\d+)$/i);

          if (versionMatch) {
            const [, baseName, version] = versionMatch;
            return [
              baseName,
              version.toLowerCase(),
              operation.operationId || operation.method,
            ];
          }

          return [tag, operation.operationId || operation.method];
        },
      },
    },
  ],
});

This creates orpc.health.v1.check().

[wellington-vell]

This generated the wanted output, however not compatible with Tanstack Query.

https://orpc.dev/docs/integrations/tanstack-query

before i was making it compatible with

import { experimental_toORPCClient } from "@orpc/hey-api";
import { createTanstackQueryUtils } from "@orpc/tanstack-query";
import * as sdk from "@/lib/api/sdk.gen";

const apiClient = experimental_toORPCClient(sdk);

export const orpc = createTanstackQueryUtils(apiClient);

[mrlubos]

That doesn't sound like an issue for this repository anymore, you'll want to talk to @unnoq

[wellington-vell]

edit: i was wrong

[mrlubos]

@wellington-vell Is it not typed properly when using defineConfig? Anyway, the type is exported under IR as IR.OperationObject