@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

npm install @cowris/paymentdb-client

Usage

Import the Prisma Client:

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: "[email protected]",
      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:

PAYMENT_DATABASE_URL="postgresql://username:password@localhost:5432/paymentdb"

Setup the database in microservice

Add this under scripts in package.json in the microservice:

{
  "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

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

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

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

const accountTransactions = await prisma.transaction.findMany({
  where: {
    account_id: "account-uuid",
    status: "success"
  },
  include: {
    funding_information: true,
    withdrawal_information: true
  }
});

Managing Currencies

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:

   npx prisma generate

3. Publish a New Version:

   • Update the package version in package.json.
   • Publish the updated package to your npm registry:

   npm publish --access public

4. Update in Microservices: Update the package in each microservice:

   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.