# @hsuite/subscriptions-types - Subscription Management Type Definitions

> 💳 **Comprehensive TypeScript type definitions for HSuite subscription management with Web3 blockchain integration**

Enterprise-grade type definitions and interfaces providing a complete subscription lifecycle management system with Web3 blockchain integration, payment processing, analytics tracking, and multi-tier subscription plans.

***

## 📚 Table of Contents

* [✨ Quick Start](#-quick-start)
* [🏗️ Architecture](#️-architecture)
* [🔧 API Reference](#-api-reference)
* [📖 Guides](#-guides)
* [🎯 Examples](#-examples)
* [🔗 Integration](#-integration)

***

## ✨ Quick Start

### Installation

```bash
npm install @hsuite/subscriptions-types
```

### Basic Setup

```typescript
import { ISubscription, Subscription } from '@hsuite/subscriptions-types';

// Interface-based type definitions
const plan: ISubscription.IPlan = ISubscription.IPlan.PREMIUM;
const status: ISubscription.IStatus = ISubscription.IStatus.ACTIVE;
const period: ISubscription.IPeriodicity = ISubscription.IPeriodicity.MONTHLY;

// Model-based runtime validation
const subscription = new Subscription.Web3.Entity();
const payment = new Subscription.Web3.Payment.Entity();
const analytics = new Subscription.Web3.Analytics.Entity();
```

### NestJS Integration

```typescript
import { Subscription } from '@hsuite/subscriptions-types';

@Controller('subscriptions')
export class SubscriptionController {
  @Post('create')
  @ApiResponse({ type: Subscription.Web3.Entity })
  async createSubscription(@Body() data: any): Promise<Subscription.Web3.Entity> {
    return new Subscription.Web3.Entity(data);
  }
}
```

***

## 🏗️ Architecture

### Core Component Areas

#### 💳 **Subscription Management**

* **Plan System** - Basic, Premium, and Enterprise subscription tiers
* **Billing Cycles** - Monthly and yearly periodicity options
* **Status Lifecycle** - Complete status tracking from pending to expired
* **Configuration Management** - Flexible plan and system configuration

#### 🌐 **Web3 Blockchain Integration**

* **Wallet Integration** - Web3 wallet address and blockchain connectivity
* **Token Management** - Subscription NFTs with serial numbers and metadata
* **Transaction Tracking** - Complete blockchain transaction history
* **Smart Contract Support** - Token gate authentication and blockchain operations

#### 💰 **Payment Processing**

* **Transaction Management** - Payment tracking with blockchain integration
* **Activity Monitoring** - API usage tracking across HTTP methods
* **Renewal Automation** - Automated subscription renewal management
* **Usage Analytics** - Comprehensive API usage analytics and reporting

#### 📊 **Analytics & Monitoring**

* **API Usage Tracking** - Detailed HTTP method and endpoint monitoring
* **Performance Metrics** - Subscription performance and usage analytics
* **Real-time Monitoring** - Live subscription status and usage tracking
* **Reporting System** - Comprehensive analytics reporting capabilities

### Dual Namespace System

#### 🔧 **ISubscription Namespace (Interfaces)**

* **Type Definitions** - Pure TypeScript interfaces for type safety
* **Plan Management** - Subscription plan and billing cycle interfaces
* **Web3 Operations** - Blockchain subscription management interfaces
* **Configuration Types** - System and subscription configuration interfaces

#### 🏛️ **Subscription Namespace (Models)**

* **Runtime Validation** - Concrete classes with built-in validation
* **Swagger Integration** - Complete API documentation decorators
* **Web3 Implementation** - Blockchain subscription management classes
* **Configuration Models** - System configuration and plan management

### Module Structure

```
src/
├── index.ts                           # Main exports and documentation
├── interfaces/                        # ISubscription namespace
│   ├── subscription.namespace.ts      # Central interface hub
│   ├── shared-types/                  # Common enums and utilities
│   └── namespaces/                    # Specialized domains
│       ├── web3/                      # Web3 subscription interfaces
│       └── config/                    # Configuration interfaces
└── models/                            # Subscription namespace
    ├── subscription.namespace.ts      # Central model hub
    └── namespaces/                    # Domain implementations
        ├── web3/                      # Web3 implementations
        └── config/                    # Configuration implementations
```

***

## 🔧 API Reference

### Core Interface Types

#### Plan Management Types

**`ISubscription.IPlan`**

```typescript
enum IPlan {
  BASIC = 'basic',        // Entry-level plan with core features
  PREMIUM = 'premium',    // Mid-tier plan with enhanced capabilities
  ENTERPRISE = 'enterprise' // Top-tier plan with complete feature access
}
```

**`ISubscription.IPeriodicity`**

```typescript
enum IPeriodicity {
  MONTHLY = 'monthly',    // Monthly billing and renewal
  YEARLY = 'yearly'       // Yearly billing and renewal
}
```

**`ISubscription.IStatus`**

```typescript
enum IStatus {
  PENDING = 'pending',        // Awaiting processing or confirmation
  PROCESSING = 'processing',  // Currently being processed
  MINTED = 'minted',         // Subscription token minted on blockchain
  DELIVERED = 'delivered',    // Successfully delivered to user
  ACTIVE = 'active',         // Currently active and in use
  CANCELLED = 'cancelled',   // Terminated by user or system
  EXPIRED = 'expired',       // Reached end date
  FAILED = 'failed'          // Processing or activation failed
}
```

#### Web3 Subscription Types

**`ISubscription.IWeb3.IEntity`**

* **Purpose**: Core Web3 subscription entity structure
* **Properties**: walletId, operatorId, status, details, payments, analytics
* **Usage**: Complete subscription lifecycle management

**`ISubscription.IWeb3.IDetails`**

* **Purpose**: Subscription detail management interface
* **Properties**: tokenId, serialNumber, metadata
* **Usage**: Blockchain token and metadata management

**`ISubscription.IWeb3.IPayment.IEntity`**

* **Purpose**: Payment transaction tracking interface
* **Properties**: date, renewal, transaction, activity
* **Usage**: Payment processing and activity monitoring

### Configuration Types

**`ISubscription.IConfig.IEntity`**

* **Purpose**: Complete subscription system configuration
* **Properties**: basic, premium, enterprise, redis, token, tokenGate
* **Usage**: System-wide subscription configuration

**`ISubscription.IConfig.IPlan.IEntity`**

* **Purpose**: Individual subscription plan configuration
* **Properties**: price, requests, description, image
* **Usage**: Plan-specific settings and limits

### Plan Comparison Matrix

| Feature                 | Basic     | Premium  | Enterprise |
| ----------------------- | --------- | -------- | ---------- |
| **Monthly Price**       | $9.99     | $19.99   | $49.99     |
| **Yearly Price**        | $99.99    | $199.99  | $499.99    |
| **API Requests**        | Limited   | Enhanced | Unlimited  |
| **Blockchain Features** | Basic     | Advanced | Enterprise |
| **Analytics**           | Basic     | Advanced | Full Suite |
| **Support**             | Community | Priority | Dedicated  |

***

## 📖 Guides

### **Subscription Lifecycle Guide**

Complete guide to managing subscription lifecycle from creation to expiration. Comprehensive lifecycle management covering subscription creation, status transitions, renewal workflows, cancellation processes, and enterprise-grade subscription lifecycle automation.

### **Web3 Integration Guide**

Learn how to integrate blockchain features and token management. Advanced integration guide covering Web3 wallet integration, blockchain token operations, NFT-based subscriptions, smart contract interactions, and enterprise Web3 subscription systems.

### **Payment Processing Guide**

Implement payment tracking and transaction management. Detailed implementation guide covering payment gateway integration, transaction monitoring, billing automation, revenue tracking, and enterprise payment processing for subscription services.

### **Analytics Implementation Guide**

Set up comprehensive analytics and usage monitoring. Advanced analytics guide covering usage tracking, performance metrics, user behavior analysis, revenue analytics, and enterprise-grade subscription analytics and reporting systems.

***

## 🎯 Examples

### Subscription Lifecycle Management

```typescript
import { ISubscription, Subscription } from '@hsuite/subscriptions-types';

@Injectable()
export class SubscriptionLifecycleService {
  
  async createSubscription(subscriptionData: any) {
    try {
      // Create subscription metadata
      const metadata = new Subscription.Web3.Metadata({
        plan: ISubscription.IPlan.PREMIUM,
        periodicity: ISubscription.IPeriodicity.MONTHLY,
        app: {
          name: subscriptionData.appName,
          description: subscriptionData.appDescription,
          logo: subscriptionData.appLogo,
          url: subscriptionData.appUrl
        }
      });

      // Create subscription details
      const details = new Subscription.Web3.Details({
        tokenId: subscriptionData.tokenId,
        serialNumber: subscriptionData.serialNumber,
        metadata: metadata
      });

      // Create subscription entity
      const subscription = new Subscription.Web3.Entity({
        walletId: subscriptionData.walletId,
        operatorId: subscriptionData.operatorId,
        status: ISubscription.IStatus.PENDING,
        details: details,
        payments: [],
        analytics: []
      });

      return {
        success: true,
        subscription: subscription,
        subscriptionId: subscription.details.tokenId,
        status: subscription.status,
        plan: metadata.plan,
        nextBilling: this.calculateNextBilling(metadata.periodicity)
      };
    } catch (error) {
      throw new Error(`Subscription creation failed: ${error.message}`);
    }
  }

  async updateSubscriptionStatus(tokenId: string, newStatus: ISubscription.IStatus) {
    try {
      const statusTransitions = {
        [ISubscription.IStatus.PENDING]: [
          ISubscription.IStatus.PROCESSING,
          ISubscription.IStatus.FAILED
        ],
        [ISubscription.IStatus.PROCESSING]: [
          ISubscription.IStatus.MINTED,
          ISubscription.IStatus.FAILED
        ],
        [ISubscription.IStatus.MINTED]: [
          ISubscription.IStatus.DELIVERED,
          ISubscription.IStatus.FAILED
        ],
        [ISubscription.IStatus.DELIVERED]: [
          ISubscription.IStatus.ACTIVE
        ],
        [ISubscription.IStatus.ACTIVE]: [
          ISubscription.IStatus.CANCELLED,
          ISubscription.IStatus.EXPIRED
        ]
      };

      // Validate status transition
      const currentSubscription = await this.getSubscription(tokenId);
      const allowedTransitions = statusTransitions[currentSubscription.status] || [];
      
      if (!allowedTransitions.includes(newStatus)) {
        throw new Error(`Invalid status transition from ${currentSubscription.status} to ${newStatus}`);
      }

      // Update subscription status
      currentSubscription.status = newStatus;

      return {
        success: true,
        tokenId,
        previousStatus: currentSubscription.status,
        newStatus,
        updatedAt: new Date().toISOString()
      };
    } catch (error) {
      throw new Error(`Status update failed: ${error.message}`);
    }
  }

  private calculateNextBilling(periodicity: ISubscription.IPeriodicity): string {
    const now = new Date();
    const nextBilling = new Date(now);
    
    if (periodicity === ISubscription.IPeriodicity.MONTHLY) {
      nextBilling.setMonth(now.getMonth() + 1);
    } else {
      nextBilling.setFullYear(now.getFullYear() + 1);
    }
    
    return nextBilling.toISOString();
  }

  private async getSubscription(tokenId: string): Promise<any> {
    // Mock implementation - replace with actual subscription retrieval
    return {
      tokenId,
      status: ISubscription.IStatus.PENDING
    };
  }
}
```

### Payment Processing and Activity Tracking

```typescript
import { ISubscription, Subscription } from '@hsuite/subscriptions-types';

@Injectable()
export class PaymentProcessingService {
  
  async processPayment(paymentData: any) {
    try {
      // Create activity tracking
      const activity = new Subscription.Web3.Payment.Activity({
        http_get: paymentData.usage.get || 0,
        http_post: paymentData.usage.post || 0,
        http_put: paymentData.usage.put || 0,
        http_delete: paymentData.usage.delete || 0,
        http_patch: paymentData.usage.patch || 0
      });

      // Create payment entity
      const payment = new Subscription.Web3.Payment.Entity({
        date: Date.now(),
        renewal: this.calculateRenewalDate(paymentData.periodicity),
        transaction: paymentData.transactionHash,
        activity: activity
      });

      // Update subscription with payment
      await this.addPaymentToSubscription(paymentData.tokenId, payment);

      return {
        success: true,
        paymentId: payment.transaction,
        amount: paymentData.amount,
        currency: paymentData.currency,
        nextRenewal: new Date(payment.renewal).toISOString(),
        usage: activity
      };
    } catch (error) {
      throw new Error(`Payment processing failed: ${error.message}`);
    }
  }

  async trackAPIUsage(usageData: any) {
    try {
      const analytics = new Subscription.Web3.Analytics.Entity({
        httpMethod: usageData.method,
        endpointUrl: usageData.endpoint,
        timestamp: Date.now()
      });

      // Add analytics to subscription
      await this.addAnalyticsToSubscription(usageData.tokenId, analytics);

      return {
        success: true,
        analyticsId: analytics.timestamp,
        method: analytics.httpMethod,
        endpoint: analytics.endpointUrl,
        recordedAt: new Date(analytics.timestamp).toISOString()
      };
    } catch (error) {
      throw new Error(`Analytics tracking failed: ${error.message}`);
    }
  }

  async generateUsageReport(tokenId: string, timeRange: { start: number; end: number }) {
    try {
      const subscription = await this.getSubscription(tokenId);
      const analytics = subscription.analytics.filter(
        (record: any) => record.timestamp >= timeRange.start && record.timestamp <= timeRange.end
      );

      const usageSummary = {
        totalRequests: analytics.length,
        methodBreakdown: this.aggregateByMethod(analytics),
        endpointBreakdown: this.aggregateByEndpoint(analytics),
        timeRange: {
          start: new Date(timeRange.start).toISOString(),
          end: new Date(timeRange.end).toISOString()
        }
      };

      return {
        success: true,
        tokenId,
        reportGenerated: new Date().toISOString(),
        usage: usageSummary
      };
    } catch (error) {
      throw new Error(`Usage report generation failed: ${error.message}`);
    }
  }

  private calculateRenewalDate(periodicity: ISubscription.IPeriodicity): number {
    const now = Date.now();
    const msInDay = 24 * 60 * 60 * 1000;
    
    if (periodicity === ISubscription.IPeriodicity.MONTHLY) {
      return now + (30 * msInDay);
    } else {
      return now + (365 * msInDay);
    }
  }

  private aggregateByMethod(analytics: any[]): Record<string, number> {
    return analytics.reduce((acc, record) => {
      acc[record.httpMethod] = (acc[record.httpMethod] || 0) + 1;
      return acc;
    }, {});
  }

  private aggregateByEndpoint(analytics: any[]): Record<string, number> {
    return analytics.reduce((acc, record) => {
      acc[record.endpointUrl] = (acc[record.endpointUrl] || 0) + 1;
      return acc;
    }, {});
  }

  private async addPaymentToSubscription(tokenId: string, payment: any): Promise<void> {
    // Implementation for adding payment to subscription
  }

  private async addAnalyticsToSubscription(tokenId: string, analytics: any): Promise<void> {
    // Implementation for adding analytics to subscription
  }

  private async getSubscription(tokenId: string): Promise<any> {
    // Implementation for retrieving subscription
    return {
      tokenId,
      analytics: []
    };
  }
}
```

### Configuration Management

```typescript
import { ISubscription, Subscription } from '@hsuite/subscriptions-types';

@Injectable()
export class SubscriptionConfigurationService {
  
  async setupSubscriptionConfiguration(configData: any) {
    try {
      // Create plan configurations
      const basicPlan = new Subscription.Config.Plan.Entity({
        price: {
          monthly: 999,  // $9.99 in cents
          yearly: 9999   // $99.99 in cents
        },
        requests: {
          get: 1000,
          post: 500,
          put: 100,
          delete: 50,
          patch: 25
        },
        description: "Basic Plan - Perfect for small projects",
        image: "https://assets.hsuite.com/plans/basic.png"
      });

      const premiumPlan = new Subscription.Config.Plan.Entity({
        price: {
          monthly: 1999,  // $19.99 in cents
          yearly: 19999   // $199.99 in cents
        },
        requests: {
          get: 5000,
          post: 2500,
          put: 500,
          delete: 250,
          patch: 125
        },
        description: "Premium Plan - Enhanced capabilities for growing businesses",
        image: "https://assets.hsuite.com/plans/premium.png"
      });

      const enterprisePlan = new Subscription.Config.Plan.Entity({
        price: {
          monthly: 4999,  // $49.99 in cents
          yearly: 49999   // $499.99 in cents
        },
        requests: {
          get: -1,    // Unlimited
          post: -1,   // Unlimited
          put: -1,    // Unlimited
          delete: -1, // Unlimited
          patch: -1   // Unlimited
        },
        description: "Enterprise Plan - Complete feature access with dedicated support",
        image: "https://assets.hsuite.com/plans/enterprise.png"
      });

      // Create main configuration
      const config = new Subscription.Config.Entity({
        basic: basicPlan,
        premium: premiumPlan,
        enterprise: enterprisePlan,
        redis: {
          host: configData.redis.host || 'localhost',
          port: configData.redis.port || 6379,
          ttl: configData.redis.ttl || 3600
        },
        token: {
          issuer: configData.token.issuer,
          secret: configData.token.secret
        },
        tokenGate: {
          enabled: true,
          options: {
            guardType: 'subscriptions'
          }
        },
        payment: {
          provider: configData.payment.provider || 'stripe',
          webhookSecret: configData.payment.webhookSecret
        }
      });

      return {
        success: true,
        configuration: config,
        plansConfigured: 3,
        features: {
          tokenGate: config.tokenGate.enabled,
          redis: !!config.redis,
          payments: !!config.payment
        }
      };
    } catch (error) {
      throw new Error(`Configuration setup failed: ${error.message}`);
    }
  }

  async validatePlanLimits(tokenId: string, requestType: string): Promise<boolean> {
    try {
      const subscription = await this.getSubscription(tokenId);
      const plan = await this.getPlanConfiguration(subscription.metadata.plan);
      const currentUsage = await this.getCurrentUsage(tokenId);

      const requestLimit = plan.requests[requestType];
      
      // Unlimited access (-1) or within limits
      if (requestLimit === -1 || currentUsage[requestType] < requestLimit) {
        return true;
      }

      return false;
    } catch (error) {
      console.error('Plan limit validation failed:', error);
      return false;
    }
  }

  async upgradePlan(tokenId: string, newPlan: ISubscription.IPlan) {
    try {
      const subscription = await this.getSubscription(tokenId);
      const currentPlan = subscription.metadata.plan;
      
      // Validate upgrade path
      const upgradeMatrix = {
        [ISubscription.IPlan.BASIC]: [ISubscription.IPlan.PREMIUM, ISubscription.IPlan.ENTERPRISE],
        [ISubscription.IPlan.PREMIUM]: [ISubscription.IPlan.ENTERPRISE],
        [ISubscription.IPlan.ENTERPRISE]: [] // Cannot upgrade from enterprise
      };

      const allowedUpgrades = upgradeMatrix[currentPlan] || [];
      
      if (!allowedUpgrades.includes(newPlan)) {
        throw new Error(`Cannot upgrade from ${currentPlan} to ${newPlan}`);
      }

      // Update subscription plan
      subscription.metadata.plan = newPlan;
      
      // Calculate pro-rated pricing
      const proRatedAmount = await this.calculateProRatedAmount(subscription, newPlan);

      return {
        success: true,
        tokenId,
        previousPlan: currentPlan,
        newPlan,
        proRatedAmount,
        effectiveDate: new Date().toISOString()
      };
    } catch (error) {
      throw new Error(`Plan upgrade failed: ${error.message}`);
    }
  }

  private async getPlanConfiguration(plan: ISubscription.IPlan): Promise<any> {
    // Mock implementation - replace with actual plan retrieval
    const plans = {
      [ISubscription.IPlan.BASIC]: {
        requests: { get: 1000, post: 500, put: 100, delete: 50, patch: 25 }
      },
      [ISubscription.IPlan.PREMIUM]: {
        requests: { get: 5000, post: 2500, put: 500, delete: 250, patch: 125 }
      },
      [ISubscription.IPlan.ENTERPRISE]: {
        requests: { get: -1, post: -1, put: -1, delete: -1, patch: -1 }
      }
    };
    
    return plans[plan];
  }

  private async getCurrentUsage(tokenId: string): Promise<Record<string, number>> {
    // Mock implementation - replace with actual usage tracking
    return {
      get: 500,
      post: 250,
      put: 50,
      delete: 25,
      patch: 10
    };
  }

  private async getSubscription(tokenId: string): Promise<any> {
    // Mock implementation
    return {
      tokenId,
      metadata: {
        plan: ISubscription.IPlan.BASIC
      }
    };
  }

  private async calculateProRatedAmount(subscription: any, newPlan: ISubscription.IPlan): Promise<number> {
    // Mock implementation for pro-rated amount calculation
    const planPrices = {
      [ISubscription.IPlan.BASIC]: 999,
      [ISubscription.IPlan.PREMIUM]: 1999,
      [ISubscription.IPlan.ENTERPRISE]: 4999
    };
    
    return planPrices[newPlan] - planPrices[subscription.metadata.plan];
  }
}
```

### Multi-Tenant Subscription Management

```typescript
import { ISubscription, Subscription } from '@hsuite/subscriptions-types';

@Injectable()
export class MultiTenantSubscriptionService {
  
  async createTenantSubscription(tenantData: any) {
    try {
      // Create tenant-specific app metadata
      const appMetadata = new Subscription.Web3.App({
        name: tenantData.applicationName,
        description: tenantData.applicationDescription,
        logo: tenantData.applicationLogo,
        url: tenantData.applicationUrl
      });

      // Create subscription for tenant
      const subscription = await this.createSubscription({
        walletId: tenantData.walletId,
        operatorId: tenantData.operatorId,
        plan: tenantData.selectedPlan,
        periodicity: tenantData.billingPeriod,
        app: appMetadata
      });

      // Setup tenant-specific limits
      await this.setupTenantLimits(subscription.details.tokenId, tenantData.customLimits);

      return {
        success: true,
        tenantId: tenantData.tenantId,
        subscription: subscription,
        features: this.getTenantFeatures(tenantData.selectedPlan),
        setupComplete: true
      };
    } catch (error) {
      throw new Error(`Tenant subscription creation failed: ${error.message}`);
    }
  }

  async manageTenantBilling(tenantId: string, billingData: any) {
    try {
      const subscriptions = await this.getTenantSubscriptions(tenantId);
      const billingResults = [];

      for (const subscription of subscriptions) {
        const usage = await this.calculateTenantUsage(subscription.details.tokenId);
        const bill = await this.generateBill(subscription, usage, billingData.billingCycle);
        
        billingResults.push({
          subscriptionId: subscription.details.tokenId,
          plan: subscription.metadata.plan,
          usage: usage,
          bill: bill
        });
      }

      return {
        success: true,
        tenantId,
        billingPeriod: billingData.billingCycle,
        subscriptions: billingResults.length,
        totalAmount: billingResults.reduce((sum, result) => sum + result.bill.amount, 0),
        generatedAt: new Date().toISOString()
      };
    } catch (error) {
      throw new Error(`Tenant billing management failed: ${error.message}`);
    }
  }

  async monitorTenantUsage(tenantId: string) {
    try {
      const subscriptions = await this.getTenantSubscriptions(tenantId);
      const usageData = [];

      for (const subscription of subscriptions) {
        const analytics = subscription.analytics || [];
        const recentUsage = analytics.filter(
          (record: any) => record.timestamp > Date.now() - (24 * 60 * 60 * 1000) // Last 24 hours
        );

        const usage = {
          subscriptionId: subscription.details.tokenId,
          plan: subscription.metadata.plan,
          dailyUsage: {
            totalRequests: recentUsage.length,
            methodBreakdown: this.aggregateByMethod(recentUsage),
            topEndpoints: this.getTopEndpoints(recentUsage, 5)
          },
          limits: await this.getPlanLimits(subscription.metadata.plan),
          utilizationPercentage: this.calculateUtilization(recentUsage, subscription.metadata.plan)
        };

        usageData.push(usage);
      }

      return {
        success: true,
        tenantId,
        monitoringPeriod: '24 hours',
        subscriptions: usageData,
        totalUsage: usageData.reduce((sum, data) => sum + data.dailyUsage.totalRequests, 0),
        alertsRequired: usageData.filter(data => data.utilizationPercentage > 80)
      };
    } catch (error) {
      throw new Error(`Tenant usage monitoring failed: ${error.message}`);
    }
  }

  private getTenantFeatures(plan: ISubscription.IPlan): string[] {
    const features = {
      [ISubscription.IPlan.BASIC]: [
        'Basic API Access',
        'Standard Support',
        'Monthly Billing'
      ],
      [ISubscription.IPlan.PREMIUM]: [
        'Enhanced API Access',
        'Priority Support',
        'Advanced Analytics',
        'Monthly/Yearly Billing'
      ],
      [ISubscription.IPlan.ENTERPRISE]: [
        'Unlimited API Access',
        'Dedicated Support',
        'Complete Analytics Suite',
        'Custom Billing Terms',
        'SLA Guarantees'
      ]
    };

    return features[plan] || [];
  }

  private async setupTenantLimits(tokenId: string, customLimits: any): Promise<void> {
    // Implementation for setting up tenant-specific limits
  }

  private async getTenantSubscriptions(tenantId: string): Promise<any[]> {
    // Mock implementation - replace with actual tenant subscription retrieval
    return [];
  }

  private async calculateTenantUsage(tokenId: string): Promise<any> {
    // Mock implementation for calculating tenant usage
    return {
      requests: 1500,
      methods: { get: 1000, post: 300, put: 150, delete: 50 }
    };
  }

  private async generateBill(subscription: any, usage: any, billingCycle: string): Promise<any> {
    // Mock implementation for bill generation
    return {
      amount: 1999, // $19.99 in cents
      currency: 'USD',
      period: billingCycle
    };
  }

  private aggregateByMethod(analytics: any[]): Record<string, number> {
    return analytics.reduce((acc, record) => {
      acc[record.httpMethod] = (acc[record.httpMethod] || 0) + 1;
      return acc;
    }, {});
  }

  private getTopEndpoints(analytics: any[], limit: number): Array<{ endpoint: string; count: number }> {
    const endpointCounts = analytics.reduce((acc, record) => {
      acc[record.endpointUrl] = (acc[record.endpointUrl] || 0) + 1;
      return acc;
    }, {});

    return Object.entries(endpointCounts)
      .map(([endpoint, count]) => ({ endpoint, count: count as number }))
      .sort((a, b) => b.count - a.count)
      .slice(0, limit);
  }

  private async getPlanLimits(plan: ISubscription.IPlan): Promise<any> {
    // Mock implementation
    return { monthly: 10000 };
  }

  private calculateUtilization(recentUsage: any[], plan: ISubscription.IPlan): number {
    // Mock calculation - replace with actual utilization logic
    return Math.min(100, (recentUsage.length / 1000) * 100);
  }
}
```

***

## 🔗 Integration

### Required Dependencies

```json
{
  "@nestjs/common": "^10.4.2",
  "@nestjs/core": "^10.4.2",
  "@hsuite/smart-network-types": "^2.0.0",
  "@hsuite/nestjs-swagger": "^1.0.3",
  "@compodoc/compodoc": "^1.1.23"
}
```

### Module Integration

```typescript
import { Module } from '@nestjs/common';
import { Subscription, ISubscription } from '@hsuite/subscriptions-types';

@Module({
  providers: [
    SubscriptionLifecycleService,
    PaymentProcessingService,
    SubscriptionConfigurationService,
    MultiTenantSubscriptionService
  ],
  exports: [
    SubscriptionLifecycleService,
    PaymentProcessingService,
    SubscriptionConfigurationService,
    MultiTenantSubscriptionService
  ]
})
export class SubscriptionTypesModule {}
```

### Documentation Generation

```bash
# Generate comprehensive documentation
npm run compodoc

# Generate documentation with coverage report
npm run compodoc:coverage
```

### Integration with HSuite Ecosystem

```typescript
// Complete integration with other HSuite modules
import { Subscription, ISubscription } from '@hsuite/subscriptions-types';
import { AuthModule } from '@hsuite/auth';
import { SmartNetworkModule } from '@hsuite/smart-network';
import { HashgraphModule } from '@hsuite/hashgraph';

@Module({
  imports: [
    AuthModule,
    SmartNetworkModule,
    HashgraphModule
  ]
})
export class SubscriptionEcosystemModule {}

@Injectable()
export class IntegratedSubscriptionService {
  constructor(
    private authService: AuthService,
    private networkService: SmartNetworkService,
    private hashgraphService: HashgraphService
  ) {}

  async createSecureSubscription(
    subscriptionData: any,
    session: IAuth.ICredentials.IWeb3.IEntity
  ): Promise<Subscription.Web3.Entity> {
    // 1. Validate permissions
    const hasPermission = await this.authService.validatePermission(
      session,
      'subscription:create'
    );

    if (!hasPermission) {
      throw new Error('Insufficient permissions for subscription creation');
    }

    // 2. Create blockchain subscription
    const subscription = new Subscription.Web3.Entity({
      walletId: session.walletId,
      operatorId: subscriptionData.operatorId,
      status: ISubscription.IStatus.PENDING,
      details: subscriptionData.details,
      payments: [],
      analytics: []
    });

    // 3. Submit to Hashgraph
    const txResponse = await this.hashgraphService.createSubscriptionToken(subscription);
    
    // 4. Update with blockchain data
    subscription.details.tokenId = txResponse.tokenId;
    subscription.status = ISubscription.IStatus.MINTED;

    return subscription;
  }
}
```

## Use Cases

### 💳 **SaaS Subscription Management**

* Multi-tier subscription plans with different feature sets
* Automated billing and renewal management
* Usage-based pricing and API rate limiting
* Customer analytics and usage reporting

### 🌐 **Web3 dApp Monetization**

* Blockchain-based subscription NFTs
* Token-gated access control
* Decentralized payment processing
* Smart contract integration

### 📊 **Enterprise Analytics Platform**

* Comprehensive API usage tracking
* Real-time monitoring and alerting
* Performance analytics and reporting
* Multi-tenant management capabilities

### 🏢 **Multi-Tenant Applications**

* Tenant-specific subscription management
* Custom billing and pricing models
* Isolated analytics and reporting
* Scalable configuration management

***

**💳 Enterprise Subscription System**: Comprehensive TypeScript definitions with Web3 blockchain integration and multi-tier subscription management.

**🌐 Blockchain-Native**: Complete Web3 support with NFT subscriptions, token gates, and smart contract integration.

**📊 Advanced Analytics**: Real-time usage tracking, performance monitoring, and comprehensive reporting capabilities.

***

<p align="center">Built with ❤️ by the HSuite Team<br>Copyright © 2025 HSuite. All rights reserved.</p>