@misterhomer1992/miit-bot-payment 1.0.1 → 1.0.2

package/README.md

@@ -1,18 +1,18 @@
 # @miit-bot/payment-utils
 
-A TypeScript utility library for payment validation and formatting. This library provides robust validation for credit card numbers, payment amounts, CVV codes, and formatting utilities for displaying payment information.
+Personal TypeScript library for managing payments and invoices in my bot applications. Built specifically for Wayforpay integration with Firebase/Firestore backend.
 
-## Features
+## Purpose
 
-- 💳 Credit card validation with Luhn algorithm
-- 🏦 Automatic card type detection (Visa, Mastercard, Amex, Discover)
-- 💰 Payment amount validation with customizable limits
-- 🔒 CVV/CVC validation
-- 🎨 Card number formatting and masking
-- 🌍 Currency formatting with internationalization support
-- 📅 Expiry date formatting
-- 🔧 Written in TypeScript with full type definitions
-- ✅ Zero dependencies (dev dependencies only)
+This is a private utility library I use across my bot projects to handle:
+
+- Payment processing with Wayforpay
+- Invoice management and webhook handling
+- Payment lifecycle tracking (pending → completed/failed/expired)
+- Multi-platform support (Telegram, web, etc.)
+- Expired payment cleanup
+
+Also includes some legacy payment validation and formatting utilities.
 
 ## Installation
 
@@ -20,226 +20,342 @@ A TypeScript utility library for payment validation and formatting. This library
 npm install @miit-bot/payment-utils
 ```
 
-or
+## Setup
 
-```bash
-yarn add @miit-bot/payment-utils
+### Firebase Initialization
+
+Initialize Firebase Admin SDK before using payment/invoice services:
+
+```typescript
+import * as admin from 'firebase-admin';
+
+admin.initializeApp({
+    credential: admin.credential.cert({
+        projectId: 'your-project-id',
+        clientEmail: 'your-client-email',
+        privateKey: 'your-private-key',
+    }),
+});
 ```
 
+### Required Firestore Collections
+
+- `payments` - Payment records
+- `invoices` - Invoice records from Wayforpay webhooks
+
 ## Usage
 
-### Card Validation
+### PaymentService
+
+Manages payment lifecycle from creation to completion.
 
 ```typescript
-import { validateCardNumber, CardType } from '@miit-bot/payment-utils';
+import { PaymentService } from '@miit-bot/payment-utils';
+
+const logger = {
+    error: (params) => console.error(params),
+    info: (params) => console.info(params),
+    warn: (params) => console.warn(params),
+    debug: (params) => console.debug(params),
+};
+
+const paymentService = new PaymentService(logger);
+
+// Create payment when user initiates purchase
+const payment = await paymentService.create({
+    orderReference: 'ORDER_123456',
+    userId: 'user_abc',
+    status: 'pending',
+    paymentLink: 'https://wayforpay.com/pay/...',
+    planId: 'premium_monthly',
+    amount: 99.99,
+    currency: 'USD',
+    createdAt: new Date().toISOString(),
+    platform: 'telegram',
+    provider: 'wayforpay',
+});
 
-// Validate a credit card number
-const result = validateCardNumber('4532015112830366');
-console.log(result);
-// {
-//   isValid: true,
-//   cardType: 'VISA',
-//   message: 'Valid card number'
-// }
-```
+// Retrieve by order reference
+const payment = await paymentService.getByOrderReference('ORDER_123456');
 
-### Amount Validation
+// Get user's payment history
+const userPayments = await paymentService.getByUserId({
+    userId: 'user_abc',
+    appNamespace: 'telegram',
+    status: 'completed', // optional filter
+});
 
