@cowris/paymentdb-client 1.0.0

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Cowris Payment Database Server
+
+MIT License
+
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,253 @@
+# @cowris/paymentdb-client
+
+A Prisma Client package for the Cowris PostgreSQL PaymentDB.
+
+## Description
+
+This package provides a centralized Prisma client for the Cowris PostgreSQL PaymentDB. It simplifies database access and ensures consistency by sharing the Prisma configuration and client instance. It offers a simple interface to interact with the Payment database, allowing you to perform CRUD operations on payment and transaction data and related tables.
+
+## Installation
+
+```bash
+npm install @cowris/paymentdb-client
+```
+
+## Usage
+
+### Import the Prisma Client:
+
+**JavaScript**
+```javascript
+const prisma = require('@cowris/paymentdb-client');
+
+async function main() {
+  // Get all transactions
+  const allTransactions = await prisma.transaction.findMany();
+  console.log(allTransactions);
+
+  // Create a new payment account
+  const newAccount = await prisma.paymentAccount.create({
+    data: {
+      account_number: "1234567890",
+      email: "user@example.com",
+      currency_id: "usd-currency-id",
+      wallet_id: "wallet-uuid"
+    }
+  });
+
+  // Get account with transactions
+  const accountWithTransactions = await prisma.paymentAccount.findUnique({
+    where: { id: "account-id" },
+    include: {
+      transactions: true,
+      currency: true,
+      managed_wallets: true
+    }
+  });
+}
+
+main()
+  .catch((e) => {
+    throw e;
+  })
+  .finally(async () => {
+    await prisma.$disconnect();
+  });
+```
+
+## Ensure Database Connection
+
+Make sure the microservice has the `PAYMENT_DATABASE_URL` environment variable set, pointing to the PostgreSQL database.
+
+Example:
+```bash
+PAYMENT_DATABASE_URL="postgresql://username:password@localhost:5432/paymentdb"
+```
+
+## Setup the database in microservice
+
+Add this under scripts in package.json in the microservice:
+
+```json
+{
+  "scripts": {
+    "setup-prisma:paymentdb": "node node_modules/@cowris/services-paymentdb/scripts/migrate.js || echo 'Migration failed. Please install the cowris paymentdb client. Run `npm install @cowris/services-paymentdb` to install it.'"
+  }
+}
+```
+
+## File Structure
+
+```
+@cowris/services-paymentdb/
+├── prisma/
+│   ├── migrations/
+│   ├── schema/
+│   │   ├── account.prisma
+│   │   ├── currency.prisma
+│   │   ├── funding.prisma
+│   │   ├── globalPaymentProvider.prisma
+│   │   ├── managedWallet.prisma
+│   │   ├── otp.prisma
+│   │   ├── reversal.prisma
+│   │   ├── transaction.prisma
+│   │   ├── transfer.prisma
+│   │   ├── withdrawal.prisma
+│   │   └── schema.prisma  // Main schema file
+│   └── .env
+├── scripts/
+│   └── migrate.js
+├── node_modules/
+├── package.json
+├── package-lock.json
+└── index.js
+```
+
+- `prisma/schema/`: Contains individual Prisma model files for different payment entities and the main schema.prisma file that combines them.
+- `prisma/migrations/`: Stores Prisma migration files (if used).
+- `prisma/.env`: Holds the database connection string (PAYMENT_DATABASE_URL).
+- `scripts/migrate.js`: Migration script for database setup.
+- `index.js`: Exports the Prisma client instance.
+
+## Schema Definition
+
+The Prisma schema is defined in the `prisma/schema` directory. Each model has its own `.prisma` file, and `schema.prisma` imports and combines them.
+
+### Key Models
+
+#### PaymentAccount
+```prisma
+model PaymentAccount {
+    id               String          @id @default(uuid())
+    account_number   String?         @unique
+    email            String?
+    currency_id      String
+    currency         Currency        @relation(fields: [currency_id], references: [id])
+    wallet_id        String          @unique
+    managed_wallets ManagedWallet[]
+    transactions     Transaction[]
+}
+```
+
+#### Transaction
+```prisma
+model Transaction {
+    id            String  @id @unique @default(uuid())
+    account_id     String
+    type          String  // funding, withdrawal, transfer, reversal
+    status        String  // initiated, pending, success, failed
+    metadata      Json?
+    provider_id   String?
+    reference_id  String?
+    created_at    DateTime @default(now())
+    
+    account       PaymentAccount @relation(fields: [account_id], references: [id])
+    // ... other relations
+}
+```
+
+### Available Models
+
+- **PaymentAccount**: Core account information with wallet associations
+- **Transaction**: All payment transactions (funding, withdrawal, transfer, reversal)
+- **Currency**: Supported currencies for payments
+- **ManagedWallet**: Wallet management information
+- **GlobalPaymentProvider**: Payment provider configurations
+- **Funding**: Funding transaction details
+- **Withdrawal**: Withdrawal transaction details
+- **Transfer**: Transfer transaction details
+- **Reversal**: Transaction reversal details
+- **OTP**: One-time password management
+
+## Common Operations
+
+### Creating a Transaction
+
+```javascript
+const transaction = await prisma.transaction.create({
+  data: {
+    account_id: "account-uuid",
+    type: "funding",
+    status: "initiated",
+    metadata: {
+      amount: 1000,
+      description: "Account funding"
+    },
+    provider_id: "provider-uuid"
+  }
+});
+```
+
+### Querying Account Balance
+
+```javascript
+const accountTransactions = await prisma.transaction.findMany({
+  where: {
+    account_id: "account-uuid",
+    status: "success"
+  },
+  include: {
+    funding_information: true,
+    withdrawal_information: true
+  }
+});
+```
+
+### Managing Currencies
+
+```javascript
+const supportedCurrencies = await prisma.currency.findMany({
+  where: {
+    is_active: true
+  }
+});
+```
+
+## Updating the Schema
+
+1. **Modify Model Files:**
+   Make changes to the relevant `.prisma` files in the `prisma/schema` directory.
+
+2. **Generate Prisma Client:**
+   Run the following command in the package's root directory:
+   ```bash
+   npx prisma generate
+   ```
+
+3. **Publish a New Version:**
+   - Update the package version in `package.json`.
+   - Publish the updated package to your npm registry:
+   ```bash
+   npm publish --access public
+   ```
+
+4. **Update in Microservices:**
+   Update the package in each microservice:
+   ```bash
+   npm update @cowris/services-paymentdb
+   ```
+
+## Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `PAYMENT_DATABASE_URL` | PostgreSQL connection string for payment database | Yes |
+
+## Security Considerations
+
+- **Database Credentials**: Do not hardcode database credentials. Use environment variables or secure credential management systems.
+- **Transaction Security**: Ensure proper validation and authorization for all payment operations.
+- **Data Encryption**: Sensitive payment data should be encrypted at rest and in transit.
+- **Access Control**: Implement proper access controls for payment operations.
+
+## Contributing
+
+Contributions are welcome. Please follow the standard pull request process and ensure all tests pass before submitting.
+
+## License
+
+ISC License
+
+## Support
+
+For issues and questions, please refer to the [GitHub repository](https://github.com/Cowristech/services-paymentdb).

package/index.d.ts

@@ -0,0 +1,6 @@
+import { PrismaClient } from './prisma/generated/paymentdb';
+
+
+declare module '@cowris/paymentdb-client' {
+  export const prisma: PrismaClient;
+}

package/index.js

@@ -0,0 +1,9 @@
+const { PrismaClient } = require('./prisma/generated/paymentdb');
+
+const prisma = new PrismaClient({
+  log: ['error', 'query', 'info', 'warn'],
+});
+
+module.exports = {
+  prisma,
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@cowris/paymentdb-client",
+  "version": "1.0.0",
+  "description": "This is a Prisma  Client package for the Cowris PaymentDB. It provides a simple interface to interact with the Payment database, allowing you to perform CRUD operations on payment and transaction data and related tables.",
+  "main": "index.js",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Cowristech/services-paymentdb.git"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "commonjs",
+  "bugs": {
+    "url": "https://github.com/Cowristech/services-paymentdb/issues"
+  },
+  "homepage": "https://github.com/Cowristech/services-paymentdb#readme",
+  "dependencies": {
+    "@prisma/client": "^6.6.0",
+    "dotenv": "^16.4.7",
+    "uuid": "^11.1.0"
+  },
+  "devDependencies": {
+    "prisma": "^6.6.0"
+  },
+  "peerDependencies": {
+    "@prisma/client": "^6.6.0",
+    "prisma": "^6.6.0"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "prisma",
+    "scripts"
+  ],
+  "prisma": {
+    "schema": "./prisma/schema"
+  }
+}

package/prisma/schema/account.prisma

@@ -0,0 +1,13 @@
+model PaymentAccount {
+    id               String          @id @default(uuid())
+    account_number   String?         @unique
+    email            String?
+    currency_id      String
+    currency         Currency        @relation(fields: [currency_id], references: [id])
+    wallet_id        String          @unique
+    managed_wallets ManagedWallet[]
+    transactions     Transaction[]
+
+    @@index([wallet_id], name: "wallet_id_index")
+    @@index([account_number], name: "wallet_account_number")
+}

package/prisma/schema/currency.prisma

@@ -0,0 +1,12 @@
+model Currency {
+    id         String   @id @default(uuid())
+    name       String   @unique
+    symbol     String
+    code       String?
+    country    String
+    created_at DateTime @default(now())
+    updated_at DateTime @updatedAt
+
+    payment_providers GlobalPaymentProvider[]
+    accounts PaymentAccount[]
+}

package/prisma/schema/funding.prisma

@@ -0,0 +1,24 @@
+model SenderAccountInformation {
+    id                String  @id @default(uuid())
+    account_firstname String? @default("")
+    account_lastname  String? @default("")
+    account_number    String?
+    account_email     String?
+    account_bank_name String?
+
+    funding Funding?
+}
+
+model Funding {
+    id                            String  @id @default(uuid())
+    transaction_id                String  @unique
+    account_id                    String
+    status                        String
+    amount                        String
+    source_currency_id            String?
+    destination_currency_id       String
+    sender_account_information_id String? @unique
+
+    transaction                Transaction?
+    sender_account_information SenderAccountInformation? @relation(fields: [sender_account_information_id], references: [id])
+}

package/prisma/schema/globalPaymentProvider.prisma

@@ -0,0 +1,9 @@
+model GlobalPaymentProvider {
+    id         String   @id @default(uuid())
+    name       String
+    supported_currencies Currency[]
+    created_at DateTime @default(now()) 
+    updated_at DateTime @updatedAt 
+
+    transactions Transaction[]
+}

package/prisma/schema/managedWallet.prisma

@@ -0,0 +1,17 @@
+model ManagedWallet {
+    id                         String   @id @default(uuid())
+    account_id                 String
+    customer_name              String?
+    wallet_identifier          String?
+    account_number             String?
+    email                      String?
+    balance                    String   @default("0.00")
+    currency_id                String
+    global_payment_provider_id String
+    type String
+    // Type can be either "static", "dynamic", "virtual-static", "virtual-dynamic"
+
+    created_at              DateTime              @default(now())
+    updated_at              DateTime              @updatedAt
+    payment_account         PaymentAccount        @relation(fields: [account_id], references: [id])
+}

package/prisma/schema/otp.prisma

@@ -0,0 +1,11 @@
+model Otp {
+  id        String   @id @default(uuid())
+  email     String
+  otp       String
+  created_at DateTime @default(now())
+  updated_at DateTime @default(now()) @updatedAt
+  expires_at DateTime
+
+  @@index([email], name: "otp_email_index")
+  @@index([otp], name: "otp_str_index")
+}

package/prisma/schema/reversal.prisma

@@ -0,0 +1,12 @@
+model Reversal {
+    id             String @id @default(uuid())
+    transaction_id String @unique
+    account_id      String
+    source_currency_id    String?
+    destination_currency_id String
+
+    amount String
+    status String
+
+    transaction Transaction?
+}

package/prisma/schema/schema.prisma

@@ -0,0 +1,9 @@
+generator client {
+  provider        = "prisma-client-js"
+  output   = "../generated/paymentdb"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("PAYMENT_DATABASE_URL")
+}

package/prisma/schema/transaction.prisma

@@ -0,0 +1,27 @@
+model Transaction {
+    id            String  @id @unique @default(uuid())
+    account_id     String
+    funding_id    String? @unique
+    withdrawal_id String? @unique
+    reversal_id   String? @unique
+    transfer_id   String? @unique
+
+    // Type can be funding, withdrawal, transfer, reversal
+    type String
+
+    // Status can be initiated, pending, success, failed
+    status       String
+    metadata     Json?
+    provider_id     String?
+    reference_id String?
+    created_at   DateTime @default(now())
+    upadated_at  DateTime @default(now())
+
+    provider GlobalPaymentProvider? @relation(fields: [provider_id], references: [id])
+    account PaymentAccount @relation(fields: [account_id], references: [id])
+
+    transfer_infomation    Transfer? @relation(fields: [transfer_id], references: [id])
+    funding_information    Funding? @relation(fields: [funding_id], references: [id])
+    withdrawal_information Withdrawal? @relation(fields: [withdrawal_id], references: [id])
+    reversal_information   Reversal? @relation(fields: [reversal_id], references: [id])
+}

package/prisma/schema/transfer.prisma

@@ -0,0 +1,25 @@
+model TransferDestinationAccountDetails {
+    id                String    @id @default(uuid())
+    account_firstname String    @default("")
+    account_lastname  String    @default("")
+    account_number    String?
+    account_email     String?
+    account_bank_name String?
+    Transfer          Transfer?
+}
+
+model Transfer {
+    id                             String  @id @default(uuid())
+    transaction_id                 String  @unique
+    from_account_id                String
+    to_account_id                  String?
+    destination_account_details_id String? @unique
+    source_currency_id             String  @unique
+    destination_currency_id        String  @unique
+    amount_in_source_currency      String
+    amount_in_destination_currency String
+    status                         String
+
+    transaction                 Transaction?
+    destination_account_details TransferDestinationAccountDetails? @relation(fields: [destination_account_details_id], references: [id])
+}

package/prisma/schema/withdrawal.prisma

@@ -0,0 +1,25 @@
+model WithdrawalDestinationAccountDetails {
+    id                String      @id @default(uuid())
+    account_firstname String      @default("")
+    account_lastname  String      @default("")
+    account_number    String?
+    account_email     String?
+    account_bank_name String?
+    withdrawal        Withdrawal?
+}
+
+model Withdrawal {
+    id                        String @id @default(uuid())
+    transaction_id            String @unique
+    from_account_id            String
+    amount_in_source_currency String
+    status                    String
+
+    destination_account_details_id String? @unique
+    source_currency_id             String  @unique
+    destination_currency_id        String  @unique
+    amount_in_destination_currency String
+
+    transaction                 Transaction?
+    destination_account_details WithdrawalDestinationAccountDetails? @relation(fields: [destination_account_details_id], references: [id])
+}

package/scripts/migrate.js

@@ -0,0 +1,54 @@
+require("dotenv").config(); 
+const { execSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+// Get the absolute path to the schema inside node_modules
+const packageRoot = path.resolve(__dirname, "..");  
+const schemaPath = path.join(packageRoot, "prisma/schema");
+
+// Ensure the schema file exists
+if (!fs.existsSync(schemaPath)) {
+  console.error(`❌ Prisma schema not found at expected path: ${schemaPath}`);
+  process.exit(1);
+}
+
+// Load the environment variables from the consuming microservice
+require("dotenv").config({ path: path.resolve(process.cwd(), ".env") });
+
+const DB_URL = process.env.PAYMENT_DATABASE_URL || "";
+const environment = process.env.NODE_ENV || "development";
+
+if (!DB_URL.includes("postgresql://") && !DB_URL.includes("postgresqls://")) {
+  console.error("❌ Invalid database URL. Provide a valid PostgreSQL connection string.");
+  process.exit(1);
+}
+
+const IS_PROD_DB = DB_URL.includes("prod") || environment === "production";
+const IS_TEST_DB = DB_URL.includes("test") || environment === "test";
+const IS_DEV_DB = DB_URL.includes("dev") || environment === "development";
+
+if (IS_PROD_DB) {
+  console.error("❌ Migrations are not allowed in production databases.");
+  process.exit(1);
+}
+
+if (!IS_TEST_DB && !IS_DEV_DB) {
+  console.log("⚠️ Migrations are disabled for production databases.");
+  process.exit(0);
+}
+
+console.log("🚀 Running Prisma migrations using the package schema...");
+
+try {
+  // Generate Prisma client using the correct schema path
+  execSync(`npx prisma generate --schema=${schemaPath}`, { stdio: "inherit" });
+
+  // Run migrations
+  execSync(`npx prisma migrate deploy --schema=${schemaPath}`, { stdio: "inherit" });
+
+  console.log("✅ Cowris PaymentDB Migrations applied successfully!");
+} catch (error) {
+  console.error("❌ Migration failed:", error.message);
+  process.exit(1);
+}