[Portal] Add `portal:recipe:new` command for API Recipes

[aliasghar98]

What

We need to add a new command portal:recipe:new to add a new API recipe/guided walkthrough to the existing build input folder.

Why

The process of adding a new API Recipe/guided walkthrough is fairly complicated for new users of the feature. We need to provide assistance through a CLI command i.e. portal:recipe:new to facilitate this process.

[aliasghar98]

Potential User Flows

The following user flows can be implemented as part of this command in order to facilitate the addition of an API Recipe/Guided Walkthrough to a user's build input:

1. Step-by-step Wizard

This approach would involve getting a user's input at every step in order to dictate what kind of API Recipe they are looking to add. The following steps are an example of what a wizard might look like, and aren't the complete number of steps needed in order to add a guided walkthrough:

1. Enter Name of the API Recipe
2. Select Type of Step to Add
   • Content
   • Endpoint

Content Step Flow:

3. Enter link or path to content markdown file to be used.
4. Do you want to add another step?
   • Yes ( repeat the process from step 2 )
   • No ( displays tree of build input folder with new files created + an explanation of what they do).

Endpoint Step Flow:

3. Select the Endpoint to be used (Or enter the endpoint's name for example. Any way to communicate which endpoint to use).
4. Enter description.
5. Enter endpointPermalink (this step can be removed).
6. Enter error message (Optional, in case the user wants to show a custom error message).
7. Do you want to add another step?
   • Yes ( repeat the process from step 2 )
   • No ( displays tree of build input folder with new files created + an explanation of what they do).

2. Automatically Create Required Files and Allow User to Customize as per need

This approach would involve creating the bare-minimum files (with skeleton code and placeholder values describing each file) required to get started with an API Recipe. This would require the user to specify the name of the recipe only. Here's a sample of what the flow may look like:

apimatic portal:recipe:new --name=my-first-api-recipe --folder=path/to/my/build/input/folder

$ Generating API Recipe... Completed ✅
├─ APIMATIC-BUILD.json : # The tailIncludes property contains the reference of the script and markdown files of your API recipe
│ ├─ content : # Includes custom documentation pages in Markdown
│ │ ├─ api-recipes
│ │ │ ├─ recipe1.md # Your API Recipe markdown file
│ │ ├─ guides
│ │ │ ├─ guide1.md
│ │ │ └─ toc.yml
│ │ └─ toc.yml : # Contains reference to API Recipe for rendering in the navigation bar
│ ├─ README.md
│ ├─ spec :
│ │ ├─ Apimatic-Calculator.json
│ │ └─ APIMATIC-META.json
│ └─ static : # Includes all static files, such as images, GIFs, and PDFs and API Recipes
│ │ └─ api-recipes
│ │ └─ recipe-1.js # Your API Recipe script file
│ └─ images
│ └─ logo.png

$ Your guided walkthrough has been added to your portal build input at: path/to/my/build/input/folder

APIMatic Build file:

{
    "$schema": "https://titan.apimatic.io/api/build/schema",
    "buildFileVersion": "1",
    "generatePortal": {
        ...
        "tailIncludes": "<script defer src='./static/scripts/guided-walkthroughs/walkthrough-1.js'></script><script>document.addEventListener('DOMContentLoaded', (event) => {APIMaticDevPortal.ready(({ registerWorkflow }) => {registerWorkflow('page:calculate-api/guided-walkthroughs/walkthrough-1', 'Sample Workflow', SampleWorkflow);});});</script>"
    }
}

API Recipe markdown file:

# This is a Guided Walkthrough File 
This is the starter content which is just dummy content that will be replaced by the content described in the API recipe script file

TOC File:

toc:
  - group: Getting Started
    items:
    # 'generate' specifies that this item will be auto-generated by APIMatic. A file/directory reference is not needed here
      - generate: How to Get Started  
        from: getting-started
  - group: API Recipes 
    items:
      - page: Recipe 1
        file: calculate-api/api-recipes/recipe-1.md
  - group: Guides
    dir: guides
    # The Endpoint and Models sections contain auto-generated content. The 'generate' and 'from' directives instruct APIMatic's Docs generation service
    # to generate and insert these sections here.
  - generate: API Endpoints
    from: endpoints
  - generate: Models
    from: models

API Recipe script file:

async function SampleWorkflow(workflowCtx, portal) {
  return {
    "Guide": { // First step of the walkthrough
      name: "Introduction Guide", // Name of the Step
      stepCallback: async () => {
        return workflowCtx.showContent(`## Enter content you wish to show here`);
      }
    },
    "Step 1": { // Second step of the walkthrough
      name: "",
      stepCallback: async (stepState) => {
        const stateAfterPreviousStep = stepState?.["Guide"]; // You can transfer state from one step to another, for e.g. you can get the auth-token in one step and use it in the next step.
        await portal.setConfig((defaultConfig) => ({}));
        return workflowCtx.showEndpoint({ // 
          description:
            "Enter description of the endpoint here",
          args: { // Enter the default arguments (or default endpoint parameter values)
            x: 5,
            y: 10,
            operation: stateAfterPreviousStep?.data?.operation,
          },
          verify: (response, setError) => { // Configure behavior and messaging for success and error states
            if (response.StatusCode == 200) {
              return true; // To mark step completion.
            } else {
              setError( 
                "API Call wasn't able to get a valid response. Please try again."
              );
              return false; // To mark step failure.
            }
          },
        });
      },
    },
  };
}

[aliasghar98]

Action Items:

• Get endpoint name and endpoint group name through text for now.
• Explore scrollable list element for endpoint groups and endpoints.