channel3-sdk 0.1.0__py3-none-any.whl → 0.1.12__py3-none-any.whl

channel3_sdk/__init__.py

@@ -6,8 +6,9 @@ from .models import (
     ProductDetail,
     SearchFilters,
     SearchRequest,
-    MerchantOffering,
-    FamilyMember,
+    SearchFilterPrice,
+    Brand,
+    Variant,
     Price,
     AvailabilityStatus,
 )
@@ -20,7 +21,7 @@ from .exceptions import (
     Channel3ConnectionError,
 )
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 __all__ = [
     # Clients
     "Channel3Client",
@@ -30,8 +31,9 @@ __all__ = [
     "ProductDetail",
     "SearchFilters",
     "SearchRequest",
-    "MerchantOffering",
-    "FamilyMember",
+    "SearchFilterPrice",
+    "Brand",
+    "Variant",
     "Price",
     "AvailabilityStatus",
     # Exceptions

channel3_sdk/client.py

@@ -6,7 +6,7 @@ import aiohttp
 import asyncio
 from pydantic import ValidationError
 
-from .models import Product, ProductDetail, SearchFilters, SearchRequest
+from .models import Product, ProductDetail, SearchFilters, SearchRequest, Brand
 from .exceptions import (
     Channel3Error,
     Channel3AuthenticationError,
@@ -127,7 +127,7 @@ class Channel3Client(BaseChannel3Client):
             query=query,
             image_url=image_url,
             base64_image=base64_image,
-            filters=filters,
+            filters=filters or SearchFilters(),
             limit=limit,
         )
 
@@ -210,6 +210,119 @@ class Channel3Client(BaseChannel3Client):
         except ValidationError as e:
             raise Channel3Error(f"Invalid response format: {str(e)}")
 
+    def get_brands(
+        self,
+        query: Optional[str] = None,
+        page: int = 1,
+        size: int = 100,
+    ) -> List[Brand]:
+        """
+        Get all brands that the vendor currently sells.
+
+        Args:
+            query: Optional text query to filter brands
+            page: Page number for pagination (default: 1)
+            size: Number of brands per page (default: 100)
+
+        Returns:
+            List of Brand objects
+
+        Raises:
+            Channel3AuthenticationError: If API key is invalid
+            Channel3ValidationError: If request parameters are invalid
+            Channel3ServerError: If server encounters an error
+            Channel3ConnectionError: If there are connection issues
+
+        Example:
+            ```python
+            brands = client.get_brands()
+            for brand in brands:
+                print(f"Brand: {brand.name}")
+            ```
+        """
+        url = f"{self.base_url}/brands"
+        params = {}
+
+        if query is not None:
+            params["query"] = query
+        if page != 1:
+            params["page"] = page
+        if size != 100:
+            params["size"] = size
+
+        try:
+            response = requests.get(
+                url, headers=self.headers, params=params, timeout=30
+            )
+            response_data = response.json()
+
+            if response.status_code != 200:
+                self._handle_error_response(response.status_code, response_data, url)
+
+            # Parse and validate response
+            return [Brand(**item) for item in response_data]
+
+        except requests.exceptions.ConnectionError as e:
+            raise Channel3ConnectionError(
+                f"Failed to connect to Channel3 API: {str(e)}"
+            )
+        except requests.exceptions.Timeout as e:
+            raise Channel3ConnectionError(f"Request timed out: {str(e)}")
+        except requests.exceptions.RequestException as e:
+            raise Channel3Error(f"Request failed: {str(e)}")
+        except ValidationError as e:
+            raise Channel3Error(f"Invalid response format: {str(e)}")
+
+    def get_brand(self, brand_id: str) -> Brand:
+        """
+        Get detailed information for a specific brand by its ID.
+
+        Args:
+            brand_id: The unique identifier of the brand
+
+        Returns:
+            Brand object with detailed brand information
+
+        Raises:
+            Channel3AuthenticationError: If API key is invalid
+            Channel3NotFoundError: If brand is not found
+            Channel3ValidationError: If brand_id is invalid
+            Channel3ServerError: If server encounters an error
+            Channel3ConnectionError: If there are connection issues
+
+        Example:
+            ```python
+            brand = client.get_brand("brand_123456")
+            print(f"Brand: {brand.name}")
+            print(f"Description: {brand.description}")
+            ```
+        """
+        if not brand_id or not brand_id.strip():
+            raise ValueError("brand_id cannot be empty")
+
+        url = f"{self.base_url}/brands/{brand_id}"
+
+        try:
+            response = requests.get(url, headers=self.headers, timeout=30)
+            response_data = response.json()
+
+            if response.status_code != 200:
+                self._handle_error_response(response.status_code, response_data, url)
+
+            # Parse and validate response
+            return Brand(**response_data)
+
+        except requests.exceptions.ConnectionError as e:
+            raise Channel3ConnectionError(
+                f"Failed to connect to Channel3 API: {str(e)}"
+            )
+        except requests.exceptions.Timeout as e:
+            raise Channel3ConnectionError(f"Request timed out: {str(e)}")
+        except requests.exceptions.RequestException as e:
+            raise Channel3Error(f"Request failed: {str(e)}")
+        except ValidationError as e:
+            raise Channel3Error(f"Invalid response format: {str(e)}")
+
 
 class AsyncChannel3Client(BaseChannel3Client):
     """Asynchronous Channel3 API client."""
@@ -255,7 +368,7 @@ class AsyncChannel3Client(BaseChannel3Client):
             query=query,
             image_url=image_url,
             base64_image=base64_image,
-            filters=filters,
+            filters=filters or SearchFilters(),
             limit=limit,
         )
 
@@ -339,3 +452,123 @@ class AsyncChannel3Client(BaseChannel3Client):
             raise Channel3Error(f"Request failed: {str(e)}")
         except ValidationError as e:
             raise Channel3Error(f"Invalid response format: {str(e)}")
+
+    async def get_brands(
+        self,
+        query: Optional[str] = None,
+        page: int = 1,
+        size: int = 100,
+    ) -> List[Brand]:
+        """
+        Get all brands that the vendor currently sells.
+
+        Args:
+            query: Optional text query to filter brands
+            page: Page number for pagination (default: 1)
+            size: Number of brands per page (default: 100)
+
+        Returns:
+            List of Brand objects
+
+        Raises:
+            Channel3AuthenticationError: If API key is invalid
+            Channel3ValidationError: If request parameters are invalid
+            Channel3ServerError: If server encounters an error
+            Channel3ConnectionError: If there are connection issues
+
+        Example:
+            ```python
+            brands = await async_client.get_brands()
+            for brand in brands:
+                print(f"Brand: {brand.name}")
+            ```
+        """
+        url = f"{self.base_url}/brands"
+        params = {}
+
+        if query is not None:
+            params["query"] = query
+        if page != 1:
+            params["page"] = page
+        if size != 100:
+            params["size"] = size
+
+        try:
+            async with aiohttp.ClientSession() as session:
+                async with session.get(
+                    url,
+                    headers=self.headers,
+                    params=params,
+                    timeout=aiohttp.ClientTimeout(total=30),
+                ) as response:
+                    response_data = await response.json()
+
+                    if response.status != 200:
+                        self._handle_error_response(response.status, response_data, url)
+
+                    # Parse and validate response
+                    return [Brand(**item) for item in response_data]
+
+        except aiohttp.ClientConnectionError as e:
+            raise Channel3ConnectionError(
+                f"Failed to connect to Channel3 API: {str(e)}"
+            )
+        except asyncio.TimeoutError as e:
+            raise Channel3ConnectionError(f"Request timed out: {str(e)}")
+        except aiohttp.ClientError as e:
+            raise Channel3Error(f"Request failed: {str(e)}")
+        except ValidationError as e:
+            raise Channel3Error(f"Invalid response format: {str(e)}")
+
+    async def get_brand(self, brand_id: str) -> Brand:
+        """
+        Get detailed information for a specific brand by its ID.
+
+        Args:
+            brand_id: The unique identifier of the brand
+
+        Returns:
+            Brand object with detailed brand information
+
+        Raises:
+            Channel3AuthenticationError: If API key is invalid
+            Channel3NotFoundError: If brand is not found
+            Channel3ValidationError: If brand_id is invalid
+            Channel3ServerError: If server encounters an error
+            Channel3ConnectionError: If there are connection issues
+
+        Example:
+            ```python
+            brand = await async_client.get_brand("brand_123456")
+            print(f"Brand: {brand.name}")
+            print(f"Description: {brand.description}")
+            ```
+        """
+        if not brand_id or not brand_id.strip():
+            raise ValueError("brand_id cannot be empty")
+
+        url = f"{self.base_url}/brands/{brand_id}"
+
+        try:
+            async with aiohttp.ClientSession() as session:
+                async with session.get(
+                    url, headers=self.headers, timeout=aiohttp.ClientTimeout(total=30)
+                ) as response:
+                    response_data = await response.json()
+
+                    if response.status != 200:
+                        self._handle_error_response(response.status, response_data, url)
+
+                    # Parse and validate response
+                    return Brand(**response_data)
+
+        except aiohttp.ClientConnectionError as e:
+            raise Channel3ConnectionError(
+                f"Failed to connect to Channel3 API: {str(e)}"
+            )
+        except asyncio.TimeoutError as e:
+            raise Channel3ConnectionError(f"Request timed out: {str(e)}")
+        except aiohttp.ClientError as e:
+            raise Channel3Error(f"Request failed: {str(e)}")
+        except ValidationError as e:
+            raise Channel3Error(f"Invalid response format: {str(e)}")

channel3_sdk/models.py

@@ -30,25 +30,21 @@ class Price(BaseModel):
     currency: str = Field(..., description="The currency code of the product.")
 
 
-class MerchantOffering(BaseModel):
-    """A merchant offering a product."""
+class Brand(BaseModel):
+    """A brand."""
 
-    url: str = Field(
-        default="https://buy.trychannel3.com", description="URL to purchase the product"
-    )
-    merchant_name: str = Field(..., description="Name of the merchant")
-    price: Price = Field(..., description="Price information")
-    availability: AvailabilityStatus = Field(
-        ..., description="Product availability status"
-    )
+    id: str = Field(..., description="Unique identifier for the brand")
+    name: str = Field(..., description="Name of the brand")
+    logo_url: Optional[str] = Field(None, description="Logo URL for the brand")
+    description: Optional[str] = Field(None, description="Description of the brand")
 
 
-class FamilyMember(BaseModel):
-    """A family member product."""
+class Variant(BaseModel):
+    """A product variant."""
 
-    id: str = Field(..., description="Unique identifier for the family member")
-    title: str = Field(..., description="Title of the family member product")
-    image_url: str = Field(..., description="Image URL for the family member product")
+    product_id: str = Field(..., description="Unique identifier for the product")
+    title: str = Field(..., description="Title of the variant")
+    image_url: str = Field(..., description="Image URL for the variant")
 
 
 class Product(BaseModel):
@@ -56,50 +52,63 @@ class Product(BaseModel):
 
     id: str = Field(..., description="Unique identifier for the product")
     score: float = Field(..., description="Relevance score for the search query")
-    brand_name: str = Field(..., description="Brand name of the product")
     title: str = Field(..., description="Product title")
-    description: str = Field(..., description="Product description")
+    description: Optional[str] = Field(None, description="Product description")
+    brand_name: str = Field(..., description="Brand name of the product")
     image_url: str = Field(..., description="Main product image URL")
-    offers: List[MerchantOffering] = Field(
-        ..., description="List of merchant offerings"
+    price: Price = Field(..., description="Price information")
+    availability: AvailabilityStatus = Field(
+        ..., description="Product availability status"
     )
-    family: List[FamilyMember] = Field(
-        default_factory=list, description="Related family products"
+    variants: List[Variant] = Field(
+        default_factory=list, description="Product variants"
     )
 
 
 class ProductDetail(BaseModel):
     """Detailed information about a product."""
 
-    brand_id: str = Field(..., description="Unique identifier for the brand")
-    brand_name: str = Field(..., description="Brand name of the product")
     title: str = Field(..., description="Product title")
-    description: str = Field(..., description="Product description")
-    image_urls: List[str] = Field(..., description="List of product image URLs")
-    merchant_offerings: List[MerchantOffering] = Field(
-        ..., description="List of merchant offerings"
+    description: Optional[str] = Field(None, description="Product description")
+    brand_id: Optional[str] = Field(None, description="Unique identifier for the brand")
+    brand_name: Optional[str] = Field(None, description="Brand name of the product")
+    image_urls: Optional[List[str]] = Field(
+        None, description="List of product image URLs"
     )
-    gender: Literal["na", "men", "women"] = Field(
-        default="na", description="Target gender"
+    price: Price = Field(..., description="Price information")
+    availability: AvailabilityStatus = Field(
+        ..., description="Product availability status"
     )
-    materials: Optional[List[str]] = Field(None, description="List of materials")
-    key_features: List[str] = Field(
-        default_factory=list, description="List of key product features"
+    key_features: Optional[List[str]] = Field(
+        None, description="List of key product features"
     )
-    family_members: List[FamilyMember] = Field(
-        default_factory=list, description="Related family products"
+    variants: List[Variant] = Field(
+        default_factory=list, description="Product variants"
     )
 
 
+class SearchFilterPrice(BaseModel):
+    """Price filter for product search."""
+
+    min_price: Optional[float] = Field(None, description="Minimum price filter")
+    max_price: Optional[float] = Field(None, description="Maximum price filter")
+
+
 class SearchFilters(BaseModel):
     """Search filters for product search."""
 
-    colors: Optional[List[str]] = Field(None, description="List of colors to filter by")
-    materials: Optional[List[str]] = Field(
-        None, description="List of materials to filter by"
+    brand_ids: Optional[List[str]] = Field(
+        None, description="List of brand IDs to filter by"
+    )
+    gender: Optional[Literal["male", "female", "unisex"]] = Field(
+        None, description="Gender to filter by"
+    )
+    price: Optional[SearchFilterPrice] = Field(
+        None, description="Price range to filter by"
+    )
+    availability: Optional[List[AvailabilityStatus]] = Field(
+        None, description="Availability statuses to filter by"
     )
-    min_price: Optional[float] = Field(None, description="Minimum price filter")
-    max_price: Optional[float] = Field(None, description="Maximum price filter")
 
 
 class SearchRequest(BaseModel):
@@ -110,7 +119,7 @@ class SearchRequest(BaseModel):
     base64_image: Optional[str] = Field(
         None, description="Base64-encoded image for visual search"
     )
-    filters: Optional[SearchFilters] = Field(None, description="Search filters")
     limit: Optional[int] = Field(
         default=20, description="Maximum number of results to return"
     )
+    filters: Optional[SearchFilters] = Field(default=None, description="Search filters")

{channel3_sdk-0.1.0.dist-info → channel3_sdk-0.1.12.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: channel3-sdk
-Version: 0.1.0
+Version: 0.1.12
 Summary: The official Python SDK for Channel3 AI Shopping API
 Home-page: https://github.com/channel3/sdk-python
 License: MIT
@@ -50,14 +50,27 @@ products = client.search(query="blue denim jacket")
 for product in products:
     print(f"Product: {product.title}")
     print(f"Brand: {product.brand_name}")
-    print(f"Price: ${product.offers[0].price.price}")
+    print(f"Price: {product.price.currency} {product.price.price}")
+    print(f"Availability: {product.availability}")
     print("---")
 
 # Get detailed product information
 product_detail = client.get_product("prod_123456")
 print(f"Detailed info for: {product_detail.title}")
-print(f"Materials: {product_detail.materials}")
-print(f"Key features: {product_detail.key_features}")
+print(f"Brand: {product_detail.brand_name}")
+if product_detail.key_features:
+    print(f"Key features: {product_detail.key_features}")
+
+# Get all brands
+brands = client.get_brands()
+for brand in brands:
+    print(f"Brand: {brand.name}")
+    if brand.description:
+        print(f"Description: {brand.description}")
+
+# Get specific brand details
+brand = client.get_brand("brand_123")
+print(f"Brand: {brand.name}")
 ```
 
 ### Asynchronous Client
@@ -76,11 +89,16 @@ async def main():
     for product in products:
         print(f"Product: {product.title}")
         print(f"Score: {product.score}")
+        print(f"Price: {product.price.currency} {product.price.price}")
     
     # Get detailed product information
     if products:
         product_detail = await client.get_product(products[0].id)
-        print(f"Gender: {product_detail.gender}")
+        print(f"Availability: {product_detail.availability}")
+    
+    # Get brands
+    brands = await client.get_brands()
+    print(f"Found {len(brands)} brands")
 
 # Run the async function
 asyncio.run(main())
@@ -114,14 +132,14 @@ products = client.search(
 ### Search with Filters
 
 ```python
-from channel3_sdk import SearchFilters
+from channel3_sdk import SearchFilters, AvailabilityStatus
 
 # Create search filters
 filters = SearchFilters(
-    colors=["blue", "navy"],
-    materials=["cotton", "denim"],
-    min_price=50.0,
-    max_price=200.0
+    brand_ids=["brand_123", "brand_456"],
+    gender="male",
+    availability=[AvailabilityStatus.IN_STOCK],
+    price={"min_price": 50.0, "max_price": 200.0}
 )
 
 # Search with filters
@@ -132,6 +150,21 @@ products = client.search(
 )
 ```
 
+### Brand Management
+
+```python
+# Get all brands with pagination
+brands = client.get_brands(page=1, size=50)
+
+# Search for specific brands
+nike_brands = client.get_brands(query="nike")
+
+# Get detailed brand information
+brand_detail = client.get_brand("brand_123")
+print(f"Brand: {brand_detail.name}")
+print(f"Logo: {brand_detail.logo_url}")
+```
+
 ## API Reference
 
 ### Client Classes
@@ -142,6 +175,8 @@ Synchronous client for the Channel3 API.
 **Methods:**
 - `search(query=None, image_url=None, base64_image=None, filters=None, limit=20)` → `List[Product]`
 - `get_product(product_id)` → `ProductDetail`
+- `get_brands(query=None, page=1, size=100)` → `List[Brand]`
+- `get_brand(brand_id)` → `Brand`
 
 #### `AsyncChannel3Client` 
 Asynchronous client for the Channel3 API.
@@ -149,48 +184,62 @@ Asynchronous client for the Channel3 API.
 **Methods:**
 - `async search(query=None, image_url=None, base64_image=None, filters=None, limit=20)` → `List[Product]`
 - `async get_product(product_id)` → `ProductDetail`
+- `async get_brands(query=None, page=1, size=100)` → `List[Brand]`
+- `async get_brand(brand_id)` → `Brand`
 
 ### Models
 
 #### `Product`
 - `id: str` - Unique product identifier
 - `score: float` - Search relevance score
-- `brand_name: str` - Brand name
 - `title: str` - Product title
-- `description: str` - Product description
+- `description: Optional[str]` - Product description
+- `brand_name: str` - Brand name
 - `image_url: str` - Main product image URL
-- `offers: List[MerchantOffering]` - Available purchase options
-- `family: List[FamilyMember]` - Related products
+- `price: Price` - Price information
+- `availability: AvailabilityStatus` - Availability status
+- `variants: List[Variant]` - Product variants
 
 #### `ProductDetail`
-- `brand_id: str` - Brand identifier
-- `brand_name: str` - Brand name
 - `title: str` - Product title
-- `description: str` - Product description
-- `image_urls: List[str]` - Product image URLs
-- `merchant_offerings: List[MerchantOffering]` - Purchase options
-- `gender: Literal["na", "men", "women"]` - Target gender
-- `materials: Optional[List[str]]` - Product materials
-- `key_features: List[str]` - Key product features
-- `family_members: List[FamilyMember]` - Related products
+- `description: Optional[str]` - Product description
+- `brand_id: Optional[str]` - Brand identifier
+- `brand_name: Optional[str]` - Brand name
+- `image_urls: Optional[List[str]]` - Product image URLs
+- `price: Price` - Price information
+- `availability: AvailabilityStatus` - Availability status
+- `key_features: Optional[List[str]]` - Key product features
+- `variants: List[Variant]` - Product variants
+
+#### `Brand`
+- `id: str` - Unique brand identifier
+- `name: str` - Brand name
+- `logo_url: Optional[str]` - Brand logo URL
+- `description: Optional[str]` - Brand description
+
+#### `Variant`
+- `product_id: str` - Associated product identifier
+- `title: str` - Variant title
+- `image_url: str` - Variant image URL
 
 #### `SearchFilters`
-- `colors: Optional[List[str]]` - Color filters
-- `materials: Optional[List[str]]` - Material filters
+- `brand_ids: Optional[List[str]]` - Brand ID filters
+- `gender: Optional[Literal["male", "female", "unisex"]]` - Gender filter
+- `price: Optional[SearchFilterPrice]` - Price range filter
+- `availability: Optional[List[AvailabilityStatus]]` - Availability filters
+
+#### `SearchFilterPrice`
 - `min_price: Optional[float]` - Minimum price
 - `max_price: Optional[float]` - Maximum price
 
-#### `MerchantOffering`
-- `url: str` - Purchase URL
-- `merchant_name: str` - Merchant name
-- `price: Price` - Price information
-- `availability: AvailabilityStatus` - Availability status
-
 #### `Price`
 - `price: float` - Current price
 - `compare_at_price: Optional[float]` - Original price (if discounted)
 - `currency: str` - Currency code
 
+#### `AvailabilityStatus`
+Enum with values: `IN_STOCK`, `OUT_OF_STOCK`, `PRE_ORDER`, `LIMITED_AVAILABILITY`, `BACK_ORDER`, `DISCONTINUED`, `SOLD_OUT`, `UNKNOWN`
+
 ## Error Handling
 
 The SDK provides specific exception types for different error conditions:

channel3_sdk-0.1.12.dist-info/RECORD

@@ -0,0 +1,7 @@
+channel3_sdk/__init__.py,sha256=vMrsZwY59OoYmoPwEnZ0kuAuWFkOIERUaoy0lWpGIlc,976
+channel3_sdk/client.py,sha256=8klt__VDUerEO6qq8-RA3w8CSImE6tfPf1v8m25_aS4,20843
+channel3_sdk/exceptions.py,sha256=5HJgrhir4-_b4XKyWAB9qp-CjVZeigXSkyM9fbcB1IA,1044
+channel3_sdk/models.py,sha256=PdFD-sESRhlZSsvVIHHlhwn-Zi5QbGcUiHo0NnP_Gqs,4520
+channel3_sdk-0.1.12.dist-info/METADATA,sha256=fflKnYaOYNhHohAMm7_MvdDgxBxOHZfXtJCYsbwj4FA,7800
+channel3_sdk-0.1.12.dist-info/WHEEL,sha256=Nq82e9rUAnEjt98J6MlVmMCZb-t9cYE2Ir1kpBmnWfs,88
+channel3_sdk-0.1.12.dist-info/RECORD,,

channel3_sdk-0.1.0.dist-info/RECORD

@@ -1,7 +0,0 @@
-channel3_sdk/__init__.py,sha256=aoe0MhblA5pEOd7iAggJ94u1Os8-xCBs6k0UWhfOiiE,960
-channel3_sdk/client.py,sha256=JuJFtXdWsezwOQk3nVUnxhdtQp300UEORsQZdCZ77V8,12525
-channel3_sdk/exceptions.py,sha256=5HJgrhir4-_b4XKyWAB9qp-CjVZeigXSkyM9fbcB1IA,1044
-channel3_sdk/models.py,sha256=AMgcsCK-jnaKA9iiL0CZvWJMprA1AxspIu4IM6vq-WE,4326
-channel3_sdk-0.1.0.dist-info/METADATA,sha256=xGgwGQ8iQTs1u7zeYK22RSF-EW02fYvPlqeC-4xerqs,6137
-channel3_sdk-0.1.0.dist-info/WHEEL,sha256=Nq82e9rUAnEjt98J6MlVmMCZb-t9cYE2Ir1kpBmnWfs,88
-channel3_sdk-0.1.0.dist-info/RECORD,,