release: 2.13.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "2.12.0"
+  ".": "2.13.0"
 }

.stats.yml

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

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 2.13.0 (2026-08-27)
+
+Full Changelog: [v2.12.0...v2.13.0](https://github.com/context-dot-dev/context-php-sdk/compare/v2.12.0...v2.13.0)
+
+### Features
+
+* **api:** api update ([171e0a4](https://github.com/context-dot-dev/context-php-sdk/commit/171e0a46709a9ca96179d7ccd149b3c949ba3e32))
+* **api:** api update ([8254251](https://github.com/context-dot-dev/context-php-sdk/commit/8254251acb0d5a1c933ae6978ab2710cf1163b8a))
+
 ## 2.12.0 (2026-08-23)
 
 Full Changelog: [v2.11.0...v2.12.0](https://github.com/context-dot-dev/context-php-sdk/compare/v2.11.0...v2.12.0)

README.md

@@ -13,7 +13,7 @@ The REST API documentation can be found on [docs.context.dev](https://docs.conte
 <!-- x-release-please-start-version -->
 
 ```
-composer require "context-dev/context-dev-php 2.12.0"
+composer require "context-dev/context-dev-php 2.13.0"
 ```
 
 <!-- x-release-please-end -->
@@ -32,7 +32,7 @@ $client = new Client(apiKey: getenv('CONTEXT_DEV_API_KEY') ?: 'My API Key');
 
 $brand = $client->brand->retrieve(domain: 'REPLACE_ME', type: 'by_domain');
 
-var_dump($brand->brand);
+var_dump($brand->cache_metadata);
 ```
 
 ### Value Objects

src/AI/AIExtractProductResponse.php

@@ -4,18 +4,22 @@
 
 namespace ContextDev\AI;
 
+use ContextDev\AI\AIExtractProductResponse\CacheMetadata;
 use ContextDev\AI\AIExtractProductResponse\KeyMetadata;
 use ContextDev\AI\AIExtractProductResponse\Platform;
 use ContextDev\AI\AIExtractProductResponse\Product;
 use ContextDev\Core\Attributes\Optional;
+use ContextDev\Core\Attributes\Required;
 use ContextDev\Core\Concerns\SdkModel;
 use ContextDev\Core\Contracts\BaseModel;
 
 /**
+ * @phpstan-import-type CacheMetadataShape from \ContextDev\AI\AIExtractProductResponse\CacheMetadata
  * @phpstan-import-type KeyMetadataShape from \ContextDev\AI\AIExtractProductResponse\KeyMetadata
  * @phpstan-import-type ProductShape from \ContextDev\AI\AIExtractProductResponse\Product
  *
  * @phpstan-type AIExtractProductResponseShape = array{
+ *   cacheMetadata: CacheMetadata|CacheMetadataShape,
  *   isProductPage?: bool|null,
  *   keyMetadata?: null|KeyMetadata|KeyMetadataShape,
  *   platform?: null|Platform|value-of<Platform>,
@@ -27,6 +31,12 @@ final class AIExtractProductResponse implements BaseModel
     /** @use SdkModel<AIExtractProductResponseShape> */
     use SdkModel;
 
+    /**
+     * 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.
+     */
+    #[Required('cache_metadata')]
+    public CacheMetadata $cacheMetadata;
+
     /**
      * Whether the given URL is a product detail page.
      */
@@ -53,6 +63,20 @@ final class AIExtractProductResponse implements BaseModel
     #[Optional(nullable: true)]
     public ?Product $product;
 
+    /**
+     * `new AIExtractProductResponse()` is missing required properties by the API.
+     *
+     * To enforce required parameters use
+     * ```
+     * AIExtractProductResponse::with(cacheMetadata: ...)
+     * ```
+     *
+     * Otherwise ensure the following setters are called
+     *
+     * ```
+     * (new AIExtractProductResponse)->withCacheMetadata(...)
+     * ```
+     */
     public function __construct()
     {
         $this->initialize();
@@ -63,18 +87,22 @@ public function __construct()
      *
      * You must use named parameters to construct any parameters with a default value.
      *
+     * @param CacheMetadata|CacheMetadataShape $cacheMetadata
      * @param KeyMetadata|KeyMetadataShape|null $keyMetadata
      * @param Platform|value-of<Platform>|null $platform
      * @param Product|ProductShape|null $product
      */
     public static function with(
+        CacheMetadata|array $cacheMetadata,
         ?bool $isProductPage = null,
         KeyMetadata|array|null $keyMetadata = null,
         Platform|string|null $platform = null,
         Product|array|null $product = null,
     ): self {
         $self = new self;
 
+        $self['cacheMetadata'] = $cacheMetadata;
+
         null !== $isProductPage && $self['isProductPage'] = $isProductPage;
         null !== $keyMetadata && $self['keyMetadata'] = $keyMetadata;
         null !== $platform && $self['platform'] = $platform;
@@ -83,6 +111,19 @@ public static function with(
         return $self;
     }
 
+    /**
+     * 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.
+     *
+     * @param CacheMetadata|CacheMetadataShape $cacheMetadata
+     */
+    public function withCacheMetadata(CacheMetadata|array $cacheMetadata): self
+    {
+        $self = clone $this;
+        $self['cacheMetadata'] = $cacheMetadata;
+
+        return $self;
+    }
+
     /**
      * Whether the given URL is a product detail page.
      */

src/AI/AIExtractProductResponse/CacheMetadata.php

@@ -0,0 +1,97 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ContextDev\AI\AIExtractProductResponse;
+
+use ContextDev\AI\AIExtractProductResponse\CacheMetadata\Status;
+use ContextDev\Core\Attributes\Required;
+use ContextDev\Core\Concerns\SdkModel;
+use ContextDev\Core\Contracts\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.
+ *
+ * @phpstan-type CacheMetadataShape = array{
+ *   ageMs: int, status: Status|value-of<Status>
+ * }
+ */
+final class CacheMetadata implements BaseModel
+{
+    /** @use SdkModel<CacheMetadataShape> */
+    use SdkModel;
+
+    /**
+     * Age of the cached data in milliseconds. Zero for miss and zdr responses.
+     */
+    #[Required('age_ms')]
+    public int $ageMs;
+
+    /**
+     * Whether the response was served from cache, required fresh work, or honored zero-data-retention cache bypass.
+     *
+     * @var value-of<Status> $status
+     */
+    #[Required(enum: Status::class)]
+    public string $status;
+
+    /**
+     * `new CacheMetadata()` is missing required properties by the API.
+     *
+     * To enforce required parameters use
+     * ```
+     * CacheMetadata::with(ageMs: ..., status: ...)
+     * ```
+     *
+     * Otherwise ensure the following setters are called
+     *
+     * ```
+     * (new CacheMetadata)->withAgeMs(...)->withStatus(...)
+     * ```
+     */
+    public function __construct()
+    {
+        $this->initialize();
+    }
+
+    /**
+     * Construct an instance from the required parameters.
+     *
+     * You must use named parameters to construct any parameters with a default value.
+     *
+     * @param Status|value-of<Status> $status
+     */
+    public static function with(int $ageMs, Status|string $status): self
+    {
+        $self = new self;
+
+        $self['ageMs'] = $ageMs;
+        $self['status'] = $status;
+
+        return $self;
+    }
+
+    /**
+     * Age of the cached data in milliseconds. Zero for miss and zdr responses.
+     */
+    public function withAgeMs(int $ageMs): self
+    {
+        $self = clone $this;
+        $self['ageMs'] = $ageMs;
+
+        return $self;
+    }
+
+    /**
+     * Whether the response was served from cache, required fresh work, or honored zero-data-retention cache bypass.
+     *
+     * @param Status|value-of<Status> $status
+     */
+    public function withStatus(Status|string $status): self
+    {
+        $self = clone $this;
+        $self['status'] = $status;
+
+        return $self;
+    }
+}

src/AI/AIExtractProductResponse/CacheMetadata/Status.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ContextDev\AI\AIExtractProductResponse\CacheMetadata;
+
+/**
+ * Whether the response was served from cache, required fresh work, or honored zero-data-retention cache bypass.
+ */
+enum Status: string
+{
+    case HIT = 'hit';
+
+    case MISS = 'miss';
+
+    case ZDR = 'zdr';
+}

src/AI/AIExtractProductsResponse.php

@@ -4,17 +4,21 @@
 
 namespace ContextDev\AI;
 
+use ContextDev\AI\AIExtractProductsResponse\CacheMetadata;
 use ContextDev\AI\AIExtractProductsResponse\KeyMetadata;
 use ContextDev\AI\AIExtractProductsResponse\Product;
 use ContextDev\Core\Attributes\Optional;
+use ContextDev\Core\Attributes\Required;
 use ContextDev\Core\Concerns\SdkModel;
 use ContextDev\Core\Contracts\BaseModel;
 
 /**
+ * @phpstan-import-type CacheMetadataShape from \ContextDev\AI\AIExtractProductsResponse\CacheMetadata
  * @phpstan-import-type KeyMetadataShape from \ContextDev\AI\AIExtractProductsResponse\KeyMetadata
  * @phpstan-import-type ProductShape from \ContextDev\AI\AIExtractProductsResponse\Product
  *
  * @phpstan-type AIExtractProductsResponseShape = array{
+ *   cacheMetadata: CacheMetadata|CacheMetadataShape,
  *   keyMetadata?: null|KeyMetadata|KeyMetadataShape,
  *   products?: list<Product|ProductShape>|null,
  * }
@@ -24,6 +28,12 @@ final class AIExtractProductsResponse implements BaseModel
     /** @use SdkModel<AIExtractProductsResponseShape> */
     use SdkModel;
 
+    /**
+     * 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.
+     */
+    #[Required('cache_metadata')]
+    public CacheMetadata $cacheMetadata;
+
     /**
      * Metadata about the API key used for the request. Included in every response whenever a valid API key is provided, even when the response status is not 200.
      */
@@ -38,6 +48,20 @@ final class AIExtractProductsResponse implements BaseModel
     #[Optional(list: Product::class)]
     public ?array $products;
 
+    /**
+     * `new AIExtractProductsResponse()` is missing required properties by the API.
+     *
+     * To enforce required parameters use
+     * ```
+     * AIExtractProductsResponse::with(cacheMetadata: ...)
+     * ```
+     *
+     * Otherwise ensure the following setters are called
+     *
+     * ```
+     * (new AIExtractProductsResponse)->withCacheMetadata(...)
+     * ```
+     */
     public function __construct()
     {
         $this->initialize();
@@ -48,21 +72,38 @@ public function __construct()
      *
      * You must use named parameters to construct any parameters with a default value.
      *
+     * @param CacheMetadata|CacheMetadataShape $cacheMetadata
      * @param KeyMetadata|KeyMetadataShape|null $keyMetadata
      * @param list<Product|ProductShape>|null $products
      */
     public static function with(
+        CacheMetadata|array $cacheMetadata,
         KeyMetadata|array|null $keyMetadata = null,
-        ?array $products = null
+        ?array $products = null,
     ): self {
         $self = new self;
 
+        $self['cacheMetadata'] = $cacheMetadata;
+
         null !== $keyMetadata && $self['keyMetadata'] = $keyMetadata;
         null !== $products && $self['products'] = $products;
 
         return $self;
     }
 
+    /**
+     * 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.
+     *
+     * @param CacheMetadata|CacheMetadataShape $cacheMetadata
+     */
+    public function withCacheMetadata(CacheMetadata|array $cacheMetadata): self
+    {
+        $self = clone $this;
+        $self['cacheMetadata'] = $cacheMetadata;
+
+        return $self;
+    }
+
     /**
      * Metadata about the API key used for the request. Included in every response whenever a valid API key is provided, even when the response status is not 200.
      *