1,000,000+ Recipe and Grocery List API (v2)

/**
 * Api1000000RecipeandGroceryListAPIv2 - generated by OmniStream from 1,000,000+ Recipe and Grocery List API (v2)'s OpenAPI spec.
 * One typed method per endpoint. A single Omni key reaches the API.
 */
const DEFAULT_BASE = "https://grid.skinvaults.online/v1/proxy/bigoven";

export class Api1000000RecipeandGroceryListAPIv2Error extends Error {
  status: number;
  code?: string;
  constructor(status: number, code: string | undefined, message?: string) {
    super(message || `Api1000000RecipeandGroceryListAPIv2 error ${status}`);
    this.name = "Api1000000RecipeandGroceryListAPIv2Error";
    this.status = status;
    this.code = code;
  }
}

export interface Api1000000RecipeandGroceryListAPIv2Options {
  baseUrl?: string;
  fetch?: typeof fetch;
  timeoutMs?: number;
}

export class Api1000000RecipeandGroceryListAPIv2 {
  /** @param token Your OmniStream key (one key for every API). */
  constructor(private token: string, private opts: Api1000000RecipeandGroceryListAPIv2Options = {}) {
    if (!token) throw new Error("Api1000000RecipeandGroceryListAPIv2: token is required");
  }
  rateLimit: { remainingMinute?: number; remainingDay?: number } | null = null;

  private async _request(method: string, path: string, { params, body }: { params?: Record<string, unknown>; body?: unknown } = {}): Promise<any> {
    const f = this.opts.fetch ?? globalThis.fetch;
    const url = new URL((this.opts.baseUrl ?? DEFAULT_BASE).replace(/\/+$/, "") + path);
    if (params) for (const [k, v] of Object.entries(params)) if (v != null) url.searchParams.set(k, String(v));
    const headers: Record<string, string> = { "x-omni-key": this.token };
    if (body !== undefined) headers["content-type"] = "application/json";
    const res = await f(url, { method, headers, body: body !== undefined ? JSON.stringify(body) : undefined });
    this.rateLimit = {
      remainingMinute: Number(res.headers.get("x-ratelimit-remaining-minute")) || undefined,
      remainingDay: Number(res.headers.get("x-ratelimit-remaining-day")) || undefined,
    };
    const data = await res.json().catch(() => ({}));
    if (!res.ok) throw new Api1000000RecipeandGroceryListAPIv2Error(res.status, data?.error?.code, data?.error?.message);
    return data.data ?? data;
  }

  /** Gets a recipe collection. A recipe collection is a curated set of recipes. */
  collectionGetCollection(params: { "id": number; "rpp"?: number; "pg"?: number; "test"?: boolean; "sessionForLogging"?: string }): Promise<any> {
    return this._request("GET", "/collection/{id}", { params });
  }

  /** Gets a recipe collection metadata. A recipe collection is a curated set of recipes. */
  collectionGetCollectionMeta(params: { "id": number }): Promise<any> {
    return this._request("GET", "/collection/{id}/meta", { params });
  }

  /** Get the list of current, seasonal recipe collections. From here, you can use the /collection/{id} endpoint to retrieve the recipes in those collections. */
  collectionCollections(params: { "test"?: string }): Promise<any> {
    return this._request("GET", "/collections", { params });
  }

  /** Get the user's grocery list.  User is determined by Basic Authentication. */
  groceryListGet(): Promise<any> {
    return this._request("GET", "/grocerylist", {});
  }

  /** Delete all the items on a grocery list; faster operation than a sync with deleted items. */
  groceryListDelete(): Promise<any> {
    return this._request("DELETE", "/grocerylist", {});
  }

  /** Clears the checked lines. */
  groceryListGroceryListRemoveMarkedItems(): Promise<any> {
    return this._request("POST", "/grocerylist/clearcheckedlines", {  });
  }

  /** Departmentalize a list of strings -- used for ad-hoc grocery list item addition */
  groceryListDepartment(body: unknown): Promise<any> {
    return this._request("POST", "/grocerylist/department", { body });
  }

