ISS-120468: Update documentation for the marketplace related commands

fern/docs/pages/references/marketplace-listings.mdx

@@ -0,0 +1,239 @@
+# Publish an item to Marketplace
+
+Welcome to the documentation page for publishing marketplace listings to the DevRev marketplace using the DevRev CLI.
+This guide will walk you through the process of submitting your listing, reviewing it, and publishing it for users to
+access and engage with. You will learn about creating and updating marketplace submissions, the roles of the marketplace
+publisher and admin, and the steps involved in getting your submission approved. Whether you're new to the DevRev CLI or
+looking for a refresher, this documentation will provide you with the necessary information to navigate the publishing
+process seamlessly. Let's dive in and get started!
+
+## Table of Contents
+
+- [Publish an item to Marketplace](#publish-an-item-to-marketplace)
+  - [Table of Contents](#table-of-contents)
+  - [Glossary](#glossary)
+  - [Marketplace](#marketplace)
+  - [Marketplace Submission](#marketplace-submission)
+  - [Marketplace Item](#marketplace-item)
+  - [Marketplace listing](#marketplace-listing)
+  - [Publishing process](#publishing-process)
+  - [Get Started](#get-started)
+  - [Create a Snap-In](#create-a-snap-in)
+  - [Create marketplace listing](#create-marketplace-listing)
+  - [Initial submission](#initial-submission)
+  - [New submission for an existing marketplace item](#new-submission-for-an-existing-marketplace-item)
+  - [Update marketplace submission](#update-marketplace-submission)
+  - [Publish marketplace submission](#publish-marketplace-submission)
+  - [Delete marketplace submission](#delete-marketplace-submission)
+  - [Auto-upgradation of marketplace-items](#auto-upgradation-of-marketplace-items)
+  - [Sharing marketplace listings](#sharing-marketplace-listings)
+  - [Ranking marketplace listings](#ranking-marketplace-listings)
+  - [Some helpful commands](#some-helpful-commands)
+
+## Glossary
+
+### Marketplace
+
+A marketplace serves as a platform for creators and consumers to collaborate, engage, and conduct transactions. It
+provides an avenue for distributing your products and services, thereby enabling you to generate revenue from them.
+
+### Marketplace Submission
+
+This object is utilized for submission purposes when the marketplace publisher is either creating a new listing for the
+marketplace or updating an existing one.
+
+### Marketplace Item
+
+Any item in marketplace listings that is available for installation.
+
+#### Marketplace listing
+
+Marketplace listing refers to all the marketplace items that belong to the same marketplace and have the same slug. It
+is also important to note that at most one marketplace item, belonging to a specific marketplace listing, can be in the
+`Published` state.
+
+![marketplace listing](./res/images/marketplace-listing.png)
+
+## Publishing process
+
+The publishing process begins by initiating a marketplace submission, which entails requesting the creation of a new
+marketplace listing or updating an existing one. The submission is created by the marketplace publisher and subsequently
+reviewed by the marketplace admin. Once the submission is ready for review, the publisher must transition it to the '
+waiting for review' state. During this phase, the marketplace admin conducts a review and decides whether to approve or
+reject the submission. If the submission is approved, the marketplace publisher can proceed to publish it. However, if
+the submission is rejected, the publisher has the option to make updates and resubmit it for another round of review.
+
+![life cycle](./res/images/lifecycle.png)
+
+## Get Started
+
+To get started with publishing a marketplace item, you will need the DevRev CLI. For CLI related
+guide [visit here](https://github.com/devrev/snap-in-docs/blob/main/references/cli.md).
+
+### Create a Snap-In
+
+To proceed with making a submission in the marketplace, you will need a Snap-In for which we will create this
+submission. If you are new to
+Snap-Ins, [follow this guide here](https://github.com/devrev/snap-in-docs/blob/main/start.md), to create your first
+Snap-In.
+
+## Create marketplace listing
+
+When creating a new marketplace listing, we have to create an initial submission where we provide all the mandatory
+properties (e.g. name, description, icon, etc.).
+
+### Initial submission
+
+To create a new marketplace listing, run the following command, which will start a __wizard__ to guide you through the
+process:
+
+```bash
+devrev marketplace_submissions create
+```
+
+### New submission for an existing marketplace item
+
+When a marketplace listing already exists (there is at least one marketplace item in the `published` or `end_of_sale`
+state), we can modify the listing by creating a new submission. First we have to create a submission which we can later
+update
+as desired.
+
+To create a new submission for an existing marketplace listing, run the following command, which will start a __wizard__
+to
+guide you through the process:
+
+```bash
+devrev marketplace_submissions create
+```
+
+## Update marketplace submission
+
+Once a submission has been created, it can be updated by running the following command, which will start a __wizard__ to
+guide you through the process:
+
+```bash
+devrev marketplace_submissions update
+```
+
+## Publish marketplace submission
+
+The newly created marketplace submission is in the `draft` state. In order to publish it, we first have to transition it
+to`waiting_for_review` state. This can be done by running the following command, which will start a __wizard__ to guide
+you through the process:
+
+```bash
+devrev marketplace_submissions transition
+```
+
+Once the submission is transitioned to the `waiting_for_review` state, it needs to be approved by a marketplace admin.
+While in review, the state of the submission is `in_review`. Once it is reviewed, the state will be changed to either
+`approved` or `rejected`.
+
+<Callout intent="note">
+Submissions whose state is `in_review` cannot be modified.
+</Callout>
+
+
+If the submission was rejected, we can transition it back to `draft` state and modify it to satisfy the requirements.
+Once the submission is updated, we can transition it back to `waiting_for_review` state to be reviewed again.
+
+If the submission was approved, we can publish it using the following command, which will start a __wizard__ to guide
+you through the process:
+
+```bash
+devrev marketplace_items publish
+```
+
+To make sure that marketplace item was published we can retrieve it using its ID:
+
+```bash
+devrev marketplace_items show "<id>" | jq "{name: .name, id: .id}"
+```
+
+## Delete marketplace submission
+
+If a marketplace submission was created by mistake or is no longer relevant, it can be deleted. However, deletion of a
+marketplace submission is only permitted for the owners of the submission and is restricted to submissions that are in
+the `draft` or `rejected` state. You can delete a submission using the following command, which will start a __wizard__
+to guide you through the process:
+
+```bash
+devrev marketplace_submissions delete
+```
+
+## Auto-upgradation of marketplace-items
+
+For marketplace-items that are Snap-Ins, auto-upgradation is also supported.
+Once a new version for a marketplace-item is published, the respective Snap-Ins will be auto-upgraded to the latest
+version.
+
+However, there are some criteria that need to be met for auto-upgrade to work:
+
+- The upgrade should not require any user input/action.
+  - There should not be any new global variables added.
+  - There should not be any new connections that needs to be configured.
+
+## Sharing marketplace listings
+
+By default, all marketplace listings are accessible to all users. However, if someone wants to share a specific
+marketplace listing with certain organizations only, they should follow the steps below:
+
+- When creating an initial submission, property __access level__ should be set to `restricted`.
+- Proceed through the review process to obtain approval for the submission.
+- Once the submission is approved, publish it to create the marketplace item.
+- To invite a specific DEV organization to the newly created marketplace item, execute the following command:
+
+```bash
+devrev marketplace_items invite [marketplace_item_id] [dev_org_id]
+  ```
+
+Example:
+
+```bash
+devrev marketplace_items invite "don:integration:dvrv-us-1:devo/123:marketplace/456:marketplace_item/789" "don:identity:dvrv-us-1:devo/456"
+  ```
+
+Once an organization is invited to a marketplace listing, their members can *view* and *install* it within their own
+organization.
+
+When a marketplace listing is marked as restricted, it is possible to change the access level to `public`. However,
+the reverse process, changing the access level from `public` to `restricted`, is not permitted.
+
+When a marketplace listing is shared with an organization, this information is **retained when creating new submissions
+for the same listing**. Additionally, automatic upgrades function seamlessly, just like in the case of public
+marketplace listings.
+
+## Ranking marketplace listings
+
+The items listed on the marketplace are arranged based on the `meta_score` property, with those having higher scores
+appearing at the top of the list. To manage the `meta_score` property, a dedicated API called `marketplace-items.rank`
+is utilized. To update the `meta_score`, one needs to provide the `marketplace item ID` along with the desired score (
+within the allowed range of values: [1, 100000]):
+
+```bash
+devrev marketplace_items rank "<marketplace_item_id>" "<meta_score>" | jq
+```
+
+<Callout intent="note">
+Please note that API usage is restricted exclusively to `DEV-0` users.
+</Callout>
+
+## Some helpful commands
+
+List marketplaces:
+
+```bash
+devrev marketplace list | jq "{name: .name, type: .marketplace_type, id: .id}"
+```
+
+List marketplace items (by default, listings are from universal marketplace):
+
+```bash
+devrev marketplace_items list | jq "{name: .name, id: .id, type: .type}"
+```
+
+List marketplace items in **organizational** marketplace:
+
+```bash
+devrev marketplace_items list --marketplace "<id>" | jq "{name: .name, id: .id, type: .type}"
+```

fern/versions/public.yml

@@ -157,6 +157,9 @@ navigation:
           - page: Snap-in V1 manifest
             slug: v1-manifest
             path: ../docs/pages/references/v1-manifest.mdx
+          - page: Marketplace listings
+            slug: marketplace-listings
+            path: ../docs/pages/references/marketplace-listings.mdx
           - section: Keyrings
             slug: keyrings
             contents: