docs: documentation of methods and usage

README.md

@@ -1,2 +1,271 @@
-# mock-paystack
+# mock-paystack-laravel
+
 PHP package for mocking Paystack responses and webhooks.
+
+## Overview
+
+MockPaystack is a Laravel package designed to simplify testing and development involving Paystack integrations. The MockPaystack package is a tool designed for developers to test and simulate interactions with Paystack APIs in a controlled environment. It provides utility classes, traits, and constants to handle various Paystack API operations, including webhooks, payment initialization, and response simulation.
+
+This package includes utilities for handling HTTP requests and responses, and it offers support for both `Illuminate\Http\Client` (Laravel HTTP client) and `GuzzleHttp` clients, ensuring compatibility with a wide range of use cases.
+
+---
+
+## Installation
+
+### Prerequisites
+
+- PHP 8.2 or higher
+- Laravel 9.x or higher
+- Composer
+
+### Installation Steps
+
+1. Add the package to your Laravel project using Composer:
+
+   ```bash
+   composer require emmo00/mock-paystack-laravel
+   ```
+
+2. Use trait in test class
+
+   ```php
+   use Emmo00\MockPaystack\MockPaystack;
+
+   class TransactionControllerTest extends TestCase 
+   {
+        use MockPaystack;
+   }
+   ```
+
+---
+
+## Features
+
+- Simulate Paystack API responses
+- Mock webhooks and payment interactions, such as successful payments, failed transactions, and more.
+- Validate request payloads and headers
+- Utilities to work seamlessly with `GuzzleHttp` and `Illuminate\Http\Client`.
+
+---
+
+### Example
+
+Here's a basic example of using the MockPaystack package:
+
+```php
+ use Emmo00\MockPaystack\MockPaystack;
+
+class ExampleTest extends TestCase
+{
+    use MockPaystack;
+
+    public function testInitializePayment()
+    {
+        $this->fakeInitializePayment(); // this catches any request made to the paystack api and returns a mock response
+
+        // make request to endpoint that calls paystack
+        $response = $this->get(route('subscriptions.pay'));
+
+
+        // Assert
+        $response->assertStatus(200);
+        $response->assertJsonStructure([
+            'message',
+            'data' => [
+                'authorization_url',
+            ],
+        ]);
+    }
+}
+```
+
+## Usage
+
+### Trait: `MockPaystack`
+
+This trait provides utility methods for handling HTTP requests, responses and webhook.
+
+### Initialize Payment Handler
+
+methods to simulate and validate Paystack payment initialization requests.
+
+#### Methods
+
+##### `fakeInitializePayment()`
+
+**Description**: Simulates an initialize payment request, ensuring required properties like `email`, `amount`, `currency`, and `Authorization` header are present.
+
+**Usage:**
+
+```php
+$this->fakeInitializePayment();
+```
+
+---
+
+##### `fakeInitializePaymentSuccess()`
+
+**Description**: Simulates a successful initialize payment request.
+
+**Usage:**
+
+```php
+$this->fakeInitializePaymentSuccess();
+```
+
+---
+
+##### `fakeInitializePaymentFailure()`
+
+**Description**: Simulates a failed initialize payment request.
+
+**Usage:**
+
+```php
+$this->fakeInitializePaymentFailure();
+```
+
+---
+
+##### `fakeInitializePaymentInvalidKey()`
+
+**Description**: Simulates a request with an invalid Authorization key.
+
+**Usage:**
+
+```php
+$this->fakeInitializePaymentInvalidKey();
+```
+
+---
+
+##### `fakeInitializePaymentInvalidRequest()`
+
+**Description**: Simulates a request with invalid payload or headers.
+
+**Usage:**
+
+```php
+$this->fakeInitializePaymentInvalidRequest();
+```
+
+---
+
+##### `fakeInitializePaymentInvalidCurrency()`
+
+**Description**: Simulates a request with an unsupported or missing currency field.
+
+**Usage:**
+
+```php
+$this->fakeInitializePaymentInvalidCurrency();
+```
+
+---
+
+##### `fakeInitializePaymentInvalidAmount()`
+
+**Description**: Simulates a request with an invalid or missing amount field.
+
+**Usage:**
+
+```php
+$this->fakeInitializePaymentInvalidAmount();
+```
+
+---
+
+##### `fakeInitializePaymentInvalidEmail()`
+
+**Description**: Simulates a request with an invalid or missing email field.
+
+**Usage:**
+
+```php
+$this->fakeInitializePaymentInvalidEmail();
+```
+
+---
+
+### Charge Success Webhook Handler
+
+`MockPaystack` also provides methods to simulate Paystack webhook notifications, like for the `charge.success` event.
+
+#### `fakeWebHookChargeSuccess()`
+
+**Description**: Sends a fake webhook `charge.success` notification to your Paystack webhook handler route.
+
+**Parameters:**
+
+- `string $route`: The webhook handler route.
+- `string $secret_key`: The secret key for webhook validation.
+- `array $metadata`: Additional metadata for the webhook.
+- `int $amount`: Transaction amount (default: 10000).
+- `string $currency`: Transaction currency (default: 'NGN').
+- `string $reference`: Transaction reference (default: 'reference').
+- `string $channel`: Payment channel (default: 'card').
+- `string $ip_address`: IP address of the transaction source (default: '0.0.0.0').
+- `array $customer`: Customer details.
+- `array $authorization`: Authorization details.
+- `bool $reusable_authorization`: Indicates if the authorization is reusable (default: true).
+
+**Returns:**
+`\Illuminate\Testing\TestResponse`: The response from your webhook handler route.
+
+**Usage:**
+
+```php
+$response = $this->fakeWebHookChargeSuccess(
+    '/webhook-route',
+    'your-secret-key',
+    ['custom-key' => 'custom-value'],
+    5000,
+    'USD',
+    'unique-reference',
+    'bank',
+    '192.168.1.1',
+    ['email' => '[email protected]'],
+    ['card' => 'visa'],
+    false
+);
+
+$response->assertStatus(200);
+```
+
+---
+---
+
+## Contributing
+
+1. Fork the repository.
+2. Create a new branch for your feature or bug fix:
+
+   ```bash
+   git checkout -b feature/my-new-feature
+   ```
+
+3. Commit your changes:
+
+   ```bash
+   git commit -m "Add some feature"
+   ```
+
+4. Push to the branch:
+
+   ```bash
+   git push origin feature/my-new-feature
+   ```
+
+5. Open a pull request.
+
+---
+
+## License
+
+This package is open-source software licensed under the [MIT license](LICENSE).
+
+---
+
+## Contact
+
+For questions or support, please reach out to [Emmanuel Nwafor](https://github.com/Emmo00).