Befana Recipes

Merge any set of recipes (each at its own servings) into one shopping list. The same ingredient is combined across recipes and converted to what a store sells ("10 cloves garlic → buy 1 head"), grouped by aisle. extra_items keep the amount the cook gave ("2 lb bananas" stays 2 lb). One that matches a recipe ingredient is added to that line when the units agree, or shown beside it when they don't ("Lemons: 1 + 2 lb"). Staples like salt and oil, anything listed in pantry, and the cook's saved pantry staples go to a separate check-the-pantry group. Items that hit the cook's allergies are flagged. The list is saved to the cook's kitchen; returns a shareable list url.

Publish a recipe to Befana. When the cook pastes, types or links a recipe, call draft_recipe first, show them the draft and publish it here with create_recipe({ draft_id }) once they confirm: never publish their text straight from fields, even a short one (for a recipe card photo, read it and pass the text to draft_recipe). Pass fields without a draft_id only for a recipe you worked out with the cook in this conversation, after showing it to them. Write each step with ingredient tags instead of typed amounts: "Whisk {flour} with {salt}". Tags default to the last word of the ingredient name ("all-purpose flour" → {flour}); set key to choose. Use {butter:1/2} when an ingredient is split across steps and {t:375} for oven temperatures in °F. title, servings, ingredients and steps are required, unless you pass draft_id: then the draft from draft_recipe is published, with any fields you pass replacing the draft's. Publish a draft only after the cook has seen and confirmed it. Returns the url plus any warnings (e.g. an ingredient never used in a step). Recipes are public and appear under My recipes in the cook's kitchen.

Turn a recipe the cook pasted, typed or linked to into a Befana draft: ingredients matched to Befana's list, steps rewritten in plain words with amounts as tags, and servings, times, timers and tags filled in. Pass text (up to 20,000 characters) or url (a public recipe page; a Pinterest Pin or pin.it link works too: Befana follows the Pin to the recipe it saved), not both. Nothing is published. Show the cook the draft (title, servings, ingredients and steps), point out anything listed in guessed, and ask them to confirm or change it. Then publish with create_recipe({ draft_id }) plus only the fields they changed, or give them edit_url to review and publish on the website. For a photo of a recipe card, read it yourself and pass the text. Limited to 20 drafts a day per cook.

Save the cook's own version of a recipe they don't own ("make it dairy-free", "halve the sugar", "scale it for 8 and keep that"). Pass only what changes; anything omitted is copied from the original. When you pass ingredients or steps, pass the complete new list (fetch the original with get_recipe first and edit it). Ingredients you keep can be resent without key; they keep the original's tags. For a new ingredient, tag it in the steps by its name in snake_case ({nutritional_yeast}) or set key. Steps carry the amounts, so when you preview a change, show the steps whose amounts change along with the ingredients. Before calling, show the cook the changed ingredients and steps and get a yes; never save silently. Without a title, the version is named after the change ("Dairy-free Chili", "Chili with Olive Oil"). A version made only to change servings keeps those as its default. The version links back to the original, which never changes. Versions are public by default and appear under My versions in the cook's kitchen; visibility "private" keeps it just for the cook (out of search, the sitemap and the original's list of variations). To change it again later, use update_recipe. On a recipe the cook already owns, use update_recipe instead; fork_recipe refuses.

A cook's public page on Befana by handle (the author.handle on any recipe, or the cook's own): display name, photo, about me, location, interests and links when they show them, and their public recipes and variations with ratings and urls. Pass no handle for the cook's own profile. Nothing private is ever here: no email, allergies, diet, preferences, saved recipes, lists or pantry.

One recipe as a hands-free sequence for voice or chat guidance: a gather list first, then each step with its amounts, the ingredients it uses, its tip (if the chef left one) and any timer. Give the cook one step at a time, and offer to set a timer when a step has one. The recipe url shows the same steps as a checklist on the cook's phone.

What the cook has on Befana: saved recipes, recipes they published, their variations, shopping lists and meal plans (from the web or any assistant), and their ratings. Use it to answer "what did I save?" or to reopen a list. Same as My Kitchen on the website.

The cook's own published recipes that have no cover photo, a generated placeholder instead of a photo, or a cover that doesn't meet Befana's photo standard (dark, blurry, washed out, too small). Use it to help the cook decide what to reshoot. Returns each recipe's url, the current cover's tier and what's wrong with it.

The cook's saved Befana preferences: allergies, diet, ingredients to avoid, household size, units, weeknight time, skill, equipment, cuisines, pantry staples, store, privacy choices (do not sell, region), and workflow: how they want you to work (which offers to make: always, ask or never; setup questions; what's new; their usual number of planned meals). They already apply to every Befana tool.

