Bergx SDK

The offical Bergx SDK for Javascript, works on browsers, mobile devices and node.js.

Bergx is a set of modules to get you moving quickly on your next project.

• User Authentication
• Authorization
• Feature Switches
• Advanced A/B Testing

Getting Started

Create an account here: https://www.bergx.io Just follow the quick start to create an organization and an application. You will need to create a client in order to interact with the API.

npm install @bergx/bergx-sdk
# or
yarn add @bergx/bergx-sdk

Usage

const bx = new BergxSDK({
  clientId: '{{clientId}}',
  clientSecret: '{{clientSecret}}',
});

// Feature Switch example
const createRes = await bx.createSwitch({
	name: "awesome-feature",
	type: "basic",
	value: "true"
});
const awesomeFeature = await bx.checkSwitch('awesome-feature', {username: 'cool guy'});
console.log(awesomeFeature); // true

API

Documentation of the raw api can be found here: https://documenter.getpostman.com/view/1097302/SWLmW44o?version=latest

There are four basic modules provided by the Bergx SDK, User Authentication, User Authorization, Feature Switches, and Advanced A/B testing. Each module has its own section below.

Initialization

Creating a new Bergx instance

The SDK is provided in a single class and is initialized using the BxConfig type. Everything is Javascript or Typescript compatible.

Types:

BxConfig Object:

| Property | Type | Required | Explanation | | --- | --- | --- | --- | | clientId | string | true | The clientId is provided from the bergx.io console when a new client is created there. | | clientSecret | string | true | The clientSecret is provided from the bergx.io console when a new client is created there. | | host | string | false | You can specify another provider's location as long as they implement the BergxAPI | | updateAccessTokenCallback | function: (userSub: string, newAccessToken: string) => void | false | Optionally, provide a callback to update your database with a user's id aka sub and a new accessToken. |

Example:

interface BxConfig {
  clientId: string;
  clientSecret: string;
  host?: string;
  updateAccessTokenCallback?: (userSub: string, newAccessToken: string) => void;
}

const bx = new BergxSDK({
  clientId: '{{clientId}}',
  clientSecret: '{{clientSecret}}',
  host: 'https://p01.bergx.io',
  updateAccessTokenCallback: (userSub: string, newAccessToken: string) => {
    db.saveUser({userId: userSub, accessToken: newAccessToken});
  }
});

Once the SDK has been initialized with a clientId and secret most calls will automatically authenticate. But any calls to the user profile endpoints will require accessTokens that are scoped to the user rather than the client. For information on how to use the User Authentication module refer to the example project in ./examples/.

User Authentication/Profile

Types:

BxUser Object:

| Property | Type | Required | Explanation | | --- | --- | --- | --- | | accessToken | string | true | The active accessToken for a given user. | | refreshToken | string | false | The refreshToken allows you to renew an expired accessToken. |

interface BxUser {
  accessToken: string;
  refreshToken: string;
}

User Object:

| Property | Type | Required | Explanation | | --- | --- | --- | --- | | claims | BxUserClaims | true | The user profile information, generally known as claims, associated with the user. | | organizations | string[] | true | An array of IDs for organizations the user is a member of in the Bergx Console. |

interface User {
  claims: BxUserClaims;
  organizations: string[];
}

BxUserClaims Object:

BxUserClaims is based on the OpenID Connect Standard user claims object. Please refer to the OpenID Connect Claims object documentation for more details https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims.

| Property | Type | Required | Explanation | | --- | --- | --- | --- | | email | string | true | User's email. | | sub | string | true | User's id or 'sub'-scriber id. | | ... | ... | ... | ... |

All other standard claims are supported.

getProfile(user: BxUser): Promise<{status: string, user: User}>

Returns a status (string) and a User object.

Example response:

{
  "status": "success",
  "user": {
    "claims": {
      "email": "[email protected]",
      "updated_at": 1588647477,
      "preferred_username": "testUser",
      "sub": "{{uuid}}",
      "email_verified": true
    },
    "organizations": []
  }
}

Usage:

const user = await bx.getProfile({
  accessToken,
  refreshToken
});

updateProfile(user: BxUser, data: BxUserClaims)

Updates the user profile in Bergx. Requires a user's accessToken.

Example response:

{
  "status": "success",
  "user": {
    "claims": {
      "email": "[email protected]",
      "updated_at": 1588647477,
      "preferred_username": "testUser",
      "sub": "{{uuid}}",
      "email_verified": true
    },
    "organizations": []
  }
}

Usage:

const user = await bx.getProfile({
  accessToken,
  refreshToken
});