  /** Add a single line item to the grocery list */
  postgrocerylistItem(body: unknown): Promise<any> {
    return this._request("POST", "/grocerylist/item", { body });
  }

  /** Update a grocery item by GUID */
  groceryListGroceryListItemGuid(body: unknown, params: { "guid": string }): Promise<any> {
    return this._request("PUT", "/grocerylist/item/{guid}", { body, params });
  }

  /** /grocerylist/item/{guid}  DELETE will delete this item assuming you own it. */
  groceryListDeleteItemByGuid(params: { "guid": string }): Promise<any> {
    return this._request("DELETE", "/grocerylist/item/{guid}", { params });
  }

  /** Add a single line item to the grocery list */
  groceryListPost(body: unknown): Promise<any> {
    return this._request("POST", "/grocerylist/line", { body });
  }

  /** Add a Recipe to the grocery list.  In the request data, pass in recipeId, scale (scale=1.0 says to keep the recipe the same size as originally posted), markAsPending (true/false) to indicate that
            the lines in the recipe should be marked in a "pending" (unconfirmed by user) state. */
  groceryListAddRecipe(body: unknown): Promise<any> {
    return this._request("POST", "/grocerylist/recipe", { body });
  }

  /** Synchronize the grocery list.  Call this with a POST to /grocerylist/sync */
  groceryListPostGroceryListSync(body: unknown): Promise<any> {
    return this._request("POST", "/grocerylist/sync", { body });
  }

  /** POST: /image/avatar
             
            Testing with Postman (validated 11/20/2015):
            1) Remove the Content-Type header; add authentication information
            2) On the request, click Body and choose "form-data", then add a line item with "key" column set to "file" and on the right,
            change the type of the input from Text to File.  Browse and choose a JPG. */
  imagesUploadUserAvatar(): Promise<any> {
    return this._request("POST", "/image/avatar", {  });
  }

  /** Indexes this instance. */
  meIndex(): Promise<any> {
    return this._request("GET", "/me", {});
  }

  /** Puts me. */
  mePutMe(body: unknown): Promise<any> {
    return this._request("PUT", "/me", { body });
  }

  /** Puts me personal. */
  mePutMePersonal(body: unknown): Promise<any> {
    return this._request("PUT", "/me/personal", { body });
  }

  /** Puts me preferences. */
  mePutMePreferences(body: unknown): Promise<any> {
    return this._request("PUT", "/me/preferences", { body });
  }

  /** Gets the options. */
  meGetOptions(): Promise<any> {
    return this._request("GET", "/me/preferences/options", {});
  }

  /** Puts me. */
  putmeProfile(body: unknown): Promise<any> {
    return this._request("PUT", "/me/profile", { body });
  }

  /** Skinnies this instance. */
  meSkinny(): Promise<any> {
    return this._request("GET", "/me/skinny", {});
  }

  /** Add a new recipe */
  recipePost(): Promise<any> {
    return this._request("POST", "/recipe", {  });
  }

  /** Update a recipe */
  recipePut(): Promise<any> {
    return this._request("PUT", "/recipe", {  });
  }

  /** Given a query, return recipe titles starting with query. Query must be at least 3 chars in length. */
  recipeAutoComplete(params: { "query": string; "limit"?: number }): Promise<any> {
    return this._request("GET", "/recipe/autocomplete", { params });
  }

  /** Automatics the complete all recipes. */
  recipeAutoCompleteAllRecipes(params: { "query": string; "limit": number }): Promise<any> {
    return this._request("GET", "/recipe/autocomplete/all", { params });
  }

  /** Automatics the complete my recipes. */
  recipeAutoCompleteMyRecipes(params: { "query": string; "limit": number }): Promise<any> {
    return this._request("GET", "/recipe/autocomplete/mine", { params });
  }

