@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 Serverless Platform Client SDK makes it easy to interact with the Serverless Platform and perform operations on it.

The SDK is light-weight, so that it can be used in the following: CLIs, Dashboards, Back-End Services, FaaS Layers. Please do not add any Node.js dependencies to this SDK, especially heavy ones.

This SDK should guide the interface design between Services and Clients. All Clients and Services must use the SDK and should never hardcode API endpoints or FaaS resources identifiers.

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

ServerlessSDK

The Serverless Platform SDK Class

Kind: global class

• ServerlessSDK
  • new ServerlessSDK(config)
  • .config() ⇒ null
  • .login([orgName], [orgUid])
  • .getDomain(serviceName) ⇒ string
  • .connect() ⇒ null
  • .disconnect() ⇒ null
  • .isConnected() ⇒ boolean
  • .publish() ⇒ null
  • .publishSync() ⇒ null
  • .createComponent(orgName, componentName)
  • .publishComponent(componentDefinition) ⇒ object
  • .getComponent(componentName, componentVersion) ⇒ object
  • .generateInstanceId(orgName, stageName, appName, instanceName) ⇒ object
  • .validateInstance(instanceToValidate) ⇒ object
  • .createInstance(orgName, stageName, appName, instanceName) ⇒ object
  • .getInstance(orgName, stageName, appName, instanceName)
  • .listInstances(orgName, orgUid)
  • .run()
  • .runFinish(method, instanceData)
  • .deploy()
  • .remove()

new ServerlessSDK(config)

Creates an instance of the SDK. Accepts a configuration object. See the config() method for more information on allowed configuration.

Param	Type
config	object

serverlessSDK.config() ⇒ null

Updates the SDK configuration

Kind: instance method of ServerlessSDK

Param	Type	Description
[config.accessKey]	string	Can either be a Serverless Platform Access Key or an ID Token.
[config.platformStage]	string	The Serverless Platform Stage you wish to interact with. This can also be set by the environment variable SERVERLESS_PLATFORM_STAGE=
[context.orgName]	string	The name of the Serverless Platform Organization you wish to interact with. If set, this value is used upon creating a Websockets connection, and auto-added to every Event you publish.
[context.orgUid]	string	The ID of the Serverless Platform Organization you wish to interact with. If set, this value is used upon creating a Websockets connection, and auto-added to every Event you publish.
[context.stageName]	string	The Serverless Platform Organization Stage you wish to interact with. If set, this value is auto-added to every Event you publish.
[context.appName]	string	The Serverless Platform Application you wish to interact with. If set, this value is auto-added to every Event you publish.
[context.instanceName]	string	The Serverless Platform Instance you wish to interact with. If set, this value is auto-added to every Event you publish.
[context.componentName]	string	The Serverless Platform Component you wish to interact with. If set, this value is auto-added to every Event you publish.
[context.componentVersion]	string	The Serverless Platform Component version you wish to interact with. If set, this value is auto-added to every Event you publish.

Example

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

  const sdk = new ServerlessSDK()
  const sdk.config({
    accessKey: '123456789',
    context: {
      orgName: 'my-org',
      orgUid: '1234',
      stageName: 'prod',
      appName: 'my-app',
      instanceName: 'my-instance'
    }
  })

serverlessSDK.login([orgName], [orgUid])

[WIP] Logs users into the Serverless Platform. It opens up a browser to start the login process. This does not return anything. Instead, it opens up a browser to start the login process, creates credentials, then saves them in the current user's root folder, and then automatically configureds the SDK with those credentials.

Kind: instance method of ServerlessSDK

Param	Type	Description
[orgName]	string	The name of the Serverless Platform Organization you wish to log into.
[orgUid]	string	The UID of the Serverless Platform Organization you wish to log into.

serverlessSDK.getDomain(serviceName) ⇒ string

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

Kind: instance method of ServerlessSDK
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.

serverlessSDK.connect() ⇒ null

Establishes a websockets connection with the Serverless Platform

Kind: instance method of ServerlessSDK

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

serverlessSDK.disconnect() ⇒ null

Disconnects a websockets connection with the Serverless Platform

Kind: instance method of ServerlessSDK

serverlessSDK.isConnected() ⇒ boolean

Checks if the SDK is currently connected to the Serverless Platform

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