-```typescript
-import { validateAmount } from '@miit-bot/payment-utils';
+// Update payment status (e.g., after webhook)
+await paymentService.updateFields({
+    orderReference: 'ORDER_123456',
+    fields: [
+        ['status', 'completed'],
+        ['invoiceId', 'invoice_xyz'],
+    ],
+});
 
-// Validate payment amount
-const result = validateAmount(99.99);
-console.log(result);
-// {
-//   isValid: true,
-//   amount: 99.99,
-//   message: 'Valid amount'
-// }
-
-// With custom limits
-const customResult = validateAmount(150.0, 10, 100);
-console.log(customResult);
-// {
-//   isValid: false,
-//   amount: 150,
-//   message: 'Amount must not exceed 100'
-// }
+// Find expired pending payments for cleanup
+const expiredPayments = await paymentService.getExpiredPendingPayments({
+    hoursOld: 24, // default: 24
+});
 ```
 
-### CVV Validation
+### InvoiceService
 
-```typescript
-import { validateCVV, CardType } from '@miit-bot/payment-utils';
+Stores invoice data from Wayforpay webhooks.
 
-// Validate CVV
-const isValid = validateCVV('123'); // true
+```typescript
+import { InvoiceService } from '@miit-bot/payment-utils';
+
+const invoiceService = new InvoiceService(logger);
+
+// Create invoice from webhook data
+const invoice = await invoiceService.create({
+    merchantAccount: 'merchant_123',
+    orderReference: 'ORDER_123456',
+    merchantSignature: 'signature_hash',
+    reasonCode: 1100,
+    reason: 'Payment successful',
+    createdDate: Date.now(),
+    processingDate: Date.now(),
+    currency: 'USD',
+    amount: 99.99,
+});
 
-// Validate Amex CVV (4 digits)
-const isValidAmex = validateCVV('1234', CardType.AMEX); // true
+// Retrieve invoice
+const invoice = await invoiceService.getByOrderReference('ORDER_123456');
 ```
 
-### Card Formatting
-
-```typescript
-import { formatCardNumber, maskCardNumber } from '@miit-bot/payment-utils';
+## Typical Workflow
 
-// Format card number with spaces
-const formatted = formatCardNumber('4532015112830366');
-console.log(formatted); // '4532 0151 1283 0366'
+### 1. User Initiates Payment
 
-// Format and mask
-const masked = formatCardNumber('4532015112830366', true);
-console.log(masked); // '**** **** **** 0366'
+```typescript
+const payment = await paymentService.create({
+    orderReference: generateOrderReference(),
+    userId: user.id,
+    status: 'pending',
+    paymentLink: wayforpayUrl,
+    planId: 'premium_monthly',
+    amount: 99.99,
+    currency: 'USD',
+    createdAt: new Date().toISOString(),
+    platform: 'telegram',
+    provider: 'wayforpay',
+});
 
-// Custom masking
-const customMask = maskCardNumber('4532015112830366', 4, 'X');
-console.log(customMask); // 'XXXXXXXXXXXX0366'
+// Send link to user
+sendPaymentLink(payment.paymentLink);
 ```
 
-### Currency Formatting
+### 2. Wayforpay Webhook Handler
 
 ```typescript
-import { formatCurrency } from '@miit-bot/payment-utils';
+// Update payment status
+await paymentService.updateFields({
+    orderReference: webhookData.orderReference,
+    fields: [['status', 'completed']],
+});
 
-// Format as USD
-const usd = formatCurrency(1234.56);
-console.log(usd); // '$1,234.56'
+// Save invoice
+const invoice = await invoiceService.create({
+    merchantAccount: webhookData.merchantAccount,
+    orderReference: webhookData.orderReference,
+    merchantSignature: webhookData.merchantSignature,
+    reasonCode: webhookData.reasonCode,
+    reason: webhookData.reason,
+    createdDate: webhookData.createdDate,
+    processingDate: webhookData.processingDate,
+    currency: webhookData.currency,
+    amount: webhookData.amount,
+});
 
-// Format with custom locale and currency
-const eur = formatCurrency(1234.56, {
-  locale: 'de-DE',
-  currency: 'EUR',
+// Link invoice to payment
+await paymentService.updateFields({
+    orderReference: webhookData.orderReference,
+    fields: [['invoiceId', invoice.id]],
 });
-console.log(eur); // '1.234,56 €'
 ```
 
