Grocery Shopping API Reference

type ShopRequest struct {
	// URL containing recipes or shopping lists.
	// The content must be accessible via a simple HTTP GET request (no authentication, no client-side JavaScript, etc.).
	// If the content is not accessible, use a scraping service and pass the content as plain text in the field below.
	ContentUrl string `json:"content_url"`

	// Free-form text describing a recipe or a shopping list.
	ContentText string `json:"content_text"`

	// Image of a recipe or a shopping list.
	ContentImageUrl string `json:"content_image,omitempty"`

	// The supermarket in which to search for products.
	// This is optional - if not specified we will automatically pick a supermarket, suitable for the user's location.
	SupermarketDomain SupermarketDomain `json:"supermarket_domain,omitempty"`
}

type ShopResponse struct {
	// A URL pointing to "https://s.pepesto.com".
	// Opening the result page allows the user to view the intended products and complete the purchase.
	// The result page can either be opened in an external browser, or embedded as an iframe in a client website, or app.
	//
	// Here is a simple HTML that can be used for embedding:
	// ---
	// <div id="pepesto-widget-container"></div>
	// <script src="https://s.pepesto.com/get_recipe.js" data-source-url="REDIRECT_URL_RETURNED_BY_THE_SHOPPING_API"></script>
	// ---
	RedirectUrl string `json:"redirect_url"`
}


// List of supported supermarket domains can be found at https://api.pepesto.com/supermarkets
type SupermarketDomain string

type PredirectRequest struct {
	ShoppingList string `json:"shopping_list"`

	// User's locale (e.g., "de-DE").
	Locale Locale `json:"locale,omitempty"`
}

type PredirectResponse struct {
	// Deferred deep link to Pepesto's mobile app. Opening it starts parsing the
	// shopping list supplied in the request body.
	RedirectUrl string `json:"redirect_url"`
}


type Locale string

type ParseRecipeRequest struct {
	// The URL of the recipe to parse. Exactly one of `RecipeUrl` or `RecipeText` must be provided.
	RecipeUrl string `json:"recipe_url"`

	// The recipe text to parse. Exactly one of `RecipeUrl` or `RecipeText` must be provided.
	RecipeText string `json:"recipe_text,omitempty"`

	// Deprecated: temporary rollout field. If set to a supermarket supported by the next-gen matcher,
	// /parse returns a KgToken containing a matcher interpretation instead of the legacy recipe payload.
	DeprecatedDomain SupermarketDomain `json:"deprecated_domain,omitempty"`
}

type ParseRecipeResponse struct {
	KgToken KgToken `json:"kg_token"`

	// Deprecated, we only popuate the KG token within this field
	DeprecatedRecipe RetrievedRecipe `json:"recipe,omitempty"`
}


type KgToken string


type RetrievedRecipe struct {
	// The human-readable title, ingredients, and cooking steps for the recipe.
	// Typically in English but translated based on the `Personalization.Locale` setting.
	Title       string   `json:"title,omitempty"`
	Ingredients []string `json:"ingredients,omitempty"`
	Steps       []string `json:"steps,omitempty"`

	// URL of a 1024x1024px image of the recipe in WebP format.
	ImageUrl string `json:"image_url,omitempty"`

	// The nutritional information for the recipe.
	Nutrition Nutrition `json:"nutrition,omitempty"`

	// Allergens
	Allergens []string `json:"allergens,omitempty"`

	// Portions. This field is not guaranteed to be set.
	Portions Portions `json:"portions,omitempty"`

	// An opaque, encrypted token representing the semantic understanding of the recipe's ingredients.
	// This token is required when calling the "products" endpoint.
	KgToken KgToken `json:"kg_token,omitempty"`
}


// List of supported supermarket domains can be found at https://api.pepesto.com/supermarkets
type SupermarketDomain string


type Nutrition struct {
	// Number of calories in the recipe.
	Calories int `json:"calories,omitempty"`
	// Number of grams of carbohydrates in the recipe.
	CarbohydratesGrams int `json:"carbohydrates_grams,omitempty"`
	// Number of grams of protein in the recipe.
	ProteinGrams int `json:"protein_grams,omitempty"`
	// Number of grams of fat in the recipe.
	FatGrams int `json:"fat_grams,omitempty"`
}

type Portions struct {
	From int `json:"from"`
	To   int `json:"to"`
}

type SuggestRecipesRequest struct {
	QueryRecipe string `json:"query"`

	// Optional personalization settings to tailor recipe retrieval to the user's preferences.
	// These preferences are stored for future use.
	Personalization *Personalization `json:"personalization,omitempty"`
}

type SuggestRecipesResponse struct {
	// An array of retrieved recipes.
	Recipes []RetrievedRecipe `json:"recipes,omitempty"`

	// A short, human-readable response to the user's query, localized to the user's language.
	// For subsequent query turns, this response should be appended to the `Query` field of the next `SuggestRecipesRequest`.
	ShortResponse string `json:"short_response,omitempty"`
}

