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 main component is a script for retrieving product data from GoMag's REST API endpoints.

Architecture

• Single File Application: gomag-vending.prg - Main Visual FoxPro script
• Technology: Visual FoxPro 9 with WinHttp.WinHttpRequest.5.1 for HTTP requests
• API Integration: GoMag REST API v1 for product management

Core Components

gomag-vending.prg

Main script that handles:

• GoMag API authentication using Apikey and ApiShop headers
• HTTP GET requests to retrieve product data
• JSON response parsing and analysis
• File output for API responses (timestamped .json files)
• Error handling and connectivity testing

Key Configuration Variables

• lcApiUrl: GoMag API endpoint (defaults to product read endpoint)
• lcApiKey: GoMag API key (must be configured)
• lcApiShop: Shop URL (must be configured)

Development Commands

Running the Application

DO gomag-vending.prg

Running from Windows Command Line

Use the provided batch file for easy execution:

run-gomag.bat

Or directly with Visual FoxPro executable:

"C:\Program Files (x86)\Microsoft Visual FoxPro 9\vfp9.exe" -T "path\to\gomag-vending-test.prg"

The batch file uses %~dp0 to automatically detect the current directory, making it portable across different locations.

Testing Connectivity

The script includes a TestConnectivity() function for internet connectivity testing.

API Integration Details

Authentication

• Uses header-based authentication with Apikey and ApiShop headers
• Requires User-Agent to be different from "PostmanRuntime"

Endpoints Used

• Primary: https://api.gomag.ro/api/v1/product/read/json?enabled=1
• Supports pagination, filtering by category/brand, and sorting parameters

Rate Limiting

• No specific limitations for READ requests
• POST requests limited to ~1 request per second (Leaky Bucket algorithm)

File Structure

/
├── gomag-vending-test.prg    # Main application script
├── run-gomag.bat            # Windows batch file for easy execution
└── gomag_products_*.json    # Generated API response files (timestamped)

Configuration Requirements

Before running, update these variables in gomag-vending.prg:10-15:

1. lcApiKey - Your GoMag API key
2. lcApiShop - Your shop URL (e.g., "https://yourstore.gomag.ro")

Helper Functions

• ParseJsonResponse() - Basic JSON structure analysis
• TestConnectivity() - Internet connectivity testing
• UrlEncode() - URL parameter encoding utility