Subscription-service

This is the primary service of the control plane responsible for subscription and plan management.

Overview

A Microservice for handling subscription management operations. It provides -

• Plan creations and management - plan includes plan tier - silo/pooled
• Add or Update Plan Items/Services/Resources to Plans - plan items are the offerings to user within the selected plan.
• Plan and its feature management.
• Create or Update Subscriptions.
• Get information about expired or expiring subscriptions.
• Billing & Invoice Management.

Billing & Invoicing

We have created a package loopback4-billing that is designed to integrate billing functionality into LoopBack 4 applications. It provides an abstract layer to work with billing services such as Chargebee, Stripe etc, offering common billing operations like creating and managing customers, invoices, payment sources, and transactions. Our subscription service uses this billing package for bill settlement.

Customizing Plans with Sizes and Features

This feature allows the creation and management of plans with different sizes and features. Plans are used to represent various service tiers or options you offer to your customers. Sizes define the overall scope or capacity of a plan, while features are specific functionalities that can be enabled or disabled for each plan.

The Plan Customization feature consists of two main aspects:

• Plan Sizes: Manage different plan sizes and their configurations.
• Plan Features: Customize features associated with a specific plan.

Plan Sizes

Plan sizes are defined by the PlanSizes model. Here's a breakdown of PlanSize:

• size: The name or label of the plan size (string, required)
• config: An optional object that can hold additional configuration details specific to the plan size

For example, the “Standard” plan may include less database capacity than the “Premium” plan.

Plan Features

Uses our @sourceloop/feature-toggle-service to manage the list of features that the application plan will have.

Plan features are saved in the FeatureValues model and associated with plans using the PlanFeaturesController. Here's a breakdown of the relevant concepts:

• Feature: Represents a general capability or functionality offered in your plans.
• FeatureValues: This model associates features with specific plans and allows configuration of their values.

Installation

Install Subscription service using npm;

$ [npm install | yarn add] @sourceloop/ctrl-plane-subscription-service

Usage