type RecipeQueryDialogTurn struct {
	// The content of the query turn. This can be free text (e.g., "I'm looking for a quick and easy dinner recipe") or more structured (e.g., "cuisine:Italian ingredients:tomato").
	Content string `json:"content,omitempty"`

	// The role of the participant issuing this query turn. Must be either "user" or "assistant" (Pepesto). This mirrors the structure of chat completion APIs in large language models like OpenAI's.
	Role string `json:"role,omitempty"`

	// Specifies whether the query represents a strict requirement or a preference.
	//
	// If `true`, all returned recipes *must* satisfy the query (e.g., "cuisine:Greek" - all recipes should be Greek).
	// If `false`, the query is treated as a preference or suggestion (e.g., "I have chickpeas at home" - some recipes may contain chickpeas, but it's not a requirement).
	Strict bool `json:"strict,omitempty"`
}

type Personalization struct {
	// The locale in which recipes should be translated (e.g., "de-DE").  Defaults to "en-UK" if empty.
	Locale Locale `json:"locale,omitempty"`

	// The number of people the recipes should serve.  Recipes will be scaled accordingly. Defaults to 3.
	Portions int `json:"portions,omitempty"`

	// The user's preferred supermarket (e.g., "coop.ch").  Used to prioritize recipes with ingredients available at that supermarket or on promotion.
	SupermarketDomain SupermarketDomain `json:"supermarket_domain,omitempty"`
}


type Locale string


type RetrievedRecipe struct {
	// The human-readable title, ingredients, and cooking steps for the recipe.
	// Typically in English but translated based on the `Personalization.Locale` setting.
	Title       string   `json:"title,omitempty"`
	Ingredients []string `json:"ingredients,omitempty"`
	Steps       []string `json:"steps,omitempty"`

	// URL of a 1024x1024px image of the recipe in WebP format.
	ImageUrl string `json:"image_url,omitempty"`

	// The nutritional information for the recipe.
	Nutrition Nutrition `json:"nutrition,omitempty"`

	// Allergens
	Allergens []string `json:"allergens,omitempty"`

	// Portions. This field is not guaranteed to be set.
	Portions Portions `json:"portions,omitempty"`

	// An opaque, encrypted token representing the semantic understanding of the recipe's ingredients.
	// This token is required when calling the "products" endpoint.
	KgToken KgToken `json:"kg_token,omitempty"`
}


type Nutrition struct {
	// Number of calories in the recipe.
	Calories int `json:"calories,omitempty"`
	// Number of grams of carbohydrates in the recipe.
	CarbohydratesGrams int `json:"carbohydrates_grams,omitempty"`
	// Number of grams of protein in the recipe.
	ProteinGrams int `json:"protein_grams,omitempty"`
	// Number of grams of fat in the recipe.
	FatGrams int `json:"fat_grams,omitempty"`
}

type Portions struct {
	From int `json:"from"`
	To   int `json:"to"`
}


// List of supported supermarket domains can be found at https://api.pepesto.com/supermarkets
type SupermarketDomain string


type KgToken string

type OfferProductsRequest struct {
	// Tokens for recipes retrieved by the /suggest or /parse endpoints.
	RecipeKgTokens []KgToken `json:"recipe_kg_tokens"`

	// A free-text shopping list (e.g., "4 eggs, pasta, 2 chicken breasts"). Maximum length: 5000 characters.
	ManualShoppingList string `json:"manual_shopping_list,omitempty"`

	// The supermarket in which to search for products.
	// Required. List of supported supermarket domains can be found at https://api.pepesto.com/supermarkets.
	SupermarketDomain SupermarketDomain `json:"supermarket_domain,omitempty"`

	// Product URLs preferred by the user. Used by the next-gen matcher to boost matching products.
	PreferredProductUrls []string `json:"preferred_product_urls,omitempty"`

	// The locale in which to display item names in the response (e.g., "de-DE").
	ItemNamesLocale Locale `json:"item_names_locale,omitempty"`
}

type OfferProductsReponse struct {
	// A list of items and their corresponding products.
	Items []ItemToProducts `json:"items,omitempty"`

	// A list of items that were present in the request, but we could not find any suitable matching products for them.
	// Either because the item was not found in the index, or because it was not available in the selected supermarket.
	NotIndexedItems []string `json:"not_indexed_items,omitempty"`

	// Currency code of the resolved supermarket.
	Currency string `json:"currency,omitempty"`
}


// For a given item (e.g., "eggs"), a list of possible products that the user can buy.
// The list is sorted, with the most appropriate product listed first.
// Sorting criteria include user preferences and past purchases, minimizing food waste and costs, choosing higher quality/bio products, and product reviews.
// An empty list indicates that no suitable products were found in the index for this item. Appropriate products may still be offered in Pepesto's UI during checkout.
type ItemToProducts struct {
	// Human-readable item name (e.g., "eggs").
	ItemName string `json:"item_name,omitempty"`

	// Concrete supermarket products offered to the user for this item.
	Products []ProductAndSuggestedQuantity `json:"products,omitempty"`
}


