@hsuite/subscriptions

A comprehensive NestJS module for managing Web3-based subscription systems with multi-blockchain support, providing subscription issuance, token gating, activity logging, and payment processing capabilities.

Features

🌐 Multi-Blockchain Support

• Hedera Hashgraph integration via HashgraphSubscriptionsHandler
• XRP Ledger integration via RippleSubscriptionsHandler
• Unified ledger plugin architecture for easy blockchain extension
• Cross-chain subscription management

🔐 Web3 Integration

• Subscription NFT Issuance: Mint subscription NFTs with configurable plans and billing cycles
• Token Gating: Access control based on NFT ownership and subscription status
• Smart Contract Integration: Direct blockchain interaction for subscription operations
• Transaction Management: Offline transaction generation and execution

📊 Subscription Management

• Lifecycle Management: Complete subscription creation, activation, renewal, and termination
• Plan Configuration: Flexible subscription plans with multiple billing periodicities
• Access Validation: Real-time subscription status and access rights verification
• Operator Integration: SmartApp operator activation and management

💳 Payment Processing

• Multi-Token Support: Accept payments in various cryptocurrencies
• Plan Changes: Dynamic subscription plan upgrades and downgrades
• Payment Method Configuration: Flexible payment options and pricing
• Transaction Tracking: Complete payment history and analytics

📈 Analytics & Monitoring

• Activity Logging: Comprehensive blockchain activity tracking
• Subscription Analytics: Usage metrics and subscription performance data
• Payment Analytics: Revenue tracking and payment success rates
• Real-time Monitoring: WebSocket-based real-time updates

⚡ Background Processing

• Redis-based Job Queue: Scalable background task processing
• Configurable Retry Policies: Robust error handling and retry mechanisms
• Asynchronous Operations: Non-blocking subscription operations
• Event-driven Architecture: Real-time event processing and notifications

Installation

npm install @hsuite/subscriptions

Dependencies

Core Dependencies

• @nestjs/common: ^10.4.2
• @nestjs/core: ^10.4.2
• @nestjs/bull: Redis-based job queue processing
• @nestjs/jwt: JWT authentication support

HSuite Ecosystem Dependencies

• @hsuite/subscriptions-types: ^2.1.1 - Type definitions and interfaces
• @hsuite/smart-config: ^2.1.1 - Configuration management
• @hsuite/hashgraph-types: ^2.0.3 - Hedera Hashgraph type definitions
• @hsuite/smart-transaction-types: ^2.0.0 - Transaction type definitions
• @hsuite/helpers: ^2.0.8 - Utility functions and helpers
• @hsuite/auth-types: ^2.1.2 - Authentication type definitions
• @hsuite/client: ^2.1.3 - HSuite client library
• @hsuite/nestjs-swagger: ^1.0.3 - Enhanced Swagger documentation

Architecture Overview

src/
├── entities/                    # Database entities
│   ├── subscription/           # Subscription entity definitions
│   ├── payments/              # Payment entity definitions
│   └── analytics/             # Analytics entity definitions
├── interfaces/                 # TypeScript interfaces and types
│   └── subscription-options.interface.ts
├── ledgers/                   # Blockchain integration layer
│   ├── ledger.plugin.ts      # Main ledger plugin abstraction
│   └── plugins/              # Chain-specific implementations
│       ├── hashgraph.plugin.ts
│       └── ripple.plugin.ts
├── models/                    # Data models and services
│   ├── analytics/            # Analytics model services
│   ├── payments/             # Payment model services
│   └── subscription/         # Subscription model services
├── web3/                     # Web3 functionality modules
│   ├── issuer/              # Subscription NFT issuance
│   │   ├── issuer.controller.ts
│   │   ├── issuer.service.ts
│   │   ├── issuer.consumer.ts
│   │   ├── issuer.validator.ts
│   │   ├── issuer.events.ts
│   │   └── issuer.gateway.ts
│   ├── logger/              # Activity logging and monitoring
│   │   ├── logger.controller.ts
│   │   ├── logger.service.ts
│   │   └── guards/
│   └── token-gate/          # Access control and token gating
│       ├── tokengate.service.ts
│       └── guards/
├── subscriptions.module.ts   # Main module configuration
├── subscriptions.service.ts  # Core subscription service
└── index.ts                 # Public API exports

Usage

Basic Module Configuration

import { Module } from '@nestjs/common';
import { SubscriptionsModule } from '@hsuite/subscriptions';
import { ConfigModule, ConfigService } from '@nestjs/config';

