@misterhomer1992/miit-bot-payment 1.1.6 → 2.0.4

package/src/modules/subscription/types.ts

@@ -0,0 +1,267 @@
+import { NestedPathsAccess } from '../../types/utilities';
+import { SubscriptionPlanEntity } from '../subscriptionPlan/types';
+import { PaymentEntity } from '../payments/types';
+
+type UpgradePreview = {
+    currentPlan: SubscriptionPlanEntity;
+    newPlan: SubscriptionPlanEntity;
+    remainingDays: number;
+    remainingValue: number;
+    upgradeCost: number;
+    currency: 'UAH' | 'USD';
+};
+
+type UpgradeResult = {
+    payment: PaymentEntity;
+    paymentUrl: string;
+};
+
+type SubscriptionEntity = {
+    /** Auto-generated unique ID (document ID) */
+    id: string;
+    /** The Telegram User ID this subscription belongs to. Links back to users. */
+    userId: string;
+    /** An identifier for the subscription plan (e.g., "basic-daily", "pro-monthly") */
+    planId: string;
+    /** The lifecycle state of this service period */
+    status: 'active' | 'expired' | 'cancelled';
+    /** The key field for the cron job. Timestamp when this paid-for period ends. */
+    expiresAt: string;
+    /** Timestamp when this period began */
+    startedAt: string;
+    /** Platform/app namespace */
+    platform: string;
+    /** Payment provider */
+    provider: 'wayforpay' | 'platform';
+};
+
+type SubscriptionPlan = {
+    id: string;
+    titleCode: string;
+    descriptionCode: string;
+    amount: number;
+    currency: 'UAH' | 'USD';
+    features: {
+        messages: number;
+        images: number;
+        voice: number;
+    };
+    regularMode: 'daily' | 'monthly' | 'yearly';
+    count: number;
+    credits: number;
+};
+
+type SubscriptionFieldPath = NestedPathsAccess<SubscriptionEntity>;
+
+/**
+ * Interface for subscription repository operations.
+ * Defines the contract for data access layer.
+ */
+interface ISubscriptionRepository {
+    /**
+     * Retrieves a subscription for a specific user.
+     * @param params - Query parameters
+     * @returns Promise resolving to SubscriptionEntity or null if not found
+     */
+    getByUser(params: {
+        userId: string;
+        platform: string;
+        status?: SubscriptionEntity['status'] | SubscriptionEntity['status'][];
+    }): Promise<SubscriptionEntity | null>;
+
+    /**
+     * Creates a new subscription record in the database.
+     * @param params - Subscription creation parameters
+     * @returns Promise resolving to created SubscriptionEntity with ID
+     */
+    create(params: {
+        userId: string;
+        platform: string;
+        planId: string;
+        expiresAt: string;
+        startedAt: string;
+    }): Promise<SubscriptionEntity>;
+
+    /**
+     * Updates specific fields of a subscription identified by userId and platform.
+     * @param params - Update parameters
+     */
+    updateFieldsByUserId(params: { userId: string; platform: string; fields: any }): Promise<void>;
+
+    /**
+     * Retrieves all active subscriptions that have expired.
+     * @returns Promise resolving to array of expired SubscriptionEntity
+     */
+    getExpiredActiveSubscriptions(): Promise<SubscriptionEntity[]>;
+
+    /**
+     * Updates specific fields of a subscription identified by subscription ID.
+     * @param params - Update parameters
+     */
+    updateFieldsById(params: { subscriptionId: string; fields: any }): Promise<void>;
+
+    /**
+     * Activates a subscription for a user using a transaction.
+     * @param params - Activation parameters
+     * @returns Promise resolving to void
+     */
+    activateSubscription(params: Omit<SubscriptionEntity, 'id' | 'status'>): Promise<void>;
+
+    /**
+     * Renews a subscription for a user using a transaction.
+     * @param params - Renewal parameters
+     */
+    renewSubscription(params: Pick<SubscriptionEntity, 'userId' | 'platform' | 'expiresAt'>): Promise<void>;
+
+    /**
+     * Retrieves subscriptions by status.
+     * @param params - Status parameters
+     * @returns Promise resolving to array of SubscriptionEntity
+     */
+    getByStatus(params: {
+        status: SubscriptionEntity['status'] | SubscriptionEntity['status'][];
+    }): Promise<SubscriptionEntity[]>;
+
+    /**
+     * Deactivates a subscription for a user using a transaction.
+     * @param params - Deactivation parameters
+     */
+    deactivateSubscription({ id }: Pick<SubscriptionEntity, 'id'>): Promise<void>;
+
+    /**
+     * Cancels a subscription for a user using a transaction.
+     * @param params - Cancellation parameters
+     */
+    cancelSubscription(params: Pick<SubscriptionEntity, 'id'>): Promise<void>;
+}
+
+/**
+ * Interface for subscription service operations.
+ * Defines the contract for business logic layer.
+ */
+interface ISubscriptionService {
+    /**
+     * Retrieves a subscription for a specific user.
+     * @param params - Query parameters
+     * @returns Promise resolving to SubscriptionEntity or null if not found
+     */
+    getByUser(params: {
+        userId: string;
+        platform: string;
+        status?: SubscriptionEntity['status'] | SubscriptionEntity['status'][];
+    }): Promise<SubscriptionEntity | null>;
+
+    /**
+     * Creates a new subscription record in the database.
+     * @param params - Subscription creation parameters
+     * @returns Promise resolving to created SubscriptionEntity with ID
+     */
+    create(params: {
+        userId: string;
+        platform: string;
+        planId: string;
+        expiresAt: string;
+        startedAt: string;
+    }): Promise<SubscriptionEntity>;
+
+    /**
+     * Updates specific fields of a subscription identified by userId and platform.
+     * @param params - Update parameters
+     */
+    updateFieldsByUserId(params: { userId: string; platform: string; fields: any }): Promise<void>;
+
+    /**
+     * Retrieves all active subscriptions that have expired.
+     * @returns Promise resolving to array of expired SubscriptionEntity
+     */
+    getExpiredActiveSubscriptions(): Promise<SubscriptionEntity[]>;
+
+    /**
+     * Updates specific fields of a subscription identified by subscription ID.
+     * @param params - Update parameters
+     */
+    updateFieldsById(params: { subscriptionId: string; fields: any }): Promise<void>;
+
+    /**
+     * Gets or creates a subscription payment URL.
+     * @param params - Payment URL creation parameters
+     * @returns Promise resolving to the payment URL string
+     */
+    getOrCreateSubscriptionPaymentUrl(params: {
+        userId: string;
+        platform: string;
+        languageCode: string;
+        translate: (params: { code: string; path: string }) => string;
+        subscriptionPlan: SubscriptionPlan;
+    }): Promise<string>;
+
+    /**
+     * Activates a subscription for a user.
+     * @param params - Activation parameters
+     */
+    activateSubscription(params: Omit<SubscriptionEntity, 'id' | 'status'>): Promise<void>;
+
+    /**
+     * Retrieves all subscriptions(active and cancelled) that have an expiration date in the past.
+     */
+    getSubscriptionsForDeactivationCheck(): Promise<SubscriptionEntity[]>;
+
+    /**
+     * Deactivates a subscription for a user.
+     * @param params - Deactivation parameters
+     */
+    deactivateSubscription({ id }: Pick<SubscriptionEntity, 'id'>): Promise<void>;
+
+    /**
+     * Cancels a subscription for a user.
+     * @param params - Cancellation parameters
+     */
+    cancelSubscription(params: Pick<SubscriptionEntity, 'id'>): Promise<void>;
+
+    /**
+     * Renews a subscription for a user by updating the expiration date.
+     * @param params - Renewal parameters
+     */
+    renewSubscription(params: Pick<SubscriptionEntity, 'userId' | 'platform' | 'expiresAt'>): Promise<void>;
+
+    /**
+     * Retrieves all subscriptions that have expired past the grace period.
+     * Only returns subscriptions that should be deactivated.
+     * @returns Promise resolving to array of expired SubscriptionEntity
+     */
+    getExpiredSubscriptions(): Promise<SubscriptionEntity[]>;
+
+    /**
+     * Retrieves all subscriptions that have had failed renewal attempts.
+     * These are cancelled subscriptions that expired and need deactivation.
+     * @returns Promise resolving to array of SubscriptionEntity with failed renewals
+     */
+    getFailedRenewals(): Promise<SubscriptionEntity[]>;
+
+    /**
+     * Deactivates a subscription by ID (alias for deactivateSubscription).
+     * @param params - Deactivation parameters
+     */
+    deactivate({ id }: Pick<SubscriptionEntity, 'id'>): Promise<void>;
+}
+
+interface ISubscriptionCapacity {
+    geminiTextCompletionTokens: number;
+    geminiImageGenerationCount: number;
+
+    openaiTextCompletionTokens: number;
+    openaiTextToSpeechChars: number;
+    openaiImageVisionTokens: number;
+    openaiTextTranscriptionMinutes: number;
+}
+
+export type {
+    SubscriptionEntity,
+    SubscriptionPlan,
+    SubscriptionFieldPath,
+    ISubscriptionRepository,
+    ISubscriptionService,
+    ISubscriptionCapacity,
+    UpgradePreview,
+    UpgradeResult,
+};