type KgToken string


type Locale string


// List of supported supermarket domains can be found at https://api.pepesto.com/supermarkets
type SupermarketDomain string


// Specifies the quantity of a product to buy.
// If `NumUnitsToBuy` is zero, Pepesto suggests treating the product as a checklist item.
// In this case, Pepesto doesn't suggest buying it by default but displays it in the UI as a reminder (useful for pantry staples like salt).
type ProductAndSuggestedQuantity struct {
	// The product.
	Product IndexedProduct `json:"product,omitempty"`

	// A session token that can be used as an input to /session endpoint.
	SessionToken SessionToken `json:"session_token,omitempty"`

	// The number of units to buy.  A value of 0 indicates a checklist item.
	NumUnitsToBuy int `json:"num_units_to_buy,omitempty"`
}


type IndexedProduct struct {
	// The product name, capturing the most important aspects. Displayed in the default language for the selected `SupermarketDomain`.
	ProductName string `json:"product_name,omitempty"`

	// The product category (e.g., "canned tomatoes", "pasta", etc.).
	Category string `json:"category,omitempty"`

	// The quantity per unit of this product.
	Quantity *QuantityPerUnit `json:"quantity,omitempty"`

	// The price per unit of this product.
	Price *PricePerUnit `json:"price,omitempty"`

	// This is typically URL of the product page on the supermarket's website.
	ProductId string `json:"product_id,omitempty"`

	// URL of an image of the product, usually points to retailer's website.
	ImageUrl string `json:"image_url,omitempty"`

	// URL of an image of the product hosted by Pepesto (not the retailer's website).
	PepestoHostedImageUrl string `json:"pepesto_hosted_image_url,omitempty"`

	// A unique identifier for products sold in multiple supermarket chains.  Allows comparing prices for the same product across different supermarkets.  Populated only for packaged products commonly sold in multiple chains.
	UniversalId int64 `json:"universal_id,omitempty"`

	Classification *ProductClassification `json:"classification,omitempty"`

	// A token that can be passed to the /session endpoint to create a session with this product, if
	// the client app, or the user chooses to add this product to the shopping cart.
	SessionToken SessionToken `json:"session_token,omitempty"`
}


type SessionToken string


type ProductClassification struct {
	IsBio          bool `json:"is_bio,omitempty"`
	IsFrozen       bool `json:"is_frozen,omitempty"`
	IsSubstitution bool `json:"is_substitution,omitempty"`
}

type QuantityPerUnit struct {
	// Estimated weight per unit (in grams).
	Grams float64 `json:"grams,omitempty"`

	// Volume per unit (in milliliters). Used for liquid products (e.g., 100ml of milk).
	Milliliters float64 `json:"milliliters,omitempty"`

	// Number of pieces per unit (e.g., 2 for a package of 2 chicken breasts).
	Pieces float64 `json:"pieces,omitempty"`

	// Number of bunches per unit (e.g., 2 bunches of parsley).
	Bunches float64 `json:"bunches,omitempty"`
}

type PricePerUnit struct {
	// Price of the product in the smallest currency unit used by the `SupermarketDomain` (e.g., 199 represents 1.99 CHF for coop.ch).
	Price int `json:"price,omitempty"`

	// Price promotion details.
	Promotion PricePromotion `json:"promotion,omitempty"`
}

type PricePromotion struct {
	// `true` if the product is currently on promotion.
	Promo bool `json:"promo,omitempty"`

	// Price discount percentage (not always available).  May not be populated, or the promotion may be of a different type (e.g., "buy 2 get 3").
	PromoPercentage float64 `json:"promo_percentage,omitempty"`
}

const MaxCustomProductsPerSearch = 10

type CustomProductsSearchRequest struct {
	// Free text descriptions of the products that we should search for.
	// E.g. 'organic strawberries 500g, H-Milch 3.5% 1L, free-range eggs 10-pack'.
	// At most MaxCustomProductsPerSearch products may be specified.
	Products []string `json:"products"`

	// Supermarket where we should search these items
	SupermarketDomain SupermarketDomain `json:"supermarket_domain"`

	// A webhook that should be called once the search is completed.
	// If specified, we make HTTP POST request to this URL with empty body.
	// Note: we append "sid=$sessionId" argument when calling your webhook.
	// The sessionId is the same as the session ID in the response.
	WebhookURL string `json:"webhook_url,omitempty"`
}

type CustomProductsSearchResponse struct {
	// Session ID that can be passed to /retrieve endpoint to retrieve the results of this search.
	SearchSessionId string `json:"search_session_id"`
}


// List of supported supermarket domains can be found at https://api.pepesto.com/supermarkets
type SupermarketDomain string

