Contentstack JavaScript Marketplace SDK

Introduction to JavaScript Marketplace SDK

Contentstack offers JavaScript Marketplace SDK. Seamlessly integrated, this SDK empowers JavaScript developers to effortlessly build, deploy, and manage marketplace applications. Below is an in-depth guide to initiate your journey with the Java Marketplace SDK.

Additional Resource To know more about the Java Marketplace SDK, refer to the About JavaScript Marketplace SDK and Get Started with JavaScript Marketplace SDK documentation.

Marketplace

Contentstack Marketplace is a hub for apps and other resources that help you extend the capabilities of our core CMS and customize its functionalities. It houses third-party integrations, UI extensions (such as dashboard, sidebar, custom field, and RTE plugins), and other tools that you can plug into Contentstack at the stack as well as organizational level.

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

client.marketplace('organization_uid');

Name	Type	Description
org_uid (required)	String	UID of the organization

app

The app method creates and retrieves a new instance of the App class with the given parameters.

Name	Type	Description
manifest_uid	String	UID of the app

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').app('manifest_uid');

installation

The installation method allows you to retrieve, update and delete the app installation.

Name	Type	Description
uid	String	UID for the installation

Example 1:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.organization('organization_uid').app('manifest_uid').installation().findAll()

.then((installations) => console.log(installations));

Example 2:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').installation('installation_uid').fetch()

.then((installation) => console.log(installation));

appRequests

The appRequests method creates an app request for the app.

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').appRequests();

findAllApps

The findAllApps method retrieves all the apps in your organization.

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').findAllApps()

.then((collection) => console.log(collection));

findAllAuthorizedApps

The findAllAuthorizedApps method retrieves all the authorized apps for the organization.

Name	Type	Description
skip	number	Offset for skipping content in response
limit	number	Limit on API response to provide content in the list

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client();

client.marketplace('organization_uid').findAllAuthorizedApps({ skip: 10 })

.then((roles) => console.log(roles));

searchApps

The searchApps method lets you find Marketplace apps in your Contentstack organization by name.

Name	Type	Description
search (required)	String	The app name or keyword to search for.
sort	String	Field to sort the results (eg. created_at, updated, at)
target_type	['stack'] or ['organization']	Specify whether your app is a stack app or an organization app
order	String	The order in which the response is given
limit	Number	Limit on API response to provide content in the list
skip	Number	Offset for skipping content in response

Example 1:

import * as contentstack from '@contentstack/marketplace-sdk'
const client = contentstack.client({ authtoken: 'TOKEN' });
const search = 'appname'
client.marketplace('organization_uid')
  .searchApps(search)
  .then((collection) => console.log(collection))
  .catch((error) => console.error(error));

Example 2:

import * as contentstack from '@contentstack/marketplace-sdk'
const client = contentstack.client({ authtoken: 'TOKEN' });
client.marketplace('organization_uid')
  .searchApps('mp app name', {
    order: 'desc',
    sort: 'created_at',
    target_type: 'field'
  })
  .then((collection) => console.log(collection))
  .catch((error) => console.error(error));

App

App/Manifest is used for creating/updating/deleting an app in your organization.

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const app = client.marketplace('organization_uid').app('manifest_uid');

Name	Type	Description
manifest_uid (required)	String	UID of the manifest

update

The update method allows you to update the app details such as name, description, icon, and so on.

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

const updateApp = {

 name: 'APP_NAME',

 description: 'APP_DESCRIPTION',

 target_type: 'stack'/'organization',

}

const app = client.marketplace('organization_uid').app('manifest_uid');

app = Object.assign(app, updateApp)

app.update()

.then((app) => console.log(app));

fetch

The fetch method retrieves the details of a particular app with its ID.

Name	Type	Description
include_oauth	Boolean	To get the oauth details of an app

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').app('manifest_uid').fetch()

.then((app) => console.log(app));

oauth

The oauth method allows you to retrieve and update Oauth and retrieve scopes.

Name	Type	Description
include_oauth	Boolean	To get the oauth details of an app

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').app('manifest_uid').oauth();

delete

The delete method is used to delete the app.

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').app('manifest_uid').delete()

