diff --git a/.github/workflows/run-tests.yml b/.github/workflows/run-tests.yml
index 79c4b44..7e31e83 100644
--- a/.github/workflows/run-tests.yml
+++ b/.github/workflows/run-tests.yml
@@ -33,6 +33,9 @@ jobs:
       - name: Install dependencies
         run: composer update --${{ matrix.stability }} --prefer-dist --no-interaction
 
+      - name: Run PHPStan
+        run: composer analyse
+
       - name: Execute tests
         run: vendor/bin/pest --coverage --coverage-clover=coverage.xml
 
diff --git a/README.md b/README.md
index 49c0db7..a130e13 100644
--- a/README.md
+++ b/README.md
@@ -167,15 +167,28 @@ $transport = TransportBuilder::make()
             maxDelayMs: 30000,       // Cap at 30 seconds
             useJitter: true          // Add randomization
         ),
-        condition: RetryCondition::default()
+        condition: (new RetryCondition())
             ->onExceptions([NetworkException::class])
     )
     ->build();
 
 // Retries automatically with exponential backoff + jitter
 $response = $transport->get('/unreliable-endpoint')->send();
+
+// Or use default retry condition (retries on any exception)
+$transport = TransportBuilder::make()
+    ->withRetries(
+        maxRetries: 3,
+        condition: RetryCondition::default() // Retries on ANY exception
+    )
+    ->build();
 ```
 
+**Retry Conditions:**
+- `RetryCondition::default()` - Retries on any exception
+- `(new RetryCondition())->onExceptions([...])` - Retry only specific exceptions
+- `(new RetryCondition())->onStatusCodes([500, 502, 503])` - Retry specific HTTP status codes
+
 ### Custom Middleware
 
 ```php
@@ -290,8 +303,26 @@ $builder->addField('username', 'john_doe')
 $response = $transport->post('/api/upload')
     ->withMultipartBuilder($builder)
     ->send();
+
+// Memory-efficient streaming for large files
+use Farzai\Transport\Multipart\StreamingMultipartBuilder;
+
+$streamBuilder = new StreamingMultipartBuilder();
+$stream = $streamBuilder
+    ->addFile('video', '/path/to/large-video.mp4', 'video.mp4')
+    ->addField('title', 'My Video')
+    ->build();
+
+// Streams file without loading entire content into memory
+$response = $transport->request()
+    ->withBody($stream)
+    ->withHeader('Content-Type', $streamBuilder->getContentType())
+    ->post('/upload')
+    ->send();
 ```
 
+**Note:** The library automatically selects `StreamingMultipartBuilder` for large files (>1MB by default) to optimize memory usage. You can also manually use it for memory-efficient uploads of any size.
+
 ### Cookie Management
 
 ```php
@@ -345,6 +376,67 @@ $newJar = new CookieJar();
 $newJar->fromArray(json_decode(file_get_contents('cookies.json'), true));
 ```
 
+**Performance Note:** The cookie management system automatically optimizes for different workloads. For applications with many cookies (50+), it uses indexed collections with O(1) domain lookups. For smaller cookie counts, it uses simpler collections to minimize overhead.
+
+### Event Monitoring
+
+Monitor HTTP requests lifecycle with event listeners:
+
+```php
+use Farzai\Transport\Events\RequestSendingEvent;
+use Farzai\Transport\Events\ResponseReceivedEvent;
+use Farzai\Transport\Events\RequestFailedEvent;
+use Farzai\Transport\Events\RetryAttemptEvent;
+
+$transport = TransportBuilder::make()
+    ->withBaseUri('https://api.example.com')
+    // Track successful responses
+    ->addEventListener(ResponseReceivedEvent::class, function ($event) {
+        printf(
+            "[SUCCESS] %s %s → %d (%.2fms)\n",
+            $event->getMethod(),
+            $event->getUri(),
+            $event->getStatusCode(),
+            $event->getDuration()
+        );
+    })
+    // Track failed requests
+    ->addEventListener(RequestFailedEvent::class, function ($event) {
+        printf(
+            "[ERROR] %s %s failed: %s\n",
+            $event->getMethod(),
+            $event->getUri(),
+            $event->getExceptionMessage()
+        );
+    })
+    // Monitor retry attempts
+    ->addEventListener(RetryAttemptEvent::class, function ($event) {
+        printf(
+            "[RETRY] Attempt %d/%d (delay: %dms)\n",
+            $event->getAttemptNumber(),
+            $event->getMaxAttempts(),
+            $event->getDelay()
+        );
+    })
+    ->withRetries(3)
+    ->build();
+
+// Events are automatically dispatched during request lifecycle
+$response = $transport->get('/api/endpoint')->send();
+```
+
+**Available Events:**
+- `RequestSendingEvent` - Before a request is sent
+- `ResponseReceivedEvent` - After successful response (includes duration metrics)
+- `RequestFailedEvent` - When a request fails with exception details
+- `RetryAttemptEvent` - Before each retry attempt with delay information
+
+**Use Cases:**
+- Performance monitoring and metrics collection
+- Logging and debugging request/response cycles
+- Custom retry notifications
+- Request/response instrumentation
+
 ### Error Handling
 
 ```php
@@ -442,15 +534,15 @@ $response = ResponseBuilder::create()
 
 ## Documentation
 
-- **[Architecture Guide](docs/architecture.md)** - Deep dive into design patterns and internal architecture
-- **[Migration Guide](docs/migration-from-guzzle.md)** - Migrating from Guzzle or v1.x
 - **[Examples](examples/)** - Practical usage examples:
   - [Basic Usage](examples/basic-usage.php)
   - [Custom HTTP Clients](examples/custom-client.php)
   - [Advanced Retry Logic](examples/advanced-retry.php)
   - [Custom Middleware](examples/middleware-example.php)
   - [File Upload](examples/file-upload.php)
+  - [Streaming Upload](examples/streaming-upload.php)
   - [Cookie Session Management](examples/cookie-session.php)
+  - [Event Monitoring](examples/event-monitoring.php)
 
 ## Architecture
 
@@ -522,7 +614,7 @@ Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed re
 
 ## Contributing
 
