Welcome to Kyma-client-connector!

The kyma-client-connector helps to integrate your nodejs application with kyma by allowing you to register your application to kyma application connector with a single command, register api, register events, fetch metadata, and send events to kyma in a simplified way.

This library is in alpha stage, but it already supports the most important functionalitties of kyma application connector, there is much more to come, keep updating your library dependencies with some frequency.

Installation

In order to install kyma-client-connector, please run the command below in your project root folder:

npm i kyma-client-connector

Once the library is installed, import the library inside your project:

kymaConnector = require('kyma-client-connector');

Commands

Below are the list of commands currently supported by the library

registerApp

Register app is the first step to connect your nodejs application to kyma application connector, it will do entire flow to register your application into Kyma, create CSR request and download the certificates to be used by your application.

In order to connect your application you need to generate your signingRequest URL:

* Kyma Opensource

If using Kyma Opensource installed over your local kubernetes, over one cloud provider kubernetes implementation or over gardener, you need to go to your kyma instance -> Application System, create your application and copy the signing request url.

* Kyma Managed Runtime

If using the Kyma Runtime available as a managed service on SAP Business Technology Platform, to create your application you need to go to SAP Business Technology Platform -> Global account -> System Landscape, create your System and Formation and copy the signing request url provided.

Once you have your signing request url, run the following command to connect your application to the just created kyma application:

registration = await kymaConnector.registerApp("<signingRequestUrl>");

The response of the registerApp command will be a json containing all the information and certificates to be used, please save this response in a safe location, it will be used everytime you need to connect to your kyma application.

connectKyma

Once your application is registered, everytime you want to use your kyma application, you must connect to it. The kyma-client-connector connectKyma command will load into your library your certificates and metadata, making the library aware of which application you want to be using. The input parameter of the connectkyma command is the json object returned by the registerApp command.

await  kymaConnector.connect(JSON.parse(registration));

registerService

The registerService command is used to register your application Events and API's into kyma, it is a JSON format which will describe the services you are registering, including authentication for the API's. For more information about the Registration JSON format, please visit https://kyma-project.io/docs/components/application-connector/#tutorials-register-a-service

The kyma-client-connector will take care of signing your api calls using the certificates generated in the registerApp process and it knows the urls to be called, based on the metadata provided. The only information that needs to be provided is the json object containing your services description.

Below an example of how to call the registerService method.

jsonBody = {
	"name": "Api and Event Test",
	"provider": "example-provider",
	"Identifier": "identifier",
	"description": "This is the long description of your service",
	"events": {
		"spec": {
			"asyncapi": "2.0.0",
			"info": {
				"title": "PetStore Events",
				"version": "2.0.0",
				"description": "Description of all the events"
			},
			"channels": {
				"stage.com.some.company.system/petCreated/v1": {
					"subscribe": {
						"message": {
							"summary": "Event containing information about new pet added to the Pet Store.",
							"payload": {
								"type": "object",
								"properties": {
									"pet": {
										"type": "object",
										"required": [
											"id",
											"name"
										],
										"example": {
											"id": "4caad296-e0c5-491e-98ac-0ed118f9474e",
											"category": "mammal",
											"name": "doggie"
										},
										"properties": {
											"id": {
												"title": "Id",
												"description": "Resource identifier",
												"type": "string"
											},
											"name": {
												"title": "Name",
												"description": "Pet name",
												"type": "string"
											},
											"category": {
												"title": "Category",
												"description": "Animal category",
												"type": "string"
											}
										}
									}
								}
							}
						}
					}
				}
			}
		}
	},
	"api": {
		"targetUrl": "https://httpbin.org/",
		"spec": {},
		"requestParameters": {
			"queryParameters": {
				"param": ["bar"]
			},
			"headers": {
				"custom-header": ["foo"]
			}
		},
		"credentials": {
			"basic": {
				"username": "{USERNAME}",
				"password": "{PASSWORD}"
			}
		}
	},
	"documentation": {
		"displayName": "Documentation",
		"description": "Description",
		"type": "some type",
		"tags": ["tag1", "tag2"],
		"docs": [{
			"title": "Documentation title...",
			"type": "type",
			"source": "source"
		}]
	}
}
	
serviceId = await kymaConnector.registerService(jsonBody);

updateService

The updateService command is used to update an already existing service into Kyma, the command is similar to the registerService, the only difference is that the serviceId of the existing service must be provided.

await  kymaConnector.updateService("<serviceId>", jsonBody);

deleteService

The deleteService command is used to delete an already existing service in Kyma for an application, only the serviceId must be provided.

await  kymaConnector.deleteService("<serviceId>");

getService

The getService command is used to retrieve the details of an existing service in Kyma for an application.

jsonBody = await kymaConnector.getService("<serviceId>");

sendEvent

If your application has events registered into Kyma, you can use the sendEvent command to push data into kyma, which can trigger a lambdaFunction or service. To send event to Kyma you only need to call the sendEvent with your data in json format as the parameter.

jsonBody = {
	"event-type":  "stage.com.some.company.system.petCreated",
	"event-type-version":  "v1",
	"event-time":  "2020-01-19T15:00:00Z",
	"data": {
		"category":  "mammal",
		"id":  "4caad296-e0c5-491e-98ac-0ed118f9474e",
		"name":  "doggie"
	}
}
return  await  kymaConnector.sendEvent(jsonBody);