type RetrieveCustomProductSearchRequest struct {
	// The session ID returned from /search endpoint.
	SearchSessionId string `json:"search_session_id"`
}

type RetrieveCustomProductSearchResponse struct {
	// One of "queued" (accepted, but not started yet), "in_progress", "done".
	Status string `json:"status"`

	// Populated only when status is "done".
	// Contains exactly as many elements as were passed in the original request.
	Items []ItemToProducts `json:"items,omitempty"`

	// Currency code of the resolved supermarket.
	Currency string `json:"currency,omitempty"`
}


// For a given item (e.g., "eggs"), a list of possible products that the user can buy.
// The list is sorted, with the most appropriate product listed first.
// Sorting criteria include user preferences and past purchases, minimizing food waste and costs, choosing higher quality/bio products, and product reviews.
// An empty list indicates that no suitable products were found in the index for this item. Appropriate products may still be offered in Pepesto's UI during checkout.
type ItemToProducts struct {
	// Human-readable item name (e.g., "eggs").
	ItemName string `json:"item_name,omitempty"`

	// Concrete supermarket products offered to the user for this item.
	Products []ProductAndSuggestedQuantity `json:"products,omitempty"`
}


// Specifies the quantity of a product to buy.
// If `NumUnitsToBuy` is zero, Pepesto suggests treating the product as a checklist item.
// In this case, Pepesto doesn't suggest buying it by default but displays it in the UI as a reminder (useful for pantry staples like salt).
type ProductAndSuggestedQuantity struct {
	// The product.
	Product IndexedProduct `json:"product,omitempty"`

	// A session token that can be used as an input to /session endpoint.
	SessionToken SessionToken `json:"session_token,omitempty"`

	// The number of units to buy.  A value of 0 indicates a checklist item.
	NumUnitsToBuy int `json:"num_units_to_buy,omitempty"`
}


type IndexedProduct struct {
	// The product name, capturing the most important aspects. Displayed in the default language for the selected `SupermarketDomain`.
	ProductName string `json:"product_name,omitempty"`

	// The product category (e.g., "canned tomatoes", "pasta", etc.).
	Category string `json:"category,omitempty"`

	// The quantity per unit of this product.
	Quantity *QuantityPerUnit `json:"quantity,omitempty"`

	// The price per unit of this product.
	Price *PricePerUnit `json:"price,omitempty"`

	// This is typically URL of the product page on the supermarket's website.
	ProductId string `json:"product_id,omitempty"`

	// URL of an image of the product, usually points to retailer's website.
	ImageUrl string `json:"image_url,omitempty"`

	// URL of an image of the product hosted by Pepesto (not the retailer's website).
	PepestoHostedImageUrl string `json:"pepesto_hosted_image_url,omitempty"`

	// A unique identifier for products sold in multiple supermarket chains.  Allows comparing prices for the same product across different supermarkets.  Populated only for packaged products commonly sold in multiple chains.
	UniversalId int64 `json:"universal_id,omitempty"`

	Classification *ProductClassification `json:"classification,omitempty"`

	// A token that can be passed to the /session endpoint to create a session with this product, if
	// the client app, or the user chooses to add this product to the shopping cart.
	SessionToken SessionToken `json:"session_token,omitempty"`
}


type SessionToken string


type ProductClassification struct {
	IsBio          bool `json:"is_bio,omitempty"`
	IsFrozen       bool `json:"is_frozen,omitempty"`
	IsSubstitution bool `json:"is_substitution,omitempty"`
}

type QuantityPerUnit struct {
	// Estimated weight per unit (in grams).
	Grams float64 `json:"grams,omitempty"`

	// Volume per unit (in milliliters). Used for liquid products (e.g., 100ml of milk).
	Milliliters float64 `json:"milliliters,omitempty"`

	// Number of pieces per unit (e.g., 2 for a package of 2 chicken breasts).
	Pieces float64 `json:"pieces,omitempty"`

	// Number of bunches per unit (e.g., 2 bunches of parsley).
	Bunches float64 `json:"bunches,omitempty"`
}

type PricePerUnit struct {
	// Price of the product in the smallest currency unit used by the `SupermarketDomain` (e.g., 199 represents 1.99 CHF for coop.ch).
	Price int `json:"price,omitempty"`

	// Price promotion details.
	Promotion PricePromotion `json:"promotion,omitempty"`
}

type PricePromotion struct {
	// `true` if the product is currently on promotion.
	Promo bool `json:"promo,omitempty"`

	// Price discount percentage (not always available).  May not be populated, or the promotion may be of a different type (e.g., "buy 2 get 3").
	PromoPercentage float64 `json:"promo_percentage,omitempty"`
}

// Re-uses the request and response types from session.go
type MCheckoutRequest = CreateSessionRequest
type MCheckoutResponse = CreateSessionResponse


