Skill: f-liva/fatsecret (version 1.1.0)

--- name: fatsecret description: FatSecret nutrition API integration for food search, nutritional lookup, barcode scanning, recipe search, and food diary logging. Use when user needs to find nutritional information for foods, search the food database, scan product barcodes, look up calories/macros/micronutrients, search for healthy recipes, or log meals to their FatSecret diary. metadata: credentials: required: - name: FATSECRET_CONSUMER_KEY description: FatSecret API Consumer Key (get from platform.fatsecret.com) - name: FATSECRET_CONSUMER_SECRET description: FatSecret API Consumer Secret optional: - name: FATSECRET_PROXY description: SOCKS5 proxy URL if FatSecret requires IP whitelisting (e.g., socks5://127.0.0.1:1080) - name: FATSECRET_CONFIG_DIR description: Custom config directory (default ~/.config/fatsecret). Use for persistent storage in containers. --- # FatSecret Nutrition API Complete integration with FatSecret for food data lookup AND diary logging. ## ⚠️ Authentication Methods This skill supports **two authentication methods** for different use cases: | Method | Use Case | User Login Required | Capabilities | |--------|----------|---------------------|--------------| | **OAuth2** (client_credentials) | Read-only access | ❌ No | Food search, barcode lookup, recipes | | **OAuth1** (3-legged) | Full access | ✅ Yes (one-time PIN) | All above + diary logging | ### Which to use? - **Just searching foods?** → OAuth2 (simpler, no user login) - **Logging to user's diary?** → OAuth1 (requires user authorization) ## 🚀 Quick Start ### 1. Get API Credentials 1. Go to https://platform.fatsecret.com 2. Register an application 3. Copy your **Consumer Key** and **Consumer Secret** ### 2. Save Credentials ```bash mkdir -p ~/.config/fatsecret cat > ~/.config/fatsecret/config.json << EOF { "consumer_key": "YOUR_CONSUMER_KEY", "consumer_secret": "YOUR_CONSUMER_SECRET" } EOF ``` ### 3. Install Dependencies ```bash cd /path/to/fatsecret-skill python3 -m venv venv source venv/bin/activate pip install -r requirements.txt ``` ### 4a. For Read-Only (OAuth2) - No user login needed ```bash # Search works immediately ./scripts/fatsecret-cli.sh search "chicken breast" ``` ### 4b. For Diary Logging (OAuth1) - One-time user authorization ```bash # Run authentication flow ./scripts/fatsecret-cli.sh auth # Follow prompts: # 1. Visit the authorization URL # 2. Log in with FatSecret account # 3. Authorize the app # 4. Enter the PIN shown # Now you can log foods ./scripts/fatsecret-cli.sh quick egg 3 Breakfast ``` ## 📋 CLI Commands | Command | Auth Required | Description | |---------|---------------|-------------| | `search <query>` | OAuth2 | Search foods | | `barcode <code>` | OAuth2 | Barcode lookup | | `recipes <query>` | OAuth2 | Search recipes | | `auth` | - | Run OAuth1 authentication | | `log` | OAuth1 | Add food to diary (interactive) | | `quick <food> [qty] [meal]` | OAuth1 | Quick log to diary | ## 🤖 Agent Integration ### For OpenClaw Agents ```python from scripts.fatsecret_agent_helper import ( get_authentication_flow, complete_authentication_flow, save_user_credentials ) # Check authentication status state = get_authentication_flow() if state["status"] == "need_credentials": # Ask user for Consumer Key/Secret # Save with: save_user_credentials(key, secret) pass elif state["status"] == "need_authorization": # Show authorization URL to user url = state["authorization_url"] # User visits URL, authorizes, gets PIN # Complete with: complete_authentication_flow(pin) pass elif state["status"] == "already_authenticated": # Ready to use diary functions from scripts.fatsecret_diary_simple import quick_log quick_log("egg", quantity=3, meal="Breakfast") ``` ### Agent Helper Functions | Function | Description | |----------|-------------| | `get_authentication_flow()` | Check status, returns next step | | `save_user_credentials(key, secret)` | Save API credentials | | `complete_authentication_flow(pin)` | Complete OAuth1 with PIN | | `quick_log(food, qty, meal)` | Log food to diary | | `log_food(food_id, serving_id, grams_or_ml, meal, name)` | Precise logging | | `search_food(query, tokens)` | Search foods | ### ⚠️ IMPORTANT: How `grams_or_ml` Works The `grams_or_ml` parameter (called `number_of_units` in FatSecret API) is the **ACTUAL amount**, not a multiplier! ```python # ❌ WRONG - This logs only 1.56 grams (7 kcal)! log_food(food_id, serving_100g_id, 1.56, "Breakfast", "Cookies") # ✅ CORRECT - This logs 156 grams (741 kcal) log_food(food_id, serving_100g_id, 156, "Breakfast", "Cookies") ``` **Examples:** | What you want | Serving type | grams_or_ml value | |---------------|--------------|-------------------| | 156g of cookies | "100g" serving | `156` | | 200ml of milk | "100ml" serving | `200` | | 3 eggs | "1 large egg" serving | `3` | | 2 slices of bread | "1 slice" serving | `2` | ## 🔐 Credential Storage All credentials and tokens are stored locally: | File | Contents | Created By | |------|----------|------------| | `$CONFIG_DIR/config.json` | Consumer Key/Secret | User (manual) | | `$CONFIG_DIR/oauth1_access_tokens.json` | OAuth1 access tokens | `auth` command | | `$CONFIG_DIR/token.json` | OAuth2 token (auto-refreshed) | OAuth2 client | Where `$CONFIG_DIR` is `~/.config/fatsecret` by default, or the value of `FATSECRET_CONFIG_DIR` if set. **To revoke access:** Delete the config folder and revoke app access from your FatSecret account settings. ### 🐳 Container/Docker Environments In containerized environments (Docker, OpenClaw sandbox), `~/.config/` may not persist across restarts. Use `FATSECRET_CONFIG_DIR` to point to a persistent volume: ```bash # Set env var to persistent directory export FATSECRET_CONFIG_DIR=[REDACTED_SECRET] # Or prefix commands FATSECRET_CONFIG_DIR="/persistent/path" ./scripts/fatsecret-cli.sh auth ``` **OpenClaw example** - add to your shell init or AGENTS.md: ```bash export FATSECRET_CONFIG_DIR=[REDACTED_SECRET] ``` ## 🌐 Proxy Configuration (Optional) Some FatSecret API plans require IP whitelisting. If needed, set a proxy: ```bash # Environment variable export FATSECRET_PROXY="socks5://127.0.0.1:1080" # Or in config.json { "consumer_key": "...", "consumer_secret": "...", "proxy": "socks5://127.0.0.1:1080" } ``` **If you don't need a proxy:** The skill works without it. Proxy is only required if FatSecret blocks your IP. ## 🌍 Open Food Facts (Alternative) For European products, use the free Open Food Facts API (no authentication): ```python from scripts.openfoodfacts_client import OpenFoodFactsClient off = OpenFoodFactsClient(country="it") products = off.search("barilla") product = off.get_product("8076800105735") # Barcode ``` ## 📁 File Structure ``` fatsecret/ ├── SKILL.md # This documentation ├── README.md # GitHub/ClawHub readme ├── requirements.txt # Python: requests, requests[socks] ├── scripts/ │ ├── fatsecret-cli.sh # Main CLI (bash wrapper) │ ├── fatsecret_auth.py # OAuth1 3-legged authentication │ ├── fatsecret_agent_helper.py # Helper functions for agents │ ├── fatsecret_diary_simple.py # Diary logging (OAuth1) │ ├── fatsecret_client.py # OAuth2 client (read-only) │ └── openfoodfacts_client.py # Open Food Facts client └── examples/ └── agent_usage_example.py # Agent integration example ``` ## ⚠️ Security Notes 1. **Credentials are stored locally** in `~/.config/fatsecret/` 2. **OAuth1 tokens don't expire** unless you revoke them 3. **OAuth1 grants full access** to your FatSecret diary (read + write) 4. **To uninstall safely:** Delete `~/.config/fatsecret/` and revoke app from FatSecret account ## 🔗 References - FatSecret API: https://platform.fatsecret.com/docs - OAuth1 Guide: https://platform.fatsecret.com/docs/guides/authentication/oauth1/three-legged - Open Food Facts: https://wiki.openfoodfacts.org/API ## Changelog ### v1.0.1 (2026-02-20) - Fixed OAuth2 client - now uses OAuth1 for all operations (food search + diary) - Unified authentication: single OAuth1 flow works for both read and write operations - Removed broken OAuth2 implementation


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: suspicious | SkillSpector: suspicious (CRITICAL)