Full recipe scaled to any number of servings, in US or metric units. Every step already contains the amounts it uses, so you can read steps aloud without referring back to the ingredient list. A step's tip is a short pointer to pass on with the step. Mention the chef's note (chef_note) only if the cook asks about the recipe's background. your_versions lists the cook's own versions of this recipe, so you can say "you have your own version of this" and offer it. On a recipe the cook owns, revision counts their edits and revisions lists the last ten (undo one with update_recipe({ restore_revision })). When the cook asks for an amount in another unit ("how many tablespoons of butter is that?"), pass units_for rather than converting yourself: the list and every step follow. When the cook wants a change, pass substitute to get sound swaps for one ingredient or for a whole diet ("dairy-free"), already filtered by the cook's allergies and diet; then show the cook the changed ingredients and steps and, once they say yes, save with fork_recipe (or update_recipe on their own recipe).

Hand a shopping list to grocery delivery (Instacart) so the cook can order from a store near them. Pass the list_id returned by build_shopping_list or plan_meals, or pass recipes directly. Items marked as in the pantry are left off. Returns one link that opens the whole list when checkout is connected, otherwise a search link per item. Always share share_url with the cook: it's the one link that opens their order (the grocer's list, or Befana's order page with every item's store search). Befana does not choose brands or promote products; the cook picks the store and products and places the order themselves.

Pick several recipes for the coming days that fit the filters and overlap in ingredients, so less food goes to waste. The cook's allergies, diet, avoid list, weeknight time limit and household size already apply. Saves the plan to the cook's kitchen and optionally returns the merged shopping list too.

Post the cook's star rating (1 to 5) and optional comment. Only post what the cook actually said; ask them for the rating if they have not given one.

Flag a recipe, review, photo or a cook's profile for Befana's moderators: spam, offensive, unsafe as written, copied without permission, not a recipe, or something else. Only report what the cook asked to report, in their words. Moderators review every report; nothing is hidden automatically.

Save (favorite) a recipe for the cook. It shows under Saved in My Kitchen on the website, with a heart on the recipe. Saving twice is harmless.

Find Befana recipes by keywords, time, diet tags, and ingredients on hand or to avoid. The cook's saved allergies, diet and avoid list already apply. Returns short summaries with slugs; call get_recipe for the full recipe. Tags in use include vegetarian, vegan, gluten-free, dairy-free, quick, dinner, breakfast, dessert, baking, soup, side, snack, make-ahead. Signed in, the cook's own recipes and versions come first; mine: true returns only those ("show me my chili"), private ones included. When the cook names a recipe their allergies, diet or avoid list hide, it comes back in hidden (slug, url, title, why) instead of recipes. They asked for it, so don't stop to ask: go on with what they asked (get_recipe, get_cook_steps, get_recipe with substitute, build_shopping_list) with that slug; the result leads with the warning, and you tell the cook why it was hidden before anything else. Never present a hidden recipe as safe.

Remove a recipe from the cook's Saved recipes. Only use when the cook asks.

Change the cook's saved Befana preferences. When the cook asks in their own words for a specific change to units, household size (servings), weeknight time, skill, equipment, cuisines, pantry, store or how you work with them (workflow: "switch me to metric", "set us to 4 people", "stop offering shopping lists", "always make the list"), that request is their yes: save it with cook_confirmed and tell them what changed (and that they can change it in Settings). For allergies, diets, the avoid list and privacy settings, and for any change you are proposing or the cook only mentioned in passing ("we're usually 4"), first tell the cook exactly what you will change and get a clear yes; set cook_confirmed only then. Never infer allergies or diets from conversation ("I'm making a cheese-free dinner" is not a milk allergy): only add them when the cook states them and confirms they should be saved. Pass only the fields to change. Lists replace the saved list, so read get_preferences first and send the full new list.

Change the cook's own public profile at befana.app/cook/<handle>: handle, display name, about me, location, cooking interests, up to three links, and whether the photo and about me show (show_details; off until the cook turns it on). Before calling, tell the cook exactly what will change and get a clear yes; set cook_confirmed only then. Pass only the fields to change; interests and links replace the saved list. A changed handle keeps the old one redirecting for 90 days. A photo is uploaded on the website (Settings → Your public profile); photo: "google" copies the cook's Google account photo, photo: null removes it. Never write about-me text for the cook: only what they said.

Edit a recipe the cook owns (one they published, or their own version from fork_recipe) in place: "add more garlic to my version". Pass only what changes; everything else stays. When you pass ingredients or steps, pass the complete new list (fetch the current one with get_recipe first and edit it); ingredients resent without key keep their tags, so changing one amount is just the list with that amount changed. For a new ingredient, tag it in the steps by its name in snake_case ({nutritional_yeast}) or set key. Steps carry the amounts, so when you preview a change, show the steps whose amounts change along with the ingredient. Before calling, show the cook the changed ingredients and steps and get a yes; never save silently. Every edit keeps the previous version: get_recipe returns revision (how many edits) and revisions; restore_revision: n puts the recipe back to how it was before edit n (the current revision number undoes the last edit), and is itself kept as an edit. visibility switches between public and "private" (just for the cook). The slug and the link to the original never change. Fails for a recipe the cook doesn't own: use fork_recipe for those.