// CreateSessionRequest creates a checkout session for the given supermarket and
// products that must be added to the user's shopping cart.
type CreateSessionRequest struct {
	SupermarketDomain SupermarketDomain `json:"supermarket_domain"`
	UserLocale        Locale            `json:"user_locale,omitempty"`
	RedirectUrl       string            `json:"redirect_url,omitempty"`

	// List of SKUs returned by /products
	SKUs []TokenAndSuggestedQuantity `json:"skus,omitempty"`

	// Deprecated - do not use - use Items instead.
	DeprecatedItems []ProductAndSuggestedQuantity `json:"items,omitempty"`

	// List of additional free-text items that have not yet been matched to concrete
	// products. Our agent will search for these items during the checkout session.
	UnresolvedItems []string `json:"unresolved_items,omitempty"`
}

type TokenAndSuggestedQuantity struct {
	SessionToken  SessionToken `json:"session_token,omitempty"`
	NumUnitsToBuy int          `json:"num_units_to_buy,omitempty"`
}

type CreateSessionResponse struct {
	// SessionId is always returned.
	//
	// If ChargeUser was set to true in the request, the session has been
	// created but is not yet ready for checkout. The referrer should wait for
	// the ChargedUserWebhook callback before proceeding with the checkout flow.
	SessionId string `json:"session_id"`

	// Deferred deep link to Pepesto's mobile app.
	// Client app can redirect their user to this URL. Once the user installs and opens the Pepesto app,
	// checkout will start automatically with the created session.
	MobileHostedUrl string `json:"mobile_hosted_url,omitempty"`
}


type Locale string


// Specifies the quantity of a product to buy.
// If `NumUnitsToBuy` is zero, Pepesto suggests treating the product as a checklist item.
// In this case, Pepesto doesn't suggest buying it by default but displays it in the UI as a reminder (useful for pantry staples like salt).
type ProductAndSuggestedQuantity struct {
	// The product.
	Product IndexedProduct `json:"product,omitempty"`

	// A session token that can be used as an input to /session endpoint.
	SessionToken SessionToken `json:"session_token,omitempty"`

	// The number of units to buy.  A value of 0 indicates a checklist item.
	NumUnitsToBuy int `json:"num_units_to_buy,omitempty"`
}


type SessionToken string


// List of supported supermarket domains can be found at https://api.pepesto.com/supermarkets
type SupermarketDomain string


type IndexedProduct struct {
	// The product name, capturing the most important aspects. Displayed in the default language for the selected `SupermarketDomain`.
	ProductName string `json:"product_name,omitempty"`

	// The product category (e.g., "canned tomatoes", "pasta", etc.).
	Category string `json:"category,omitempty"`

	// The quantity per unit of this product.
	Quantity *QuantityPerUnit `json:"quantity,omitempty"`

	// The price per unit of this product.
	Price *PricePerUnit `json:"price,omitempty"`

	// This is typically URL of the product page on the supermarket's website.
	ProductId string `json:"product_id,omitempty"`

	// URL of an image of the product, usually points to retailer's website.
	ImageUrl string `json:"image_url,omitempty"`

	// URL of an image of the product hosted by Pepesto (not the retailer's website).
	PepestoHostedImageUrl string `json:"pepesto_hosted_image_url,omitempty"`

	// A unique identifier for products sold in multiple supermarket chains.  Allows comparing prices for the same product across different supermarkets.  Populated only for packaged products commonly sold in multiple chains.
	UniversalId int64 `json:"universal_id,omitempty"`

	Classification *ProductClassification `json:"classification,omitempty"`

	// A token that can be passed to the /session endpoint to create a session with this product, if
	// the client app, or the user chooses to add this product to the shopping cart.
	SessionToken SessionToken `json:"session_token,omitempty"`
}


type ProductClassification struct {
	IsBio          bool `json:"is_bio,omitempty"`
	IsFrozen       bool `json:"is_frozen,omitempty"`
	IsSubstitution bool `json:"is_substitution,omitempty"`
}

type QuantityPerUnit struct {
	// Estimated weight per unit (in grams).
	Grams float64 `json:"grams,omitempty"`

	// Volume per unit (in milliliters). Used for liquid products (e.g., 100ml of milk).
	Milliliters float64 `json:"milliliters,omitempty"`

	// Number of pieces per unit (e.g., 2 for a package of 2 chicken breasts).
	Pieces float64 `json:"pieces,omitempty"`

	// Number of bunches per unit (e.g., 2 bunches of parsley).
	Bunches float64 `json:"bunches,omitempty"`
}

type PricePerUnit struct {
	// Price of the product in the smallest currency unit used by the `SupermarketDomain` (e.g., 199 represents 1.99 CHF for coop.ch).
	Price int `json:"price,omitempty"`

	// Price promotion details.
	Promotion PricePromotion `json:"promotion,omitempty"`
}

type PricePromotion struct {
	// `true` if the product is currently on promotion.
	Promo bool `json:"promo,omitempty"`

	// Price discount percentage (not always available).  May not be populated, or the promotion may be of a different type (e.g., "buy 2 get 3").
	PromoPercentage float64 `json:"promo_percentage,omitempty"`
}

