@doctech/fib/README.md

First Iraqi Bank payment integration for DocTech

# @doctech/fib

![npm](https://img.shields.io/npm/v/@doctech/fib)
![License](https://img.shields.io/npm/l/@doctech/fib)

A modern TypeScript/Node.js client for First Iraqi Bank payment integration.

## Features

- ✅ Create payment requests
- ✅ Check payment status
- ✅ Cancel payments
- ✅ TypeScript type definitions
- ✅ Modern Promise-based API

## Installation

```bash
npm install @doctech/fib
# or
yarn add @doctech/fib
# or
pnpm add @doctech/fib
```

## Quick Start

```typescript
import { FIBClient } from "@doctech/fib";

// Initialize client
const client = new FIBClient({
  clientId: "your_client_id",
  clientSecret: "your_client_secret",
  baseUrl: "https://api.fib.iq", // or your specific endpoint
});

// Create a payment
const payment = await client.createPayment({
  monetaryValue: {
    amount: "50000",
    currency: "IQD",
  },
  description: "Payment for order #1234",
  category: "ECOMMERCE",
});

console.log("Payment created:", payment);
console.log("QR Code:", payment.qrCode);
console.log("App Link:", payment.personalAppLink);

// Check payment status
const status = await client.getPaymentStatus(payment.paymentId);
console.log("Payment status:", status.status);

// Cancel a payment (if needed)
await client.cancelPayment(payment.paymentId);
```

## API Reference

### Configuration

```typescript
interface FIBConfig {
  clientId: string; // Your FIB client ID
  clientSecret: string; // Your FIB client secret
  baseUrl: string; // FIB API base URL
}
```

### Methods

#### createPayment(options)

Creates a new payment request.

```typescript
interface CreatePaymentOptions {
  monetaryValue: {
    amount: string;
    currency: "IQD";
  };
  statusCallbackUrl?: string;
  description?: string;
  expiresIn?: string;
  refundableFor?: string;
  category?: PaymentCategory;
}

// Available payment categories
type PaymentCategory =
  | "ERP"
  | "POS"
  | "ECOMMERCE"
  | "UTILITY"
  | "PAYROLL"
  | "SUPPLIER"
  | "LOAN"
  | "GOVERNMENT"
  | "MISCELLANEOUS"
  | "OTHER";
```

#### getPaymentStatus(paymentId)

Retrieves the current status of a payment.

#### cancelPayment(paymentId)

Cancels an existing payment.

## Error Handling

The client throws errors for various failure scenarios:

```typescript
try {
  const payment = await client.createPayment({
    /* ... */
  });
} catch (error) {
  console.error("Failed to create payment:", error);
}
```

## License

MIT © [Yad Hersh](https://github.com/YadaCoder)