feat: add sdk quickstart flow and other various improvements (#210)

- Added a new command `apimatic quickstart` to replace `apimatic portal quickstart`, which allows users to get started with either SDK or Portal.
- Fixed invalid `api transform` command examples.
- Improved portal generation to avoid timeout errors.
- Improved note wrapping to cater smaller terminal screens.
- Updated APIMatic API SDK dependency version to the latest.
- Streamlined CLI output messages for CI/CD workflows.

---------

Co-authored-by: Muhammad Sohail <62895181+sohail2721@users.noreply.github.com>
Co-authored-by: Mujahid Daud Khan <37825767+Shield-Jaguar@users.noreply.github.com>
Co-authored-by: Shield-Jaguar <mujahiddaudkhan@gmail.com>
Co-authored-by: saeedjamshaid <saeed.jamshaid@outlook.com>

Author: 4 people

README.md

@@ -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.4",
+        "@apimatic/sdk": "^0.2.0-alpha.5",
         "@clack/prompts": "1.0.0-alpha.1",
         "@oclif/core": "^4.2.8",
         "@oclif/plugin-autocomplete": "^3.2.24",
@@ -64,6 +64,7 @@
         "form-data": "^4.0.2",
         "fs-extra": "^11.3.0",
         "get-port": "^7.1.0",
+        "is-in-ci": "^2.0.0",
         "livereload": "^0.9.3",
         "neverthrow": "^8.2.0",
         "open": "^8.4.0",
@@ -145,7 +146,7 @@
             }
         },
         "topicSeparator": " ",
