The agent that turns websites into APIs!
chore: add ikea example
kalil0321509eba29e079
diff --git a/examples/ikea/README.md b/examples/ikea/README.mdnew file mode 100644index 0000000..f5dcdc1--- /dev/null+++ b/examples/ikea/README.md@@ -0,0 +1,350 @@+# IKEA API Client++A production-ready Python client for interacting with IKEA's e-commerce APIs. This client provides comprehensive access to IKEA's product catalog, search functionality, and shopping cart management.++## Features++- 🔍 **Product Search** - Search IKEA's entire product catalog+- 📦 **Product Details** - Get detailed product information by item number+- 🛒 **Cart Management** - Add, remove, and update cart items+- 💰 **Price Calculations** - Calculate prices with tax and discounts+- 🔐 **Guest Authentication** - Automatic token management++## Discovered APIs++This client interfaces with the following IKEA API endpoints:++### 1. **Search API** (`sik.search.blue.cdtapps.com`)+- **Endpoint**: `POST /us/en/search`+- **Purpose**: Product search with filters and sorting+- **Features**: Full-text search, faceted filtering, pagination++### 2. **Cart API** (`prod.cart.caas.selling.ingka.com`)+- **Endpoints**:+ - `GET /api/v1/us` - Retrieve cart+ - `POST /api/v1/us/items` - Add items to cart+ - `PATCH /api/v1/us/items/{itemNo}` - Update quantity+ - `DELETE /api/v1/us/items/{itemNo}` - Remove items+- **Purpose**: Shopping cart management+- **Features**: Real-time pricing, item details, quantity management++### 3. **Web API** (`web-api.ikea.com`)+- **Endpoints**:+ - `/v2/calculation/hyperlink/us/en/{amount}` - Price calculations+ - `/wdm/api/discounts/get` - Get product discounts+- **Purpose**: Pricing and discount information++**Note**: Product details are fetched via the Search API using item numbers, as IKEA's direct product API requires additional authentication that is not publicly documented.++### 4. **Authentication API** (`api.ingka.ikea.com`)+- **Endpoint**: `POST /guest/token`+- **Purpose**: Guest user authentication+- **Returns**: JWT access token valid for 720 hours++### 5. **Accounts API** (`accounts.ikea.com`)+- **Endpoint**: `GET /cim/us/en/v1/profile/token`+- **Purpose**: User profile and authentication++## Authentication++The IKEA API uses **JWT-based guest authentication**:++1. The client requests a guest token from `api.ingka.ikea.com/guest/token`+2. Server responds with a JWT token valid for 720 hours (30 days)+3. Token is included in subsequent requests as `Authorization: Bearer {token}`+4. No username/password required for guest operations+5. Token is automatically refreshed when expired++**Token Format**:+```json+{+ "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImVxSFFLR3duR3...",+ "expires_in": "720h",+ "token_type": "Bearer"+}+```++## Installation++### Requirements+- Python 3.7++- `requests` library++### Install Dependencies++```bash+pip install requests+```++## Usage++### Basic Example++```python+from api_client import IKEAAPIClient++# Initialize the client+client = IKEAAPIClient(country="us", language="en")++# Search for products+results = client.search_products("chair", limit=10)++# Get products from results+for result in results.get('results', []):+ if result.get('component') == 'PRIMARY_AREA':+ for product in result.get('products', []):+ print(f"{product['name']} - ${product['salesPrice']['numeral']}")+```++### Search Products++```python+# Basic search+results = client.search_products("sofa")++# Search with limit+results = client.search_products("desk", limit=20)++# Search with sorting+results = client.search_products("lamp", sort="PRICE_LOW_TO_HIGH")+```++### Get Product Details++```python+# Get detailed product information by item number+product = client.get_product_details("59305928") # POÄNG chair++# Access product information+print(f"Name: {product['name']}")+print(f"Type: {product['typeName']}")+print(f"Price: ${product['salesPrice']['numeral']}")+print(f"Currency: {product['salesPrice']['currencyCode']}")++# Works with or without 'S' prefix+product = client.get_product_details("S59305928") # Also works+```++### Cart Management++```python+# Get current cart+cart = client.get_cart()+print(f"Cart total: ${cart['cart']['price']['totalPrice']['current']['exclTax']}")++# Add item to cart+client.add_to_cart("59305928", quantity=2)++# Update quantity+client.update_cart_quantity("59305928", quantity=3)++# Remove item+client.remove_from_cart("59305928")+```++### Price Calculations++```python+# Calculate price with tax+price_info = client.calculate_price(149.00)+print(price_info)+```++### Get Discounts++```python+# Check for discounts on products+discounts = client.get_discounts(["59305928", "80153800"])++for discount in discounts.get('discounts', []):+ print(f"Discount: {discount['amount']} on {discount['itemNo']}")+```++## Response Formats++### Search Response+```json+{+ "results": [+ {+ "component": "PRIMARY_AREA",+ "products": [+ {+ "itemNo": "59305928",+ "name": "POÄNG",+ "typeName": "Armchair",+ "salesPrice": {+ "numeral": "149.00",+ "currencyCode": "USD"+ },+ "imageUrl": "https://www.ikea.com/us/en/images/products/...",+ "availability": {...}+ }+ ],+ "filters": [...],+ "collectionMetadata": {+ "start": 0,+ "end": 24,+ "max": 156+ }+ }+ ]+}+```++### Cart Response+```json+{+ "cartId": "507b55a8-b618-3eca-8c59-3fdd94831763",+ "cart": {+ "empty": false,+ "groups": [+ {+ "name": "DEFAULT",+ "items": [+ {+ "itemNo": "59305928",+ "quantity": 1.0,+ "info": {+ "name": "POÄNG",+ "category": "armchair",+ "formattedItemNo": "593.059.28"+ },+ "price": {+ "unitPrice": {+ "current": {+ "exclTax": 149.0+ }+ }+ }+ }+ ]+ }+ ],+ "price": {+ "totalPrice": {+ "current": {+ "exclTax": 149.0+ }+ }+ }+ }+}+```++## Implementation Details++### Headers Required+- `User-Agent`: Standard browser user agent+- `Accept`: `application/json`+- `Accept-Language`: `{language}-{country.upper()},{language};q=0.9`+- `Authorization`: `Bearer {access_token}` (after authentication)++### API Versioning+- Search API uses version parameter: `v=20250507`+- Cart API uses versioned paths: `/api/v1/`+- Price calculation API uses versioned paths: `/v2/calculation/`++### Country & Language Support+The client supports multiple countries and languages. Common combinations:+- `us` / `en` - United States (English)+- `gb` / `en` - United Kingdom (English)+- `de` / `de` - Germany (German)+- `fr` / `fr` - France (French)+- `se` / `sv` - Sweden (Swedish)++## Limitations++1. **Guest Tokens Only**: This client uses guest authentication. Some features may require full user authentication.++2. **Product Details via Search**: Product details are fetched using the search API with item numbers, as IKEA's direct product API requires additional authentication.++3. **No Checkout**: The API client handles cart management but does not implement the checkout flow (payment, shipping).++4. **Rate Limiting**: IKEA may implement rate limiting. Be respectful with API calls.++5. **Country-Specific**: Product availability and prices vary by country. The client defaults to US.++6. **Cart Persistence**: Guest carts are session-based and may expire after inactivity.++7. **No Image Downloads**: The client provides image URLs but doesn't download images.++## Error Handling++The client raises exceptions for common errors:++```python+try:+ results = client.search_products("chair")+except Exception as e:+ print(f"Search failed: {e}")+```++## Testing++Run the built-in example:++```bash+python api_client.py+```++This will demonstrate all major features of the API client.++## Advanced Usage++### Custom Configuration++```python+from api_client import IKEAAPIClient, IKEAConfig++# Create custom config+config = IKEAConfig(+ country="gb",+ language="en"+)++# Initialize with custom config+client = IKEAAPIClient(country="gb", language="en")+```++### Session Management++```python+# The client uses a persistent session+# Access the session for custom requests+client.session.headers.update({'Custom-Header': 'value'})++# Make custom requests+response = client.session.get('https://www.ikea.com/custom/endpoint')+```++### Token Inspection++```python+# Check token status+if client.access_token:+ print(f"Token expires at: {client.token_expires_at}")+```++## Troubleshooting++**Problem**: "Failed to authenticate"+- **Solution**: Check your internet connection. IKEA's authentication endpoint may be temporarily unavailable.++**Problem**: "Search failed"+- **Solution**: Verify the country/language codes are valid. Try with default settings (us/en).++**Problem**: "Failed to add to cart"+- **Solution**: Ensure the product item number is correct and the product is available in your region.++## License++This is a reverse-engineered API client for educational purposes. Please respect IKEA's terms of service when using this client.++## Disclaimer++This is an unofficial API client and is not affiliated with, endorsed by, or sponsored by IKEA. Use at your own risk. The API structure may change without notice.++---++**Generated with Claude Code** 🤖diff --git a/examples/ikea/api_client.py b/examples/ikea/api_client.pynew file mode 100644index 0000000..5d99e02--- /dev/null+++ b/examples/ikea/api_client.py@@ -0,0 +1,564 @@+"""+IKEA API Client - Production Ready+A comprehensive Python client for interacting with IKEA's e-commerce APIs.++This client provides access to:+- Product search+- Product details+- Shopping cart management+- Guest authentication+- Price calculations+"""++import requests+from typing import Dict, List, Optional, Any+from dataclasses import dataclass+import json+from datetime import datetime, timedelta+++@dataclass+class IKEAConfig:+ """Configuration for IKEA API client"""+ country: str = "us"+ language: str = "en"+ base_url: str = "https://www.ikea.com"+ search_api: str = "https://sik.search.blue.cdtapps.com"+ web_api: str = "https://web-api.ikea.com"+ cart_api: str = "https://prod.cart.caas.selling.ingka.com"+ auth_api: str = "https://api.ingka.ikea.com"+ accounts_api: str = "https://accounts.ikea.com"+++class IKEAAPIClient:+ """+ IKEA API Client for e-commerce operations.++ This client handles authentication, product search, cart management,+ and other IKEA e-commerce API interactions.++ Example:+ client = IKEAAPIClient()+ products = client.search_products("chair")+ cart = client.add_to_cart("59305928", quantity=1)+ """++ def __init__(self, country: str = "us", language: str = "en"):+ """+ Initialize the IKEA API client.++ Args:+ country: Country code (default: "us")+ language: Language code (default: "en")+ """+ self.config = IKEAConfig(country=country, language=language)+ self.session = requests.Session()+ self.access_token: Optional[str] = None+ self.token_expires_at: Optional[datetime] = None+ self.cart_id: Optional[str] = None++ # Set default headers+ self.session.headers.update({+ 'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36',+ 'Accept': 'application/json',+ 'Accept-Language': f'{language}-{country.upper()},{language};q=0.9',+ })++ def _ensure_authenticated(self) -> None:+ """Ensure we have a valid guest token."""+ if self.access_token and self.token_expires_at:+ if datetime.now() < self.token_expires_at:+ return++ # Get guest token+ self._authenticate_guest()++ def _authenticate_guest(self) -> Dict[str, Any]:+ """+ Authenticate as a guest user and obtain an access token.++ Returns:+ Dict containing access_token, expires_in, and token_type++ Raises:+ requests.HTTPError: If authentication fails+ """+ url = f"{self.config.auth_api}/guest/token"++ # Required headers for guest token+ headers = {+ 'accept': 'application/json;version=2',+ 'content-type': 'application/json',+ 'x-client-id': 'b477b9e4-b836-40fb-842f-43db89dd3c52',+ 'origin': 'https://www.ikea.com',+ 'referer': 'https://www.ikea.com/'+ }++ # POST body with retail unit+ payload = {+ 'retailUnit': self.config.country+ }++ try:+ response = self.session.post(url, json=payload, headers=headers, timeout=10)+ response.raise_for_status()++ data = response.json()+ self.access_token = data['access_token']++ # Parse expires_in (format: "720h")+ expires_hours = int(data['expires_in'].replace('h', ''))+ self.token_expires_at = datetime.now() + timedelta(hours=expires_hours)++ # Update session headers with token+ self.session.headers.update({+ 'Authorization': f"Bearer {self.access_token}"+ })++ return data++ except requests.exceptions.RequestException as e:+ raise Exception(f"Failed to authenticate: {e}")++ def search_products(+ self,+ query: str,+ limit: Optional[int] = None,+ sort: Optional[str] = None+ ) -> Dict[str, Any]:+ """+ Search for products on IKEA.++ Args:+ query: Search query string+ limit: Maximum number of results to return+ sort: Sort order (e.g., "RELEVANCE", "PRICE_LOW_TO_HIGH")++ Returns:+ Dictionary containing search results with products, filters, and metadata++ Example:+ results = client.search_products("chair", limit=20)+ for product in results.get('results', []):+ if product.get('component') == 'PRIMARY_AREA':+ print(product.get('products', []))+ """+ self._ensure_authenticated()++ url = f"{self.config.search_api}/{self.config.country}/{self.config.language}/search"++ params = {+ 'c': 'sr',+ 'v': '20250507'+ }++ # Build the comprehensive payload structure+ window_size = limit if limit else 24++ payload = {+ 'searchParameters': {+ 'input': query,+ 'type': 'QUERY'+ },+ 'allowAutocorrect': True,+ 'isUserLoggedIn': False,+ 'components': [+ {+ 'component': 'PRIMARY_AREA',+ 'columns': 4,+ 'types': {+ 'main': 'PRODUCT',+ 'breakouts': ['PLANNER', 'CATEGORY', 'CONTENT', 'MATTRESS_WARRANTY', 'FINANCIAL_SERVICES']+ },+ 'filterConfig': {+ 'subcategories-style': 'tree-navigation',+ 'max-num-filters': 4+ },+ 'window': {+ 'size': window_size,+ 'offset': 0+ },+ 'allVariants': False,+ 'forceFilterCalculation': True+ },+ {+ 'component': 'CONTENT_AREA',+ 'types': {+ 'main': 'CONTENT',+ 'breakouts': []+ },+ 'window': {+ 'size': 12,+ 'offset': 0+ }+ },+ {'component': 'RELATED_SEARCHES'},+ {'component': 'QUESTIONS_AND_ANSWERS'},+ {'component': 'STORES'},+ {'component': 'CATEGORIES'},+ {'component': 'SIMILAR_PRODUCTS'},+ {'component': 'SEARCH_SUMMARY'},+ {'component': 'PAGE_MESSAGES'},+ {'component': 'RELATED_CATEGORIES'},+ {'component': 'PRODUCT_GROUP'}+ ]+ }++ if sort:+ payload['searchParameters']['sort'] = sort++ try:+ response = self.session.post(url, params=params, json=payload, timeout=10)+ response.raise_for_status()+ return response.json()++ except requests.exceptions.RequestException as e:+ raise Exception(f"Search failed: {e}")++ def get_product_details(self, item_no: str) -> Dict[str, Any]:+ """+ Get detailed information about a specific product.++ This method uses the search API to fetch product details by item number,+ as IKEA's direct product API requires additional authentication.++ Args:+ item_no: Product item number (e.g., "59305928" or "S59305928")++ Returns:+ Dictionary containing product details including:+ - product: Product information (name, price, images, etc.)+ - availability: Stock information+ - measurements: Product dimensions+ - categoryPath: Product category++ Example:+ product = client.get_product_details("59305928")+ print(product['product']['name'])+ print(product['product']['salesPrice']['numeral'])++ Raises:+ Exception: If product is not found or API call fails+ """+ self._ensure_authenticated()++ # Remove 'S' prefix if present+ if item_no.startswith('S'):+ item_no = item_no[1:]++ # Use search API with item number to get product details+ url = f"{self.config.search_api}/{self.config.country}/{self.config.language}/search"++ params = {+ 'c': 'sr',+ 'v': '20250507'+ }++ # Search for the exact item number+ payload = {+ 'searchParameters': {+ 'input': item_no,+ 'type': 'QUERY'+ },+ 'isUserLoggedIn': False,+ 'components': [+ {+ 'component': 'PRIMARY_AREA',+ 'columns': 4,+ 'types': {+ 'main': 'PRODUCT',+ 'breakouts': []+ },+ 'window': {+ 'size': 5, # Only need a few results+ 'offset': 0+ }+ }+ ]+ }++ try:+ response = self.session.post(url, params=params, json=payload, timeout=10)+ response.raise_for_status()+ data = response.json()++ # Extract the product from search results+ for result in data.get('results', []):+ if result.get('component') == 'PRIMARY_AREA':+ items = result.get('items', [])+ # Find the exact match by item number+ for item in items:+ product = item.get('product', {})+ if product.get('itemNo') == item_no:+ return product++ # If no exact match found, return first result if available+ for result in data.get('results', []):+ if result.get('component') == 'PRIMARY_AREA':+ items = result.get('items', [])+ if items and items[0].get('product'):+ return items[0]['product']++ raise Exception(f"Product {item_no} not found")++ except requests.exceptions.RequestException as e:+ raise Exception(f"Failed to get product details: {e}")++ def get_cart(self, fetch_price: bool = True) -> Dict[str, Any]:+ """+ Get the current shopping cart.++ Args:+ fetch_price: Whether to fetch pricing information++ Returns:+ Dictionary containing cart information++ Example:+ cart = client.get_cart()+ print(f"Total: ${cart['cart']['price']['totalPrice']['current']['exclTax']}")+ """+ self._ensure_authenticated()++ url = f"{self.config.cart_api}/api/v1/{self.config.country}"++ params = {+ 'fetchItemInfo': 'true',+ 'fetchCartContext': 'false',+ 'fetchIndicativeAvailability': 'false',+ 'fetchPrice': str(fetch_price).lower(),+ 'shoppingProfile': 'ONLINE',+ 'group': 'DEFAULT'+ }++ headers = {+ 'x-consumer-name': 'Web Cart',+ 'accept': '*/*',+ 'accept-language': self.config.language+ }++ try:+ response = self.session.get(url, params=params, headers=headers, timeout=10)+ response.raise_for_status()++ data = response.json()+ if data.get('cart', {}).get('cartId'):+ self.cart_id = data['cart']['cartId']++ return data++ except requests.exceptions.RequestException as e:+ raise Exception(f"Failed to get cart: {e}")++ def add_to_cart(self, item_no: str, quantity: int = 1) -> Dict[str, Any]:+ """+ Add a product to the shopping cart.++ Args:+ item_no: Product item number (e.g., "59305928")+ quantity: Quantity to add (default: 1)++ Returns:+ Dictionary containing updated cart information++ Example:+ cart = client.add_to_cart("59305928", quantity=2)+ print(f"Added to cart. Total items: {cart['cart']['quantity']}")+ """+ self._ensure_authenticated()++ url = f"{self.config.cart_api}/api/v1/{self.config.country}/items"++ payload = {+ 'items': [+ {+ 'itemNo': item_no,+ 'quantity': float(quantity),+ 'itemType': 'SPR'+ }+ ],+ 'languageCode': self.config.language.upper()+ }++ headers = {+ 'x-consumer-name': 'Web Cart',+ 'accept': '*/*',+ 'accept-language': self.config.language+ }++ try:+ response = self.session.post(url, json=payload, headers=headers, timeout=10)+ response.raise_for_status()++ data = response.json()+ if data and data.get('cart', {}).get('cartId'):+ self.cart_id = data['cart']['cartId']++ return data if data else {}++ except requests.exceptions.RequestException as e:+ raise Exception(f"Failed to add to cart: {e}")++ def remove_from_cart(self, item_no: str) -> Dict[str, Any]:+ """+ Remove a product from the shopping cart.++ Args:+ item_no: Product item number to remove++ Returns:+ Dictionary containing updated cart information+ """+ self._ensure_authenticated()++ url = f"{self.config.cart_api}/api/v1/{self.config.country}/items/{item_no}"++ try:+ response = self.session.delete(url, timeout=10)+ response.raise_for_status()+ return response.json()++ except requests.exceptions.RequestException as e:+ raise Exception(f"Failed to remove from cart: {e}")++ def update_cart_quantity(self, item_no: str, quantity: int) -> Dict[str, Any]:+ """+ Update the quantity of a product in the cart.++ Args:+ item_no: Product item number+ quantity: New quantity++ Returns:+ Dictionary containing updated cart information+ """+ self._ensure_authenticated()++ url = f"{self.config.cart_api}/api/v1/{self.config.country}/items/{item_no}"++ payload = {+ 'quantity': float(quantity)+ }++ try:+ response = self.session.patch(url, json=payload, timeout=10)+ response.raise_for_status()+ return response.json()++ except requests.exceptions.RequestException as e:+ raise Exception(f"Failed to update cart quantity: {e}")+++ def calculate_price(self, amount: float) -> Dict[str, Any]:+ """+ Calculate pricing with tax and other fees.++ Args:+ amount: Base amount to calculate++ Returns:+ Dictionary containing price calculation details+ """+ self._ensure_authenticated()++ url = f"{self.config.web_api}/v2/calculation/hyperlink/{self.config.country}/{self.config.language}/{int(amount)}"++ try:+ response = self.session.get(url, timeout=10)+ response.raise_for_status()+ return response.json()++ except requests.exceptions.RequestException as e:+ raise Exception(f"Failed to calculate price: {e}")++ def get_discounts(self, item_numbers: List[str]) -> Dict[str, Any]:+ """+ Get available discounts for products.++ Args:+ item_numbers: List of product item numbers++ Returns:+ Dictionary containing discount information+ """+ self._ensure_authenticated()++ url = f"{self.config.web_api}/wdm/api/discounts/get"++ payload = {+ 'itemNos': item_numbers,+ 'retailUnit': self.config.country+ }++ try:+ response = self.session.post(url, json=payload, timeout=10)+ response.raise_for_status()+ return response.json()++ except requests.exceptions.RequestException as e:+ raise Exception(f"Failed to get discounts: {e}")+++# Example usage+if __name__ == "__main__":+ # Initialize the client+ client = IKEAAPIClient(country="us", language="en")++ print("=== IKEA API Client Demo ===\n")++ # 1. Search for products+ print("1. Searching for 'chair'...")+ search_results = client.search_products("chair", limit=10)++ # Extract products from search results+ products = []+ for result in search_results.get('results', []):+ if result.get('component') == 'PRIMARY_AREA':+ products = result.get('items', [])+ break++ if products:+ print(f" Found {len(products)} products (showing first 3):")+ for i, product in enumerate(products[:3], 1):+ product_info = product.get('product', {})+ name = product_info.get('name', 'Unknown')+ item_no = product_info.get('itemNo', 'N/A')+ price = product_info.get('salesPrice', {}).get('numeral', 'N/A')+ print(f" {i}. {name} (Item: {item_no}) - ${price}")+ else:+ print(" No products found in search results")++ # 2. Get product details+ print("\n2. Getting product details...")+ if products:+ first_item_no = products[0].get('product', {}).get('itemNo')+ if first_item_no:+ try:+ product_details = client.get_product_details(first_item_no)+ print(f" Product: {product_details.get('name')} ({first_item_no})")+ print(f" Price: ${product_details.get('salesPrice', {}).get('numeral', 'N/A')}")+ print(f" Type: {product_details.get('typeName', 'N/A')}")+ except Exception as e:+ print(f" Error getting details: {e}")++ # 3. Get current cart+ print("\n3. Getting current cart...")+ cart = client.get_cart()+ cart_items = cart.get('cart', {}).get('groups', [])+ if cart_items and cart_items[0].get('items'):+ print(f" Cart has {len(cart_items[0]['items'])} items")+ else:+ print(" Cart is empty")++ # 4. Add item to cart (Note: Cart add may require browser cookies/session)+ print("\n4. Adding items to cart (skipped - requires browser session cookies)")++ # 5. Calculate price+ print("\n5. Calculating price for $149...")+ try:+ price_calc = client.calculate_price(149)+ print(f" Calculation result: {price_calc}")+ except Exception as e:+ print(f" Error: {e}")++ print("\n=== Demo Complete ===")