-### Expiry Date Formatting
+### 3. Cleanup Expired Payments (Cron Job)
 
 ```typescript
-import { formatExpiryDate } from '@miit-bot/payment-utils';
-
-// Format expiry date
-const expiry = formatExpiryDate(12, 2025);
-console.log(expiry); // '12/25'
+async function cleanupExpiredPayments() {
+    const expired = await paymentService.getExpiredPendingPayments({ hoursOld: 24 });
+
+    for (const payment of expired) {
+        await paymentService.updateFields({
+            orderReference: payment.orderReference,
+            fields: [['status', 'expired']],
+        });
+    }
+}
 ```
 
 ## API Reference
 
+### PaymentService
+
+**Methods:**
+
+- `getByOrderReference(orderReference: string): Promise<PaymentEntity | null>`
+- `getByUserId(params: { userId: string; appNamespace: AppNamespace; status?: PaymentStatus }): Promise<PaymentEntity[]>`
+- `create(paymentData: Omit<PaymentEntity, 'id'>): Promise<PaymentEntity>`
+- `updateFields(params: { orderReference: string; fields: UpdateDBPaymentFields }): Promise<void>`
+- `getExpiredPendingPayments(params?: { hoursOld?: number }): Promise<PaymentEntity[]>`
+
+### InvoiceService
+
+**Methods:**
+
+- `create(invoiceData: Omit<InvoiceEntity, 'id'>): Promise<InvoiceEntity>`
+- `getByOrderReference(orderReference: string): Promise<InvoiceEntity | null>`
+
 ### Types
 
-#### CardType
+#### PaymentEntity
 
 ```typescript
-enum CardType {
-  VISA = 'VISA',
-  MASTERCARD = 'MASTERCARD',
-  AMEX = 'AMEX',
-  DISCOVER = 'DISCOVER',
-  UNKNOWN = 'UNKNOWN',
+interface PaymentEntity {
+    id?: string;
+    orderReference: string;
+    userId: string;
+    status: 'pending' | 'completed' | 'failed' | 'expired';
+    paymentLink: string;
+    planId: string;
+    amount: number;
+    currency: 'UAH' | 'USD';
+    createdAt: string;
+    invoiceId?: string;
+    platform: AppNamespace;
+    provider: 'wayforpay';
 }
 ```
 
-#### CardValidationResult
+#### InvoiceEntity
 
 ```typescript
-interface CardValidationResult {
-  isValid: boolean;
-  cardType: CardType;
-  message?: string;
+interface InvoiceEntity {
+    id: string;
+    merchantAccount: string;
+    orderReference: string;
+    merchantSignature: string;
+    reasonCode: number;
+    reason: string;
+    createdDate: number;
+    processingDate: number;
+    currency: string;
+    amount: number;
 }
 ```
 
-#### AmountValidationResult
+#### Logger Interface
 
 ```typescript
-interface AmountValidationResult {
-  isValid: boolean;
-  amount?: number;
-  message?: string;
+interface Logger {
+    error(params: { message: string; payload?: any }): void;
+    info(params: { message: string; payload?: any }): void;
+    warn(params: { message: string; payload?: any }): void;
+    debug(params: { message: string; payload?: any }): void;
 }
 ```
 
-### Validators
+## Legacy Validation & Formatting
 
-#### validateCardNumber(cardNumber: string): CardValidationResult
-
-Validates a credit card number using the Luhn algorithm and detects the card type.
+### Card Validation
 
-#### validateAmount(amount: string | number, minAmount?: number, maxAmount?: number): AmountValidationResult
+```typescript
+import { validateCardNumber, CardType } from '@miit-bot/payment-utils';
 
-Validates a payment amount with optional min/max limits. Defaults: min=0.01, max=999999.99
+const result = validateCardNumber('4532015112830366');
+// { isValid: true, cardType: 'VISA', message: 'Valid card number' }
+```
 
