mcp-recipes 2.0.0 → 3.0.0

package/dist/sources/client.d.ts

@@ -30,6 +30,21 @@ interface Logger {
     error: (message: string) => void;
 }
 
+/**
+ * Reading what a page's own headings announce.
+ *
+ * A heading is the one statement a page makes about its own layout, and it is
+ * the only evidence there is that a part of a recipe was published when nothing
+ * was read out of that part. That matters because reading nothing is a fact
+ * about this server, and only the page can say whether there was anything to
+ * read.
+ *
+ * Both languages the pages are written in are recognised here, since a heading
+ * belongs to a page rather than to the corpus it sits in.
+ */
+/** The parts of a recipe a page announces with a heading of its own. */
+type PagePart = "ingredients" | "method";
+
 /** The shapes the source layer produces. Nothing here knows about MCP. */
 
 /**
@@ -115,6 +130,31 @@ interface RecipeDetail {
     prepMinutes: number | null;
     cookMinutes: number | null;
     totalMinutes: number | null;
+    /**
+     * Time the recipe stands, from a source that publishes it apart from
+     * preparation and cooking. It belongs to no other source's cooking time, and
+     * a source publishing none says null, which is not a dish that needs no rest.
+     */
+    restMinutes: number | null;
+    /**
+     * Whether the source publishes the method as one block of prose rather than
+     * as steps of its own. Null from a source that says neither, since a single
+     * entry can be one block or a method of one step and only the source knows.
+     */
+    stepsAsOneBlock: boolean | null;
+    /**
+     * A part the source published nothing of because it keeps it for its
+     * subscribers, and the words that say so.
+     *
+     * Null from a source that withholds nothing. That is a different statement
+     * from an empty list: a part withheld is a part the page has, and an answer
+     * that read it as a part this server failed to read would say something the
+     * page never said.
+     */
+    withheld: {
+        parts: PagePart[];
+        why: string;
+    } | null;
     category: string | null;
     author: string | null;
     rating: Rating | null;
@@ -324,6 +364,106 @@ interface CookbookReader {
     }>;
 }
 