  /** Get a list of recipe categories (the ID field can be used for include_cat in search parameters) */
  recipeCategories(): Promise<any> {
    return this._request("GET", "/recipe/categories", {});
  }

  /** Returns last active recipe for the user */
  recipeGetActiveRecipe(params: { "userName": string }): Promise<any> {
    return this._request("GET", "/recipe/get/active/recipe", { params });
  }

  /** Gets recipe single step as text */
  recipeGetStep(params: { "userName": string; "recipeId": number; "stepId": number }): Promise<any> {
    return this._request("POST", "/recipe/get/saved/step", { params });
  }

  /** Returns stored step number and number of steps in recipe */
  recipeGetStepNumber(params: { "userName": string; "recipeId": number }): Promise<any> {
    return this._request("POST", "/recipe/get/step/number", { params });
  }

  /** Gets the pending by user. */
  imagesGetPendingByUser(): Promise<any> {
    return this._request("GET", "/recipe/photos/pending", {});
  }

  /** Stores recipe step number and returns saved step data */
  recipeGetSteps(params: { "userName": string; "recipeId": number; "stepId": number }): Promise<any> {
    return this._request("POST", "/recipe/post/step", { params });
  }

  /** Update (PUT) a reply to a given review. Authenticated user must be the original one that posted the reply. */
  reviewPutReply(params: { "replyId": string }): Promise<any> {
    return this._request("PUT", "/recipe/review/replies/{replyId}", { params });
  }

  /** DELETE a reply to a given review. Authenticated user must be the one who originally posted the reply. */
  reviewDeleteReply(params: { "replyId": string }): Promise<any> {
    return this._request("DELETE", "/recipe/review/replies/{replyId}", { params });
  }

  /** Get a given review by string-style ID. This will return a payload with FeaturedReply, ReplyCount.
            Recommended display is to list top-level reviews with one featured reply underneath. 
            Currently, the FeaturedReply is the most recent one for that rating. */
  getrecipeReviewReviewid(params: { "reviewId": string }): Promise<any> {
    return this._request("GET", "/recipe/review/{reviewId}", { params });
  }

  /** Update a given top-level review. */
  reviewPut(params: { "reviewId": string }): Promise<any> {
    return this._request("PUT", "/recipe/review/{reviewId}", { params });
  }

  /** Get a paged list of replies for a given review. */
  reviewGetReplies(params: { "reviewId": string; "pg"?: number; "rpp"?: number }): Promise<any> {
    return this._request("GET", "/recipe/review/{reviewId}/replies", { params });
  }

  /** POST a reply to a given review. The date will be set by server. Note that replies no longer have star ratings, only top-level reviews do. */
  reviewPostReply(params: { "reviewId": string }): Promise<any> {
    return this._request("POST", "/recipe/review/{reviewId}/replies", { params });
  }

  /** POST an image as a new RecipeScan request
                1)  Fetch the filename -- DONE
                2)  Copy it to the pics/scan folder - ENSURE NO NAMING COLLISIONS -- DONE
                3)  Create 120 thumbnail size  in pics/scan/120 -- DONE
                4)  Insert the CloudTasks record
                5)  Create the HIT
                6)  Update the CloudTasks record with the HIT ID
                7)  Email the requesing user
                8)  Call out to www.bigoven.com to fetch the image and re-create the thumbnail */
  recipeScan(params: { "test"?: boolean; "devicetype"?: string; "lat"?: number; "lng"?: number }): Promise<any> {
    return this._request("POST", "/recipe/scan", { params });
  }

  /** Return full Recipe detail with steps. Returns 403 if the recipe is owned by someone else. */
  recipeGetRecipeWithSteps(params: { "id": number; "prefetch"?: boolean }): Promise<any> {
    return this._request("GET", "/recipe/steps/{id}", { params });
  }

  /** Return full Recipe detail. Returns 403 if the recipe is owned by someone else. */
  recipeGet(params: { "id": number; "prefetch"?: boolean }): Promise<any> {
    return this._request("GET", "/recipe/{id}", { params });
  }

