gomag-vending/CLAUDE.md

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

DO gomag-vending.prg

Running from Windows Command Line

Use the provided batch file:

run-gomag.bat

Direct execution with Visual FoxPro:

"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