serverlessSDK.publish() ⇒ null

Publishes a Serverless Platform Event via Websockets. The use-case for this is asynchronous publishing, where you do not want to synchronous auth requests, where every message must be authorized first, adding latency.

Kind: instance method of ServerlessSDK

serverlessSDK.publishSync() ⇒ null

Publishes a Serverless Platform Event via HTTP API. The use-case for this is synchronous publishing, where you do not want to open a websockets connection.

Kind: instance method of ServerlessSDK

serverlessSDK.createComponent(orgName, componentName)

Returns a new Component as a Javascript object.

Kind: instance method of ServerlessSDK

Param	Type	Default	Description
orgName	*		The name of the Serverless Platform Organization.
componentName	*		The name of the Serverless Platform Stage.

serverlessSDK.publishComponent(componentDefinition) ⇒ object

This method publishes a Component to the Serverless Platform Registry. This method accepts a Component Definition (e.g. serverless.component.yml) as an object. In the Component Definition, it looks at the "main" property to find the path to the Component source directory. Then it collects that directory, adds in the special Component Handler, and packages everything into a zip file. After that, it fetches secure upload URLs and uploads the Component to the Serverless Registry. Once a Component has been uploaded to the Registry, the Registry must do some background processing to publish it, while that's happening, this method polls the API to see when the Component is finished being processed, and then returns the published definition.

Kind: instance method of ServerlessSDK
Returns: object - The published Component definition is returned from the Platform API.

Param	Type	Description
componentDefinition	*	An object containing the properties of a Component.

serverlessSDK.getComponent(componentName, componentVersion) ⇒ object

Get Component

Kind: instance method of ServerlessSDK
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.

serverlessSDK.generateInstanceId(orgName, stageName, appName, instanceName) ⇒ object

Returns a properly formatted ID for an Instance

Kind: instance method of ServerlessSDK
Returns: object - Returns a properly formatted ID for an Instance

Param	Type	Default	Description
orgName	*		The name of the Serverless Platform Organization.
stageName	*		The name of the Serverless Platform Stage.
appName	*		The name of the Serverless Platform Application.
instanceName	*		The name of the Serverless Platform Instance.

serverlessSDK.validateInstance(instanceToValidate) ⇒ object

Validates the properties of an Instance, as well as auto-corrects shortened syntax (e.g. org => orgName)

Kind: instance method of ServerlessSDK
Returns: object - Returns a validated, formatted version of the Instance

Param	Type	Description
instanceToValidate	*	The Serverless Platform Instance you want to validate.

serverlessSDK.createInstance(orgName, stageName, appName, instanceName) ⇒ object

Returns a new Instance as a Javascript object.

Kind: instance method of ServerlessSDK
Returns: object - Returns a new Instance definition as a Javascript Object.

Param	Type	Default	Description
orgName	*		The name of the Serverless Platform Organization.
stageName	*		The name of the Serverless Platform Stage.
appName	*		The name of the Serverless Platform Application.
instanceName	*		The name of the Serverless Platform Instance.

serverlessSDK.getInstance(orgName, stageName, appName, instanceName)

Get an Instance from the Serverless Platform by it's name and the names of its Organization, Stage, Application.

Kind: instance method of ServerlessSDK

Param	Type	Default	Description
orgName	*		The name of the Serverless Platform Organization.
stageName	*		The name of the Serverless Platform Stage.
appName	*		The name of the Serverless Platform Application.
instanceName	*		The name of the Serverless Platform Instance.

serverlessSDK.listInstances(orgName, orgUid)

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

Kind: instance method of ServerlessSDK

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

serverlessSDK.run()

Run

Kind: instance method of ServerlessSDK

serverlessSDK.runFinish(method, instanceData)

Run Finish

Kind: instance method of ServerlessSDK

Param	Type	Default	Description
method	string	null	The action that was performed on the Component.
instanceData	object		An object representing your Instance definition.

serverlessSDK.deploy()

Performs a "deploy" action and polls the "getInstance" endpoint until its "instanceStatus" reflects a successful deployment, or error.

Kind: instance method of ServerlessSDK

serverlessSDK.remove()

Performs a "remove" action and polls the "getInstance" endpoint until its "instanceStatus" reflects a successful deployment, or error.

Kind: instance method of ServerlessSDK

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.