feat: update sdk generate to accept build input instead of a spec file (#243)

What was Added?

- Uses the new SDK generation endpoint that accepts a build as input rather than a spec file.
- Updates the SDK Generate command to accept a build as parameter.
- Modifies the SDK Quickstart command's functionality to create the build in the src directory before generating the SDK.

---------

Co-authored-by: Ayesha <88117894+Ayeshas09@users.noreply.github.com>

Author: aliasghar98

README.md

@@ -24,7 +24,7 @@ $ npm install -g @apimatic/cli
 $ apimatic COMMAND
 running command...
 $ apimatic (--version)
-@apimatic/cli/1.1.0-beta.6 win32-x64 node-v23.4.0
+@apimatic/cli/1.1.0-beta.7 win32-x64 node-v23.4.0
 $ apimatic --help [COMMAND]
 USAGE
   $ apimatic COMMAND
@@ -411,16 +411,17 @@ Generate an SDK for your API
 
 ```
 USAGE
-  $ apimatic sdk generate -l csharp|java|php|python|ruby|typescript|go [--spec <value>] [-d <value>] [-f] [--zip]
-    [-k <value>]
+  $ apimatic sdk generate -l csharp|java|php|python|ruby|typescript|go [-i <value>] [-d <value>] [-f] [--zip] [-k
+    <value>]
 
 FLAGS
   -d, --destination=<value>  directory where the SDK will be generated
   -f, --force                overwrite changes without asking for user consent.
+  -i, --input=<value>        [default: ./] path to the parent directory containing the 'src' directory, which includes
+                             API specifications and configuration files.
   -k, --auth-key=<value>     override current authentication state with an authentication key.
   -l, --language=<option>    (required) programming language for SDK generation
                              <options: csharp|java|php|python|ruby|typescript|go>
-      --spec=<value>         [default: ./src/spec] path to the folder containing the API specification file
       --zip                  download the generated SDK as a .zip archive
 
 DESCRIPTION
@@ -432,7 +433,7 @@ DESCRIPTION
 EXAMPLES
   apimatic sdk generate --language=java
 
-  apimatic sdk generate --language=csharp --spec=./src/spec
+  apimatic sdk generate --language=csharp --input=./
 
   apimatic sdk generate --language=python --destination=./sdk --zip
 ```

package-lock.json

@@ -47,7 +47,7 @@
         "test": "tsx node_modules/mocha/bin/_mocha --forbid-only \"test/**/*.test.ts\" --timeout 99999"
     },
     "dependencies": {
-        "@apimatic/sdk": "^0.2.0-alpha.6",
+        "@apimatic/sdk": "^0.2.0-alpha.7",
         "@clack/prompts": "1.0.0-alpha.1",
         "@oclif/core": "^4.2.8",
         "@oclif/plugin-autocomplete": "^3.2.24",

package.json

@@ -3,11 +3,12 @@ import { DirectoryPath } from "../../types/file/directoryPath.js";
 import { ActionResult } from "../action-result.js";
 import { withDirPath } from "../../infrastructure/tmp-extensions.js";
 import { SdkContext } from "../../types/sdk-context.js";
-import { SpecContext } from "../../types/spec-context.js";
+import { VersionedBuildContext } from "../../types/versioned-build-context.js";
 import { SdkGeneratePrompts } from "../../prompts/sdk/generate.js";
 import { CommandMetadata } from "../../types/common/command-metadata.js";
 import { TempContext } from "../../types/temp-context.js";
 import { Language } from "../../types/sdk/generate.js";
+import { BuildContext } from "../../types/build-context.js";
 
 export class GenerateAction {
   private readonly prompts: SdkGeneratePrompts = new SdkGeneratePrompts();
@@ -23,20 +24,31 @@ export class GenerateAction {
   }
 
   public readonly execute = async (
-    specDirectory: DirectoryPath,
+    buildDirectory: DirectoryPath,
     sdkDirectory: DirectoryPath,
     language: Language,
     force: boolean,
     zipSdk: boolean
   ): Promise<ActionResult> => {
-    if (specDirectory.isEqual(sdkDirectory)) {
-      this.prompts.sameSpecAndSdkDir(specDirectory);
+    if (buildDirectory.isEqual(sdkDirectory)) {
+      this.prompts.sameBuildAndSdkDir(buildDirectory);
       return ActionResult.failed();
     }
 
-    const specContext = new SpecContext(specDirectory);
-    if (!(await specContext.validate())) {
-      this.prompts.invalidSpecDirectory(specDirectory);
+    const versionedBuildContext = new VersionedBuildContext(buildDirectory);
+    if (await versionedBuildContext.exists()) {
+      const resolvedDirectory = await versionedBuildContext.getResolvedBuildDirectory();
+      if (!resolvedDirectory) {
+        this.prompts.versionedBuildEmpty();
+        return ActionResult.failed();
+      }
+      buildDirectory = resolvedDirectory;
+      this.prompts.versionedBuild(versionedBuildContext.getRelativePath(resolvedDirectory));
+    }
+
+    const buildContext = new BuildContext(buildDirectory);
+    if (!(await buildContext.validate())) {
+      this.prompts.srcDirectoryEmpty(buildDirectory);
       return ActionResult.failed();
     }
 
@@ -48,15 +60,15 @@ export class GenerateAction {
 
     return await withDirPath(async (tempDirectory) => {
       const tempContext = new TempContext(tempDirectory);
-      const specZipPath = await tempContext.zip(specDirectory);
+      const buildZipPath = await tempContext.zip(buildDirectory);
 
       const response = await this.prompts.generateSDK(
-        this.portalService.generateSdk(specZipPath, language, this.configDir, this.commandMetadata, this.authKey)
+        this.portalService.generateSdk(buildZipPath, language, this.configDir, this.commandMetadata, this.authKey)
       );
 
       // TODO: this should be service error
       if (response.isErr()) {
-        this.prompts.logGenerationError(response.error);
+        this.prompts.sdkGenerationServiceError(response.error);
         return ActionResult.failed();
       }
 

src/actions/sdk/generate.ts

@@ -17,13 +17,9 @@ import { LauncherService } from '../../infrastructure/launcher-service.js';
 import { ZipService } from '../../infrastructure/zip-service.js';
 import { FileName } from '../../types/file/fileName.js';
 import { FeaturesToRemove, ValidationService } from '../../infrastructure/services/validation-service.js';
-
-const defaultSpecUrl = new UrlPath(
-  `https://raw.githubusercontent.com/apimatic/sample-docs-as-code-portal/refs/heads/master/src/spec/openapi.json`
-);
-const metadataFileUrl = new UrlPath(
-  `https://raw.githubusercontent.com/apimatic/sample-docs-as-code-portal/refs/heads/master/src/spec/APIMATIC-META.json`
-);
+import { BuildContext } from '../../types/build-context.js';
+import { TempContext } from '../../types/temp-context.js';
+import { getLanguagesConfig } from '../../types/build/build.js';
 
 export class SdkQuickstartAction {
   private readonly prompts = new SdkQuickstartPrompts();
@@ -32,6 +28,13 @@ export class SdkQuickstartAction {
   private readonly launcherService = new LauncherService();
   private readonly zipService = new ZipService();
   private readonly validationService = new ValidationService(this.configDir);
+  private readonly buildFileUrl = new UrlPath(
+    `https://github.com/apimatic/sample-docs-as-code-portal/archive/refs/heads/master.zip`
+  );
+  private readonly defaultSpecUrl = new UrlPath(
+    `https://raw.githubusercontent.com/apimatic/sample-docs-as-code-portal/refs/heads/master/src/spec/openapi.json`
+  );
+  private readonly repositoryFolderName = 'sample-docs-as-code-portal-master/src' as const;
 
   constructor(private readonly configDir: DirectoryPath, private readonly commandMetadata: CommandMetadata) {}
 
@@ -50,7 +53,7 @@ export class SdkQuickstartAction {
 
       let specPath: FilePath | undefined;
       while (!specPath) {
-        const inputPath = await this.prompts.specPathPrompt(defaultSpecUrl);
+        const inputPath = await this.prompts.specPathPrompt(this.defaultSpecUrl);
         if (!inputPath) {
           this.prompts.noSpecSpecified();
           return ActionResult.cancelled();
@@ -89,7 +92,7 @@ export class SdkQuickstartAction {
           return ActionResult.cancelled();
         }
         const downloadFileResult = await this.prompts.downloadSpecFile(
-          this.fileDownloadService.downloadFile(defaultSpecUrl)
+          this.fileDownloadService.downloadFile(this.defaultSpecUrl)
         );
         if (downloadFileResult.isErr()) {
           this.prompts.serviceError(downloadFileResult.error);
@@ -152,35 +155,39 @@ export class SdkQuickstartAction {
         break;
       }
 
-      // Setup source directory with the spec folder
-      const apimaticMetaFile = await this.prompts.downloadMetadataFile(
-        this.fileDownloadService.downloadFile(metadataFileUrl)
+      // Setup source directory with the build structure
+      const masterBuildFile = await this.prompts.downloadBuildDirectory(
+        this.fileDownloadService.downloadFile(this.buildFileUrl)
       );
-      if (apimaticMetaFile.isErr()) {
-        this.prompts.serviceError(apimaticMetaFile.error);
+      if (masterBuildFile.isErr()) {
+        this.prompts.serviceError(masterBuildFile.error);
         return ActionResult.failed();
       }
-      const tempSpecDirectory = tempDirectory.join('spec');
-      await this.fileService.createDirectoryIfNotExists(tempSpecDirectory);
-      const metadataFilePath = new FilePath(tempSpecDirectory, apimaticMetaFile.value.filename);
-      await this.fileService.writeFile(metadataFilePath, apimaticMetaFile.value.stream);
-
-      if (await this.fileService.isZipFile(specPath)) {
-        await this.zipService.unArchive(specPath, tempSpecDirectory);
-      } else {
-        await this.fileService.copyToDir(specPath, tempSpecDirectory);
-      }
+      const tempContext = new TempContext(tempDirectory);
+      const masterBuildFilePath = await tempContext.save(masterBuildFile.value.stream);
+      await this.zipService.unArchive(masterBuildFilePath, tempDirectory);
+      const extractedFolder = tempDirectory.join(this.repositoryFolderName);
+
+      const tempBuildContext = new BuildContext(extractedFolder);
+      await tempBuildContext.deleteWorkflowDir();
+
+      const buildFile = await tempBuildContext.getBuildFileContents();
+      buildFile.generatePortal!.languageConfig = getLanguagesConfig([language]);
+      await tempBuildContext.updateBuildFileContents(buildFile);
 
       const sourceDirectory = inputDirectory.join('src');
+      await this.fileService.copyDirectoryContents(extractedFolder, sourceDirectory);
+
       const specDirectory = sourceDirectory.join('spec');
-      await this.fileService.copyDirectoryContents(tempSpecDirectory, specDirectory);
+      const specContext = new SpecContext(specDirectory);
+      await specContext.replaceDefaultSpec(specPath);
 
-      const srcDirectoryStructure = await this.fileService.getDirectory(sourceDirectory);
-      this.prompts.printDirectoryStructure(inputDirectory, srcDirectoryStructure);
+      const buildDirectoryStructure = await this.fileService.getDirectory(sourceDirectory);
+      this.prompts.printDirectoryStructure(inputDirectory, buildDirectoryStructure);
 
       const sdkDirectory = inputDirectory.join('sdk');
       const sdkGenerateAction = new GenerateAction(this.configDir, this.commandMetadata);
-      const result = await sdkGenerateAction.execute(specDirectory, sdkDirectory, language as Language, true, false);
+      const result = await sdkGenerateAction.execute(sourceDirectory, sdkDirectory, language as Language, true, false);
       if (result.isFailed()) {
         return ActionResult.failed();
       }

src/actions/sdk/quickstart.ts

@@ -21,10 +21,7 @@ Supports multiple programming languages including Java, C#, Python, JavaScript,
       description: "Programming language for SDK generation",
       options: Object.values(Language).map((p) => p.valueOf()),
     }),
-    spec: Flags.string({
-      description: "Path to the folder containing the API specification file",
-      default: "./src/spec"
-    }),
+    ...FlagsProvider.input,
     destination: Flags.string({
       char: "d",
       description: "Directory where the SDK will be generated"
@@ -39,18 +36,19 @@ Supports multiple programming languages including Java, C#, Python, JavaScript,
 
   static examples = [
     `${SdkGenerate.cmdTxt} ${format.flag("language", "java")}`,
-    `${SdkGenerate.cmdTxt} ${format.flag("language", "csharp")} ${format.flag("spec", "./src/spec")}`,
+    `${SdkGenerate.cmdTxt} ${format.flag("language", "csharp")} ${format.flag("input", "./")}`,
     `${SdkGenerate.cmdTxt} ${format.flag("language", "python")} ${format.flag("destination", "./sdk")} ${format.flag(
       "zip"
     )}`
   ];
 
   async run() {
     const {
-      flags: { language, spec, destination, force, zip: zipSdk, "auth-key": authKey }
+      flags: { language, input, destination, force, zip: zipSdk, "auth-key": authKey }
     } = await this.parse(SdkGenerate);
 
-    const specDirectory = new DirectoryPath(spec);
+    const workingDirectory = DirectoryPath.createInput(input);
+    const buildDirectory = input ? new DirectoryPath(input, "src") : workingDirectory.join("src");
     const sdkDirectory = destination ? new DirectoryPath(destination) : DirectoryPath.default.join("sdk");
 
     const commandMetadata: CommandMetadata = {
@@ -60,7 +58,7 @@ Supports multiple programming languages including Java, C#, Python, JavaScript,
 
     intro("Generate SDK");
     const action = new GenerateAction(this.getConfigDir(), commandMetadata, authKey);
-    const result = await action.execute(specDirectory, sdkDirectory, language as Language, force, zipSdk);
+    const result = await action.execute(buildDirectory, sdkDirectory, language as Language, force, zipSdk);
     outro(result);
   }
 

src/commands/sdk/generate.ts

@@ -57,6 +57,17 @@ export class FileService {
     return new Directory(directoryPath, results);
   }
 
+  public async getSubDirectoriesPaths(dir: DirectoryPath): Promise<DirectoryPath[]> {
+  try {
+    const entries = await fsExtra.readdir(dir.toString(), { withFileTypes: true });
+    return entries
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => dir.join(entry.name));
+  } catch {
+    return [];
+  }
+}
+
   public async copyDirectoryContents(source: DirectoryPath, destination: DirectoryPath) {
     const entries = await fsExtra.readdir(source.toString());
     await Promise.all(

src/infrastructure/file-service.ts

@@ -5,7 +5,7 @@ import { SubscriptionInfo } from "../../types/api/account.js";
 import { envInfo } from "../env-info.js";
 import { err, ok, Result } from "neverthrow";
 import { handleServiceError, ServiceError } from "../service-error.js";
-import { PortalGenerationStatusResponse } from "@apimatic/sdk";
+import { PortalGenerationStatusResponse, SdkGenerationStatusResponse } from "@apimatic/sdk";
 
 export class ApiService {
   private readonly apiBaseUrl = "https://api.apimatic.io" as const;
@@ -66,6 +66,39 @@ export class ApiService {
     }
   }
 
+  public async getSdkGenerationStatus(
+    requestId: string,
+    configDir: DirectoryPath,
+    shell: string,
+    authKey: string | null
+  ): Promise<Result<SdkGenerationStatusResponse, ServiceError>> {
+    const authInfo: AuthInfo | null = await getAuthInfo(configDir.toString());
+    if (authInfo === null && !authKey) {
+      return err(ServiceError.UnAuthorized);
+    }
+
+    try {
+      const token = authKey || authInfo?.authKey;
+      const response = await this.axiosInstance(shell, token).get(`/sdk/${requestId}/status`, {
+        headers: { Accept: "application/json" },
+        maxRedirects: 0,
+        validateStatus: () => true
+      });
+
+      if (response.status === 200) {
+        return ok(response.data as SdkGenerationStatusResponse);
+      }
+
+      if (response.status === 302) {
+        return ok({ status: "Completed" } as SdkGenerationStatusResponse);
+      }
+
+      return err(ServiceError.InvalidResponse);
+    } catch (error: unknown) {
+      return err(handleServiceError(error));
+    }
+  }
+
   public async sendTelemetry(payload: string, authKey: string, shell: string): Promise<Result<string, string | ServiceError>> {
     try {
       const response = await this.axiosInstance(shell, authKey).post("/telemetry/track", payload, {