• Create a new Loopback4 Application (If you don't have one already) lb4 testapp

• Install the subscription service npm i @sourceloop/ctrl-plane-subscription-service

• Set the environment variables.

• Run the migrations.

• Add the SubscriptionServiceComponent to your Loopback4 Application (in application.ts).

  // import the SubscriptionServiceComponent
  import {SubscriptionServiceComponent} from '@sourceloop/ctrl-plane-subscription-service';
  // add Component for subscription-service
  this.component(SubscriptionServiceComponent);

• If you wish to use Sequelize as the ORM, make sure to use the Sequelize-compatible components,else use the default component.

  //import like this
  import {SubscriptionSequelizeServiceComponent} from '@sourceloop/ctrl-plane-subscription-service/sequelize';
  // bind the component
  this.component(SubscriptionSequelizeServiceComponent);

This microservice uses loopback4-authentication and @sourceloop/core and that uses asymmetric token encryption and decryption by default for that setup please refer their documentation but if you wish to override -

• Install following packages npm install @sourceloop/core loopback4-authorization loopback4-authentication

• Add the following to your application.ts

  this.bind(SubscriptionServiceBindings.Config).to({
      useCustomSequence: true,
    });
    this.component(AuthenticationComponent);
    this.sequence(ServiceSequence);
    // Add bearer verifier component
    this.bind(BearerVerifierBindings.Config).to({
      type: BearerVerifierType.service,
      useSymmetricEncryption: true,
    } as BearerVerifierConfig);
    this.component(BearerVerifierComponent);
    // Add authorization component
    this.bind(AuthorizationBindings.CONFIG).to({
      allowAlwaysPaths: ['/explorer', '/openapi.json'],
    });
    this.component(AuthorizationComponent);

  comment the following since we are using our custom sequence

  // Set up the custom sequence
  //this.sequence(MySequence);

• Set up a Loopback4 Datasource with dataSourceName property set to SubscriptionDB. This component internally uses FeatureToggleServiceComponent that requires a datasource binding with the name 'FeatureToggleDB'. Make sure to create a datasource for it. You can refer an example datasource here.

• Bind any of the custom providers you need.

Integrating Billing Functionality into Subscription Service using LoopBack 4

We are leveraging the loopback4-billing package to integrate billing capabilities into our Subscription Service.

To include billing functionality, we integrate the BillingComponent into the SubscriptionServiceComponent as follows:

// import billing component from loopback4-billing
import {BillingComponent} from 'loopback4-billing';
// add Component for subscription-service component
this.application.component(BillingComponent);

We utilize the BillingProvider binding from loopback4-billing in our controllers as shown below:

// import billing component from loopback4-billing
import {BillingComponentBindings,IService} from 'loopback4-billing';
// add Component for subscription-service component
export class BillingInvoiceController {
constructor(
...
  @inject(BillingComponentBindings.BillingProvider)
  private readonly billingProvider: IService,
...
) {}
}

Depending on the billing provider, the setup process varies. Currently, we support Stripe and Chargebee.

For ChargeBee -

To use Chargebee as the billing provider, you need to configure the Chargebee API keys and site URL in your application. You can set these values in the environment variables of your LoopBack 4 project.

API_KEY=your_chargebee_api_key
SITE=your_chargebee_site_url

Next, bind these values with ChargeBeeBindings.Config and register the Chargebee provider, as shown below:

import {ChargeBeeBindings, BillingComponentBindings} from 'loopback4-billing';
import {SubscriptionServiceComponent} from '@sourceloop/ctrl-plane-subscription-service';
export class YourApplication extends BootMixin(
  ServiceMixin(RepositoryMixin(RestApplication)),
) {
  constructor(options: ApplicationConfig = {}) {
    super(options);

    // Bind the config values
    this.bind(ChargeBeeBindings.config).to({
      site: process.env.SITE ?? '',
      apiKey: process.env.API_KEY ?? '',
    });
    // Register Billing component
    this.bind(BillingComponentBindings.SDKProvider).toProvider(
      ChargeBeeServiceProvider,
    );
  }
}

For STRIPE -

To use Stripe as the billing provider, you need to configure the Chargebee API keys and site URL in your application. You can set these values in the environment variables of your LoopBack 4 project.

STRIPE_SECRET=your_stripe_secret_key

Next, bind these values with StripeBindings.Config and register the Stripe provider, as shown below:

import {StripeBindings, BillingComponentBindings} from 'loopback4-billing';
import {SubscriptionServiceComponent} from '@sourceloop/ctrl-plane-subscription-service';
export class YourApplication extends BootMixin(
  ServiceMixin(RepositoryMixin(RestApplication)),
) {
  constructor(options: ApplicationConfig = {}) {
    super(options);

    // Bind the config values
    this.bind(StripeBindings.config).to({
      secretKey: process.env.STRIPE_SECRET ?? '',
    });
    // Register Billing component
    this.bind(BillingComponentBindings.SDKProvider).toProvider(
      StripeServiceProvider,
    );
  }
}

Environment Variables

Setting up a DataSource

Here is a sample Implementation DataSource implementation using environment variables and PostgreSQL as the data source.

import {inject, lifeCycleObserver, LifeCycleObserver} from '@loopback/core';
import {juggler} from '@loopback/repository';
import {TenantManagementDbSourceName} from '@sourceloop/tenant-management-service';

const config = {
  name: SubscriptionDbSourceName,
  connector: 'postgresql',
  url: '',
  host: process.env.DB_HOST,
  port: process.env.DB_PORT,
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_DATABASE,
  schema: process.env.DB_SCHEMA,
};

@lifeCycleObserver('datasource')
export class AuthenticationDbDataSource
  extends juggler.DataSource
  implements LifeCycleObserver
{
  static dataSourceName = SubscriptionDbSourceName;
  static readonly defaultConfig = config;

  constructor(
    // You need to set datasource configuration name as 'datasources.config.Authentication' otherwise you might get Errors
    @inject(`datasources.config.${SubscriptionDbSourceName}`, {optional: true})
    dsConfig: object = config,
  ) {
    super(dsConfig);
  }
}

Below is example of a Feature Toggle datasource.

import {inject, lifeCycleObserver, LifeCycleObserver} from '@loopback/core';
import {juggler} from '@loopback/repository';
import {FeatureToggleDbName} from '@sourceloop/feature-toggle-service';

const config = {
  name: FeatureToggleDbName,
  connector: 'postgresql',
  url: '',
  host: process.env.DB_HOST,
  port: process.env.DB_PORT,
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_DATABASE,
  schema: process.env.DB_SCHEMA,
};

@lifeCycleObserver('datasource')
export class FeatureToggleDbDataSource
  extends juggler.DataSource
  implements LifeCycleObserver
{
  static dataSourceName = FeatureToggleDbName;
  static readonly defaultConfig = config;

  constructor(
    @inject('datasources.config.feature', {optional: true})
    dsConfig: object = config,
  ) {
    super(dsConfig);
  }
}

Migrations

The migrations required for this service can be copied from the service. You can customize or cherry-pick the migrations in the copied files according to your specific requirements and then apply them to the DB.

Database Schema