@crvouga/mockingbird-service-edamam

Local emulators. Real API contracts. Part of Mockingbird.

Stateful emulator of the Edamam APIs our apps call, answering from a built-in food and recipe corpus: the Food Database v2 parser (text and UPC), nutrients and image recognition, Nutrition Analysis (nutrition-data, nutrition-details), Recipe Search v2 (search with filters and _cont paging, by URI, by id), the Meal Planner v1 select, and Shopping List v2. Nutrition logging, barcode scans, photo logging, recipe search, meal plans and grocery lists then work in tests without Edamam keys, quotas or network.

• Operation coverage: SUPPORT.md
• The contract (openapi.yaml) is hand-authored from Edamam's per-API docs and our consumers: metrics/adapters/outbound/edamam-nutrition.adapter.ts, meal-planning/adapters/outbound/edamam-meal-planning.adapter.ts, and the Python chat service's tools/nutrition/client.py.

Install

npm install -D @crvouga/mockingbird-service-edamam

ESM only. Node >= 22 or Bun >= 1.2. No native dependencies. Serve it with npx mockingbird-edamam serve, createServer from ./server (Node), or createRuntime with any Fetch server.

Usage

Both backend adapters hardcode https://api.edamam.com (seam: a base-URL env for EDAMAM_BASE_URL / EDAMAM_MEAL_BASE_URL, and the Python client's EDAMAM_BASE_URL). Keys can be any values (EDAMAM_FOOD_APP_ID/KEY or EDAMAM_APP_ID/KEY, EDAMAM_MEAL_APP_ID/KEY, the Python client's edamam_* settings); without them our adapters report unavailable and never call out.

npx mockingbird-edamam serve --port 8824

import { createServer } from "@crvouga/mockingbird-service-edamam/server"

// Test setup: the emulator. The application gets EDAMAM_BASE_URL = server.url.
const server = await createServer()
const baseUrl = server.url

// Application code: the Food Database request it sends to api.edamam.com.
const query = new URLSearchParams({
  app_id: "a",
  app_key: "k",
  ingr: "2 large eggs",
  "nutrition-type": "logging",
})
const response = await fetch(`${baseUrl}/api/food-database/v2/parser?${query}`)
const parsed = await response.json()
// → {text, parsed: [{food: {foodId: "food_egg", label: "Egg", nutrients: {ENERC_KCAL: 143, …}},
//     quantity: 2, measure: {uri: "…#Measure_large", label: "Large", weight: 50}}], hints: […]}
await server.close()

Routes

Every call takes app_id and app_key as query parameters (the meal planner and shopping list also accept Authorization: Basic app_id:app_key, which our adapter sends).

Errors: Food Database and Nutrition Analysis answer {status: "error", error, message}; Recipe Search, Meal Planner and Shopping List answer [{errorCode, message, params}].

Corpus (DEFAULT_FOODS, DEFAULT_RECIPES): 18 foods with per-100 g nutrients and measures (including a meal, two packaged products with UPCs 850000000012 and 850000000036, and one UPC 850000000029 with no nutrition data) and 8 recipes built from them, so recipe totals, per-serving values and shopping lists agree with the food database.

Admin (beyond the standard contract)

Fault presets (POST /__admin/faults {"preset": "<name>", "count"?: n}): rate_limited (429), payment_required (402), unauthorized (401), server_error (500), parser_schema_drift, recipe_quality (555), vision_not_found, meal_plan_incomplete, meal_plan_timeout, slow (12 s, past our 10 s timeouts), connection_drop.

Namespaces

x-mockingbird-namespace, a /__admin/ns/<name> prefix on the base URL (works for the nutrition adapter and the Python client, which concatenate paths; the meal adapter resolves paths with new URL(endpoint, base), which drops a prefix), or by application id: PUT /__admin/credentials {"credentials": {"<app_id>": "<namespace>"}}.

Deliberately not modelled

• Edamam's NLP and databases: the parser understands leading quantities, known measures and corpus food names only; real food and recipe content needs a recorded corpus.
• Parser nutrients[CODE] is a best guess, not oracle-verified (vendor docs only say the Food Database can "search for food by given nutrient quantity"; the query syntax, the error for a malformed range and any plan restriction were never observed live). The emulator reads nutrients[PROCNT]=20+, =5 (at most) and =5-15 (inclusive) like calories, against the food's per-100 g nutrients, and a raw + that decoded to a space still means "or more". Several codes, a repeated code and health / calories / category / categoryLabel all must hold; nothing matching is 200 with hints: [] and parsed: []. A food with no value for the code never matches. Any code shaped like a nutrient code is accepted, but the built-in corpus carries only ENERC_KCAL, PROCNT, FAT, CHOCDF, FIBTG and SUGAR, so codes such as NA or FE match only foods seeded with POST /__admin/foods that carry them (an emulator limitation, not a vendor answer). A malformed range or code is 400 bad_request. The upc lookup ignores the filters, as it does for calories.
• Food Database autocomplete, brand search and nutrients qualifiers; Recipe Search user recipes (type=user), field= projection and images other than the URL.
• Meal Planner plan-level fit beyond a day-calorie check, mark weighting, nested sub-sections, and shopping-cart checkout pages.

API

Part of mockingbird.