initial commit

2026-07-12 10:17:17 -04:00
commit dab5a4ebc6
1424 changed files with 330463 additions and 0 deletions
@@ -0,0 +1,67 @@
+# Batch Recipe Import
+
+Import recipes in bulk via the Mealie API. The scraper extracts full recipe data (ingredients, steps, images, times) from any supported URL.
+
+## Python Script
+
+```python
+import requests
+import time
+
+MEALIE = "http://127.0.0.1:9925"
+EMAIL = "your@email.com"
+PASSWORD = "your-password"
+
+# Authenticate
+resp = requests.post(
+    f"{MEALIE}/api/auth/token",
+    data={"username": EMAIL, "password": PASSWORD, "grant_type": ""},
+    headers={"Content-Type": "application/x-www-form-urlencoded"}
+)
+token = resp.json()["access_token"]
+headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
+
+# Recipe URLs (one per line)
+urls = [
+    "https://www.bbcgoodfood.com/recipes/classic-lasagne",
+    "https://www.budgetbytes.com/one-pot-creamy-cajun-chicken-pasta/",
+    "https://www.recipetineats.com/thai-green-curry/",
+]
+
+for url in urls:
+    resp = requests.post(
+        f"{MEALIE}/api/recipes/create/url",
+        json={"url": url},
+        headers=headers,
+        timeout=60
+    )
+    if resp.status_code in (200, 201):
+        print(f"  OK: {url.split('/')[-2]}")
+    else:
+        print(f"  FAIL: {url.split('/')[-2]} — {resp.status_code}")
+    time.sleep(1.5)  # Be polite to recipe sites
+```
+
+## Bulk curl (no Python needed)
+
+```bash
+# Get token
+TOKEN=$(curl -s -X POST "http://127.0.0.1:9925/api/auth/token" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "grant_type=&username=you@email.com&password=yourpass" \
+  | grep -o '"access_token":"[^"]*"' | cut -d'"' -f4)
+
+# Import a single recipe
+curl -s -X POST "http://127.0.0.1:9925/api/recipes/create/url" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://www.bbcgoodfood.com/recipes/classic-lasagne"}'
+```
+
+## Notes
+
+- URLs must be full recipe pages, not search results or category pages.
+- If a site returns HTTP 400 consistently, it likely blocks automated scrapers — see `scraper-sites.md` for alternatives.
+- First import may be slow (Mealie's scraper downloads the page, parses schema.org JSON-LD, and extracts structured data).
+- **Real-world success rate:** ~50-60% across mixed URLs. Expect roughly half to fail on the first pass. Rerun failures from a reliable source (BBC Good Food, RecipeTin Eats) to fill gaps.
+- **From Hermes:** use `execute_code` with `import requests` — the sandboxed Python environment can call `http://127.0.0.1:9925` directly. No need for curl or external scripts.
@@ -0,0 +1,58 @@
+# Recipe Management via API
+
+Beyond batch importing, the Mealie API supports full CRUD for recipes — useful for bulk deletion, tag assignment, or fixing metadata.
+
+## Authentication (same as batch import)
+
+```python
+import requests
+M = "http://127.0.0.1:9925"
+token = requests.post(f"{M}/api/auth/token",
+    data={"username": "email", "password": "pw", "grant_type": ""},
+    headers={"Content-Type": "application/x-www-form-urlencoded"}
+).json()["access_token"]
+h = {"Authorization": f"Bearer {token}"}
+```
+
+## List all recipes
+
+```python
+r = requests.get(f"{M}/api/recipes?page=1&perPage=100", headers=h)
+data = r.json()  # keys: page, per_page, total, total_pages, items
+for recipe in data["items"]:
+    print(f"[{recipe['id']}] {recipe['name']}")
+```
+
+Pagination: increment `page` until `page > total_pages`.
+
+## Delete recipes (single or bulk)
+
+```python
+# Single
+r = requests.delete(f"{M}/api/recipes/{recipe_id}", headers=h)
+
+# Bulk with keyword filter
+for recipe in data["items"]:
+    if "pork" in recipe["name"].lower():
+        r = requests.delete(f"{M}/api/recipes/{recipe['id']}", headers=h)
+        print(f"Deleted: {recipe['name']} -> {r.status_code}")
+```
+
+HTTP 200 = success. No undo — confirm your filter before running.
+
+## Find by keyword
+
+Check `name`, `slug`, `description`, and `recipeIngredient` for matching terms:
+
+```python
+import json
+txt = json.dumps(recipe).lower()
+if "bacon" in txt:
+    # recipe mentions bacon somewhere
+```
+
+## Notes
+
+- Recipe IDs are UUIDs (e.g. `52fe7e87-49c2-4cd4-b4f3-82ae7e1b102b`), not sequential integers.
+- The list endpoint returns limited fields; fetch individual recipes (`GET /api/recipes/{id}`) for full ingredient/instruction data.
+- Deletion is instant — no trash/recycle bin in Mealie.
@@ -0,0 +1,52 @@
+# Recipe Scraper Site Compatibility
+
+Mealie's built-in recipe scraper extracts structured data from recipe websites. Compatibility varies — some sites block automated access (Cloudflare, aggressive bot detection), others work flawlessly.
+
+## Reliable (high success rate)
+
+| Site | Notes |
+|---|---|
+| **BBC Good Food** (bbcgoodfood.com) | Excellent. Fast parsing, full ingredient + step extraction. |
+| **RecipeTin Eats** (recipetineats.com) | Very reliable. Good image extraction. |
+| **Budget Bytes** (budgetbytes.com) | Works ~70% of time. Rate-limit sensitive — add 1-2s delay between imports. |
+| **Love and Lemons** (loveandlemons.com) | Works well. Vegan/vegetarian focus. |
+
+## Unreliable / Blocked (low success rate)
+
+| Site | Issue |
+|---|---|
+| **AllRecipes** (allrecipes.com) | Aggressive bot detection. HTTP 400 on most attempts. |
+| **Simply Recipes** (simplyrecipes.com) | Blocks automated scrapers. |
+| **Damn Delicious** (damndelicious.net) | Cloudflare or similar protection. Fails consistently. |
+| **Gimme Some Oven** (gimmesomeoven.com) | Same blocking issue as above. |
+
+## Curated import strategy (near-100% success)
+
+When batch-importing by cuisine or theme, search **only** BBC Good Food and RecipeTin Eats for individual recipe URLs. Restricting to these two sites yields near-100% scraper success, compared to ~50-60% when mixing sources.
+
+**Workflow for cuisine batch imports:**
+1. Search `site:bbcgoodfood.com <cuisine> recipe` and `site:recipetineats.com <cuisine> recipe`
+2. Pick individual recipe URLs (not category/list pages — URLs must end in a recipe slug like `/easy-chicken-fajitas`)
+3. Run the batch import script from `references/batch-import.md` with 2-second delays
+4. Expect 90-100% success rate
+
+**Real-world example:** A 20-recipe batch (10 Mexican, 10 Mediterranean) from BBC Good Food + RecipeTin Eats imported with 20/20 success (100%). The same approach with mixed sources typically yields 10-12 successes.
+
+## Workarounds for blocked sites
+
+1. **Manual entry:** Copy-paste ingredients and steps into Mealie's manual recipe form.
+2. **Screenshot + OCR:** Not implemented yet, but Mealie supports OCR recipe creation (requires OpenAI API key or local LLM).
+3. **Alternative source:** Many popular recipes exist on multiple sites — search BBC Good Food or RecipeTin Eats for a similar version.
+4. **Import from JSON:** If you have recipes in JSON-LD or schema.org format, use Mealie's JSON import endpoint.
+
+## Testing a new site
+
+```bash
+# Quick test — if this returns 400, the site is likely blocked
+curl -s -X POST "http://127.0.0.1:9925/api/recipes/create/url" \
+  -H "Authorization: Bearer *** \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://example.com/recipe/test"}'
+```
+
+A successful import returns 200/201 with recipe JSON. 400 usually means the scraper couldn't extract data from the page. 500 means the site blocked the request entirely.