@Module({
  imports: [
    SubscriptionsModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: (config: ConfigService) => ({
        subscription: {
          issuer: {
            enabled: true,
            options: {
              token: {
                id: config.get('SUBSCRIPTION_TOKEN_ID')
              }
            }
          },
          utilities: {
            refreshInterval: 3600 // 1 hour
          }
        },
        bull: {
          redis: {
            socket: {
              host: config.get('REDIS_HOST'),
              port: config.get('REDIS_PORT')
            },
            password: config.get('REDIS_PASSWORD'),
            username: config.get('REDIS_USERNAME'),
            database: config.get('REDIS_DATABASE')
          },
          defaultJobOptions: {
            attempts: 3,
            backoff: { 
              type: 'exponential', 
              delay: 1000 
            }
          }
        }
      }),
      inject: [ConfigService],
      jwt: {
        secret: config.get('JWT_SECRET'),
        signOptions: { expiresIn: '24h' }
      },
      enableIssuer: true,
      enableTokenGate: true
    })
  ]
})
export class AppModule {}

Advanced Multi-Chain Configuration

SubscriptionsModule.forRootAsync({
  imports: [ConfigModule, SmartLedgersModule],
  useFactory: async (config: ConfigService, ledgers: SmartLedgersService) => ({
    subscription: {
      issuer: {
        enabled: true,
        options: {
          token: {
            id: config.get('SUBSCRIPTION_TOKEN_ID'),
            network: config.get('BLOCKCHAIN_NETWORK') // 'hashgraph' or 'ripple'
          },
          plans: {
            basic: {
              price: new Decimal(10),
              features: ['feature1', 'feature2']
            },
            premium: {
              price: new Decimal(25),
              features: ['feature1', 'feature2', 'feature3']
            }
          }
        },
        utilities: {
          refreshInterval: 1800, // 30 minutes
          maxRetries: 5
        }
      },
      tokenGate: {
        enabled: true,
        requireActiveSubscription: true,
        gracePeriodDays: 7
      }
    },
    bull: {
      redis: {
        socket: {
          host: config.get('REDIS_HOST'),
          port: parseInt(config.get('REDIS_PORT')),
        },
        password: config.get('REDIS_PASSWORD'),
        username: config.get('REDIS_USERNAME'),
        database: parseInt(config.get('REDIS_DATABASE'))
      },
      defaultJobOptions: {
        attempts: 5,
        backoff: { 
          type: 'exponential', 
          delay: 2000 
        },
        removeOnComplete: 100,
        removeOnFail: 50
      }
    }
  }),
  inject: [ConfigService, SmartLedgersService],
  jwt: {
    secret: config.get('JWT_SECRET'),
    signOptions: { expiresIn: '24h' }
  },
  enableIssuer: true,
  enableTokenGate: true
})

Using the Subscription Service

import { Injectable } from '@nestjs/common';
import { SubscriptionsService } from '@hsuite/subscriptions';

@Injectable()
export class MyService {
  constructor(private subscriptionsService: SubscriptionsService) {}
  
  async checkUserAccess(userId: string): Promise<boolean> {
    // The service provides the foundation for subscription operations
    // Specific implementations would be added based on business requirements
    return true; // Placeholder - implement based on your needs
  }
}

Using Web3 Issuer Service

import { Injectable } from '@nestjs/common';
import { SubscriptionsWeb3IssuerService } from '@hsuite/subscriptions';
import { ISubscription } from '@hsuite/subscriptions-types';

@Injectable()
export class SubscriptionManager {
  constructor(
    private issuerService: SubscriptionsWeb3IssuerService
  ) {}

  async createSubscription(
    userSession: any,
    plan: ISubscription.IPlan,
    periodicity: ISubscription.IPeriodicity
  ) {
    // Generate subscription request transaction
    const transaction = await this.issuerService.subscribeRequest(
      userSession, 
      plan, 
      periodicity
    );
    
    return transaction;
  }

  async getAvailablePlans() {
    return await this.issuerService.getAllPlans();
  }

  async getPaymentMethods() {
    return await this.issuerService.getPaymentMethods();
  }
}

Using Token Gate Guards

import { Controller, Get, UseGuards } from '@nestjs/common';
import { SubscriptionTokenGateGuard } from '@hsuite/subscriptions';

@Controller('protected')
export class ProtectedController {
  