+/**
+ * BBC Good Food, as a source.
+ *
+ * An English recipe site addressing a recipe by the path of its page. Two of
+ * its statements need care. Its total can sit on the largest number of rows one
+ * search will serve, where it states a floor rather than a count. And it keeps
+ * some recipes' ingredients and method for its subscribers while publishing the
+ * rest of the page, which is a part withheld rather than a part this server
+ * failed to read.
+ *
+ * A difficulty the site writes in a word of its own is not carried, since it
+ * publishes no scale for it. Its rendition for readers in the United States is
+ * not read either: taking lines from both would make a list in two measuring
+ * systems that the site never published as one.
+ */
+
+/** A search row, as BBC Good Food's own reader publishes one. */
+interface GoodFoodRow {
+    id: string;
+    title: string;
+    url: string;
+    image_url: string | null;
+    rating: number | null;
+    rating_count: number | null;
+    /** True where the recipe sits behind the site's subscription. */
+    premium: boolean;
+    total_minutes: number | null;
+    difficulty: string | null;
+    author: string | null;
+}
+/** A listing, as that reader publishes one. */
+interface GoodFoodReport {
+    query: string;
+    results: GoodFoodRow[];
+    result_count: number;
+    total_available: number | null;
+    /** True where the total sits on the largest number of rows one search serves. */
+    total_is_ceiling: boolean;
+    rows_seen: number;
+    restrictions_lifted: string[];
+}
+/** One line of an ingredient list, as that reader publishes it. */
+interface GoodFoodIngredient {
+    text: string;
+    amount: number | null;
+    unit: string | null;
+    item: string;
+    note: string | null;
+    /** The site's own normalised name for it, which no other source publishes. */
+    term: string | null;
+}
+interface GoodFoodGroup {
+    heading: string | null;
+    ingredients: GoodFoodIngredient[];
+}
+/** A recipe, as that reader publishes one. */
+interface GoodFoodRecipe {
+    id: string;
+    title: string;
+    url: string;
+    premium: boolean;
+    yield_text: string | null;
+    yield_count: number | null;
+    prep_minutes: number | null;
+    cook_minutes: number | null;
+    total_minutes: number | null;
+    difficulty: string | null;
+    diets: string[];
+    author: string | null;
+    rating: number | null;
+    rating_count: number | null;
+    description: string | null;
+    /** Empty where the recipe sits behind the subscription. */
+    ingredients: GoodFoodGroup[];
+    /** Empty where the recipe sits behind the subscription. */
+    steps: string[];
+    nutrition: Array<{
+        label: string;
+        value: number | null;
+        unit: string;
+    }>;
+    nutrition_per: string | null;
+    us_edition: unknown;
+}
+/** The part of BBC Good Food's client this server uses. */
+interface GoodFoodReader {
+    searchRecipes: (query: string, options?: {
+        limit?: number;
+    }) => Promise<{
+        data: GoodFoodReport;
+        cached: boolean;
+        skipped?: string[];
+    }>;
+    getRecipe: (id: string) => Promise<{
+        data: GoodFoodRecipe;
+        cached: boolean;
+        skipped?: string[];
+    }>;
+}
+
 /**
  * Marmiton, as a source.
  *
@@ -378,6 +518,204 @@ interface MarmitonReader {
     }>;
 }
 
+/**
+ * Ptitchef, as a source.
+ *
+ * A French recipe site addressing a recipe by the path of its page. It answers
+ * a search in several ways and prints one total for all of them, so the same
+ * number counts a category on one answer and the rows served on another; what
+ * it counts is said in words beside it rather than left to be guessed.
+ *
+ * Two figures the site publishes are not carried. It estimates what a recipe
+ * costs in euros, which is a price where another source ranks a recipe inside
+ * its own list, and one field holding both would invite the two to be compared.
+ * It writes a difficulty in a word of its own and states no scale for it, so
+ * the word sits on no axis a caller could put beside another source's.
+ */
+
+/** How the site answered a wording, as its own reader reports it. */
+type PtitchefKind = "topic" | "free_text" | "category" | "guide" | "standing" | "fridge" | "recipe" | "unmatched";
+/** A search row, as Ptitchef's own reader publishes one. */
+interface PtitchefRow {
+    id: string;
+    title: string;
+    url: string;
+    image_url: string | null;
+    rating: number | null;
+    /** How many readers rated it. */
+    rating_count: number | null;
+    /** How many wrote a review, which counts a different thing. */
+    review_count: number | null;
+    category: string | null;
+    difficulty: string | null;
+    total_minutes: number | null;
+    calories: string | null;
+    ingredients_preview: string | null;
+}
+/** A listing, as that reader publishes one. */
+interface PtitchefListing {
+    asked: string;
+    kind: PtitchefKind;
+    topic_slug: string | null;
+    title: string | null;
+    results: PtitchefRow[];
+    result_count: number;
+    rows_seen: number;
+    folded: number;
+    total_available: number | null;
+    page: number;
+    single_page: boolean;
+    url: string;
+}
+/** A recipe, as that reader publishes one. */
+interface PtitchefRecipe {
+    id: string;
+    title: string;
+    url: string;
+    description: string | null;
+    image_url: string | null;
+    category: string | null;
+    cuisine: string | null;
+    difficulty: string | null;
+    author: string | null;
+    author_url: string | null;
+    published: string | null;
+    modified: string | null;
+    rating: number | null;
+    rating_count: number | null;
+    review_count: number | null;
+    prep_minutes: number | null;
+    cook_minutes: number | null;
+    total_minutes: number | null;
+    yield_count: number | null;
+    yield_text: string | null;
+    yield_unit: string | null;
+    ingredients: string[];
+    steps: Array<{
+        text: string;
+        image_url: string | null;
+    }>;
+    /** True where the site published its method as one block of prose. */
+    steps_are_one_block: boolean;
+    /** The panel as the site prints it, slot by slot, unread slots left null. */
+    nutrition: unknown;
+    estimated_cost: string | null;
+    keywords: string[];
+    faq: unknown[];
+    translations: unknown[];
+}
+/** The part of Ptitchef's client this server uses. */
+interface PtitchefReader {
+    searchRecipes: (query: string) => Promise<{
+        data: PtitchefListing;
+        cached: boolean;
+        skipped?: string[];
+    }>;
+    getRecipe: (id: string) => Promise<{
+        data: PtitchefRecipe;
+        cached: boolean;
+        skipped?: string[];
+    }>;
+}
+
+/**
+ * Supertoinette, as a source.
+ *
+ * A French recipe site addressing a recipe by a number. It prints no total on
+ * a search page and publishes no nutrition panel, and both of those are stated
+ * here as silence: a count nobody published is not a count of zero.
+ */
+
+/** A search row, as Supertoinette's own reader publishes one. */
+interface SupertoinetteListingRow {
+    id: string;
+    title: string;
+    title_as_published: string;
+    url: string;
+    image_url: string | null;
+    description: string | null;
+    categories: string[];
+}
+/** One line of an ingredient list, as that reader publishes it. */
+interface SupertoinetteIngredient {
+    amount_text: string | null;
+    label: string;
+    /** The whole line as published, quantity included. */
+    raw: string;
+    /** The ingredient page the site linked the words to. Not read: the site
+     * links the wrong page often enough that pairing recipes by it would pair
+     * the wrong recipes. */
+    sheet: unknown;
+    is_heading: boolean;
+}
+/** A recipe, as Supertoinette's own reader publishes one. */
+interface SupertoinetteRecipe {
+    id: string;
+    title: string;
+    title_as_published: string;
+    url: string;
+    description: string | null;
+    yield_text: string | null;
+    ingredients: SupertoinetteIngredient[];
+    steps: string[];
+    intro: string | null;
+    prep_minutes: number | null;
+    cook_minutes: number | null;
+    total_minutes: number | null;
+    /** Time the recipe stands, which the site prints on its own. */
+    rest_minutes: number | null;
+    category: string | null;
+    author: string | null;
+    rating: {
+        value: number;
+        count: number;
+        scale: number;
+    } | null;
+    /** The site publishes none, and the field says so rather than being absent. */
+    nutrition: null;
+    difficulty: {
+        label: string;
+    } | null;
+    cost_level: {
+        label: string;
+        level: number;
+        scale: number;
+    } | null;
+    images: string[];
+    tags: unknown[];
+    ingredient_sheets: unknown[];
+    faq: unknown[];
+}
+interface SupertoinetteListing {
+    results: SupertoinetteListingRow[];
+    rows_published: number;
+    total_available: null;
+    last_page: number;
+    facets: unknown[];
+    matched_nothing: boolean;
+    url: string;
+}
+/** The part of Supertoinette's client this server uses. */
+interface SupertoinetteReader {
+    searchRecipes: (request: {
+        query: string;
+        page: number;
+        category: string | null;
+    }) => Promise<{
+        data: {
+            listing: SupertoinetteListing;
+            dropped_category: string | null;
+        };
+        cached: boolean;
+        skipped?: string[];
+    }>;
+    getRecipe: (id: string) => Promise<{
+        data: SupertoinetteRecipe;
+        cached: boolean;
+        skipped?: string[];
+    }>;
+}
+
 /**
  * The sources this server reads.
  *
@@ -390,10 +728,16 @@ interface MarmitonReader {
  * A reader may be supplied in place of the one that talks to a site, so a
  * program embedding this server can put its own cache in front of a corpus, and
  * a test can drive it from fixed answers.
+ *
+ * Each key is the id of the source it stands in for, so what a caller has
+ * replaced can be read off against what the registry builds.
  */
 interface Readers {
     marmiton?: MarmitonReader;
     cookbook?: CookbookReader;
+    ptitchef?: PtitchefReader;
+    goodfood?: GoodFoodReader;
+    supertoinette?: SupertoinetteReader;
 }
 
 /**