// CreateSessionRequest creates a checkout session for the given supermarket and
// products that must be added to the user's shopping cart.
type CreateSessionRequest struct {
	SupermarketDomain SupermarketDomain `json:"supermarket_domain"`
	UserLocale        Locale            `json:"user_locale,omitempty"`
	RedirectUrl       string            `json:"redirect_url,omitempty"`

	// List of SKUs returned by /products
	SKUs []TokenAndSuggestedQuantity `json:"skus,omitempty"`

	// Deprecated - do not use - use Items instead.
	DeprecatedItems []ProductAndSuggestedQuantity `json:"items,omitempty"`

	// List of additional free-text items that have not yet been matched to concrete
	// products. Our agent will search for these items during the checkout session.
	UnresolvedItems []string `json:"unresolved_items,omitempty"`
}

type TokenAndSuggestedQuantity struct {
	SessionToken  SessionToken `json:"session_token,omitempty"`
	NumUnitsToBuy int          `json:"num_units_to_buy,omitempty"`
}

type CreateSessionResponse struct {
	// SessionId is always returned.
	//
	// If ChargeUser was set to true in the request, the session has been
	// created but is not yet ready for checkout. The referrer should wait for
	// the ChargedUserWebhook callback before proceeding with the checkout flow.
	SessionId string `json:"session_id"`

	// Deferred deep link to Pepesto's mobile app.
	// Client app can redirect their user to this URL. Once the user installs and opens the Pepesto app,
	// checkout will start automatically with the created session.
	MobileHostedUrl string `json:"mobile_hosted_url,omitempty"`
}


type Locale string


// Specifies the quantity of a product to buy.
// If `NumUnitsToBuy` is zero, Pepesto suggests treating the product as a checklist item.
// In this case, Pepesto doesn't suggest buying it by default but displays it in the UI as a reminder (useful for pantry staples like salt).
type ProductAndSuggestedQuantity struct {
	// The product.
	Product IndexedProduct `json:"product,omitempty"`

	// A session token that can be used as an input to /session endpoint.
	SessionToken SessionToken `json:"session_token,omitempty"`

	// The number of units to buy.  A value of 0 indicates a checklist item.
	NumUnitsToBuy int `json:"num_units_to_buy,omitempty"`
}


type SessionToken string


// List of supported supermarket domains can be found at https://api.pepesto.com/supermarkets
type SupermarketDomain string


type IndexedProduct struct {
	// The product name, capturing the most important aspects. Displayed in the default language for the selected `SupermarketDomain`.
	ProductName string `json:"product_name,omitempty"`

	// The product category (e.g., "canned tomatoes", "pasta", etc.).
	Category string `json:"category,omitempty"`

	// The quantity per unit of this product.
	Quantity *QuantityPerUnit `json:"quantity,omitempty"`

	// The price per unit of this product.
	Price *PricePerUnit `json:"price,omitempty"`

	// This is typically URL of the product page on the supermarket's website.
	ProductId string `json:"product_id,omitempty"`

	// URL of an image of the product, usually points to retailer's website.
	ImageUrl string `json:"image_url,omitempty"`

	// URL of an image of the product hosted by Pepesto (not the retailer's website).
	PepestoHostedImageUrl string `json:"pepesto_hosted_image_url,omitempty"`

	// A unique identifier for products sold in multiple supermarket chains.  Allows comparing prices for the same product across different supermarkets.  Populated only for packaged products commonly sold in multiple chains.
	UniversalId int64 `json:"universal_id,omitempty"`

	Classification *ProductClassification `json:"classification,omitempty"`

	// A token that can be passed to the /session endpoint to create a session with this product, if
	// the client app, or the user chooses to add this product to the shopping cart.
	SessionToken SessionToken `json:"session_token,omitempty"`
}


type ProductClassification struct {
	IsBio          bool `json:"is_bio,omitempty"`
	IsFrozen       bool `json:"is_frozen,omitempty"`
	IsSubstitution bool `json:"is_substitution,omitempty"`
}

type QuantityPerUnit struct {
	// Estimated weight per unit (in grams).
	Grams float64 `json:"grams,omitempty"`

	// Volume per unit (in milliliters). Used for liquid products (e.g., 100ml of milk).
	Milliliters float64 `json:"milliliters,omitempty"`

	// Number of pieces per unit (e.g., 2 for a package of 2 chicken breasts).
	Pieces float64 `json:"pieces,omitempty"`

	// Number of bunches per unit (e.g., 2 bunches of parsley).
	Bunches float64 `json:"bunches,omitempty"`
}

type PricePerUnit struct {
	// Price of the product in the smallest currency unit used by the `SupermarketDomain` (e.g., 199 represents 1.99 CHF for coop.ch).
	Price int `json:"price,omitempty"`

	// Price promotion details.
	Promotion PricePromotion `json:"promotion,omitempty"`
}

