@serverless/platform-client

What is @serverless/platform-client?

@serverless/platform-client is an npm package that provides a client for interacting with the Serverless Platform. It allows users to manage and deploy serverless applications, interact with the Serverless Framework Dashboard, and access various services provided by the Serverless Platform.

What are @serverless/platform-client's main functionalities?

Initialize the client

This code initializes the Serverless SDK client, which is the starting point for interacting with the Serverless Platform.

const { ServerlessSDK } = require('@serverless/platform-client');
const sdk = new ServerlessSDK();

Login to the Serverless Platform

This code demonstrates how to log in to the Serverless Platform using the SDK. This is necessary for performing authenticated operations.

const { ServerlessSDK } = require('@serverless/platform-client');
const sdk = new ServerlessSDK();
(async () => {
  await sdk.login();
})();

Deploy a service

This code demonstrates how to deploy a service to the Serverless Platform. It requires the user to be logged in and provides details about the organization, application, service, and stage.

const { ServerlessSDK } = require('@serverless/platform-client');
const sdk = new ServerlessSDK();
(async () => {
  await sdk.login();
  const result = await sdk.deploy({
    orgName: 'your-org',
    appName: 'your-app',
    serviceName: 'your-service',
    stageName: 'dev',
    inputs: {}
  });
  console.log(result);
})();

List services

This code demonstrates how to list all services within a specific organization. It requires the user to be logged in and provides the organization name.

const { ServerlessSDK } = require('@serverless/platform-client');
const sdk = new ServerlessSDK();
(async () => {
  await sdk.login();
  const services = await sdk.listServices({ orgName: 'your-org' });
  console.log(services);
})();

Other packages similar to @serverless/platform-client

aws-sdk

The AWS SDK for JavaScript provides a comprehensive set of tools for interacting with AWS services. It is more general-purpose compared to @serverless/platform-client, which is specifically designed for the Serverless Platform. The AWS SDK supports a wide range of AWS services and is suitable for users who need to interact with AWS directly.

google-cloud

The Google Cloud Client Library for Node.js provides tools for interacting with Google Cloud services. Similar to the AWS SDK, it is more general-purpose and supports a wide range of Google Cloud services. It is suitable for users who need to interact with Google Cloud directly, whereas @serverless/platform-client is focused on the Serverless Platform.

azure-sdk-for-js

The Azure SDK for JavaScript provides tools for interacting with Azure services. It is a comprehensive library for managing Azure resources and services. Like the AWS and Google Cloud SDKs, it is more general-purpose and supports a wide range of Azure services, while @serverless/platform-client is focused on the Serverless Platform.

README

Serverless Platform Client SDK

This light-weight SDK is designed to be used anywhere (CLI, Front-End, Back-End Services, etc.) and make it easy to interact with the Serverless Platform and perform operations on it. It's really just a wrapper around the Serverless Platform Services, with great documentation so that you can better understand how its APIs work.

Quick-Start

Install the Serverless Platform Client SDK via NPM.

npm i @serverless/platform-client

If you are working with the dev environment of the Serverless Platform, set the following environment variable, or configure the client programmatically, as detailed below.

export SERVERLESS_PLATFORM_STAGE=dev

Here is how you require, instantiate the Client and use it:

const { ServerlessClient } = require('@serverless/platform-client')

client = new ServerlessClient({
  platformStage: 'dev',  // Optional.  Defaults to 'prod'
  accessKey: 'JA98JAJFASLFJSALFJASLFJ', // Optional, but recommended.  Platform Access Key needed to identify all requests.
})

const instances = await client.listInstances('my-org')

ServerlessClient

The Serverless Platform Client SDK Class

Kind: global class

• ServerlessClient
  • new ServerlessClient(config)
  • .config() ⇒ null
  • .getDomain(serviceName) ⇒ string
  • .connect() ⇒ null
  • .disconnect() ⇒ null
  • .isConnected() ⇒ boolean
  • .publish() ⇒ null
  • .getComponent(componentName, componentVersion) ⇒ object
  • .prePublish(orgName, orgUid, componentDefinition)
  • .getInstance(orgName, orgUid, appName, stageName, instanceName)
  • .listInstances(orgName, orgUid)
  • .saveInstance(instance)
  • .getUploadUrls(orgName, orgUid)
  • .run()
  • .runPolling()

new ServerlessClient(config)

Accepts a configuration block. See the config() method for more information.

Param	Type
config	object

serverlessClient.config() ⇒ null

Updates the SDK configuration

Kind: instance method of ServerlessClient

Param	Type	Description
config.accessKey	object	Can either be a Serverless Platform Access Key or an ID Token.
config.platformStage	object	The Serverless Platform Stage you wish to interact with.

