fix(client): properly generate file params

Author: stainless-app[bot]

README.md

@@ -145,6 +145,36 @@ $client = new Client(requestOptions: ['maxRetries' => 0]);
 $result = $client->accounts->list(requestOptions: ['maxRetries' => 5]);
 ```
 
+### File uploads
+
+Request parameters that correspond to file uploads can be passed as a resource returned by `fopen()`, a string of file contents, or a `FileParam` instance.
+
+```php
+<?php
+
+use BeeperDesktop\Core\FileParam;
+
+// Pass a string with filename and content type:
+$contents = file_get_contents('/path/to/file');
+// Pass a string with filename and content type:
+$response = $client->assets->upload(
+  file: FileParam::fromString($contents, filename: '/path/to/file', contentType: '…'),
+);
+
+// Pass in only a string (where applicable)
+$response = $client->assets->upload(file: '…');
+
+// Pass an open resource:
+$fd = fopen('/path/to/file', 'r');
+try {
+  $response = $client->assets->upload(
+    file: FileParam::fromResource($fd, filename: '/path/to/file', contentType: '…'),
+  );
+} finally {
+  fclose($fd);
+}
+```
+
 ## Advanced concepts
 
 ### Making custom or undocumented requests

src/Assets/AssetUploadParams.php

@@ -9,14 +9,15 @@
 use BeeperDesktop\Core\Concerns\SdkModel;
 use BeeperDesktop\Core\Concerns\SdkParams;
 use BeeperDesktop\Core\Contracts\BaseModel;
+use BeeperDesktop\Core\FileParam;
 
 /**
  * Upload a file to a temporary location using multipart/form-data. Returns an uploadID that can be referenced when sending messages with attachments.
  *
  * @see BeeperDesktop\Services\AssetsService::upload()
  *
  * @phpstan-type AssetUploadParamsShape = array{
- *   file: string, fileName?: string|null, mimeType?: string|null
+ *   file: string|FileParam, fileName?: string|null, mimeType?: string|null
  * }
  */
 final class AssetUploadParams implements BaseModel
@@ -68,7 +69,7 @@ public function __construct()
      * You must use named parameters to construct any parameters with a default value.
      */
     public static function with(
-        string $file,
+        string|FileParam $file,
         ?string $fileName = null,
         ?string $mimeType = null
     ): self {
@@ -85,7 +86,7 @@ public static function with(
     /**
      * The file to upload (max 500 MB).
      */
-    public function withFile(string $file): self
+    public function withFile(string|FileParam $file): self
     {
         $self = clone $this;
         $self['file'] = $file;

src/Core/Conversion.php

@@ -21,6 +21,10 @@ public static function dump_unknown(mixed $value, DumpState $state): mixed
         }
 
         if (is_object($value)) {
+            if ($value instanceof FileParam) {
+                return $value;
+            }
+
             if (is_a($value, class: ConverterSource::class)) {
                 return $value::converter()->dump($value, state: $state);
             }

src/Core/FileParam.php

@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BeeperDesktop\Core;
+
+/**
+ * Represents a file to upload in a multipart request.
+ *
+ * ```php
+ * // From a file on disk:
+ * $client->files->upload(file: FileParam::fromResource(fopen('data.csv', 'r')));
+ *
+ * // From a string:
+ * $client->files->upload(file: FileParam::fromString('csv data...', 'data.csv'));
+ * ```
+ */
+final class FileParam
+{
+    public const DEFAULT_CONTENT_TYPE = 'application/octet-stream';
+
+    /**
+     * @param resource|string $data the file content as a resource or string
+     */
+    private function __construct(
+        public readonly mixed $data,
+        public readonly string $filename,
+        public readonly string $contentType = self::DEFAULT_CONTENT_TYPE,
+    ) {}
+
+    /**
+     * Create a FileParam from an open resource (e.g. from fopen()).
+     *
+     * @param resource $resource an open file resource
+     * @param string|null $filename Override the filename. Defaults to the resource URI basename.
+     * @param string $contentType override the content type
+     */
+    public static function fromResource(mixed $resource, ?string $filename = null, string $contentType = self::DEFAULT_CONTENT_TYPE): self
+    {
+        if (!is_resource($resource)) {
+            throw new \InvalidArgumentException('Expected a resource, got '.get_debug_type($resource));
+        }
+
+        if (null === $filename) {
+            $meta = stream_get_meta_data($resource);
+            $filename = basename($meta['uri'] ?? 'upload');
+        }
+
+        return new self($resource, filename: $filename, contentType: $contentType);
+    }
+
+    /**
+     * Create a FileParam from a string.
+     *
+     * @param string $content the file content
+     * @param string $filename the filename for the Content-Disposition header
+     * @param string $contentType override the content type
+     */
+    public static function fromString(string $content, string $filename, string $contentType = self::DEFAULT_CONTENT_TYPE): self
+    {
+        return new self($content, filename: $filename, contentType: $contentType);
+    }
+}

src/Core/Util.php

@@ -283,7 +283,7 @@ public static function withSetBody(
 
         if (preg_match('/^multipart\/form-data/', $contentType)) {
             [$boundary, $gen] = self::encodeMultipartStreaming($body);
-            $encoded = implode('', iterator_to_array($gen));
+            $encoded = implode('', iterator_to_array($gen, preserve_keys: false));
             $stream = $factory->createStream($encoded);
 
             /** @var RequestInterface */
@@ -447,11 +447,18 @@ private static function writeMultipartContent(
     ): \Generator {
         $contentLine = "Content-Type: %s\r\n\r\n";
 
-        if (is_resource($val)) {
-            yield sprintf($contentLine, $contentType ?? 'application/octet-stream');
-            while (!feof($val)) {
-                if ($read = fread($val, length: self::BUF_SIZE)) {
-                    yield $read;
+        if ($val instanceof FileParam) {
+            $ct = $val->contentType ?? $contentType;
+
+            yield sprintf($contentLine, $ct);
+            $data = $val->data;
+            if (is_string($data)) {
+                yield $data;
+            } else { // resource
+                while (!feof($data)) {
+                    if ($read = fread($data, length: self::BUF_SIZE)) {
+                        yield $read;
+                    }
                 }
             }
         } elseif (is_string($val) || is_numeric($val) || is_bool($val)) {
@@ -483,17 +490,48 @@ private static function writeMultipartChunk(
         yield 'Content-Disposition: form-data';
 
         if (!is_null($key)) {
-            $name = rawurlencode(self::strVal($key));
+            $name = str_replace(['"', "\r", "\n"], replace: '', subject: $key);
 
             yield "; name=\"{$name}\"";
         }
 
+        // File uploads require a filename in the Content-Disposition header,
+        // e.g. `Content-Disposition: form-data; name="file"; filename="data.csv"`
+        // Without this, many servers will reject the upload with a 400.
+        if ($val instanceof FileParam) {
+            $filename = str_replace(['"', "\r", "\n"], replace: '', subject: $val->filename);
+
+            yield "; filename=\"{$filename}\"";
+        }
+
         yield "\r\n";
         foreach (self::writeMultipartContent($val, closing: $closing) as $chunk) {
             yield $chunk;
         }
     }
 
+    /**
+     * Expands list arrays into separate multipart parts, applying the configured array key format.
+     *
+     * @param list<callable> $closing
+     *
+     * @return \Generator<string>
+     */
+    private static function writeMultipartField(
+        string $boundary,
+        ?string $key,
+        mixed $val,
+        array &$closing
+    ): \Generator {
+        if (is_array($val) && array_is_list($val)) {
+            foreach ($val as $item) {
+                yield from self::writeMultipartField(boundary: $boundary, key: $key, val: $item, closing: $closing);
+            }
+        } else {
+            yield from self::writeMultipartChunk(boundary: $boundary, key: $key, val: $val, closing: $closing);
+        }
+    }
+
     /**
      * @param bool|int|float|string|resource|\Traversable<mixed,>|array<string,mixed>|null $body
      *
@@ -508,14 +546,10 @@ private static function encodeMultipartStreaming(mixed $body): array
             try {
                 if (is_array($body) || is_object($body)) {
                     foreach ((array) $body as $key => $val) {
-                        foreach (static::writeMultipartChunk(boundary: $boundary, key: $key, val: $val, closing: $closing) as $chunk) {
-                            yield $chunk;
-                        }
+                        yield from static::writeMultipartField(boundary: $boundary, key: $key, val: $val, closing: $closing);
                     }
                 } else {
-                    foreach (static::writeMultipartChunk(boundary: $boundary, key: null, val: $body, closing: $closing) as $chunk) {
-                        yield $chunk;
-                    }
+                    yield from static::writeMultipartField(boundary: $boundary, key: null, val: $body, closing: $closing);
                 }
 
                 yield "--{$boundary}--\r\n";

src/ServiceContracts/AssetsContract.php

@@ -8,6 +8,7 @@
 use BeeperDesktop\Assets\AssetUploadBase64Response;
 use BeeperDesktop\Assets\AssetUploadResponse;
 use BeeperDesktop\Core\Exceptions\APIException;
+use BeeperDesktop\Core\FileParam;
 use BeeperDesktop\RequestOptions;
 
 /**
@@ -44,15 +45,15 @@ public function serve(
     /**
      * @api
      *
-     * @param string $file the file to upload (max 500 MB)
+     * @param string|FileParam $file the file to upload (max 500 MB)
      * @param string $fileName Original filename. Defaults to the uploaded file name if omitted
      * @param string $mimeType MIME type. Auto-detected from magic bytes if omitted
      * @param RequestOpts|null $requestOptions
      *
      * @throws APIException
      */
     public function upload(
-        string $file,
+        string|FileParam $file,
         ?string $fileName = null,
         ?string $mimeType = null,
         RequestOptions|array|null $requestOptions = null,

src/Services/AssetsRawService.php

@@ -14,6 +14,7 @@
 use BeeperDesktop\Client;
 use BeeperDesktop\Core\Contracts\BaseResponse;
 use BeeperDesktop\Core\Exceptions\APIException;
+use BeeperDesktop\Core\FileParam;
 use BeeperDesktop\RequestOptions;
 use BeeperDesktop\ServiceContracts\AssetsRawContract;
 
@@ -98,7 +99,7 @@ public function serve(
      * Upload a file to a temporary location using multipart/form-data. Returns an uploadID that can be referenced when sending messages with attachments.
      *
      * @param array{
-     *   file: string, fileName?: string, mimeType?: string
+     *   file: string|FileParam, fileName?: string, mimeType?: string
      * }|AssetUploadParams $params
      * @param RequestOpts|null $requestOptions
      *

src/Services/AssetsService.php

@@ -9,6 +9,7 @@
 use BeeperDesktop\Assets\AssetUploadResponse;
 use BeeperDesktop\Client;
 use BeeperDesktop\Core\Exceptions\APIException;
+use BeeperDesktop\Core\FileParam;
 use BeeperDesktop\Core\Util;
 use BeeperDesktop\RequestOptions;
 use BeeperDesktop\ServiceContracts\AssetsContract;
@@ -82,15 +83,15 @@ public function serve(
      *
      * Upload a file to a temporary location using multipart/form-data. Returns an uploadID that can be referenced when sending messages with attachments.
      *
-     * @param string $file the file to upload (max 500 MB)
+     * @param string|FileParam $file the file to upload (max 500 MB)
      * @param string $fileName Original filename. Defaults to the uploaded file name if omitted
      * @param string $mimeType MIME type. Auto-detected from magic bytes if omitted
      * @param RequestOpts|null $requestOptions
      *
      * @throws APIException
      */
     public function upload(
-        string $file,
+        string|FileParam $file,
         ?string $fileName = null,
         ?string $mimeType = null,
         RequestOptions|array|null $requestOptions = null,

tests/Services/AssetsTest.php

@@ -6,6 +6,7 @@
 use BeeperDesktop\Assets\AssetUploadBase64Response;
 use BeeperDesktop\Assets\AssetUploadResponse;
 use BeeperDesktop\Client;
+use BeeperDesktop\Core\FileParam;
 use BeeperDesktop\Core\Util;
 use PHPUnit\Framework\Attributes\CoversNothing;
 use PHPUnit\Framework\Attributes\Test;
@@ -72,7 +73,9 @@ public function testServeWithOptionalParams(): void
     #[Test]
     public function testUpload(): void
     {
-        $result = $this->client->assets->upload(file: 'file');
+        $result = $this->client->assets->upload(
+            file: FileParam::fromString('Example data', filename: uniqid('file-upload-', true)),
+        );
 
         // @phpstan-ignore-next-line method.alreadyNarrowedType
         $this->assertInstanceOf(AssetUploadResponse::class, $result);
@@ -82,9 +85,9 @@ public function testUpload(): void
     public function testUploadWithOptionalParams(): void
     {
         $result = $this->client->assets->upload(
-            file: 'file',
+            file: FileParam::fromString('Example data', filename: uniqid('file-upload-', true)),
             fileName: 'fileName',
-            mimeType: 'mimeType'
+            mimeType: 'mimeType',
         );
 
         // @phpstan-ignore-next-line method.alreadyNarrowedType