npm package: @muhammedaksam/bulut-tahsilat-node
Description: TypeScript client SDK for BulutTahsilat Bank Payment Web Service
Author: Muhammed Mustafa AKŞAM
Latest version: 1.0.12

# BulutTahsilat Bank Payment Web Service Client SDK

[![npm version](https://img.shields.io/npm/v/@muhammedaksam/bulut-tahsilat-node.svg)](https://www.npmjs.com/package/@muhammedaksam/bulut-tahsilat-node)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
[![CI](https://github.com/muhammedaksam/bulut-tahsilat-node/workflows/CI/badge.svg)](https://github.com/muhammedaksam/bulut-tahsilat-node/actions)
[![codecov](https://codecov.io/gh/muhammedaksam/bulut-tahsilat-node/branch/main/graph/badge.svg)](https://codecov.io/gh/muhammedaksam/bulut-tahsilat-node)
[![Node.js](https://img.shields.io/badge/Node.js-20%2B-green.svg)](https://nodejs.org/)

An unofficial TypeScript client SDK for the BulutTahsilat Bank Payment Web Service.

A comprehensive TypeScript client SDK for the BulutTahsilat Bank Payment Web Service. This library provides type-safe access to all SOAP operations with a modern, intuitive API.

## Features

- 🚀 **TypeScript Client SDK** - Type-safe API client with full IntelliSense support
- 🧪 **Comprehensive Coverage** - 40+ methods covering all SOAP service endpoints
- ⚡ **Modern API** - Promise-based with async/await syntax
- 🔐 **Automatic Authentication** - Configure once, use everywhere
- 📝 **Full Type Definitions** - Catch errors at compile time
- 🛡️ **Error Handling** - Proper SOAP fault detection and reporting
- 🔍 **Debug Mode** - Request/response logging for development

## Installation

Install the SDK using your preferred package manager:

```bash
pnpm add @muhammedaksam/bulut-tahsilat-node
```

Or with npm:

```bash
npm install @muhammedaksam/bulut-tahsilat-node
```

Or with yarn:

```bash
yarn add @muhammedaksam/bulut-tahsilat-node
```

## Quick Start

```typescript
import { BankPaymentServiceClient, PaymentStatusType } from '@muhammedaksam/bulut-tahsilat-node';

// Initialize the client
const client = new BankPaymentServiceClient({
  userName: 'your-username',
  password: 'your-password',
  firmCode: 'your-firm-code',
  firmAPICode: 'your-firm-api-code',
});

// Get bank payment list
const payments = await client.getBankPaymentList({
  paymentStatusTypeID: PaymentStatusType.Waiting,
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
});

console.log(payments);
```

## Configuration

### Client Options

```typescript
interface ClientConfig {
  /** Username for authentication (required) */
  userName: string;

  /** Password for authentication (required) */
  password: string;

  /** Firm code for operations requiring firmCode */
  firmCode?: string;

  /** Firm API code for operations requiring firmAPICode */
  firmAPICode?: string;

  /** Base URL of the SOAP service (default: https://ws.buluttahsilat.com/WebService/WSBankPaymentService.asmx) */
  baseURL?: string;

  /** Request timeout in milliseconds (default: 30000) */
  timeout?: number;

  /** Enable debug logging (default: false) */
  debug?: boolean;
}
```

### Example Configuration

```typescript
const client = new BankPaymentServiceClient({
  userName: process.env.BULUT_USERNAME!,
  password: process.env.BULUT_PASSWORD!,
  firmCode: process.env.BULUT_FIRM_CODE,
  firmAPICode: process.env.BULUT_API_CODE,
  timeout: 60000,
  debug: process.env.NODE_ENV === 'development',
});
```

## API Reference

### Bank Payment Operations

#### getBankPaymentList

Get bank payment list filtered by status and date range.

```typescript
const payments = await client.getBankPaymentList({
  paymentStatusTypeID: PaymentStatusType.Waiting,
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
});
```

#### getBankPaymentListDebit

Get debit bank payments only.

```typescript
const debitPayments = await client.getBankPaymentListDebit({
  paymentStatusTypeID: PaymentStatusType.Approved,
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
});
```

#### getBankPaymentListAll

Get all bank payments (both credit and debit).

```typescript
const allPayments = await client.getBankPaymentListAll({
  paymentStatusTypeID: PaymentStatusType.Approved,
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
});
```

#### getBankPaymentListAllSubFirm

Get bank payments for all sub-firms, optionally filtered by tax number.

```typescript
const subFirmPayments = await client.getBankPaymentListAllSubFirm({
  paymentStatusTypeID: PaymentStatusType.Waiting,
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
  taxNumber: '1234567890',
});
```

#### getBankPaymentListAllWithFeature

Get bank payments with additional feature fields.

```typescript
const featuredPayments = await client.getBankPaymentListAllWithFeature({
  paymentStatusTypeID: PaymentStatusType.Approved,
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
});
```

#### getBankPaymentListForCustomFields

Get bank payments including custom fields.

```typescript
const customPayments = await client.getBankPaymentListForCustomFields({
  paymentStatusTypeID: PaymentStatusType.Waiting,
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
});
```

#### getPaymentCategoryList

Get list of all payment categories.

```typescript
const categories = await client.getPaymentCategoryList();
```

### Payment Status Operations

#### updatePaymentStatus

Update the status of a single payment.

```typescript
await client.updatePaymentStatus(
  12345, // paymentID
  PaymentStatusType.Approved
);
```

#### updatePaymentStatusWithExpCode

Update payment status using payment expense code.

```typescript
const result = await client.updatePaymentStatusWithExpCode(
  12345,
  'EXP-CODE-001',
  PaymentStatusType.Approved
);
```

#### updatePaymentStatusWithIDList

Update status for multiple payments at once.

```typescript
await client.updatePaymentStatusWithIDList([12345, 12346, 12347], PaymentStatusType.Approved);
```

#### updatePaymentStatusWithERPRefNo

Update payment status with ERP reference number.

```typescript
await client.updatePaymentStatusWithERPRefNo(12345, PaymentStatusType.Approved, 'ERP-REF-001');
```

### SubFirm Operations

#### addSubFirm

Create a new sub-firm.

```typescript
import { EnumStatus } from '@muhammedaksam/bulut-tahsilat-node';

const result = await client.addSubFirm({
  subFirm: {
    FirmName: 'Test Company Ltd.',
    Address: '123 Main Street',
    County: 'District',
    CityID: 34,
    Phone: '+905551234567',
    TaxOffice: 'Tax Office Name',
    TaxNumber: '1234567890',
    AuthPersName: 'John',
    AuthPersSurname: 'Doe',
    AuthPersGSM: '+905551234567',
    AuthPersGenderID: 1,
    Status: EnumStatus.Active,
    DealerCode: 'DEALER001',
    BusinessArea: 'BA001',
    AccountingCode: 'AC001',
    ReservedField: 'Reserved',
  },
});
```

#### getSubFirmList

Get list of all sub-firms.

```typescript
const subFirms = await client.getSubFirmList();
```

#### getSubFirmInfo

Get details of a specific sub-firm.

```typescript
const info = await client.getSubFirmInfo('PAYMENT-EXP-CODE');
```

#### updateSubFirm

Update an existing sub-firm.

```typescript
await client.updateSubFirm({
  paymentExpCode: 'PAYMENT-EXP-CODE',
  subFirm: {
    FirmName: 'Updated Company Name',
    // ... other fields
  },
});
```

#### addSubFirmIBAN / deleteSubFirmIBAN

Manage IBANs for a sub-firm.

```typescript
// Add IBAN
await client.addSubFirmIBAN({
  paymentExpCode: 'PAYMENT-EXP-CODE',
  iban: 'TR330006100519786457841326',
  bankCode: '0001',
});

// Delete IBAN
await client.deleteSubFirmIBAN({
  paymentExpCode: 'PAYMENT-EXP-CODE',
  iban: 'TR330006100519786457841326',
  bankCode: '0001',
});
```

#### addSubFirmVKN / deleteSubFirmVKN

Manage tax numbers (VKN) for a sub-firm.

```typescript
// Add VKN
await client.addSubFirmVKN({
  paymentExpCode: 'PAYMENT-EXP-CODE',
  vkn: '1234567890',
  name: 'John',
  surname: 'Doe',
});

// Delete VKN
await client.deleteSubFirmVKN({
  paymentExpCode: 'PAYMENT-EXP-CODE',
  vkn: '1234567890',
});
```

#### getSubFirmPaymentChannel

Get payment channel configuration for a sub-firm.

```typescript
const channel = await client.getSubFirmPaymentChannel('PAYMENT-EXP-CODE');
console.log(channel.IBANList);
console.log(channel.VKNList);
console.log(channel.FormulaList);
```

#### deleteAllMatchingCriteria

Delete all matching criteria for a sub-firm.

```typescript
const result = await client.deleteAllMatchingCriteria('PAYMENT-EXP-CODE');
```

### Bank Balance Operations

#### getFirmBankBalance

Get current bank balance for all accounts or a specific IBAN.

```typescript
// All accounts
const balance = await client.getFirmBankBalance();

// Specific IBAN
const ibanBalance = await client.getFirmBankBalance('TR330006100519786457841326');
```

#### getFirmBankBalanceSubFirm

Get bank balance for a sub-firm.

```typescript
const balance = await client.getFirmBankBalanceSubFirm(
  'TR330006100519786457841326',
  '1234567890' // tax number
);
```

#### getFirmBankDailyBalance

Get bank balance for a specific date.

```typescript
const dailyBalance = await client.getFirmBankDailyBalance(
  'TR330006100519786457841326',
  new Date('2024-01-15')
);
```

### POS Payment Operations

#### getPosPaymentList

Get POS payment transactions.

```typescript
const posPayments = await client.getPosPaymentList({
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
});
```

#### getPosPaymentListWithValorDate

Get POS payments filtered by valor date.

```typescript
const payments = await client.getPosPaymentListWithValorDate({
  valorStartDate: new Date('2024-01-01'),
  valorEndDate: new Date('2024-01-31'),
});
```

#### getPosPaymentListWithEndOfDay

Get POS payments filtered by end of day date.

```typescript
const payments = await client.getPosPaymentListWithEndOfDay({
  endOfDayStartDate: new Date('2024-01-01'),
  endOfDayEndDate: new Date('2024-01-31'),
});
```

#### getPosPaymentSUM / getValorPaymentSUM

Get sum of POS payments.

```typescript
const sum = await client.getPosPaymentSUM({
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
});

const valorSum = await client.getValorPaymentSUM({
  valorStartDate: new Date('2024-01-01'),
  valorEndDate: new Date('2024-01-31'),
});
```

#### getPosPaymentListGreaterThanID

Incrementally fetch POS payments (for pagination/sync).

```typescript
const newPayments = await client.getPosPaymentListGreaterThanID({
  posPaymentID: 1000,
});
```

#### getPosReturnList

Get POS return transactions.

```typescript
const returns = await client.getPosReturnList({
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
});
```

### Other Operations

#### getFirmDebtInfo

Get firm debt information.

```typescript
const debtInfo = await client.getFirmDebtInfo();
```

#### getVPosTransactionList

Get virtual POS transaction list.

```typescript
const vposTransactions = await client.getVPosTransactionList({
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
});
```

#### getFirmManagerList / addFirmManager / deleteFirmManager

Manage firm managers.

```typescript
// Get list
const managers = await client.getFirmManagerList();

// Add manager
await client.addFirmManager({
  /* params */
});

// Delete manager
await client.deleteFirmManager({
  /* params */
});
```

## Type Definitions

### Enums

```typescript
// Payment status types
enum PaymentStatusType {
  Waiting = 1,
  Approved = 2,
  Rejected = 3,
  Cancelled = 4,
}

// Entity status
enum EnumStatus {
  Active = 'Active',
  Passive = 'Passive',
}

// Account type
enum AccountType {
  Current = 1,
  Savings = 2,
}

// Gender
enum Gender {
  Male = 1,
  Female = 2,
}
```

### Common Interfaces

See the [full type definitions](./src/types) for all available interfaces.

## Error Handling

The client automatically handles SOAP faults and HTTP errors.

```typescript
try {
  const payments = await client.getBankPaymentList({
    paymentStatusTypeID: PaymentStatusType.Waiting,
    startDate: new Date('2024-01-01'),
    endDate: new Date('2024-01-31'),
  });
} catch (error) {
  if (error instanceof Error) {
    if (error.message.includes('SOAP Fault')) {
      console.error('SOAP Error:', error.message);
    } else if (error.message.includes('HTTP Error')) {
      console.error('Network Error:', error.message);
    } else {
      console.error('Unknown Error:', error.message);
    }
  }
}
```

## Available Scripts

### Development

```bash
pnpm run dev              # Watch mode
pnpm run build:watch      # Build in watch mode
```

### Testing

```bash
pnpm run test             # Run tests
pnpm run test:watch       # Run tests in watch mode
pnpm run test:coverage    # Run tests with coverage
pnpm run test:light       # Light test mode
pnpm run test:serial      # Run tests serially
pnpm run test:bail        # Stop on first error
```

### Code Quality

```bash
pnpm run lint             # Run ESLint
pnpm run lint:fix         # Fix ESLint issues
pnpm run format           # Format code with Prettier
pnpm run format:check     # Check formatting
pnpm run fix              # Fix lint and format issues
```

### Utilities

```bash
pnpm run clean            # Clean build artifacts
```

## Development

This project uses [pnpm](https://pnpm.io/) for package management.

### Prerequisites

- Node.js 20 or higher
- pnpm 10.23.0 or higher

Install pnpm globally if you haven't already:

```bash
npm install -g pnpm
```

### Install Dependencies

```bash
pnpm install
```

### Build the Project

```bash
pnpm run build
```

### Development Setup

1. Install dependencies: `pnpm install`
2. Run tests: `pnpm test`
3. Start development mode: `pnpm run dev`

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Disclaimer

This is an unofficial SDK for BulutTahsilat Bank Payment Web Service. Please refer to the [official BulutTahsilat documentation](https://ws.buluttahsilat.com/WebService/WSBankPaymentService.asmx) for the most up-to-date API information.

## Credits

This SDK is built based on the official BulutTahsilat Bank Payment Web Service available at [https://ws.buluttahsilat.com/WebService/WSBankPaymentService.asmx](https://ws.buluttahsilat.com/WebService/WSBankPaymentService.asmx).

## Support

If you encounter any issues or have questions, please [open an issue](https://github.com/muhammedaksam/bulut-tahsilat-node/issues) on GitHub.