.then((response) => console.log(response));

hosting

The hosting method allows you to retrieve, update, and deploy a manifest.

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').app('manifest_uid').hosting();

install

The install method initiates the installation of the app.

Name	Type	Description
param.targetType (required)	String	The target on which app needs to be installed. It can either be a stack or an organization
param.targetUid	String	The UID of the target, on which the app will be installed

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').app('manifest_uid').install({ targetUid: 'STACK_API_KEY', targetType: 'stack' })

.then((installation) => console.log(installation));

upgrade

The upgrade method upgrades the installation of an app.

Name	Type	Description
param.targetType (required)	String	The target on which app needs to be installed. It can either be a stack or an organization
param.targetUid (required)		The uid of the target, on which the app will be installed

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').app('manifest_uid').upgrade({ targetUid: 'STACK_API_KEY', targetType: 'stack' })

.then((installation) => console.log(installation));

authorize

The authorize method authorizes the app for a specific scope.

Name	Type	Description
param.responseType (required)	String	Desired grant type
param.clientId (required)	String	Client id of the app
param.redirectUri	String	Redirect URL of the app
param.scope	String	Scopes of the app
param.state	String	Local state provided by the client

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').app('app_uid').authorize({ responseType, clientId, redirectUri, scope, state })

.then((response) => console.log(response));

getRequests

The getRequests method retrieves all requests of an app.

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').app('app_uid').getRequests()

.then((response) => console.log(response));

authorization

The authorization method allows you to retrieve all and revoke specific or all authorizations.

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').app('manifest_uid').authorization();

listInstallations

The listInstallations method is used to retrieve all installations of your Contentstack organization.

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').app('app_uid').listInstallations()

.then((collection) => console.log(collection));

create

The create method creates a new app/manifest in your Contentstack organization.

Name	Type	Description
app_details (required)	Object	Details of the app to be created

Example:

import * as contentstack from '@contentstack/marketplace'

const client = contentstack.client({ authtoken: 'TOKEN'});

const app = {

 name: 'APP_NAME',

 description: 'APP_DESCRIPTION',

 target_type: 'stack'/'organization',

 webhook: // optional

  {

    target_url: 'TARGET_URL',

    channel: 'CHANNEL'

  },

 oauth: // optional

  {

    redirect_uri: 'REDIRECT_URI',

    enabled: true,

  }

}


client.marketplace('organization_uid').app().create(app)

.then((app) => console.log(app));

Oauth

Contentstack OAuth allows users to share protected data from the Contentstack API without sharing the credentials. To do this, the Contentstack OAuth server issues access tokens (App and User tokens) that client applications can use to access restricted data on behalf of the user.

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').app('manifest_uid').oauth();

fetch

The fetch method retrieves the authentication details of the app.

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').app('manifest_uid').oauth().fetch()

.then((oAuthConfig) => console.log(oAuthConfig));

update

The update method updates the OAuth details i.e., the redirect url and permission scope of an app.

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

const config = {

 redirect_uri: 'REDIRECT_URI',

 app_token_config: {

   enabled: true,

   scopes: ['scope1', 'scope2']

  },

  user_token_config: {

   enabled: true,

   scopes: ['scope1', 'scope2']

  }

 };

client.marketplace('organization_uid').app('manifest_uid').oauth().update({ config })

.then((oAuthConfig) => console.log(oAuthConfig));

getScopes

The getScopes method is used to retrieve all permission scopes.

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').app('manifest_uid').oauth().getScopes()

.then((scopes) => console.log(scopes));

Hosting

The hosting class retrieves the details about the hosting configuration of an app.

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').app('manifest_uid');

isEnable

The isEnable method retrieves the OAuth details of the app.

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});


client.marketplace('organization_uid').app('manifest_uid').hosting().isEnable()

.then((data) => console.log(data));

enable

The enable method enables the hosting of an app.

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').app('manifest_uid').hosting().enable()

.then((data) => {});

disable

The disable method disables the hosting of an app.

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').app('manifest_uid').hosting().disable()

.then((data) => {});

createUploadUrl

The createUploadUrl method creates a signed url for file upload.

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').app('manifest_uid').hosting().createUploadUrl()

