Package Exports

@serverless/platform-client

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@serverless/platform-client) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

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