cs-icon.svg

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');
NameTypeDescription

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.

Returns:
Type
App
NameTypeDescription

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.

Returns:
Type
Installation
NameTypeDescription

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.

Returns:
Type
AppRequest

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.

Returns:
Type
findAllApps

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.

Returns:
Type
roles
NameTypeDescription

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));

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');
NameTypeDescription

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.

Returns:
Type
App

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.

Returns:
Type
Promise
NameTypeDescription

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.

Returns:
Type
Oauth
NameTypeDescription

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.

Returns:
Type
Promise

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.

Returns:
Type
Hosting

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.

Returns:
Type
Promise
NameTypeDescription

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.

Returns:
Type
Promise
NameTypeDescription

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.

Returns:
Type
Promise
NameTypeDescription

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.

Returns:
Type
Promise

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.

Returns:
Type
Authorization

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.

Returns:
Type
Promise.<ContentstackCollection.<Installation>>

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.

Returns:
Type
Promise.<App>
NameTypeDescription

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.

Returns:
Type
Promise.<AppOAuth>

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.

Returns:
Type
Promise.<AppOAuth>

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.

Returns:
Type
Promise.<AppOAuth>

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.

Returns:
Type
Promise.<AppOAuth>

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.

Returns:
Type
Promise.<Response>

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.

Returns:
Type
Promise.<Response>

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.

Returns:
Type
Promise.<Response>

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.

Returns:
Type
Promise.<Deployment>

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.

Returns:
Type
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.

Returns:
Type
Promise.<Deployment>
NameTypeDescription

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.

Returns:
Type
Promise.<Response>
NameTypeDescription

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.

Returns:
Type
Promise.<Deployment>

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.

Returns:
Type
Promise.<ContentstackCollection>

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.

Returns:
Type
Promise
NameTypeDescription

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.

Returns:
Type
Promise
NameTypeDescription

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.

Returns:
Type
Promise
NameTypeDescription

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.

Returns:
Type
Promise.<Response>
NameTypeDescription

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.

Returns:
Type
Promise.<Response>

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.

Returns:
Type
Promise.<Response>

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();
NameTypeDescription

installationUid

String

The UID of installation

fetch

The fetch method retrieves a specific installation of an app.

Returns:
Type
Promise.<Installation>

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.

Returns:
Type
Promise.<Installation>
NameTypeDescription

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.

Returns:
Type
Promise.<Response>

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.

Returns:
Type
Promise.<Response>
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.

Returns:
Type
Promise.<Response>
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.

Returns:
Type
Promise.<Response>
NameTypeDescription

{ / / 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.

Returns:
Type
Promise.<Response>
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.

Returns:
Type
Promise.<Response>
NameTypeDescription

{ / / 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.

Returns:
Type
Promise.<Response>
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.

Returns:
Type
WebHooks
NameTypeDescription

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.

Returns:
Type
Promise.<ContentstackCollection.<Installation>>
NameTypeDescription

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.

Returns:
Type
Promise.<ContentstackCollection.<Installation>>
NameTypeDescription

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:

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

getInstalledUsers

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

Returns:
Type
Promise.<ContentstackCollection.<Installation>>

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.

Returns:
Type
Promise.<ContentstackCollection.<Installation>>

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));