feat(api): api update

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 41
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/context-dev/context.dev-8be9b7cfe70702af909241420da1c61ba6b248345c5faec3b472df540bc6a553.yml
-openapi_spec_hash: f98fb82a9ad562fc04d32f7063182de8
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/context-dev/context.dev-dc61df29e1b6282f9df685fadd65f3683afe352deccae94d0c080092e0eae4b3.yml
+openapi_spec_hash: 258caa98cd0de5f7149f6937d071c912
 config_hash: 0fb0ceca5946298c416cec0cca5260c7

README.md

@@ -45,7 +45,7 @@ brand = client.brand.retrieve(
     domain="REPLACE_ME",
     type="by_domain",
 )
-print(brand.brand)
+print(brand.cache_metadata)
 ```
 
 While you can provide an `api_key` keyword argument,
@@ -72,7 +72,7 @@ async def main() -> None:
         domain="REPLACE_ME",
         type="by_domain",
     )
-    print(brand.brand)
+    print(brand.cache_metadata)
 
 
 asyncio.run(main())
@@ -109,7 +109,7 @@ async def main() -> None:
             domain="REPLACE_ME",
             type="by_domain",
         )
-        print(brand.brand)
+        print(brand.cache_metadata)
 
 
 asyncio.run(main())
@@ -279,7 +279,7 @@ response = client.brand.with_raw_response.retrieve(
 print(response.headers.get('X-My-Header'))
 
 brand = response.parse()  # get the object that `brand.retrieve()` would have returned
-print(brand.brand)
+print(brand.cache_metadata)
 ```
 
 These methods return an [`APIResponse`](https://github.com/context-dot-dev/context-python-sdk/tree/main/src/context/dev/_response.py) object.

src/context/dev/types/ai_extract_product_response.py

@@ -5,7 +5,23 @@
 
 from .._models import BaseModel
 
-__all__ = ["AIExtractProductResponse", "KeyMetadata", "Product"]
+__all__ = ["AIExtractProductResponse", "CacheMetadata", "KeyMetadata", "Product"]
+
+
+class CacheMetadata(BaseModel):
+    """Cache outcome for this response.
+
+    Composite responses are hits only when every cache-controlled fetch contributing to the output was a hit; age_ms is the oldest contributing hit.
+    """
+
+    age_ms: int
+    """Age of the cached data in milliseconds. Zero for miss and zdr responses."""
+
+    status: Literal["hit", "miss", "zdr"]
+    """
+    Whether the response was served from cache, required fresh work, or honored
+    zero-data-retention cache bypass.
+    """
 
 
 class KeyMetadata(BaseModel):
@@ -83,6 +99,13 @@ class Product(BaseModel):
 
 
 class AIExtractProductResponse(BaseModel):
+    cache_metadata: CacheMetadata
+    """Cache outcome for this response.
+
+    Composite responses are hits only when every cache-controlled fetch contributing
+    to the output was a hit; age_ms is the oldest contributing hit.
+    """
+
     is_product_page: Optional[bool] = None
     """Whether the given URL is a product detail page"""
 

src/context/dev/types/ai_extract_products_response.py

@@ -5,7 +5,23 @@
 
 from .._models import BaseModel
 
-__all__ = ["AIExtractProductsResponse", "KeyMetadata", "Product"]
+__all__ = ["AIExtractProductsResponse", "CacheMetadata", "KeyMetadata", "Product"]
+
+
+class CacheMetadata(BaseModel):
+    """Cache outcome for this response.
+
+    Composite responses are hits only when every cache-controlled fetch contributing to the output was a hit; age_ms is the oldest contributing hit.
+    """
+
+    age_ms: int
+    """Age of the cached data in milliseconds. Zero for miss and zdr responses."""
+
+    status: Literal["hit", "miss", "zdr"]
+    """
+    Whether the response was served from cache, required fresh work, or honored
+    zero-data-retention cache bypass.
+    """
 
 
 class KeyMetadata(BaseModel):
@@ -81,6 +97,13 @@ class Product(BaseModel):
 
 
 class AIExtractProductsResponse(BaseModel):
+    cache_metadata: CacheMetadata
+    """Cache outcome for this response.
+
+    Composite responses are hits only when every cache-controlled fetch contributing
+    to the output was a hit; age_ms is the oldest contributing hit.
+    """
+
     key_metadata: Optional[KeyMetadata] = None
     """Metadata about the API key used for the request.
 

src/context/dev/types/batch_get_results_response.py

@@ -12,6 +12,7 @@
     "BatchGetResultsResponse",
     "Data",
     "DataOk",
+    "DataOkCacheMetadata",
     "DataOkMetadata",
     "DataOkMetadataAlternate",
     "DataOkMetadataHeading",
@@ -20,6 +21,22 @@
 ]
 
 
+class DataOkCacheMetadata(BaseModel):
+    """Cache outcome for this response.
+
+    Composite responses are hits only when every cache-controlled fetch contributing to the output was a hit; age_ms is the oldest contributing hit.
+    """
+
+    age_ms: int
+    """Age of the cached data in milliseconds. Zero for miss and zdr responses."""
+
+    status: Literal["hit", "miss", "zdr"]
+    """
+    Whether the response was served from cache, required fresh work, or honored
+    zero-data-retention cache bypass.
+    """
+
+
 class DataOkMetadataAlternate(BaseModel):
     href: str
     """Resolved alternate URL."""
@@ -115,6 +132,13 @@ class DataOkMetadata(BaseModel):
 class DataOk(BaseModel):
     """A page the batch fetched successfully."""
 
+    cache_metadata: DataOkCacheMetadata
+    """Cache outcome for this response.
+
+    Composite responses are hits only when every cache-controlled fetch contributing
+    to the output was a hit; age_ms is the oldest contributing hit.
+    """
+
     final_url: str
     """URL the content was read from, after redirects."""
 

src/context/dev/types/batch_submit_response.py

@@ -7,7 +7,23 @@
 from .._models import BaseModel
 from .crawl_controls import CrawlControls
 
-__all__ = ["BatchSubmitResponse", "Credits", "InvalidURL", "KeyMetadata"]
+__all__ = ["BatchSubmitResponse", "CacheMetadata", "Credits", "InvalidURL", "KeyMetadata"]
+
+
+class CacheMetadata(BaseModel):
+    """Cache outcome for this response.
+
+    Composite responses are hits only when every cache-controlled fetch contributing to the output was a hit; age_ms is the oldest contributing hit.
+    """
+
+    age_ms: int
+    """Age of the cached data in milliseconds. Zero for miss and zdr responses."""
+
+    status: Literal["hit", "miss", "zdr"]
+    """
+    Whether the response was served from cache, required fresh work, or honored
+    zero-data-retention cache bypass.
+    """
 
 
 class Credits(BaseModel):
@@ -42,6 +58,13 @@ class BatchSubmitResponse(BaseModel):
     id: str
     """Batch ID. Poll GET /batch/{batch_id} with it."""
 
+    cache_metadata: CacheMetadata
+    """Cache outcome for this response.
+
+    Composite responses are hits only when every cache-controlled fetch contributing
+    to the output was a hit; age_ms is the oldest contributing hit.
+    """
+
     crawl: Optional[CrawlControls] = None
     """
     The crawl controls as submitted, so the limits requested can be compared against

src/context/dev/types/brand_retrieve_response.py

@@ -7,6 +7,7 @@
 
 __all__ = [
     "BrandRetrieveResponse",
+    "CacheMetadata",
     "Brand",
     "BrandAddress",
     "BrandBackdrop",
@@ -26,6 +27,22 @@
 ]
 
 
+class CacheMetadata(BaseModel):
+    """Cache outcome for this response.
+
+    Composite responses are hits only when every cache-controlled fetch contributing to the output was a hit; age_ms is the oldest contributing hit.
+    """
+
+    age_ms: int
+    """Age of the cached data in milliseconds. Zero for miss and zdr responses."""
+
+    status: Literal["hit", "miss", "zdr"]
+    """
+    Whether the response was served from cache, required fresh work, or honored
+    zero-data-retention cache bypass.
+    """
+
+
 class BrandAddress(BaseModel):
     """Physical address of the brand"""
 
@@ -690,6 +707,13 @@ class KeyMetadata(BaseModel):
 
 
 class BrandRetrieveResponse(BaseModel):
+    cache_metadata: CacheMetadata
+    """Cache outcome for this response.
+
+    Composite responses are hits only when every cache-controlled fetch contributing
+    to the output was a hit; age_ms is the oldest contributing hit.
+    """
+
     brand: Optional[Brand] = None
     """Detailed brand information"""
 

src/context/dev/types/brand_retrieve_simplified_response.py

@@ -7,6 +7,7 @@
 
 __all__ = [
     "BrandRetrieveSimplifiedResponse",
+    "CacheMetadata",
     "Brand",
     "BrandBackdrop",
     "BrandBackdropColor",
@@ -19,6 +20,22 @@
 ]
 
 
+class CacheMetadata(BaseModel):
+    """Cache outcome for this response.
+
+    Composite responses are hits only when every cache-controlled fetch contributing to the output was a hit; age_ms is the oldest contributing hit.
+    """
+
+    age_ms: int
+    """Age of the cached data in milliseconds. Zero for miss and zdr responses."""
+
+    status: Literal["hit", "miss", "zdr"]
+    """
+    Whether the response was served from cache, required fresh work, or honored
+    zero-data-retention cache bypass.
+    """
+
+
 class BrandBackdropColor(BaseModel):
     hex: Optional[str] = None
     """Color in hexadecimal format"""
@@ -141,6 +158,13 @@ class KeyMetadata(BaseModel):
 
 
 class BrandRetrieveSimplifiedResponse(BaseModel):
+    cache_metadata: CacheMetadata
+    """Cache outcome for this response.
+
+    Composite responses are hits only when every cache-controlled fetch contributing
+    to the output was a hit; age_ms is the oldest contributing hit.
+    """
+
     brand: Optional[Brand] = None
     """Simplified brand information"""
 

src/context/dev/types/web_extract_fonts_response.py

@@ -7,7 +7,23 @@
 
 from .._models import BaseModel
 
-__all__ = ["WebExtractFontsResponse", "Font", "FontLinks", "KeyMetadata"]
+__all__ = ["WebExtractFontsResponse", "CacheMetadata", "Font", "FontLinks", "KeyMetadata"]
+
+
+class CacheMetadata(BaseModel):
+    """Cache outcome for this response.
+
+    Composite responses are hits only when every cache-controlled fetch contributing to the output was a hit; age_ms is the oldest contributing hit.
+    """
+
+    age_ms: int
+    """Age of the cached data in milliseconds. Zero for miss and zdr responses."""
+
+    status: Literal["hit", "miss", "zdr"]
+    """
+    Whether the response was served from cache, required fresh work, or honored
+    zero-data-retention cache bypass.
+    """
 
 
 class Font(BaseModel):
@@ -71,6 +87,13 @@ class KeyMetadata(BaseModel):
 
 
 class WebExtractFontsResponse(BaseModel):
+    cache_metadata: CacheMetadata
+    """Cache outcome for this response.
+
+    Composite responses are hits only when every cache-controlled fetch contributing
+    to the output was a hit; age_ms is the oldest contributing hit.
+    """
+
     code: int
     """HTTP status code, e.g., 200"""
 

src/context/dev/types/web_extract_response.py

@@ -7,7 +7,23 @@
 
 from .._models import BaseModel
 
-__all__ = ["WebExtractResponse", "Metadata", "MetadataActionsApplied", "KeyMetadata"]
+__all__ = ["WebExtractResponse", "CacheMetadata", "Metadata", "MetadataActionsApplied", "KeyMetadata"]
+
+
+class CacheMetadata(BaseModel):
+    """Cache outcome for this response.
+
+    Composite responses are hits only when every cache-controlled fetch contributing to the output was a hit; age_ms is the oldest contributing hit.
+    """
+
+    age_ms: int
+    """Age of the cached data in milliseconds. Zero for miss and zdr responses."""
+
+    status: Literal["hit", "miss", "zdr"]
+    """
+    Whether the response was served from cache, required fresh work, or honored
+    zero-data-retention cache bypass.
+    """
 
 
 class MetadataActionsApplied(BaseModel):
@@ -66,6 +82,13 @@ class KeyMetadata(BaseModel):
 
 
 class WebExtractResponse(BaseModel):
+    cache_metadata: CacheMetadata
+    """Cache outcome for this response.
+
+    Composite responses are hits only when every cache-controlled fetch contributing
+    to the output was a hit; age_ms is the oldest contributing hit.
+    """
+
     data: Dict[str, object]
     """Extracted data matching the request schema"""