# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a Visual FoxPro 9 project that interfaces with the GoMag e-commerce API. The application retrieves both product and order data from GoMag's REST API endpoints with full pagination support and comprehensive error handling.

## Architecture

- **Main Application**: `gomag-vending.prg` - Primary Visual FoxPro script with pagination support
- **Utility Module**: `utils.prg` - INI file handling, logging, and helper functions
- **JSON Library**: `nfjson/` - Third-party JSON parsing library for VFP
- **Technology**: Visual FoxPro 9 with WinHttp.WinHttpRequest.5.1 for HTTP requests
- **API Integration**: GoMag REST API v1 for products and orders management

## Core Components

### gomag-vending.prg
Main application script with:
- Complete pagination support for products and orders
- Configurable API settings via INI file
- Comprehensive error handling and logging
- Rate limiting compliance (1-second delays between requests)
- JSON array output generation for both products and orders

### utils.prg
Utility functions module containing:
- INI file operations (`ReadPini`, `WritePini`, `LoadSettings`)
- Logging system (`InitLog`, `LogMessage`, `CloseLog`)
- Connectivity testing (`TestConnectivity`)
- URL encoding utilities (`UrlEncode`)
- Default configuration creation (`CreateDefaultIni`)

### settings.ini
Configuration file with sections:
- `[API]` - API endpoints, credentials, and headers
- `[PAGINATION]` - Page size limits
- `[OPTIONS]` - Feature toggles for products/orders retrieval
- `[FILTERS]` - Date range filters for orders

## Development Commands

### Running the Application
```foxpro
DO gomag-vending.prg
```

### Running from Windows Command Line
Use the provided batch file:
```cmd
run-gomag.bat
```

Direct execution with Visual FoxPro:
```cmd
"C:\Program Files (x86)\Microsoft Visual FoxPro 9\vfp9.exe" -T "gomag-vending.prg"
```

## Configuration Management

The application uses `settings.ini` for all configuration. Key settings:

### Required Configuration
- `ApiKey` - Your GoMag API key
- `ApiShop` - Your shop URL (e.g., "https://yourstore.gomag.ro")

### Feature Control
- `GetProducts` - Set to "1" to retrieve products, "0" to skip
- `GetOrders` - Set to "1" to retrieve orders, "0" to skip
- `OrderDaysBack` - Number of days back to retrieve orders (default: 7)

### Pagination
- `Limit` - Records per page (default: 100, max recommended for GoMag API)

## API Integration Details

### Authentication
- Header-based authentication using `Apikey` and `ApiShop` headers
- User-Agent must differ from "PostmanRuntime"

### Endpoints
- Products: `https://api.gomag.ro/api/v1/product/read/json?enabled=1`
- Orders: `https://api.gomag.ro/api/v1/order/read/json`

### Rate Limiting
- 1-second pause between paginated requests
- No specific READ request limitations
- POST requests limited to ~1 request per second (Leaky Bucket)

## Directory Structure

```
/
├── gomag-vending.prg         # Main application
├── utils.prg                 # Utility functions
├── settings.ini              # Configuration file
├── run-gomag.bat            # Windows launcher
├── nfjson/                  # JSON parsing library
│   ├── nfjsoncreate.prg
│   └── nfjsonread.prg
├── log/                     # Generated log files
├── output/                  # Generated JSON files
└── products-example.json    # Sample API response
```

## Output Files

### Generated Files
- `log/gomag_sync_YYYYMMDD_HHMMSS.log` - Detailed execution logs
- `output/gomag_all_products_YYYYMMDD_HHMMSS.json` - Complete product array
- `output/gomag_orders_last7days_YYYYMMDD_HHMMSS.json` - Orders array

### Error Files
- `gomag_error_pageN_*.json` - Raw API responses for failed parsing
- `gomag_error_pageN_*.log` - HTTP error details with status codes

## Key Functions

### Main Application (gomag-vending.prg)
- `SaveProductsArray` - Converts paginated product data to JSON array
- `SaveOrdersArray` - Converts paginated order data to JSON array
- `MergeProducts` - Combines products from multiple pages
- `MergeOrdersArray` - Combines orders from multiple pages

### Utilities (utils.prg)
- `LoadSettings` - Loads complete INI configuration into object
- `InitLog`/`LogMessage`/`CloseLog` - Comprehensive logging system
- `TestConnectivity` - Internet connection verification
- `CreateDefaultIni` - Generates template configuration file