  /** Delete a Recipe (you must be authenticated as an owner of the recipe) */
  recipeDelete(params: { "id": number }): Promise<any> {
    return this._request("DELETE", "/recipe/{id}", { params });
  }

  /** Zaps the recipe. */
  recipeZapRecipe(params: { "id": number }): Promise<any> {
    return this._request("GET", "/recipe/{id}/zap", { params });
  }

  /** Feedback on a Recipe -- for internal BigOven editors */
  recipeFeedback(body: unknown, params: { "recipeId": number }): Promise<any> {
    return this._request("POST", "/recipe/{recipeId}/feedback", { body, params });
  }

  /** POST: /recipe/{recipeId}/image?lat=42&amp;lng=21&amp;caption=this%20is%20my%20caption
             
             Note that caption, lng and lat are all optional, but must go on the request URI as params because this endpoint
             needs a multipart/mime content header and will not parse JSON in the body along with it.
            
             Testing with Postman (validated 11/20/2015):
             1) Remove the Content-Type header; add authentication information
             2) On the request, click Body and choose "form-data", then add a line item with "key" column set to "file" and on the right,
             change the type of the input from Text to File.  Browse and choose a JPG. */
  imagesUploadRecipeImage(params: { "recipeId": string; "caption"?: string; "lat"?: number; "lng"?: number }): Promise<any> {
    return this._request("POST", "/recipe/{recipeId}/image", { params });
  }

  /** Get all the images for a recipe. DEPRECATED. Please use /recipe/{recipeId}/photos. */
  imagesGet(params: { "recipeId": number }): Promise<any> {
    return this._request("GET", "/recipe/{recipeId}/images", { params });
  }

  /** HTTP POST a new note into the system. */
  notePost(body: unknown, params: { "recipeId": number }): Promise<any> {
    return this._request("POST", "/recipe/{recipeId}/note", { body, params });
  }

  /** Get a given note. Make sure you're passing authentication information in the header for the user who owns the note. */
  noteGet(params: { "recipeId": number; "noteId": number }): Promise<any> {
    return this._request("GET", "/recipe/{recipeId}/note/{noteId}", { params });
  }

  /** HTTP PUT (update) a Recipe note (RecipeNote). */
  notePut(body: unknown, params: { "recipeId": number; "noteId": number }): Promise<any> {
    return this._request("PUT", "/recipe/{recipeId}/note/{noteId}", { body, params });
  }

  /** Delete a review
                do a DELETE Http request of /note/{ID} */
  noteDelete(params: { "recipeId": number; "noteId": number }): Promise<any> {
    return this._request("DELETE", "/recipe/{recipeId}/note/{noteId}", { params });
  }

  /** recipe/100/notes */
  noteGetNotes(params: { "recipeId": number; "pg"?: number; "rpp"?: number }): Promise<any> {
    return this._request("GET", "/recipe/{recipeId}/notes", { params });
  }

  /** Get all the photos for a recipe */
  imagesGetRecipePhotos(params: { "recipeId": number; "pg"?: number; "rpp"?: number }): Promise<any> {
    return this._request("GET", "/recipe/{recipeId}/photos", { params });
  }

  /** Get recipes related to the given recipeId */
  recipeRelated(params: { "recipeId": number; "pg"?: number; "rpp"?: number }): Promise<any> {
    return this._request("GET", "/recipe/{recipeId}/related", { params });
  }

  /** Get *my* review for the recipe {recipeId}, where "me" is determined by standard authentication headers */
  getrecipeRecipeidReview(params: { "recipeId": number }): Promise<any> {
    return this._request("GET", "/recipe/{recipeId}/review", { params });
  }

  /** Add a new review. Only one review can be provided per {userId, recipeId} pair. Otherwise your review will be updated. */
  reviewPost(params: { "recipeId": number }): Promise<any> {
    return this._request("POST", "/recipe/{recipeId}/review", { params });
  }

