feat!: use builders for RequestOptions

stainless-app[bot] · stainless-app[bot] · commit b176ad5c1a04 · 2025-09-02T16:25:58.000Z
diff --git a/README.md b/README.md
@@ -157,7 +157,7 @@ Certain errors will be automatically retried 2 times by default, with a short ex
 
 Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal errors, and timeouts will all be retried by default.
 
-You can use the `max_retries` option to configure or disable this:
+You can use the `maxRetries` option to configure or disable this:
 
 ```php
 <?php
@@ -175,7 +175,7 @@ $result = $client->messages->create(
   maxTokens: 1024,
   messages: [MessageParam::with(role: "user", content: "Hello, Claude")],
   model: "claude-sonnet-4-20250514",
-  new RequestOptions(maxRetries: 5),
+  requestOptions: RequestOptions::with(maxRetries: 5),
 );
 ```
 
@@ -187,7 +187,7 @@ $result = $client->messages->create(
 
 You can send undocumented parameters to any endpoint, and read undocumented response properties, like so:
 
-Note: the `extra_` parameters of the same name overrides the documented parameters.
+Note: the `extra*` parameters of the same name overrides the documented parameters.
 
 ```php
 <?php
@@ -199,7 +199,7 @@ $message = $client->messages->create(
   maxTokens: 1024,
   messages: [MessageParam::with(role: "user", content: "Hello, Claude")],
   model: "claude-sonnet-4-20250514",
-  new RequestOptions(
+  requestOptions: RequestOptions::with(
     extraQueryParams: ["my_query_parameter" => "value"],
     extraBodyParams: ["my_body_parameter" => "value"],
     extraHeaders: ["my-header" => "value"],
diff --git a/src/Client.php b/src/Client.php
@@ -44,7 +44,7 @@ public function __construct(
             'ANTHROPIC_BASE_URL'
         ) ?: 'https://api.anthropic.com';
 
-        $options = new RequestOptions(
+        $options = RequestOptions::with(
             uriFactory: Psr17FactoryDiscovery::findUriFactory(),
             streamFactory: Psr17FactoryDiscovery::findStreamFactory(),
             requestFactory: Psr17FactoryDiscovery::findRequestFactory(),
diff --git a/src/Core.php b/src/Core.php
@@ -4,6 +4,6 @@
 
 namespace Anthropic\Core;
 
-use Anthropic\Core\Implementation\Omittable;
+use Anthropic\Core\Implementation\Omit;
 
-const OMIT = Omittable::OMIT;
+const OMIT = Omit::omit;
diff --git a/src/Core/BaseClient.php b/src/Core/BaseClient.php
@@ -32,6 +32,8 @@ class BaseClient
     protected UriInterface $baseUrl;
 
     /**
+     * @internal
+     *
      * @param array<string, string|int|list<string|int>|null> $headers
      */
     public function __construct(
@@ -108,6 +110,8 @@ protected function authHeaders(): array
     }
 
     /**
+     * @internal
+     *
      * @param string|list<string> $path
      * @param array<string, mixed> $query
      * @param array<string, string|int|list<string|int>|null> $headers
@@ -135,26 +139,31 @@ protected function buildRequest(
         mixed $body,
         RequestOptions|array|null $opts,
     ): array {
-        $opts = array_merge($this->options->toArray(), RequestOptions::parse($opts)->toArray());
-        $options = new RequestOptions(...$opts);
+        $options = RequestOptions::parse($this->options, $opts);
 
         $parsedPath = Util::parsePath($path);
 
         /** @var array<string, mixed> $mergedQuery */
-        $mergedQuery = array_merge_recursive($query, $options->extraQueryParams);
+        $mergedQuery = array_merge_recursive(
+            $query,
+            $options->extraQueryParams ?? [],
+        );
         $uri = Util::joinUri($this->baseUrl, path: $parsedPath, query: $mergedQuery)->__toString();
 
         /** @var array<string, string|list<string>|null> $mergedHeaders */
         $mergedHeaders = [...$this->headers,
             ...$this->authHeaders(),
             ...$headers,
-            ...$options->extraHeaders, ];
+            ...($options->extraHeaders ?? []), ];
 
         $req = ['method' => strtoupper($method), 'path' => $uri, 'query' => $mergedQuery, 'headers' => $mergedHeaders, 'body' => $body];
 
         return [$req, $options];
     }
 
+    /**
+     * @internal
+     */
     protected function followRedirect(
         ResponseInterface $rsp,
         RequestInterface $req
@@ -170,6 +179,8 @@ protected function followRedirect(
     }
 
     /**
+     * @internal
+     *
      * @param bool|int|float|string|resource|\Traversable<mixed>|array<string,
      * mixed,>|null $data
      */
diff --git a/src/Core/Concerns/SdkParams.php b/src/Core/Concerns/SdkParams.php
@@ -18,15 +18,7 @@ trait SdkParams
      * @param array<string, mixed>|self|null           $params
      * @param array<string, mixed>|RequestOptions|null $options
      *
-     * @return array{array<string, mixed>, array{
-     *     timeout: float,
-     *     maxRetries: int,
-     *     initialRetryDelay: float,
-     *     maxRetryDelay: float,
-     *     extraHeaders: list<string>,
-     *     extraQueryParams: list<string>,
-     *     extraBodyParams: list<string>,
-     * }}
+     * @return array{array<string, mixed>, RequestOptions}
      */
     public static function parseRequest(array|self|null $params, array|RequestOptions|null $options): array
     {
@@ -40,17 +32,6 @@ public static function parseRequest(array|self|null $params, array|RequestOption
             $opts->maxRetries = 0;
         }
 
-        $opt = $opts->__serialize();
-        if (empty($opt['extraHeaders'])) {
-            unset($opt['extraHeaders']);
-        }
-        if (empty($opt['extraQueryParams'])) {
-            unset($opt['extraQueryParams']);
-        }
-        if (empty($opt['extraBodyParams'])) {
-            unset($opt['extraBodyParams']);
-        }
-
-        return [$dumped, $opt]; // @phpstan-ignore-line
+        return [$dumped, $opts]; // @phpstan-ignore-line
     }
 }
diff --git a/src/Core/Implementation/Omit.php b/src/Core/Implementation/Omit.php
@@ -7,7 +7,7 @@
 /**
  * @internal
  */
-enum Omittable
+enum Omit
 {
-    case OMIT;
+    case omit;
 }
diff --git a/src/Core/Services/Beta/FilesService.php b/src/Core/Services/Beta/FilesService.php
@@ -69,7 +69,7 @@ public function list(
                 $header_params,
                 ['betas' => 'anthropic-beta']
             ),
-            options: array_merge(
+            options: RequestOptions::parse(
                 ['extraHeaders' => ['anthropic-beta' => 'files-api-2025-04-14']],
                 $options,
             ),
@@ -103,7 +103,7 @@ public function delete(
                 $parsed,
                 ['betas' => 'anthropic-beta']
             ),
-            options: array_merge(
+            options: RequestOptions::parse(
                 ['extraHeaders' => ['anthropic-beta' => 'files-api-2025-04-14']],
                 $options,
             ),
@@ -136,7 +136,7 @@ public function retrieveMetadata(
                 $parsed,
                 ['betas' => 'anthropic-beta']
             ),
-            options: array_merge(
+            options: RequestOptions::parse(
                 ['extraHeaders' => ['anthropic-beta' => 'files-api-2025-04-14']],
                 $options,
             ),
diff --git a/src/Core/Services/Beta/Messages/BatchesService.php b/src/Core/Services/Beta/Messages/BatchesService.php
@@ -64,7 +64,7 @@ public function create(
                 $header_params
             ),
             body: (object) array_diff_key($parsed, array_keys($header_params)),
-            options: array_merge(
+            options: RequestOptions::parse(
                 ['extraHeaders' => ['anthropic-beta' => 'message-batches-2024-09-24']],
                 $options,
             ),
@@ -99,7 +99,7 @@ public function retrieve(
                 $parsed,
                 ['betas' => 'anthropic-beta']
             ),
-            options: array_merge(
+            options: RequestOptions::parse(
                 ['extraHeaders' => ['anthropic-beta' => 'message-batches-2024-09-24']],
                 $options,
             ),
@@ -153,7 +153,7 @@ public function list(
                 $header_params,
                 ['betas' => 'anthropic-beta']
             ),
-            options: array_merge(
+            options: RequestOptions::parse(
                 ['extraHeaders' => ['anthropic-beta' => 'message-batches-2024-09-24']],
                 $options,
             ),
@@ -191,7 +191,7 @@ public function delete(
                 $parsed,
                 ['betas' => 'anthropic-beta']
             ),
-            options: array_merge(
+            options: RequestOptions::parse(
                 ['extraHeaders' => ['anthropic-beta' => 'message-batches-2024-09-24']],
                 $options,
             ),
@@ -228,7 +228,7 @@ public function cancel(
                 $parsed,
                 ['betas' => 'anthropic-beta']
             ),
-            options: array_merge(
+            options: RequestOptions::parse(
                 ['extraHeaders' => ['anthropic-beta' => 'message-batches-2024-09-24']],
                 $options,
             ),
@@ -265,7 +265,7 @@ public function results(
                 ['Accept' => 'application/x-jsonl', ...$parsed],
                 ['betas' => 'anthropic-beta'],
             ),
-            options: array_merge(
+            options: RequestOptions::parse(
                 ['extraHeaders' => ['anthropic-beta' => 'message-batches-2024-09-24']],
                 $options,
             ),
@@ -296,7 +296,7 @@ public function resultsStream(
                 ['Accept' => 'application/x-jsonl', ...$parsed],
                 ['betas' => 'anthropic-beta'],
             ),
-            options: array_merge(
+            options: RequestOptions::parse(
                 ['extraHeaders' => ['anthropic-beta' => 'message-batches-2024-09-24']],
                 $options,
             ),
diff --git a/src/Core/Services/Beta/MessagesService.php b/src/Core/Services/Beta/MessagesService.php
@@ -294,7 +294,7 @@ public function create(
                 $header_params
             ),
             body: (object) array_diff_key($parsed, array_keys($header_params)),
-            options: array_merge(['timeout' => 600], $options),
+            options: $options,
             convert: BetaMessage::class,
         );
     }
@@ -526,7 +526,7 @@ public function createStream(
                 $header_params
             ),
             body: (object) array_diff_key($parsed, array_keys($header_params)),
-            options: array_merge(['timeout' => 600], $options),
+            options: $options,
             convert: BetaRawMessageStreamEvent::class,
             stream: SSEStream::class,
         );
diff --git a/src/Core/Services/MessagesService.php b/src/Core/Services/MessagesService.php
@@ -272,7 +272,7 @@ public function create(
             method: 'post',
             path: 'v1/messages',
             body: (object) $parsed,
-            options: array_merge(['timeout' => 600], $options),
+            options: $options,
             convert: Message::class,
         );
     }
@@ -490,7 +490,7 @@ public function createStream(
             method: 'post',
             path: 'v1/messages',
             body: (object) $parsed,
-            options: array_merge(['timeout' => 600], $options),
+            options: $options,
             convert: RawMessageStreamEvent::class,
             stream: SSEStream::class,
         );
diff --git a/src/RequestOptions.php b/src/RequestOptions.php

Original file line number	Diff line number	Diff line change
`@@ -7,7 +7,7 @@`
`7`	`7`	`/**`
`8`	`8`	`* @internal`
`9`	`9`	`*/`
`10`		`-enum Omittable`
	`10`	`+enum Omit`
`11`	`11`	`{`
`12`		`- case OMIT;`
	`12`	`+ case omit;`
`13`	`13`	`}`