type PricePromotion struct {
	// `true` if the product is currently on promotion.
	Promo bool `json:"promo,omitempty"`

	// Price discount percentage (not always available).  May not be populated, or the promotion may be of a different type (e.g., "buy 2 get 3").
	PromoPercentage float64 `json:"promo_percentage,omitempty"`
}

import pb "pepesto.com/go/proto"

// NextCheckoutIterationRequest represents the request body for advancing
// a checkout-driving session by one "turn" over a REST API.
//
// External clients:
//   - NEVER create sessions via this API.
//   - MUST always provide a valid ContinueSessionID obtained from Pepesto
//     (e.g. via the Pepesto app or other Pepesto APIs).
//
// On each call, the client:
//  1. Sends the current ContinueSessionID (the active session).
//  2. Optionally provides results from the previous instruction:
//     - PrevTurnResponse (JS execution result)
//     - Screenshot (page screenshot)
//  3. Receives a NextCheckoutIterationResponse with an instruction to execute.
type NextCheckoutIterationRequest struct {
	// ContinueSessionID is the ID of an existing driver session that the client
	// wants to advance.
	//
	// This value:
	//   - MUST be obtained by external clients via an out-of-band mechanism
	//     (Pepesto app, grocery search API, etc.).
	//   - MUST be echoed on every subsequent request for the same session.
	ContinueSessionID string `json:"continue_session_id"`

	// PrevTurnResponse contains the result of JavaScript execution performed
	// in response to the previous instruction (if any).
	//
	// If the server did not request JS execution on the previous turn, this
	// should be omitted.
	PrevTurnResponse *JsExecutionResult `json:"prev_turn_response,omitempty"`

	// Screenshot represents an optional screenshot taken after executing the
	// previous instruction. It's a base-64 encoded value.
	//
	// Clients should attach this when the previous response had
	// AttachScreenshotOnNextTurn = true.
	Screenshot string `json:"screenshot,omitempty"`
}

// JsExecutionResult carries the outcome of JavaScript execution done by
// the client on the previous turn.
type JsExecutionResult struct {
	// Result is the string returned by the JavaScript function when
	// execution succeeds.
	Result string `json:"result,omitempty"`

	// Error is a description of why execution failed (JS error, timeout, etc.).
	// If non-empty, the server should treat the execution as failed and prefer
	// this field over Result.
	Error string `json:"error,omitempty"`
}

// NextCheckoutIterationResponse represents the server's response for each turn.
//
// It contains:
//   - SessionID: the session that was advanced.
//   - Exactly one of the instruction fields set (LoadPage, etc.).
//   - Optional metadata for UI/debugging (AttachScreenshotOnNextTurn).
type NextCheckoutIterationResponse struct {
	ProtoResp *pb.NextCheckoutIterationResponse `json:"proto"`
}

type RetrieveCatalogRequest struct {
	// The supermarket for which to retrieve the catalog.
	SupermarketDomain SupermarketDomain `json:"supermarket_domain"`
}

type RetrieveCatalogResponse struct {
	// A list of indexed products.
	Products []IndexedProduct `json:"products,omitempty"`
}


type IndexedProduct struct {
	// The product name, capturing the most important aspects. Displayed in the default language for the selected `SupermarketDomain`.
	ProductName string `json:"product_name,omitempty"`

	// The product category (e.g., "canned tomatoes", "pasta", etc.).
	Category string `json:"category,omitempty"`

	// The quantity per unit of this product.
	Quantity *QuantityPerUnit `json:"quantity,omitempty"`

	// The price per unit of this product.
	Price *PricePerUnit `json:"price,omitempty"`

	// This is typically URL of the product page on the supermarket's website.
	ProductId string `json:"product_id,omitempty"`

	// URL of an image of the product, usually points to retailer's website.
	ImageUrl string `json:"image_url,omitempty"`

	// URL of an image of the product hosted by Pepesto (not the retailer's website).
	PepestoHostedImageUrl string `json:"pepesto_hosted_image_url,omitempty"`

	// A unique identifier for products sold in multiple supermarket chains.  Allows comparing prices for the same product across different supermarkets.  Populated only for packaged products commonly sold in multiple chains.
	UniversalId int64 `json:"universal_id,omitempty"`

	Classification *ProductClassification `json:"classification,omitempty"`

	// A token that can be passed to the /session endpoint to create a session with this product, if
	// the client app, or the user chooses to add this product to the shopping cart.
	SessionToken SessionToken `json:"session_token,omitempty"`
}


// List of supported supermarket domains can be found at https://api.pepesto.com/supermarkets
type SupermarketDomain string


type ProductClassification struct {
	IsBio          bool `json:"is_bio,omitempty"`
	IsFrozen       bool `json:"is_frozen,omitempty"`
	IsSubstitution bool `json:"is_substitution,omitempty"`
}

