feat: add support for spec pruning and webhooks callbacks flags in toc command (#220)

---------

Co-authored-by: Ayesha <88117894+Ayeshas09@users.noreply.github.com>
Co-authored-by: Asad Ali <14asadali@gmail.com>
Co-authored-by: Muhammad Sohail <62895181+sohail2721@users.noreply.github.com>

Author: 4 people

.prettierrc

@@ -1,7 +1,7 @@
 {
     "parser": "typescript",
     "printWidth": 120,
-    "singleQuote": false,
+    "singleQuote": true,
     "trailingComma": "none",
     "tabWidth": 2
 }

README.md

@@ -24,7 +24,7 @@ $ npm install -g @apimatic/cli
 $ apimatic COMMAND
 running command...
 $ apimatic (--version)
-@apimatic/cli/1.0.0-beta.1 win32-x64 node-v23.4.0
+@apimatic/cli/1.1.0-beta.3 win32-x64 node-v23.4.0
 $ apimatic --help [COMMAND]
 USAGE
   $ apimatic COMMAND
@@ -349,16 +349,21 @@ Generate a Table of Contents (TOC) file for your API documentation portal
 ```
 USAGE
   $ apimatic portal toc new [-d <value>] [-i <value>] [-f] [--expand-endpoints] [--expand-models]
+    [--expand-webhooks] [--expand-callbacks]
 
 FLAGS
   -d, --destination=<value>  [default: <input>/src/content] path where the toc.yml 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.
+      --expand-callbacks     include individual entries for each callback in the generated 'toc.yml'. Requires a valid
+                             API specification in the working directory.
       --expand-endpoints     include individual entries for each endpoint in the generated 'toc.yml'. Requires a valid
                              API specification in the working directory.
       --expand-models        include individual entries for each model in the generated 'toc.yml'. Requires a valid API
                              specification in the working directory.
+      --expand-webhooks      include individual entries for each webhook in the generated 'toc.yml'. Requires a valid
+                             API specification in the working directory.
 
 DESCRIPTION
   Generate a Table of Contents (TOC) file for your API documentation portal

package-lock.json

@@ -1,54 +1,94 @@
 enum ResultType {
-  Success= 0,
+  Success = 0,
   Cancel = 130,
-  Failure= 1
+  Failure = 1,
 }
 
-export class ActionResult {
+export class ActionResult<T = void> {
   private readonly message: string;
   private readonly resultType: ResultType;
+  private readonly value?: T;
 
-  private constructor(resultType: ResultType, message: string) {
+  private constructor(resultType: ResultType, message: string, value?: T) {
     this.resultType = resultType;
     this.message = message;
+    this.value = value;
   }
 
-  static success() {
-    return new ActionResult(ResultType.Success, " Succeeded ");
+  static success<T>(value?: T): ActionResult<T> {
+    return new ActionResult<T>(ResultType.Success, "Succeeded", value);
   }
 
-  static failed() {
-    return new ActionResult(ResultType.Failure, " Failed ");
+  static failed<T = never>(message = "Failed"): ActionResult<T> {
+    return new ActionResult(ResultType.Failure, message);
   }
 
-  static cancelled() {
-    return new ActionResult(ResultType.Cancel, " Cancelled ");
+  static cancelled<T = never>(message = "Cancelled"): ActionResult<T> {
+    return new ActionResult(ResultType.Cancel, message);
   }
 
-  static stopped() {
-    return new ActionResult(ResultType.Cancel, " Stopped ");
+  static stopped<T = never>(message = "Stopped"): ActionResult<T> {
+    return new ActionResult(ResultType.Cancel, message);
   }
 
-  public getMessage() {
+  public getMessage(): string {
     return this.message;
   }
 
-  public getExitCode() {
+  public getExitCode(): number {
     return this.resultType.valueOf();
   }
 
-  public isFailed() {
+  public isFailed(): boolean {
     return this.resultType === ResultType.Failure;
   }
 
-  public mapAll<T>(onSuccess: () => T, onFailure: () => T, onCancel: () => T): T {
+  public isSuccess(): boolean {
+    return this.resultType === ResultType.Success;
+  }
+
+  public isCancelled(): boolean {
+    return this.resultType === ResultType.Cancel;
+  }
+
+  public match<R>(
+    onSuccess: (value: T) => R,
+    onFailure: (message: string) => R,
+    onCancel: (message: string) => R
+  ): R {
     switch (this.resultType) {
       case ResultType.Success:
-        return onSuccess();
+        return onSuccess(this.value!);
+      case ResultType.Failure:
+        return onFailure(this.message);
+      case ResultType.Cancel:
+        return onCancel(this.message);
+    }
+  }
+
+  public getValue(): T {
+    if (!this.isSuccess()) {
+      throw new Error(`Cannot unwrap ${ResultType[this.resultType]} result: ${this.message}`);
+    }
+    return this.value!;
+  }
+
+  public getValueOr(defaultValue: T): T {
+    return this.isSuccess() ? this.value! : defaultValue;
+  }
+
+  public mapAll<R>(
+    onSuccess: (value?: T) => R,
+    onFailure: () => R,
+    onCancel: () => R
+  ): R {
+    switch (this.resultType) {
+      case ResultType.Success:
+        return onSuccess(this.value);
       case ResultType.Failure:
         return onFailure();
       case ResultType.Cancel:
         return onCancel();
     }
   }
-}
+}

src/actions/action-result.ts

@@ -1,11 +1,12 @@
 import { DirectoryPath } from "../../types/file/directoryPath.js";
 import { ActionResult } from "../action-result.js";
 import { ApiValidatePrompts } from "../../prompts/api/validate.js";
-import { ValidationService } from "../../infrastructure/services/validation-service.js";
+import { UnallowedFeaturesResponse, ValidationService } from "../../infrastructure/services/validation-service.js";
 import { CommandMetadata } from "../../types/common/command-metadata.js";
 import { ResourceInput } from "../../types/file/resource-input.js";
 import { withDirPath } from "../../infrastructure/tmp-extensions.js";
 import { ResourceContext } from "../../types/resource-context.js";
+import { ValidationSummary } from "@apimatic/sdk";
 
 export class ValidateAction {
   private readonly prompts: ApiValidatePrompts = new ApiValidatePrompts();
@@ -22,7 +23,7 @@ export class ValidateAction {
   public readonly execute = async (
     resourcePath: ResourceInput,
     displayValidationSummary = true
-  ): Promise<ActionResult> => {
+  ): Promise<ActionResult<UnallowedFeaturesResponse | null>> => {
     return await withDirPath(async (tempDirectory) => {
       const resourceContext = new ResourceContext(tempDirectory);
       const specFileDirResult = await resourceContext.resolveTo(resourcePath);
@@ -44,13 +45,26 @@ export class ValidateAction {
       }
       const validationSummary = validationSummaryResult.value;
       if (displayValidationSummary) {
-        this.prompts.displayValidationMessages(validationSummary);
+        if (this.hasValidationIssues(validationSummary.result.validation)) {
+          this.prompts.displayValidationSummary(validationSummary.result.validation);
+        }
+        if (this.hasValidationIssues(validationSummary.result.linting)) {
+          this.prompts.displayValidationSummary(validationSummary.result.linting);
+        }
       }
-      if (!validationSummary.success) {
+      if (!validationSummary.result.validation.isSuccess || !validationSummary.result.linting.isSuccess) {
         return ActionResult.failed();
       }
-
-      return ActionResult.success();
+      return ActionResult.success(validationSummary.unallowedFeatures);
     });
   };
+
+  private hasValidationIssues(summary: ValidationSummary): boolean {
+    return (
+      summary.blocking.length > 0 ||
+      summary.errors.length > 0 ||
+      summary.warnings.length > 0 ||
+      summary.information.length > 0
+    );
+  }
 }

src/actions/api/validate.ts

@@ -16,6 +16,8 @@ import { FileDownloadService } from "../../infrastructure/services/file-download
 import { getLanguagesConfig } from "../../types/build/build.js";
 import { FilePath } from "../../types/file/filePath.js";
 import { SpecContext } from "../../types/spec-context.js";
+import { FeaturesToRemove, ValidationService } from "../../infrastructure/services/validation-service.js";
+import { FileName } from "../../types/file/fileName.js";
 
 const defaultPort: number = 3000 as const;
 
@@ -26,19 +28,25 @@ 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/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 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;
+  private readonly validationService: ValidationService;
 
   constructor(configDir: DirectoryPath, commandMetadata: CommandMetadata) {
     this.configDir = configDir;
     this.commandMetadata = commandMetadata;
+    this.validationService = new ValidationService(this.configDir);
   }
 
   public readonly execute = async (): Promise<ActionResult> => {
     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();
       }
@@ -98,6 +106,24 @@ export class PortalQuickstartAction {
         }
       }
 
+      const unallowed = validationResult.getValue();
+      if (unallowed && (unallowed.Features?.length > 0 || unallowed.EndpointCount > unallowed.EndpointLimit)) {
+        const config: FeaturesToRemove = {
+          features: unallowed.Features.filter((name) => !!name),
+          endpointsToKeep: unallowed.EndpointLimit
+        };
+
+        const stripUnallowedFeaturesResult = await this.validationService.stripUnallowedFeatures(specPath, config);
+        if (stripUnallowedFeaturesResult.isErr()) {
+          this.prompts.splitSpecDetected(unallowed);
+          return ActionResult.failed();
+        } else {
+          this.prompts.stripUnallowedFeaturesStep(unallowed);
+          const specContext = new SpecContext(tempDirectory);
+          specPath = await specContext.save(stripUnallowedFeaturesResult.value, new FileName("pruned-spec.zip"));
+        }
+      }
+
       // Step 3/4
       this.prompts.selectLanguagesStep();
       const languages = await this.prompts.selectLanguagesPrompt();
@@ -163,9 +189,11 @@ export class PortalQuickstartAction {
       const result = await portalServeAction.execute(sourceDirectory, portalDirectory, defaultPort, true, false, () => {
         this.prompts.nextSteps();
       });
+
       if (result.isFailed()) {
         return ActionResult.failed();
       }
+
       return ActionResult.success();
     });
   };