fix: add missing json tags, python readme

Author: ByteSizedMarius

pkg/category_structs.go

@@ -8,17 +8,17 @@ import (
 // ProductResults is the flattened result from product search endpoints.
 // Endpoint: GET /api/products
 type ProductResults struct {
-	Products   []Product
+	Products   []Product `json:"products"`
 	Pagination struct {
-		ObjectsPerPage int
-		CurrentPage    int
-		PageCount      int
-		ObjectCount    int
-	}
+		ObjectsPerPage int `json:"objectsPerPage"`
+		CurrentPage    int `json:"currentPage"`
+		PageCount      int `json:"pageCount"`
+		ObjectCount    int `json:"objectCount"`
+	} `json:"pagination"`
 	SearchTerm struct {
-		Original  string
-		Corrected *string // non-nil if API corrected a typo
-	}
+		Original  string  `json:"original"`
+		Corrected *string `json:"corrected"`
+	} `json:"searchTerm"`
 }
 
 func (pr ProductResults) String() string {

pkg/discounts_struct.go

@@ -118,8 +118,8 @@ type RawOffer struct {
 
 // Discounts is the struct that holds cleaned up discount data.
 type Discounts struct {
-	Categories []DiscountCategory
-	ValidUntil time.Time
+	Categories []DiscountCategory `json:"categories"`
+	ValidUntil time.Time          `json:"validUntil"`
 }
 
 // GroupByProductCategory groups the discounts by their product category and returns the results.
@@ -165,24 +165,24 @@ func (d Discounts) String() string {
 // It contains an index for sorting the categories in their intended order and the actual discounts.
 // Calling GroupByProductCategory reorders the discounts by their product category (z. B. "Nahrungsmittel").
 type DiscountCategory struct {
-	ID     string
-	Title  string
-	Index  int
-	Offers []Discount
+	ID     string     `json:"id"`
+	Title  string     `json:"title"`
+	Index  int        `json:"index"`
+	Offers []Discount `json:"offers"`
 }
 
 // Discount is the actual discount with some of the information provided by rewe.
 type Discount struct {
-	Title           string
-	Subtitle        string
-	Images          []string
-	PriceRaw string
+	Title    string   `json:"title"`
+	Subtitle string   `json:"subtitle"`
+	Images   []string `json:"images"`
+	PriceRaw string   `json:"priceRaw"`
 	// Price is the parsed price in euros. Check PriceParseFail before using -
 	// if true, Price is 0.0 due to parse failure, not because item is free.
-	Price          float64
-	PriceParseFail bool
-	Manufacturer    string
-	ArticleNo       string
-	NutriScore      string
-	ProductCategory string
+	Price           float64 `json:"price"`
+	PriceParseFail  bool    `json:"priceParseFail"`
+	Manufacturer    string  `json:"manufacturer"`
+	ArticleNo       string  `json:"articleNo"`
+	NutriScore      string  `json:"nutriScore"`
+	ProductCategory string  `json:"productCategory"`
 }

pkg/products.go

@@ -179,19 +179,19 @@ func getProductsCommon(marketID string, opts *ProductOpts, queryParams url.Value
 	return ProductResults{
 		Products: raw.Data.Products.Products,
 		Pagination: struct {
-			ObjectsPerPage int
-			CurrentPage    int
-			PageCount      int
-			ObjectCount    int
+			ObjectsPerPage int `json:"objectsPerPage"`
+			CurrentPage    int `json:"currentPage"`
+			PageCount      int `json:"pageCount"`
+			ObjectCount    int `json:"objectCount"`
 		}{
 			ObjectsPerPage: raw.Data.Products.Pagination.ObjectsPerPage,
 			CurrentPage:    raw.Data.Products.Pagination.CurrentPage,
 			PageCount:      raw.Data.Products.Pagination.PageCount,
 			ObjectCount:    raw.Data.Products.Pagination.ObjectCount,
 		},
 		SearchTerm: struct {
-			Original  string
-			Corrected *string
+			Original  string  `json:"original"`
+			Corrected *string `json:"corrected"`
 		}{
 			Original:  raw.Data.Products.Search.Term.Original,
 			Corrected: raw.Data.Products.Search.Term.Corrected,

python/README.md

@@ -27,7 +27,7 @@ python python/build_lib.py
 cd python && pip install -e .
 ```
 
-This builds both the Linux .so and Windows .dll.
+This builds both the Linux .so and Windows .dll. For macOS, see [building from source](#macos).
 
 ## Usage
 
@@ -37,16 +37,92 @@ from rewerse import Rewerse
 client = Rewerse(cert="certificate.pem", key="private.key")
 
 markets = client.market_search("Berlin")
+# [
+#     {
+#         "wwIdent": "8547534",
+#         "name": "REWE Markt",
+#         "companyName": "REWE Karsten Schmidt oHG",
+#         "street": "Schönhauser Allee 80",
+#         "zipCode": "10439",
+#         "city": "Berlin",
+#         "location": {"latitude": 52.54984, "longitude": 13.41488},
+#         "openingStatus": {"openState": "CLOSED", "statusText": "Geschlossen", ...},
+#         "serviceFlags": {"hasPickup": true},
+#         ...
+#     },
+#     ...
+# ]
+
 market_id = markets[0]["wwIdent"]
 
-response = client.get_products(market_id, "Milch")
+products = client.get_products(market_id, "Milch")
+# {
+#     "products": [
+#         {
+#             "productId": "677067",
+#             "title": "Weihenstephan H-Milch 3,5% 1l",
+#             "listing": {
+#                 "currentRetailPrice": 99,
+#                 "grammage": "1l",
+#                 "discount": {"__typename": "RegularProductDiscount", "validTo": "04.04."},
+#                 "loyaltyBonus": {"bonusType": "CENT", "bonusValue": 10},
+#                 ...
+#             },
+#             "attributes": {"isOrganic": false, "isVegan": false, "isBulkyGood": true, ...},
+#             ...
+#         },
+#         ...
+#     ],
+#     "pagination": {"objectsPerPage": 30, "currentPage": 1, "pageCount": 24, "objectCount": 706},
+#     "searchTerm": {"original": "Milch", "corrected": null}
+# }
+
 discounts = client.get_discounts(market_id)
+# {
+#     "categories": [
+#         {
+#             "id": "markt-topangebote",
+#             "title": "Top-Angebote in deinem Markt",
+#             "index": 3,
+#             "offers": [
+#                 {
+#                     "title": "Kinder Riegel",
+#                     "subtitle": "je 18 x 21-g-Pckg. (1 kg = 11.56)",
+#                     "price": 3.99,
+#                     "priceRaw": "3,99 €",
+#                     "manufacturer": "FERRERO",
+#                     "articleNo": "249183",
+#                     "productCategory": "suesses-und-salziges",
+#                     ...
+#                 },
+#                 ...
+#             ]
+#         },
+#         ...
+#     ],
+#     "validUntil": "2026-04-05T00:00:00Z"
+# }
+
 recipes = client.recipe_search(search_term="Pasta")
+# {
+#     "totalCount": 150,
+#     "recipes": [
+#         {
+#             "id": "60f6d89e-640e-4911-8b61-628250c2217a",
+#             "title": "Bruschetta Pasta",
+#             "duration": "25 min",
+#             "difficultyLevel": 1,
+#             "difficultyDescription": "Einfach"
+#         },
+#         ...
+#     ],
+#     "metadata": {"collections": ["Vegetarisch"], "difficulties": ["Gering", "Mittel", "Hoch"], ...}
+# }
 ```
 
 ## Methods
 
-All methods raise `RewerseError` on failure. Responses are untyped dicts; see [Go structs](https://pkg.go.dev/github.com/ByteSizedMarius/rewerse-engineering/pkg) for field definitions.
+All methods raise `RewerseError` on failure. Responses are untyped dicts; field definitions, filter constants, and enum values are documented in the [Go reference](https://pkg.go.dev/github.com/ByteSizedMarius/rewerse-engineering/pkg#pkg-types).
 
 ### Markets
 
@@ -65,6 +141,8 @@ All methods raise `RewerseError` on failure. Responses are untyped dicts; see [G
 | `get_product_suggestions(query, *, page=1, objects_per_page=25)` | Autocomplete suggestions |
 | `get_product_recommendations(market_id, listing_id)` | Related product recommendations |
 
+See [`ProductFilter`](https://pkg.go.dev/github.com/ByteSizedMarius/rewerse-engineering/pkg#ProductFilter). Prices in `currentRetailPrice` are in **cents** (divide by 100 for euros).
+
 ### Discounts
 
 | Method | Description |
@@ -76,11 +154,13 @@ All methods raise `RewerseError` on failure. Responses are untyped dicts; see [G
 
 | Method | Description |
 |--------|-------------|
-| `recipe_search(*, search_term="", sorting="RELEVANCE_DESC", difficulty="", collection="", page=1, objects_per_page=20)` | Search recipes. Difficulty: `"Gering"`, `"Mittel"`, `"Hoch"`. Collection: `"Vegetarisch"`, `"Vegan"` |
+| `recipe_search(*, search_term="", sorting="RELEVANCE_DESC", difficulty="", collection="", page=1, objects_per_page=20)` | Search recipes |
 | `get_recipe_details(recipe_id)` | Get full recipe with ingredients and steps |
 | `get_recipe_popular_terms()` | Get popular recipe search terms |
 | `get_recipe_hub()` | Get recipe homepage (recipe of the day, popular, categories) |
 
+See [`RecipeDifficulty`](https://pkg.go.dev/github.com/ByteSizedMarius/rewerse-engineering/pkg#RecipeDifficulty), [`RecipeCollection`](https://pkg.go.dev/github.com/ByteSizedMarius/rewerse-engineering/pkg#RecipeCollection).
+
 ### Shop & Services
 
 | Method | Description |
@@ -89,6 +169,8 @@ All methods raise `RewerseError` on failure. Responses are untyped dicts; see [G
 | `get_service_portfolio(zipcode)` | Get available REWE services for a zip code |
 | `get_recalls()` | Get current product recalls |
 
+See [`ServiceType`](https://pkg.go.dev/github.com/ByteSizedMarius/rewerse-engineering/pkg#ServiceType). Must match market capabilities — check `serviceFlags.hasPickup` from `get_market_details()`.
+
 ### Basket
 
 | Method | Description |
@@ -98,6 +180,8 @@ All methods raise `RewerseError` on failure. Responses are untyped dicts; see [G
 | `set_basket_item(basket_id, market_id, zip_code, service_type, listing_id, quantity, version)` | Add/update item quantity in basket |
 | `remove_basket_item(basket_id, market_id, zip_code, service_type, listing_id)` | Remove item from basket |
 
+See [`ServiceType`](https://pkg.go.dev/github.com/ByteSizedMarius/rewerse-engineering/pkg#ServiceType). `version`: basket state version for optimistic locking (from previous basket response). Prices in cents.
+
 ### Delivery
 
 | Method | Description |

python/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rewerse"
-version = "0.1.0"
+version = "0.1.1"
 description = "Python bindings for the REWE mobile API"
 readme = "README.md"
 requires-python = ">=3.10"