Merge pull request #9 from context-dot-dev/release-please--branches--main--changes--next

release: 2.1.0

Author: YahiaBakour

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "2.0.0"
+  ".": "2.1.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 29
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/context-dev/context.dev-7dbd739a81e6aaf7fc7ef1858606e7d572d309af55082a66431d9292e655e66f.yml
-openapi_spec_hash: a6374d5d718a7bd9d3d54fb657e2bd9d
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/context-dev/context.dev-51ebe668b198157ccb18984017dd2fe35f7675220e8b933b03325b3c459ef2a6.yml
+openapi_spec_hash: b3ed94bd6b59d4e32fc2c5aa8187d6b2
 config_hash: ff35e224e809656528c44163aa41bebd

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 2.1.0 (2026-07-08)
+
+Full Changelog: [v2.0.0...v2.1.0](https://github.com/context-dot-dev/context-php-sdk/compare/v2.0.0...v2.1.0)
+
+### Features
+
+* **api:** api update ([efb4692](https://github.com/context-dot-dev/context-php-sdk/commit/efb469262cfa86a8b362131a90c0ccacabf3e7c9))
+* **api:** api update ([5e090db](https://github.com/context-dot-dev/context-php-sdk/commit/5e090db2c8b5430cf5818984c928831952dcbb32))
+* **api:** api update ([3503b7b](https://github.com/context-dot-dev/context-php-sdk/commit/3503b7b911e5e6992406040ecb82c6d8f7711243))
+* **api:** api update ([5b92377](https://github.com/context-dot-dev/context-php-sdk/commit/5b9237711f3ad827a51e6166d71e69fab8fd37dd))
+
 ## 2.0.0 (2026-07-06)
 
 Full Changelog: [v1.3.0...v2.0.0](https://github.com/context-dot-dev/context-php-sdk/compare/v1.3.0...v2.0.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.0.0"
+composer require "context-dev/context-dev-php 2.1.0"
 ```
 
 <!-- x-release-please-end -->

src/Brand/BrandRetrieveParams.php

@@ -13,7 +13,7 @@
 use ContextDev\Core\Contracts\BaseModel;
 
 /**
- * Retrieve logos, backdrops, colors, industry, description, and more. Provide exactly one lookup identifier in the request body: a domain, company name, email address, stock ticker, or transaction descriptor.
+ * Retrieve logos, backdrops, colors, industry, description, and more. Provide exactly one lookup identifier in the request body: a domain, company name, email address, stock ticker, transaction descriptor, or direct URL. Note: `by_direct_url` fetches brand data only from the provided URL — not from the entire internet.
  *
  * @see ContextDev\Services\BrandService::retrieve()
  *
@@ -29,6 +29,7 @@
  *   email: string,
  *   ticker: string,
  *   tickerExchange?: string|null,
+ *   directURL: string,
  *   transactionInfo: string,
  *   city?: string|null,
  *   highConfidenceOnly?: bool|null,
@@ -108,6 +109,12 @@ final class BrandRetrieveParams implements BaseModel
     #[Optional('ticker_exchange')]
     public ?string $tickerExchange;
 
+    /**
+     * Full http(s) URL to fetch brand data from (e.g., 'https://stripe.com/enterprise'). Only this URL is fetched — not the entire internet.
+     */
+    #[Required('direct_url')]
+    public string $directURL;
+
     /**
      * Transaction information to identify the brand.
      */
@@ -149,6 +156,7 @@ final class BrandRetrieveParams implements BaseModel
      *   name: ...,
      *   email: ...,
      *   ticker: ...,
+     *   directURL: ...,
      *   transactionInfo: ...,
      * )
      * ```
@@ -162,6 +170,7 @@ final class BrandRetrieveParams implements BaseModel
      *   ->withName(...)
      *   ->withEmail(...)
      *   ->withTicker(...)
+     *   ->withDirectURL(...)
      *   ->withTransactionInfo(...)
      * ```
      */
@@ -184,6 +193,7 @@ public static function with(
         string $name,
         string $email,
         string $ticker,
+        string $directURL,
         string $transactionInfo,
         ForceLanguage|string|null $forceLanguage = null,
         ?int $maxAgeMs = null,
@@ -203,6 +213,7 @@ public static function with(
         $self['name'] = $name;
         $self['email'] = $email;
         $self['ticker'] = $ticker;
+        $self['directURL'] = $directURL;
         $self['transactionInfo'] = $transactionInfo;
 
         null !== $forceLanguage && $self['forceLanguage'] = $forceLanguage;
@@ -342,6 +353,17 @@ public function withTickerExchange(string $tickerExchange): self
         return $self;
     }
 
+    /**
+     * Full http(s) URL to fetch brand data from (e.g., 'https://stripe.com/enterprise'). Only this URL is fetched — not the entire internet.
+     */
+    public function withDirectURL(string $directURL): self
+    {
+        $self = clone $this;
+        $self['directURL'] = $directURL;
+
+        return $self;
+    }
+
     /**
      * Transaction information to identify the brand.
      */

src/Monitors/MonitorCreateParams/ChangeDetection/MonitorsSemanticChangeDetection.php

@@ -10,10 +10,10 @@
 use ContextDev\Core\Contracts\BaseModel;
 
 /**
- * Detect meaning-level changes that match a natural language query.
+ * Detect meaning-level changes to the extracted data, ignoring cosmetic or paraphrase-only differences. What is watched is determined by the extract target's `schema` and `instructions`.
  *
  * @phpstan-type MonitorsSemanticChangeDetectionShape = array{
- *   query: string, type: 'semantic', confidenceThreshold?: float|null
+ *   type: 'semantic', confidenceThreshold?: float|null
  * }
  */
 final class MonitorsSemanticChangeDetection implements BaseModel
@@ -25,26 +25,9 @@ final class MonitorsSemanticChangeDetection implements BaseModel
     #[Required]
     public string $type = 'semantic';
 
-    #[Required]
-    public string $query;
-
     #[Optional('confidence_threshold')]
     public ?float $confidenceThreshold;
 
-    /**
-     * `new MonitorsSemanticChangeDetection()` is missing required properties by the API.
-     *
-     * To enforce required parameters use
-     * ```
-     * MonitorsSemanticChangeDetection::with(query: ...)
-     * ```
-     *
-     * Otherwise ensure the following setters are called
-     *
-     * ```
-     * (new MonitorsSemanticChangeDetection)->withQuery(...)
-     * ```
-     */
     public function __construct()
     {
         $this->initialize();
@@ -55,27 +38,15 @@ public function __construct()
      *
      * You must use named parameters to construct any parameters with a default value.
      */
-    public static function with(
-        string $query,
-        ?float $confidenceThreshold = null
-    ): self {
+    public static function with(?float $confidenceThreshold = null): self
+    {
         $self = new self;
 
-        $self['query'] = $query;
-
         null !== $confidenceThreshold && $self['confidenceThreshold'] = $confidenceThreshold;
 
         return $self;
     }
 
-    public function withQuery(string $query): self
-    {
-        $self = clone $this;
-        $self['query'] = $query;
-
-        return $self;
-    }
-
     /**
      * @param 'semantic' $type
      */

src/Monitors/MonitorCreateParams/Target/MonitorsExtractTarget.php

@@ -10,13 +10,13 @@
 use ContextDev\Core\Contracts\BaseModel;
 
 /**
- * Watch a site's extracted structured data.
+ * Watch the monitor-relevant pages of a site for meaningful changes. A crawl guided by `schema`/`instructions` selects up to `max_pages` relevant pages to track; each run re-checks exactly those pages, and confirmed content changes are judged against the monitor's instructions. The tracked page set is refreshed by a periodic re-discovery crawl.
  *
  * @phpstan-type MonitorsExtractTargetShape = array{
+ *   instructions: string,
  *   type: 'extract',
  *   url: string,
  *   followSubdomains?: bool|null,
- *   instructions?: string|null,
  *   maxDepth?: int|null,
  *   maxPages?: int|null,
  *   schema?: array<string,mixed>|null,
@@ -31,6 +31,12 @@ final class MonitorsExtractTarget implements BaseModel
     #[Required]
     public string $type = 'extract';
 
+    /**
+     * Natural-language instructions guiding which pages and facts to track and which changes to report.
+     */
+    #[Required]
+    public string $instructions;
+
     /**
      * Root URL to extract structured data from.
      */
@@ -40,26 +46,20 @@ final class MonitorsExtractTarget implements BaseModel
     #[Optional('follow_subdomains')]
     public ?bool $followSubdomains;
 
-    /**
-     * Optional natural-language instructions guiding what to extract.
-     */
-    #[Optional]
-    public ?string $instructions;
-
     /**
      * Optional maximum link depth from the starting URL (0 = only the starting page).
      */
     #[Optional('max_depth')]
     public ?int $maxDepth;
 
     /**
-     * Maximum number of pages to analyze during extraction.
+     * Maximum number of pages to track.
      */
     #[Optional('max_pages')]
     public ?int $maxPages;
 
     /**
-     * JSON Schema describing the structured data to extract and watch for changes. If omitted, a default summary + key-points schema is used.
+     * JSON Schema describing the data you care about. It guides which pages are selected for tracking and gives the change judge context on what matters. If omitted, a default summary + key-points schema is used.
      *
      * @var array<string,mixed>|null $schema
      */
@@ -71,13 +71,13 @@ final class MonitorsExtractTarget implements BaseModel
      *
      * To enforce required parameters use
      * ```
-     * MonitorsExtractTarget::with(url: ...)
+     * MonitorsExtractTarget::with(instructions: ..., url: ...)
      * ```
      *
      * Otherwise ensure the following setters are called
      *
      * ```
-     * (new MonitorsExtractTarget)->withURL(...)
+     * (new MonitorsExtractTarget)->withInstructions(...)->withURL(...)
      * ```
      */
     public function __construct()
@@ -93,26 +93,37 @@ public function __construct()
      * @param array<string,mixed>|null $schema
      */
     public static function with(
+        string $instructions,
         string $url,
         ?bool $followSubdomains = null,
-        ?string $instructions = null,
         ?int $maxDepth = null,
         ?int $maxPages = null,
         ?array $schema = null,
     ): self {
         $self = new self;
 
+        $self['instructions'] = $instructions;
         $self['url'] = $url;
 
         null !== $followSubdomains && $self['followSubdomains'] = $followSubdomains;
-        null !== $instructions && $self['instructions'] = $instructions;
         null !== $maxDepth && $self['maxDepth'] = $maxDepth;
         null !== $maxPages && $self['maxPages'] = $maxPages;
         null !== $schema && $self['schema'] = $schema;
 
         return $self;
     }
 
+    /**
+     * Natural-language instructions guiding which pages and facts to track and which changes to report.
+     */
+    public function withInstructions(string $instructions): self
+    {
+        $self = clone $this;
+        $self['instructions'] = $instructions;
+
+        return $self;
+    }
+
     /**
      * @param 'extract' $type
      */
@@ -143,17 +154,6 @@ public function withFollowSubdomains(bool $followSubdomains): self
         return $self;
     }
 
-    /**
-     * Optional natural-language instructions guiding what to extract.
-     */
-    public function withInstructions(string $instructions): self
-    {
-        $self = clone $this;
-        $self['instructions'] = $instructions;
-
-        return $self;
-    }
-
     /**
      * Optional maximum link depth from the starting URL (0 = only the starting page).
      */
@@ -166,7 +166,7 @@ public function withMaxDepth(int $maxDepth): self
     }
 
     /**
-     * Maximum number of pages to analyze during extraction.
+     * Maximum number of pages to track.
      */
     public function withMaxPages(int $maxPages): self
     {
@@ -177,7 +177,7 @@ public function withMaxPages(int $maxPages): self
     }
 
     /**
-     * JSON Schema describing the structured data to extract and watch for changes. If omitted, a default summary + key-points schema is used.
+     * JSON Schema describing the data you care about. It guides which pages are selected for tracking and gives the change judge context on what matters. If omitted, a default summary + key-points schema is used.
      *
      * @param array<string,mixed> $schema
      */

src/Monitors/MonitorCreateParams/Target/MonitorsSitemapTarget.php

@@ -10,7 +10,7 @@
 use ContextDev\Core\Contracts\BaseModel;
 
 /**
- * Watch a sitemap for URL additions and removals. Crawled URLs are normalized (lowercased host, no trailing slash/fragment) and scoped to the monitored site and its subdomains before comparison. A new URL set must be observed on two consecutive runs before a change is reported, suppressing one-run crawl flaps.
+ * Watch a sitemap for URL additions and removals. Crawled URLs are normalized (lowercased host, no trailing slash/fragment) and scoped to the monitored site and its subdomains before comparison. On a detected difference the sitemap is re-fetched within the same run and only URLs both observations agree on are reported, suppressing transient crawl flaps.
  *
  * @phpstan-type MonitorsSitemapTargetShape = array{
  *   type: 'sitemap',

src/Monitors/MonitorGetChangeResponse.php

@@ -40,7 +40,6 @@
  *   importance?: null|Importance|value-of<Importance>,
  *   matchedURLCount?: int|null,
  *   matchedURLs?: list<string>|null,
- *   query?: string|null,
  *   removedURLCount?: int|null,
  *   removedURLs?: list<string>|null,
  *   tags?: list<string>|null,
@@ -136,9 +135,6 @@ final class MonitorGetChangeResponse implements BaseModel
     #[Optional('matched_urls', list: 'string')]
     public ?array $matchedURLs;
 
-    #[Optional]
-    public ?string $query;
-
     #[Optional('removed_url_count')]
     public ?int $removedURLCount;
 
@@ -234,7 +230,6 @@ public static function with(
         Importance|string|null $importance = null,
         ?int $matchedURLCount = null,
         ?array $matchedURLs = null,
-        ?string $query = null,
         ?int $removedURLCount = null,
         ?array $removedURLs = null,
         ?array $tags = null,
@@ -262,7 +257,6 @@ public static function with(
         null !== $importance && $self['importance'] = $importance;
         null !== $matchedURLCount && $self['matchedURLCount'] = $matchedURLCount;
         null !== $matchedURLs && $self['matchedURLs'] = $matchedURLs;
-        null !== $query && $self['query'] = $query;
         null !== $removedURLCount && $self['removedURLCount'] = $removedURLCount;
         null !== $removedURLs && $self['removedURLs'] = $removedURLs;
         null !== $tags && $self['tags'] = $tags;
@@ -464,14 +458,6 @@ public function withMatchedURLs(array $matchedURLs): self
         return $self;
     }
 
-    public function withQuery(string $query): self
-    {
-        $self = clone $this;
-        $self['query'] = $query;
-
-        return $self;
-    }
-
     public function withRemovedURLCount(int $removedURLCount): self
     {
         $self = clone $this;