Initial commit with current state

2025-08-28 00:28:20 +03:00
commit 9d3fa2bf9e
13 changed files with 2800 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,130 @@
+# 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