.then((data) => {});

latestLiveDeployment

The latestLiveDeployment method retrieves the details of the latest deployment of the source file.

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').app('manifest_uid').hosting().latestLiveDeployment()

.then((data) => {});

deployment

The deployment method creates an instance of Hosting deployment.

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').app('manifest_uid').hosting().deployment();

Deployment

The Deployment method retrieves and manages the deployment related processes.

fetch

The fetch method retrieves all the details of a deployment of an app.

Name	Type	Description
deployment_uid (required)	String	UID of a deployment

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').app('manifest_uid').hosting().deployment('deployment_uid').fetch()

.then((data) => {});

logs

The logs method retrieves the logs of a deployment.

Name	Type	Description
deployment_uid (required)	String	UID of a deployment

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').app('manifest_uid').hosting().deployment('deployment_uid').logs()

.then((data) => {});

create

The create method deploys the uploaded file in hosting.

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').app('manifest_uid').hosting().deployment().create()

.then((data) => {});

findAll

The findAll deployments method retrieves all the available deployments made for an app.

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').app('manifest_uid').hosting().deployment().findAll()

.then((data) => {});

AppRequests

The AppRequests class creates, deletes, or retrieves the app requests made by the user.

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').appRequests();

delete

The delete method deletes an app request of an app in target_uid.

Name	Type	Description
requestUID (required)	String	The ID of the request to be deleted

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});


client.marketplace('organization_uid').appRequests().delete('request_uid`)

.then((response) => console.log(response));

create

The create method creates an app request.

Name	Type	Description
appUid (required)	String	The UID for the app for request
targetUid (required)	String	The UID of the target, on which the app will be installed

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').appRequests().create({ appUid: 'app_uid', targetUid: 'target_uid' })

.then((response) => console.log(response));

findAll

The findAll method retrieves the requests of all apps in an organization.

Name	Type	Description
skip	Number	Offset for skipping content in response
limit	Number	Limit on API response to provide content in the list
order	Must be one of ['asc', 'desc', 'ASC', 'DESC']	Specify the order in which the apps should appear in the response, either ascending or descending.
sort	Must be one of ['name', 'updated_at', 'created_at']	The order in which apps are sorted.
search	String	String for search by app name
target_uid	String	Search based on stack
target_type	Must be one of ['stack','organization']	Specify whether the app you are looking for is a stack app or an organization app

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').appRequests().findAll({ skip: 10, limit: 10, order: 'asc' })

.then((response) => console.log(response));

Authorization

The authorization class defines the auth related queries of an app.

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').app('manifest_uid').authorization();

findAll

The findAll method retrieves the requests of all authorized apps in a particular organization.

Name	Type	Description
skip	Number	Offset for skipping content in response
limit	Number	Limit on API response to provide content in the list
order	Must be one of ['asc', 'desc', 'ASC', 'DESC']	Specify the order in which the apps should appear in the response, either ascending or descending.
sort	Must be one of ['name', 'updated_at', 'created_at']	The order in which apps are sorted.
search	String	String for search by app name

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});


client.marketplace('organization_uid').app('manifest_uid').authorization().findAll({ skip: 10, limit: 10, order: 'asc' })

.then((response) => console.log(response));

revokeAll

Revoke all users tokens issued to an authorized app for the particular organization.

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});


client.marketplace('organization_uid').app('manifest_uid').authorization().revokeAll()

.then((response) => console.log(response));

revoke

Revoke user token issued to an authorized app for the particular organization.

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});


client.marketplace('organization_uid').app('manifest_uid').authorization().revoke('authorization_uid')

.then((response) => console.log(response));

Installation

The installation class defined the installation related queries for the marketplace.

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').installation();

Name	Type	Description
installationUid	String	The UID of installation

fetch

The fetch method retrieves a specific installation of an app.

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').installation('installation_uid').fetch()

.then((installation) => console.log(installation));

update

The update installation call is used to update information of an installation.

Name	Type	Description
config	Object	Configuration that needs to be updated
server_config	Object	Server configuration that needs to be updated
webhooks	Array of Objects with webhook_uid and channels	Webhooks attached to the app that needs to be updated
ui_locations	Array of Object with type and meta keys	The location of the app in the UI flow that is to updated

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});