  /** Get a given review - DEPRECATED. See recipe/review/{reviewId} for the current usage.
            Beginning in January 2017, BigOven moded from an integer-based ID system to a GUID-style string-based ID system for reviews and replies.
            We are also supporting more of a "Google Play" style model for Reviews and Replies. That is, there are top-level Reviews and then
            an unlimited list of replies (which do not carry star ratings) underneath existing reviews. Also, a given user can only have one review 
            per recipe. Existing legacy endpoints will continue to work, but we strongly recommend you migrate to using the newer endpoints listed
            which do NOT carry the "DEPRECATED" flag. */
  reviewGet(params: { "reviewId": number; "recipeId": number }): Promise<any> {
    return this._request("GET", "/recipe/{recipeId}/review/{reviewId}", { params });
  }

  /** HTTP PUT (update) a recipe review. DEPRECATED. Please see recipe/review/{reviewId} PUT for the new endpoint.
            We are moving to a string-based primary key system, no longer integers, for reviews and replies. */
  reviewPutLegacy(body: unknown, params: { "reviewId": number; "recipeId": number }): Promise<any> {
    return this._request("PUT", "/recipe/{recipeId}/review/{reviewId}", { body, params });
  }

  /** DEPRECATED! - Deletes a review by recipeId and reviewId. Please use recipe/review/{reviewId} instead. */
  reviewDelete(params: { "recipeId": number; "reviewId": number }): Promise<any> {
    return this._request("DELETE", "/recipe/{recipeId}/review/{reviewId}", { params });
  }

  /** Get paged list of reviews for a recipe. Each review will have at most one FeaturedReply, as well as a ReplyCount. */
  reviewGetReviews(params: { "recipeId": number; "pg"?: number; "rpp"?: number }): Promise<any> {
    return this._request("GET", "/recipe/{recipeId}/reviews", { params });
  }

  /** Gets a list of RecipeScan images for the recipe. There will be at most 3 per recipe. */
  imagesGetScanImages(params: { "recipeId": number }): Promise<any> {
    return this._request("GET", "/recipe/{recipeId}/scans", { params });
  }

  /** Search for recipes. There are many parameters that you can apply. Starting with the most common, use title_kw to search within a title.
            Use any_kw to search across the entire recipe.
            If you'd like to limit by course, set the parameter "include_primarycat" to one of (appetizers,bread,breakfast,dessert,drinks,maindish,salad,sidedish,soup,marinades,other).
            If you'd like to exclude a category, set exclude_cat to one or more (comma-separated) list of those categories to exclude.
            If you'd like to include a category, set include_cat to one or more (comma-separated) of those categories to include.
            To explicitly include an ingredient in your search, set the parameter "include_ing" to a CSV of up to three ingredients, e.g.:include_ing=mustard,chicken,beef%20tips
            To explicitly exclude an ingredient in your search, set the parameter "exclude_ing" to a CSV of up to three ingredients.
            All searches must contain the paging parameters pg and rpp, which are integers, and represent the page number (1-based) and results per page (rpp).
            So, to get the third page of a result set paged with 25 recipes per page, you'd pass pg=3&amp;rpp=25
            If you'd like to target searches to just a single target user's recipes, set userId=the target userId (number).
            Or, you can set username=theirusername
            vtn;vgn;chs;glf;ntf;dyf;sff;slf;tnf;wmf;rmf;cps
            cuisine
            photos
            filter=added,try,favorites,myrecipes\r\n\r\n
            folder=FolderNameCaseSensitive
            coll=ID of Collection */
  recipeRecipeSearch(params: { "any_kw"?: string; "folder"?: string; "coll"?: number; "filter"?: string; "title_kw"?: string; "userId"?: number; "username"?: string; "token"?: string; "photos"?: boolean; "boostmine"?: boolean; "include_cat"?: string; "exclude_cat"?: string; "include_primarycat"?: string; "exclude_primarycat"?: string; "include_ing"?: string; "exclude_ing"?: string; "cuisine"?: string; "db"?: string; "userset"?: string; "servingsMin"?: number; "totalMins"?: number; "maxIngredients"?: number; "minIngredients"?: number; "rpp"?: number; "pg"?: number; "vtn"?: number; "vgn"?: number; "chs"?: number; "glf"?: number; "ntf"?: number; "dyf"?: number; "sff"?: number; "slf"?: number; "tnf"?: number; "wmf"?: number; "rmf"?: number; "cps"?: number; "champion"?: number; "synonyms"?: boolean }): Promise<any> {
    return this._request("GET", "/recipes", { params });
  }