package/src/modules/subscription/utils.ts

@@ -0,0 +1,5 @@
+function getSubscriptionTitle(planTitle: string) {
+    return `Miia telegram bot: ${planTitle}`;
+}
+
+export { getSubscriptionTitle };

package/src/modules/subscriptionPlan/const.ts

@@ -0,0 +1,106 @@
+import { SubscriptionPlanEntity } from './types';
+
+export const SUBSCRIPTION_PLAN_COLLECTION = 'subscription_plans';
+
+export const CACHE_TTL_MS = 20 * 60 * 60 * 1000; // 20 hours in milliseconds
+
+export const DEFAULT_SUBSCRIPTION_PLANS: Omit<SubscriptionPlanEntity, 'createdAt' | 'updatedAt'>[] = [
+    // UAH Plans
+    {
+        id: 'basic-monthly',
+        titleCode: 'subscription.plan.basic.title',
+        descriptionCode: 'subscription.plan.basic.description',
+        amount: 99,
+        currency: 'UAH',
+        features: {
+            messages: 1000,
+            images: 50,
+            voice: 100,
+        },
+        regularMode: 'monthly',
+        count: 1,
+        credits: 1000,
+        isActive: true,
+    },
+    {
+        id: 'pro-monthly',
+        titleCode: 'subscription.plan.pro.title',
+        descriptionCode: 'subscription.plan.pro.description',
+        amount: 199,
+        currency: 'UAH',
+        features: {
+            messages: 5000,
+            images: 200,
+            voice: 500,
+        },
+        regularMode: 'monthly',
+        count: 1,
+        credits: 5000,
+        isActive: true,
+    },
+    {
+        id: 'premium-monthly',
+        titleCode: 'subscription.plan.premium.title',
+        descriptionCode: 'subscription.plan.premium.description',
+        amount: 399,
+        currency: 'UAH',
+        features: {
+            messages: 15000,
+            images: 500,
+            voice: 1000,
+        },
+        regularMode: 'monthly',
+        count: 1,
+        credits: 15000,
+        isActive: true,
+    },
+    // USD Plans - $7, $10, $14 tiers
+    {
+        id: 'starter-monthly-usd',
+        titleCode: 'subscription.plan.starter.title',
+        descriptionCode: 'subscription.plan.starter.description',
+        amount: 7,
+        currency: 'USD',
+        features: {
+            messages: 2000,
+            images: 100,
+            voice: 200,
+        },
+        regularMode: 'monthly',
+        count: 1,
+        credits: 2000,
+        isActive: true,
+    },
+    {
+        id: 'standard-monthly-usd',
+        titleCode: 'subscription.plan.standard.title',
+        descriptionCode: 'subscription.plan.standard.description',
+        amount: 10,
+        currency: 'USD',
+        features: {
+            messages: 5000,
+            images: 250,
+            voice: 500,
+        },
+        regularMode: 'monthly',
+        count: 1,
+        credits: 5000,
+        isActive: true,
+    },
+    {
+        id: 'professional-monthly-usd',
+        titleCode: 'subscription.plan.professional.title',
+        descriptionCode: 'subscription.plan.professional.description',
+        amount: 14,
+        currency: 'USD',
+        features: {
+            messages: 10000,
+            images: 500,
+            voice: 1000,
+        },
+        regularMode: 'monthly',
+        count: 1,
+        credits: 10000,
+        isActive: true,
+    },
+];