-#### validateCVV(cvv: string, cardType?: CardType): boolean
+### Amount Validation
 
-Validates a CVV/CVC code. Returns true if valid (3 digits for most cards, 4 for Amex).
+```typescript
+import { validateAmount } from '@miit-bot/payment-utils';
 
-### Formatters
+const result = validateAmount(99.99);
+// { isValid: true, amount: 99.99, message: 'Valid amount' }
+```
 
-#### formatCardNumber(cardNumber: string, maskDigits?: boolean): string
+### CVV Validation
 
-Formats a card number with spaces. Optionally masks all but the last 4 digits.
+```typescript
+import { validateCVV, CardType } from '@miit-bot/payment-utils';
 
-#### formatCurrency(amount: number, options?: CurrencyFormatOptions): string
+const isValid = validateCVV('123'); // true
+const isValidAmex = validateCVV('1234', CardType.AMEX); // true
+```
 
-Formats a number as currency with internationalization support.
+### Card Formatting
 
-#### maskCardNumber(cardNumber: string, visibleDigits?: number, maskChar?: string): string
+```typescript
+import { formatCardNumber, maskCardNumber } from '@miit-bot/payment-utils';
 
-Masks a card number showing only the last N digits.
+formatCardNumber('4532015112830366'); // '4532 0151 1283 0366'
+formatCardNumber('4532015112830366', true); // '**** **** **** 0366'
+maskCardNumber('4532015112830366', 4, 'X'); // 'XXXXXXXXXXXX0366'
+```
 
-#### formatExpiryDate(month: number, year: number): string
+### Currency Formatting
 
-Formats an expiry date to MM/YY format.
+```typescript
+import { formatCurrency } from '@miit-bot/payment-utils';
 
-## Development
+formatCurrency(1234.56); // '$1,234.56'
+formatCurrency(1234.56, { locale: 'de-DE', currency: 'EUR' }); // '1.234,56 €'
+```
 
-### Setup
+### Expiry Date Formatting
 
-```bash
-# Install dependencies
-npm install
+```typescript
+import { formatExpiryDate } from '@miit-bot/payment-utils';
 
-# Build the library
-npm run build
+formatExpiryDate(12, 2025); // '12/25'
+```
 
-# Run linter
-npm run lint
+## Architecture
 
-# Format code
-npm run format
+**Service Layer** - Business logic and error handling
 
-# Watch mode for development
-npm run watch
-```
+- `PaymentService` - Payment operations
+- `InvoiceService` - Invoice operations
 
-### Building
+**Repository Layer** - Database operations
 
-The library is built using TypeScript compiler. The build output is in the `dist` folder with:
+- `PaymentRepository` - Firestore queries for payments
+- `InvoiceRepository` - Firestore queries for invoices
 
-- Compiled JavaScript files
-- Type declaration files (.d.ts)
-- Source maps
+Benefits: Clean separation, easy testing, type-safe.
 
-### Publishing
+## Development
 
 ```bash
-# Build and publish to npm
-npm publish
-```
+# Install
+npm install
 
-## License
+# Build
+npm run build
 
-MIT
+# Lint
+npm run lint
 