  /** Get a random, home-page-quality Recipe. */
  recipeGetRandomRecipe(): Promise<any> {
    return this._request("GET", "/recipes/random", {});
  }

  /** Get the recipe/comment tuples for those recipes with 4 or 5 star ratings */
  recipeRaves(params: { "pg"?: number; "rpp"?: number }): Promise<any> {
    return this._request("GET", "/recipes/raves", { params });
  }

  /** Get a list of recipes that the authenticated user has most recently viewed */
  recipeRecentViews(params: { "pg"?: number; "rpp"?: number }): Promise<any> {
    return this._request("GET", "/recipes/recentviews", { params });
  }

  /** Search for recipes. There are many parameters that you can apply. Starting with the most common, use title_kw to search within a title.
            Use any_kw to search across the entire recipe.
            If you'd like to limit by course, set the parameter "include_primarycat" to one of (appetizers,bread,breakfast,dessert,drinks,maindish,salad,sidedish,soup,marinades,other).
            If you'd like to exclude a category, set exclude_cat to one or more (comma-separated) list of those categories to exclude.
            If you'd like to include a category, set include_cat to one or more (comma-separated) of those categories to include.
            To explicitly include an ingredient in your search, set the parameter "include_ing" to a CSV of up to three ingredients, e.g.:include_ing=mustard,chicken,beef%20tips
            To explicitly exclude an ingredient in your search, set the parameter "exclude_ing" to a CSV of up to three ingredients.
            All searches must contain the paging parameters pg and rpp, which are integers, and represent the page number (1-based) and results per page (rpp).
            So, to get the third page of a result set paged with 25 recipes per page, you'd pass pg=3&amp;rpp=25
            If you'd like to target searches to just a single target user's recipes, set userId=the target userId (number).
            Or, you can set username=theirusername
            vtn;vgn;chs;glf;ntf;dyf;sff;slf;tnf;wmf;rmf;cps
            cuisine
            photos
            filter=added,try,favorites,myrecipes\r\n\r\n
            folder=FolderNameCaseSensitive
            coll=ID of Collection */
  recipeRecipeSearchRandom(params: { "any_kw"?: string; "folder"?: string; "coll"?: number; "filter"?: string; "title_kw"?: string; "userId"?: number; "username"?: string; "token"?: string; "photos"?: boolean; "boostmine"?: boolean; "include_cat"?: string; "exclude_cat"?: string; "include_primarycat"?: string; "exclude_primarycat"?: string; "include_ing"?: string; "exclude_ing"?: string; "cuisine"?: string; "db"?: string; "userset"?: string; "servingsMin"?: number; "totalMins"?: number; "maxIngredients"?: number; "minIngredients"?: number; "vtn"?: number; "vgn"?: number; "chs"?: number; "glf"?: number; "ntf"?: number; "dyf"?: number; "sff"?: number; "slf"?: number; "tnf"?: number; "wmf"?: number; "rmf"?: number; "cps"?: number; "champion"?: number; "synonyms"?: boolean }): Promise<any> {
    return this._request("GET", "/recipes/top25random", { params });
  }

  /** Same as GET recipe but also includes the recipe videos (if any) */
  recipeGetV2(params: { "id": number; "prefetch"?: boolean }): Promise<any> {
    return this._request("GET", "/recipes/{id}", { params });
  }
}

export default Api1000000RecipeandGroceryListAPIv2;