package/src/modules/subscriptionPlan/index.ts

@@ -0,0 +1,4 @@
+export * from './types';
+export * from './const';
+export * from './repository';
+export * from './service';

package/src/modules/subscriptionPlan/repository.ts

@@ -0,0 +1,129 @@
+import { FieldValue, Firestore, getFirestore, QueryDocumentSnapshot } from 'firebase-admin/firestore';
+import { SubscriptionPlanEntity, SubscriptionPlanFieldPath, ISubscriptionPlanRepository } from './types';
+import { SUBSCRIPTION_PLAN_COLLECTION } from './const';
+
+export type UpdateDBSubscriptionPlanFields = [
+    SubscriptionPlanFieldPath,
+    FieldValue | string | number | boolean | Date | [] | {},
+][];
+
+export class SubscriptionPlanRepository implements ISubscriptionPlanRepository {
+    private readonly db: Firestore;
+    private readonly collectionName = SUBSCRIPTION_PLAN_COLLECTION;
+
+    constructor({ db }: { db?: Firestore } = {}) {
+        this.db = db || getFirestore();
+    }
+
+    public async getAll(): Promise<SubscriptionPlanEntity[]> {
+        const querySnapshot = await this.db.collection(this.collectionName).get();
+
+        if (querySnapshot.empty) {
+            return [];
+        }
+
+        return querySnapshot.docs.map((doc) => this.mapDocumentToEntity(doc));
+    }
+
+    public async getById(id: string): Promise<SubscriptionPlanEntity | null> {
+        const docSnapshot = await this.db.collection(this.collectionName).doc(id).get();
+
+        if (!docSnapshot.exists) {
+            return null;
+        }
+
+        return {
+            id: docSnapshot.id,
+            ...docSnapshot.data(),
+        } as SubscriptionPlanEntity;
+    }
+
+    public async create(
+        params: Omit<SubscriptionPlanEntity, 'id' | 'createdAt' | 'updatedAt'>,
+    ): Promise<SubscriptionPlanEntity> {
+        const docRef = this.db.collection(this.collectionName).doc();
+        const now = new Date().toISOString();
+
+        const planEntity: SubscriptionPlanEntity = {
+            ...params,
+            id: docRef.id,
+            createdAt: now,
+            updatedAt: now,
+        };
+
+        await docRef.set(planEntity);
+
+        return planEntity;
+    }
+
+    public async update(
+        id: string,
+        params: Partial<Omit<SubscriptionPlanEntity, 'id' | 'createdAt' | 'updatedAt'>>,
+    ): Promise<SubscriptionPlanEntity> {
+        const docRef = this.db.collection(this.collectionName).doc(id);
+        const docSnapshot = await docRef.get();
+
+        if (!docSnapshot.exists) {
+            throw new Error(`Subscription plan not found: ${id}`);
+        }
+
+        const now = new Date().toISOString();
+        const updateData = {
+            ...params,
+            updatedAt: now,
+        };
+
+        await docRef.update(updateData);
+
+        const updatedDoc = await docRef.get();
+        return {
+            id: updatedDoc.id,
+            ...updatedDoc.data(),
+        } as SubscriptionPlanEntity;
+    }
+
+    public async deactivate(id: string): Promise<void> {
+        const docRef = this.db.collection(this.collectionName).doc(id);
+        const docSnapshot = await docRef.get();
+
+        if (!docSnapshot.exists) {
+            throw new Error(`Subscription plan not found: ${id}`);
+        }
+
+        await docRef.update({
+            isActive: false,
+            updatedAt: new Date().toISOString(),
+        });
+    }
+
+    public async seedDefaults(
+        defaultPlans: Omit<SubscriptionPlanEntity, 'createdAt' | 'updatedAt'>[],
+    ): Promise<void> {
+        const batch = this.db.batch();
+        const now = new Date().toISOString();
+
+        for (const plan of defaultPlans) {
+            const docRef = this.db.collection(this.collectionName).doc(plan.id);
+            const planEntity: SubscriptionPlanEntity = {
+                ...plan,
+                createdAt: now,
+                updatedAt: now,
+            };
+            batch.set(docRef, planEntity);
+        }
+
+        await batch.commit();
+    }
+
+    public async isEmpty(): Promise<boolean> {
+        const querySnapshot = await this.db.collection(this.collectionName).limit(1).get();
+        return querySnapshot.empty;
+    }
+
+    private mapDocumentToEntity(doc: QueryDocumentSnapshot): SubscriptionPlanEntity {
+        return {
+            id: doc.id,
+            ...doc.data(),
+        } as SubscriptionPlanEntity;
+    }
+}