{
  "schemaVersion": "1.0",
  "item": {
    "slug": "fatsecret",
    "name": "Fatsecret",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/f-liva/fatsecret",
    "canonicalUrl": "https://clawhub.ai/f-liva/fatsecret",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/fatsecret",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=fatsecret",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "README.md",
      "SKILL.md",
      "examples/agent_usage_example.py",
      "references/api.md",
      "requirements.txt",
      "scripts/fatsecret-cli.sh"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/fatsecret"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/fatsecret",
    "agentPageUrl": "https://openagent3.xyz/skills/fatsecret/agent",
    "manifestUrl": "https://openagent3.xyz/skills/fatsecret/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/fatsecret/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "FatSecret Nutrition API",
        "body": "Complete integration with FatSecret for food data lookup AND diary logging."
      },
      {
        "title": "⚠️ Authentication Methods",
        "body": "This skill supports two authentication methods for different use cases:\n\nMethodUse CaseUser Login RequiredCapabilitiesOAuth2 (client_credentials)Read-only access❌ NoFood search, barcode lookup, recipesOAuth1 (3-legged)Full access✅ Yes (one-time PIN)All above + diary logging"
      },
      {
        "title": "Which to use?",
        "body": "Just searching foods? → OAuth2 (simpler, no user login)\nLogging to user's diary? → OAuth1 (requires user authorization)"
      },
      {
        "title": "1. Get API Credentials",
        "body": "Go to https://platform.fatsecret.com\nRegister an application\nCopy your Consumer Key and Consumer Secret"
      },
      {
        "title": "2. Save Credentials",
        "body": "mkdir -p ~/.config/fatsecret\ncat > ~/.config/fatsecret/config.json << EOF\n{\n  \"consumer_key\": \"YOUR_CONSUMER_KEY\",\n  \"consumer_secret\": \"YOUR_CONSUMER_SECRET\"\n}\nEOF"
      },
      {
        "title": "3. Install Dependencies",
        "body": "cd /path/to/fatsecret-skill\npython3 -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt"
      },
      {
        "title": "4a. For Read-Only (OAuth2) - No user login needed",
        "body": "# Search works immediately\n./scripts/fatsecret-cli.sh search \"chicken breast\""
      },
      {
        "title": "4b. For Diary Logging (OAuth1) - One-time user authorization",
        "body": "# Run authentication flow\n./scripts/fatsecret-cli.sh auth\n\n# Follow prompts:\n# 1. Visit the authorization URL\n# 2. Log in with FatSecret account\n# 3. Authorize the app\n# 4. Enter the PIN shown\n\n# Now you can log foods\n./scripts/fatsecret-cli.sh quick egg 3 Breakfast"
      },
      {
        "title": "📋 CLI Commands",
        "body": "CommandAuth RequiredDescriptionsearch <query>OAuth2Search foodsbarcode <code>OAuth2Barcode lookuprecipes <query>OAuth2Search recipesauth-Run OAuth1 authenticationlogOAuth1Add food to diary (interactive)quick <food> [qty] [meal]OAuth1Quick log to diary"
      },
      {
        "title": "For OpenClaw Agents",
        "body": "from scripts.fatsecret_agent_helper import (\n    get_authentication_flow,\n    complete_authentication_flow,\n    save_user_credentials\n)\n\n# Check authentication status\nstate = get_authentication_flow()\n\nif state[\"status\"] == \"need_credentials\":\n    # Ask user for Consumer Key/Secret\n    # Save with: save_user_credentials(key, secret)\n    pass\n\nelif state[\"status\"] == \"need_authorization\":\n    # Show authorization URL to user\n    url = state[\"authorization_url\"]\n    # User visits URL, authorizes, gets PIN\n    # Complete with: complete_authentication_flow(pin)\n    pass\n\nelif state[\"status\"] == \"already_authenticated\":\n    # Ready to use diary functions\n    from scripts.fatsecret_diary_simple import quick_log\n    quick_log(\"egg\", quantity=3, meal=\"Breakfast\")"
      },
      {
        "title": "Agent Helper Functions",
        "body": "FunctionDescriptionget_authentication_flow()Check status, returns next stepsave_user_credentials(key, secret)Save API credentialscomplete_authentication_flow(pin)Complete OAuth1 with PINquick_log(food, qty, meal)Log food to diarylog_food(food_id, serving_id, grams_or_ml, meal, name)Precise loggingsearch_food(query, tokens)Search foods"
      },
      {
        "title": "⚠️ IMPORTANT: How grams_or_ml Works",
        "body": "The grams_or_ml parameter (called number_of_units in FatSecret API) is the ACTUAL amount, not a multiplier!\n\n# ❌ WRONG - This logs only 1.56 grams (7 kcal)!\nlog_food(food_id, serving_100g_id, 1.56, \"Breakfast\", \"Cookies\")\n\n# ✅ CORRECT - This logs 156 grams (741 kcal)\nlog_food(food_id, serving_100g_id, 156, \"Breakfast\", \"Cookies\")\n\nExamples:\n\nWhat you wantServing typegrams_or_ml value156g of cookies\"100g\" serving156200ml of milk\"100ml\" serving2003 eggs\"1 large egg\" serving32 slices of bread\"1 slice\" serving2"
      },
      {
        "title": "🔐 Credential Storage",
        "body": "All credentials and tokens are stored locally:\n\nFileContentsCreated By$CONFIG_DIR/config.jsonConsumer Key/SecretUser (manual)$CONFIG_DIR/oauth1_access_tokens.jsonOAuth1 access tokensauth command$CONFIG_DIR/token.jsonOAuth2 token (auto-refreshed)OAuth2 client\n\nWhere $CONFIG_DIR is ~/.config/fatsecret by default, or the value of FATSECRET_CONFIG_DIR if set.\n\nTo revoke access: Delete the config folder and revoke app access from your FatSecret account settings."
      },
      {
        "title": "🐳 Container/Docker Environments",
        "body": "In containerized environments (Docker, OpenClaw sandbox), ~/.config/ may not persist across restarts. Use FATSECRET_CONFIG_DIR to point to a persistent volume:\n\n# Set env var to persistent directory\nexport FATSECRET_CONFIG_DIR=\"/home/node/clawd/config/fatsecret\"\n\n# Or prefix commands\nFATSECRET_CONFIG_DIR=\"/persistent/path\" ./scripts/fatsecret-cli.sh auth\n\nOpenClaw example - add to your shell init or AGENTS.md:\n\nexport FATSECRET_CONFIG_DIR=\"/home/node/clawd/config/fatsecret\""
      },
      {
        "title": "🌐 Proxy Configuration (Optional)",
        "body": "Some FatSecret API plans require IP whitelisting. If needed, set a proxy:\n\n# Environment variable\nexport FATSECRET_PROXY=\"socks5://127.0.0.1:1080\"\n\n# Or in config.json\n{\n  \"consumer_key\": \"...\",\n  \"consumer_secret\": \"...\",\n  \"proxy\": \"socks5://127.0.0.1:1080\"\n}\n\nIf you don't need a proxy: The skill works without it. Proxy is only required if FatSecret blocks your IP."
      },
      {
        "title": "🌍 Open Food Facts (Alternative)",
        "body": "For European products, use the free Open Food Facts API (no authentication):\n\nfrom scripts.openfoodfacts_client import OpenFoodFactsClient\n\noff = OpenFoodFactsClient(country=\"it\")\nproducts = off.search(\"barilla\")\nproduct = off.get_product(\"8076800105735\")  # Barcode"
      },
      {
        "title": "📁 File Structure",
        "body": "fatsecret/\n├── SKILL.md                      # This documentation\n├── README.md                     # GitHub/ClawHub readme\n├── requirements.txt              # Python: requests, requests[socks]\n├── scripts/\n│   ├── fatsecret-cli.sh          # Main CLI (bash wrapper)\n│   ├── fatsecret_auth.py         # OAuth1 3-legged authentication\n│   ├── fatsecret_agent_helper.py # Helper functions for agents\n│   ├── fatsecret_diary_simple.py # Diary logging (OAuth1)\n│   ├── fatsecret_client.py       # OAuth2 client (read-only)\n│   └── openfoodfacts_client.py   # Open Food Facts client\n└── examples/\n    └── agent_usage_example.py    # Agent integration example"
      },
      {
        "title": "⚠️ Security Notes",
        "body": "Credentials are stored locally in ~/.config/fatsecret/\nOAuth1 tokens don't expire unless you revoke them\nOAuth1 grants full access to your FatSecret diary (read + write)\nTo uninstall safely: Delete ~/.config/fatsecret/ and revoke app from FatSecret account"
      },
      {
        "title": "🔗 References",
        "body": "FatSecret API: https://platform.fatsecret.com/docs\nOAuth1 Guide: https://platform.fatsecret.com/docs/guides/authentication/oauth1/three-legged\nOpen Food Facts: https://wiki.openfoodfacts.org/API"
      },
      {
        "title": "v1.0.1 (2026-02-20)",
        "body": "Fixed OAuth2 client - now uses OAuth1 for all operations (food search + diary)\nUnified authentication: single OAuth1 flow works for both read and write operations\nRemoved broken OAuth2 implementation"
      }
    ],
    "body": "FatSecret Nutrition API\n\nComplete integration with FatSecret for food data lookup AND diary logging.\n\n⚠️ Authentication Methods\n\nThis skill supports two authentication methods for different use cases:\n\nMethod\tUse Case\tUser Login Required\tCapabilities\nOAuth2 (client_credentials)\tRead-only access\t❌ No\tFood search, barcode lookup, recipes\nOAuth1 (3-legged)\tFull access\t✅ Yes (one-time PIN)\tAll above + diary logging\nWhich to use?\nJust searching foods? → OAuth2 (simpler, no user login)\nLogging to user's diary? → OAuth1 (requires user authorization)\n🚀 Quick Start\n1. Get API Credentials\nGo to https://platform.fatsecret.com\nRegister an application\nCopy your Consumer Key and Consumer Secret\n2. Save Credentials\nmkdir -p ~/.config/fatsecret\ncat > ~/.config/fatsecret/config.json << EOF\n{\n  \"consumer_key\": \"YOUR_CONSUMER_KEY\",\n  \"consumer_secret\": \"YOUR_CONSUMER_SECRET\"\n}\nEOF\n\n3. Install Dependencies\ncd /path/to/fatsecret-skill\npython3 -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt\n\n4a. For Read-Only (OAuth2) - No user login needed\n# Search works immediately\n./scripts/fatsecret-cli.sh search \"chicken breast\"\n\n4b. For Diary Logging (OAuth1) - One-time user authorization\n# Run authentication flow\n./scripts/fatsecret-cli.sh auth\n\n# Follow prompts:\n# 1. Visit the authorization URL\n# 2. Log in with FatSecret account\n# 3. Authorize the app\n# 4. Enter the PIN shown\n\n# Now you can log foods\n./scripts/fatsecret-cli.sh quick egg 3 Breakfast\n\n📋 CLI Commands\nCommand\tAuth Required\tDescription\nsearch <query>\tOAuth2\tSearch foods\nbarcode <code>\tOAuth2\tBarcode lookup\nrecipes <query>\tOAuth2\tSearch recipes\nauth\t-\tRun OAuth1 authentication\nlog\tOAuth1\tAdd food to diary (interactive)\nquick <food> [qty] [meal]\tOAuth1\tQuick log to diary\n🤖 Agent Integration\nFor OpenClaw Agents\nfrom scripts.fatsecret_agent_helper import (\n    get_authentication_flow,\n    complete_authentication_flow,\n    save_user_credentials\n)\n\n# Check authentication status\nstate = get_authentication_flow()\n\nif state[\"status\"] == \"need_credentials\":\n    # Ask user for Consumer Key/Secret\n    # Save with: save_user_credentials(key, secret)\n    pass\n\nelif state[\"status\"] == \"need_authorization\":\n    # Show authorization URL to user\n    url = state[\"authorization_url\"]\n    # User visits URL, authorizes, gets PIN\n    # Complete with: complete_authentication_flow(pin)\n    pass\n\nelif state[\"status\"] == \"already_authenticated\":\n    # Ready to use diary functions\n    from scripts.fatsecret_diary_simple import quick_log\n    quick_log(\"egg\", quantity=3, meal=\"Breakfast\")\n\nAgent Helper Functions\nFunction\tDescription\nget_authentication_flow()\tCheck status, returns next step\nsave_user_credentials(key, secret)\tSave API credentials\ncomplete_authentication_flow(pin)\tComplete OAuth1 with PIN\nquick_log(food, qty, meal)\tLog food to diary\nlog_food(food_id, serving_id, grams_or_ml, meal, name)\tPrecise logging\nsearch_food(query, tokens)\tSearch foods\n⚠️ IMPORTANT: How grams_or_ml Works\n\nThe grams_or_ml parameter (called number_of_units in FatSecret API) is the ACTUAL amount, not a multiplier!\n\n# ❌ WRONG - This logs only 1.56 grams (7 kcal)!\nlog_food(food_id, serving_100g_id, 1.56, \"Breakfast\", \"Cookies\")\n\n# ✅ CORRECT - This logs 156 grams (741 kcal)\nlog_food(food_id, serving_100g_id, 156, \"Breakfast\", \"Cookies\")\n\n\nExamples:\n\nWhat you want\tServing type\tgrams_or_ml value\n156g of cookies\t\"100g\" serving\t156\n200ml of milk\t\"100ml\" serving\t200\n3 eggs\t\"1 large egg\" serving\t3\n2 slices of bread\t\"1 slice\" serving\t2\n🔐 Credential Storage\n\nAll credentials and tokens are stored locally:\n\nFile\tContents\tCreated By\n$CONFIG_DIR/config.json\tConsumer Key/Secret\tUser (manual)\n$CONFIG_DIR/oauth1_access_tokens.json\tOAuth1 access tokens\tauth command\n$CONFIG_DIR/token.json\tOAuth2 token (auto-refreshed)\tOAuth2 client\n\nWhere $CONFIG_DIR is ~/.config/fatsecret by default, or the value of FATSECRET_CONFIG_DIR if set.\n\nTo revoke access: Delete the config folder and revoke app access from your FatSecret account settings.\n\n🐳 Container/Docker Environments\n\nIn containerized environments (Docker, OpenClaw sandbox), ~/.config/ may not persist across restarts. Use FATSECRET_CONFIG_DIR to point to a persistent volume:\n\n# Set env var to persistent directory\nexport FATSECRET_CONFIG_DIR=\"/home/node/clawd/config/fatsecret\"\n\n# Or prefix commands\nFATSECRET_CONFIG_DIR=\"/persistent/path\" ./scripts/fatsecret-cli.sh auth\n\n\nOpenClaw example - add to your shell init or AGENTS.md:\n\nexport FATSECRET_CONFIG_DIR=\"/home/node/clawd/config/fatsecret\"\n\n🌐 Proxy Configuration (Optional)\n\nSome FatSecret API plans require IP whitelisting. If needed, set a proxy:\n\n# Environment variable\nexport FATSECRET_PROXY=\"socks5://127.0.0.1:1080\"\n\n# Or in config.json\n{\n  \"consumer_key\": \"...\",\n  \"consumer_secret\": \"...\",\n  \"proxy\": \"socks5://127.0.0.1:1080\"\n}\n\n\nIf you don't need a proxy: The skill works without it. Proxy is only required if FatSecret blocks your IP.\n\n🌍 Open Food Facts (Alternative)\n\nFor European products, use the free Open Food Facts API (no authentication):\n\nfrom scripts.openfoodfacts_client import OpenFoodFactsClient\n\noff = OpenFoodFactsClient(country=\"it\")\nproducts = off.search(\"barilla\")\nproduct = off.get_product(\"8076800105735\")  # Barcode\n\n📁 File Structure\nfatsecret/\n├── SKILL.md                      # This documentation\n├── README.md                     # GitHub/ClawHub readme\n├── requirements.txt              # Python: requests, requests[socks]\n├── scripts/\n│   ├── fatsecret-cli.sh          # Main CLI (bash wrapper)\n│   ├── fatsecret_auth.py         # OAuth1 3-legged authentication\n│   ├── fatsecret_agent_helper.py # Helper functions for agents\n│   ├── fatsecret_diary_simple.py # Diary logging (OAuth1)\n│   ├── fatsecret_client.py       # OAuth2 client (read-only)\n│   └── openfoodfacts_client.py   # Open Food Facts client\n└── examples/\n    └── agent_usage_example.py    # Agent integration example\n\n⚠️ Security Notes\nCredentials are stored locally in ~/.config/fatsecret/\nOAuth1 tokens don't expire unless you revoke them\nOAuth1 grants full access to your FatSecret diary (read + write)\nTo uninstall safely: Delete ~/.config/fatsecret/ and revoke app from FatSecret account\n🔗 References\nFatSecret API: https://platform.fatsecret.com/docs\nOAuth1 Guide: https://platform.fatsecret.com/docs/guides/authentication/oauth1/three-legged\nOpen Food Facts: https://wiki.openfoodfacts.org/API\nChangelog\nv1.0.1 (2026-02-20)\nFixed OAuth2 client - now uses OAuth1 for all operations (food search + diary)\nUnified authentication: single OAuth1 flow works for both read and write operations\nRemoved broken OAuth2 implementation"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/f-liva/fatsecret",
    "publisherUrl": "https://clawhub.ai/f-liva/fatsecret",
    "owner": "f-liva",
    "version": "1.1.0",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/fatsecret",
    "downloadUrl": "https://openagent3.xyz/downloads/fatsecret",
    "agentUrl": "https://openagent3.xyz/skills/fatsecret/agent",
    "manifestUrl": "https://openagent3.xyz/skills/fatsecret/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/fatsecret/agent.md"
  }
}