const updateInstallation = {

 name: 'APP_NAME',

 description: 'APP_DESCRIPTION',

 target_type: 'stack'/'organization',

};


const installation = client.marketplace('organization_uid').installation('installation_uid');

installation = Object.assign(installation, updateInstallation);

installation.update()

.then((installation) => console.log(installation));

uninstall

The uninstall method uninstalls the installation.

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').installation('installation_uid').uninstall()

.then((response) => console.log(response));

configuration

The configuration method retrieves the organization level app installation configuration.

import * as contentstack from '@contentstack/marketplace-sdk' 

const client = contentstack.client({ authtoken: 'TOKEN'}); 

client.marketplace('organization_uid').installation('installation_uid').configuration() 

.then((response) => console.log(response));

getConfigLocation

The getConfigLocation method retrieves the organization level app installation configuration.

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'})


client.marketplace('organization_uid').installation('installation_uid').getConfigLocation()

.then((response) => console.log(response))

setConfiguration

The setConfiguration method updates the organization level app installation configuration.

Name	Type	Description
{ / / config keys } (required)	Object	Configuration that needs to be updated

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});


client.marketplace('organization_uid').installation('installation_uid').setConfiguration()

.then((response) => console.log(response));

serverConfig

The serverConfig method retrieves the server side organization level configuration required for the app.

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').installation('installation_uid').serverConfig()

.then((response) => console.log(response));

setServerConfig

The setServerConfig method updates the server side organization level configuration required for the app.

Name	Type	Description
{ / / config keys } (required)	Object	Configuration that needs to be updated

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').installation('installation_uid').setServerConfig({<configuration_details>})

.then((response) => console.log(response));

installationData

The installationData method retrieves the installation data of an app configuration.

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').installation('installation_uid').installationData()

.then((response) => console.log(response));

webhooks

The webhooks gives a Webhook instance.

Name	Type	Description
webhook_uid (required)	String	The UID of webhook

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid')..installation('installation_uid').webhooks('webhook_uid');

fetchAll

The fetchAll method retrieves all the installations in your Contentstack organization.

Name	Type	Description
app_uids	String(comma separated)	The App UIDs of which installation need to be listed
installation_uids	String(comma separated)	Installations UID of the app
target_uids	String(comma separated)	Stack API key or organization UID
sort	String	Field to sort the results (eg. created_at, updated, at)
order	String	The order in which the response is given
limit	Number	Limit on API response to provide content in the list
skip	Number	Offset for skipping content in response

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});

client.marketplace('organization_uid').installation().fetchAll({ < optional params object>})

.then((collection) => console.log(collection));

getInstalledApps

The getInstalledApps method retrieves all the installed apps in your Contentstack organization.

Name	Type	Description
include_update_details	Boolean	To show only apps which have update
target_type	Must use one of ['stack','organization']	Specify whether your app is a stack app or an organization app
target_uids	String(comma separated)	Stack API key or organization UID
sort	String	Field to sort the results (eg. created_at, updated, at)
order	String	The order in which the response is given
limit	Number	Limit on API response to provide content in the list
skip	Number	Offset for skipping content in response

Example 1:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});


client.marketplace('organization_uid').installation().getInstalledApps()

.then((collection) => console.log(collection));

Example 2:

If you have to retrieve the list of apps installed for a specific target UID, use the following code

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});


client.marketplace('organization_uid').installation().getInstalledApps({


	target_uid: 'api_key', 


})


.then((collection) => console.log(collection));

getInstalledUsers

The getInstalledUsers call retrieves the list of users for the organization who installed the apps.

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});


client.marketplace('organization_uid').installation().getInstalledUsers()

.then((collection) => console.log(collection));

getInstalledStacks

The getInstalledStacks method retrieves the list of all the stacks a user is part of.

Example:

import * as contentstack from '@contentstack/marketplace-sdk'

const client = contentstack.client({ authtoken: 'TOKEN'});


client.marketplace('organization_uid').installation().getInstalledStacks()

.then((collection) => console.log(collection));