serverlessClient.getDomain(serviceName) ⇒ string

Gets a domain for a specific service: "engine", "registry", "events-streaming"

Kind: instance method of ServerlessClient
Returns: string - The domain of that service.

Param	Type	Default	Description
serviceName	string	null	The name of the Serverless Platform Service you want the domain for.

serverlessClient.connect() ⇒ null

Establishes a websockets connection with the Serverless Platform

Kind: instance method of ServerlessClient

Param	Type	Description
options.org	string	Name of the Serverless Platform Org.
options.onEvent	function	A function that handles events recieved from the Serverless Platform
options.filter	function	Filters which events this connection should receive

serverlessClient.disconnect() ⇒ null

Disconnects a websockets connection with the Serverless Platform

Kind: instance method of ServerlessClient

serverlessClient.isConnected() ⇒ boolean

Checks if the SDK is currently connected to the Serverless Platform

Kind: instance method of ServerlessClient
Returns: boolean - Will return true if the websocket connection is active.

serverlessClient.publish() ⇒ null

Publishes a Serverless Platform Event

Kind: instance method of ServerlessClient

serverlessClient.getComponent(componentName, componentVersion) ⇒ object

Get Component

Kind: instance method of ServerlessClient
Returns: object - Returns a Component definition from the Registry.

Param	Type	Default	Description
componentName	*		The name of the Component within the Registry.
componentVersion	*		The version of a specific Component within the Registry. If this is not included, this method will always return the latest version.

serverlessClient.prePublish(orgName, orgUid, componentDefinition)

Pre-Publish Component

Kind: instance method of ServerlessClient

Param	Type	Description
orgName	*	// Optional. Must include either orgName or orgUid.
orgUid	*	// Optional. Must include either orgName or orgUid.
componentDefinition	*	// serverless.component.yml

serverlessClient.getInstance(orgName, orgUid, appName, stageName, instanceName)

Get Instance

Kind: instance method of ServerlessClient

Param	Type	Default	Description
orgName	*		Optional. Must include either orgName or orgUid.
orgUid	*		Optional. Must include either orgName or orgUid.
appName	*		Required. The name of the Application the Instance is within.
stageName	*		Required. The name of the Stage the Instance is within.
instanceName	*		Required. The name of the Instance.

serverlessClient.listInstances(orgName, orgUid)

List all Component Instances within an Org, given an org name or org UId

Kind: instance method of ServerlessClient

Param	Type	Default	Description
orgName	*		Optional. Must include either orgName or orgUid.
orgUid	*		Optional. Must include either orgName or orgUid.

serverlessClient.saveInstance(instance)

Save Instance

Kind: instance method of ServerlessClient

Param	Type	Description
instance	object	An object representing your Instance definition.

serverlessClient.getUploadUrls(orgName, orgUid)

Get the upload URLs needed to upload source code before an Instance is run.

Kind: instance method of ServerlessClient

Param	Type	Default	Description
orgName	*		Optional. Must include either orgName or orgUid.
orgUid	*		Optional. Must include either orgName or orgUid.

serverlessClient.run()

Run a method of an Instance (e.g. 'deploy', 'remove', etc.)

Kind: instance method of ServerlessClient

Param	Type	Description
data.instance	object	The Instance definition.
data.method	string	The method you wish to run on the Instance (e.g. deploy, remove).
data.credentials	object	The credentials of the cloud providers required by the Instance.
data.options	object	Any options you wish to supply the Instance method.
data.size	number	The size in bytes of the source code, so that the Instance method can validate it beforehand.

serverlessClient.runPolling()

Run a method of an Instance (e.g. 'deploy', 'remove', etc.)

Kind: instance method of ServerlessClient

Param	Type	Description
data.instance	object	The Instance definition.
data.method	string	The method you wish to run on the Instance (e.g. deploy, remove).
data.credentials	object	The credentials of the cloud providers required by the Instance.
data.options	object	Any options you wish to supply the Instance method.
data.size	number	The size in bytes of the source code, so that the Instance method can validate it beforehand.

F.A.Q.

How do I update the documentation?

Before publishing the client, be sure to update it's documentation by running: npm run docs within the client folder.

Why is this separate from serverless/platform-sdk?

The reason this is kept in a separate library is because this SDK needs to be extremely light-weight, since it is used in back-end services built on AWS Lambda, as well as packaged into the Lambda Layer that is included within every Component Function in the Serverless Registry. The original Platform SDK contains many heavy NPM dependencies, increasing the overall package size, and slowing down the performance of any Lambda functions that use it.

---

© Serverless Inc.