-        "state": "Alpha"
+        "state": "beta"
     },
     "lint-staged": {
         "*.js": "eslint --cache --fix",

package-lock.json

@@ -8,6 +8,7 @@ import { withDirPath } from "../../infrastructure/tmp-extensions.js";
 import { LauncherService } from "../../infrastructure/launcher-service.js";
 import { TempContext } from "../../types/temp-context.js";
 import { CommandMetadata } from "../../types/common/command-metadata.js";
+import { ServiceError } from "../../infrastructure/service-error.js";
 
 export class GenerateAction {
   private readonly prompts: PortalGeneratePrompts = new PortalGeneratePrompts();
@@ -57,7 +58,10 @@ export class GenerateAction {
 
       if (response.isErr()) {
         const error = response.error;
-        if (typeof error === "string") {
+        if (error instanceof ServiceError) {
+          this.prompts.portalGenerationServiceError(error);
+        }
+        else if (typeof error === "string") {
           this.prompts.portalGenerationError(error);
         } else {
           const errorZipPath = await tempContext.save(error);

package.json

@@ -17,7 +17,6 @@ import { getLanguagesConfig } from "../../types/build/build.js";
 import { FilePath } from "../../types/file/filePath.js";
 import { SpecContext } from "../../types/spec-context.js";
 
-
 const defaultPort: number = 3000 as const;
 
 export class PortalQuickstartAction {
@@ -27,21 +26,19 @@ export class PortalQuickstartAction {
   private readonly configDir: DirectoryPath;
   private readonly commandMetadata: CommandMetadata;
   private readonly fileDownloadService = new FileDownloadService();
-  private readonly buildFileUrl = new UrlPath(`https://github.com/apimatic/static-portal-workflow/archive/refs/heads/master.zip`);
-  private readonly defaultSpecUrl = new UrlPath(`https://raw.githubusercontent.com/apimatic/static-portal-workflow/refs/heads/master/spec/openapi.json`);
-  private readonly repositoryFolderName = "static-portal-workflow-master" as const;
+  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(configDir: DirectoryPath, commandMetadata: CommandMetadata) {
     this.configDir = configDir;
     this.commandMetadata = commandMetadata;
   }
 
   public readonly execute = async (): Promise<ActionResult> => {
-    this.prompts.welcomeMessage();
-
     const storedAuth = await getAuthInfo(this.configDir.toString());
     if (!storedAuth?.authKey) {
-      const loginResult = await new LoginAction(this.configDir, this.commandMetadata).execute();
+      const loginResult = await new LoginAction(this.configDir, this.commandMetadata).execute(); 
       if (loginResult.isFailed()) {
         return ActionResult.failed();
       }
@@ -66,7 +63,7 @@ export class PortalQuickstartAction {
           if (downloadFileResult.isErr()) {
             this.prompts.serviceError(downloadFileResult.error);
           } else {
-            const specContext = new SpecContext(tempDirectory)
+            const specContext = new SpecContext(tempDirectory);
             specPath = await specContext.save(downloadFileResult.value.stream, downloadFileResult.value.filename);
           }
         } else {
@@ -96,7 +93,7 @@ export class PortalQuickstartAction {
         if (downloadFileResult.isErr()) {
           this.prompts.serviceError(downloadFileResult.error);
         } else {
-          const specContext = new SpecContext(tempDirectory)
+          const specContext = new SpecContext(tempDirectory);
           specPath = await specContext.save(downloadFileResult.value.stream, downloadFileResult.value.filename);
         }
       }
@@ -145,7 +142,6 @@ export class PortalQuickstartAction {
       const extractedFolder = tempDirectory.join(this.repositoryFolderName);
 
       const tempBuildContext = new BuildContext(extractedFolder);
-      await tempBuildContext.replaceDefaultSpec(specPath);
       await tempBuildContext.deleteWorkflowDir();
 
       const buildFile = await tempBuildContext.getBuildFileContents();
@@ -155,6 +151,10 @@ export class PortalQuickstartAction {
       const sourceDirectory = inputDirectory.join("src");
       await this.fileService.copyDirectoryContents(extractedFolder, sourceDirectory);
 
+      const specDirectory = sourceDirectory.join("spec");
+      const specContext = new SpecContext(specDirectory);
+      await specContext.replaceDefaultSpec(specPath);
+
       const buildDirectoryStructure = await this.fileService.getDirectory(sourceDirectory);
       this.prompts.printDirectoryStructure(inputDirectory, buildDirectoryStructure);
 

src/actions/portal/generate.ts

@@ -65,10 +65,11 @@ export class PortalRecipeAction {
 
     // Setup recipe context
     const recipeContext = new RecipeContext(recipeName);
-    const recipeFileName = recipeContext.getRecipeName();
+    const recipeScriptFileName = recipeContext.getRecipeScriptFileName();
+    const recipeMarkdownFileName = recipeContext.getRecipeMarkdownFileName();
 
     // Check if the recipe already exists
-    const recipeAlreadyExists = recipeContext.exists(tocData, recipeName, recipeFileName);
+    const recipeAlreadyExists = recipeContext.exists(tocData, recipeName, recipeMarkdownFileName);
     if (recipeAlreadyExists && !(await this.prompts.overwriteApiRecipeInTocPrompt(recipeName))) {
       return ActionResult.cancelled();
     }
@@ -106,7 +107,9 @@ export class PortalRecipeAction {
               const specFileStream = await this.fileService.getStream(specZipPath);
 
               try {
-                return await this.prompts.generateSdl(this.portalService.generateSdl(specFileStream, this.configDirectory, this.commandMetadata))
+                return await this.prompts.generateSdl(
+                  this.portalService.generateSdl(specFileStream, this.configDirectory, this.commandMetadata)
+                );
               } finally {
                 specFileStream.close();
               }
@@ -144,12 +147,13 @@ export class PortalRecipeAction {
       tocData,
       tocContext.tocPath,
       recipeName,
-      recipeFileName,
+      recipeScriptFileName,
+      recipeMarkdownFileName,
       buildContext,
       buildDirectory
     );
 
-    const tocStructure = this.getTocStructure(recipeFileName);
+    const tocStructure = this.getTocStructure(recipeScriptFileName);
     this.prompts.recipeCreated();
     this.prompts.displayRecipeStructure(tocStructure);
     this.prompts.nextSteps();

src/actions/portal/quickstart.ts

@@ -22,7 +22,6 @@ export class PortalServeAction {
   private readonly configDir: DirectoryPath;
   private readonly commandMetadata: CommandMetadata;
   private readonly authKey: string | null;
-  private isPortalServed: boolean = false;
 
   public constructor(configDir: DirectoryPath, commandMetadata: CommandMetadata, authKey: string | null = null) {
     this.configDir = configDir;
@@ -50,7 +49,7 @@ export class PortalServeAction {
     }
 
     const liveReloadPort = await this.networkService.getServerPort([35729, 35730, 35731, 35732]);
-    const liveReloadServer = createLiveReloadServer({ port: liveReloadPort});
+    const liveReloadServer = createLiveReloadServer({ port: liveReloadPort });
     const server = this.application
       .use(connectLiveReload())
       .use(express.static(portalDirectory.toString(), { extensions: ["html"] }))
@@ -136,7 +135,6 @@ export class PortalServeAction {
 
     await watcher.close();
     debounceService.close();
-
     liveReloadServer.close();
     server.close();
     return ActionResult.success();

src/actions/portal/recipe/new-recipe.ts

@@ -1,4 +1,4 @@
-import { err, ok, Result } from "neverthrow";
+import { ok } from "neverthrow";
 import { PortalNewTocPrompts } from "../../../prompts/portal/toc/new-toc.js";
 import { TocStructureGenerator } from "../../../application/portal/toc/toc-structure-generator.js";
 import { TocEndpoint, TocGroup, TocModel } from "../../../types/toc/toc.js";
@@ -7,7 +7,6 @@ import { CommandMetadata } from "../../../types/common/command-metadata.js";
 import { ActionResult } from "../../action-result.js";
 import { TocContext } from "../../../types/toc-context.js";
 import { FileService } from "../../../infrastructure/file-service.js";
-import { FilePath } from "../../../types/file/filePath.js";
 import { BuildContext } from "../../../types/build-context.js";
 import { getEndpointGroupsAndModels } from "../../../types/sdl/sdl.js";
 import { withDirPath } from "../../../infrastructure/tmp-extensions.js";

src/actions/portal/serve.ts

@@ -0,0 +1,31 @@
+import { QuickstartPrompts } from "../prompts/quickstart.js";
+import { CommandMetadata } from "../types/common/command-metadata.js";
+import { DirectoryPath } from "../types/file/directoryPath.js";
+import { ActionResult } from "./action-result.js";
+import { PortalQuickstartAction } from "./portal/quickstart.js";
+import { SdkQuickstartAction } from "./sdk/quickstart.js";
+
+export class QuickstartAction {
+  private readonly prompts = new QuickstartPrompts();
+
+  public constructor(private readonly configDir: DirectoryPath, private readonly commandMetadata: CommandMetadata) {}
+
+  public readonly execute = async (): Promise<ActionResult> => {
+    this.prompts.welcomeMessage();
+    const selectedFlow = await this.prompts.selectQuickstartFlow();
+    switch (selectedFlow) {
+      case "portal": {
+        const action = new PortalQuickstartAction(this.configDir, this.commandMetadata);
+        return await action.execute();
+      }
+      case "sdk": {
+        const action = new SdkQuickstartAction(this.configDir, this.commandMetadata);
+        return await action.execute();
+      }
+      case undefined: {
+        this.prompts.noQuickstartFlowSelected();
+        return ActionResult.cancelled();
+      }
+    }
+  };
+}