Merge pull request #17 from mozex/files-resource

Add Files API resource

Author: mozex

README.md

@@ -25,6 +25,7 @@ A community-maintained PHP SDK for the [Anthropic API](https://platform.claude.c
   - [Token Counting](https://mozex.dev/docs/anthropic-php/v1/usage/token-counting)
   - [Models](https://mozex.dev/docs/anthropic-php/v1/usage/models)
   - [Batches](https://mozex.dev/docs/anthropic-php/v1/usage/batches)
+  - [Files](https://mozex.dev/docs/anthropic-php/v1/usage/files)
   - [Completions](https://mozex.dev/docs/anthropic-php/v1/usage/completions)
 - Reference
   - [Configuration](https://mozex.dev/docs/anthropic-php/v1/reference/configuration)

docs/reference/testing.md

@@ -51,6 +51,9 @@ Every response class has a `fake()` method:
 | `Batches\BatchListResponse::fake()` | Batch list |
 | `Batches\BatchResultResponse::fake()` | Batch results |
 | `Batches\DeletedBatchResponse::fake()` | Batch delete |
+| `Files\FileResponse::fake()` | Files upload/retrieve metadata |
+| `Files\FileListResponse::fake()` | Files list |
+| `Files\DeletedFileResponse::fake()` | Files delete |
 
 ## Overriding response fields
 

docs/usage/files.md

@@ -0,0 +1,187 @@
+---
+title: Files
+weight: 10
+---
+
+The Files API lets you upload documents once and reference them by `file_id` in any later Messages call. Anthropic currently flags this endpoint as beta on their side; the SDK sends the required header for you, so there's nothing to configure.
+
+## Uploading a file
+
+Pass any readable resource under the `file` key. The client streams it to `/v1/files` as `multipart/form-data` and gives you back the metadata:
+
+```php
+$response = $client->files()->upload([
+    'file' => fopen('/path/to/document.pdf', 'r'),
+]);
+
+$response->id;           // 'file_011CNha8iCJcU1wXNR6q4V8w'
+$response->type;         // 'file'
+$response->filename;     // 'document.pdf'
+$response->mimeType;     // 'application/pdf'
+$response->sizeBytes;    // 1024000
+$response->createdAt;    // '2025-01-01T00:00:00Z'
+$response->downloadable; // false
+```
+
+Supported types map to content blocks like this:
+
+| File type | MIME | Use it in |
+|-----------|------|-----------|
+| PDF | `application/pdf` | `document` block |
+| Plain text | `text/plain` | `document` block |
+| Images | `image/jpeg`, `image/png`, `image/gif`, `image/webp` | `image` block |
+| Code execution inputs | varies (CSV, XLSX, JSON, etc.) | `container_upload` block |
+
+Max file size is 500 MB. The storage ceiling is 500 GB per organization.
+
+Keep the `id` wherever you'd normally keep a file path. You'll hand it back to the Messages API as a `file_id`.
+
+## Referencing a file in a message
+
+Once you have an `id`, drop it into a content block. For a PDF or text file, that's a `document` block with `source.type` set to `file`. Note the `betas` key on the Messages call: the Messages endpoint only accepts `source.type: file` when the `files-api-2025-04-14` beta header is on that specific request. The SDK auto-injects it on `$client->files()` calls but doesn't know whether any given Messages call references a file_id, so you pass it explicitly here:
+
+```php
+$response = $client->messages()->create([
+    'model' => 'claude-opus-4-6',
+    'max_tokens' => 1024,
+    'betas' => ['files-api-2025-04-14'],
+    'messages' => [
+        [
+            'role' => 'user',
+            'content' => [
+                ['type' => 'text', 'text' => 'Summarise this document.'],
+                [
+                    'type' => 'document',
+                    'source' => [
+                        'type' => 'file',
+                        'file_id' => 'file_011CNha8iCJcU1wXNR6q4V8w',
+                    ],
+                ],
+            ],
+        ],
+    ],
+]);
+```
+
+If every Messages call in your app references uploaded files, skip the per-call `betas` and set the header globally on the factory instead:
+
+```php
+$client = Anthropic::factory()
+    ->withApiKey('your-api-key')
+    ->withHttpHeader('anthropic-beta', 'files-api-2025-04-14')
+    ->make();
+```
+
+For images, swap `document` for `image`:
+
+```php
+[
+    'type' => 'image',
+    'source' => [
+        'type' => 'file',
+        'file_id' => 'file_011CPMxVD3fHLUhvTqtsQA5w',
+    ],
+]
+```
+
+Same file can be referenced from any number of requests, which is the point of the whole API.
+
+## Listing files
+
+`list()` returns a cursor-paginated page of files in the workspace tied to your API key:
+
+```php
+$response = $client->files()->list(['limit' => 20]);
+
+foreach ($response->data as $file) {
+    $file->id;
+    $file->filename;
+    $file->sizeBytes;
+}
+
+$response->firstId; // 'file_011CNha8iCJcU1wXNR6q4V8w'
+$response->lastId;  // 'file_011CPMxVD3fHLUhvTqtsQA5w'
+$response->hasMore; // false
+```
+
+Pagination works like the Models and Batches endpoints. `limit` goes up to 1000 and defaults to 20. Use `after_id` with the previous page's `lastId` to walk forward, or `before_id` with `firstId` to walk backward:
+
+```php
+$page1 = $client->files()->list(['limit' => 100]);
+
+while ($page1->hasMore) {
+    $page1 = $client->files()->list([
+        'limit' => 100,
+        'after_id' => $page1->lastId,
+    ]);
+}
+```
+
+There's also an optional `scope_id` parameter to filter by session scope, which matters if you're using files inside a session.
+
+## Retrieving metadata
+
+`retrieveMetadata()` is a GET on a single file. Same response shape as upload:
+
+```php
+$file = $client->files()->retrieveMetadata('file_011CNha8iCJcU1wXNR6q4V8w');
+
+$file->filename;     // 'document.pdf'
+$file->mimeType;     // 'application/pdf'
+$file->sizeBytes;    // 1024000
+$file->downloadable; // false
+```
+
+For session-scoped files (created by the code execution tool or Skills API), `scope` tells you where it came from:
+
+```php
+$file->scope?->type; // 'session'
+$file->scope?->id;   // 'session_01AbCdEfGhIjKlMnOpQrStUv'
+```
+
+## Downloading a file
+
+Only files created by the [code execution tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool) or [Skills](https://platform.claude.com/docs/en/build-with-claude/skills-guide) can be downloaded. Files you upload yourself can't be read back. `downloadable` on the metadata tells you which is which.
+
+`download()` returns the raw bytes as a string:
+
+```php
+$bytes = $client->files()->download('file_011CPMxVD3fHLUhvTqtsQA5w');
+
+file_put_contents('output.png', $bytes);
+```
+
+For a large download, wrap the write in something that writes to disk as it goes rather than holding the whole thing in memory. If you're building on top of Guzzle or Symfony, you can swap the transporter out via the factory and stream directly.
+
+## Deleting a file
+
+```php
+$response = $client->files()->delete('file_011CNha8iCJcU1wXNR6q4V8w');
+
+$response->id;   // 'file_011CNha8iCJcU1wXNR6q4V8w'
+$response->type; // 'file_deleted'
+```
+
+Deletes are permanent. Files still being referenced in an in-flight Messages call may keep working briefly, but new requests using that `file_id` will fail with a 404.
+
+## Errors to expect
+
+The common ones, from the [Anthropic docs](https://platform.claude.com/docs/en/build-with-claude/files):
+
+- `404` if the `file_id` doesn't exist or belongs to another workspace.
+- `400` if you use the wrong block type for the file (e.g., image file inside a `document` block).
+- `400` if the filename breaks the rules (1 to 255 characters, no `< > : " | ? * \ /` or control characters).
+- `413` if the file is over 500 MB.
+- `403` if your organization is over the 500 GB total.
+
+All of these surface as `Anthropic\Exceptions\ErrorException` with the usual `message` and `type` on the payload.
+
+## Rate limits
+
+Anthropic caps file-related calls at roughly 100 per minute. Normal messages and token usage rate limits still apply on top.
+
+File operations themselves (upload, list, retrieve, download, delete) are free. Tokens are only charged when the file is actually used inside a Messages call.
+
+---
+
+For the full API reference, see the [Files API guide](https://platform.claude.com/docs/en/build-with-claude/files) and the [Files endpoint reference](https://platform.claude.com/docs/en/api/files-list) on the Anthropic docs.

src/Client.php

@@ -8,6 +8,7 @@
 use Anthropic\Contracts\TransporterContract;
 use Anthropic\Resources\Batches;
 use Anthropic\Resources\Completions;
+use Anthropic\Resources\Files;
 use Anthropic\Resources\Messages;
 use Anthropic\Resources\Models;
 
@@ -61,4 +62,14 @@ public function batches(): Batches
     {
         return new Batches($this->transporter);
     }
+
+    /**
+     * Upload, list, retrieve, download, and delete files.
+     *
+     * @see https://platform.claude.com/docs/en/build-with-claude/files
+     */
+    public function files(): Files
+    {
+        return new Files($this->transporter);
+    }
 }

src/Contracts/ClientContract.php

@@ -4,6 +4,7 @@
 
 use Anthropic\Contracts\Resources\BatchesContract;
 use Anthropic\Contracts\Resources\CompletionsContract;
+use Anthropic\Contracts\Resources\FilesContract;
 use Anthropic\Contracts\Resources\MessagesContract;
 use Anthropic\Contracts\Resources\ModelsContract;
 
@@ -37,4 +38,11 @@ public function models(): ModelsContract;
      * @see https://platform.claude.com/docs/en/api/messages/batches/create
      */
     public function batches(): BatchesContract;
+
+    /**
+     * Upload, list, retrieve, download, and delete files.
+     *
+     * @see https://platform.claude.com/docs/en/build-with-claude/files
+     */
+    public function files(): FilesContract;
 }

src/Contracts/Resources/FilesContract.php

@@ -0,0 +1,49 @@
+<?php
+
+namespace Anthropic\Contracts\Resources;
+
+use Anthropic\Responses\Files\DeletedFileResponse;
+use Anthropic\Responses\Files\FileListResponse;
+use Anthropic\Responses\Files\FileResponse;
+
+interface FilesContract
+{
+    /**
+     * Uploads a file to be referenced in future API calls.
+     *
+     * @see https://platform.claude.com/docs/en/api/files-create
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function upload(array $parameters): FileResponse;
+
+    /**
+     * Lists files belonging to the workspace of the API key.
+     *
+     * @see https://platform.claude.com/docs/en/api/files-list
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function list(array $parameters = []): FileListResponse;
+
+    /**
+     * Retrieves metadata for a specific file.
+     *
+     * @see https://platform.claude.com/docs/en/api/files-metadata
+     */
+    public function retrieveMetadata(string $fileId): FileResponse;
+
+    /**
+     * Downloads the contents of a file created by skills or the code execution tool.
+     *
+     * @see https://platform.claude.com/docs/en/api/files-content
+     */
+    public function download(string $fileId): string;
+
+    /**
+     * Deletes a file.
+     *
+     * @see https://platform.claude.com/docs/en/api/files-delete
+     */
+    public function delete(string $fileId): DeletedFileResponse;
+}

src/Resources/Files.php

@@ -0,0 +1,98 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Anthropic\Resources;
+
+use Anthropic\Contracts\Resources\FilesContract;
+use Anthropic\Responses\Files\DeletedFileResponse;
+use Anthropic\Responses\Files\FileListResponse;
+use Anthropic\Responses\Files\FileResponse;
+use Anthropic\ValueObjects\Transporter\Payload;
+use Anthropic\ValueObjects\Transporter\Response;
+
+final class Files implements FilesContract
+{
+    use Concerns\Transportable;
+
+    /**
+     * The beta header required for every Files API request. Auto-injected on every method.
+     */
+    private const BETA = 'files-api-2025-04-14';
+
+    /**
+     * Uploads a file to be referenced in future API calls.
+     *
+     * @see https://platform.claude.com/docs/en/api/files-create
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function upload(array $parameters): FileResponse
+    {
+        $payload = Payload::upload('files', $parameters)->withBetas([self::BETA]);
+
+        /** @var Response<array{id: string, type: string, filename: string, mime_type: string, size_bytes: int, created_at: string, downloadable?: bool, scope?: array{id: string, type: string}}> $response */
+        $response = $this->transporter->requestObject($payload);
+
+        return FileResponse::from($response->data(), $response->meta());
+    }
+
+    /**
+     * Lists files belonging to the workspace of the API key.
+     *
+     * @see https://platform.claude.com/docs/en/api/files-list
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function list(array $parameters = []): FileListResponse
+    {
+        $payload = Payload::list('files', $parameters)->withBetas([self::BETA]);
+
+        /** @var Response<array{data: array<int, array{id: string, type: string, filename: string, mime_type: string, size_bytes: int, created_at: string, downloadable?: bool, scope?: array{id: string, type: string}}>, first_id?: ?string, last_id?: ?string, has_more?: bool}> $response */
+        $response = $this->transporter->requestObject($payload);
+
+        return FileListResponse::from($response->data(), $response->meta());
+    }
+
+    /**
+     * Retrieves metadata for a specific file.
+     *
+     * @see https://platform.claude.com/docs/en/api/files-metadata
+     */
+    public function retrieveMetadata(string $fileId): FileResponse
+    {
+        $payload = Payload::retrieve('files', $fileId)->withBetas([self::BETA]);
+
+        /** @var Response<array{id: string, type: string, filename: string, mime_type: string, size_bytes: int, created_at: string, downloadable?: bool, scope?: array{id: string, type: string}}> $response */
+        $response = $this->transporter->requestObject($payload);
+
+        return FileResponse::from($response->data(), $response->meta());
+    }
+
+    /**
+     * Downloads the contents of a file created by skills or the code execution tool.
+     *
+     * @see https://platform.claude.com/docs/en/api/files-content
+     */
+    public function download(string $fileId): string
+    {
+        $payload = Payload::retrieveContent('files', $fileId)->withBetas([self::BETA]);
+
+        return $this->transporter->requestContent($payload);
+    }
+
+    /**
+     * Deletes a file.
+     *
+     * @see https://platform.claude.com/docs/en/api/files-delete
+     */
+    public function delete(string $fileId): DeletedFileResponse
+    {
+        $payload = Payload::delete('files', $fileId)->withBetas([self::BETA]);
+
+        /** @var Response<array{id: string, type: string}> $response */
+        $response = $this->transporter->requestObject($payload);
+
+        return DeletedFileResponse::from($response->data(), $response->meta());
+    }
+}