type QuantityPerUnit struct {
	// Estimated weight per unit (in grams).
	Grams float64 `json:"grams,omitempty"`

	// Volume per unit (in milliliters). Used for liquid products (e.g., 100ml of milk).
	Milliliters float64 `json:"milliliters,omitempty"`

	// Number of pieces per unit (e.g., 2 for a package of 2 chicken breasts).
	Pieces float64 `json:"pieces,omitempty"`

	// Number of bunches per unit (e.g., 2 bunches of parsley).
	Bunches float64 `json:"bunches,omitempty"`
}

type PricePerUnit struct {
	// Price of the product in the smallest currency unit used by the `SupermarketDomain` (e.g., 199 represents 1.99 CHF for coop.ch).
	Price int `json:"price,omitempty"`

	// Price promotion details.
	Promotion PricePromotion `json:"promotion,omitempty"`
}

type PricePromotion struct {
	// `true` if the product is currently on promotion.
	Promo bool `json:"promo,omitempty"`

	// Price discount percentage (not always available).  May not be populated, or the promotion may be of a different type (e.g., "buy 2 get 3").
	PromoPercentage float64 `json:"promo_percentage,omitempty"`
}


type SessionToken string

type RetrieveCatalogRequest struct {
	// The supermarket for which to retrieve the catalog.
	SupermarketDomain SupermarketDomain `json:"supermarket_domain"`
}

type RetrieveCatalogResponse struct {
	// A list of indexed products.
	Products []IndexedProduct `json:"products,omitempty"`
}


type IndexedProduct struct {
	// The product name, capturing the most important aspects. Displayed in the default language for the selected `SupermarketDomain`.
	ProductName string `json:"product_name,omitempty"`

	// The product category (e.g., "canned tomatoes", "pasta", etc.).
	Category string `json:"category,omitempty"`

	// The quantity per unit of this product.
	Quantity *QuantityPerUnit `json:"quantity,omitempty"`

	// The price per unit of this product.
	Price *PricePerUnit `json:"price,omitempty"`

	// This is typically URL of the product page on the supermarket's website.
	ProductId string `json:"product_id,omitempty"`

	// URL of an image of the product, usually points to retailer's website.
	ImageUrl string `json:"image_url,omitempty"`

	// URL of an image of the product hosted by Pepesto (not the retailer's website).
	PepestoHostedImageUrl string `json:"pepesto_hosted_image_url,omitempty"`

	// A unique identifier for products sold in multiple supermarket chains.  Allows comparing prices for the same product across different supermarkets.  Populated only for packaged products commonly sold in multiple chains.
	UniversalId int64 `json:"universal_id,omitempty"`

	Classification *ProductClassification `json:"classification,omitempty"`

	// A token that can be passed to the /session endpoint to create a session with this product, if
	// the client app, or the user chooses to add this product to the shopping cart.
	SessionToken SessionToken `json:"session_token,omitempty"`
}


// List of supported supermarket domains can be found at https://api.pepesto.com/supermarkets
type SupermarketDomain string


type ProductClassification struct {
	IsBio          bool `json:"is_bio,omitempty"`
	IsFrozen       bool `json:"is_frozen,omitempty"`
	IsSubstitution bool `json:"is_substitution,omitempty"`
}

type QuantityPerUnit struct {
	// Estimated weight per unit (in grams).
	Grams float64 `json:"grams,omitempty"`

	// Volume per unit (in milliliters). Used for liquid products (e.g., 100ml of milk).
	Milliliters float64 `json:"milliliters,omitempty"`

	// Number of pieces per unit (e.g., 2 for a package of 2 chicken breasts).
	Pieces float64 `json:"pieces,omitempty"`

	// Number of bunches per unit (e.g., 2 bunches of parsley).
	Bunches float64 `json:"bunches,omitempty"`
}

type PricePerUnit struct {
	// Price of the product in the smallest currency unit used by the `SupermarketDomain` (e.g., 199 represents 1.99 CHF for coop.ch).
	Price int `json:"price,omitempty"`

	// Price promotion details.
	Promotion PricePromotion `json:"promotion,omitempty"`
}

type PricePromotion struct {
	// `true` if the product is currently on promotion.
	Promo bool `json:"promo,omitempty"`

	// Price discount percentage (not always available).  May not be populated, or the promotion may be of a different type (e.g., "buy 2 get 3").
	PromoPercentage float64 `json:"promo_percentage,omitempty"`
}


type SessionToken string

type LinkEmailRequest struct {
	Email string `json:"email"`

	// Set this if you used an alias when purchasing credits.
	// This field can be used to support and distinguish between different
	// api keys for the same email.
	Alias string `json:"alias,omitempty"`
}

type LinkEmailResponse struct {
	ApiKey string `json:"api_key"`
}

type CheckCreditsRequest struct {
}

type CheckCreditsResponse struct {
	EuroCents int64 `json:"euro_cents"`
}