-## Contributing
+# Format
+npm run format
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+# Watch
+npm run watch
+```
 
-## Author
+### Dependencies
 
-Your Name
+- **firebase-admin** - Peer dependency for Firestore
+- **TypeScript** - Dev dependency
+- **ESLint** - Dev dependency
+- **Prettier** - Dev dependency
 
-## Repository
+## License
 
-https://github.com/yourusername/miit-bot-payment
+MIT

package/dist/index.d.ts

@@ -1,2 +1,3 @@
-export * from './modules/payments/repository';
+export * from './modules/payments';
+export * from './modules/invoice';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,+BAA+B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -14,5 +14,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./modules/payments/repository"), exports);
+__exportStar(require("./modules/payments"), exports);
+__exportStar(require("./modules/invoice"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,gEAA8C"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,qDAAmC;AACnC,oDAAkC"}

package/dist/modules/invoice/const.d.ts

@@ -0,0 +1,4 @@
+import { InvoiceEntity } from './types';
+declare const DEFAULT_INVOICE_ENTITY: Partial<InvoiceEntity>;
+export { DEFAULT_INVOICE_ENTITY };
+//# sourceMappingURL=const.d.ts.map

package/dist/modules/invoice/const.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"const.d.ts","sourceRoot":"","sources":["../../../src/modules/invoice/const.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAExC,QAAA,MAAM,sBAAsB,EAAE,OAAO,CAAC,aAAa,CAElD,CAAC;AAEF,OAAO,EAAE,sBAAsB,EAAE,CAAC"}

package/dist/modules/invoice/const.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_INVOICE_ENTITY = void 0;
+const DEFAULT_INVOICE_ENTITY = {
+    currency: 'UAH',
+};
+exports.DEFAULT_INVOICE_ENTITY = DEFAULT_INVOICE_ENTITY;
+//# sourceMappingURL=const.js.map

package/dist/modules/invoice/const.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"const.js","sourceRoot":"","sources":["../../../src/modules/invoice/const.ts"],"names":[],"mappings":";;;AAEA,MAAM,sBAAsB,GAA2B;IACnD,QAAQ,EAAE,KAAK;CAClB,CAAC;AAEO,wDAAsB"}

package/dist/modules/invoice/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './repository';
+export * from './service';
+export * from './const';
+//# sourceMappingURL=index.d.ts.map

package/dist/modules/invoice/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/invoice/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC"}

package/dist/modules/invoice/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./repository"), exports);
+__exportStar(require("./service"), exports);
+__exportStar(require("./const"), exports);
+//# sourceMappingURL=index.js.map

package/dist/modules/invoice/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/invoice/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,+CAA6B;AAC7B,4CAA0B;AAC1B,0CAAwB"}

package/dist/modules/invoice/repository.d.ts

@@ -0,0 +1,34 @@
+import { InvoiceEntity } from './types';
+/**
+ * InvoiceRepository class handles all database operations related to invoices.
+ * Implements repository pattern for invoice data access.
+ */
+declare class InvoiceRepository {
+    private readonly db;
+    private readonly collectionName;
+    /**
+     * Creates an instance of InvoiceRepository.
+     */
+    constructor();
+    /**
+     * Retrieves an invoice by its order reference.
+     * @param orderReference - The unique order reference identifier
+     * @returns Promise resolving to InvoiceEntity or null if not found
+     */
+    getByOrderReference(orderReference: string): Promise<InvoiceEntity | null>;
+    /**
+     * Creates a new invoice record in the database.
+     * @param invoiceData - Invoice data without ID (ID will be auto-generated)
+     * @returns Promise resolving to created InvoiceEntity with ID
+     * @throws Error if invoice creation fails
+     */
+    create(invoiceData: Omit<InvoiceEntity, 'id'>): Promise<InvoiceEntity>;
+    /**
+     * Maps a Firestore document to an InvoiceEntity.
+     * @param doc - Firestore document snapshot
+     * @returns InvoiceEntity with document ID
+     */
+    private mapDocumentToEntity;
+}
+export { InvoiceRepository };
+//# sourceMappingURL=repository.d.ts.map

package/dist/modules/invoice/repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../../src/modules/invoice/repository.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAGxC;;;GAGG;AACH,cAAM,iBAAiB;IACnB,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAY;IAC/B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAc;IAE7C;;OAEG;;IAKH;;;;OAIG;IACU,mBAAmB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAevF;;;;;OAKG;IACU,MAAM,CAAC,WAAW,EAAE,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC;IAkBnF;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;CAM9B;AAED,OAAO,EAAE,iBAAiB,EAAE,CAAC"}