-Please see [CONTRIBUTING](https://github.com/farzai/.github/blob/main/CONTRIBUTING.md) for details.
+Please see [CONTRIBUTING](docs/contributing/CONTRIBUTING.md) for details.
 
 ## Security Vulnerabilities
 
diff --git a/composer.json b/composer.json
index 1509517..e2ee4e5 100644
--- a/composer.json
+++ b/composer.json
@@ -1,9 +1,21 @@
 {
     "name": "farzai/transport",
-    "description": "A HTTP client for Farzai Package",
+    "description": "A modern, PSR-compliant HTTP client for PHP with middleware architecture, advanced retry strategies, and fluent API for building requests",
     "keywords": [
-        "farzai",
-        "transport"
+        "http",
+        "http-client",
+        "psr-7",
+        "psr-18",
+        "rest-client",
+        "api-client",
+        "middleware",
+        "retry",
+        "cookie",
+        "multipart",
+        "form-data",
+        "file-upload",
+        "fluent-api",
+        "psr"
     ],
     "homepage": "https://github.com/farzai/transport-php",
     "license": "MIT",
@@ -48,7 +60,9 @@
     "scripts": {
         "test": "vendor/bin/pest",
         "test-coverage": "vendor/bin/pest --coverage",
-        "format": "vendor/bin/pint"
+        "format": "vendor/bin/pint",
+        "analyse": "vendor/bin/phpstan analyse --memory-limit=2G",
+        "analyse:baseline": "vendor/bin/phpstan analyse --memory-limit=2G --generate-baseline"
     },
     "config": {
         "sort-packages": true,
diff --git a/examples/event-monitoring.php b/examples/event-monitoring.php
new file mode 100644
index 0000000..58f26b1
--- /dev/null
+++ b/examples/event-monitoring.php
@@ -0,0 +1,49 @@
+<?php
+
+require __DIR__.'/../vendor/autoload.php';
+
+use Farzai\Transport\Events\RequestFailedEvent;
+use Farzai\Transport\Events\ResponseReceivedEvent;
+use Farzai\Transport\Events\RetryAttemptEvent;
+use Farzai\Transport\TransportBuilder;
+
+echo "Event Monitoring Example\n";
+echo "========================\n\n";
+
+// Create transport with event listeners
+$transport = TransportBuilder::make()
+    ->withBaseUri('https://httpbin.org')
+    ->addEventListener(ResponseReceivedEvent::class, function ($event) {
+        printf(
+            "[SUCCESS] %s %s → %d (%.2fms)\n",
+            $event->getMethod(),
+            $event->getUri(),
+            $event->getStatusCode(),
+            $event->getDuration()
+        );
+    })
+    ->addEventListener(RequestFailedEvent::class, function ($event) {
+        printf(
+            "[ERROR] %s %s failed: %s\n",
+            $event->getMethod(),
+            $event->getUri(),
+            $event->getExceptionMessage()
+        );
+    })
+    ->addEventListener(RetryAttemptEvent::class, function ($event) {
+        printf(
+            "[RETRY] Attempt %d/%d (delay: %dms)\n",
+            $event->getAttemptNumber(),
+            $event->getMaxAttempts(),
+            $event->getDelay()
+        );
+    })
+    ->withRetries(3)
+    ->build();
+
+// Make request
+echo "Making GET request...\n";
+$response = $transport->get('/get?foo=bar')->send();
+
+echo "\nResponse Status: ".$response->statusCode()."\n";
+echo "Response successful!\n";
diff --git a/examples/streaming-upload.php b/examples/streaming-upload.php
new file mode 100644
index 0000000..7766094
--- /dev/null
+++ b/examples/streaming-upload.php
@@ -0,0 +1,61 @@
+<?php
+
+require __DIR__.'/../vendor/autoload.php';
+
+use Farzai\Transport\Multipart\MultipartBuilderFactory;
+use Farzai\Transport\Multipart\StreamingMultipartBuilder;
+use Farzai\Transport\TransportBuilder;
+
+echo "Streaming Upload Example\n";
+echo "========================\n\n";
+
+// Create a test file
+$testFile = sys_get_temp_dir().'/test-upload.txt';
+file_put_contents($testFile, str_repeat('Large file content... ', 1000));
+$fileSize = filesize($testFile);
+
+echo "Test file: {$testFile}\n";
+echo 'File size: '.number_format($fileSize)." bytes\n\n";
+
+// Method 1: Manual streaming builder
+echo "Method 1: Manual Streaming Builder\n";
+echo "-----------------------------------\n";
+
+$transport = TransportBuilder::make()
+    ->withBaseUri('https://httpbin.org')
+    ->build();
+
+$builder = new StreamingMultipartBuilder;
+$stream = $builder
+    ->addFile('file', $testFile, 'upload.txt', 'text/plain')
+    ->addField('description', 'Streaming upload test')
+    ->addField('timestamp', (string) time())
+    ->build();
+
+echo 'Memory before: '.number_format(memory_get_usage(true) / 1024)." KB\n";
+
+$response = $transport->post('/post')
+    ->withBody($stream)
+    ->withHeader('Content-Type', $builder->getContentType())
+    ->send();
+
+echo 'Memory after:  '.number_format(memory_get_usage(true) / 1024)." KB\n";
+echo 'Status: '.$response->statusCode()."\n\n";
+
+// Method 2: Auto-selection with factory
+echo "Method 2: Auto-Selection Factory\n";
+echo "---------------------------------\n";
+
+$parts = [
+    ['name' => 'file', 'contents' => $testFile, 'filename' => 'upload.txt'],
+    ['name' => 'description', 'contents' => 'Auto-selected builder'],
+];
+
+$builder = MultipartBuilderFactory::create(null, $parts);
+echo 'Selected builder: '.($builder instanceof StreamingMultipartBuilder ? 'Streaming' : 'Standard')."\n";
+echo 'Threshold: '.MultipartBuilderFactory::getDefaultThreshold()." bytes\n\n";
+
+// Cleanup
+unlink($testFile);
+
+echo "Example complete!\n";
diff --git a/phpstan.neon b/phpstan.neon
new file mode 100644
index 0000000..199d230
--- /dev/null
+++ b/phpstan.neon
@@ -0,0 +1,41 @@
+parameters:
+    level: 8
+    paths:
+        - src
+    excludePaths:
+        - tests
+        - vendor
+
+    # Strict rules for better type safety
+    checkGenericClassInNonGenericObjectType: true
+    checkMissingVarTagTypehint: true
+    treatPhpDocTypesAsCertain: false
+
+    # Exception rules
+    exceptions:
+        check:
+            missingCheckedExceptionInThrows: true
+            tooWideThrowType: true
+        implicitThrows: true
+        checkedExceptionClasses:
+            - Farzai\Transport\Exceptions\TransportException
+
+    # Additional checks
+    reportUnmatchedIgnoredErrors: true
+    reportMaybesInMethodSignatures: true
+    reportStaticMethodSignatures: true
+
+    # Type coverage (optional - uncomment to track type coverage)
+    # type_coverage:
+    #     param_type: 100
+    #     return_type: 100
+    #     property_type: 100
+
+    # Ignore specific errors if needed (add as you encounter false positives)
+    ignoreErrors:
+        # Add patterns here if needed
+        # - '#PHPDoc tag @var for variable#'
+
+    # Bootstrap file if needed
+    # bootstrapFiles:
+    #     - tests/bootstrap.php
diff --git a/src/Contracts/ResponseInterface.php b/src/Contracts/ResponseInterface.php
index f3fdc3d..401f05d 100644
--- a/src/Contracts/ResponseInterface.php
+++ b/src/Contracts/ResponseInterface.php
@@ -21,6 +21,8 @@ public function body(): string;
 
     /**
      * Return the response headers.
+     *
+     * @return array<string, array<string>>
      */
     public function headers(): array;
 
@@ -57,7 +59,7 @@ public function toArray(): array;
      *
      * @throws \Psr\Http\Client\ClientExceptionInterface
      */
-    public function throw(?callable $callback = null);
+    public function throw(?callable $callback = null): static;
 
     /**
      * Return the psr request.
diff --git a/src/Cookie/AdaptiveCookieCollection.php b/src/Cookie/AdaptiveCookieCollection.php
new file mode 100644
index 0000000..f949515
--- /dev/null
+++ b/src/Cookie/AdaptiveCookieCollection.php
@@ -0,0 +1,295 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Farzai\Transport\Cookie;
+
+/**
+ * Adaptive cookie collection that automatically upgrades from simple to indexed.
+ *
+ * Design Pattern: Adapter Pattern + Strategy Pattern
+ * - Wraps underlying collection implementation
+ * - Automatically switches strategy when threshold reached
+ * - Provides transparent upgrade without user intervention
+ *
+ * Lifecycle:
+ * 1. Starts as SimpleCookieCollection (low overhead)
+ * 2. Monitors cookie count on each add()
+ * 3. Upgrades to IndexedCookieCollection when threshold reached
+ * 4. All subsequent operations use indexed collection
+ *
+ * Use Case:
+ * - When cookie count is unpredictable
+ * - When you want automatic optimization
+ * - When you want to start light and scale up
+ *
+ * @example
+ * ```php
+ * $collection = new AdaptiveCookieCollection(threshold: 50);
+ *
+ * // Starts as SimpleCookieCollection
+ * for ($i = 0; $i < 45; $i++) {
+ *     $collection->add($cookie); // Still simple
+ * }
+ *
+ * // Auto-upgrades to IndexedCookieCollection
+ * $collection->add($cookie); // Triggers upgrade at cookie #50
+ *
+ * // Now using indexed collection
+ * $matches = $collection->findForUrl($url); // O(1) lookup
+ * ```
+ */
+final class AdaptiveCookieCollection implements CookieCollectionInterface
+{
+    /**
+     * Underlying collection implementation.
+     */
+    private CookieCollectionInterface $collection;
+
+    /**
+     * Threshold for upgrading to indexed collection.
+     */
+    private int $threshold;
+
+    /**
+     * Whether collection has been upgraded.
+     */
+    private bool $upgraded = false;
+
+    /**
+     * Create a new adaptive cookie collection.
+     *
+     * @param  int  $threshold  Cookie count threshold for upgrade (default 50)
+     * @param  CookieCollectionInterface|null  $initialCollection  Optional initial collection
+     */
+    public function __construct(
+        int $threshold = CookieCollectionFactory::DEFAULT_THRESHOLD,
+        ?CookieCollectionInterface $initialCollection = null
+    ) {
+        $this->threshold = max(1, $threshold);
+        $this->collection = $initialCollection ?? new SimpleCookieCollection;
+
+        // Check if initial collection is already indexed
+        $this->upgraded = $this->collection instanceof IndexedCookieCollection;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function add(Cookie $cookie): void
+    {
+        $this->collection->add($cookie);
+
+        // Check if we should upgrade
+        $this->maybeUpgrade();
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function remove(string $identifier): void
+    {
+        $this->collection->remove($identifier);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function get(string $identifier): ?Cookie
+    {
+        return $this->collection->get($identifier);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function findForUrl(string $url, bool $isSecure): array
+    {
+        return $this->collection->findForUrl($url, $isSecure);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function all(): array
+    {
+        return $this->collection->all();
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function count(): int
+    {
+        return $this->collection->count();
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function isEmpty(): bool
+    {
+        return $this->collection->isEmpty();
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function clear(): void
+    {
+        $this->collection->clear();
+
+        // Downgrade back to simple after clear
+        if ($this->upgraded) {
+            $this->collection = new SimpleCookieCollection;
+            $this->upgraded = false;
+        }
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function removeExpired(): int
+    {
+        $removed = $this->collection->removeExpired();
+
+        // Check if we should downgrade after removing cookies
+        $this->maybeDowngrade();
+
+        return $removed;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getType(): string
+    {
+        return $this->collection->getType().' (Adaptive)';
+    }
+
+    /**
+     * Check if the collection has been upgraded.
+     *
+     * @return bool True if upgraded to indexed, false if still simple
+     */
+    public function isUpgraded(): bool
+    {
+        return $this->upgraded;
+    }
+
+    /**
+     * Get the current threshold.
+     *
+     * @return int Threshold value
+     */
+    public function getThreshold(): int
+    {
+        return $this->threshold;
+    }
+
+    /**
+     * Get the underlying collection implementation.
+     *
+     * @return CookieCollectionInterface The wrapped collection
+     */
+    public function getUnderlyingCollection(): CookieCollectionInterface
+    {
+        return $this->collection;
+    }
+
+    /**
+     * Force upgrade to indexed collection.
+     *
+     * Useful for testing or when you know you'll need indexed performance.
+     */
+    public function forceUpgrade(): void
+    {
+        if ($this->upgraded) {
+            return; // Already upgraded
+        }
+
+        $this->upgrade();
+    }
+
+    /**
+     * Force downgrade to simple collection.
+     *
+     * Useful when cookie count decreases significantly.
+     */
+    public function forceDowngrade(): void
+    {
+        if (! $this->upgraded) {
+            return; // Already simple
+        }
+
+        $this->downgrade();
+    }
+
+    /**
+     * Check if upgrade is needed and perform it.
+     */
+    private function maybeUpgrade(): void
+    {
+        if ($this->upgraded) {
+            return; // Already upgraded
+        }
+
+        if ($this->collection->count() >= $this->threshold) {
+            $this->upgrade();
+        }
+    }
+
+    /**
+     * Check if downgrade is beneficial and perform it.
+     *
+     * Downgrades if cookie count drops significantly below threshold (< 50% of threshold).
+     */
+    private function maybeDowngrade(): void
+    {
+        if (! $this->upgraded) {
+            return; // Already simple
+        }
+
+        // Downgrade if count drops below 50% of threshold
+        $downgradeThreshold = (int) ($this->threshold * 0.5);
+        if ($this->collection->count() < $downgradeThreshold) {
+            $this->downgrade();
+        }
+    }
+
+    /**
+     * Upgrade from simple to indexed collection.
+     */
+    private function upgrade(): void
+    {
+        // Create new indexed collection
+        $indexed = new IndexedCookieCollection;
+
+        // Migrate all cookies
+        foreach ($this->collection->all() as $cookie) {
+            $indexed->add($cookie);
+        }
+
+        // Switch to indexed collection
+        $this->collection = $indexed;
+        $this->upgraded = true;
+    }
+
+    /**
+     * Downgrade from indexed to simple collection.
+     */
+    private function downgrade(): void
+    {
+        // Create new simple collection
+        $simple = new SimpleCookieCollection;
+
+        // Migrate all cookies
+        foreach ($this->collection->all() as $cookie) {
+            $simple->add($cookie);
+        }
+
+        // Switch to simple collection
+        $this->collection = $simple;
+        $this->upgraded = false;
+    }
+}
diff --git a/src/Cookie/Cookie.php b/src/Cookie/Cookie.php
index ef506e9..521226f 100644
--- a/src/Cookie/Cookie.php
+++ b/src/Cookie/Cookie.php
@@ -22,7 +22,7 @@ final class Cookie
 
     private readonly ?string $domain;
 
-    private readonly ?string $path;
+    private readonly string $path;
 
     private readonly bool $secure;
 
diff --git a/src/Cookie/CookieCollectionFactory.php b/src/Cookie/CookieCollectionFactory.php
new file mode 100644
index 0000000..17c359c
--- /dev/null
+++ b/src/Cookie/CookieCollectionFactory.php
@@ -0,0 +1,192 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Farzai\Transport\Cookie;
+
+/**
+ * Factory for creating cookie collections with automatic strategy selection.
+ *
+ * Design Pattern: Factory Pattern + Strategy Pattern
+ * - Creates appropriate collection based on cookie count
+ * - Encapsulates strategy selection logic
+ * - Provides consistent interface
+ *
+ * Selection Strategy:
+ * - < 50 cookies: SimpleCookieCollection (linear search, lower overhead)
+ * - >= 50 cookies: IndexedCookieCollection (hash map, faster lookups)
+ *
+ * Rationale for 50 cookie threshold:
+ * - Benchmarks show indexed lookup becomes beneficial at ~50 cookies
+ * - Below 50: Overhead of indexing outweighs benefits
+ * - Above 50: O(1) lookups significantly faster than O(n)
+ *
+ * @example
+ * ```php
+ * // Auto-select based on count
+ * $collection = CookieCollectionFactory::create(45); // SimpleCookieCollection
+ * $collection = CookieCollectionFactory::create(100); // IndexedCookieCollection
+ *
+ * // Force specific implementation
+ * $collection = CookieCollectionFactory::createSimple();
+ * $collection = CookieCollectionFactory::createIndexed();
+ *
+ * // With custom threshold
+ * $collection = CookieCollectionFactory::create(75, threshold: 100);
+ * ```
+ */
+final class CookieCollectionFactory
+{
+    /**
+     * Default threshold for switching to indexed collection (50 cookies).
+     *
+     * Based on performance benchmarks showing indexed lookup
+     * becomes beneficial around 50 cookies.
+     */
+    public const DEFAULT_THRESHOLD = 50;
+
+    /**
+     * Create a cookie collection, auto-selecting implementation based on expected count.
+     *
+     * @param  int  $expectedCount  Expected number of cookies
+     * @param  int  $threshold  Cookie count threshold for indexed collection
+     * @return CookieCollectionInterface The cookie collection
+     */
+    public static function create(
+        int $expectedCount = 0,
+        int $threshold = self::DEFAULT_THRESHOLD
+    ): CookieCollectionInterface {
+        if ($expectedCount >= $threshold) {
+            return new IndexedCookieCollection;
+        }
+
+        return new SimpleCookieCollection;
+    }
+
+    /**
+     * Create a simple (non-indexed) cookie collection.
+     *
+     * Use for small cookie counts or when memory is more critical than speed.
+     */
+    public static function createSimple(): SimpleCookieCollection
+    {
+        return new SimpleCookieCollection;
+    }
+
+    /**
+     * Create an indexed cookie collection.
+     *
+     * Use for large cookie counts or when lookup speed is critical.
+     */
+    public static function createIndexed(): IndexedCookieCollection
+    {
+        return new IndexedCookieCollection;
+    }
+
+    /**
+     * Get the recommended collection type for a given cookie count.
+     *
+     * @param  int  $count  Cookie count
+     * @param  int  $threshold  Threshold for indexed collection
+     * @return class-string<CookieCollectionInterface> Collection class name
+     */
+    public static function getRecommendedType(
+        int $count,
+        int $threshold = self::DEFAULT_THRESHOLD
+    ): string {
+        if ($count >= $threshold) {
+            return IndexedCookieCollection::class;
+        }
+
+        return SimpleCookieCollection::class;
+    }
+
+    /**
+     * Check if indexed collection is recommended for a given count.
+     *
+     * @param  int  $count  Cookie count
+     * @param  int  $threshold  Threshold for indexed collection
+     * @return bool True if indexed recommended, false otherwise
+     */
+    public static function shouldUseIndexed(
+        int $count,
+        int $threshold = self::DEFAULT_THRESHOLD
+    ): bool {
+        return $count >= $threshold;
+    }
+
+    /**
+     * Create a collection from an existing array of cookies.
+     *
+     * Automatically selects implementation based on cookie count.
+     *
+     * @param  array<Cookie>  $cookies  Array of cookies
+     * @param  int  $threshold  Threshold for indexed collection
+     * @return CookieCollectionInterface The cookie collection
+     */
+    public static function fromCookies(
+        array $cookies,
+        int $threshold = self::DEFAULT_THRESHOLD
+    ): CookieCollectionInterface {
+        $collection = self::create(count($cookies), $threshold);
+
+        foreach ($cookies as $cookie) {
+            $collection->add($cookie);
+        }
+
+        return $collection;
+    }
+
+    /**
+     * Create a collection and automatically upgrade when threshold is reached.
+     *
+     * Returns an adaptive collection that starts as simple and upgrades
+     * to indexed when it crosses the threshold.
+     *
+     * Note: This requires the collection to be wrapped in an adapter.
+     *
+     * @param  int  $threshold  Threshold for upgrade
+     * @return AdaptiveCookieCollection Adaptive collection wrapper
+     */
+    public static function createAdaptive(
+        int $threshold = self::DEFAULT_THRESHOLD
+    ): AdaptiveCookieCollection {
+        return new AdaptiveCookieCollection($threshold);
+    }
+
+    /**
+     * Get the default threshold.
+     *
+     * @return int Default threshold (50)
+     */
+    public static function getDefaultThreshold(): int
+    {
+        return self::DEFAULT_THRESHOLD;
+    }
+
+    /**
+     * Migrate from one collection type to another.
+     *
+     * Useful when manually upgrading/downgrading collections.
+     *
+     * @param  CookieCollectionInterface  $from  Source collection
+     * @param  class-string<CookieCollectionInterface>  $toType  Target collection class
+     * @return CookieCollectionInterface New collection with same cookies
+     */
+    public static function migrate(
+        CookieCollectionInterface $from,
+        string $toType
+    ): CookieCollectionInterface {
+        if ($from instanceof $toType) {
+            return $from; // Already correct type
+        }
+
+        $to = new $toType;
+
+        foreach ($from->all() as $cookie) {
+            $to->add($cookie);
+        }
+
+        return $to;
+    }
+}
diff --git a/src/Cookie/CookieCollectionInterface.php b/src/Cookie/CookieCollectionInterface.php
new file mode 100644
index 0000000..588f7e5
--- /dev/null
+++ b/src/Cookie/CookieCollectionInterface.php
@@ -0,0 +1,102 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Farzai\Transport\Cookie;
+
+/**
+ * Interface for cookie collection storage strategies.
+ *
+ * Design Pattern: Composite Pattern + Strategy Pattern
+ * - Defines common interface for different storage implementations
+ * - Allows transparent switching between simple and indexed storage
+ * - Enables performance optimization based on cookie count
+ *
+ * Implementations:
+ * - SimpleCookieCollection: Linear search (O(n)) - Good for < 50 cookies
+ * - IndexedCookieCollection: Hash map lookup (O(1)) - Good for >= 50 cookies
+ *
+ * @example
+ * ```php
+ * $collection = CookieCollectionFactory::create();
+ * $collection->add($cookie);
+ * $matches = $collection->findForUrl('https://example.com');
+ * ```
+ */
+interface CookieCollectionInterface
+{
+    /**
+     * Add a cookie to the collection.
+     *
+     * If a cookie with the same identifier exists, it will be replaced.
+     *
+     * @param  Cookie  $cookie  The cookie to add
+     */
+    public function add(Cookie $cookie): void;
+
+    /**
+     * Remove a cookie by its identifier.
+     *
+     * @param  string  $identifier  The cookie identifier (name|domain|path)
+     */
+    public function remove(string $identifier): void;
+
+    /**
+     * Get a cookie by its identifier.
+     *
+     * @param  string  $identifier  The cookie identifier (name|domain|path)
+     * @return Cookie|null The cookie if found, null otherwise
+     */
+    public function get(string $identifier): ?Cookie;
+
+    /**
+     * Find all cookies matching a URL.
+     *
+     * This is the performance-critical method that benefits from indexing.
+     *
+     * @param  string  $url  The URL to match
+     * @param  bool  $isSecure  Whether the request is HTTPS
+     * @return array<Cookie> Array of matching cookies
+     */
+    public function findForUrl(string $url, bool $isSecure): array;
+
+    /**
+     * Get all cookies in the collection.
+     *
+     * @return array<Cookie> Array of all cookies
+     */
+    public function all(): array;
+
+    /**
+     * Get the number of cookies in the collection.
+     *
+     * @return int Cookie count
+     */
+    public function count(): int;
+
+    /**
+     * Check if the collection is empty.
+     *
+     * @return bool True if empty, false otherwise
+     */
+    public function isEmpty(): bool;
+
+    /**
+     * Remove all cookies from the collection.
+     */
+    public function clear(): void;
+
+    /**
+     * Remove all expired cookies.
+     *
+     * @return int Number of cookies removed
+     */
+    public function removeExpired(): int;
+
+    /**
+     * Get the implementation type (for debugging/stats).
+     *
+     * @return string Implementation class name
+     */
+    public function getType(): string;
+}
diff --git a/src/Cookie/CookieJar.php b/src/Cookie/CookieJar.php
index bc97799..4814bd8 100644
--- a/src/Cookie/CookieJar.php
+++ b/src/Cookie/CookieJar.php
@@ -7,20 +7,25 @@
 /**
  * Cookie storage and management following RFC 6265.
  *
+ * Design Pattern: Composite Pattern (uses CookieCollectionInterface)
+ * - Delegates storage to collection implementation
+ * - Automatically uses indexed collection for large cookie counts
+ * - Provides high-level cookie management API
+ *
  * This class provides:
  * - Cookie storage with automatic expiration handling
  * - Domain and path-based cookie matching
  * - Session vs persistent cookie handling
- * - Thread-safe cookie operations
+ * - Adaptive performance optimization (auto-indexes at 50+ cookies)
  *
  * @see https://datatracker.ietf.org/doc/html/rfc6265
  */
 class CookieJar
 {
     /**
-     * @var array<string, Cookie>
+     * Underlying cookie collection.
      */
-    private array $cookies = [];
+    private CookieCollectionInterface $collection;
 
     /**
      * Whether to persist session cookies.
@@ -31,10 +36,14 @@ class CookieJar
      * Create a new cookie jar.
      *
      * @param  bool  $persistSessionCookies  Whether to persist session cookies
+     * @param  CookieCollectionInterface|null  $collection  Optional custom collection
      */
-    public function __construct(bool $persistSessionCookies = false)
-    {
+    public function __construct(
+        bool $persistSessionCookies = false,
+        ?CookieCollectionInterface $collection = null
+    ) {
         $this->persistSessionCookies = $persistSessionCookies;
+        $this->collection = $collection ?? CookieCollectionFactory::createAdaptive();
     }
 
     /**
@@ -59,7 +68,7 @@ public function setCookie(Cookie $cookie): self
             // Still store in memory for current session
         }
 
-        $this->cookies[$cookie->getIdentifier()] = $cookie;
+        $this->collection->add($cookie);
 
         return $this;
     }
@@ -75,7 +84,7 @@ public function getCookie(string $name, ?string $domain = null, string $path = '
     {
         $identifier = sprintf('%s|%s|%s', $name, $domain ?? '', $path);
 
-        return $this->cookies[$identifier] ?? null;
+        return $this->collection->get($identifier);
     }
 
     /**
@@ -83,6 +92,10 @@ public function getCookie(string $name, ?string $domain = null, string $path = '
      *
      * Returns cookies sorted by path length (most specific first).
      *
+     * Performance: This method benefits from indexed collection when cookie count >= 50.
+     * - < 50 cookies: O(n) linear search
+     * - >= 50 cookies: O(1) domain lookup + O(k) where k = cookies for that domain
+     *
      * @param  string  $url  The URL to match
      * @param  bool|null  $isSecure  Whether the request is secure (auto-detect if null)
      * @return array<Cookie>
@@ -96,34 +109,10 @@ public function getCookiesForUrl(string $url, ?bool $isSecure = null): array
             return [];
         }
 
-        $domain = $parsed['host'] ?? '';
-        $path = $parsed['path'] ?? '/';
         $isSecure = $isSecure ?? (($parsed['scheme'] ?? '') === 'https');
 
-        $matching = [];
-
-        foreach ($this->cookies as $cookie) {
-            if ($cookie->matchesUrl($url, $isSecure)) {
-                $matching[] = $cookie;
-            }
-        }
-
-        // Sort by path length (RFC 6265 Section 5.4)
-        usort($matching, function (Cookie $a, Cookie $b) {
-            $lengthA = strlen($a->getPath());
-            $lengthB = strlen($b->getPath());
-
-            if ($lengthA === $lengthB) {
-                // If same length, sort by creation time (older first)
-                // Since we don't track creation time, maintain insertion order
-                return 0;
-            }
-
-            // Longer paths first (more specific)
-            return $lengthB <=> $lengthA;
-        });
-
-        return $matching;
+        // Delegate to collection's optimized findForUrl method
+        return $this->collection->findForUrl($url, $isSecure);
     }
 
     /**
@@ -138,7 +127,7 @@ public function getAllCookies(bool $includeExpired = false): array
             $this->removeExpiredCookies();
         }
 
-        return array_values($this->cookies);
+        return $this->collection->all();
     }
 
     /**
@@ -153,7 +142,7 @@ public function removeCookie(string $name, ?string $domain = null, string $path
     {
         $identifier = sprintf('%s|%s|%s', $name, $domain ?? '', $path);
 
-        unset($this->cookies[$identifier]);
+        $this->collection->remove($identifier);
 
         return $this;
     }
@@ -165,7 +154,7 @@ public function removeCookie(string $name, ?string $domain = null, string $path
      */
     public function clear(): self
     {
-        $this->cookies = [];
+        $this->collection->clear();
 
         return $this;
     }
@@ -177,10 +166,7 @@ public function clear(): self
      */
     public function removeExpiredCookies(): self
     {
-        $this->cookies = array_filter(
-            $this->cookies,
-            fn (Cookie $cookie) => ! $cookie->isExpired()
-        );
+        $this->collection->removeExpired();
 
         return $this;
     }
@@ -196,7 +182,7 @@ public function count(bool $includeExpired = false): int
             $this->removeExpiredCookies();
         }
 
-        return count($this->cookies);
+        return $this->collection->count();
     }
 
     /**
@@ -206,7 +192,7 @@ public function isEmpty(): bool
     {
         $this->removeExpiredCookies();
 
-        return empty($this->cookies);
+        return $this->collection->isEmpty();
     }
 
     /**
@@ -280,7 +266,7 @@ public function toArray(): array
                 'http_only' => $cookie->isHttpOnly(),
                 'same_site' => $cookie->getSameSite(),
             ];
-        }, $this->cookies);
+        }, $this->collection->all());
     }
 
     /**
diff --git a/src/Cookie/IndexedCookieCollection.php b/src/Cookie/IndexedCookieCollection.php
new file mode 100644
index 0000000..601cef4
--- /dev/null
+++ b/src/Cookie/IndexedCookieCollection.php
@@ -0,0 +1,324 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Farzai\Transport\Cookie;
+
+/**
+ * Indexed cookie collection using hash map for fast domain lookups.
+ *
+ * Design Pattern: Composite Pattern (Leaf) + Index Pattern
+ * - Implements CookieCollectionInterface
+ * - Uses hash map indexed by domain (O(1) average case)
+ * - Best for large cookie counts (>= 50 cookies)
+ *
+ * Characteristics:
+ * - Time Complexity: O(1) average case for findForUrl() (per domain)
+ * - Space Complexity: O(n) with indexing overhead
+ * - Memory Overhead: ~2x (maintains both identifier map and domain index)
+ * - Best Use: Large cookie counts, high-traffic scenarios
+ *
+ * Indexing Strategy:
+ * - Primary index: identifier → Cookie
+ * - Secondary index: domain → Cookie[]
+ * - Handles subdomain matching efficiently
+ *
+ * @example
+ * ```php
+ * $collection = new IndexedCookieCollection();
+ * $collection->add(new Cookie('session', 'abc123', null, 'example.com'));
+ * $matches = $collection->findForUrl('https://example.com/path');
+ * // O(1) domain lookup instead of O(n) linear search
+ * ```
+ */
+final class IndexedCookieCollection implements CookieCollectionInterface
+{
+    /**
+     * Primary storage: identifier → Cookie.
+     *
+     * @var array<string, Cookie>
+     */
+    private array $cookies = [];
+
+    /**
+     * Secondary index: domain → array of cookie identifiers.
+     *
+     * Example:
+     * [
+     *     'example.com' => ['session|example.com|/', 'token|example.com|/'],
+     *     '.example.com' => ['ga|.example.com|/'],
+     * ]
+     *
+     * @var array<string, array<string>>
+     */
+    private array $domainIndex = [];
+
+    /**
+     * {@inheritDoc}
+     */
+    public function add(Cookie $cookie): void
+    {
+        $identifier = $cookie->getIdentifier();
+        $domain = $cookie->getDomain() ?? '';
+
+        // Remove old cookie if exists (to update index)
+        if (isset($this->cookies[$identifier])) {
+            $this->removeFromDomainIndex($identifier, $domain);
+        }
+
+        // Add to primary storage
+        $this->cookies[$identifier] = $cookie;
+
+        // Add to domain index
+        $this->addToDomainIndex($identifier, $domain);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function remove(string $identifier): void
+    {
+        if (! isset($this->cookies[$identifier])) {
+            return;
+        }
+
+        $cookie = $this->cookies[$identifier];
+        $domain = $cookie->getDomain() ?? '';
+
+        // Remove from domain index
+        $this->removeFromDomainIndex($identifier, $domain);
+
+        // Remove from primary storage
+        unset($this->cookies[$identifier]);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function get(string $identifier): ?Cookie
+    {
+        return $this->cookies[$identifier] ?? null;
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * This is the optimized method that benefits from domain indexing.
+     * Instead of checking ALL cookies, we only check cookies for relevant domains.
+     */
+    public function findForUrl(string $url, bool $isSecure): array
+    {
+        $parsed = parse_url($url);
+        if ($parsed === false) {
+            return [];
+        }
+
+        $domain = $parsed['host'] ?? '';
+        if ($domain === '') {
+            return [];
+        }
+
+        // Get candidate cookies from domain index - O(1) lookup
+        $candidates = $this->getCandidateCookies($domain);
+
+        // Filter candidates that actually match the URL
+        $matching = [];
+        foreach ($candidates as $cookie) {
+            if ($cookie->matchesUrl($url, $isSecure)) {
+                $matching[] = $cookie;
+            }
+        }
+
+        // Sort by path length (RFC 6265 Section 5.4)
+        usort($matching, function (Cookie $a, Cookie $b) {
+            $lengthA = strlen($a->getPath());
+            $lengthB = strlen($b->getPath());
+
+            if ($lengthA === $lengthB) {
+                return 0;
+            }
+
+            // Longer paths first (more specific)
+            return $lengthB <=> $lengthA;
+        });
+
+        return $matching;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function all(): array
+    {
+        return array_values($this->cookies);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function count(): int
+    {
+        return count($this->cookies);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function isEmpty(): bool
+    {
+        return empty($this->cookies);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function clear(): void
+    {
+        $this->cookies = [];
+        $this->domainIndex = [];
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function removeExpired(): int
+    {
+        $originalCount = count($this->cookies);
+        $toRemove = [];
+
+        // Find expired cookies
+        foreach ($this->cookies as $identifier => $cookie) {
+            if ($cookie->isExpired()) {
+                $toRemove[] = $identifier;
+            }
+        }
+
+        // Remove them (this updates indexes)
+        foreach ($toRemove as $identifier) {
+            $this->remove($identifier);
+        }
+
+        return count($toRemove);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getType(): string
+    {
+        return self::class;
+    }
+
+    /**
+     * Get candidate cookies for a domain.
+     *
+     * Returns cookies that might match the domain, including:
+     * - Exact domain match
+     * - Parent domain matches (.example.com matches api.example.com)
+     *
+     * @param  string  $domain  The domain to match
+     * @return array<Cookie> Candidate cookies
+     */
+    private function getCandidateCookies(string $domain): array
+    {
+        $candidates = [];
+
+        // Check exact domain
+        if (isset($this->domainIndex[$domain])) {
+            foreach ($this->domainIndex[$domain] as $identifier) {
+                if (isset($this->cookies[$identifier])) {
+                    $candidates[] = $this->cookies[$identifier];
+                }
+            }
+        }
+
+        // Check domain with leading dot (.example.com)
+        $dottedDomain = '.'.$domain;
+        if (isset($this->domainIndex[$dottedDomain])) {
+            foreach ($this->domainIndex[$dottedDomain] as $identifier) {
+                if (isset($this->cookies[$identifier])) {
+                    $candidates[] = $this->cookies[$identifier];
+                }
+            }
+        }
+
+        // Check parent domains (e.g., .example.com for api.example.com)
+        $parts = explode('.', $domain);
+        for ($i = 1; $i < count($parts); $i++) {
+            $parentDomain = '.'.implode('.', array_slice($parts, $i));
+
+            if (isset($this->domainIndex[$parentDomain])) {
+                foreach ($this->domainIndex[$parentDomain] as $identifier) {
+                    if (isset($this->cookies[$identifier])) {
+                        $candidates[] = $this->cookies[$identifier];
+                    }
+                }
+            }
+        }
+
+        return $candidates;
+    }
+
+    /**
+     * Add a cookie identifier to the domain index.
+     *
+     * @param  string  $identifier  Cookie identifier
+     * @param  string  $domain  Cookie domain
+     */
+    private function addToDomainIndex(string $identifier, string $domain): void
+    {
+        if (! isset($this->domainIndex[$domain])) {
+            $this->domainIndex[$domain] = [];
+        }
+
+        // Avoid duplicates
+        if (! in_array($identifier, $this->domainIndex[$domain], true)) {
+            $this->domainIndex[$domain][] = $identifier;
+        }
+    }
+
+    /**
+     * Remove a cookie identifier from the domain index.
+     *
+     * @param  string  $identifier  Cookie identifier
+     * @param  string  $domain  Cookie domain
+     */
+    private function removeFromDomainIndex(string $identifier, string $domain): void
+    {
+        if (! isset($this->domainIndex[$domain])) {
+            return;
+        }
+
+        $this->domainIndex[$domain] = array_filter(
+            $this->domainIndex[$domain],
+            fn ($id) => $id !== $identifier
+        );
+
+        // Clean up empty domain entries
+        if (empty($this->domainIndex[$domain])) {
+            unset($this->domainIndex[$domain]);
+        }
+    }
+
+    /**
+     * Get statistics about the index (for debugging/monitoring).
+     *
+     * @return array<string, mixed> Index statistics
+     */
+    public function getIndexStats(): array
+    {
+        $domainCounts = array_map('count', $this->domainIndex);
+
+        return [
+            'total_cookies' => count($this->cookies),
+            'indexed_domains' => count($this->domainIndex),
+            'avg_cookies_per_domain' => count($this->cookies) > 0
+                ? count($this->cookies) / max(1, count($this->domainIndex))
+                : 0,
+            'max_cookies_per_domain' => ! empty($domainCounts) ? max($domainCounts) : 0,
+            'memory_overhead_ratio' => count($this->cookies) > 0
+                ? count($this->domainIndex) / count($this->cookies)
+                : 0,
+        ];
+    }
+}
diff --git a/src/Cookie/SimpleCookieCollection.php b/src/Cookie/SimpleCookieCollection.php
new file mode 100644
index 0000000..d1b9979
--- /dev/null
+++ b/src/Cookie/SimpleCookieCollection.php
@@ -0,0 +1,143 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Farzai\Transport\Cookie;
+
+/**
+ * Simple cookie collection using linear search.
+ *
+ * Design Pattern: Composite Pattern (Leaf)
+ * - Implements CookieCollectionInterface
+ * - Uses array with linear search (O(n))
+ * - Best for small cookie counts (< 50 cookies)
+ *
+ * Characteristics:
+ * - Time Complexity: O(n) for findForUrl()
+ * - Space Complexity: O(n)
+ * - Memory Overhead: Minimal (single array)
+ * - Best Use: Small cookie counts, simple scenarios
+ *
+ * @example
+ * ```php
+ * $collection = new SimpleCookieCollection();
+ * $collection->add(new Cookie('session', 'abc123', null, 'example.com'));
+ * $matches = $collection->findForUrl('https://example.com/path');
+ * ```
+ */
+final class SimpleCookieCollection implements CookieCollectionInterface
+{
+    /**
+     * @var array<string, Cookie>
+     */
+    private array $cookies = [];
+
+    /**
+     * {@inheritDoc}
+     */
+    public function add(Cookie $cookie): void
+    {
+        $this->cookies[$cookie->getIdentifier()] = $cookie;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function remove(string $identifier): void
+    {
+        unset($this->cookies[$identifier]);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function get(string $identifier): ?Cookie
+    {
+        return $this->cookies[$identifier] ?? null;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function findForUrl(string $url, bool $isSecure): array
+    {
+        $matching = [];
+
+        // Linear search through all cookies - O(n)
+        foreach ($this->cookies as $cookie) {
+            if ($cookie->matchesUrl($url, $isSecure)) {
+                $matching[] = $cookie;
+            }
+        }
+
+        // Sort by path length (RFC 6265 Section 5.4)
+        usort($matching, function (Cookie $a, Cookie $b) {
+            $lengthA = strlen($a->getPath());
+            $lengthB = strlen($b->getPath());
+
+            if ($lengthA === $lengthB) {
+                return 0;
+            }
+
+            // Longer paths first (more specific)
+            return $lengthB <=> $lengthA;
+        });
+
+        return $matching;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function all(): array
+    {
+        return array_values($this->cookies);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function count(): int
+    {
+        return count($this->cookies);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function isEmpty(): bool
+    {
+        return empty($this->cookies);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function clear(): void
+    {
+        $this->cookies = [];
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function removeExpired(): int
+    {
+        $originalCount = count($this->cookies);
+
+        $this->cookies = array_filter(
+            $this->cookies,
+            fn (Cookie $cookie) => ! $cookie->isExpired()
+        );
+
+        return $originalCount - count($this->cookies);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getType(): string
+    {
+        return self::class;
+    }
+}
diff --git a/src/Events/AbstractEvent.php b/src/Events/AbstractEvent.php
new file mode 100644
index 0000000..2a7984b
--- /dev/null
+++ b/src/Events/AbstractEvent.php
@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Farzai\Transport\Events;
+
+/**
+ * Abstract base class for all events providing common functionality.
+ *
+ * Implements propagation control which is common to all events.
+ * Concrete event classes should extend this and add specific data/methods.
+ *
+ * Design Pattern: Template Method Pattern
+ * - Provides default implementation of event interface
+ * - Subclasses add specific event data and behavior
+ *
+ * @example
+ * ```php
+ * class CustomEvent extends AbstractEvent
+ * {
+ *     public function __construct(
+ *         private readonly mixed $data
+ *     ) {}
+ *
+ *     public function getData(): mixed
+ *     {
+ *         return $this->data;
+ *     }
+ * }
+ * ```
+ */
+abstract class AbstractEvent implements EventInterface
+{
+    /**
+     * Whether event propagation has been stopped.
+     */
+    private bool $propagationStopped = false;
+
+    /**
+     * {@inheritDoc}
+     */
+    public function isPropagationStopped(): bool
+    {
+        return $this->propagationStopped;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function stopPropagation(): void
+    {
+        $this->propagationStopped = true;
+    }
+}
diff --git a/src/Events/EventDispatcher.php b/src/Events/EventDispatcher.php
new file mode 100644
index 0000000..1d49b46
--- /dev/null
+++ b/src/Events/EventDispatcher.php
@@ -0,0 +1,162 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Farzai\Transport\Events;
+
+/**
+ * Default event dispatcher implementation.
+ *
+ * Design Pattern: Observer Pattern
+ * - Maintains map of event classes to listener arrays
+ * - Dispatches events to registered listeners
+ * - Supports propagation control
+ *
+ * Thread Safety: Not thread-safe by default.
+ * For multi-threaded environments, wrap in mutex or use
+ * separate dispatcher instances per thread.
+ *
+ * @example
+ * ```php
+ * $dispatcher = new EventDispatcher();
+ *
+ * $dispatcher->addEventListener(RequestSentEvent::class, function ($event) {
+ *     // Log request
+ *     $this->logger->info('Request sent', [
+ *         'uri' => (string) $event->getRequest()->getUri(),
+ *         'method' => $event->getRequest()->getMethod(),
+ *     ]);
+ * });
+ *
+ * $dispatcher->addEventListener(ResponseReceivedEvent::class, function ($event) {
+ *     // Record metrics
+ *     $this->metrics->recordLatency($event->getDuration());
+ *     $this->metrics->recordStatusCode($event->getResponse()->statusCode());
+ * });
+ *
+ * // Dispatch events (done automatically by Transport)
+ * $dispatcher->dispatch($event);
+ * ```
+ */
+final class EventDispatcher implements EventDispatcherInterface
+{
+    /**
+     * Map of event class names to arrays of listeners.
+     *
+     * @var array<class-string<EventInterface>, array<callable>>
+     */
+    private array $listeners = [];
+
+    /**
+     * {@inheritDoc}
+     */
+    public function dispatch(EventInterface $event): void
+    {
+        $eventClass = get_class($event);
+
+        // Get listeners for this exact event class and parent classes
+        $listeners = $this->getListenersForEvent($eventClass);
+
+        foreach ($listeners as $listener) {
+            // Stop if propagation has been stopped
+            if ($event->isPropagationStopped()) {
+                break;
+            }
+
+            // Call the listener
+            $listener($event);
+        }
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function addEventListener(string $eventClass, callable $listener): void
+    {
+        if (! isset($this->listeners[$eventClass])) {
+            $this->listeners[$eventClass] = [];
+        }
+
+        $this->listeners[$eventClass][] = $listener;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function removeEventListener(string $eventClass, callable $listener): void
+    {
+        if (! isset($this->listeners[$eventClass])) {
+            return;
+        }
+
+        $this->listeners[$eventClass] = array_filter(
+            $this->listeners[$eventClass],
+            fn ($registered) => $registered !== $listener
+        );
+
+        // Clean up empty arrays
+        if (empty($this->listeners[$eventClass])) {
+            unset($this->listeners[$eventClass]);
+        }
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function hasListeners(string $eventClass): bool
+    {
+        return isset($this->listeners[$eventClass]) && ! empty($this->listeners[$eventClass]);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getListeners(string $eventClass): array
+    {
+        return $this->listeners[$eventClass] ?? [];
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function removeAllListeners(?string $eventClass = null): void
+    {
+        if ($eventClass === null) {
+            $this->listeners = [];
+
+            return;
+        }
+
+        unset($this->listeners[$eventClass]);
+    }
+
+    /**
+     * Get all listeners for an event, including listeners for parent event classes.
+     *
+     * This allows listeners to register for base event classes and receive
+     * notifications for all subclasses.
+     *
+     * @param  class-string  $eventClass  The event class
+     * @return array<callable> Array of listeners
+     */
+    private function getListenersForEvent(string $eventClass): array
+    {
+        $listeners = [];
+
+        // Add listeners for this exact class
+        if (isset($this->listeners[$eventClass])) {
+            $listeners = array_merge($listeners, $this->listeners[$eventClass]);
+        }
+
+        // Add listeners for parent classes
+        $parentClass = get_parent_class($eventClass);
+        while ($parentClass !== false) {
+            if (isset($this->listeners[$parentClass])) {
+                $listeners = array_merge($listeners, $this->listeners[$parentClass]);
+            }
+            $parentClass = get_parent_class($parentClass);
+        }
+
+        return $listeners;
+    }
+}
diff --git a/src/Events/EventDispatcherInterface.php b/src/Events/EventDispatcherInterface.php
new file mode 100644
index 0000000..e272136
--- /dev/null
+++ b/src/Events/EventDispatcherInterface.php
@@ -0,0 +1,89 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Farzai\Transport\Events;
+
+/**
+ * Event dispatcher interface for managing event listeners and dispatching events.
+ *
+ * Design Pattern: Observer Pattern (Subject)
+ * - Maintains list of observers (listeners)
+ * - Notifies observers when events occur
+ * - Allows dynamic listener registration/removal
+ *
+ * Simplified from PSR-14 for Transport use cases.
+ *
+ * @example
+ * ```php
+ * $dispatcher = new EventDispatcher();
+ *
+ * // Add listener
+ * $dispatcher->addEventListener(RequestSentEvent::class, function ($event) {
+ *     echo "Request sent to: " . $event->getRequest()->getUri() . "\n";
+ * });
+ *
+ * // Dispatch event
+ * $dispatcher->dispatch(new RequestSentEvent($request, $response));
+ * ```
+ */
+interface EventDispatcherInterface
+{
+    /**
+     * Dispatch an event to all registered listeners.
+     *
+     * Listeners are called in the order they were registered.
+     * If a listener calls stopPropagation() on the event,
+     * remaining listeners will not be called.
+     *
+     * @param  EventInterface  $event  The event to dispatch
+     */
+    public function dispatch(EventInterface $event): void;
+
+    /**
+     * Add an event listener for a specific event class.
+     *
+     * The listener will be called whenever an event of the specified
+     * class (or subclass) is dispatched.
+     *
+     * @param  class-string<EventInterface>  $eventClass  The event class to listen for
+     * @param  callable(EventInterface): void  $listener  The listener callable
+     */
+    public function addEventListener(string $eventClass, callable $listener): void;
+
+    /**
+     * Remove an event listener.
+     *
+     * The listener must be the exact same callable instance that was
+     * registered with addEventListener().
+     *
+     * @param  class-string<EventInterface>  $eventClass  The event class
+     * @param  callable(EventInterface): void  $listener  The listener to remove
+     */
+    public function removeEventListener(string $eventClass, callable $listener): void;
+
+    /**
+     * Check if any listeners are registered for an event class.
+     *
+     * @param  class-string<EventInterface>  $eventClass  The event class
+     * @return bool True if listeners exist, false otherwise
+     */
+    public function hasListeners(string $eventClass): bool;
+
+    /**
+     * Get all listeners for an event class.
+     *
+     * @param  class-string<EventInterface>  $eventClass  The event class
+     * @return array<callable> Array of listener callables
+     */
+    public function getListeners(string $eventClass): array;
+
+    /**
+     * Remove all listeners for a specific event class.
+     *
+     * If no event class is specified, removes ALL listeners.
+     *
+     * @param  class-string<EventInterface>|null  $eventClass  Optional event class
+     */
+    public function removeAllListeners(?string $eventClass = null): void;
+}
diff --git a/src/Events/EventInterface.php b/src/Events/EventInterface.php
new file mode 100644
index 0000000..74d87dd
--- /dev/null
+++ b/src/Events/EventInterface.php
@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Farzai\Transport\Events;
+
+/**
+ * Base interface for all transport events.
+ *
+ * Design Pattern: Observer Pattern
+ * - Events represent things that have happened in the system
+ * - Listeners can observe events without modifying behavior
+ * - Supports event propagation control
+ *
+ * Inspired by PSR-14 Event Dispatcher but simplified for our use case.
+ *
+ * @example
+ * ```php
+ * $transport->addEventListener(ResponseReceivedEvent::class, function ($event) {
+ *     if ($event->getResponse()->statusCode() >= 500) {
+ *         $this->logger->error('Server error', ['event' => $event]);
+ *         $event->stopPropagation();
+ *     }
+ * });
+ * ```
+ */
+interface EventInterface
+{
+    /**
+     * Check if event propagation has been stopped.
+     *
+     * When true, the event dispatcher will not call any remaining listeners.
+     *
+     * @return bool True if propagation stopped, false otherwise
+     */
+    public function isPropagationStopped(): bool;
+
+    /**
+     * Stop event propagation.
+     *
+     * This prevents subsequent listeners from being called for this event.
+     * Useful for error handling or circuit breaking.
+     */
+    public function stopPropagation(): void;
+}
diff --git a/src/Events/RequestFailedEvent.php b/src/Events/RequestFailedEvent.php
new file mode 100644
index 0000000..aecdb19
--- /dev/null
+++ b/src/Events/RequestFailedEvent.php
@@ -0,0 +1,201 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Farzai\Transport\Events;
+
+use Psr\Http\Message\RequestInterface;
+use Throwable;
+
+/**
+ * Event dispatched when a request fails with an exception.
+ *
+ * This event is fired when any exception occurs during request processing,
+ * including network errors, timeouts, HTTP errors, etc.
+ *
+ * Use Cases:
+ * - Error logging and monitoring
+ * - Alert on repeated failures
+ * - Track error rates
+ * - Implement custom error recovery
+ * - Circuit breaker implementation
+ *
+ * @example
+ * ```php
+ * $dispatcher->addEventListener(RequestFailedEvent::class, function ($event) {
+ *     $this->logger->error('Request failed', [
+ *         'method' => $event->getMethod(),
+ *         'uri' => $event->getUri(),
+ *         'error' => $event->getException()->getMessage(),
+ *         'type' => get_class($event->getException()),
+ *         'attempt' => $event->getAttemptNumber(),
+ *     ]);
+ *
+ *     // Alert on network errors
+ *     if ($event->isNetworkError()) {
+ *         $this->alerts->networkIssue($event->getUri());
+ *     }
+ *
+ *     // Track error metrics
+ *     $this->metrics->incrementErrorCount($event->getUri());
+ * });
+ * ```
+ */
+final class RequestFailedEvent extends AbstractEvent
+{
+    private float $timestamp;
+
+    /**
+     * Create a new request failed event.
+     *
+     * @param  RequestInterface  $request  The PSR-7 request that failed
+     * @param  Throwable  $exception  The exception that was thrown
+     * @param  int  $attemptNumber  The attempt number (1-based, useful for retries)
+     * @param  float  $timestamp  Unix timestamp when failure occurred (microtime)
+     */
+    public function __construct(
+        private readonly RequestInterface $request,
+        private readonly Throwable $exception,
+        private readonly int $attemptNumber = 1,
+        float $timestamp = 0.0
+    ) {
+        // Use current microtime if not provided
+        $this->timestamp = $timestamp === 0.0 ? microtime(true) : $timestamp;
+    }
+
+    /**
+     * Get the PSR-7 request that failed.
+     *
+     * @return RequestInterface The request
+     */
+    public function getRequest(): RequestInterface
+    {
+        return $this->request;
+    }
+
+    /**
+     * Get the exception that caused the failure.
+     *
+     * @return Throwable The exception
+     */
+    public function getException(): Throwable
+    {
+        return $this->exception;
+    }
+
+    /**
+     * Get the attempt number.
+     *
+     * For non-retry scenarios, this will be 1.
+     * For retry scenarios, this increments with each retry.
+     *
+     * @return int Attempt number (1-based)
+     */
+    public function getAttemptNumber(): int
+    {
+        return $this->attemptNumber;
+    }
+
+    /**
+     * Get the timestamp when the failure occurred.
+     *
+     * @return float Unix timestamp with microseconds
+     */
+    public function getTimestamp(): float
+    {
+        return $this->timestamp;
+    }
+
+    /**
+     * Get the HTTP method.
+     *
+     * @return string HTTP method (GET, POST, etc.)
+     */
+    public function getMethod(): string
+    {
+        return $this->request->getMethod();
+    }
+
+    /**
+     * Get the request URI.
+     *
+     * @return string The URI as a string
+     */
+    public function getUri(): string
+    {
+        return (string) $this->request->getUri();
+    }
+
+    /**
+     * Get the exception class name.
+     *
+     * @return string Fully qualified exception class name
+     */
+    public function getExceptionType(): string
+    {
+        return get_class($this->exception);
+    }
+
+    /**
+     * Get the exception message.
+     *
+     * @return string Exception message
+     */
+    public function getExceptionMessage(): string
+    {
+        return $this->exception->getMessage();
+    }
+
+    /**
+     * Check if this is a network error.
+     *
+     * Network errors include connection failures, DNS failures, etc.
+     *
+     * @return bool True if network error, false otherwise
+     */
+    public function isNetworkError(): bool
+    {
+        $exceptionType = $this->getExceptionType();
+
+        return str_contains($exceptionType, 'NetworkException')
+            || str_contains($exceptionType, 'ConnectionException')
+            || str_contains($exceptionType, 'ConnectException');
+    }
+
+    /**
+     * Check if this is a timeout error.
+     *
+     * @return bool True if timeout error, false otherwise
+     */
+    public function isTimeoutError(): bool
+    {
+        $exceptionType = $this->getExceptionType();
+
+        return str_contains($exceptionType, 'TimeoutException');
+    }
+
+    /**
+     * Check if this is an HTTP error (4xx or 5xx status code).
+     *
+     * @return bool True if HTTP error, false otherwise
+     */
+    public function isHttpError(): bool
+    {
+        $exceptionType = $this->getExceptionType();
+
+        return str_contains($exceptionType, 'HttpException')
+            || str_contains($exceptionType, 'ClientException')
+            || str_contains($exceptionType, 'ServerException')
+            || str_contains($exceptionType, 'BadResponseException');
+    }
+
+    /**
+     * Check if this is a retry attempt (not the first attempt).
+     *
+     * @return bool True if this is a retry, false if first attempt
+     */
+    public function isRetry(): bool
+    {
+        return $this->attemptNumber > 1;
+    }
+}
diff --git a/src/Events/RequestSendingEvent.php b/src/Events/RequestSendingEvent.php
new file mode 100644
index 0000000..86da2ee
--- /dev/null
+++ b/src/Events/RequestSendingEvent.php
@@ -0,0 +1,89 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Farzai\Transport\Events;
+
+use Psr\Http\Message\RequestInterface;
+
+/**
+ * Event dispatched before a request enters the middleware pipeline.
+ *
+ * This is the first event in the request lifecycle, fired before any
+ * middleware processing occurs.
+ *
+ * Use Cases:
+ * - Log all outgoing requests
+ * - Add request tracking/correlation IDs
+ * - Implement request quotas or rate limiting
+ * - Audit API calls
+ *
+ * @example
+ * ```php
+ * $dispatcher->addEventListener(RequestSendingEvent::class, function ($event) {
+ *     $this->logger->info('Sending request', [
+ *         'method' => $event->getRequest()->getMethod(),
+ *         'uri' => (string) $event->getRequest()->getUri(),
+ *         'time' => $event->getTimestamp(),
+ *     ]);
+ * });
+ * ```
+ */
+final class RequestSendingEvent extends AbstractEvent
+{
+    private float $timestamp;
+
+    /**
+     * Create a new request sending event.
+     *
+     * @param  RequestInterface  $request  The PSR-7 request being sent
+     * @param  float  $timestamp  Unix timestamp when request started (microtime)
+     */
+    public function __construct(
+        private readonly RequestInterface $request,
+        float $timestamp = 0.0
+    ) {
+        // Use current microtime if not provided
+        $this->timestamp = $timestamp === 0.0 ? microtime(true) : $timestamp;
+    }
+
+    /**
+     * Get the PSR-7 request.
+     *
+     * @return RequestInterface The request
+     */
+    public function getRequest(): RequestInterface
+    {
+        return $this->request;
+    }
+
+    /**
+     * Get the timestamp when the request started.
+     *
+     * @return float Unix timestamp with microseconds
+     */
+    public function getTimestamp(): float
+    {
+        return $this->timestamp;
+    }
+
+    /**
+     * Get the HTTP method.
+     *
+     * @return string HTTP method (GET, POST, etc.)
+     */
+    public function getMethod(): string
+    {
+        return $this->request->getMethod();
+    }
+
+    /**
+     * Get the request URI.
+     *
+     * @return string The URI as a string
+     */
+    public function getUri(): string
+    {
+        return (string) $this->request->getUri();
+    }
+}
diff --git a/src/Events/RequestSentEvent.php b/src/Events/RequestSentEvent.php
new file mode 100644
index 0000000..608c47f
--- /dev/null
+++ b/src/Events/RequestSentEvent.php
@@ -0,0 +1,133 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Farzai\Transport\Events;
+
+use Psr\Http\Message\RequestInterface;
+use Psr\Http\Message\ResponseInterface;
+
+/**
+ * Event dispatched after request has been sent to the HTTP client.
+ *
+ * This event is fired after the HTTP client returns a response,
+ * before any response processing or middleware unwinding occurs.
+ *
+ * Use Cases:
+ * - Record request/response metrics
+ * - Log successful API calls
+ * - Track API usage statistics
+ * - Implement custom caching logic
+ *
+ * @example
+ * ```php
+ * $dispatcher->addEventListener(RequestSentEvent::class, function ($event) {
+ *     $this->metrics->recordLatency(
+ *         $event->getUri(),
+ *         $event->getDuration()
+ *     );
+ *     $this->metrics->recordStatusCode(
+ *         $event->getResponse()->getStatusCode()
+ *     );
+ * });
+ * ```
+ */
+final class RequestSentEvent extends AbstractEvent
+{
+    /**
+     * Create a new request sent event.
+     *
+     * @param  RequestInterface  $request  The PSR-7 request that was sent
+     * @param  ResponseInterface  $response  The PSR-7 response received
+     * @param  float  $duration  Duration in milliseconds
+     * @param  float  $timestamp  Unix timestamp when request completed (microtime)
+     */
+    public function __construct(
+        private readonly RequestInterface $request,
+        private readonly ResponseInterface $response,
+        private readonly float $duration,
+        private readonly float $timestamp
+    ) {}
+
+    /**
+     * Get the PSR-7 request that was sent.
+     *
+     * @return RequestInterface The request
+     */
+    public function getRequest(): RequestInterface
+    {
+        return $this->request;
+    }
+
+    /**
+     * Get the PSR-7 response received.
+     *
+     * @return ResponseInterface The response
+     */
+    public function getResponse(): ResponseInterface
+    {
+        return $this->response;
+    }
+
+    /**
+     * Get the request duration in milliseconds.
+     *
+     * @return float Duration in milliseconds
+     */
+    public function getDuration(): float
+    {
+        return $this->duration;
+    }
+
+    /**
+     * Get the timestamp when the request completed.
+     *
+     * @return float Unix timestamp with microseconds
+     */
+    public function getTimestamp(): float
+    {
+        return $this->timestamp;
+    }
+
+    /**
+     * Get the HTTP method.
+     *
+     * @return string HTTP method (GET, POST, etc.)
+     */
+    public function getMethod(): string
+    {
+        return $this->request->getMethod();
+    }
+
+    /**
+     * Get the request URI.
+     *
+     * @return string The URI as a string
+     */
+    public function getUri(): string
+    {
+        return (string) $this->request->getUri();
+    }
+
+    /**
+     * Get the HTTP status code.
+     *
+     * @return int HTTP status code (200, 404, 500, etc.)
+     */
+    public function getStatusCode(): int
+    {
+        return $this->response->getStatusCode();
+    }
+
+    /**
+     * Check if the response was successful (2xx status code).
+     *
+     * @return bool True if successful, false otherwise
+     */
+    public function isSuccessful(): bool
+    {
+        $status = $this->getStatusCode();
+
+        return $status >= 200 && $status < 300;
+    }
+}
diff --git a/src/Events/ResponseReceivedEvent.php b/src/Events/ResponseReceivedEvent.php
new file mode 100644
index 0000000..8fc0715
--- /dev/null
+++ b/src/Events/ResponseReceivedEvent.php
@@ -0,0 +1,172 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Farzai\Transport\Events;
+
+use Psr\Http\Message\RequestInterface;
+use Psr\Http\Message\ResponseInterface;
+
+/**
+ * Event dispatched after response has been processed through middleware.
+ *
+ * This is the final successful event in the request lifecycle, fired after
+ * all middleware has processed the response.
+ *
+ * Difference from RequestSentEvent:
+ * - RequestSentEvent: Fired immediately after HTTP client returns
+ * - ResponseReceivedEvent: Fired after middleware processing
+ *
+ * Use Cases:
+ * - Final response logging
+ * - End-to-end metrics (including middleware overhead)
+ * - Response caching decisions
+ * - Success notifications
+ *
+ * @example
+ * ```php
+ * $dispatcher->addEventListener(ResponseReceivedEvent::class, function ($event) {
+ *     // Log complete request/response cycle
+ *     $this->logger->info('Request completed', [
+ *         'method' => $event->getMethod(),
+ *         'uri' => $event->getUri(),
+ *         'status' => $event->getStatusCode(),
+ *         'duration' => $event->getDuration(),
+ *         'success' => $event->isSuccessful(),
+ *     ]);
+ *
+ *     // Send notification for slow requests
+ *     if ($event->getDuration() > 5000) {  // > 5 seconds
+ *         $this->alerts->slowRequest($event);
+ *     }
+ * });
+ * ```
+ */
+final class ResponseReceivedEvent extends AbstractEvent
+{
+    /**
+     * Create a new response received event.
+     *
+     * @param  RequestInterface  $request  The PSR-7 request
+     * @param  ResponseInterface  $response  The PSR-7 response (possibly modified by middleware)
+     * @param  float  $duration  Total duration in milliseconds (including middleware)
+     * @param  float  $timestamp  Unix timestamp when processing completed (microtime)
+     */
+    public function __construct(
+        private readonly RequestInterface $request,
+        private readonly ResponseInterface $response,
+        private readonly float $duration,
+        private readonly float $timestamp
+    ) {}
+
+    /**
+     * Get the PSR-7 request.
+     *
+     * @return RequestInterface The request
+     */
+    public function getRequest(): RequestInterface
+    {
+        return $this->request;
+    }
+
+    /**
+     * Get the PSR-7 response.
+     *
+     * This may be different from the original HTTP client response if
+     * middleware has modified it.
+     *
+     * @return ResponseInterface The response (possibly modified)
+     */
+    public function getResponse(): ResponseInterface
+    {
+        return $this->response;
+    }
+
+    /**
+     * Get the total request duration in milliseconds.
+     *
+     * Includes time spent in middleware pipeline.
+     *
+     * @return float Duration in milliseconds
+     */
+    public function getDuration(): float
+    {
+        return $this->duration;
+    }
+
+    /**
+     * Get the timestamp when processing completed.
+     *
+     * @return float Unix timestamp with microseconds
+     */
+    public function getTimestamp(): float
+    {
+        return $this->timestamp;
+    }
+
+    /**
+     * Get the HTTP method.
+     *
+     * @return string HTTP method (GET, POST, etc.)
+     */
+    public function getMethod(): string
+    {
+        return $this->request->getMethod();
+    }
+
+    /**
+     * Get the request URI.
+     *
+     * @return string The URI as a string
+     */
+    public function getUri(): string
+    {
+        return (string) $this->request->getUri();
+    }
+
+    /**
+     * Get the HTTP status code.
+     *
+     * @return int HTTP status code (200, 404, 500, etc.)
+     */
+    public function getStatusCode(): int
+    {
+        return $this->response->getStatusCode();
+    }
+
+    /**
+     * Check if the response was successful (2xx status code).
+     *
+     * @return bool True if successful, false otherwise
+     */
+    public function isSuccessful(): bool
+    {
+        $status = $this->getStatusCode();
+
+        return $status >= 200 && $status < 300;
+    }
+
+    /**
+     * Check if the response was a client error (4xx status code).
+     *
+     * @return bool True if client error, false otherwise
+     */
+    public function isClientError(): bool
+    {
+        $status = $this->getStatusCode();
+
+        return $status >= 400 && $status < 500;
+    }
+
+    /**
+     * Check if the response was a server error (5xx status code).
+     *
+     * @return bool True if server error, false otherwise
+     */
+    public function isServerError(): bool
+    {
+        $status = $this->getStatusCode();
+
+        return $status >= 500 && $status < 600;
+    }
+}
diff --git a/src/Events/RetryAttemptEvent.php b/src/Events/RetryAttemptEvent.php
new file mode 100644
index 0000000..ea57f25
--- /dev/null
+++ b/src/Events/RetryAttemptEvent.php
@@ -0,0 +1,195 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Farzai\Transport\Events;
+
+use Psr\Http\Message\RequestInterface;
+use Throwable;
+
+/**
+ * Event dispatched before each retry attempt.
+ *
+ * This event is fired just before the retry middleware attempts to resend
+ * a failed request. It provides information about the failure and retry strategy.
+ *
+ * Use Cases:
+ * - Log retry attempts
+ * - Monitor retry behavior
+ * - Implement custom retry logic
+ * - Alert on excessive retries
+ * - Track retry success rates
+ *
+ * @example
+ * ```php
+ * $dispatcher->addEventListener(RetryAttemptEvent::class, function ($event) {
+ *     $this->logger->warning('Retrying request', [
+ *         'uri' => $event->getUri(),
+ *         'attempt' => $event->getAttemptNumber(),
+ *         'max_attempts' => $event->getMaxAttempts(),
+ *         'delay' => $event->getDelay(),
+ *         'reason' => $event->getReason()->getMessage(),
+ *     ]);
+ *
+ *     // Alert if approaching max retries
+ *     if ($event->getAttemptNumber() >= $event->getMaxAttempts() - 1) {
+ *         $this->alerts->retryExhaustion($event->getUri());
+ *     }
+ * });
+ * ```
+ */
+final class RetryAttemptEvent extends AbstractEvent
+{
+    private float $timestamp;
+
+    /**
+     * Create a new retry attempt event.
+     *
+     * @param  RequestInterface  $request  The PSR-7 request being retried
+     * @param  Throwable  $reason  The exception that triggered the retry
+     * @param  int  $attemptNumber  The attempt number (1-based, so 2 = first retry)
+     * @param  int  $maxAttempts  Maximum number of attempts configured
+     * @param  int  $delay  Delay before retry in milliseconds
+     * @param  float  $timestamp  Unix timestamp when retry will occur (microtime)
+     */
+    public function __construct(
+        private readonly RequestInterface $request,
+        private readonly Throwable $reason,
+        private readonly int $attemptNumber,
+        private readonly int $maxAttempts,
+        private readonly int $delay,
+        float $timestamp = 0.0
+    ) {
+        // Use current microtime if not provided
+        $this->timestamp = $timestamp === 0.0 ? microtime(true) : $timestamp;
+    }
+
+    /**
+     * Get the PSR-7 request being retried.
+     *
+     * @return RequestInterface The request
+     */
+    public function getRequest(): RequestInterface
+    {
+        return $this->request;
+    }
+
+    /**
+     * Get the exception that triggered the retry.
+     *
+     * @return Throwable The exception
+     */
+    public function getReason(): Throwable
+    {
+        return $this->reason;
+    }
+
+    /**
+     * Get the current attempt number.
+     *
+     * Note: This is 1-based, so:
+     * - 1 = initial attempt (not a retry)
+     * - 2 = first retry
+     * - 3 = second retry
+     *
+     * @return int Attempt number (1-based)
+     */
+    public function getAttemptNumber(): int
+    {
+        return $this->attemptNumber;
+    }
+
+    /**
+     * Get the maximum number of attempts configured.
+     *
+     * @return int Maximum attempts
+     */
+    public function getMaxAttempts(): int
+    {
+        return $this->maxAttempts;
+    }
+
+    /**
+     * Get the delay before retry in milliseconds.
+     *
+     * @return int Delay in milliseconds
+     */
+    public function getDelay(): int
+    {
+        return $this->delay;
+    }
+
+    /**
+     * Get the timestamp when the retry will occur.
+     *
+     * @return float Unix timestamp with microseconds
+     */
+    public function getTimestamp(): float
+    {
+        return $this->timestamp;
+    }
+
+    /**
+     * Get the HTTP method.
+     *
+     * @return string HTTP method (GET, POST, etc.)
+     */
+    public function getMethod(): string
+    {
+        return $this->request->getMethod();
+    }
+
+    /**
+     * Get the request URI.
+     *
+     * @return string The URI as a string
+     */
+    public function getUri(): string
+    {
+        return (string) $this->request->getUri();
+    }
+
+    /**
+     * Get the number of remaining attempts.
+     *
+     * @return int Remaining attempts (including this one)
+     */
+    public function getRemainingAttempts(): int
+    {
+        return $this->maxAttempts - $this->attemptNumber + 1;
+    }
+
+    /**
+     * Check if this is the last retry attempt.
+     *
+     * @return bool True if last attempt, false otherwise
+     */
+    public function isLastAttempt(): bool
+    {
+        return $this->attemptNumber >= $this->maxAttempts;
+    }
+
+    /**
+     * Get retry progress as a percentage.
+     *
+     * @return float Progress from 0.0 to 100.0
+     */
+    public function getProgress(): float
+    {
+        if ($this->maxAttempts <= 1) {
+            return 100.0;
+        }
+
+        return ($this->attemptNumber / $this->maxAttempts) * 100.0;
+    }
+
+    /**
+     * Get the delay in seconds (for readability).
+     *
+     * @return float Delay in seconds
+     */
+    public function getDelayInSeconds(): float
+    {
+        return $this->delay / 1000.0;
+    }
+}
diff --git a/src/Exceptions/HttpException.php b/src/Exceptions/HttpException.php
index 0c0ae96..dfab338 100644
--- a/src/Exceptions/HttpException.php
+++ b/src/Exceptions/HttpException.php
@@ -111,7 +111,7 @@ public function getContext(): array
             ],
         ];
 
-        if ($this->hasResponse()) {
+        if ($this->response !== null) {
             $context['response'] = [
                 'status_code' => $this->response->getStatusCode(),
                 'reason_phrase' => $this->response->getReasonPhrase(),
diff --git a/src/Exceptions/JsonEncodeException.php b/src/Exceptions/JsonEncodeException.php
index fbe8cd9..88114b3 100644
--- a/src/Exceptions/JsonEncodeException.php
+++ b/src/Exceptions/JsonEncodeException.php
@@ -50,9 +50,9 @@ public function __construct(
      * @param  mixed  $value  The value that failed to encode
      * @param  int  $depth  The nesting depth used
      */
-    public static function fromJsonException(\JsonException $exception, mixed $value, int $depth = 512): static
+    public static function fromJsonException(\JsonException $exception, mixed $value, int $depth = 512): self
     {
-        return new static(
+        return new self(
             message: sprintf('Failed to encode JSON: %s', $exception->getMessage()),
             value: $value,
             jsonErrorCode: $exception->getCode(),
diff --git a/src/Exceptions/JsonParseException.php b/src/Exceptions/JsonParseException.php
index b6d37ee..bcbfaec 100644
--- a/src/Exceptions/JsonParseException.php
+++ b/src/Exceptions/JsonParseException.php
@@ -49,9 +49,9 @@ public function __construct(
      * @param  string  $jsonString  The JSON string that failed to parse
      * @param  int  $depth  The nesting depth used
      */
-    public static function fromJsonException(\JsonException $exception, string $jsonString, int $depth = 512): static
+    public static function fromJsonException(\JsonException $exception, string $jsonString, int $depth = 512): self
     {
-        return new static(
+        return new self(
             message: sprintf('Failed to parse JSON: %s', $exception->getMessage()),
             jsonString: $jsonString,
             jsonErrorCode: $exception->getCode(),
diff --git a/src/Exceptions/ResponseExceptionFactory.php b/src/Exceptions/ResponseExceptionFactory.php
index eab9502..2cd1844 100644
--- a/src/Exceptions/ResponseExceptionFactory.php
+++ b/src/Exceptions/ResponseExceptionFactory.php
@@ -112,7 +112,7 @@ public static function getErrorMessage(ResponseInterface $response): string
         $statusCode = $response->statusCode();
 
         // Try to extract error from JSON response
-        $jsonError = static::extractJsonError($response);
+        $jsonError = self::extractJsonError($response);
         if ($jsonError !== null) {
             return $jsonError;
         }
diff --git a/src/Factory/HttpFactory.php b/src/Factory/HttpFactory.php
index 48d4e7a..e015bcc 100644
--- a/src/Factory/HttpFactory.php
+++ b/src/Factory/HttpFactory.php
@@ -167,7 +167,6 @@ public function createStream(string $content = ''): StreamInterface
      * @return StreamInterface The created stream
      *
      * @throws \RuntimeException If no stream factory is available
-     * @throws \InvalidArgumentException If resource is invalid
      */
     public function createStreamFromResource($resource): StreamInterface
     {
diff --git a/src/Middleware/EventMiddleware.php b/src/Middleware/EventMiddleware.php
new file mode 100644
index 0000000..cbf0f7d
--- /dev/null
+++ b/src/Middleware/EventMiddleware.php
@@ -0,0 +1,109 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Farzai\Transport\Middleware;
+
+use Farzai\Transport\Events\EventDispatcherInterface;
+use Farzai\Transport\Events\RequestFailedEvent;
+use Farzai\Transport\Events\RequestSendingEvent;
+use Farzai\Transport\Events\RequestSentEvent;
+use Farzai\Transport\Events\ResponseReceivedEvent;
+use Psr\Http\Message\RequestInterface;
+use Psr\Http\Message\ResponseInterface;
+
+/**
+ * Middleware that dispatches events during the HTTP lifecycle.
+ *
+ * Design Pattern: Observer Pattern + Middleware Pattern
+ * - Observes HTTP lifecycle through middleware pipeline
+ * - Dispatches events to registered listeners
+ * - Non-invasive (doesn't modify request/response)
+ *
+ * Events Dispatched:
+ * 1. RequestSendingEvent - Before request enters pipeline
+ * 2. RequestSentEvent - Immediately after HTTP client returns
+ * 3. ResponseReceivedEvent - After middleware unwinding completes
+ * 4. RequestFailedEvent - When request fails
+ *
+ * @example
+ * ```php
+ * $dispatcher = new EventDispatcher();
+ * $dispatcher->addEventListener(ResponseReceivedEvent::class, function ($event) {
+ *     $this->metrics->recordLatency($event->getDuration());
+ * });
+ *
+ * $transport = TransportBuilder::make()
+ *     ->withMiddleware(new EventMiddleware($dispatcher))
+ *     ->build();
+ * ```
+ */
+final class EventMiddleware implements MiddlewareInterface
+{
+    /**
+     * Create a new event middleware.
+     *
+     * @param  EventDispatcherInterface  $dispatcher  The event dispatcher
+     */
+    public function __construct(
+        private readonly EventDispatcherInterface $dispatcher
+    ) {}
+
+    /**
+     * {@inheritDoc}
+     */
+    public function handle(RequestInterface $request, callable $next): ResponseInterface
+    {
+        $startTime = microtime(true);
+
+        // Dispatch RequestSendingEvent
+        $this->dispatcher->dispatch(
+            new RequestSendingEvent($request, $startTime)
+        );
+
+        try {
+            // Call next middleware / HTTP client
+            $response = $next($request);
+
+            $sentTime = microtime(true);
+            $sentDuration = ($sentTime - $startTime) * 1000; // Convert to milliseconds
+
+            // Dispatch RequestSentEvent - immediately after HTTP client returns
+            $this->dispatcher->dispatch(
+                new RequestSentEvent($request, $response, $sentDuration, $sentTime)
+            );
+
+            $endTime = microtime(true);
+            $duration = ($endTime - $startTime) * 1000; // Total duration including middleware
+
+            // Dispatch ResponseReceivedEvent - after all processing
+            $this->dispatcher->dispatch(
+                new ResponseReceivedEvent($request, $response, $duration, $endTime)
+            );
+
+            return $response;
+        } catch (\Throwable $exception) {
+            $failureTime = microtime(true);
+
+            // Dispatch RequestFailedEvent
+            $this->dispatcher->dispatch(
+                new RequestFailedEvent($request, $exception, 1, $failureTime)
+            );
+
+            // Re-throw the exception
+            throw $exception;
+        }
+    }
+
+    /**
+     * Get the event dispatcher.
+     *
+     * Useful for tests or runtime inspection.
+     *
+     * @return EventDispatcherInterface The event dispatcher
+     */
+    public function getEventDispatcher(): EventDispatcherInterface
+    {
+        return $this->dispatcher;
+    }
+}
diff --git a/src/Middleware/RetryMiddleware.php b/src/Middleware/RetryMiddleware.php
index e6661c7..63f9559 100644
--- a/src/Middleware/RetryMiddleware.php
+++ b/src/Middleware/RetryMiddleware.php
@@ -4,6 +4,9 @@
 
 namespace Farzai\Transport\Middleware;
 
+use Farzai\Transport\Events\EventDispatcherInterface;
+use Farzai\Transport\Events\RequestFailedEvent;
+use Farzai\Transport\Events\RetryAttemptEvent;
 use Farzai\Transport\Exceptions\RetryExhaustedException;
 use Farzai\Transport\Retry\RetryCondition;
 use Farzai\Transport\Retry\RetryContext;
@@ -17,9 +20,13 @@ class RetryMiddleware implements MiddlewareInterface
     public function __construct(
         private readonly int $maxAttempts,
         private readonly RetryStrategyInterface $strategy,
-        private readonly RetryCondition $condition
+        private readonly RetryCondition $condition,
+        private readonly ?EventDispatcherInterface $eventDispatcher = null
     ) {}
 
+    /**
+     * @throws \Farzai\Transport\Exceptions\RetryExhaustedException
+     */
     public function handle(RequestInterface $request, callable $next): ResponseInterface
     {
         $context = new RetryContext(
@@ -32,6 +39,18 @@ public function handle(RequestInterface $request, callable $next): ResponseInter
             try {
                 return $next($request);
             } catch (Throwable $exception) {
+                // Dispatch RequestFailedEvent for each failure attempt
+                if ($this->eventDispatcher !== null) {
+                    $this->eventDispatcher->dispatch(
+                        new RequestFailedEvent(
+                            $request,
+                            $exception,
+                            $context->attempt + 1, // 1-based attempt number
+                            microtime(true)
+                        )
+                    );
+                }
+
                 // Check if we should retry
                 if (! $this->condition->shouldRetry($exception, $context)) {
                     if ($context->attempt > 0) {
@@ -55,6 +74,20 @@ public function handle(RequestInterface $request, callable $next): ResponseInter
                 $delay = $this->strategy->getDelay($context);
                 $context = $context->nextAttempt($exception, $delay);
 
+                // Dispatch RetryAttemptEvent before retry
+                if ($this->eventDispatcher !== null) {
+                    $this->eventDispatcher->dispatch(
+                        new RetryAttemptEvent(
+                            $request,
+                            $exception,
+                            $context->attempt + 1, // Current attempt number (after increment)
+                            $this->maxAttempts,
+                            $delay,
+                            microtime(true)
+                        )
+                    );
+                }
+
                 // Sleep before retry (convert milliseconds to microseconds)
                 if ($delay > 0) {
                     usleep($delay * 1000);
diff --git a/src/Multipart/MultipartBuilderFactory.php b/src/Multipart/MultipartBuilderFactory.php
new file mode 100644
index 0000000..6e48292
--- /dev/null
+++ b/src/Multipart/MultipartBuilderFactory.php
@@ -0,0 +1,258 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Farzai\Transport\Multipart;
+
+use Farzai\Transport\Factory\HttpFactory;
+
+/**
+ * Factory for creating the appropriate multipart builder based on content size.
+ *
+ * Design Pattern: Factory Pattern + Strategy Pattern
+ * - Encapsulates builder selection logic
+ * - Auto-selects optimal strategy based on file sizes
+ * - Provides consistent interface regardless of strategy
+ *
+ * Selection Strategy:
+ * - Total size < threshold: Standard builder (faster for small files)
+ * - Total size >= threshold: Streaming builder (memory-efficient for large files)
+ *
+ * Default Threshold: 10 MB
+ *
+ * @example
+ * ```php
+ * // Auto-selection based on file sizes
+ * $builder = MultipartBuilderFactory::create($httpFactory, $parts);
+ *
+ * // Force streaming builder
+ * $builder = MultipartBuilderFactory::createStreaming($httpFactory);
+ *
+ * // Force standard builder
+ * $builder = MultipartBuilderFactory::createStandard($httpFactory);
+ *
+ * // Custom threshold (50 MB)
+ * $builder = MultipartBuilderFactory::create(
+ *     $httpFactory,
+ *     $parts,
+ *     streamingThreshold: 50 * 1024 * 1024
+ * );
+ * ```
+ */
+final class MultipartBuilderFactory
+{
+    /**
+     * Default threshold for switching to streaming (10 MB).
+     */
+    public const DEFAULT_STREAMING_THRESHOLD = 10 * 1024 * 1024;
+
+    /**
+     * Create a multipart builder, auto-selecting based on content size.
+     *
+     * @param  HttpFactory|null  $httpFactory  Optional HTTP factory
+     * @param  array<array<string, mixed>>|null  $parts  Optional parts array to analyze
+     * @param  int  $streamingThreshold  Size threshold in bytes (default 10 MB)
+     * @param  string|null  $boundary  Optional custom boundary
+     */
+    public static function create(
+        ?HttpFactory $httpFactory = null,
+        ?array $parts = null,
+        int $streamingThreshold = self::DEFAULT_STREAMING_THRESHOLD,
+        ?string $boundary = null
+    ): MultipartStreamBuilder|StreamingMultipartBuilder {
+        $httpFactory = $httpFactory ?? HttpFactory::getInstance();
+
+        // If no parts provided, default to standard builder
+        if ($parts === null || empty($parts)) {
+            return new MultipartStreamBuilder($boundary, $httpFactory);
+        }
+
+        // Calculate total size of all parts
+        $totalSize = self::calculateTotalSize($parts);
+
+        // If size cannot be determined, use streaming to be safe
+        if ($totalSize === null) {
+            return new StreamingMultipartBuilder($httpFactory, $boundary);
+        }
+
+        // Select builder based on total size
+        if ($totalSize >= $streamingThreshold) {
+            return new StreamingMultipartBuilder($httpFactory, $boundary);
+        }
+
+        return new MultipartStreamBuilder($boundary, $httpFactory);
+    }
+
+    /**
+     * Create a standard (non-streaming) multipart builder.
+     *
+     * Use for small files where speed is more important than memory efficiency.
+     *
+     * @param  HttpFactory|null  $httpFactory  Optional HTTP factory
+     * @param  string|null  $boundary  Optional custom boundary
+     */
+    public static function createStandard(
+        ?HttpFactory $httpFactory = null,
+        ?string $boundary = null
+    ): MultipartStreamBuilder {
+        $httpFactory = $httpFactory ?? HttpFactory::getInstance();
+
+        return new MultipartStreamBuilder($boundary, $httpFactory);
+    }
+
+    /**
+     * Create a streaming multipart builder.
+     *
+     * Use for large files or when memory efficiency is critical.
+     *
+     * @param  HttpFactory|null  $httpFactory  Optional HTTP factory
+     * @param  string|null  $boundary  Optional custom boundary
+     * @param  int  $chunkSize  Chunk size in bytes (default 8192)
+     */
+    public static function createStreaming(
+        ?HttpFactory $httpFactory = null,
+        ?string $boundary = null,
+        int $chunkSize = 8192
+    ): StreamingMultipartBuilder {
+        $httpFactory = $httpFactory ?? HttpFactory::getInstance();
+
+        return new StreamingMultipartBuilder($httpFactory, $boundary, $chunkSize);
+    }
+
+    /**
+     * Get the recommended builder type for a given size.
+     *
+     * @param  int  $totalBytes  Total size in bytes
+     * @param  int  $threshold  Streaming threshold in bytes
+     * @return class-string<MultipartStreamBuilder|StreamingMultipartBuilder>
+     */
+    public static function getRecommendedBuilder(
+        int $totalBytes,
+        int $threshold = self::DEFAULT_STREAMING_THRESHOLD
+    ): string {
+        if ($totalBytes >= $threshold) {
+            return StreamingMultipartBuilder::class;
+        }
+
+        return MultipartStreamBuilder::class;
+    }
+
+    /**
+     * Check if streaming is recommended for given parts.
+     *
+     * @param  array<array<string, mixed>>  $parts  The parts to analyze
+     * @param  int  $threshold  Streaming threshold in bytes
+     * @return bool True if streaming recommended, false otherwise
+     */
+    public static function shouldUseStreaming(
+        array $parts,
+        int $threshold = self::DEFAULT_STREAMING_THRESHOLD
+    ): bool {
+        $totalSize = self::calculateTotalSize($parts);
+
+        // If size unknown, recommend streaming to be safe
+        if ($totalSize === null) {
+            return true;
+        }
+
+        return $totalSize >= $threshold;
+    }
+
+    /**
+     * Calculate total size of all parts.
+     *
+     * Returns null if any part's size cannot be determined.
+     *
+     * @param  array<array<string, mixed>>  $parts
+     * @return int|null Total size in bytes, or null if unknown
+     */
+    private static function calculateTotalSize(array $parts): ?int
+    {
+        $totalSize = 0;
+
+        foreach ($parts as $part) {
+            if (! is_array($part)) {
+                continue;
+            }
+
+            $contents = $part['contents'] ?? null;
+            $filename = $part['filename'] ?? null;
+
+            // Skip if no contents
+            if ($contents === null) {
+                continue;
+            }
+
+            // File path
+            if (is_string($contents) && $filename !== null && is_file($contents)) {
+                $size = filesize($contents);
+                if ($size === false) {
+                    return null; // Cannot determine size
+                }
+                $totalSize += $size;
+
+                continue;
+            }
+
+            // String contents
+            if (is_string($contents)) {
+                $totalSize += strlen($contents);
+
+                continue;
+            }
+
+            // Stream contents
+            if ($contents instanceof \Psr\Http\Message\StreamInterface) {
+                $size = $contents->getSize();
+                if ($size === null) {
+                    return null; // Cannot determine size
+                }
+                $totalSize += $size;
+
+                continue;
+            }
+
+            // Unknown content type
+            return null;
+        }
+
+        return $totalSize;
+    }
+
+    /**
+     * Format size in human-readable format.
+     *
+     * @param  int  $bytes  Size in bytes
+     * @return string Formatted size (e.g., "10.5 MB")
+     */
+    public static function formatSize(int $bytes): string
+    {
+        $units = ['B', 'KB', 'MB', 'GB', 'TB'];
+        $power = $bytes > 0 ? floor(log($bytes, 1024)) : 0;
+        $power = min($power, count($units) - 1);
+
+        $size = $bytes / pow(1024, $power);
+
+        return sprintf('%.1f %s', $size, $units[$power]);
+    }
+
+    /**
+     * Get the default streaming threshold.
+     *
+     * @return int Threshold in bytes (10 MB)
+     */
+    public static function getDefaultThreshold(): int
+    {
+        return self::DEFAULT_STREAMING_THRESHOLD;
+    }
+
+    /**
+     * Get the default streaming threshold in human-readable format.
+     *
+     * @return string Formatted threshold (e.g., "10.0 MB")
+     */
+    public static function getDefaultThresholdFormatted(): string
+    {
+        return self::formatSize(self::DEFAULT_STREAMING_THRESHOLD);
+    }
+}
diff --git a/src/Multipart/MultipartStream.php b/src/Multipart/MultipartStream.php
new file mode 100644
index 0000000..6b2d1b4
--- /dev/null
+++ b/src/Multipart/MultipartStream.php
@@ -0,0 +1,352 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Farzai\Transport\Multipart;
+
+use Psr\Http\Message\StreamInterface;
+
+/**
+ * Custom PSR-7 stream implementation for streaming multipart data.
+ *
+ * Design Pattern: Iterator Pattern
+ * - Implements lazy evaluation
+ * - Yields data chunks on-demand
+ * - Maintains internal state (position, current part, etc.)
+ *
+ * Memory Characteristics:
+ * - O(1) memory usage (constant, regardless of data size)
+ * - Only chunk size in memory at any time (~8KB default)
+ * - Files never fully loaded into memory
+ *
+ * Limitations:
+ * - Cannot seek (not seekable)
+ * - Cannot rewind (one-time read)
+ * - Cannot get size upfront (unknown size)
+ *
+ * @example
+ * ```php
+ * $stream = new MultipartStream($parts, $boundary, 8192);
+ *
+ * // Read in chunks
+ * while (!$stream->eof()) {
+ *     $chunk = $stream->read(8192);
+ *     // Send chunk...
+ * }
+ * ```
+ */
+final class MultipartStream implements StreamInterface
+{
+    /**
+     * @var array<Part>
+     */
+    private array $parts;
+
+    private string $boundary;
+
+    private int $chunkSize;
+
+    /**
+     * Current state of the stream.
+     */
+    private int $currentPartIndex = 0;
+
+    /** @var resource|null */
+    private $currentFileHandle = null;
+
+    private string $buffer = '';
+
+    private bool $eof = false;
+
+    private int $position = 0;
+
+    /**
+     * Whether we've written the boundary for the current part.
+     */
+    private bool $currentPartBoundaryWritten = false;
+
+    /**
+     * Whether we've written the headers for the current part.
+     */
+    private bool $currentPartHeadersWritten = false;
+
+    /**
+     * Whether we've written the content for the current part.
+     */
+    private bool $currentPartContentWritten = false;
+
+    /**
+     * Create a new multipart stream.
+     *
+     * @param  array<Part>  $parts  The parts to stream
+     * @param  string  $boundary  The boundary string
+     * @param  int  $chunkSize  Chunk size for reading files
+     */
+    public function __construct(
+        array $parts,
+        string $boundary,
+        int $chunkSize
+    ) {
+        $this->parts = $parts;
+        $this->boundary = $boundary;
+        $this->chunkSize = $chunkSize;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function __toString(): string
+    {
+        try {
+            $this->rewind();
+
+            return $this->getContents();
+        } catch (\Throwable $e) {
+            return '';
+        }
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function close(): void
+    {
+        if ($this->currentFileHandle !== null) {
+            fclose($this->currentFileHandle);
+            $this->currentFileHandle = null;
+        }
+
+        $this->eof = true;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function detach()
+    {
+        $handle = $this->currentFileHandle;
+        $this->currentFileHandle = null;
+        $this->eof = true;
+
+        return $handle;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getSize(): ?int
+    {
+        // Cannot determine size without reading all data
+        return null;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function tell(): int
+    {
+        return $this->position;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function eof(): bool
+    {
+        return $this->eof;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function isSeekable(): bool
+    {
+        return false;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function seek(int $offset, int $whence = SEEK_SET): void
+    {
+        throw new \RuntimeException('Stream is not seekable');
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function rewind(): void
+    {
+        throw new \RuntimeException('Stream cannot be rewound');
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function isWritable(): bool
+    {
+        return false;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function write(string $string): int
+    {
+        throw new \RuntimeException('Stream is not writable');
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function isReadable(): bool
+    {
+        return true;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function read(int $length): string
+    {
+        if ($this->eof) {
+            return '';
+        }
+
+        // Fill buffer until we have enough data or reach EOF
+        while (strlen($this->buffer) < $length && ! $this->eof) {
+            $this->fillBuffer();
+        }
+
+        // Extract requested amount from buffer
+        $data = substr($this->buffer, 0, $length);
+        $this->buffer = substr($this->buffer, $length);
+        $this->position += strlen($data);
+
+        return $data;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getContents(): string
+    {
+        $contents = '';
+
+        while (! $this->eof()) {
+            $contents .= $this->read($this->chunkSize);
+        }
+
+        return $contents;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getMetadata(?string $key = null): mixed
+    {
+        $metadata = [
+            'boundary' => $this->boundary,
+            'chunk_size' => $this->chunkSize,
+            'parts_count' => count($this->parts),
+            'current_part' => $this->currentPartIndex,
+            'eof' => $this->eof,
+        ];
+
+        if ($key === null) {
+            return $metadata;
+        }
+
+        return $metadata[$key] ?? null;
+    }
+
+    /**
+     * Fill the internal buffer with more data.
+     *
+     * This is where the actual streaming magic happens.
+     */
+    private function fillBuffer(): void
+    {
+        // Check if we've processed all parts
+        if ($this->currentPartIndex >= count($this->parts)) {
+            // Add closing boundary
+            if (! $this->eof) {
+                $this->buffer .= "--{$this->boundary}--\r\n";
+                $this->eof = true;
+            }
+
+            return;
+        }
+
+        $part = $this->parts[$this->currentPartIndex];
+
+        // Write part boundary
+        if (! $this->currentPartBoundaryWritten) {
+            $this->buffer .= "--{$this->boundary}\r\n";
+            $this->currentPartBoundaryWritten = true;
+
+            return;
+        }
+
+        // Write part headers
+        if (! $this->currentPartHeadersWritten) {
+            foreach ($part->getHeaders() as $name => $value) {
+                $this->buffer .= "{$name}: {$value}\r\n";
+            }
+            $this->buffer .= "\r\n"; // Header/body separator
+            $this->currentPartHeadersWritten = true;
+
+            return;
+        }
+
+        // Write part content
+        if (! $this->currentPartContentWritten) {
+            $contents = $part->getContents();
+
+            if ($contents instanceof StreamInterface) {
+                // Stream file in chunks
+                if ($this->currentFileHandle === null) {
+                    // Get underlying resource or read from stream
+                    $data = $contents->read($this->chunkSize);
+                    if ($data !== '') {
+                        $this->buffer .= $data;
+
+                        return;
+                    }
+                }
+
+                // If stream is EOF, mark content as written
+                if ($contents->eof()) {
+                    $this->currentPartContentWritten = true;
+                    $this->buffer .= "\r\n";
+                }
+            } else {
+                // String content - add all at once
+                $this->buffer .= $contents;
+                $this->currentPartContentWritten = true;
+                $this->buffer .= "\r\n";
+            }
+
+            return;
+        }
+
+        // Move to next part
+        $this->currentPartIndex++;
+        $this->currentPartBoundaryWritten = false;
+        $this->currentPartHeadersWritten = false;
+        $this->currentPartContentWritten = false;
+
+        if ($this->currentFileHandle !== null) {
+            fclose($this->currentFileHandle);
+            $this->currentFileHandle = null;
+        }
+    }
+
+    /**
+     * Destructor - ensure file handles are closed.
+     */
+    public function __destruct()
+    {
+        $this->close();
+    }
+}
diff --git a/src/Multipart/Part.php b/src/Multipart/Part.php
index 79b844b..3b6d592 100644
--- a/src/Multipart/Part.php
+++ b/src/Multipart/Part.php
@@ -25,7 +25,7 @@ final class Part
      * Create a new multipart part.
      *
      * @param  string  $name  The field name
-     * @param  StreamInterface|string|resource  $contents  The content stream or string
+     * @param  StreamInterface|string  $contents  The content stream or string
      * @param  string|null  $filename  Optional filename (for file uploads)
      * @param  array<string, string>  $headers  Optional custom headers
      */
diff --git a/src/Multipart/StreamingMultipartBuilder.php b/src/Multipart/StreamingMultipartBuilder.php
new file mode 100644
index 0000000..7fcf066
--- /dev/null
+++ b/src/Multipart/StreamingMultipartBuilder.php
@@ -0,0 +1,347 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Farzai\Transport\Multipart;
+
+use Farzai\Transport\Factory\HttpFactory;
+use Psr\Http\Message\StreamInterface;
+
+/**
+ * Streaming builder for creating memory-efficient multipart/form-data streams.
+ *
+ * Design Pattern: Iterator Pattern
+ * - Yields data chunks on-demand (lazy evaluation)
+ * - Reads files in small chunks (8KB default)
+ * - Constant memory usage regardless of file size
+ *
+ * Use Cases:
+ * - Large file uploads (>= 10 MB)
+ * - Multiple file uploads
+ * - Memory-constrained environments
+ * - Concurrent uploads
+ *
+ * Differences from MultipartStreamBuilder:
+ * - MultipartStreamBuilder: Loads entire body into memory (fast for small files)
+ * - StreamingMultipartBuilder: Streams in chunks (memory-efficient for large files)
+ *
+ * @example
+ * ```php
+ * $builder = new StreamingMultipartBuilder($httpFactory);
+ * $stream = $builder
+ *     ->addFile('video', '/path/to/large-video.mp4')
+ *     ->addField('title', 'My Video')
+ *     ->build();
+ *
+ * // File read in 8KB chunks during transmission, not loaded upfront
+ * $response = $transport->request()
+ *     ->withBody($stream)
+ *     ->withHeader('Content-Type', $builder->getContentType())
+ *     ->post('/upload');
+ * ```
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc7578
+ */
+final class StreamingMultipartBuilder
+{
+    /**
+     * @var array<Part>
+     */
+    private array $parts = [];
+
+    private readonly string $boundary;
+
+    private readonly HttpFactory $httpFactory;
+
+    /**
+     * Chunk size for reading files (8KB default).
+     *
+     * Smaller = Lower memory, more CPU
+     * Larger = Higher memory, less CPU
+     */
+    private int $chunkSize = 8192;
+
+    /**
+     * Create a new streaming multipart builder.
+     *
+     * @param  HttpFactory|null  $httpFactory  Optional HTTP factory
+     * @param  string|null  $boundary  Optional custom boundary
+     * @param  int  $chunkSize  Chunk size in bytes (default 8192)
+     */
+    public function __construct(
+        ?HttpFactory $httpFactory = null,
+        ?string $boundary = null,
+        int $chunkSize = 8192
+    ) {
+        $this->httpFactory = $httpFactory ?? HttpFactory::getInstance();
+        $this->boundary = $boundary ?? $this->generateBoundary();
+        $this->chunkSize = max(1024, $chunkSize); // Minimum 1KB
+    }
+
+    /**
+     * Add a text field.
+     *
+     * @param  string  $name  Field name
+     * @param  string  $value  Field value
+     * @return $this
+     */
+    public function addField(string $name, string $value): self
+    {
+        $this->parts[] = Part::text($name, $value);
+
+        return $this;
+    }
+
+    /**
+     * Add a file from a path (will be streamed during upload).
+     *
+     * @param  string  $name  Field name
+     * @param  string  $path  File path
+     * @param  string|null  $filename  Optional custom filename
+     * @param  string|null  $contentType  Optional content type
+     * @return $this
+     *
+     * @throws \RuntimeException If file cannot be read
+     */
+    public function addFile(
+        string $name,
+        string $path,
+        ?string $filename = null,
+        ?string $contentType = null
+    ): self {
+        if (! is_readable($path)) {
+            throw new \RuntimeException("File not readable: {$path}");
+        }
+
+        if (! is_file($path)) {
+            throw new \RuntimeException("Not a file: {$path}");
+        }
+
+        $filename = $filename ?? basename($path);
+
+        // Store path instead of loading file - will be streamed later
+        $stream = $this->httpFactory->createStreamFromFile($path, 'r');
+        $this->parts[] = Part::file($name, $stream, $filename, $contentType);
+
+        return $this;
+    }
+
+    /**
+     * Add a file from contents.
+     *
+     * Note: If contents is a string, it will be loaded into memory.
+     * For large content, use addFile() with a file path instead.
+     *
+     * @param  string  $name  Field name
+     * @param  StreamInterface|string  $contents  File contents
+     * @param  string  $filename  Filename
+     * @param  string|null  $contentType  Optional content type
+     * @return $this
+     */
+    public function addFileContents(
+        string $name,
+        StreamInterface|string $contents,
+        string $filename,
+        ?string $contentType = null
+    ): self {
+        $this->parts[] = Part::file($name, $contents, $filename, $contentType);
+
+        return $this;
+    }
+
+    /**
+     * Add a custom part.
+     *
+     * @param  Part  $part  The part to add
+     * @return $this
+     */
+    public function addPart(Part $part): self
+    {
+        $this->parts[] = $part;
+
+        return $this;
+    }
+
+    /**
+     * Add multiple parts from an array.
+     *
+     * @param  array<mixed>  $parts
+     * @return $this
+     */
+    public function addMultiple(array $parts): self
+    {
+        foreach ($parts as $key => $value) {
+            if (is_array($value) && isset($value['name'], $value['contents'])) {
+                $this->addFromArray($value);
+            } elseif (is_string($key)) {
+                $this->addField($key, (string) $value);
+            }
+        }
+
+        return $this;
+    }
+
+    /**
+     * Get the boundary string.
+     */
+    public function getBoundary(): string
+    {
+        return $this->boundary;
+    }
+
+    /**
+     * Get the Content-Type header value.
+     */
+    public function getContentType(): string
+    {
+        return 'multipart/form-data; boundary='.$this->boundary;
+    }
+
+    /**
+     * Set chunk size for file reading.
+     *
+     * @param  int  $bytes  Chunk size in bytes (minimum 1024)
+     * @return $this
+     */
+    public function setChunkSize(int $bytes): self
+    {
+        $this->chunkSize = max(1024, $bytes);
+
+        return $this;
+    }
+
+    /**
+     * Get the chunk size.
+     */
+    public function getChunkSize(): int
+    {
+        return $this->chunkSize;
+    }
+
+    /**
+     * Build the streaming multipart stream.
+     *
+     * Returns a custom StreamInterface that yields data on-demand.
+     * The stream uses the Iterator pattern internally to read file chunks lazily.
+     *
+     * @return StreamInterface The streaming multipart stream
+     */
+    public function build(): StreamInterface
+    {
+        return new MultipartStream(
+            $this->parts,
+            $this->boundary,
+            $this->chunkSize
+        );
+    }
+
+    /**
+     * Get all parts.
+     *
+     * @return array<Part>
+     */
+    public function getParts(): array
+    {
+        return $this->parts;
+    }
+
+    /**
+     * Count the number of parts.
+     */
+    public function count(): int
+    {
+        return count($this->parts);
+    }
+
+    /**
+     * Calculate total size of the multipart body.
+     *
+     * Note: This may be slow for large files as it needs to determine each part's size.
+     * Returns null if size cannot be determined.
+     */
+    public function getSize(): ?int
+    {
+        $size = 0;
+
+        foreach ($this->parts as $part) {
+            // Boundary + CRLF
+            $size += strlen("--{$this->boundary}\r\n");
+
+            // Headers
+            foreach ($part->getHeaders() as $name => $value) {
+                $size += strlen("{$name}: {$value}\r\n");
+            }
+
+            // Header/body separator
+            $size += 2; // \r\n
+
+            // Content size
+            $partSize = $part->getSize();
+            if ($partSize === null) {
+                return null; // Cannot determine size
+            }
+            $size += $partSize;
+
+            // CRLF after content
+            $size += 2;
+        }
+
+        // Closing boundary
+        $size += strlen("--{$this->boundary}--\r\n");
+
+        return $size;
+    }
+
+    /**
+     * Add a part from array configuration.
+     *
+     * @param  array<string, mixed>  $config
+     */
+    private function addFromArray(array $config): void
+    {
+        $name = (string) $config['name'];
+        $contents = $config['contents'];
+        $filename = $config['filename'] ?? null;
+        $contentType = $config['content-type'] ?? $config['contentType'] ?? null;
+
+        // File path
+        if (is_string($contents) && isset($config['filename']) && is_file($contents)) {
+            $this->addFile($name, $contents, $filename, $contentType);
+
+            return;
+        }
+
+        // File with contents
+        if ($filename !== null) {
+            if (is_string($contents)) {
+                $contents = $this->httpFactory->createStream($contents);
+            }
+
+            $this->addFileContents($name, $contents, $filename, $contentType);
+
+            return;
+        }
+
+        // Regular field
+        $this->addField($name, (string) $contents);
+    }
+
+    /**
+     * Generate a unique boundary string.
+     */
+    private function generateBoundary(): string
+    {
+        return '----TransportPHPStreaming'.bin2hex(random_bytes(16));
+    }
+
+    /**
+     * Create a new builder instance.
+     *
+     * @param  HttpFactory|null  $httpFactory  Optional HTTP factory
+     * @param  string|null  $boundary  Optional custom boundary
+     */
+    public static function create(?HttpFactory $httpFactory = null, ?string $boundary = null): self
+    {
+        return new self($httpFactory, $boundary);
+    }
+}
diff --git a/src/RequestBuilder.php b/src/RequestBuilder.php
index 100e055..e3924c8 100644
--- a/src/RequestBuilder.php
+++ b/src/RequestBuilder.php
@@ -109,7 +109,7 @@ public function withBody(StreamInterface|string $body): self
      *
      * @param  mixed  $data  The data to encode as JSON
      *
-     * @throws \Farzai\Transport\Exceptions\JsonEncodeException When encoding fails
+     * @throws \Farzai\Transport\Exceptions\SerializationException When encoding fails
      */
     public function withJson(mixed $data): self
     {
@@ -271,7 +271,10 @@ public function send(): ResponseInterface
             throw new \RuntimeException('No transport instance available. Use Transport::request() or provide transport in constructor.');
         }
 
-        return $this->transport->sendRequest($this->build());
+        $request = $this->build();
+        $psrResponse = $this->transport->sendRequest($request);
+
+        return new Response($request, $psrResponse, $this->serializer);
     }
 
     // Convenience methods for HTTP verbs
diff --git a/src/Response.php b/src/Response.php
index fe55d0a..651a2cb 100644
--- a/src/Response.php
+++ b/src/Response.php
@@ -84,7 +84,7 @@ public function isSuccessful(): bool
      * @param  string|null  $key  Optional dot-notation key path (e.g., "user.name")
      * @return mixed The decoded JSON data
      *
-     * @throws \Farzai\Transport\Exceptions\JsonParseException
+     * @throws \Farzai\Transport\Exceptions\SerializationException
      */
     public function json(?string $key = null): mixed
     {
@@ -116,6 +116,8 @@ public function json(?string $key = null): mixed
      *
      * @param  string|null  $key  Optional dot-notation key path
      * @return mixed The decoded data or null on failure
+     *
+     * @throws \Farzai\Transport\Exceptions\SerializationException
      */
     public function jsonOrNull(?string $key = null): mixed
     {
@@ -131,7 +133,7 @@ public function jsonOrNull(?string $key = null): mixed
      *
      * @return array<mixed>
      *
-     * @throws \Farzai\Transport\Exceptions\JsonParseException
+     * @throws \Farzai\Transport\Exceptions\SerializationException
      */
     public function toArray(): array
     {
@@ -149,13 +151,11 @@ public function toArray(): array
      *
      * @param  callable|null  $callback  Custom callback to throw an exception.
      * @return $this
-     *
-     * @throws \Psr\Http\Client\ClientExceptionInterface
      */
-    public function throw(?callable $callback = null)
+    public function throw(?callable $callback = null): static
     {
-        $callback = $callback ?? function (ResponseInterface $response, ?\Exception $e) {
-            if (! $this->isSuccessful()) {
+        $callback = $callback ?? function (ResponseInterface $response, ?\Throwable $e) {
+            if (! $this->isSuccessful() && $e !== null) {
                 throw $e;
             }
 
@@ -226,6 +226,7 @@ public function getBody(): StreamInterface
 
     public function withProtocolVersion(string $version): static
     {
+        /** @phpstan-ignore-next-line */
         return new static($this->request, $this->response->withProtocolVersion($version), $this->serializer);
     }
 
@@ -234,6 +235,7 @@ public function withProtocolVersion(string $version): static
      */
     public function withHeader(string $name, $value): static
     {
+        /** @phpstan-ignore-next-line */
         return new static($this->request, $this->response->withHeader($name, $value), $this->serializer);
     }
 
@@ -242,21 +244,25 @@ public function withHeader(string $name, $value): static
      */
     public function withAddedHeader(string $name, $value): static
     {
+        /** @phpstan-ignore-next-line */
         return new static($this->request, $this->response->withAddedHeader($name, $value), $this->serializer);
     }
 
     public function withoutHeader(string $name): static
     {
+        /** @phpstan-ignore-next-line */
         return new static($this->request, $this->response->withoutHeader($name), $this->serializer);
     }
 
     public function withBody(StreamInterface $body): static
     {
+        /** @phpstan-ignore-next-line */
         return new static($this->request, $this->response->withBody($body), $this->serializer);
     }
 
     public function withStatus(int $code, string $reasonPhrase = ''): static
     {
+        /** @phpstan-ignore-next-line */
         return new static($this->request, $this->response->withStatus($code, $reasonPhrase), $this->serializer);
     }
 
diff --git a/src/ResponseBuilder.php b/src/ResponseBuilder.php
index 8815e97..1599594 100644
--- a/src/ResponseBuilder.php
+++ b/src/ResponseBuilder.php
@@ -40,9 +40,9 @@ public function __construct(?HttpFactory $httpFactory = null)
     /**
      * Create a new response builder instance.
      */
-    public static function create(?HttpFactory $httpFactory = null): ResponseBuilder
+    public static function create(?HttpFactory $httpFactory = null): self
     {
-        return new static($httpFactory);
+        return new self($httpFactory);
     }
 
     /**
diff --git a/src/Serialization/JsonSerializer.php b/src/Serialization/JsonSerializer.php
index 8c50372..6cd5097 100644
--- a/src/Serialization/JsonSerializer.php
+++ b/src/Serialization/JsonSerializer.php
@@ -49,11 +49,18 @@ public function __construct(
     public function encode(mixed $data): string
     {
         try {
-            return json_encode(
+            $result = json_encode(
                 value: $data,
                 flags: $this->config->encodeFlags,
-                depth: $this->config->maxDepth
+                depth: max(1, $this->config->maxDepth)
             );
+
+            // With JSON_THROW_ON_ERROR, this should never be false, but satisfy PHPStan
+            if ($result === false) {
+                throw new \JsonException('JSON encoding failed');
+            }
+
+            return $result;
         } catch (\JsonException $e) {
             throw JsonEncodeException::fromJsonException($e, $data, $this->config->maxDepth);
         }
@@ -82,7 +89,7 @@ public function decode(string $data, ?string $key = null): mixed
             $decoded = json_decode(
                 json: $data,
                 associative: $this->config->associative,
-                depth: $this->config->maxDepth,
+                depth: max(1, $this->config->maxDepth),
                 flags: $this->config->decodeFlags
             );
 
@@ -153,7 +160,9 @@ private function extractValue(mixed $data, string $key): mixed
 
         // If data is an object, convert to array for extraction
         if (is_object($data)) {
-            return Arr::get(json_decode(json_encode($data), true), $key);
+            $json = json_encode($data, JSON_THROW_ON_ERROR);
+
+            return Arr::get(json_decode($json, true), $key);
         }
 
         // For scalar values, only return if key is empty
diff --git a/src/TransportBuilder.php b/src/TransportBuilder.php
index f88f240..dbf7671 100644
--- a/src/TransportBuilder.php
+++ b/src/TransportBuilder.php
@@ -5,8 +5,12 @@
 namespace Farzai\Transport;
 
 use Farzai\Transport\Cookie\CookieJar;
+use Farzai\Transport\Events\EventDispatcher;
+use Farzai\Transport\Events\EventDispatcherInterface;
+use Farzai\Transport\Events\EventInterface;
 use Farzai\Transport\Factory\ClientFactory;
 use Farzai\Transport\Middleware\CookieMiddleware;
+use Farzai\Transport\Middleware\EventMiddleware;
 use Farzai\Transport\Middleware\LoggingMiddleware;
 use Farzai\Transport\Middleware\MiddlewareInterface;
 use Farzai\Transport\Middleware\RetryMiddleware;
@@ -48,6 +52,8 @@ final class TransportBuilder
 
     private ?CookieJar $cookieJar = null;
 
+    private ?EventDispatcherInterface $eventDispatcher = null;
+
     /**
      * Create a new builder instance.
      */
@@ -175,6 +181,53 @@ public function withCookies(): self
         return $this->withCookieJar();
     }
 
+    /**
+     * Configure event dispatcher for HTTP lifecycle monitoring.
+     *
+     * @param  EventDispatcherInterface|null  $dispatcher  Optional custom event dispatcher
+     * @return $this
+     */
+    public function withEventDispatcher(?EventDispatcherInterface $dispatcher = null): self
+    {
+        $clone = clone $this;
+        $clone->eventDispatcher = $dispatcher ?? new EventDispatcher;
+
+        return $clone;
+    }
+
+    /**
+     * Add an event listener for HTTP lifecycle events.
+     *
+     * This is a convenience method that creates an EventDispatcher if needed
+     * and registers the listener.
+     *
+     * @param  class-string<EventInterface>  $eventClass  The event class to listen for
+     * @param  callable(EventInterface): void  $listener  The listener callable
+     * @return $this
+     *
+     * @example
+     * ```php
+     * $transport = TransportBuilder::make()
+     *     ->addEventListener(ResponseReceivedEvent::class, function ($event) {
+     *         echo "Request completed in {$event->getDuration()}ms\n";
+     *     })
+     *     ->build();
+     * ```
+     */
+    public function addEventListener(string $eventClass, callable $listener): self
+    {
+        $clone = clone $this;
+
+        // Create dispatcher if not exists
+        if ($clone->eventDispatcher === null) {
+            $clone->eventDispatcher = new EventDispatcher;
+        }
+
+        $clone->eventDispatcher->addEventListener($eventClass, $listener);
+
+        return $clone;
+    }
+
     /**
      * Get the configured client.
      */
@@ -214,7 +267,8 @@ public function build(): Transport
             maxRetries: $this->maxRetries,
             retryStrategy: $this->retryStrategy ?? new ExponentialBackoffStrategy,
             retryCondition: $this->retryCondition ?? RetryCondition::default(),
-            middlewares: $this->buildMiddlewares($logger)
+            middlewares: $this->buildMiddlewares($logger),
+            eventDispatcher: $this->eventDispatcher
         );
 
         return new Transport($config);
@@ -229,7 +283,12 @@ private function buildMiddlewares(LoggerInterface $logger): array
     {
         $middlewares = [];
 
-        // Add cookie middleware first if configured
+        // Add event middleware first if configured (to track entire lifecycle)
+        if ($this->eventDispatcher !== null) {
+            $middlewares[] = new EventMiddleware($this->eventDispatcher);
+        }
+
+        // Add cookie middleware early if configured
         if ($this->cookieJar !== null) {
             $middlewares[] = new CookieMiddleware($this->cookieJar);
         }
@@ -248,7 +307,8 @@ private function buildMiddlewares(LoggerInterface $logger): array
                 $middlewares[] = new RetryMiddleware(
                     maxAttempts: $this->maxRetries,
                     strategy: $this->retryStrategy ?? new ExponentialBackoffStrategy,
-                    condition: $this->retryCondition ?? RetryCondition::default()
+                    condition: $this->retryCondition ?? RetryCondition::default(),
+                    eventDispatcher: $this->eventDispatcher
                 );
             }
         }
diff --git a/src/TransportConfig.php b/src/TransportConfig.php
index 88f1d58..d091fce 100644
--- a/src/TransportConfig.php
+++ b/src/TransportConfig.php
@@ -4,6 +4,7 @@
 
 namespace Farzai\Transport;
 
+use Farzai\Transport\Events\EventDispatcherInterface;
 use Farzai\Transport\Middleware\MiddlewareInterface;
 use Farzai\Transport\Retry\ExponentialBackoffStrategy;
 use Farzai\Transport\Retry\RetryCondition;
@@ -27,7 +28,8 @@ public function __construct(
         public readonly int $maxRetries = 0,
         public readonly RetryStrategyInterface $retryStrategy = new ExponentialBackoffStrategy,
         public readonly RetryCondition $retryCondition = new RetryCondition,
-        public readonly array $middlewares = []
+        public readonly array $middlewares = [],
+        public readonly ?EventDispatcherInterface $eventDispatcher = null
     ) {
         $this->validate();
     }
@@ -70,7 +72,8 @@ public function withHeaders(array $headers): self
             maxRetries: $this->maxRetries,
             retryStrategy: $this->retryStrategy,
             retryCondition: $this->retryCondition,
-            middlewares: $this->middlewares
+            middlewares: $this->middlewares,
+            eventDispatcher: $this->eventDispatcher
         );
     }
 
@@ -88,7 +91,8 @@ public function withBaseUri(string $baseUri): self
             maxRetries: $this->maxRetries,
             retryStrategy: $this->retryStrategy,
             retryCondition: $this->retryCondition,
-            middlewares: $this->middlewares
+            middlewares: $this->middlewares,
+            eventDispatcher: $this->eventDispatcher
         );
     }
 
@@ -106,7 +110,8 @@ public function withTimeout(int $timeout): self
             maxRetries: $this->maxRetries,
             retryStrategy: $this->retryStrategy,
             retryCondition: $this->retryCondition,
-            middlewares: $this->middlewares
+            middlewares: $this->middlewares,
+            eventDispatcher: $this->eventDispatcher
         );
     }
 
@@ -127,7 +132,8 @@ public function withRetries(
             maxRetries: $maxRetries,
             retryStrategy: $strategy ?? $this->retryStrategy,
             retryCondition: $condition ?? $this->retryCondition,
-            middlewares: $this->middlewares
+            middlewares: $this->middlewares,
+            eventDispatcher: $this->eventDispatcher
         );
     }
 
@@ -145,7 +151,8 @@ public function withMiddleware(MiddlewareInterface $middleware): self
             maxRetries: $this->maxRetries,
             retryStrategy: $this->retryStrategy,
             retryCondition: $this->retryCondition,
-            middlewares: [...$this->middlewares, $middleware]
+            middlewares: [...$this->middlewares, $middleware],
+            eventDispatcher: $this->eventDispatcher
         );
     }
 
@@ -163,7 +170,27 @@ public function withLogger(LoggerInterface $logger): self
             maxRetries: $this->maxRetries,
             retryStrategy: $this->retryStrategy,
             retryCondition: $this->retryCondition,
-            middlewares: $this->middlewares
+            middlewares: $this->middlewares,
+            eventDispatcher: $this->eventDispatcher
+        );
+    }
+
+    /**
+     * Create a new configuration with an event dispatcher.
+     */
+    public function withEventDispatcher(?EventDispatcherInterface $eventDispatcher): self
+    {
+        return new self(
+            client: $this->client,
+            logger: $this->logger,
+            baseUri: $this->baseUri,
+            headers: $this->headers,
+            timeout: $this->timeout,
+            maxRetries: $this->maxRetries,
+            retryStrategy: $this->retryStrategy,
+            retryCondition: $this->retryCondition,
+            middlewares: $this->middlewares,
+            eventDispatcher: $eventDispatcher
         );
     }
 }
diff --git a/tests/Cookie/AdaptiveCookieCollectionTest.php b/tests/Cookie/AdaptiveCookieCollectionTest.php
new file mode 100644
index 0000000..ee2eac5
--- /dev/null
+++ b/tests/Cookie/AdaptiveCookieCollectionTest.php
@@ -0,0 +1,465 @@
+<?php
+
+declare(strict_types=1);
+
+use Farzai\Transport\Cookie\AdaptiveCookieCollection;
+use Farzai\Transport\Cookie\Cookie;
+use Farzai\Transport\Cookie\IndexedCookieCollection;
+use Farzai\Transport\Cookie\SimpleCookieCollection;
+
+describe('AdaptiveCookieCollection', function () {
+    // Initialization tests
+    it('initializes with default threshold', function () {
+        $collection = new AdaptiveCookieCollection;
+
+        expect($collection->getThreshold())->toBe(50);
+        expect($collection->isUpgraded())->toBeFalse();
+        expect($collection->isEmpty())->toBeTrue();
+    });
+
+    it('initializes with custom threshold', function () {
+        $collection = new AdaptiveCookieCollection(threshold: 100);
+
+        expect($collection->getThreshold())->toBe(100);
+        expect($collection->isUpgraded())->toBeFalse();
+    });
+
+    it('enforces minimum threshold of 1', function () {
+        $collection = new AdaptiveCookieCollection(threshold: 0);
+
+        expect($collection->getThreshold())->toBe(1);
+    });
+
+    it('initializes with SimpleCookieCollection by default', function () {
+        $collection = new AdaptiveCookieCollection;
+
+        expect($collection->getUnderlyingCollection())->toBeInstanceOf(SimpleCookieCollection::class);
+    });
+
+    it('accepts initial SimpleCookieCollection', function () {
+        $simple = new SimpleCookieCollection;
+        $simple->add(new Cookie('existing', 'value'));
+
+        $collection = new AdaptiveCookieCollection(initialCollection: $simple);
+
+        expect($collection->count())->toBe(1);
+        expect($collection->isUpgraded())->toBeFalse();
+    });
+
+    it('accepts initial IndexedCookieCollection and marks as upgraded', function () {
+        $indexed = new IndexedCookieCollection;
+        $indexed->add(new Cookie('existing', 'value'));
+
+        $collection = new AdaptiveCookieCollection(initialCollection: $indexed);
+
+        expect($collection->count())->toBe(1);
+        expect($collection->isUpgraded())->toBeTrue();
+    });
+
+    // Upgrade behavior tests
+    it('starts as simple collection', function () {
+        $collection = new AdaptiveCookieCollection(threshold: 50);
+
+        expect($collection->getUnderlyingCollection())->toBeInstanceOf(SimpleCookieCollection::class);
+    });
+
+    it('stays simple below threshold', function () {
+        $collection = new AdaptiveCookieCollection(threshold: 50);
+
+        for ($i = 0; $i < 49; $i++) {
+            $collection->add(new Cookie("cookie{$i}", "value{$i}"));
+        }
+
+        expect($collection->count())->toBe(49);
+        expect($collection->isUpgraded())->toBeFalse();
+        expect($collection->getUnderlyingCollection())->toBeInstanceOf(SimpleCookieCollection::class);
+    });
+
+    it('upgrades at threshold boundary', function () {
+        $collection = new AdaptiveCookieCollection(threshold: 50);
+
+        for ($i = 0; $i < 50; $i++) {
+            $collection->add(new Cookie("cookie{$i}", "value{$i}"));
+        }
+
+        expect($collection->count())->toBe(50);
+        expect($collection->isUpgraded())->toBeTrue();
+        expect($collection->getUnderlyingCollection())->toBeInstanceOf(IndexedCookieCollection::class);
+    });
+
+    it('upgrades exactly when threshold is reached', function () {
+        $collection = new AdaptiveCookieCollection(threshold: 10);
+
+        // Add 9 cookies - should stay simple
+        for ($i = 0; $i < 9; $i++) {
+            $collection->add(new Cookie("cookie{$i}", "value{$i}"));
+        }
+        expect($collection->isUpgraded())->toBeFalse();
+
+        // Add 10th cookie - should trigger upgrade
+        $collection->add(new Cookie('cookie9', 'value9'));
+        expect($collection->isUpgraded())->toBeTrue();
+    });
+
+    it('preserves all cookies during upgrade', function () {
+        $collection = new AdaptiveCookieCollection(threshold: 5);
+
+        $cookies = [];
+        for ($i = 0; $i < 5; $i++) {
+            $cookie = new Cookie("cookie{$i}", "value{$i}", null, 'example.com', "/path{$i}");
+            $cookies[] = $cookie;
+            $collection->add($cookie);
+        }
+
+        expect($collection->isUpgraded())->toBeTrue();
+        expect($collection->count())->toBe(5);
+
+        // Verify all cookies are still accessible
+        foreach ($cookies as $cookie) {
+            $retrieved = $collection->get($cookie->getIdentifier());
+            expect($retrieved)->not->toBeNull();
+            expect($retrieved->getValue())->toBe($cookie->getValue());
+        }
+    });
+
+    it('stays upgraded after threshold is reached', function () {
+        $collection = new AdaptiveCookieCollection(threshold: 5);
+
+        for ($i = 0; $i < 10; $i++) {
+            $collection->add(new Cookie("cookie{$i}", "value{$i}"));
+        }
+
+        expect($collection->isUpgraded())->toBeTrue();
+
+        // Remove some cookies - should stay upgraded
+        $collection->remove('cookie0|/');
+        $collection->remove('cookie1|/');
+
+        expect($collection->isUpgraded())->toBeTrue();
+    });
+
+    // Downgrade behavior tests
+    it('downgrades after clear()', function () {
+        $collection = new AdaptiveCookieCollection(threshold: 5);
+
+        for ($i = 0; $i < 10; $i++) {
+            $collection->add(new Cookie("cookie{$i}", "value{$i}"));
+        }
+
+        expect($collection->isUpgraded())->toBeTrue();
+
+        $collection->clear();
+
+        expect($collection->isEmpty())->toBeTrue();
+        expect($collection->isUpgraded())->toBeFalse();
+        expect($collection->getUnderlyingCollection())->toBeInstanceOf(SimpleCookieCollection::class);
+    });
+
+    it('downgrades when removeExpired drops below 50% of threshold', function () {
+        $collection = new AdaptiveCookieCollection(threshold: 100);
+
+        // Add 100 cookies to trigger upgrade (90 expired, 10 valid)
+        for ($i = 0; $i < 90; $i++) {
+            $collection->add(new Cookie("expired{$i}", "value{$i}", time() - 3600));
+        }
+        for ($i = 0; $i < 10; $i++) {
+            $collection->add(new Cookie("valid{$i}", "value{$i}", time() + 3600));
+        }
+
+        expect($collection->isUpgraded())->toBeTrue();
+
+        // Remove expired cookies - should drop to 10 cookies (< 50 which is 50% of 100)
+        $removed = $collection->removeExpired();
+
+        expect($removed)->toBe(90);
+        expect($collection->count())->toBe(10);
+        expect($collection->isUpgraded())->toBeFalse();
+    });
+
+    it('stays upgraded when removeExpired keeps count above 50% threshold', function () {
+        $collection = new AdaptiveCookieCollection(threshold: 100);
+
+        // Add 100 cookies (40 expired, 60 valid)
+        for ($i = 0; $i < 40; $i++) {
+            $collection->add(new Cookie("expired{$i}", "value{$i}", time() - 3600));
+        }
+        for ($i = 0; $i < 60; $i++) {
+            $collection->add(new Cookie("valid{$i}", "value{$i}", time() + 3600));
+        }
+
+        expect($collection->isUpgraded())->toBeTrue();
+
+        // Remove expired - stays at 60 cookies (>= 50 which is 50% of 100)
+        $collection->removeExpired();
+
+        expect($collection->count())->toBe(60);
+        expect($collection->isUpgraded())->toBeTrue();
+    });
+
+    // Force upgrade/downgrade tests
+    it('force upgrades from simple to indexed', function () {
+        $collection = new AdaptiveCookieCollection(threshold: 50);
+
+        $collection->add(new Cookie('cookie1', 'value1'));
+        $collection->add(new Cookie('cookie2', 'value2'));
+
+        expect($collection->isUpgraded())->toBeFalse();
+
+        $collection->forceUpgrade();
+
+        expect($collection->isUpgraded())->toBeTrue();
+        expect($collection->getUnderlyingCollection())->toBeInstanceOf(IndexedCookieCollection::class);
+        expect($collection->count())->toBe(2);
+    });
+
+    it('force downgrade from indexed to simple', function () {
+        $collection = new AdaptiveCookieCollection(threshold: 5);
+
+        for ($i = 0; $i < 10; $i++) {
+            $collection->add(new Cookie("cookie{$i}", "value{$i}"));
+        }
+
+        expect($collection->isUpgraded())->toBeTrue();
+
+        $collection->forceDowngrade();
+
+        expect($collection->isUpgraded())->toBeFalse();
+        expect($collection->getUnderlyingCollection())->toBeInstanceOf(SimpleCookieCollection::class);
+        expect($collection->count())->toBe(10);
+    });
+
+    it('force upgrade does nothing if already upgraded', function () {
+        $collection = new AdaptiveCookieCollection(threshold: 2);
+
+        $collection->add(new Cookie('cookie1', 'value1'));
+        $collection->add(new Cookie('cookie2', 'value2'));
+
+        expect($collection->isUpgraded())->toBeTrue();
+
+        $collection->forceUpgrade();
+
+        expect($collection->isUpgraded())->toBeTrue();
+    });
+
+    it('force downgrade does nothing if already simple', function () {
+        $collection = new AdaptiveCookieCollection(threshold: 50);
+
+        $collection->add(new Cookie('cookie1', 'value1'));
+
+        expect($collection->isUpgraded())->toBeFalse();
+
+        $collection->forceDowngrade();
+
+        expect($collection->isUpgraded())->toBeFalse();
+    });
+
+    // Delegation tests
+    it('delegates add operation to underlying collection', function () {
+        $collection = new AdaptiveCookieCollection(threshold: 50);
+        $cookie = new Cookie('test', 'value');
+
+        $collection->add($cookie);
+
+        expect($collection->get($cookie->getIdentifier()))->toBe($cookie);
+    });
+
+    it('delegates remove operation to underlying collection', function () {
+        $collection = new AdaptiveCookieCollection(threshold: 50);
+        $cookie = new Cookie('test', 'value');
+
+        $collection->add($cookie);
+        $collection->remove($cookie->getIdentifier());
+
+        expect($collection->get($cookie->getIdentifier()))->toBeNull();
+    });
+
+    it('delegates get operation to underlying collection', function () {
+        $collection = new AdaptiveCookieCollection(threshold: 50);
+        $cookie = new Cookie('test', 'value123');
+
+        $collection->add($cookie);
+
+        $retrieved = $collection->get($cookie->getIdentifier());
+        expect($retrieved)->not->toBeNull();
+        expect($retrieved->getValue())->toBe('value123');
+    });
+
+    it('delegates findForUrl to underlying collection', function () {
+        $collection = new AdaptiveCookieCollection(threshold: 50);
+        $cookie = new Cookie('session', 'abc', null, 'example.com', '/');
+
+        $collection->add($cookie);
+
+        $matches = $collection->findForUrl('https://example.com/', true);
+        expect($matches)->toHaveCount(1);
+        expect($matches[0]->getName())->toBe('session');
+    });
+
+    it('delegates all() to underlying collection', function () {
+        $collection = new AdaptiveCookieCollection(threshold: 50);
+        $cookie1 = new Cookie('first', 'value1');
+        $cookie2 = new Cookie('second', 'value2');
+
+        $collection->add($cookie1);
+        $collection->add($cookie2);
+
+        $all = $collection->all();
+        expect($all)->toHaveCount(2);
+    });
+
+    it('delegates count() to underlying collection', function () {
+        $collection = new AdaptiveCookieCollection(threshold: 50);
+
+        expect($collection->count())->toBe(0);
+
+        $collection->add(new Cookie('cookie1', 'value1'));
+        expect($collection->count())->toBe(1);
+
+        $collection->add(new Cookie('cookie2', 'value2'));
+        expect($collection->count())->toBe(2);
+    });
+
+    it('delegates isEmpty() to underlying collection', function () {
+        $collection = new AdaptiveCookieCollection(threshold: 50);
+
+        expect($collection->isEmpty())->toBeTrue();
+
+        $collection->add(new Cookie('test', 'value'));
+
+        expect($collection->isEmpty())->toBeFalse();
+    });
+
+    // getType() tests
+    it('returns type with Adaptive suffix when simple', function () {
+        $collection = new AdaptiveCookieCollection(threshold: 50);
+
+        expect($collection->getType())->toContain('SimpleCookieCollection');
+        expect($collection->getType())->toContain('Adaptive');
+    });
+
+    it('returns type with Adaptive suffix when upgraded', function () {
+        $collection = new AdaptiveCookieCollection(threshold: 2);
+
+        $collection->add(new Cookie('cookie1', 'value1'));
+        $collection->add(new Cookie('cookie2', 'value2'));
+
+        expect($collection->getType())->toContain('IndexedCookieCollection');
+        expect($collection->getType())->toContain('Adaptive');
+    });
+
+    // Edge cases and integration tests
+    it('handles rapid additions across threshold', function () {
+        $collection = new AdaptiveCookieCollection(threshold: 10);
+
+        for ($i = 0; $i < 20; $i++) {
+            $collection->add(new Cookie("rapid{$i}", "value{$i}"));
+        }
+
+        expect($collection->count())->toBe(20);
+        expect($collection->isUpgraded())->toBeTrue();
+    });
+
+    it('maintains functionality after multiple upgrade/downgrade cycles', function () {
+        $collection = new AdaptiveCookieCollection(threshold: 10);
+
+        // Cycle 1: upgrade
+        for ($i = 0; $i < 15; $i++) {
+            $collection->add(new Cookie("cookie{$i}", "value{$i}", time() + 3600));
+        }
+        expect($collection->isUpgraded())->toBeTrue();
+
+        // Cycle 2: clear and downgrade
+        $collection->clear();
+        expect($collection->isUpgraded())->toBeFalse();
+
+        // Cycle 3: upgrade again
+        for ($i = 0; $i < 12; $i++) {
+            $collection->add(new Cookie("newcookie{$i}", "value{$i}"));
+        }
+        expect($collection->isUpgraded())->toBeTrue();
+
+        expect($collection->count())->toBe(12);
+    });
+
+    it('correctly finds cookies after upgrade', function () {
+        $collection = new AdaptiveCookieCollection(threshold: 3);
+
+        $collection->add(new Cookie('cookie1', 'value1', null, 'example.com', '/'));
+        $collection->add(new Cookie('cookie2', 'value2', null, 'example.com', '/api'));
+        $collection->add(new Cookie('cookie3', 'value3', null, 'example.com', '/app'));
+
+        expect($collection->isUpgraded())->toBeTrue();
+
+        $matches = $collection->findForUrl('https://example.com/api/users', true);
+        expect($matches)->toHaveCount(2); // /api and / match
+    });
+
+    it('handles cookies with various domains and paths across upgrade', function () {
+        $collection = new AdaptiveCookieCollection(threshold: 5);
+
+        $collection->add(new Cookie('root', 'val1', null, 'example.com', '/'));
+        $collection->add(new Cookie('api', 'val2', null, 'api.example.com', '/'));
+        $collection->add(new Cookie('shared', 'val3', null, '.example.com', '/'));
+        $collection->add(new Cookie('secure', 'val4', null, 'example.com', '/secure', true));
+        $collection->add(new Cookie('tracker', 'val5', null, '.example.com', '/track'));
+
+        expect($collection->isUpgraded())->toBeTrue();
+        expect($collection->count())->toBe(5);
+
+        // Test various URL matches - only cookies that match domain AND path will be found
+        $matches1 = $collection->findForUrl('https://example.com/', true);
+        expect($matches1)->toHaveCount(2); // root (/) and shared (.example.com /)
+        // Note: secure (/secure) doesn't match "/" and tracker (/track) doesn't match "/"
+
+        $matches2 = $collection->findForUrl('https://api.example.com/', true);
+        expect($matches2)->toHaveCount(2); // api, shared
+    });
+
+    it('preserves cookie order and sorting after upgrade', function () {
+        $collection = new AdaptiveCookieCollection(threshold: 4);
+
+        $collection->add(new Cookie('short', 'val1', null, 'example.com', '/'));
+        $collection->add(new Cookie('medium', 'val2', null, 'example.com', '/api'));
+        $collection->add(new Cookie('long', 'val3', null, 'example.com', '/api/users'));
+        $collection->add(new Cookie('longest', 'val4', null, 'example.com', '/api/users/profile'));
+
+        expect($collection->isUpgraded())->toBeTrue();
+
+        $matches = $collection->findForUrl('https://example.com/api/users/profile', true);
+
+        // Should be sorted by path length (longest first)
+        expect($matches)->toHaveCount(4);
+        expect($matches[0]->getName())->toBe('longest');
+        expect($matches[1]->getName())->toBe('long');
+        expect($matches[2]->getName())->toBe('medium');
+        expect($matches[3]->getName())->toBe('short');
+    });
+
+    it('handles threshold of 1 correctly', function () {
+        $collection = new AdaptiveCookieCollection(threshold: 1);
+
+        expect($collection->isUpgraded())->toBeFalse();
+
+        $collection->add(new Cookie('first', 'value'));
+
+        expect($collection->isUpgraded())->toBeTrue();
+    });
+
+    it('replaces cookies with same identifier across upgrade', function () {
+        $collection = new AdaptiveCookieCollection(threshold: 3);
+
+        $cookie1 = new Cookie('token', 'old_value', null, 'example.com', '/');
+        $collection->add($cookie1);
+        $collection->add(new Cookie('other1', 'val1'));
+        $collection->add(new Cookie('other2', 'val2'));
+
+        expect($collection->isUpgraded())->toBeTrue();
+
+        // Replace with same identifier
+        $cookie2 = new Cookie('token', 'new_value', null, 'example.com', '/');
+        $collection->add($cookie2);
+
+        expect($collection->count())->toBe(3);
+        expect($collection->get($cookie2->getIdentifier())->getValue())->toBe('new_value');
+    });
+});
diff --git a/tests/Cookie/CookieCollectionFactoryTest.php b/tests/Cookie/CookieCollectionFactoryTest.php
new file mode 100644
index 0000000..cc1186a
--- /dev/null
+++ b/tests/Cookie/CookieCollectionFactoryTest.php
@@ -0,0 +1,306 @@
+<?php
+
+declare(strict_types=1);
+
+use Farzai\Transport\Cookie\AdaptiveCookieCollection;
+use Farzai\Transport\Cookie\Cookie;
+use Farzai\Transport\Cookie\CookieCollectionFactory;
+use Farzai\Transport\Cookie\IndexedCookieCollection;
+use Farzai\Transport\Cookie\SimpleCookieCollection;
+
+describe('CookieCollectionFactory', function () {
+    // create() method tests
+    it('creates SimpleCookieCollection for count below threshold', function () {
+        $collection = CookieCollectionFactory::create(30);
+
+        expect($collection)->toBeInstanceOf(SimpleCookieCollection::class);
+    });
+
+    it('creates IndexedCookieCollection for count at threshold', function () {
+        $collection = CookieCollectionFactory::create(50);
+
+        expect($collection)->toBeInstanceOf(IndexedCookieCollection::class);
+    });
+
+    it('creates IndexedCookieCollection for count above threshold', function () {
+        $collection = CookieCollectionFactory::create(100);
+
+        expect($collection)->toBeInstanceOf(IndexedCookieCollection::class);
+    });
+
+    it('creates SimpleCookieCollection for zero count', function () {
+        $collection = CookieCollectionFactory::create(0);
+
+        expect($collection)->toBeInstanceOf(SimpleCookieCollection::class);
+    });
+
+    it('respects custom threshold in create()', function () {
+        $collection1 = CookieCollectionFactory::create(75, threshold: 100);
+        $collection2 = CookieCollectionFactory::create(75, threshold: 50);
+
+        expect($collection1)->toBeInstanceOf(SimpleCookieCollection::class);
+        expect($collection2)->toBeInstanceOf(IndexedCookieCollection::class);
+    });
+
+    it('handles boundary case at custom threshold', function () {
+        $customThreshold = 25;
+
+        $belowThreshold = CookieCollectionFactory::create(24, threshold: $customThreshold);
+        $atThreshold = CookieCollectionFactory::create(25, threshold: $customThreshold);
+
+        expect($belowThreshold)->toBeInstanceOf(SimpleCookieCollection::class);
+        expect($atThreshold)->toBeInstanceOf(IndexedCookieCollection::class);
+    });
+
+    // createSimple() method tests
+    it('creates SimpleCookieCollection via createSimple()', function () {
+        $collection = CookieCollectionFactory::createSimple();
+
+        expect($collection)->toBeInstanceOf(SimpleCookieCollection::class);
+        expect($collection->isEmpty())->toBeTrue();
+    });
+
+    // createIndexed() method tests
+    it('creates IndexedCookieCollection via createIndexed()', function () {
+        $collection = CookieCollectionFactory::createIndexed();
+
+        expect($collection)->toBeInstanceOf(IndexedCookieCollection::class);
+        expect($collection->isEmpty())->toBeTrue();
+    });
+
+    // getRecommendedType() method tests
+    it('recommends SimpleCookieCollection for small count', function () {
+        $type = CookieCollectionFactory::getRecommendedType(20);
+
+        expect($type)->toBe(SimpleCookieCollection::class);
+    });
+
+    it('recommends IndexedCookieCollection for large count', function () {
+        $type = CookieCollectionFactory::getRecommendedType(80);
+
+        expect($type)->toBe(IndexedCookieCollection::class);
+    });
+
+    it('recommends IndexedCookieCollection at exact threshold', function () {
+        $type = CookieCollectionFactory::getRecommendedType(50);
+
+        expect($type)->toBe(IndexedCookieCollection::class);
+    });
+
+    it('recommends SimpleCookieCollection one below threshold', function () {
+        $type = CookieCollectionFactory::getRecommendedType(49);
+
+        expect($type)->toBe(SimpleCookieCollection::class);
+    });
+
+    it('respects custom threshold in getRecommendedType()', function () {
+        $type1 = CookieCollectionFactory::getRecommendedType(60, threshold: 100);
+        $type2 = CookieCollectionFactory::getRecommendedType(60, threshold: 50);
+
+        expect($type1)->toBe(SimpleCookieCollection::class);
+        expect($type2)->toBe(IndexedCookieCollection::class);
+    });
+
+    // shouldUseIndexed() method tests
+    it('returns false for count below threshold', function () {
+        $result = CookieCollectionFactory::shouldUseIndexed(30);
+
+        expect($result)->toBeFalse();
+    });
+
+    it('returns true for count at threshold', function () {
+        $result = CookieCollectionFactory::shouldUseIndexed(50);
+
+        expect($result)->toBeTrue();
+    });
+
+    it('returns true for count above threshold', function () {
+        $result = CookieCollectionFactory::shouldUseIndexed(100);
+
+        expect($result)->toBeTrue();
+    });
+
+    it('respects custom threshold in shouldUseIndexed()', function () {
+        $result1 = CookieCollectionFactory::shouldUseIndexed(75, threshold: 100);
+        $result2 = CookieCollectionFactory::shouldUseIndexed(75, threshold: 50);
+
+        expect($result1)->toBeFalse();
+        expect($result2)->toBeTrue();
+    });
+
+    // fromCookies() method tests
+    it('creates SimpleCookieCollection from small cookie array', function () {
+        $cookies = [
+            new Cookie('cookie1', 'value1'),
+            new Cookie('cookie2', 'value2'),
+            new Cookie('cookie3', 'value3'),
+        ];
+
+        $collection = CookieCollectionFactory::fromCookies($cookies);
+
+        expect($collection)->toBeInstanceOf(SimpleCookieCollection::class);
+        expect($collection->count())->toBe(3);
+    });
+
+    it('creates IndexedCookieCollection from large cookie array', function () {
+        $cookies = [];
+        for ($i = 0; $i < 60; $i++) {
+            $cookies[] = new Cookie("cookie{$i}", "value{$i}");
+        }
+
+        $collection = CookieCollectionFactory::fromCookies($cookies);
+
+        expect($collection)->toBeInstanceOf(IndexedCookieCollection::class);
+        expect($collection->count())->toBe(60);
+    });
+
+    it('creates empty collection from empty array', function () {
+        $collection = CookieCollectionFactory::fromCookies([]);
+
+        expect($collection)->toBeInstanceOf(SimpleCookieCollection::class);
+        expect($collection->isEmpty())->toBeTrue();
+    });
+
+    it('respects custom threshold in fromCookies()', function () {
+        $cookies = [];
+        for ($i = 0; $i < 30; $i++) {
+            $cookies[] = new Cookie("cookie{$i}", "value{$i}");
+        }
+
+        $collection1 = CookieCollectionFactory::fromCookies($cookies, threshold: 50);
+        $collection2 = CookieCollectionFactory::fromCookies($cookies, threshold: 20);
+
+        expect($collection1)->toBeInstanceOf(SimpleCookieCollection::class);
+        expect($collection2)->toBeInstanceOf(IndexedCookieCollection::class);
+    });
+
+    it('preserves all cookies when creating from array', function () {
+        $cookie1 = new Cookie('session', 'abc123', null, 'example.com', '/');
+        $cookie2 = new Cookie('token', 'xyz789', null, 'api.example.com', '/v1');
+        $cookies = [$cookie1, $cookie2];
+
+        $collection = CookieCollectionFactory::fromCookies($cookies);
+
+        expect($collection->count())->toBe(2);
+        expect($collection->get($cookie1->getIdentifier()))->toBe($cookie1);
+        expect($collection->get($cookie2->getIdentifier()))->toBe($cookie2);
+    });
+
+    // createAdaptive() method tests
+    it('creates AdaptiveCookieCollection with default threshold', function () {
+        $collection = CookieCollectionFactory::createAdaptive();
+
+        expect($collection)->toBeInstanceOf(AdaptiveCookieCollection::class);
+    });
+
+    it('creates AdaptiveCookieCollection with custom threshold', function () {
+        $collection = CookieCollectionFactory::createAdaptive(threshold: 100);
+
+        expect($collection)->toBeInstanceOf(AdaptiveCookieCollection::class);
+    });
+
+    // getDefaultThreshold() method tests
+    it('returns correct default threshold', function () {
+        $threshold = CookieCollectionFactory::getDefaultThreshold();
+
+        expect($threshold)->toBe(50);
+        expect($threshold)->toBe(CookieCollectionFactory::DEFAULT_THRESHOLD);
+    });
+
+    // migrate() method tests
+    it('migrates from SimpleCookieCollection to IndexedCookieCollection', function () {
+        $simple = new SimpleCookieCollection;
+        $simple->add(new Cookie('cookie1', 'value1'));
+        $simple->add(new Cookie('cookie2', 'value2'));
+
+        $indexed = CookieCollectionFactory::migrate($simple, IndexedCookieCollection::class);
+
+        expect($indexed)->toBeInstanceOf(IndexedCookieCollection::class);
+        expect($indexed->count())->toBe(2);
+        expect($indexed->get('cookie1||/'))->not->toBeNull();
+    });
+
+    it('migrates from IndexedCookieCollection to SimpleCookieCollection', function () {
+        $indexed = new IndexedCookieCollection;
+        $indexed->add(new Cookie('cookie1', 'value1'));
+        $indexed->add(new Cookie('cookie2', 'value2'));
+
+        $simple = CookieCollectionFactory::migrate($indexed, SimpleCookieCollection::class);
+
+        expect($simple)->toBeInstanceOf(SimpleCookieCollection::class);
+        expect($simple->count())->toBe(2);
+    });
+
+    it('returns same collection if already correct type', function () {
+        $simple = new SimpleCookieCollection;
+        $simple->add(new Cookie('cookie1', 'value1'));
+
+        $result = CookieCollectionFactory::migrate($simple, SimpleCookieCollection::class);
+
+        expect($result)->toBe($simple);
+        expect($result->count())->toBe(1);
+    });
+
+    it('preserves all cookies during migration', function () {
+        $simple = new SimpleCookieCollection;
+        $cookie1 = new Cookie('session', 'abc123', null, 'example.com', '/');
+        $cookie2 = new Cookie('token', 'xyz789', null, 'api.example.com', '/v1');
+        $cookie3 = new Cookie('tracking', 'id999', time() + 3600, '.example.com', '/');
+
+        $simple->add($cookie1);
+        $simple->add($cookie2);
+        $simple->add($cookie3);
+
+        $indexed = CookieCollectionFactory::migrate($simple, IndexedCookieCollection::class);
+
+        expect($indexed->count())->toBe(3);
+        expect($indexed->get($cookie1->getIdentifier())->getValue())->toBe('abc123');
+        expect($indexed->get($cookie2->getIdentifier())->getValue())->toBe('xyz789');
+        expect($indexed->get($cookie3->getIdentifier())->getValue())->toBe('id999');
+    });
+
+    // Integration and edge case tests
+    it('factory methods produce functional collections', function () {
+        $simple = CookieCollectionFactory::createSimple();
+        $indexed = CookieCollectionFactory::createIndexed();
+
+        $cookie = new Cookie('test', 'value', null, 'example.com', '/');
+
+        $simple->add($cookie);
+        $indexed->add($cookie);
+
+        $simpleMatches = $simple->findForUrl('https://example.com/', true);
+        $indexedMatches = $indexed->findForUrl('https://example.com/', true);
+
+        expect($simpleMatches)->toHaveCount(1);
+        expect($indexedMatches)->toHaveCount(1);
+    });
+
+    it('respects threshold at boundary conditions', function () {
+        // Test exactly at threshold boundary
+        $at49 = CookieCollectionFactory::create(49);
+        $at50 = CookieCollectionFactory::create(50);
+        $at51 = CookieCollectionFactory::create(51);
+
+        expect($at49)->toBeInstanceOf(SimpleCookieCollection::class);
+        expect($at50)->toBeInstanceOf(IndexedCookieCollection::class);
+        expect($at51)->toBeInstanceOf(IndexedCookieCollection::class);
+    });
+
+    it('handles extreme threshold values', function () {
+        $veryLowThreshold = CookieCollectionFactory::create(1, threshold: 1);
+        $veryHighThreshold = CookieCollectionFactory::create(1000, threshold: 10000);
+
+        expect($veryLowThreshold)->toBeInstanceOf(IndexedCookieCollection::class);
+        expect($veryHighThreshold)->toBeInstanceOf(SimpleCookieCollection::class);
+    });
+
+    it('migrates empty collections correctly', function () {
+        $simple = new SimpleCookieCollection;
+
+        $indexed = CookieCollectionFactory::migrate($simple, IndexedCookieCollection::class);
+
+        expect($indexed)->toBeInstanceOf(IndexedCookieCollection::class);
+        expect($indexed->isEmpty())->toBeTrue();
+    });
+});
diff --git a/tests/Cookie/IndexedCookieCollectionTest.php b/tests/Cookie/IndexedCookieCollectionTest.php
new file mode 100644
index 0000000..70165aa
--- /dev/null
+++ b/tests/Cookie/IndexedCookieCollectionTest.php
@@ -0,0 +1,465 @@
+<?php
+
+declare(strict_types=1);
+
+use Farzai\Transport\Cookie\Cookie;
+use Farzai\Transport\Cookie\IndexedCookieCollection;
+
+describe('IndexedCookieCollection', function () {
+    // Basic Operations
+    it('adds cookie and maintains primary storage', function () {
+        $collection = new IndexedCookieCollection;
+        $cookie = new Cookie('session', 'abc123', null, 'example.com', '/');
+
+        $collection->add($cookie);
+
+        expect($collection->count())->toBe(1);
+        expect($collection->get($cookie->getIdentifier()))->toBe($cookie);
+    });
+
+    it('adds cookie and maintains domain index', function () {
+        $collection = new IndexedCookieCollection;
+        $cookie = new Cookie('session', 'abc123', null, 'example.com', '/');
+
+        $collection->add($cookie);
+
+        $stats = $collection->getIndexStats();
+        expect($stats['indexed_domains'])->toBe(1);
+        expect($stats['total_cookies'])->toBe(1);
+    });
+
+    it('replaces existing cookie with same identifier', function () {
+        $collection = new IndexedCookieCollection;
+        $cookie1 = new Cookie('token', 'old', null, 'example.com', '/');
+        $cookie2 = new Cookie('token', 'new', null, 'example.com', '/');
+
+        $collection->add($cookie1);
+        $collection->add($cookie2);
+
+        expect($collection->count())->toBe(1);
+        expect($collection->get($cookie2->getIdentifier())->getValue())->toBe('new');
+    });
+
+    it('removes cookie and cleans up indices', function () {
+        $collection = new IndexedCookieCollection;
+        $cookie = new Cookie('session', 'abc123', null, 'example.com', '/');
+
+        $collection->add($cookie);
+        $collection->remove($cookie->getIdentifier());
+
+        expect($collection->count())->toBe(0);
+        expect($collection->get($cookie->getIdentifier()))->toBeNull();
+
+        $stats = $collection->getIndexStats();
+        expect($stats['indexed_domains'])->toBe(0);
+    });
+
+    it('removes non-existent cookie gracefully', function () {
+        $collection = new IndexedCookieCollection;
+
+        $collection->remove('non-existent-id');
+
+        expect($collection->count())->toBe(0);
+    });
+
+    it('gets cookie by identifier', function () {
+        $collection = new IndexedCookieCollection;
+        $cookie = new Cookie('token', 'xyz789', null, 'api.example.com', '/v1');
+
+        $collection->add($cookie);
+
+        $retrieved = $collection->get($cookie->getIdentifier());
+        expect($retrieved)->not->toBeNull();
+        expect($retrieved->getValue())->toBe('xyz789');
+    });
+
+    it('returns null for non-existent identifier', function () {
+        $collection = new IndexedCookieCollection;
+
+        expect($collection->get('non-existent'))->toBeNull();
+    });
+
+    it('counts cookies correctly', function () {
+        $collection = new IndexedCookieCollection;
+
+        $collection->add(new Cookie('cookie1', 'value1', null, 'example.com'));
+        $collection->add(new Cookie('cookie2', 'value2', null, 'example.com'));
+        $collection->add(new Cookie('cookie3', 'value3', null, 'other.com'));
+
+        expect($collection->count())->toBe(3);
+    });
+
+    it('checks if collection is empty', function () {
+        $collection = new IndexedCookieCollection;
+
+        expect($collection->isEmpty())->toBeTrue();
+
+        $collection->add(new Cookie('test', 'value'));
+
+        expect($collection->isEmpty())->toBeFalse();
+    });
+
+    it('clears all cookies and indices', function () {
+        $collection = new IndexedCookieCollection;
+
+        $collection->add(new Cookie('cookie1', 'value1', null, 'example.com'));
+        $collection->add(new Cookie('cookie2', 'value2', null, 'other.com'));
+
+        $collection->clear();
+
+        expect($collection->isEmpty())->toBeTrue();
+        expect($collection->count())->toBe(0);
+
+        $stats = $collection->getIndexStats();
+        expect($stats['indexed_domains'])->toBe(0);
+    });
+
+    it('returns all cookies as array', function () {
+        $collection = new IndexedCookieCollection;
+        $cookie1 = new Cookie('first', 'value1');
+        $cookie2 = new Cookie('second', 'value2');
+
+        $collection->add($cookie1);
+        $collection->add($cookie2);
+
+        $all = $collection->all();
+        expect($all)->toHaveCount(2);
+        expect($all)->toContain($cookie1);
+        expect($all)->toContain($cookie2);
+    });
+
+    // Domain Indexing and Lookup Tests
+    it('finds cookies for exact domain match', function () {
+        $collection = new IndexedCookieCollection;
+        $cookie = new Cookie('session', 'abc123', null, 'example.com', '/');
+
+        $collection->add($cookie);
+
+        $matches = $collection->findForUrl('https://example.com/', true);
+        expect($matches)->toHaveCount(1);
+        expect($matches[0]->getName())->toBe('session');
+    });
+
+    it('finds cookies for subdomain with parent domain cookie', function () {
+        $collection = new IndexedCookieCollection;
+        $cookie = new Cookie('shared', 'value', null, '.example.com', '/');
+
+        $collection->add($cookie);
+
+        $matches = $collection->findForUrl('https://api.example.com/', true);
+        expect($matches)->toHaveCount(1);
+        expect($matches[0]->getName())->toBe('shared');
+    });
+
+    it('finds cookies for multiple domain levels', function () {
+        $collection = new IndexedCookieCollection;
+        $cookie1 = new Cookie('root', 'value1', null, '.example.com', '/');
+        $cookie2 = new Cookie('subdomain', 'value2', null, 'api.example.com', '/');
+
+        $collection->add($cookie1);
+        $collection->add($cookie2);
+
+        $matches = $collection->findForUrl('https://api.example.com/', true);
+        expect($matches)->toHaveCount(2);
+    });
+
+    it('does not find cookies from different domains', function () {
+        $collection = new IndexedCookieCollection;
+        $cookie = new Cookie('session', 'value', null, 'example.com', '/');
+
+        $collection->add($cookie);
+
+        $matches = $collection->findForUrl('https://other.com/', true);
+        expect($matches)->toHaveCount(0);
+    });
+
+    it('finds cookies with deep subdomain matching', function () {
+        $collection = new IndexedCookieCollection;
+        $cookie = new Cookie('tracker', 'value', null, '.example.com', '/');
+
+        $collection->add($cookie);
+
+        $matches = $collection->findForUrl('https://api.v2.prod.example.com/', true);
+        expect($matches)->toHaveCount(1);
+    });
+
+    // Path Sorting Tests
+    it('sorts cookies by path specificity', function () {
+        $collection = new IndexedCookieCollection;
+        $cookie1 = new Cookie('root', 'value1', null, 'example.com', '/');
+        $cookie2 = new Cookie('api', 'value2', null, 'example.com', '/api');
+        $cookie3 = new Cookie('users', 'value3', null, 'example.com', '/api/users');
+
+        // Add in random order
+        $collection->add($cookie1);
+        $collection->add($cookie3);
+        $collection->add($cookie2);
+
+        $matches = $collection->findForUrl('https://example.com/api/users/123', true);
+
+        expect($matches)->toHaveCount(3);
+        // More specific paths should come first
+        expect($matches[0]->getName())->toBe('users');
+        expect($matches[1]->getName())->toBe('api');
+        expect($matches[2]->getName())->toBe('root');
+    });
+
+    it('sorts cookies with equal path lengths by maintaining order', function () {
+        $collection = new IndexedCookieCollection;
+        $cookie1 = new Cookie('first', 'value1', null, 'example.com', '/api');
+        $cookie2 = new Cookie('second', 'value2', null, 'example.com', '/app');
+
+        $collection->add($cookie1);
+        $collection->add($cookie2);
+
+        $matches = $collection->findForUrl('https://example.com/api', true);
+
+        expect($matches)->toHaveCount(1);
+        expect($matches[0]->getName())->toBe('first');
+    });
+
+    // Secure Flag Tests
+    it('respects secure flag for HTTPS requests', function () {
+        $collection = new IndexedCookieCollection;
+        $secureCookie = new Cookie('secure', 'value', null, 'example.com', '/', true);
+
+        $collection->add($secureCookie);
+
+        $httpsMatches = $collection->findForUrl('https://example.com/', true);
+        $httpMatches = $collection->findForUrl('http://example.com/', false);
+
+        expect($httpsMatches)->toHaveCount(1);
+        expect($httpMatches)->toHaveCount(0);
+    });
+
+    // Expired Cookie Tests
+    it('removes expired cookies and updates indices', function () {
+        $collection = new IndexedCookieCollection;
+        $expired1 = new Cookie('old1', 'value1', time() - 3600, 'example.com');
+        $expired2 = new Cookie('old2', 'value2', time() - 7200, 'other.com');
+        $valid = new Cookie('fresh', 'value3', time() + 3600, 'example.com');
+
+        $collection->add($expired1);
+        $collection->add($expired2);
+        $collection->add($valid);
+
+        $removed = $collection->removeExpired();
+
+        expect($removed)->toBe(2);
+        expect($collection->count())->toBe(1);
+
+        $stats = $collection->getIndexStats();
+        expect($stats['indexed_domains'])->toBe(1);
+    });
+
+    it('removeExpired returns zero when no cookies expired', function () {
+        $collection = new IndexedCookieCollection;
+        $valid1 = new Cookie('cookie1', 'value1', time() + 3600);
+        $valid2 = new Cookie('cookie2', 'value2', time() + 7200);
+
+        $collection->add($valid1);
+        $collection->add($valid2);
+
+        $removed = $collection->removeExpired();
+
+        expect($removed)->toBe(0);
+        expect($collection->count())->toBe(2);
+    });
+
+    // Index Statistics Tests
+    it('provides accurate index statistics', function () {
+        $collection = new IndexedCookieCollection;
+        $collection->add(new Cookie('cookie1', 'value1', null, 'example.com'));
+        $collection->add(new Cookie('cookie2', 'value2', null, 'example.com'));
+        $collection->add(new Cookie('cookie3', 'value3', null, 'other.com'));
+
+        $stats = $collection->getIndexStats();
+
+        expect($stats['total_cookies'])->toBe(3);
+        expect($stats['indexed_domains'])->toBe(2);
+        expect($stats['avg_cookies_per_domain'])->toBeGreaterThan(0);
+        expect($stats['max_cookies_per_domain'])->toBeGreaterThanOrEqual(1);
+    });
+
+    it('calculates memory overhead ratio correctly', function () {
+        $collection = new IndexedCookieCollection;
+
+        // Add multiple cookies to same domain
+        for ($i = 0; $i < 10; $i++) {
+            $collection->add(new Cookie("cookie{$i}", "value{$i}", null, 'example.com', "/path{$i}"));
+        }
+
+        $stats = $collection->getIndexStats();
+
+        expect($stats['memory_overhead_ratio'])->toBeGreaterThan(0);
+        expect($stats['memory_overhead_ratio'])->toBeLessThan(1); // Should be less than 1 for single domain
+    });
+
+    it('handles empty collection statistics', function () {
+        $collection = new IndexedCookieCollection;
+
+        $stats = $collection->getIndexStats();
+
+        expect($stats['total_cookies'])->toBe(0);
+        expect($stats['indexed_domains'])->toBe(0);
+        expect($stats['avg_cookies_per_domain'])->toBe(0);
+        expect($stats['max_cookies_per_domain'])->toBe(0);
+        expect($stats['memory_overhead_ratio'])->toBe(0);
+    });
+
+    // Edge Cases
+    it('handles invalid URL gracefully', function () {
+        $collection = new IndexedCookieCollection;
+        $cookie = new Cookie('test', 'value', null, 'example.com');
+
+        $collection->add($cookie);
+
+        $matches = $collection->findForUrl('http:///invalid', true);
+        expect($matches)->toHaveCount(0);
+    });
+
+    it('handles URL without host', function () {
+        $collection = new IndexedCookieCollection;
+        $cookie = new Cookie('test', 'value', null, 'example.com');
+
+        $collection->add($cookie);
+
+        $matches = $collection->findForUrl('/just/a/path', true);
+        expect($matches)->toHaveCount(0);
+    });
+
+    it('handles cookie with null domain', function () {
+        $collection = new IndexedCookieCollection;
+        $cookie = new Cookie('test', 'value', null, null, '/');
+
+        $collection->add($cookie);
+
+        expect($collection->count())->toBe(1);
+
+        $stats = $collection->getIndexStats();
+        expect($stats['indexed_domains'])->toBeGreaterThanOrEqual(0);
+    });
+
+    it('handles multiple cookies with same name but different paths', function () {
+        $collection = new IndexedCookieCollection;
+        $cookie1 = new Cookie('token', 'value1', null, 'example.com', '/');
+        $cookie2 = new Cookie('token', 'value2', null, 'example.com', '/api');
+
+        $collection->add($cookie1);
+        $collection->add($cookie2);
+
+        expect($collection->count())->toBe(2);
+
+        $matches = $collection->findForUrl('https://example.com/api/users', true);
+        expect($matches)->toHaveCount(2);
+    });
+
+    it('updates domain index when cookie domain changes', function () {
+        $collection = new IndexedCookieCollection;
+        $cookie1 = new Cookie('session', 'value', null, 'old.com', '/');
+
+        $collection->add($cookie1);
+        expect($collection->findForUrl('https://old.com/', true))->toHaveCount(1);
+
+        // Different domain means different cookie (different identifier)
+        $cookie2 = new Cookie('session', 'value', null, 'new.com', '/');
+        $collection->add($cookie2);
+
+        // Both cookies should exist since they have different identifiers
+        expect($collection->count())->toBe(2);
+        expect($collection->findForUrl('https://old.com/', true))->toHaveCount(1);
+        expect($collection->findForUrl('https://new.com/', true))->toHaveCount(1);
+    });
+
+    // Performance Characteristics
+    it('efficiently handles large number of cookies', function () {
+        $collection = new IndexedCookieCollection;
+
+        // Add 100 cookies across 10 domains
+        for ($domain = 0; $domain < 10; $domain++) {
+            for ($i = 0; $i < 10; $i++) {
+                $cookie = new Cookie(
+                    "cookie_{$domain}_{$i}",
+                    "value_{$i}",
+                    null,
+                    "domain{$domain}.com",
+                    "/path{$i}"
+                );
+                $collection->add($cookie);
+            }
+        }
+
+        expect($collection->count())->toBe(100);
+
+        $stats = $collection->getIndexStats();
+        expect($stats['indexed_domains'])->toBe(10);
+        expect($stats['avg_cookies_per_domain'])->toBe(10);
+
+        // Should efficiently find cookies for one domain without checking all 100
+        // Only cookies with paths that are prefixes of the URL path will match
+        $matches = $collection->findForUrl('https://domain5.com/path3/something', true);
+        expect($matches)->toHaveCount(1); // Only /path3 matches /path3/something
+    });
+
+    it('maintains index integrity after multiple operations', function () {
+        $collection = new IndexedCookieCollection;
+
+        // Add cookies
+        $cookie1 = new Cookie('cookie1', 'value1', null, 'example.com');
+        $cookie2 = new Cookie('cookie2', 'value2', null, 'example.com');
+        $collection->add($cookie1);
+        $collection->add($cookie2);
+
+        // Remove one
+        $collection->remove($cookie1->getIdentifier());
+
+        // Add another
+        $cookie3 = new Cookie('cookie3', 'value3', null, 'example.com');
+        $collection->add($cookie3);
+
+        // Replace existing
+        $cookie2Updated = new Cookie('cookie2', 'new_value', null, 'example.com');
+        $collection->add($cookie2Updated);
+
+        $matches = $collection->findForUrl('https://example.com/', true);
+        expect($matches)->toHaveCount(2);
+        expect($collection->count())->toBe(2);
+
+        $stats = $collection->getIndexStats();
+        expect($stats['indexed_domains'])->toBe(1);
+    });
+
+    it('returns correct type identifier', function () {
+        $collection = new IndexedCookieCollection;
+
+        expect($collection->getType())->toBe(IndexedCookieCollection::class);
+    });
+
+    it('handles concurrent domain index lookups', function () {
+        $collection = new IndexedCookieCollection;
+
+        // Add cookies for multiple domains
+        $collection->add(new Cookie('cookie1', 'value1', null, 'example.com', '/'));
+        $collection->add(new Cookie('cookie2', 'value2', null, '.example.com', '/'));
+        $collection->add(new Cookie('cookie3', 'value3', null, 'api.example.com', '/'));
+
+        // Should find all three for api.example.com
+        // (exact match + .example.com parent + api.example.com)
+        $matches = $collection->findForUrl('https://api.example.com/', true);
+        expect($matches)->toHaveCount(2); // .example.com and api.example.com
+    });
+
+    it('avoids duplicate identifiers in domain index', function () {
+        $collection = new IndexedCookieCollection;
+        $cookie = new Cookie('session', 'value', null, 'example.com', '/');
+
+        // Add same cookie multiple times
+        $collection->add($cookie);
+        $collection->add($cookie);
+        $collection->add($cookie);
+
+        expect($collection->count())->toBe(1);
+        $matches = $collection->findForUrl('https://example.com/', true);
+        expect($matches)->toHaveCount(1);
+    });
+});
diff --git a/tests/Events/EventDispatcherTest.php b/tests/Events/EventDispatcherTest.php
new file mode 100644
index 0000000..3a1a04d
--- /dev/null
+++ b/tests/Events/EventDispatcherTest.php
@@ -0,0 +1,251 @@
+<?php
+
+use Farzai\Transport\Events\AbstractEvent;
+use Farzai\Transport\Events\EventDispatcher;
+use Farzai\Transport\Events\EventInterface;
+
+beforeEach(function () {
+    $this->dispatcher = new EventDispatcher;
+});
+
+it('can add single listener for event', function () {
+    $called = false;
+    $listener = function (EventInterface $event) use (&$called) {
+        $called = true;
+    };
+
+    $this->dispatcher->addEventListener(TestEvent::class, $listener);
+
+    expect($this->dispatcher->hasListeners(TestEvent::class))->toBeTrue();
+    expect($this->dispatcher->getListeners(TestEvent::class))->toHaveCount(1);
+});
+
+it('can add multiple listeners for same event', function () {
+    $listener1 = fn ($event) => null;
+    $listener2 = fn ($event) => null;
+    $listener3 = fn ($event) => null;
+
+    $this->dispatcher->addEventListener(TestEvent::class, $listener1);
+    $this->dispatcher->addEventListener(TestEvent::class, $listener2);
+    $this->dispatcher->addEventListener(TestEvent::class, $listener3);
+
+    expect($this->dispatcher->getListeners(TestEvent::class))->toHaveCount(3);
+});
+
+it('listeners receive event object when dispatched', function () {
+    $receivedEvent = null;
+    $listener = function (EventInterface $event) use (&$receivedEvent) {
+        $receivedEvent = $event;
+    };
+
+    $this->dispatcher->addEventListener(TestEvent::class, $listener);
+
+    $event = new TestEvent('test-data');
+    $this->dispatcher->dispatch($event);
+
+    expect($receivedEvent)->toBe($event);
+    expect($receivedEvent->getData())->toBe('test-data');
+});
+
+it('can remove specific listener', function () {
+    $listener1 = fn ($event) => null;
+    $listener2 = fn ($event) => null;
+
+    $this->dispatcher->addEventListener(TestEvent::class, $listener1);
+    $this->dispatcher->addEventListener(TestEvent::class, $listener2);
+
+    expect($this->dispatcher->getListeners(TestEvent::class))->toHaveCount(2);
+
+    $this->dispatcher->removeEventListener(TestEvent::class, $listener1);
+
+    expect($this->dispatcher->getListeners(TestEvent::class))->toHaveCount(1);
+    expect(array_values($this->dispatcher->getListeners(TestEvent::class)))->toBe([$listener2]);
+});
+
+it('can remove all listeners for event type', function () {
+    $this->dispatcher->addEventListener(TestEvent::class, fn ($e) => null);
+    $this->dispatcher->addEventListener(TestEvent::class, fn ($e) => null);
+    $this->dispatcher->addEventListener(AnotherTestEvent::class, fn ($e) => null);
+
+    expect($this->dispatcher->hasListeners(TestEvent::class))->toBeTrue();
+    expect($this->dispatcher->hasListeners(AnotherTestEvent::class))->toBeTrue();
+
+    $this->dispatcher->removeAllListeners(TestEvent::class);
+
+    expect($this->dispatcher->hasListeners(TestEvent::class))->toBeFalse();
+    expect($this->dispatcher->hasListeners(AnotherTestEvent::class))->toBeTrue();
+});
+
+it('can remove all listeners without event class', function () {
+    $this->dispatcher->addEventListener(TestEvent::class, fn ($e) => null);
+    $this->dispatcher->addEventListener(AnotherTestEvent::class, fn ($e) => null);
+
+    expect($this->dispatcher->hasListeners(TestEvent::class))->toBeTrue();
+    expect($this->dispatcher->hasListeners(AnotherTestEvent::class))->toBeTrue();
+
+    $this->dispatcher->removeAllListeners();
+
+    expect($this->dispatcher->hasListeners(TestEvent::class))->toBeFalse();
+    expect($this->dispatcher->hasListeners(AnotherTestEvent::class))->toBeFalse();
+});
+
+it('hasListeners returns correct boolean', function () {
+    expect($this->dispatcher->hasListeners(TestEvent::class))->toBeFalse();
+
+    $this->dispatcher->addEventListener(TestEvent::class, fn ($e) => null);
+
+    expect($this->dispatcher->hasListeners(TestEvent::class))->toBeTrue();
+});
+
+it('getListeners returns empty array for unregistered event', function () {
+    expect($this->dispatcher->getListeners(TestEvent::class))->toBe([]);
+});
+
+it('stops calling listeners when propagation stopped', function () {
+    $callCount = 0;
+
+    $listener1 = function (EventInterface $event) use (&$callCount) {
+        $callCount++;
+        $event->stopPropagation();
+    };
+
+    $listener2 = function (EventInterface $event) use (&$callCount) {
+        $callCount++;
+    };
+
+    $listener3 = function (EventInterface $event) use (&$callCount) {
+        $callCount++;
+    };
+
+    $this->dispatcher->addEventListener(TestEvent::class, $listener1);
+    $this->dispatcher->addEventListener(TestEvent::class, $listener2);
+    $this->dispatcher->addEventListener(TestEvent::class, $listener3);
+
+    $event = new TestEvent('test');
+    $this->dispatcher->dispatch($event);
+
+    expect($callCount)->toBe(1);
+    expect($event->isPropagationStopped())->toBeTrue();
+});
+
+it('calls listeners for parent event classes', function () {
+    $baseListenerCalled = false;
+    $childListenerCalled = false;
+
+    $baseListener = function (EventInterface $event) use (&$baseListenerCalled) {
+        $baseListenerCalled = true;
+    };
+
+    $childListener = function (EventInterface $event) use (&$childListenerCalled) {
+        $childListenerCalled = true;
+    };
+
+    $this->dispatcher->addEventListener(TestEvent::class, $baseListener);
+    $this->dispatcher->addEventListener(ChildTestEvent::class, $childListener);
+
+    $event = new ChildTestEvent('child-data');
+    $this->dispatcher->dispatch($event);
+
+    expect($baseListenerCalled)->toBeTrue();
+    expect($childListenerCalled)->toBeTrue();
+});
+
+it('listener removal does not affect other listeners', function () {
+    $listener1Called = false;
+    $listener2Called = false;
+
+    $listener1 = function ($event) use (&$listener1Called) {
+        $listener1Called = true;
+    };
+
+    $listener2 = function ($event) use (&$listener2Called) {
+        $listener2Called = true;
+    };
+
+    $this->dispatcher->addEventListener(TestEvent::class, $listener1);
+    $this->dispatcher->addEventListener(TestEvent::class, $listener2);
+
+    $this->dispatcher->removeEventListener(TestEvent::class, $listener1);
+    $this->dispatcher->dispatch(new TestEvent('test'));
+
+    expect($listener1Called)->toBeFalse();
+    expect($listener2Called)->toBeTrue();
+});
+
+it('cleans up empty listener arrays after removal', function () {
+    $listener = fn ($e) => null;
+
+    $this->dispatcher->addEventListener(TestEvent::class, $listener);
+    expect($this->dispatcher->hasListeners(TestEvent::class))->toBeTrue();
+
+    $this->dispatcher->removeEventListener(TestEvent::class, $listener);
+    expect($this->dispatcher->hasListeners(TestEvent::class))->toBeFalse();
+    expect($this->dispatcher->getListeners(TestEvent::class))->toBe([]);
+});
+
+it('handles removing non existent listener gracefully', function () {
+    $listener = fn ($e) => null;
+
+    $this->dispatcher->removeEventListener(TestEvent::class, $listener);
+
+    expect($this->dispatcher->hasListeners(TestEvent::class))->toBeFalse();
+});
+
+it('dispatches events in order of registration', function () {
+    $order = [];
+
+    $listener1 = function ($event) use (&$order) {
+        $order[] = 1;
+    };
+
+    $listener2 = function ($event) use (&$order) {
+        $order[] = 2;
+    };
+
+    $listener3 = function ($event) use (&$order) {
+        $order[] = 3;
+    };
+
+    $this->dispatcher->addEventListener(TestEvent::class, $listener1);
+    $this->dispatcher->addEventListener(TestEvent::class, $listener2);
+    $this->dispatcher->addEventListener(TestEvent::class, $listener3);
+
+    $this->dispatcher->dispatch(new TestEvent('test'));
+
+    expect($order)->toBe([1, 2, 3]);
+});
+
+it('allows same listener to be registered multiple times', function () {
+    $callCount = 0;
+    $listener = function ($event) use (&$callCount) {
+        $callCount++;
+    };
+
+    $this->dispatcher->addEventListener(TestEvent::class, $listener);
+    $this->dispatcher->addEventListener(TestEvent::class, $listener);
+
+    $this->dispatcher->dispatch(new TestEvent('test'));
+
+    expect($callCount)->toBe(2);
+});
+
+class TestEvent extends AbstractEvent
+{
+    public function __construct(
+        private readonly string $data
+    ) {}
+
+    public function getData(): string
+    {
+        return $this->data;
+    }
+}
+
+class AnotherTestEvent extends AbstractEvent
+{
+    public function __construct(
+        private readonly string $data = ''
+    ) {}
+}
+
+class ChildTestEvent extends TestEvent {}
diff --git a/tests/Events/RequestFailedEventTest.php b/tests/Events/RequestFailedEventTest.php
new file mode 100644
index 0000000..69b74c8
--- /dev/null
+++ b/tests/Events/RequestFailedEventTest.php
@@ -0,0 +1,237 @@
+<?php
+
+declare(strict_types=1);
+
+use Farzai\Transport\Events\RequestFailedEvent;
+use Farzai\Transport\Exceptions\ClientException;
+use Farzai\Transport\Exceptions\NetworkException;
+use Farzai\Transport\Exceptions\ServerException;
+use Farzai\Transport\Exceptions\TimeoutException;
+use Farzai\Transport\Factory\HttpFactory;
+
+beforeEach(function () {
+    $factory = HttpFactory::getInstance();
+    $this->request = $factory->createRequest('POST', 'https://api.example.com/users');
+});
+
+it('creates event with request and exception', function () {
+    $exception = new Exception('Connection failed');
+
+    $event = new RequestFailedEvent($this->request, $exception);
+
+    expect($event->getRequest())->toBe($this->request)
+        ->and($event->getException())->toBe($exception)
+        ->and($event->getAttemptNumber())->toBe(1);
+});
+
+it('stores and retrieves all properties correctly', function () {
+    $exception = new RuntimeException('Test error');
+    $timestamp = 1234567890.123456;
+
+    $event = new RequestFailedEvent(
+        $this->request,
+        $exception,
+        3,
+        $timestamp
+    );
+
+    expect($event->getRequest())->toBe($this->request)
+        ->and($event->getException())->toBe($exception)
+        ->and($event->getAttemptNumber())->toBe(3)
+        ->and($event->getTimestamp())->toBe($timestamp);
+});
+
+it('uses current time when timestamp not provided', function () {
+    $beforeTime = microtime(true);
+
+    $event = new RequestFailedEvent(
+        $this->request,
+        new Exception('error')
+    );
+
+    $afterTime = microtime(true);
+
+    $timestamp = $event->getTimestamp();
+    expect($timestamp)->toBeGreaterThanOrEqual($beforeTime)
+        ->and($timestamp)->toBeLessThanOrEqual($afterTime);
+});
+
+it('uses provided timestamp when given', function () {
+    $providedTimestamp = 1609459200.5; // 2021-01-01 00:00:00.5
+
+    $event = new RequestFailedEvent(
+        $this->request,
+        new Exception('error'),
+        1,
+        $providedTimestamp
+    );
+
+    expect($event->getTimestamp())->toBe($providedTimestamp);
+});
+
+it('getMethod returns request method', function () {
+    $event = new RequestFailedEvent($this->request, new Exception('error'));
+
+    expect($event->getMethod())->toBe('POST');
+});
+
+it('getUri returns request uri as string', function () {
+    $event = new RequestFailedEvent($this->request, new Exception('error'));
+
+    expect($event->getUri())->toBe('https://api.example.com/users');
+});
+
+it('getExceptionType returns exception class name', function () {
+    $exception = new RuntimeException('Test error');
+
+    $event = new RequestFailedEvent($this->request, $exception);
+
+    expect($event->getExceptionType())->toBe(RuntimeException::class);
+});
+
+it('getExceptionMessage returns exception message', function () {
+    $exception = new Exception('This is a test error message');
+
+    $event = new RequestFailedEvent($this->request, $exception);
+
+    expect($event->getExceptionMessage())->toBe('This is a test error message');
+});
+
+it('isNetworkError detects NetworkException', function () {
+    $exception = new NetworkException('Connection failed', $this->request);
+
+    $event = new RequestFailedEvent($this->request, $exception);
+
+    expect($event->isNetworkError())->toBeTrue()
+        ->and($event->isTimeoutError())->toBeFalse()
+        ->and($event->isHttpError())->toBeFalse();
+});
+
+it('isNetworkError detects exception with NetworkException in name', function () {
+    // Create a custom exception that contains "NetworkException" in the class name
+    $exception = new class('Network error') extends Exception
+    {
+        public function __construct(string $message)
+        {
+            parent::__construct($message);
+        }
+    };
+
+    // Override the class name check by using a NetworkException
+    $networkException = new NetworkException('Connection issue', $this->request);
+    $event = new RequestFailedEvent($this->request, $networkException);
+
+    expect($event->isNetworkError())->toBeTrue();
+});
+
+it('isTimeoutError detects TimeoutException', function () {
+    $exception = new TimeoutException('Request timeout', $this->request, 30);
+
+    $event = new RequestFailedEvent($this->request, $exception);
+
+    expect($event->isTimeoutError())->toBeTrue()
+        ->and($event->isNetworkError())->toBeFalse()
+        ->and($event->isHttpError())->toBeFalse();
+});
+
+it('isHttpError detects ClientException', function () {
+    $response = HttpFactory::getInstance()->createResponse(404);
+    $exception = new ClientException('Not found', $this->request, $response);
+
+    $event = new RequestFailedEvent($this->request, $exception);
+
+    expect($event->isHttpError())->toBeTrue()
+        ->and($event->isNetworkError())->toBeFalse()
+        ->and($event->isTimeoutError())->toBeFalse();
+});
+
+it('isHttpError detects ServerException', function () {
+    $response = HttpFactory::getInstance()->createResponse(500);
+    $exception = new ServerException('Internal server error', $this->request, $response);
+
+    $event = new RequestFailedEvent($this->request, $exception);
+
+    expect($event->isHttpError())->toBeTrue()
+        ->and($event->isNetworkError())->toBeFalse()
+        ->and($event->isTimeoutError())->toBeFalse();
+});
+
+it('error detection returns false for other exception types', function () {
+    $exception = new RuntimeException('Generic error');
+
+    $event = new RequestFailedEvent($this->request, $exception);
+
+    expect($event->isNetworkError())->toBeFalse()
+        ->and($event->isTimeoutError())->toBeFalse()
+        ->and($event->isHttpError())->toBeFalse();
+});
+
+it('isRetry returns false for attempt 1', function () {
+    $event = new RequestFailedEvent(
+        $this->request,
+        new Exception('error'),
+        1
+    );
+
+    expect($event->isRetry())->toBeFalse();
+});
+
+it('isRetry returns true for attempt greater than 1', function () {
+    $event = new RequestFailedEvent(
+        $this->request,
+        new Exception('error'),
+        2
+    );
+
+    expect($event->isRetry())->toBeTrue();
+});
+
+it('isRetry returns true for multiple retry attempts', function () {
+    $event = new RequestFailedEvent(
+        $this->request,
+        new Exception('error'),
+        5
+    );
+
+    expect($event->isRetry())->toBeTrue();
+});
+
+it('can stop propagation', function () {
+    $event = new RequestFailedEvent($this->request, new Exception('error'));
+
+    expect($event->isPropagationStopped())->toBeFalse();
+
+    $event->stopPropagation();
+
+    expect($event->isPropagationStopped())->toBeTrue();
+});
+
+it('handles exceptions with empty message', function () {
+    $exception = new Exception('');
+
+    $event = new RequestFailedEvent($this->request, $exception);
+
+    expect($event->getExceptionMessage())->toBe('');
+});
+
+it('works with different http methods', function () {
+    $getRequest = HttpFactory::getInstance()->createRequest('GET', 'https://api.example.com');
+    $deleteRequest = HttpFactory::getInstance()->createRequest('DELETE', 'https://api.example.com');
+
+    $event1 = new RequestFailedEvent($getRequest, new Exception('error'));
+    $event2 = new RequestFailedEvent($deleteRequest, new Exception('error'));
+
+    expect($event1->getMethod())->toBe('GET')
+        ->and($event2->getMethod())->toBe('DELETE');
+});
+
+it('works with different uris', function () {
+    $request1 = HttpFactory::getInstance()->createRequest('GET', 'https://api.example.com/v1/users');
+    $request2 = HttpFactory::getInstance()->createRequest('GET', 'http://localhost:8080/test?foo=bar');
+
+    $event1 = new RequestFailedEvent($request1, new Exception('error'));
+    $event2 = new RequestFailedEvent($request2, new Exception('error'));
+
+    expect($event1->getUri())->toBe('https://api.example.com/v1/users')
+        ->and($event2->getUri())->toBe('http://localhost:8080/test?foo=bar');
+});
diff --git a/tests/Events/RequestSendingEventTest.php b/tests/Events/RequestSendingEventTest.php
new file mode 100644
index 0000000..14bc324
--- /dev/null
+++ b/tests/Events/RequestSendingEventTest.php
@@ -0,0 +1,95 @@
+<?php
+
+declare(strict_types=1);
+
+use Farzai\Transport\Events\RequestSendingEvent;
+use Farzai\Transport\Factory\HttpFactory;
+use Psr\Http\Message\RequestInterface;
+
+beforeEach(function () {
+    $factory = HttpFactory::getInstance();
+    $this->request = $factory->createRequest('GET', 'https://api.example.com/users');
+});
+
+it('creates event with request', function () {
+    $event = new RequestSendingEvent($this->request);
+
+    expect($event->getRequest())->toBe($this->request);
+});
+
+it('uses current time when timestamp not provided', function () {
+    $beforeTime = microtime(true);
+
+    $event = new RequestSendingEvent($this->request);
+
+    $afterTime = microtime(true);
+
+    $timestamp = $event->getTimestamp();
+    expect($timestamp)->toBeGreaterThanOrEqual($beforeTime)
+        ->and($timestamp)->toBeLessThanOrEqual($afterTime);
+});
+
+it('uses provided timestamp when given', function () {
+    $providedTimestamp = 1609459200.5; // 2021-01-01 00:00:00.5
+
+    $event = new RequestSendingEvent($this->request, $providedTimestamp);
+
+    expect($event->getTimestamp())->toBe($providedTimestamp);
+});
+
+it('getRequest returns PSR7 request', function () {
+    $event = new RequestSendingEvent($this->request);
+
+    expect($event->getRequest())->toBeInstanceOf(RequestInterface::class)
+        ->and($event->getRequest())->toBe($this->request);
+});
+
+it('getMethod returns HTTP method', function () {
+    $postRequest = HttpFactory::getInstance()->createRequest('POST', 'https://api.example.com');
+
+    $event = new RequestSendingEvent($postRequest);
+
+    expect($event->getMethod())->toBe('POST');
+});
+
+it('getUri returns URI as string', function () {
+    $event = new RequestSendingEvent($this->request);
+
+    expect($event->getUri())->toBe('https://api.example.com/users');
+});
+
+it('can stop propagation', function () {
+    $event = new RequestSendingEvent($this->request);
+
+    expect($event->isPropagationStopped())->toBeFalse();
+
+    $event->stopPropagation();
+
+    expect($event->isPropagationStopped())->toBeTrue();
+});
+
+it('works with different http methods', function () {
+    $methods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'];
+
+    foreach ($methods as $method) {
+        $request = HttpFactory::getInstance()->createRequest($method, 'https://api.example.com');
+        $event = new RequestSendingEvent($request);
+
+        expect($event->getMethod())->toBe($method);
+    }
+});
+
+it('works with different uris', function () {
+    $uris = [
+        'https://api.example.com',
+        'http://localhost:8080',
+        'https://example.com/api/v1/users?page=1',
+    ];
+
+    foreach ($uris as $uri) {
+        $request = HttpFactory::getInstance()->createRequest('GET', $uri);
+        $event = new RequestSendingEvent($request);
+
+        expect($event->getUri())->toBe($uri);
+    }
+});
diff --git a/tests/Events/RequestSentEventTest.php b/tests/Events/RequestSentEventTest.php
new file mode 100644
index 0000000..8d9498c
--- /dev/null
+++ b/tests/Events/RequestSentEventTest.php
@@ -0,0 +1,179 @@
+<?php
+
+declare(strict_types=1);
+
+use Farzai\Transport\Events\RequestSentEvent;
+use Farzai\Transport\Factory\HttpFactory;
+
+beforeEach(function () {
+    $this->factory = HttpFactory::getInstance();
+    $this->request = $this->factory->createRequest('POST', 'https://api.example.com/users');
+    $this->response = $this->factory->createResponse(200);
+});
+
+it('creates event with all required parameters', function () {
+    $duration = 123.45;
+    $timestamp = 1234567890.123456;
+
+    $event = new RequestSentEvent(
+        $this->request,
+        $this->response,
+        $duration,
+        $timestamp
+    );
+
+    expect($event->getRequest())->toBe($this->request)
+        ->and($event->getResponse())->toBe($this->response)
+        ->and($event->getDuration())->toBe($duration)
+        ->and($event->getTimestamp())->toBe($timestamp);
+});
+
+it('returns correct request response duration timestamp', function () {
+    $duration = 250.5;
+    $timestamp = microtime(true);
+
+    $event = new RequestSentEvent(
+        $this->request,
+        $this->response,
+        $duration,
+        $timestamp
+    );
+
+    expect($event->getRequest())->toBe($this->request)
+        ->and($event->getResponse())->toBe($this->response)
+        ->and($event->getDuration())->toBe($duration)
+        ->and($event->getTimestamp())->toBe($timestamp);
+});
+
+it('getMethod returns HTTP method', function () {
+    $event = new RequestSentEvent(
+        $this->request,
+        $this->response,
+        100.0,
+        microtime(true)
+    );
+
+    expect($event->getMethod())->toBe('POST');
+});
+
+it('getUri returns URI string', function () {
+    $event = new RequestSentEvent(
+        $this->request,
+        $this->response,
+        100.0,
+        microtime(true)
+    );
+
+    expect($event->getUri())->toBe('https://api.example.com/users');
+});
+
+it('getStatusCode returns correct status', function () {
+    $response404 = $this->factory->createResponse(404);
+
+    $event = new RequestSentEvent(
+        $this->request,
+        $response404,
+        100.0,
+        microtime(true)
+    );
+
+    expect($event->getStatusCode())->toBe(404);
+});
+
+it('isSuccessful returns true for 2xx codes', function () {
+    $successCodes = [200, 201, 202, 204, 299];
+
+    foreach ($successCodes as $code) {
+        $response = $this->factory->createResponse($code);
+        $event = new RequestSentEvent($this->request, $response, 100.0, microtime(true));
+
+        expect($event->isSuccessful())->toBeTrue("Status $code should be successful");
+    }
+});
+
+it('isSuccessful returns false for non 2xx codes', function () {
+    $failureCodes = [199, 300, 301, 400, 404, 500, 502];
+
+    foreach ($failureCodes as $code) {
+        $response = $this->factory->createResponse($code);
+        $event = new RequestSentEvent($this->request, $response, 100.0, microtime(true));
+
+        expect($event->isSuccessful())->toBeFalse("Status $code should not be successful");
+    }
+});
+
+it('can stop propagation', function () {
+    $event = new RequestSentEvent(
+        $this->request,
+        $this->response,
+        100.0,
+        microtime(true)
+    );
+
+    expect($event->isPropagationStopped())->toBeFalse();
+
+    $event->stopPropagation();
+
+    expect($event->isPropagationStopped())->toBeTrue();
+});
+
+it('handles different durations', function () {
+    $durations = [0.0, 1.5, 10.0, 100.5, 1000.0, 5000.75];
+
+    foreach ($durations as $duration) {
+        $event = new RequestSentEvent(
+            $this->request,
+            $this->response,
+            $duration,
+            microtime(true)
+        );
+
+        expect($event->getDuration())->toBe($duration);
+    }
+});
+
+it('works with various http methods', function () {
+    $methods = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'];
+
+    foreach ($methods as $method) {
+        $request = $this->factory->createRequest($method, 'https://api.example.com');
+        $event = new RequestSentEvent($request, $this->response, 100.0, microtime(true));
+
+        expect($event->getMethod())->toBe($method);
+    }
+});
+
+it('works with various status codes', function () {
+    $statusCodes = [200, 201, 301, 400, 404, 500, 503];
+
+    foreach ($statusCodes as $code) {
+        $response = $this->factory->createResponse($code);
+        $event = new RequestSentEvent($this->request, $response, 100.0, microtime(true));
+
+        expect($event->getStatusCode())->toBe($code);
+    }
+});
+
+it('handles zero duration', function () {
+    $event = new RequestSentEvent(
+        $this->request,
+        $this->response,
+        0.0,
+        microtime(true)
+    );
+
+    expect($event->getDuration())->toBe(0.0);
+});
+
+it('handles very long duration', function () {
+    $longDuration = 10000.123; // 10 seconds
+
+    $event = new RequestSentEvent(
+        $this->request,
+        $this->response,
+        $longDuration,
+        microtime(true)
+    );
+
+    expect($event->getDuration())->toBe($longDuration);
+});
diff --git a/tests/Events/ResponseReceivedEventTest.php b/tests/Events/ResponseReceivedEventTest.php
new file mode 100644
index 0000000..8f6ba6e
--- /dev/null
+++ b/tests/Events/ResponseReceivedEventTest.php
@@ -0,0 +1,200 @@
+<?php
+
+declare(strict_types=1);
+
+use Farzai\Transport\Events\ResponseReceivedEvent;
+use Farzai\Transport\Factory\HttpFactory;
+use Psr\Http\Message\RequestInterface;
+use Psr\Http\Message\ResponseInterface;
+
+beforeEach(function () {
+    $this->factory = HttpFactory::getInstance();
+    $this->request = $this->factory->createRequest('GET', 'https://api.example.com/data');
+    $this->response = $this->factory->createResponse(200);
+});
+
+it('creates event with all parameters', function () {
+    $duration = 150.25;
+    $timestamp = 1234567890.123456;
+
+    $event = new ResponseReceivedEvent(
+        $this->request,
+        $this->response,
+        $duration,
+        $timestamp
+    );
+
+    expect($event->getRequest())->toBe($this->request)
+        ->and($event->getResponse())->toBe($this->response)
+        ->and($event->getDuration())->toBe($duration)
+        ->and($event->getTimestamp())->toBe($timestamp);
+});
+
+it('returns request response duration timestamp', function () {
+    $duration = 200.0;
+    $timestamp = microtime(true);
+
+    $event = new ResponseReceivedEvent(
+        $this->request,
+        $this->response,
+        $duration,
+        $timestamp
+    );
+
+    expect($event->getRequest())->toBeInstanceOf(RequestInterface::class)
+        ->and($event->getResponse())->toBeInstanceOf(ResponseInterface::class)
+        ->and($event->getDuration())->toBe($duration)
+        ->and($event->getTimestamp())->toBe($timestamp);
+});
+
+it('getMethod and getUri work correctly', function () {
+    $event = new ResponseReceivedEvent(
+        $this->request,
+        $this->response,
+        100.0,
+        microtime(true)
+    );
+
+    expect($event->getMethod())->toBe('GET')
+        ->and($event->getUri())->toBe('https://api.example.com/data');
+});
+
+it('getStatusCode returns correct status', function () {
+    $response201 = $this->factory->createResponse(201);
+
+    $event = new ResponseReceivedEvent(
+        $this->request,
+        $response201,
+        100.0,
+        microtime(true)
+    );
+
+    expect($event->getStatusCode())->toBe(201);
+});
+
+it('isSuccessful detects 2xx codes', function () {
+    $successCodes = [200, 201, 202, 204, 299];
+
+    foreach ($successCodes as $code) {
+        $response = $this->factory->createResponse($code);
+        $event = new ResponseReceivedEvent($this->request, $response, 100.0, microtime(true));
+
+        expect($event->isSuccessful())->toBeTrue("Status $code should be successful")
+            ->and($event->isClientError())->toBeFalse("Status $code should not be client error")
+            ->and($event->isServerError())->toBeFalse("Status $code should not be server error");
+    }
+});
+
+it('isClientError detects 4xx codes', function () {
+    $clientErrorCodes = [400, 401, 403, 404, 422, 429, 499];
+
+    foreach ($clientErrorCodes as $code) {
+        $response = $this->factory->createResponse($code);
+        $event = new ResponseReceivedEvent($this->request, $response, 100.0, microtime(true));
+
+        expect($event->isClientError())->toBeTrue("Status $code should be client error")
+            ->and($event->isSuccessful())->toBeFalse("Status $code should not be successful")
+            ->and($event->isServerError())->toBeFalse("Status $code should not be server error");
+    }
+});
+
+it('isServerError detects 5xx codes', function () {
+    $serverErrorCodes = [500, 501, 502, 503, 504, 599];
+
+    foreach ($serverErrorCodes as $code) {
+        $response = $this->factory->createResponse($code);
+        $event = new ResponseReceivedEvent($this->request, $response, 100.0, microtime(true));
+
+        expect($event->isServerError())->toBeTrue("Status $code should be server error")
+            ->and($event->isSuccessful())->toBeFalse("Status $code should not be successful")
+            ->and($event->isClientError())->toBeFalse("Status $code should not be client error");
+    }
+});
+
+it('status helpers return false for other ranges', function () {
+    $otherCodes = [100, 101, 199, 300, 301, 302, 399];
+
+    foreach ($otherCodes as $code) {
+        $response = $this->factory->createResponse($code);
+        $event = new ResponseReceivedEvent($this->request, $response, 100.0, microtime(true));
+
+        expect($event->isSuccessful())->toBeFalse("Status $code should not be successful")
+            ->and($event->isClientError())->toBeFalse("Status $code should not be client error")
+            ->and($event->isServerError())->toBeFalse("Status $code should not be server error");
+    }
+});
+
+it('can stop propagation', function () {
+    $event = new ResponseReceivedEvent(
+        $this->request,
+        $this->response,
+        100.0,
+        microtime(true)
+    );
+
+    expect($event->isPropagationStopped())->toBeFalse();
+
+    $event->stopPropagation();
+
+    expect($event->isPropagationStopped())->toBeTrue();
+});
+
+it('handles edge of status code ranges', function () {
+    // Test boundary values
+    $boundaries = [
+        199 => ['successful' => false, 'clientError' => false, 'serverError' => false],
+        200 => ['successful' => true, 'clientError' => false, 'serverError' => false],
+        299 => ['successful' => true, 'clientError' => false, 'serverError' => false],
+        300 => ['successful' => false, 'clientError' => false, 'serverError' => false],
+        399 => ['successful' => false, 'clientError' => false, 'serverError' => false],
+        400 => ['successful' => false, 'clientError' => true, 'serverError' => false],
+        499 => ['successful' => false, 'clientError' => true, 'serverError' => false],
+        500 => ['successful' => false, 'clientError' => false, 'serverError' => true],
+        599 => ['successful' => false, 'clientError' => false, 'serverError' => true],
+        600 => ['successful' => false, 'clientError' => false, 'serverError' => false],
+    ];
+
+    foreach ($boundaries as $code => $expected) {
+        $response = $this->factory->createResponse($code);
+        $event = new ResponseReceivedEvent($this->request, $response, 100.0, microtime(true));
+
+        expect($event->isSuccessful())->toBe(
+            $expected['successful'],
+            "Status $code successful check failed"
+        );
+        expect($event->isClientError())->toBe(
+            $expected['clientError'],
+            "Status $code client error check failed"
+        );
+        expect($event->isServerError())->toBe(
+            $expected['serverError'],
+            "Status $code server error check failed"
+        );
+    }
+});
+
+it('works with different http methods', function () {
+    $methods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
+
+    foreach ($methods as $method) {
+        $request = $this->factory->createRequest($method, 'https://api.example.com');
+        $event = new ResponseReceivedEvent($request, $this->response, 100.0, microtime(true));
+
+        expect($event->getMethod())->toBe($method);
+    }
+});
+
+it('handles various durations', function () {
+    $durations = [0.0, 50.5, 150.75, 1000.0, 5000.123];
+
+    foreach ($durations as $duration) {
+        $event = new ResponseReceivedEvent(
+            $this->request,
+            $this->response,
+            $duration,
+            microtime(true)
+        );
+
+        expect($event->getDuration())->toBe($duration);
+    }
+});
diff --git a/tests/Events/RetryAttemptEventTest.php b/tests/Events/RetryAttemptEventTest.php
new file mode 100644
index 0000000..c11f318
--- /dev/null
+++ b/tests/Events/RetryAttemptEventTest.php
@@ -0,0 +1,340 @@
+<?php
+
+declare(strict_types=1);
+
+use Farzai\Transport\Events\RetryAttemptEvent;
+use Farzai\Transport\Factory\HttpFactory;
+
+beforeEach(function () {
+    $factory = HttpFactory::getInstance();
+    $this->request = $factory->createRequest('GET', 'https://api.example.com/data');
+});
+
+it('creates event with all parameters', function () {
+    $reason = new RuntimeException('Connection timeout');
+
+    $event = new RetryAttemptEvent(
+        $this->request,
+        $reason,
+        2,
+        5,
+        1000
+    );
+
+    expect($event->getRequest())->toBe($this->request)
+        ->and($event->getReason())->toBe($reason)
+        ->and($event->getAttemptNumber())->toBe(2)
+        ->and($event->getMaxAttempts())->toBe(5)
+        ->and($event->getDelay())->toBe(1000);
+});
+
+it('uses current time when timestamp not provided', function () {
+    $beforeTime = microtime(true);
+
+    $event = new RetryAttemptEvent(
+        $this->request,
+        new Exception('error'),
+        2,
+        3,
+        500
+    );
+
+    $afterTime = microtime(true);
+
+    $timestamp = $event->getTimestamp();
+    expect($timestamp)->toBeGreaterThanOrEqual($beforeTime)
+        ->and($timestamp)->toBeLessThanOrEqual($afterTime);
+});
+
+it('returns all properties correctly', function () {
+    $reason = new Exception('Test error');
+    $timestamp = 1234567890.123456;
+
+    $event = new RetryAttemptEvent(
+        $this->request,
+        $reason,
+        3,
+        5,
+        2000,
+        $timestamp
+    );
+
+    expect($event->getRequest())->toBe($this->request)
+        ->and($event->getReason())->toBe($reason)
+        ->and($event->getAttemptNumber())->toBe(3)
+        ->and($event->getMaxAttempts())->toBe(5)
+        ->and($event->getDelay())->toBe(2000)
+        ->and($event->getTimestamp())->toBe($timestamp);
+});
+
+it('getMethod returns request method', function () {
+    $postRequest = HttpFactory::getInstance()->createRequest('POST', 'https://api.example.com');
+
+    $event = new RetryAttemptEvent(
+        $postRequest,
+        new Exception('error'),
+        2,
+        3,
+        1000
+    );
+
+    expect($event->getMethod())->toBe('POST');
+});
+
+it('getUri returns request uri as string', function () {
+    $event = new RetryAttemptEvent(
+        $this->request,
+        new Exception('error'),
+        2,
+        3,
+        1000
+    );
+
+    expect($event->getUri())->toBe('https://api.example.com/data');
+});
+
+it('getRemainingAttempts calculates correctly', function () {
+    // On attempt 2 out of 5 max attempts
+    $event = new RetryAttemptEvent(
+        $this->request,
+        new Exception('error'),
+        2,
+        5,
+        1000
+    );
+
+    // Remaining = maxAttempts - attemptNumber + 1 = 5 - 2 + 1 = 4
+    expect($event->getRemainingAttempts())->toBe(4);
+});
+
+it('getRemainingAttempts returns 1 on last attempt', function () {
+    $event = new RetryAttemptEvent(
+        $this->request,
+        new Exception('error'),
+        5,
+        5,
+        1000
+    );
+
+    expect($event->getRemainingAttempts())->toBe(1);
+});
+
+it('isLastAttempt returns true when at max attempts', function () {
+    $event = new RetryAttemptEvent(
+        $this->request,
+        new Exception('error'),
+        5,
+        5,
+        1000
+    );
+
+    expect($event->isLastAttempt())->toBeTrue();
+});
+
+it('isLastAttempt returns true when exceeding max attempts', function () {
+    $event = new RetryAttemptEvent(
+        $this->request,
+        new Exception('error'),
+        6,
+        5,
+        1000
+    );
+
+    expect($event->isLastAttempt())->toBeTrue();
+});
+
+it('isLastAttempt returns false when more attempts remain', function () {
+    $event = new RetryAttemptEvent(
+        $this->request,
+        new Exception('error'),
+        2,
+        5,
+        1000
+    );
+
+    expect($event->isLastAttempt())->toBeFalse();
+});
+
+it('getProgress calculates percentage correctly', function () {
+    $event = new RetryAttemptEvent(
+        $this->request,
+        new Exception('error'),
+        2,
+        5,
+        1000
+    );
+
+    // Progress = (2 / 5) * 100 = 40%
+    expect($event->getProgress())->toBe(40.0);
+});
+
+it('getProgress returns 100 for last attempt', function () {
+    $event = new RetryAttemptEvent(
+        $this->request,
+        new Exception('error'),
+        5,
+        5,
+        1000
+    );
+
+    expect($event->getProgress())->toBe(100.0);
+});
+
+it('getProgress handles maxAttempts 1 edge case', function () {
+    $event = new RetryAttemptEvent(
+        $this->request,
+        new Exception('error'),
+        1,
+        1,
+        1000
+    );
+
+    // When maxAttempts is 1, always return 100%
+    expect($event->getProgress())->toBe(100.0);
+});
+
+it('getProgress calculates correctly for first retry', function () {
+    $event = new RetryAttemptEvent(
+        $this->request,
+        new Exception('error'),
+        1,
+        4,
+        1000
+    );
+
+    // Progress = (1 / 4) * 100 = 25%
+    expect($event->getProgress())->toBe(25.0);
+});
+
+it('getDelayInSeconds converts milliseconds correctly', function () {
+    $event = new RetryAttemptEvent(
+        $this->request,
+        new Exception('error'),
+        2,
+        3,
+        1000
+    );
+
+    // 1000 milliseconds = 1.0 seconds
+    expect($event->getDelayInSeconds())->toBe(1.0);
+});
+
+it('getDelayInSeconds handles fractional seconds', function () {
+    $event = new RetryAttemptEvent(
+        $this->request,
+        new Exception('error'),
+        2,
+        3,
+        1500
+    );
+
+    // 1500 milliseconds = 1.5 seconds
+    expect($event->getDelayInSeconds())->toBe(1.5);
+});
+
+it('getDelayInSeconds handles zero delay', function () {
+    $event = new RetryAttemptEvent(
+        $this->request,
+        new Exception('error'),
+        2,
+        3,
+        0
+    );
+
+    expect($event->getDelayInSeconds())->toBe(0.0);
+});
+
+it('getDelayInSeconds handles large delays', function () {
+    $event = new RetryAttemptEvent(
+        $this->request,
+        new Exception('error'),
+        2,
+        3,
+        60000 // 60 seconds
+    );
+
+    expect($event->getDelayInSeconds())->toBe(60.0);
+});
+
+it('can stop propagation', function () {
+    $event = new RetryAttemptEvent(
+        $this->request,
+        new Exception('error'),
+        2,
+        3,
+        1000
+    );
+
+    expect($event->isPropagationStopped())->toBeFalse();
+
+    $event->stopPropagation();
+
+    expect($event->isPropagationStopped())->toBeTrue();
+});
+
+it('works with various delay values', function () {
+    $delays = [100, 500, 1000, 2000, 5000, 10000];
+
+    foreach ($delays as $delay) {
+        $event = new RetryAttemptEvent(
+            $this->request,
+            new Exception('error'),
+            2,
+            3,
+            $delay
+        );
+
+        expect($event->getDelay())->toBe($delay)
+            ->and($event->getDelayInSeconds())->toBe($delay / 1000.0);
+    }
+});
+
+it('works with first retry attempt', function () {
+    // First retry is attempt number 2
+    $event = new RetryAttemptEvent(
+        $this->request,
+        new Exception('error'),
+        2,
+        5,
+        1000
+    );
+
+    expect($event->getAttemptNumber())->toBe(2)
+        ->and($event->getRemainingAttempts())->toBe(4)
+        ->and($event->isLastAttempt())->toBeFalse();
+});
+
+it('works with different max attempts', function () {
+    $maxAttempts = [1, 2, 3, 5, 10];
+
+    foreach ($maxAttempts as $max) {
+        $event = new RetryAttemptEvent(
+            $this->request,
+            new Exception('error'),
+            1,
+            $max,
+            1000
+        );
+
+        expect($event->getMaxAttempts())->toBe($max);
+    }
+});
+
+it('handles different exception types', function () {
+    $exceptions = [
+        new Exception('Generic error'),
+        new RuntimeException('Runtime error'),
+    ];
+
+    foreach ($exceptions as $exception) {
+        $event = new RetryAttemptEvent(
+            $this->request,
+            $exception,
+            2,
+            3,
+            1000
+        );
+
+        expect($event->getReason())->toBe($exception);
+    }
+});
diff --git a/tests/Factory/ClientFactoryTest.php b/tests/Factory/ClientFactoryTest.php
index 55cf8f1..d6e23cc 100644
--- a/tests/Factory/ClientFactoryTest.php
+++ b/tests/Factory/ClientFactoryTest.php
@@ -244,4 +244,169 @@
 
         expect($client)->toBeInstanceOf(ClientInterface::class);
     });
+
+    // Additional test cases for enhanced coverage
+
+    it('logs PSR-18 discovery fallback with client class name', function () {
+        $logger = Mockery::mock(LoggerInterface::class);
+
+        // The logger should receive at least one debug call
+        $logger->shouldReceive('debug')->atLeast()->once();
+
+        $client = ClientFactory::create($logger);
+
+        expect($client)->toBeInstanceOf(ClientInterface::class);
+    });
+
+    it('createGuzzle returns different instances on multiple calls', function () {
+        if (! class_exists('GuzzleHttp\Client')) {
+            $this->markTestSkipped('GuzzleHttp\Client is not installed');
+        }
+
+        $client1 = ClientFactory::createGuzzle();
+        $client2 = ClientFactory::createGuzzle();
+
+        expect($client1)->toBeInstanceOf(\GuzzleHttp\Client::class);
+        expect($client2)->toBeInstanceOf(\GuzzleHttp\Client::class);
+        expect($client1)->not->toBe($client2); // Different instances
+    });
+
+    it('createSymfony returns different instances on multiple calls', function () {
+        if (! class_exists('Symfony\Component\HttpClient\Psr18Client')) {
+            $this->markTestSkipped('Symfony HTTP Client is not installed');
+        }
+
+        $client1 = ClientFactory::createSymfony();
+        $client2 = ClientFactory::createSymfony();
+
+        expect($client1)->toBeInstanceOf(\Symfony\Component\HttpClient\Psr18Client::class);
+        expect($client2)->toBeInstanceOf(\Symfony\Component\HttpClient\Psr18Client::class);
+        expect($client1)->not->toBe($client2); // Different instances
+    });
+
+    it('create returns same client type on multiple calls', function () {
+        $client1 = ClientFactory::create();
+        $client2 = ClientFactory::create();
+
+        expect(get_class($client1))->toBe(get_class($client2));
+    });
+
+    it('getDetectedClientName is consistent with create()', function () {
+        $detectedName = ClientFactory::getDetectedClientName();
+        $client = ClientFactory::create();
+
+        expect(get_class($client))->toBe($detectedName);
+    });
+
+    it('isAvailable returns consistent results for known client types', function () {
+        $guzzleAvailable = ClientFactory::isAvailable('guzzle');
+        $symfonyAvailable = ClientFactory::isAvailable('symfony');
+
+        // If Guzzle is available, we should be able to create it
+        if ($guzzleAvailable) {
+            expect(fn () => ClientFactory::createGuzzle())->not->toThrow(RuntimeException::class);
+        }
+
+        // If Symfony is available, we should be able to create it
+        if ($symfonyAvailable) {
+            expect(fn () => ClientFactory::createSymfony())->not->toThrow(RuntimeException::class);
+        }
+    });
+
+    it('createGuzzle with complex configuration', function () {
+        if (! class_exists('GuzzleHttp\Client')) {
+            $this->markTestSkipped('GuzzleHttp\Client is not installed');
+        }
+
+        $config = [
+            'timeout' => 30,
+            'connect_timeout' => 10,
+            'verify' => true,
+            'allow_redirects' => false,
+            'http_errors' => false,
+        ];
+
+        $client = ClientFactory::createGuzzle($config);
+
+        expect($client)->toBeInstanceOf(\GuzzleHttp\Client::class);
+    });
+
+    it('createSymfony with complex options', function () {
+        if (! class_exists('Symfony\Component\HttpClient\Psr18Client')) {
+            $this->markTestSkipped('Symfony HTTP Client is not installed');
+        }
+
+        $options = [
+            'timeout' => 30,
+            'max_duration' => 60,
+            'max_redirects' => 10,
+            'http_version' => '2.0',
+        ];
+
+        $client = ClientFactory::createSymfony($options);
+
+        expect($client)->toBeInstanceOf(\Symfony\Component\HttpClient\Psr18Client::class);
+    });
+
+    it('isAvailable handles mixed case client types', function () {
+        $result1 = ClientFactory::isAvailable('GuZzLe');
+        $result2 = ClientFactory::isAvailable('SyMfOnY');
+
+        expect($result1)->toBeBool();
+        expect($result2)->toBeBool();
+    });
+
+    it('isAvailable with empty string returns false', function () {
+        $result = ClientFactory::isAvailable('');
+
+        expect($result)->toBeFalse();
+    });
+
+    it('isAvailable with namespace check', function () {
+        // Test with a class that should exist (not an interface)
+        $result = ClientFactory::isAvailable(\stdClass::class);
+
+        expect($result)->toBeTrue();
+
+        // Test with an interface - class_exists returns false for interfaces by default
+        $result2 = ClientFactory::isAvailable(ClientInterface::class);
+        expect($result2)->toBeFalse(); // Interfaces return false unless using second parameter
+    });
+
+    it('create error message includes helpful installation instructions', function () {
+        // This test is only meaningful if no PSR-18 client is available
+        // Since we have clients installed, we'll skip this scenario
+        // but the error handling logic is covered by the try-catch in create()
+
+        $client = ClientFactory::create();
+        expect($client)->toBeInstanceOf(ClientInterface::class);
+    });
+
+    it('createGuzzle error message includes composer command', function () {
+        if (class_exists('GuzzleHttp\Client')) {
+            $this->markTestSkipped('GuzzleHttp\Client is installed');
+        }
+
+        try {
+            ClientFactory::createGuzzle();
+            expect(true)->toBeFalse(); // Should not reach here
+        } catch (\RuntimeException $e) {
+            expect($e->getMessage())->toContain('composer require');
+            expect($e->getMessage())->toContain('guzzlehttp/guzzle');
+        }
+    });
+
+    it('createSymfony error message includes composer command', function () {
+        if (class_exists('Symfony\Component\HttpClient\Psr18Client')) {
+            $this->markTestSkipped('Symfony HTTP Client is installed');
+        }
+
+        try {
+            ClientFactory::createSymfony();
+            expect(true)->toBeFalse(); // Should not reach here
+        } catch (\RuntimeException $e) {
+            expect($e->getMessage())->toContain('composer require');
+            expect($e->getMessage())->toContain('symfony/http-client');
+        }
+    });
 });
diff --git a/tests/Helpers/CreatesTransport.php b/tests/Helpers/CreatesTransport.php
new file mode 100644
index 0000000..efe08c9
--- /dev/null
+++ b/tests/Helpers/CreatesTransport.php
@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Farzai\Transport\Tests\Helpers;
+
+use Farzai\Transport\Transport;
+use Farzai\Transport\TransportBuilder;
+use Psr\Http\Client\ClientInterface;
+
+/**
+ * Trait for creating transport instances in tests.
+ */
+trait CreatesTransport
+{
+    protected function createTransport(?ClientInterface $client = null): Transport
+    {
+        $builder = TransportBuilder::make();
+
+        if ($client !== null) {
+            $builder = $builder->setClient($client);
+        }
+
+        return $builder->build();
+    }
+
+    protected function createTransportWithMock(int $status = 200, string $body = ''): Transport
+    {
+        $client = MockClientBuilder::create()
+            ->willReturn($status, [], $body)
+            ->build();
+
+        return $this->createTransport($client);
+    }
+}
diff --git a/tests/Helpers/MockClientBuilder.php b/tests/Helpers/MockClientBuilder.php
new file mode 100644
index 0000000..d9f7bb7
--- /dev/null
+++ b/tests/Helpers/MockClientBuilder.php
@@ -0,0 +1,121 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Farzai\Transport\Tests\Helpers;
+
+use GuzzleHttp\Psr7\Response as GuzzleResponse;
+use Mockery;
+use Psr\Http\Client\ClientInterface;
+use Psr\Http\Message\RequestInterface;
+use Psr\Http\Message\ResponseInterface;
+
+/**
+ * Builder for creating PSR-18 client mocks.
+ *
+ * Design Pattern: Builder Pattern
+ * - Fluent API for mock configuration
+ * - Reduces test setup boilerplate
+ * - Makes tests more readable
+ *
+ * @example
+ * ```php
+ * $client = MockClientBuilder::create()
+ *     ->willReturn(200, ['Content-Type' => 'application/json'], '{"success":true}')
+ *     ->build();
+ * ```
+ */
+final class MockClientBuilder
+{
+    private ?ResponseInterface $response = null;
+
+    private ?\Throwable $exception = null;
+
+    /** @var callable|null */
+    private $callback = null;
+
+    private int $callCount = 1;
+
+    /**
+     * Create a new mock client builder.
+     */
+    public static function create(): self
+    {
+        return new self;
+    }
+
+    /**
+     * Set the response to return.
+     */
+    public function willReturn(
+        int $status = 200,
+        array $headers = [],
+        string $body = ''
+    ): self {
+        $this->response = new GuzzleResponse($status, $headers, $body);
+
+        return $this;
+    }
+
+    /**
+     * Set a custom response object.
+     */
+    public function willReturnResponse(ResponseInterface $response): self
+    {
+        $this->response = $response;
+
+        return $this;
+    }
+
+    /**
+     * Set an exception to throw.
+     */
+    public function willThrow(\Throwable $exception): self
+    {
+        $this->exception = $exception;
+
+        return $this;
+    }
+
+    /**
+     * Set a callback to determine response.
+     */
+    public function willCall(callable $callback): self
+    {
+        $this->callback = $callback;
+
+        return $this;
+    }
+
+    /**
+     * Set expected call count.
+     */
+    public function times(int $count): self
+    {
+        $this->callCount = $count;
+
+        return $this;
+    }
+
+    /**
+     * Build the mock client.
+     */
+    public function build(): ClientInterface
+    {
+        $mock = Mockery::mock(ClientInterface::class);
+
+        $expectation = $mock->shouldReceive('sendRequest')
+            ->times($this->callCount)
+            ->with(Mockery::type(RequestInterface::class));
+
+        if ($this->callback !== null) {
+            $expectation->andReturnUsing($this->callback);
+        } elseif ($this->exception !== null) {
+            $expectation->andThrow($this->exception);
+        } else {
+            $expectation->andReturn($this->response ?? new GuzzleResponse(200));
+        }
+
+        return $mock;
+    }
+}
diff --git a/tests/Middleware/EventMiddlewareTest.php b/tests/Middleware/EventMiddlewareTest.php
new file mode 100644
index 0000000..69960db
--- /dev/null
+++ b/tests/Middleware/EventMiddlewareTest.php
@@ -0,0 +1,283 @@
+<?php
+
+declare(strict_types=1);
+
+use Farzai\Transport\Events\EventDispatcher;
+use Farzai\Transport\Events\EventInterface;
+use Farzai\Transport\Events\RequestFailedEvent;
+use Farzai\Transport\Events\RequestSendingEvent;
+use Farzai\Transport\Events\RequestSentEvent;
+use Farzai\Transport\Events\ResponseReceivedEvent;
+use Farzai\Transport\Factory\HttpFactory;
+use Farzai\Transport\Middleware\EventMiddleware;
+
+beforeEach(function () {
+    $this->dispatcher = new EventDispatcher;
+    $this->middleware = new EventMiddleware($this->dispatcher);
+    $this->dispatchedEvents = [];
+
+    // Register listeners that capture all event types
+    $captureEvent = function (EventInterface $event) {
+        $this->dispatchedEvents[] = $event;
+    };
+
+    $this->dispatcher->addEventListener(RequestSendingEvent::class, $captureEvent);
+    $this->dispatcher->addEventListener(RequestSentEvent::class, $captureEvent);
+    $this->dispatcher->addEventListener(ResponseReceivedEvent::class, $captureEvent);
+    $this->dispatcher->addEventListener(RequestFailedEvent::class, $captureEvent);
+});
+
+it('dispatches RequestSendingEvent before request', function () {
+    $factory = HttpFactory::getInstance();
+    $request = $factory->createRequest('GET', 'https://api.example.com');
+    $response = $factory->createResponse(200);
+
+    $this->middleware->handle($request, fn ($req) => $response);
+
+    // First event should be RequestSendingEvent
+    expect($this->dispatchedEvents[0])->toBeInstanceOf(RequestSendingEvent::class)
+        ->and($this->dispatchedEvents[0]->getRequest())->toBe($request);
+});
+
+it('dispatches RequestSentEvent after successful response', function () {
+    $factory = HttpFactory::getInstance();
+    $request = $factory->createRequest('POST', 'https://api.example.com');
+    $response = $factory->createResponse(201);
+
+    $this->middleware->handle($request, fn ($req) => $response);
+
+    // Second event should be RequestSentEvent
+    expect($this->dispatchedEvents[1])->toBeInstanceOf(RequestSentEvent::class)
+        ->and($this->dispatchedEvents[1]->getRequest())->toBe($request)
+        ->and($this->dispatchedEvents[1]->getResponse())->toBe($response);
+});
+
+it('dispatches ResponseReceivedEvent after middleware processing', function () {
+    $factory = HttpFactory::getInstance();
+    $request = $factory->createRequest('GET', 'https://api.example.com');
+    $response = $factory->createResponse(200);
+
+    $this->middleware->handle($request, fn ($req) => $response);
+
+    // Third event should be ResponseReceivedEvent
+    expect($this->dispatchedEvents[2])->toBeInstanceOf(ResponseReceivedEvent::class)
+        ->and($this->dispatchedEvents[2]->getRequest())->toBe($request)
+        ->and($this->dispatchedEvents[2]->getResponse())->toBe($response);
+});
+
+it('dispatches RequestFailedEvent on exception', function () {
+    $factory = HttpFactory::getInstance();
+    $request = $factory->createRequest('GET', 'https://api.example.com');
+    $exception = new Exception('Connection failed');
+
+    try {
+        $this->middleware->handle($request, function () use ($exception) {
+            throw $exception;
+        });
+        expect(true)->toBeFalse('Exception should have been thrown');
+    } catch (Exception $e) {
+        // Expected
+    }
+
+    // Should have RequestSendingEvent and RequestFailedEvent
+    expect($this->dispatchedEvents)->toHaveCount(2)
+        ->and($this->dispatchedEvents[0])->toBeInstanceOf(RequestSendingEvent::class)
+        ->and($this->dispatchedEvents[1])->toBeInstanceOf(RequestFailedEvent::class)
+        ->and($this->dispatchedEvents[1]->getRequest())->toBe($request)
+        ->and($this->dispatchedEvents[1]->getException())->toBe($exception);
+});
+
+it('re-throws exception after dispatching failure event', function () {
+    $factory = HttpFactory::getInstance();
+    $request = $factory->createRequest('GET', 'https://api.example.com');
+    $exception = new Exception('Test error');
+
+    expect(fn () => $this->middleware->handle($request, function () use ($exception) {
+        throw $exception;
+    }))->toThrow(Exception::class, 'Test error');
+});
+
+it('calculates durations correctly in milliseconds', function () {
+    $factory = HttpFactory::getInstance();
+    $request = $factory->createRequest('GET', 'https://api.example.com');
+    $response = $factory->createResponse(200);
+
+    // Simulate some processing time
+    $this->middleware->handle($request, function ($req) use ($response) {
+        usleep(5000); // 5ms delay
+
+        return $response;
+    });
+
+    /** @var RequestSentEvent $sentEvent */
+    $sentEvent = $this->dispatchedEvents[1];
+    /** @var ResponseReceivedEvent $receivedEvent */
+    $receivedEvent = $this->dispatchedEvents[2];
+
+    // Durations should be in milliseconds and greater than 0
+    expect($sentEvent->getDuration())->toBeGreaterThan(0)
+        ->and($receivedEvent->getDuration())->toBeGreaterThan(0)
+        // Duration should be at least 4ms (we waited 5ms, allow some margin)
+        ->and($sentEvent->getDuration())->toBeGreaterThanOrEqual(4.0);
+});
+
+it('RequestSentEvent has different duration than ResponseReceivedEvent', function () {
+    $factory = HttpFactory::getInstance();
+    $request = $factory->createRequest('GET', 'https://api.example.com');
+    $response = $factory->createResponse(200);
+
+    $this->middleware->handle($request, fn ($req) => $response);
+
+    /** @var RequestSentEvent $sentEvent */
+    $sentEvent = $this->dispatchedEvents[1];
+    /** @var ResponseReceivedEvent $receivedEvent */
+    $receivedEvent = $this->dispatchedEvents[2];
+
+    // ResponseReceivedEvent duration should be >= RequestSentEvent duration
+    // (includes time for dispatching RequestSentEvent)
+    expect($receivedEvent->getDuration())->toBeGreaterThanOrEqual($sentEvent->getDuration());
+});
+
+it('getEventDispatcher returns dispatcher instance', function () {
+    expect($this->middleware->getEventDispatcher())->toBe($this->dispatcher);
+});
+
+it('events contain correct request response data', function () {
+    $factory = HttpFactory::getInstance();
+    $request = $factory->createRequest('POST', 'https://api.example.com/users');
+    $response = $factory->createResponse(201);
+
+    $this->middleware->handle($request, fn ($req) => $response);
+
+    /** @var RequestSendingEvent $sendingEvent */
+    $sendingEvent = $this->dispatchedEvents[0];
+    /** @var RequestSentEvent $sentEvent */
+    $sentEvent = $this->dispatchedEvents[1];
+    /** @var ResponseReceivedEvent $receivedEvent */
+    $receivedEvent = $this->dispatchedEvents[2];
+
+    // Check request consistency
+    expect($sendingEvent->getMethod())->toBe('POST')
+        ->and($sentEvent->getMethod())->toBe('POST')
+        ->and($receivedEvent->getMethod())->toBe('POST');
+
+    expect($sendingEvent->getUri())->toBe('https://api.example.com/users')
+        ->and($sentEvent->getUri())->toBe('https://api.example.com/users')
+        ->and($receivedEvent->getUri())->toBe('https://api.example.com/users');
+
+    // Check response consistency
+    expect($sentEvent->getStatusCode())->toBe(201)
+        ->and($receivedEvent->getStatusCode())->toBe(201);
+});
+
+it('works with multiple listeners', function () {
+    $sendingEventCount = 0;
+    $sentEventCount = 0;
+    $receivedEventCount = 0;
+
+    $this->dispatcher->addEventListener(RequestSendingEvent::class, function () use (&$sendingEventCount) {
+        $sendingEventCount++;
+    });
+
+    $this->dispatcher->addEventListener(RequestSentEvent::class, function () use (&$sentEventCount) {
+        $sentEventCount++;
+    });
+
+    $this->dispatcher->addEventListener(ResponseReceivedEvent::class, function () use (&$receivedEventCount) {
+        $receivedEventCount++;
+    });
+
+    $factory = HttpFactory::getInstance();
+    $request = $factory->createRequest('GET', 'https://api.example.com');
+    $response = $factory->createResponse(200);
+
+    $this->middleware->handle($request, fn ($req) => $response);
+
+    expect($sendingEventCount)->toBe(1)
+        ->and($sentEventCount)->toBe(1)
+        ->and($receivedEventCount)->toBe(1);
+});
+
+it('dispatches events in correct order', function () {
+    $factory = HttpFactory::getInstance();
+    $request = $factory->createRequest('GET', 'https://api.example.com');
+    $response = $factory->createResponse(200);
+
+    $this->middleware->handle($request, fn ($req) => $response);
+
+    expect($this->dispatchedEvents)->toHaveCount(3)
+        ->and($this->dispatchedEvents[0])->toBeInstanceOf(RequestSendingEvent::class)
+        ->and($this->dispatchedEvents[1])->toBeInstanceOf(RequestSentEvent::class)
+        ->and($this->dispatchedEvents[2])->toBeInstanceOf(ResponseReceivedEvent::class);
+});
+
+it('event timestamps are captured correctly', function () {
+    $factory = HttpFactory::getInstance();
+    $request = $factory->createRequest('GET', 'https://api.example.com');
+    $response = $factory->createResponse(200);
+
+    $beforeTime = microtime(true);
+
+    $this->middleware->handle($request, fn ($req) => $response);
+
+    $afterTime = microtime(true);
+
+    /** @var RequestSendingEvent $sendingEvent */
+    $sendingEvent = $this->dispatchedEvents[0];
+    /** @var RequestSentEvent $sentEvent */
+    $sentEvent = $this->dispatchedEvents[1];
+    /** @var ResponseReceivedEvent $receivedEvent */
+    $receivedEvent = $this->dispatchedEvents[2];
+
+    // All timestamps should be within the test execution window
+    expect($sendingEvent->getTimestamp())->toBeGreaterThanOrEqual($beforeTime)
+        ->and($receivedEvent->getTimestamp())->toBeLessThanOrEqual($afterTime);
+
+    // Timestamps should be in chronological order (allowing small floating point differences)
+    expect($receivedEvent->getTimestamp())->toBeLessThanOrEqual($sentEvent->getTimestamp() + 0.001)
+        ->and($sentEvent->getTimestamp())->toBeLessThanOrEqual($sendingEvent->getTimestamp() + 0.001);
+});
+
+it('RequestFailedEvent has attempt number 1', function () {
+    $factory = HttpFactory::getInstance();
+    $request = $factory->createRequest('GET', 'https://api.example.com');
+
+    try {
+        $this->middleware->handle($request, function () {
+            throw new Exception('Error');
+        });
+    } catch (Exception $e) {
+        // Expected
+    }
+
+    /** @var RequestFailedEvent $failedEvent */
+    $failedEvent = $this->dispatchedEvents[1];
+
+    expect($failedEvent->getAttemptNumber())->toBe(1);
+});
+
+it('returns response from next callable', function () {
+    $factory = HttpFactory::getInstance();
+    $request = $factory->createRequest('GET', 'https://api.example.com');
+    $expectedResponse = $factory->createResponse(200);
+
+    $actualResponse = $this->middleware->handle($request, fn ($req) => $expectedResponse);
+
+    expect($actualResponse)->toBe($expectedResponse);
+});
+
+it('passes request to next callable', function () {
+    $factory = HttpFactory::getInstance();
+    $request = $factory->createRequest('GET', 'https://api.example.com');
+    $response = $factory->createResponse(200);
+
+    $receivedRequest = null;
+
+    $this->middleware->handle($request, function ($req) use ($response, &$receivedRequest) {
+        $receivedRequest = $req;
+
+        return $response;
+    });
+
+    expect($receivedRequest)->toBe($request);
+});
diff --git a/tests/Multipart/MultipartBuilderFactoryTest.php b/tests/Multipart/MultipartBuilderFactoryTest.php
new file mode 100644
index 0000000..9b58b98
--- /dev/null
+++ b/tests/Multipart/MultipartBuilderFactoryTest.php
@@ -0,0 +1,403 @@
+<?php
+
+declare(strict_types=1);
+
+use Farzai\Transport\Factory\HttpFactory;
+use Farzai\Transport\Multipart\MultipartBuilderFactory;
+use Farzai\Transport\Multipart\MultipartStreamBuilder;
+use Farzai\Transport\Multipart\StreamingMultipartBuilder;
+
+beforeEach(function () {
+    $this->factory = HttpFactory::getInstance();
+
+    // Create a small test file (1 KB)
+    $this->smallFile = sys_get_temp_dir().'/small-file-'.uniqid().'.txt';
+    file_put_contents($this->smallFile, str_repeat('a', 1024));
+
+    // Create a large test file (11 MB - exceeds default 10 MB threshold)
+    $this->largeFile = sys_get_temp_dir().'/large-file-'.uniqid().'.txt';
+    $handle = fopen($this->largeFile, 'w');
+    for ($i = 0; $i < 11; $i++) {
+        fwrite($handle, str_repeat('b', 1024 * 1024)); // 1 MB at a time
+    }
+    fclose($handle);
+});
+
+afterEach(function () {
+    if (file_exists($this->smallFile)) {
+        @unlink($this->smallFile);
+    }
+    if (file_exists($this->largeFile)) {
+        @unlink($this->largeFile);
+    }
+});
+
+it('create returns MultipartStreamBuilder for small size', function () {
+    $parts = [
+        [
+            'name' => 'small_file',
+            'contents' => $this->smallFile,
+            'filename' => 'small.txt',
+        ],
+    ];
+
+    $builder = MultipartBuilderFactory::create(null, $parts);
+
+    expect($builder)->toBeInstanceOf(MultipartStreamBuilder::class);
+});
+
+it('create returns StreamingMultipartBuilder for large size', function () {
+    $parts = [
+        [
+            'name' => 'large_file',
+            'contents' => $this->largeFile,
+            'filename' => 'large.txt',
+        ],
+    ];
+
+    $builder = MultipartBuilderFactory::create(null, $parts);
+
+    expect($builder)->toBeInstanceOf(StreamingMultipartBuilder::class);
+});
+
+it('create uses default threshold', function () {
+    // Default is 10 MB
+    expect(MultipartBuilderFactory::DEFAULT_STREAMING_THRESHOLD)->toBe(10 * 1024 * 1024);
+});
+
+it('create respects custom threshold', function () {
+    $parts = [
+        [
+            'name' => 'file',
+            'contents' => $this->smallFile, // 1 KB
+            'filename' => 'file.txt',
+        ],
+    ];
+
+    // Set threshold to 512 bytes - our 1KB file should use streaming
+    $builder = MultipartBuilderFactory::create(null, $parts, 512);
+
+    expect($builder)->toBeInstanceOf(StreamingMultipartBuilder::class);
+});
+
+it('create defaults to standard when no parts provided', function () {
+    $builder = MultipartBuilderFactory::create();
+
+    expect($builder)->toBeInstanceOf(MultipartStreamBuilder::class);
+});
+
+it('create uses streaming when size cannot be determined', function () {
+    // Test with invalid content type that will return null size
+    $parts = [
+        [
+            'name' => 'unknown',
+            'contents' => new stdClass, // Invalid content type
+        ],
+    ];
+
+    $builder = MultipartBuilderFactory::create(null, $parts);
+
+    // When size is unknown, should use streaming for safety
+    expect($builder)->toBeInstanceOf(StreamingMultipartBuilder::class);
+});
+
+it('createStandard returns MultipartStreamBuilder', function () {
+    $builder = MultipartBuilderFactory::createStandard();
+
+    expect($builder)->toBeInstanceOf(MultipartStreamBuilder::class);
+});
+
+it('createStandard accepts custom boundary', function () {
+    $boundary = 'CustomBoundary123';
+    $builder = MultipartBuilderFactory::createStandard(null, $boundary);
+
+    expect($builder->getBoundary())->toBe($boundary);
+});
+
+it('createStreaming returns StreamingMultipartBuilder', function () {
+    $builder = MultipartBuilderFactory::createStreaming();
+
+    expect($builder)->toBeInstanceOf(StreamingMultipartBuilder::class);
+});
+
+it('createStreaming accepts custom boundary and chunk size', function () {
+    $boundary = 'StreamBoundary456';
+    $chunkSize = 16384;
+
+    $builder = MultipartBuilderFactory::createStreaming(null, $boundary, $chunkSize);
+
+    expect($builder->getBoundary())->toBe($boundary)
+        ->and($builder->getChunkSize())->toBe($chunkSize);
+});
+
+it('calculateTotalSize handles string contents', function () {
+    $parts = [
+        ['name' => 'field1', 'contents' => 'Hello'],
+        ['name' => 'field2', 'contents' => 'World'],
+    ];
+
+    $shouldStream = MultipartBuilderFactory::shouldUseStreaming($parts, 100);
+
+    expect($shouldStream)->toBeFalse(); // Total is 10 bytes, threshold is 100
+});
+
+it('calculateTotalSize handles file paths', function () {
+    $parts = [
+        [
+            'name' => 'file',
+            'contents' => $this->smallFile,
+            'filename' => 'file.txt',
+        ],
+    ];
+
+    $shouldStream = MultipartBuilderFactory::shouldUseStreaming($parts, 512);
+
+    expect($shouldStream)->toBeTrue(); // 1KB file > 512 bytes threshold
+});
+
+it('calculateTotalSize handles StreamInterface', function () {
+    $stream = $this->factory->createStream('Stream content here');
+
+    $parts = [
+        [
+            'name' => 'stream',
+            'contents' => $stream,
+            'filename' => 'data.txt',
+        ],
+    ];
+
+    // Stream has size, so should be calculable
+    $builder = MultipartBuilderFactory::create(null, $parts, 100);
+
+    // 19 bytes of content < 100 bytes threshold
+    expect($builder)->toBeInstanceOf(MultipartStreamBuilder::class);
+});
+
+it('calculateTotalSize returns null for unknown size', function () {
+    // Create parts with unknown size
+    $parts = [
+        [
+            'name' => 'unknown',
+            'contents' => new stdClass, // Invalid content type
+        ],
+    ];
+
+    $shouldStream = MultipartBuilderFactory::shouldUseStreaming($parts);
+
+    expect($shouldStream)->toBeTrue(); // Unknown size = use streaming
+});
+
+it('getRecommendedBuilder returns correct class', function () {
+    $smallSize = 5 * 1024 * 1024; // 5 MB
+    $largeSize = 15 * 1024 * 1024; // 15 MB
+    $threshold = 10 * 1024 * 1024; // 10 MB
+
+    expect(MultipartBuilderFactory::getRecommendedBuilder($smallSize, $threshold))
+        ->toBe(MultipartStreamBuilder::class);
+
+    expect(MultipartBuilderFactory::getRecommendedBuilder($largeSize, $threshold))
+        ->toBe(StreamingMultipartBuilder::class);
+});
+
+it('shouldUseStreaming returns correct boolean', function () {
+    $smallParts = [
+        ['name' => 'text', 'contents' => 'Small content'],
+    ];
+
+    $largeParts = [
+        [
+            'name' => 'file',
+            'contents' => $this->largeFile,
+            'filename' => 'large.txt',
+        ],
+    ];
+
+    expect(MultipartBuilderFactory::shouldUseStreaming($smallParts))->toBeFalse()
+        ->and(MultipartBuilderFactory::shouldUseStreaming($largeParts))->toBeTrue();
+});
+
+it('shouldUseStreaming recommends streaming when size unknown', function () {
+    $parts = [
+        [
+            'name' => 'data',
+            'contents' => ['invalid' => 'type'], // Invalid content
+        ],
+    ];
+
+    expect(MultipartBuilderFactory::shouldUseStreaming($parts))->toBeTrue();
+});
+
+it('formatSize formats bytes correctly', function () {
+    expect(MultipartBuilderFactory::formatSize(0))->toBe('0.0 B')
+        ->and(MultipartBuilderFactory::formatSize(1))->toBe('1.0 B')
+        ->and(MultipartBuilderFactory::formatSize(1024))->toBe('1.0 KB')
+        ->and(MultipartBuilderFactory::formatSize(1024 * 1024))->toBe('1.0 MB')
+        ->and(MultipartBuilderFactory::formatSize(1024 * 1024 * 1024))->toBe('1.0 GB');
+});
+
+it('formatSize formats with decimal', function () {
+    expect(MultipartBuilderFactory::formatSize(1536))->toBe('1.5 KB')
+        ->and(MultipartBuilderFactory::formatSize(2621440))->toBe('2.5 MB')
+        ->and(MultipartBuilderFactory::formatSize(11274289152))->toBe('10.5 GB');
+});
+
+it('formatSize handles large sizes', function () {
+    // Test TB
+    $oneTerabyte = 1024 * 1024 * 1024 * 1024;
+    $formatted = MultipartBuilderFactory::formatSize($oneTerabyte);
+
+    expect($formatted)->toContain('TB');
+});
+
+it('getDefaultThreshold returns 10MB', function () {
+    $threshold = MultipartBuilderFactory::getDefaultThreshold();
+
+    expect($threshold)->toBe(10 * 1024 * 1024)
+        ->and($threshold)->toBe(10485760);
+});
+
+it('getDefaultThresholdFormatted returns formatted string', function () {
+    $formatted = MultipartBuilderFactory::getDefaultThresholdFormatted();
+
+    expect($formatted)->toBe('10.0 MB');
+});
+
+it('handles multiple files total size calculation', function () {
+    $parts = [
+        [
+            'name' => 'file1',
+            'contents' => $this->smallFile,
+            'filename' => 'file1.txt',
+        ],
+        [
+            'name' => 'file2',
+            'contents' => $this->smallFile,
+            'filename' => 'file2.txt',
+        ],
+    ];
+
+    // 2KB total < 10MB threshold
+    $builder = MultipartBuilderFactory::create(null, $parts);
+
+    expect($builder)->toBeInstanceOf(MultipartStreamBuilder::class);
+});
+
+it('handles mixed content types', function () {
+    $stream = $this->factory->createStream('Stream data');
+
+    $parts = [
+        ['name' => 'text', 'contents' => 'Text field'],
+        [
+            'name' => 'file',
+            'contents' => $this->smallFile,
+            'filename' => 'file.txt',
+        ],
+        [
+            'name' => 'stream',
+            'contents' => $stream,
+            'filename' => 'data.txt',
+        ],
+    ];
+
+    $builder = MultipartBuilderFactory::create(null, $parts);
+
+    // Total should be small, so standard builder
+    expect($builder)->toBeInstanceOf(MultipartStreamBuilder::class);
+});
+
+it('handles empty parts array', function () {
+    $builder = MultipartBuilderFactory::create(null, []);
+
+    expect($builder)->toBeInstanceOf(MultipartStreamBuilder::class);
+});
+
+it('skips invalid parts in size calculation', function () {
+    $parts = [
+        ['name' => 'valid', 'contents' => 'Valid content'],
+        ['name' => 'no_contents'], // Missing contents
+        'invalid_structure', // Not an array
+    ];
+
+    $shouldStream = MultipartBuilderFactory::shouldUseStreaming($parts, 100);
+
+    // Should still work, only counting valid parts
+    expect($shouldStream)->toBeFalse();
+});
+
+it('handles file that cannot get size', function () {
+    $parts = [
+        [
+            'name' => 'resource',
+            'contents' => tmpfile(), // Resource without size
+        ],
+    ];
+
+    // Should return streaming builder when size cannot be determined
+    $builder = MultipartBuilderFactory::create(null, $parts);
+
+    expect($builder)->toBeInstanceOf(StreamingMultipartBuilder::class);
+});
+
+it('distinguishes string content from file path', function () {
+    $parts = [
+        // String content without filename - treated as text field
+        ['name' => 'field', 'contents' => 'Just text'],
+        // String with filename but not a real file - still treated as string
+        ['name' => 'fake_file', 'contents' => '/not/a/file', 'filename' => 'fake.txt'],
+    ];
+
+    $shouldStream = MultipartBuilderFactory::shouldUseStreaming($parts, 100);
+
+    expect($shouldStream)->toBeFalse(); // Small text content
+});
+
+it('create accepts HttpFactory parameter', function () {
+    $factory = HttpFactory::getInstance();
+
+    $builder = MultipartBuilderFactory::create($factory);
+
+    expect($builder)->toBeInstanceOf(MultipartStreamBuilder::class);
+});
+
+it('create accepts custom boundary', function () {
+    $boundary = 'MyCustomBoundary';
+
+    $builder = MultipartBuilderFactory::create(null, null, boundary: $boundary);
+
+    expect($builder->getBoundary())->toBe($boundary);
+});
+
+it('threshold exactly at boundary uses streaming', function () {
+    $threshold = 1024; // 1 KB
+    $parts = [
+        ['name' => 'text', 'contents' => str_repeat('a', 1024)], // Exactly 1 KB
+    ];
+
+    $builder = MultipartBuilderFactory::create(null, $parts, $threshold);
+
+    // At threshold or above = streaming
+    expect($builder)->toBeInstanceOf(StreamingMultipartBuilder::class);
+});
+
+it('just below threshold uses standard', function () {
+    $threshold = 1024; // 1 KB
+    $parts = [
+        ['name' => 'text', 'contents' => str_repeat('a', 1023)], // Just below
+    ];
+
+    $builder = MultipartBuilderFactory::create(null, $parts, $threshold);
+
+    expect($builder)->toBeInstanceOf(MultipartStreamBuilder::class);
+});
+
+it('formatSize handles fractional KB', function () {
+    $size = 1536; // 1.5 KB
+    $formatted = MultipartBuilderFactory::formatSize($size);
+
+    expect($formatted)->toBe('1.5 KB');
+});
+
+it('formatSize handles bytes less than 1KB', function () {
+    expect(MultipartBuilderFactory::formatSize(512))->toBe('512.0 B')
+        ->and(MultipartBuilderFactory::formatSize(100))->toBe('100.0 B');
+});
diff --git a/tests/Multipart/MultipartStreamTest.php b/tests/Multipart/MultipartStreamTest.php
new file mode 100644
index 0000000..f140cd7
--- /dev/null
+++ b/tests/Multipart/MultipartStreamTest.php
@@ -0,0 +1,453 @@
+<?php
+
+declare(strict_types=1);
+
+use Farzai\Transport\Factory\HttpFactory;
+use Farzai\Transport\Multipart\MultipartStream;
+use Farzai\Transport\Multipart\Part;
+
+beforeEach(function () {
+    $this->factory = HttpFactory::getInstance();
+
+    // Create a temporary test file
+    $this->testFile = sys_get_temp_dir().'/multipart-stream-test-'.uniqid().'.txt';
+    file_put_contents($this->testFile, 'Test file content for multipart streaming');
+});
+
+afterEach(function () {
+    if (file_exists($this->testFile)) {
+        @unlink($this->testFile);
+    }
+});
+
+it('creates stream with parts boundary and chunk size', function () {
+    $parts = [Part::text('field', 'value')];
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+
+    expect($stream)->toBeInstanceOf(MultipartStream::class);
+});
+
+it('read returns correct data chunks', function () {
+    $parts = [Part::text('name', 'John Doe')];
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+
+    $chunk = $stream->read(50);
+
+    expect($chunk)->toBeString()
+        ->and($chunk)->toContain('--TestBoundary');
+});
+
+it('read returns empty string when eof', function () {
+    $parts = [];
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+
+    // Read everything
+    $stream->getContents();
+
+    expect($stream->eof())->toBeTrue()
+        ->and($stream->read(100))->toBe('');
+});
+
+it('fills buffer progressively', function () {
+    $parts = [Part::text('field', 'value')];
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+
+    $chunk1 = $stream->read(10);
+    $chunk2 = $stream->read(10);
+
+    expect($chunk1)->toBeString()
+        ->and($chunk2)->toBeString()
+        ->and($chunk1)->not->toBeEmpty();
+});
+
+it('writes boundaries correctly', function () {
+    $parts = [Part::text('field', 'value')];
+    $stream = new MultipartStream($parts, 'CustomBoundary', 8192);
+
+    $content = $stream->getContents();
+
+    expect($content)->toContain('--CustomBoundary')
+        ->and($content)->toContain('--CustomBoundary--'); // Closing boundary
+});
+
+it('writes closing boundary', function () {
+    $parts = [Part::text('field', 'value')];
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+
+    $content = $stream->getContents();
+
+    expect($content)->toEndWith("--TestBoundary--\r\n");
+});
+
+it('writes part headers correctly', function () {
+    $parts = [Part::text('username', 'john_doe')];
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+
+    $content = $stream->getContents();
+
+    expect($content)->toContain('Content-Disposition:')
+        ->and($content)->toContain('form-data')
+        ->and($content)->toContain('name="username"');
+});
+
+it('writes CRLF separators', function () {
+    $parts = [Part::text('field', 'value')];
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+
+    $content = $stream->getContents();
+
+    expect($content)->toContain("\r\n");
+});
+
+it('streams file content in chunks', function () {
+    $fileStream = $this->factory->createStreamFromFile($this->testFile, 'r');
+    $parts = [Part::file('document', $fileStream, 'test.txt')];
+
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+    $content = $stream->getContents();
+
+    expect($content)->toContain('Test file content for multipart streaming');
+});
+
+it('handles string content', function () {
+    $parts = [Part::text('message', 'Hello World')];
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+
+    $content = $stream->getContents();
+
+    expect($content)->toContain('Hello World');
+});
+
+it('handles StreamInterface content', function () {
+    $contentStream = $this->factory->createStream('Stream content here');
+    $parts = [Part::file('file', $contentStream, 'data.txt')];
+
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+    $content = $stream->getContents();
+
+    expect($content)->toContain('Stream content here');
+});
+
+it('eof returns false initially', function () {
+    $parts = [Part::text('field', 'value')];
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+
+    expect($stream->eof())->toBeFalse();
+});
+
+it('eof returns true at end', function () {
+    $parts = [Part::text('field', 'value')];
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+
+    $stream->getContents();
+
+    expect($stream->eof())->toBeTrue();
+});
+
+it('tell tracks position correctly', function () {
+    $parts = [Part::text('field', 'value')];
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+
+    expect($stream->tell())->toBe(0);
+
+    $stream->read(10);
+    expect($stream->tell())->toBe(10);
+
+    $stream->read(5);
+    expect($stream->tell())->toBe(15);
+});
+
+it('getSize returns null', function () {
+    $parts = [Part::text('field', 'value')];
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+
+    expect($stream->getSize())->toBeNull();
+});
+
+it('isSeekable returns false', function () {
+    $parts = [Part::text('field', 'value')];
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+
+    expect($stream->isSeekable())->toBeFalse();
+});
+
+it('seek throws RuntimeException', function () {
+    $parts = [Part::text('field', 'value')];
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+
+    expect(fn () => $stream->seek(0))
+        ->toThrow(RuntimeException::class, 'Stream is not seekable');
+});
+
+it('rewind throws RuntimeException', function () {
+    $parts = [Part::text('field', 'value')];
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+
+    expect(fn () => $stream->rewind())
+        ->toThrow(RuntimeException::class, 'Stream cannot be rewound');
+});
+
+it('isWritable returns false', function () {
+    $parts = [Part::text('field', 'value')];
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+
+    expect($stream->isWritable())->toBeFalse();
+});
+
+it('write throws RuntimeException', function () {
+    $parts = [Part::text('field', 'value')];
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+
+    expect(fn () => $stream->write('data'))
+        ->toThrow(RuntimeException::class, 'Stream is not writable');
+});
+
+it('isReadable returns true', function () {
+    $parts = [Part::text('field', 'value')];
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+
+    expect($stream->isReadable())->toBeTrue();
+});
+
+it('getContents reads all remaining data', function () {
+    $parts = [
+        Part::text('field1', 'value1'),
+        Part::text('field2', 'value2'),
+    ];
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+
+    $content = $stream->getContents();
+
+    expect($content)->toContain('value1')
+        ->and($content)->toContain('value2')
+        ->and($stream->eof())->toBeTrue();
+});
+
+it('close closes file handles', function () {
+    $parts = [Part::text('field', 'value')];
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+
+    $stream->close();
+
+    expect($stream->eof())->toBeTrue();
+});
+
+it('detach returns and clears file handle', function () {
+    $parts = [Part::text('field', 'value')];
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+
+    $handle = $stream->detach();
+
+    expect($stream->eof())->toBeTrue();
+    // Handle might be null if no file was being read
+    expect($handle === null || is_resource($handle))->toBeTrue();
+});
+
+it('getMetadata returns stream info', function () {
+    $parts = [Part::text('field', 'value')];
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+
+    $metadata = $stream->getMetadata();
+
+    expect($metadata)->toBeArray()
+        ->and($metadata)->toHaveKey('boundary')
+        ->and($metadata)->toHaveKey('chunk_size')
+        ->and($metadata)->toHaveKey('parts_count')
+        ->and($metadata['boundary'])->toBe('TestBoundary')
+        ->and($metadata['chunk_size'])->toBe(8192)
+        ->and($metadata['parts_count'])->toBe(1);
+});
+
+it('getMetadata with key returns specific value', function () {
+    $parts = [Part::text('field', 'value')];
+    $stream = new MultipartStream($parts, 'TestBoundary', 4096);
+
+    expect($stream->getMetadata('boundary'))->toBe('TestBoundary')
+        ->and($stream->getMetadata('chunk_size'))->toBe(4096)
+        ->and($stream->getMetadata('parts_count'))->toBe(1)
+        ->and($stream->getMetadata('non_existent_key'))->toBeNull();
+});
+
+it('toString returns full content', function () {
+    $parts = [Part::text('name', 'John')];
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+
+    // __toString() calls rewind() which throws, so it catches and returns empty
+    // This is expected behavior for non-rewindable streams
+    $content = (string) $stream;
+
+    // After __toString fails (due to rewind), stream should return empty string
+    expect($content)->toBe('');
+});
+
+it('toString returns empty string on error', function () {
+    // Create stream that will throw on rewind
+    $parts = [Part::text('field', 'value')];
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+
+    // Read some data first
+    $stream->read(10);
+
+    // __toString tries to rewind, which will throw
+    // Should catch and return empty string
+    $result = (string) $stream;
+
+    expect($result)->toBe('');
+});
+
+it('multiple parts processed correctly', function () {
+    $parts = [
+        Part::text('field1', 'value1'),
+        Part::text('field2', 'value2'),
+        Part::text('field3', 'value3'),
+    ];
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+
+    $content = $stream->getContents();
+
+    // Check all parts are present
+    expect($content)->toContain('value1')
+        ->and($content)->toContain('value2')
+        ->and($content)->toContain('value3');
+
+    // Check boundaries between parts
+    expect(substr_count($content, '--TestBoundary'."\r\n"))->toBe(3);
+});
+
+it('handles empty parts array', function () {
+    $stream = new MultipartStream([], 'TestBoundary', 8192);
+
+    $content = $stream->getContents();
+
+    expect($content)->toContain('--TestBoundary--')
+        ->and($stream->eof())->toBeTrue();
+});
+
+it('handles mixed text and file parts', function () {
+    $fileStream = $this->factory->createStream('File content');
+
+    $parts = [
+        Part::text('title', 'Document Title'),
+        Part::file('document', $fileStream, 'doc.txt'),
+        Part::text('description', 'Description here'),
+    ];
+
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+    $content = $stream->getContents();
+
+    expect($content)->toContain('Document Title')
+        ->and($content)->toContain('File content')
+        ->and($content)->toContain('Description here');
+});
+
+it('reads in small chunks', function () {
+    $parts = [Part::text('field', 'value')];
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+
+    $chunks = [];
+    while (! $stream->eof()) {
+        $chunk = $stream->read(5); // Read very small chunks
+        if ($chunk !== '') {
+            $chunks[] = $chunk;
+        }
+    }
+
+    expect(count($chunks))->toBeGreaterThan(1);
+    $fullContent = implode('', $chunks);
+    expect($fullContent)->toContain('value');
+});
+
+it('position increments correctly', function () {
+    $parts = [Part::text('test', 'data')];
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+
+    $pos1 = $stream->tell();
+    $stream->read(10);
+    $pos2 = $stream->tell();
+    $stream->read(10);
+    $pos3 = $stream->tell();
+
+    expect($pos1)->toBe(0)
+        ->and($pos2)->toBe(10)
+        ->and($pos3)->toBe(20);
+});
+
+it('handles large content efficiently', function () {
+    // Create a large text field
+    $largeContent = str_repeat('A', 100000); // 100KB
+    $parts = [Part::text('large_field', $largeContent)];
+
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+
+    // Read in chunks
+    $totalRead = 0;
+    while (! $stream->eof()) {
+        $chunk = $stream->read(8192);
+        $totalRead += strlen($chunk);
+    }
+
+    expect($totalRead)->toBeGreaterThan(100000);
+});
+
+it('destructor closes handles', function () {
+    $parts = [Part::text('field', 'value')];
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+
+    // Let destructor run
+    unset($stream);
+
+    // If we reach here without errors, destructor worked
+    expect(true)->toBeTrue();
+});
+
+it('handles file streaming with actual file', function () {
+    $fileStream = $this->factory->createStreamFromFile($this->testFile, 'r');
+    $parts = [Part::file('upload', $fileStream, 'document.txt', 'text/plain')];
+
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+    $content = $stream->getContents();
+
+    expect($content)->toContain('Content-Disposition: form-data')
+        ->and($content)->toContain('name="upload"')
+        ->and($content)->toContain('filename="document.txt"')
+        ->and($content)->toContain('Content-Type: text/plain')
+        ->and($content)->toContain('Test file content for multipart streaming');
+});
+
+it('close sets eof to true', function () {
+    $parts = [Part::text('field', 'value')];
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+
+    expect($stream->eof())->toBeFalse();
+
+    $stream->close();
+
+    expect($stream->eof())->toBeTrue();
+});
+
+it('detach sets eof to true', function () {
+    $parts = [Part::text('field', 'value')];
+    $stream = new MultipartStream($parts, 'TestBoundary', 8192);
+
+    expect($stream->eof())->toBeFalse();
+
+    $stream->detach();
+
+    expect($stream->eof())->toBeTrue();
+});
+
+it('formats multipart correctly according to RFC7578', function () {
+    $parts = [
+        Part::text('name', 'John Doe'),
+        Part::text('email', 'john@example.com'),
+    ];
+
+    $stream = new MultipartStream($parts, 'Boundary123', 8192);
+    $content = $stream->getContents();
+
+    // Verify RFC 7578 format
+    expect($content)->toMatch('/--Boundary123\r\n/')
+        ->and($content)->toMatch('/Content-Disposition: form-data; name="name"\r\n/')
+        ->and($content)->toMatch('/\r\n\r\nJohn Doe\r\n/')
+        ->and($content)->toEndWith('--Boundary123--'."\r\n");
+});
diff --git a/tests/Multipart/StreamingMultipartBuilderTest.php b/tests/Multipart/StreamingMultipartBuilderTest.php
new file mode 100644
index 0000000..b648c18
--- /dev/null
+++ b/tests/Multipart/StreamingMultipartBuilderTest.php
@@ -0,0 +1,364 @@
+<?php
+
+declare(strict_types=1);
+
+use Farzai\Transport\Factory\HttpFactory;
+use Farzai\Transport\Multipart\MultipartStream;
+use Farzai\Transport\Multipart\Part;
+use Farzai\Transport\Multipart\StreamingMultipartBuilder;
+
+beforeEach(function () {
+    $this->factory = HttpFactory::getInstance();
+
+    // Create a temporary test file
+    $this->testFile = sys_get_temp_dir().'/transport-php-test-'.uniqid().'.txt';
+    file_put_contents($this->testFile, 'Test file content for streaming upload');
+});
+
+afterEach(function () {
+    if (file_exists($this->testFile)) {
+        @unlink($this->testFile);
+    }
+});
+
+it('creates builder with default settings', function () {
+    $builder = new StreamingMultipartBuilder;
+
+    expect($builder)->toBeInstanceOf(StreamingMultipartBuilder::class)
+        ->and($builder->getChunkSize())->toBe(8192) // Default 8KB
+        ->and($builder->getContentType())->toStartWith('multipart/form-data; boundary=');
+});
+
+it('creates builder with custom boundary', function () {
+    $boundary = 'CustomBoundary123';
+    $builder = new StreamingMultipartBuilder(null, $boundary);
+
+    expect($builder->getBoundary())->toBe($boundary)
+        ->and($builder->getContentType())->toBe("multipart/form-data; boundary={$boundary}");
+});
+
+it('creates builder with custom chunk size', function () {
+    $builder = new StreamingMultipartBuilder(null, null, 16384);
+
+    expect($builder->getChunkSize())->toBe(16384);
+});
+
+it('addField adds text field', function () {
+    $builder = new StreamingMultipartBuilder;
+    $result = $builder->addField('username', 'john_doe');
+
+    expect($result)->toBe($builder) // Fluent interface
+        ->and($builder->getParts())->toHaveCount(1);
+});
+
+it('addFile throws exception for non readable file', function () {
+    $builder = new StreamingMultipartBuilder;
+
+    expect(fn () => $builder->addFile('document', '/non/existent/file.txt'))
+        ->toThrow(RuntimeException::class, 'File not readable:');
+});
+
+it('addFile throws exception for non file path', function () {
+    $builder = new StreamingMultipartBuilder;
+    $directory = sys_get_temp_dir();
+
+    expect(fn () => $builder->addFile('document', $directory))
+        ->toThrow(RuntimeException::class, 'Not a file:');
+});
+
+it('addFile adds file with custom filename', function () {
+    $builder = new StreamingMultipartBuilder;
+    $builder->addFile('document', $this->testFile, 'custom-name.txt');
+
+    expect($builder->getParts())->toHaveCount(1);
+});
+
+it('addFile uses basename when filename not provided', function () {
+    $builder = new StreamingMultipartBuilder;
+    $builder->addFile('document', $this->testFile);
+
+    $parts = $builder->getParts();
+    expect($parts)->toHaveCount(1);
+
+    // Verify the part was created (filename would be basename of testFile)
+    $headers = $parts[0]->getHeaders();
+    expect($headers['Content-Disposition'])->toContain('transport-php-test-');
+});
+
+it('addFile creates stream from file path', function () {
+    $builder = new StreamingMultipartBuilder;
+    $builder->addFile('document', $this->testFile, 'test.txt', 'text/plain');
+
+    $parts = $builder->getParts();
+    expect($parts)->toHaveCount(1)
+        ->and($parts[0])->toBeInstanceOf(Part::class);
+});
+
+it('addFileContents accepts string contents', function () {
+    $builder = new StreamingMultipartBuilder;
+    $builder->addFileContents('file', 'string content', 'file.txt');
+
+    expect($builder->getParts())->toHaveCount(1);
+});
+
+it('addFileContents accepts StreamInterface contents', function () {
+    $builder = new StreamingMultipartBuilder;
+    $stream = $this->factory->createStream('stream content');
+
+    $builder->addFileContents('file', $stream, 'file.txt');
+
+    expect($builder->getParts())->toHaveCount(1);
+});
+
+it('addPart adds custom Part object', function () {
+    $builder = new StreamingMultipartBuilder;
+    $part = Part::text('field', 'value');
+
+    $result = $builder->addPart($part);
+
+    expect($result)->toBe($builder)
+        ->and($builder->getParts())->toHaveCount(1)
+        ->and($builder->getParts()[0])->toBe($part);
+});
+
+it('addMultiple handles simple key value format', function () {
+    $builder = new StreamingMultipartBuilder;
+    $builder->addMultiple([
+        'name' => 'John Doe',
+        'email' => 'john@example.com',
+        'age' => '30',
+    ]);
+
+    expect($builder->getParts())->toHaveCount(3);
+});
+
+it('addMultiple handles array format with files', function () {
+    $builder = new StreamingMultipartBuilder;
+    $builder->addMultiple([
+        [
+            'name' => 'document',
+            'contents' => $this->testFile,
+            'filename' => 'upload.txt',
+        ],
+        [
+            'name' => 'description',
+            'contents' => 'File description',
+        ],
+    ]);
+
+    expect($builder->getParts())->toHaveCount(2);
+});
+
+it('getBoundary returns boundary string', function () {
+    $builder = new StreamingMultipartBuilder;
+    $boundary = $builder->getBoundary();
+
+    expect($boundary)->toBeString()
+        ->and($boundary)->toStartWith('----TransportPHPStreaming');
+});
+
+it('getContentType returns correct header value', function () {
+    $boundary = 'TestBoundary123';
+    $builder = new StreamingMultipartBuilder(null, $boundary);
+
+    expect($builder->getContentType())->toBe("multipart/form-data; boundary={$boundary}");
+});
+
+it('setChunkSize sets size with minimum 1KB', function () {
+    $builder = new StreamingMultipartBuilder;
+
+    // Try to set below minimum
+    $builder->setChunkSize(512);
+    expect($builder->getChunkSize())->toBe(1024); // Should be clamped to 1KB
+
+    // Set valid size
+    $builder->setChunkSize(4096);
+    expect($builder->getChunkSize())->toBe(4096);
+});
+
+it('setChunkSize returns builder for chaining', function () {
+    $builder = new StreamingMultipartBuilder;
+    $result = $builder->setChunkSize(2048);
+
+    expect($result)->toBe($builder);
+});
+
+it('getChunkSize returns chunk size', function () {
+    $builder = new StreamingMultipartBuilder(null, null, 16384);
+
+    expect($builder->getChunkSize())->toBe(16384);
+});
+
+it('build returns MultipartStream instance', function () {
+    $builder = new StreamingMultipartBuilder;
+    $builder->addField('test', 'value');
+
+    $stream = $builder->build();
+
+    expect($stream)->toBeInstanceOf(MultipartStream::class);
+});
+
+it('getParts returns array of parts', function () {
+    $builder = new StreamingMultipartBuilder;
+    $builder->addField('field1', 'value1');
+    $builder->addField('field2', 'value2');
+
+    $parts = $builder->getParts();
+
+    expect($parts)->toBeArray()
+        ->and($parts)->toHaveCount(2)
+        ->and($parts)->each->toBeInstanceOf(Part::class);
+});
+
+it('count returns correct part count', function () {
+    $builder = new StreamingMultipartBuilder;
+
+    expect($builder->count())->toBe(0);
+
+    $builder->addField('field1', 'value1');
+    expect($builder->count())->toBe(1);
+
+    $builder->addField('field2', 'value2');
+    expect($builder->count())->toBe(2);
+});
+
+it('getSize calculates total size', function () {
+    $builder = new StreamingMultipartBuilder(null, 'TestBoundary');
+    $builder->addField('name', 'John');
+
+    $size = $builder->getSize();
+
+    expect($size)->toBeInt()
+        ->and($size)->toBeGreaterThan(0);
+});
+
+it('getSize returns null when size cannot be determined', function () {
+    $builder = new StreamingMultipartBuilder;
+
+    // Add a part with unknown size (using a non-seekable stream)
+    $stream = $this->factory->createStream('content');
+    $builder->addFileContents('file', $stream, 'test.txt');
+
+    // For string streams, size should be determinable, so let's test with actual scenario
+    // In real case, getSize() might return null for non-seekable streams
+    $size = $builder->getSize();
+
+    // This test depends on implementation - size might be calculable or not
+    expect($size === null || is_int($size))->toBeTrue();
+});
+
+it('Boundary starts with TransportPHPStreaming', function () {
+    $builder = new StreamingMultipartBuilder;
+    $boundary = $builder->getBoundary();
+
+    expect($boundary)->toStartWith('----TransportPHPStreaming')
+        ->and(strlen($boundary))->toBeGreaterThan(25); // Should have random suffix
+});
+
+it('create static factory works', function () {
+    $builder = StreamingMultipartBuilder::create();
+
+    expect($builder)->toBeInstanceOf(StreamingMultipartBuilder::class);
+});
+
+it('create accepts custom factory and boundary', function () {
+    $factory = HttpFactory::getInstance();
+    $boundary = 'CustomBoundary';
+
+    $builder = StreamingMultipartBuilder::create($factory, $boundary);
+
+    expect($builder->getBoundary())->toBe($boundary);
+});
+
+it('supports fluent interface', function () {
+    $builder = new StreamingMultipartBuilder;
+
+    $result = $builder
+        ->addField('name', 'John')
+        ->addField('email', 'john@example.com')
+        ->setChunkSize(4096);
+
+    expect($result)->toBe($builder)
+        ->and($builder->getParts())->toHaveCount(2);
+});
+
+it('handles multiple files', function () {
+    $file2 = sys_get_temp_dir().'/transport-php-test-2-'.uniqid().'.txt';
+    file_put_contents($file2, 'Second file content');
+
+    try {
+        $builder = new StreamingMultipartBuilder;
+        $builder->addFile('file1', $this->testFile);
+        $builder->addFile('file2', $file2);
+
+        expect($builder->getParts())->toHaveCount(2);
+    } finally {
+        @unlink($file2);
+    }
+});
+
+it('handles mixed fields and files', function () {
+    $builder = new StreamingMultipartBuilder;
+    $builder->addField('title', 'Document Title');
+    $builder->addFile('document', $this->testFile);
+    $builder->addField('description', 'Document Description');
+
+    expect($builder->getParts())->toHaveCount(3);
+});
+
+it('addFile with content type', function () {
+    $builder = new StreamingMultipartBuilder;
+    $builder->addFile('image', $this->testFile, 'photo.jpg', 'image/jpeg');
+
+    $parts = $builder->getParts();
+    expect($parts)->toHaveCount(1);
+});
+
+it('addFileContents with content type', function () {
+    $builder = new StreamingMultipartBuilder;
+    $builder->addFileContents('data', '{"key":"value"}', 'data.json', 'application/json');
+
+    $parts = $builder->getParts();
+    $headers = $parts[0]->getHeaders();
+    expect($headers['Content-Type'])->toContain('application/json');
+});
+
+it('chunk size enforces minimum during construction', function () {
+    $builder = new StreamingMultipartBuilder(null, null, 100); // Below 1KB
+
+    expect($builder->getChunkSize())->toBe(1024);
+});
+
+it('handles empty builder', function () {
+    $builder = new StreamingMultipartBuilder;
+
+    expect($builder->getParts())->toHaveCount(0)
+        ->and($builder->count())->toBe(0);
+});
+
+it('build works with empty parts', function () {
+    $builder = new StreamingMultipartBuilder;
+    $stream = $builder->build();
+
+    expect($stream)->toBeInstanceOf(MultipartStream::class);
+});
+
+it('addMultiple handles content type aliases', function () {
+    $builder = new StreamingMultipartBuilder;
+    $builder->addMultiple([
+        [
+            'name' => 'file1',
+            'contents' => 'content',
+            'filename' => 'test.txt',
+            'content-type' => 'text/plain',
+        ],
+        [
+            'name' => 'file2',
+            'contents' => 'content2',
+            'filename' => 'test2.txt',
+            'contentType' => 'text/html',
+        ],
+    ]);
+
+    expect($builder->getParts())->toHaveCount(2);
+});