  @Get('premium-content')
  @UseGuards(SubscriptionTokenGateGuard)
  async getPremiumContent() {
    // This endpoint requires an active subscription
    return { message: 'Premium content accessible only to subscribers' };
  }
}

Using Ledger Plugin for Multi-Chain Operations

import { Injectable } from '@nestjs/common';
import { SubscriptionsLedgerPlugin } from '@hsuite/subscriptions';
import Decimal from 'decimal.js';

@Injectable()
export class PaymentService {
  constructor(
    private ledgerPlugin: SubscriptionsLedgerPlugin
  ) {}

  async processSubscriptionPayment(
    tokenId: string,
    fromAccount: string,
    toAccount: string,
    amount: Decimal,
    memo: string
  ) {
    // Works across Hashgraph and Ripple networks
    const transactionBytes = await this.ledgerPlugin.paySubscriptionRequest(
      tokenId,
      fromAccount,
      toAccount,
      amount,
      memo
    );
    
    return transactionBytes;
  }
}

API Endpoints

The module exposes a comprehensive REST API for subscription management:

Subscription Plans

• GET /subscriptions/web3/plans - Get all available subscription plans
• GET /subscriptions/web3/payment-methods - Get payment method configuration

Subscription Operations

• GET /subscriptions/web3/subscribe/request - Generate subscription NFT minting transaction
• POST /subscriptions/web3/subscribe/execute - Execute subscription NFT minting
• PATCH /subscriptions/web3/activate/:serialNumber/:operatorId - Activate subscription with operator

Subscription Management

• GET /subscriptions/web3/:serialNumber - Get subscription details
• PATCH /subscriptions/web3/:serialNumber/renew - Renew subscription
• DELETE /subscriptions/web3/:serialNumber - Cancel subscription
• PATCH /subscriptions/web3/:serialNumber/change-plan - Change subscription plan

Activity Logging

• GET /subscriptions/web3/logger/activities - Get subscription activities
• POST /subscriptions/web3/logger/log - Log custom activity

WebSocket Events

Real-time subscription updates via WebSocket:

// Client-side WebSocket connection
const socket = io('/subscriptions');

// Listen for subscription events
socket.on('subscription:created', (data) => {
  console.log('New subscription created:', data);
});

socket.on('subscription:activated', (data) => {
  console.log('Subscription activated:', data);
});

socket.on('subscription:renewed', (data) => {
  console.log('Subscription renewed:', data);
});

socket.on('payment:processed', (data) => {
  console.log('Payment processed:', data);
});

Background Jobs

The module uses Bull queues for background processing:

Available Queues

• Subscription Processing: Handles subscription lifecycle operations
• Payment Processing: Manages payment transactions and validations
• Analytics Processing: Processes subscription and payment analytics
• Notification Processing: Sends subscription-related notifications

Job Types

• subscription:mint - Process subscription NFT minting
• subscription:activate - Handle subscription activation
• subscription:renew - Process subscription renewals
• payment:process - Handle payment transactions
• analytics:update - Update subscription analytics

Configuration Options

Subscription Configuration

interface ISubscriptionConfig {
  issuer: {
    enabled: boolean;
    options: {
      token: {
        id: string;
        network?: string;
      };
      plans?: Record<string, IPlanConfig>;
    };
    utilities: {
      refreshInterval: number;
      maxRetries?: number;
    };
  };
  tokenGate?: {
    enabled: boolean;
    requireActiveSubscription: boolean;
    gracePeriodDays?: number;
  };
}

Redis Configuration

interface IRedisConfig {
  socket: {
    host: string;
    port: number;
  };
  password?: string;
  username?: string;
  database?: number;
}

Development

Running Tests

# Unit tests
npm run test

# E2E tests
npm run test:e2e

# Test coverage
npm run test:cov

Documentation Generation

Generate comprehensive documentation using Compodoc:

# Generate documentation
npm run compodoc

# Generate documentation with coverage report
npm run compodoc:coverage

Building the Library

# Build the library
npm run build

# Build with watch mode
npm run build:watch

Version History

• v2.1.7 (Current) - Enhanced multi-chain support, improved analytics, updated dependencies
• v2.0.9 - Package.json modifications and dependency updates
• v2.0.8 - Major refactoring with improved architecture and documentation

License

This package is part of the HSuite Enterprise ecosystem.

Built with ❤️ by the HbarSuite Team
Copyright © 2024 HbarSuite. All rights reserved.