Symeo JS SDK

The Symeo SDK made for interacting with your Symeo secrets and configuration from JavaScript or TypeScript applications.

Table of Contents

• Install
• Usage
• Symeo CLI options

Install

NPM

npm install symeo-js --save 

Yarn

yarn add symeo-js

Usage

Define configuration contract

Create a symeo.config.yml file in the root of your project, and define the structure and types of your application configuration.

For example:

database:
  host:
    type: string
  port:
    type: integer
  username:
    type: string
  password:
    type: string
    secret: true

• You can nest properties to any depth level
• Supported types are boolean, string, integer and float
• Properties can be flagged with optional: true, or secret: true

Build your configuration to access it in your code

You can add a build configuration command to your package.json:

{
  "scripts": {
    "build:config": "symeo-js build"
  }
}

And then run npm run build:config or yarn build:config

Use your configuration anywhere in your code

Your configuration is then accessible with the import:

import { config } from '@symeo-sdk';

Or using require:

const { config } = require('@symeo-sdk');

For example:

import { config } from '@symeo-sdk';
import { Client } from "postgres";

export class DatabaseClient {
  private client: Client;

  constructor() {
    this.client = new Client({
      host: config.database.host,
      port: config.database.port,
      username: config.database.username,
      password: config.database.password,
    })
  }
}

Create your local configuration file

Create a symeo.local.yml file in the root of your project, defining the values matching your configuration contract.

For example:

database:
  host: "localhost"
  port: 5432
  username: "postgres"
  password: "XPJc5qAbQcn77GWg"

Wrap your application startup with the symeo command

This will trigger the rebuild of you configuration at each statup and inject values into your runtime.

In your package.json, replace for example:

{
  "scripts": {
    "start": "node dist/index.js"
  }
}

with:

{
  "scripts": {
    "start": "symeo-js start -- node dist/index.js"
  }
}

Or, directly from the command line:

node_modules/.bin/symeo-js start -- node dist/index.js

Start application with configuration from Symeo platform

After creating an environment and its api key in the Symeo platform, use this command in your package.json

symeo-js start --api-key $YOUR_ENVIRONMENT_API_KEY -- node index.js

Or, directly from the command line:

node_modules/.bin/symeo-js start --api-key $YOUR_ENVIRONMENT_API_KEY -- node index.js

So the sdk fetch the values for the given environment and starts your application with those values.

Follow the Symeo platform documentation for more details.

Check your configuration is valid

In your CI or CD pipeline, run:

symeo-js validate --api-key $YOUR_ENVIRONMENT_API_KEY

Which will check if the values filled in the Symeo platform comply with your contract.

Symeo CLI commands

symeo-js build

Build your typescript types from your contract file.

-c, --contract-file

The path to your configuration contract file. Default is symeo.config.yml.

-r, --force-recreate

By default, if contract stays identical, configuration won't be rebuilt to save time. Passing this option will force the rebuild of your configuration.

symeo-js start

Start your application with your configuration values, either read from a local file or fetched from the Symeo platform.

-c, --contract-file

The path to your configuration contract file. Default is symeo.config.yml.

-f, --values-file

The path to your local values file. Default is symeo.local.yml.

-k, --api-key

The environment api key to use to fetch values from Symeo platform. If empty, values will be fetched from local value file (symeo.local.yml by default). If specified, parameter -f, --values-file is ignored.

-a, --api-url

The api endpoint used to fetch your configuration with the api key. Default is https://api.symeo.io/api/v1/values.

-r, --force-recreate

By default, if contract stays identical, configuration won't be rebuilt to save time. Passing this option will force the rebuild of your configuration.

symeo-js validate

Check that with your configuration values, either read from a local file or fetched from the Symeo platform, match your contract.

-c, --contract-file

The path to your configuration contract file. Default is symeo.config.yml.

-f, --values-file

The path to your local values file. Default is symeo.local.yml.

-k, --api-key

The environment api key to use to fetch values from Symeo platform. If empty, values will be fetched from local value file (symeo.local.yml by default). If specified, parameter -f, --values-file is ignored.

-a, --api-url

The api endpoint used to fetch your configuration with the api key. Default is https://api.symeo.io/api/v1/values.