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.

serverlessSDK.config() ⇒ null

Updates the SDK configuration

Kind: instance method of ServerlessSDK

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

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.

serverlessSDK.connect() ⇒ null

Establishes a websockets connection with the Serverless Platform

Kind: instance method of ServerlessSDK

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

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.

serverlessSDK.getComponent(componentName, componentVersion) ⇒ object

Get Component

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

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

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

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.

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

serverlessSDK.listInstances(orgName, orgUid)

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

Kind: instance method of ServerlessSDK

serverlessSDK.run()

Run

Kind: instance method of ServerlessSDK

serverlessSDK.runFinish(method, instanceData)

Run Finish

Kind: instance method of ServerlessSDK

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.