@receeco/pos-agent/README.md

Receeco POS Integration Middleware Agent

# Receeco POS Agent

A lightweight middleware service that integrates with Point-of-Sale systems to generate instant digital receipts.

## Features

- **Real-time Integration**: Captures transaction data instantly from POS terminals
- **QR Code Generation**: Creates unique QR codes for each transaction
- **Offline Support**: Queues transactions when backend is unavailable
- **Short Code Generation**: 6-digit codes for manual entry
- **Zero Downtime**: Maintains existing paper receipt workflows

## Quick Start

### 1. Installation

```bash
npm install -g @receeco/pos-agent
```

### 2. Initialize Configuration

```bash
receeco-pos init --merchant-id=YOUR_MERCHANT_ID --api-key=YOUR_API_KEY
```

### 3. Start the Service

```bash
receeco-pos start
```

### 4. Test Integration

```bash
# Quick CLI test (built-in command)
receeco-pos test

# Visual browser-based testing
receeco-pos emulator
```

## API Endpoints

### POST /transactions

Process a new transaction and generate digital receipt.

**Request Body:**

```json
{
  "merchantId": "merchant_123",
  "merchantName": "Test Store",
  "items": [
    {
      "name": "Rice (5kg)",
      "quantity": 1,
      "unitPrice": 85.0,
      "totalPrice": 85.0
    }
  ],
  "totalAmount": 85.0,
  "currency": "NGN",
  "paymentMethod": "card",
  "timestamp": "2024-01-15T14:30:00Z"
}
```

**Response:**

```json
{
  "receiptId": "rcpt_abc123",
  "receiptUrl": "https://receeco.com/receipt/rcpt_abc123",
  "qrCodeUrl": "data:image/png;base64...",
  "qrCodeSvg": "<svg>...</svg>",
  "shortCode": "ABC123",
  "deepLinkUrl": "https://receeco.com/receipt/rcpt_abc123",
  "status": "success",
  "timestamp": "2024-01-15T14:30:00Z"
}
```

### GET /health

Check service health status.

### GET /queue/status

Check offline queue status.

## Configuration

Create a `.env` file with your configuration:

```env
MERCHANT_ID=your_merchant_id
RECEECO_API_KEY=your_api_key
RECEECO_API_URL=https://receeco.com/api
RECEECO_WEB_URL=https://receeco.com
PORT=3001
LOG_LEVEL=info

NODE_ENV=production
```

## POS Integration Examples

### Quickteller POS

Configure your POS to send transaction data to:

```
POST http://localhost:3001/transactions
```

### Phoenix POS

Use webhook integration:

```javascript
// In your POS system
fetch("http://localhost:3001/transactions", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(transactionData),
});
```

## CLI Commands

### Basic Commands
- `receeco-pos init` - Initialize configuration
- `receeco-pos start` - Start the service
- `receeco-pos status` - Check service status
- `receeco-pos test` - Test with sample transaction
- `receeco-pos emulator` - Open visual browser-based testing tool
- `receeco-pos clear-queue` - Clear failed transactions from queue

### Windows Service Management
- `receeco-pos install-service` - Install as Windows service
- `receeco-pos start-service` - Start Windows service
- `receeco-pos stop-service` - Stop Windows service
- `receeco-pos uninstall-service` - Remove Windows service

## Support

For integration support, contact the Receeco team or visit our documentation at https://docs.receeco.com