Merge pull request #3 from njoguamos/add-ability-to-list-brands

Add ability to list brands

.github/workflows/phpstan.yml

@@ -1,11 +1,6 @@
 name: PHPStan
 
-on:
-  push:
-    paths:
-      - '**.php'
-      - 'phpstan.neon.dist'
-      - '.github/workflows/phpstan.yml'
+on: [pull_request]
 
 jobs:
   phpstan:

.github/workflows/run-tests.yml

@@ -28,8 +28,8 @@ jobs:
         uses: shivammathur/setup-php@v2
         with:
           php-version: ${{ matrix.php }}
-          extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite, bcmath, soap, intl, gd, exif, iconv, imagick, fileinfo
-          coverage: none
+          extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite, bcmath, soap, intl, gd, exif, iconv, imagick, fileinfo,
+          coverage: xdebug
 
       - name: Setup problem matchers
         run: |

README.md

@@ -1,18 +1,23 @@
-# A laravel package scaforlding Cash App API.
+# A laravel package scaffolding Cash App API.
 
-[![Latest Version on Packagist](https://img.shields.io/packagist/v/njoguamos/laravel-cashapp.svg?style=flat-square)](https://packagist.org/packages/njoguamos/laravel-cashapp)
-[![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/njoguamos/laravel-cashapp/run-tests.yml?branch=main&label=tests&style=flat-square)](https://github.com/njoguamos/laravel-cashapp/actions?query=workflow%3Arun-tests+branch%3Amain)
-[![GitHub Code Style Action Status](https://img.shields.io/github/actions/workflow/status/njoguamos/laravel-cashapp/fix-php-code-style-issues.yml?branch=main&label=code%20style&style=flat-square)](https://github.com/njoguamos/laravel-cashapp/actions?query=workflow%3A"Fix+PHP+code+style+issues"+branch%3Amain)
-[![Total Downloads](https://img.shields.io/packagist/dt/njoguamos/laravel-cashapp.svg?style=flat-square)](https://packagist.org/packages/njoguamos/laravel-cashapp)
-
-This is where your description should go. Limit it to a paragraph or two. Consider adding a small example.
+- [ ] Add description
 
 ## Installation
 
-You can install the package via composer:
-
-```bash
-composer require njoguamos/laravel-cashapp
+This package is not public. You can install the package by updating your project composer as follows. 
+
+```json
+{
+    "repositories": [
+        {
+            "type": "vcs",
+            "url": "https://github.com/njoguamos/laravel-cashapp.git"
+        }
+    ],
+    "require": {
+        "njoguamos/laravel-cashapp": "dev-master"
+    }
+}
 ```
 
 You can publish and run the migrations with:
@@ -43,11 +48,61 @@ php artisan vendor:publish --tag="laravel-cashapp-views"
 
 ## Usage
 
+### 1 Network API
+
+#### 1.1 Brands
+
+##### 1.1.1 List Brands
+
+Get a list of brands matching the given query parameters.
+
 ```php
-$cashApp = new NjoguAmos\CashApp();
-echo $cashApp->echoPhrase('Hello, Njogu Amos!');
+use NjoguAmos\CashApp\CashApp;
+
+# Defaults
+$brands = CashApp::listBrands();
+
+# With params
+$brands = CashApp::listBrands(limit: 20);
+```
+
+<details>
+<summary>Success Response</summary>
+
+```json
+{
+  "brands": [
+    {
+      "id": "string",
+      "name": "string",
+      "created_at": "2021-01-01T00:00:00Z",
+      "updated_at": "2021-01-01T00:00:00Z",
+      "reference_id": "example-id",
+      "color": "#ffffff",
+      "profile_image_url": "https://franklin-assets.s3.amazonaws.com/merchants/assets/v3/generic/m_category_business.png",
+      "metadata": {
+        "my-meta": "meta-value"
+      }
+    }
+  ],
+  "cursor": "string"
+}
 ```
 
+</details>
+
+<details>
+<summary>Query Parameters</summary>
+
+| params       | type                                              | required | deafult | description                                                                                                                                       |
+|--------------|---------------------------------------------------|----------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------|
+| cursor       | `string` >= 1 characters                          | false    | null    | A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. |
+| limit        | `integer` >=1 and <= 100                          | false    | 50      | Maximum number of brands to return.                                                                                                               |
+| reference_id | `string`   >= 1 characters and <= 1024 characters | false    | null    | Filters results to only include brands with a `reference_id` matching the given value.                                                            |
+
+</details>
+
+
 ## Testing
 
 ```bash
@@ -56,7 +111,7 @@ composer test
 
 ## Changelog
 
-Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
+Please see [releases](https://github.com/njoguamos/laravel-cashapp/releases) for more information on what has changed recently.
 
 ## Contributing
 

composer.json

@@ -18,8 +18,8 @@
     "require": {
         "php": "^8.1 | ^8.2 | ^8.3",
         "illuminate/contracts": "^10.0",
-        "saloonphp/saloon": "^3.0",
-        "spatie/laravel-package-tools": "^1.14.0"
+        "saloonphp/saloon": "^v3.6.0",
+        "spatie/laravel-package-tools": "^1.16.0"
     },
     "require-dev": {
         "laravel/pint": "^1.0",

config/cashapp.php

@@ -14,7 +14,7 @@
     |
     */
 
-    'production' => env(key: 'CASH_PRODUCTION', default: false),
+    'production' => env(key: 'CASHAPP_PRODUCTION', default: false),
 
     /*
      |--------------------------------------------------------------------------
@@ -29,7 +29,7 @@
      */
 
     'urls' => [
-        'sandbox'    => env(key: 'CASH_APP_SANDBOX_URL', default: 'https://sandbox.api.cash.app'),
-        'production' => env(key: 'CASH_APP_PRODUCTION_URL', default: 'https://api.cash.app'),
+        'sandbox'    => env(key: 'CASHAPP_SANDBOX_URL', default: 'https://sandbox.api.cash.app'),
+        'production' => env(key: 'CASHAPP_PRODUCTION_URL', default: 'https://api.cash.app'),
     ]
 ];

src/CashApp.php

@@ -2,6 +2,33 @@
 
 namespace NjoguAmos\CashApp;
 
+use NjoguAmos\CashApp\Connectors\CashAppConnector;
+use NjoguAmos\CashApp\Requests\Network\Brands\ListBrandsRequest;
+use Saloon\Exceptions\Request\FatalRequestException;
+use Saloon\Exceptions\Request\RequestException;
+
 class CashApp
 {
+    /**
+     * @throws FatalRequestException
+     * @throws RequestException
+     */
+    public static function listBrands(string $cursor = null, int $limit = 50, $reference_id = null): string
+    {
+        $connector = new CashAppConnector();
+
+        $request = new ListBrandsRequest();
+
+        if ($cursor) {
+            $request->query()->add('cursor', $cursor);
+        }
+
+        if ($reference_id) {
+            $request->query()->add('reference_id', $reference_id);
+        }
+
+        $request->query()->add('limit', $limit);
+
+        return $connector->send($request)->body();
+    }
 }

src/Connectors/CashAppBaseConnector.php → src/Connectors/CashAppConnector.php

@@ -4,7 +4,7 @@
 
 use Saloon\Http\Connector;
 
-class CashAppBaseConnector extends Connector
+class CashAppConnector extends Connector
 {
     public function resolveBaseUrl(): string
     {
@@ -14,4 +14,13 @@ public function resolveBaseUrl(): string
 
         return  config(key: 'cashapp.urls.sandbox');
     }
+
+    protected function defaultHeaders(): array
+    {
+        return [
+            'Accept'      => 'application/json',
+            'X-Region'    => '@TODO',
+            'X-Signature' => '@TODO',
+        ];
+    }
 }

src/Requests/Network/Brands/ListBrandsRequest.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace NjoguAmos\CashApp\Requests\Network\Brands;
+
+use Saloon\Enums\Method;
+use Saloon\Http\Request;
+
+class ListBrandsRequest extends Request
+{
+    protected Method $method = Method::GET;
+
+    public function resolveEndpoint(): string
+    {
+        return '/networks/brands';
+    }
+}

tests/Feature/CashAppTest.php

@@ -0,0 +1,18 @@
+<?php
+
+use NjoguAmos\CashApp\CashApp;
+use NjoguAmos\CashApp\Requests\Network\Brands\ListBrandsRequest;
+
+it(description: 'can successfully get brands from cash app API', closure: function () {
+    $mockClient = mockRequest(
+        request: ListBrandsRequest::class,
+        jsonFile: 'network/list-brands.json'
+    );
+
+    /** @noinspection PhpUnhandledExceptionInspection */
+    $brands = CashApp::listBrands();
+
+    $mockClient->assertSent(value: ListBrandsRequest::class);
+
+    $mockClient->assertSentCount(count: 1);
+});

tests/Pest.php

@@ -1,5 +1,23 @@
 <?php
 
 use NjoguAmos\CashApp\Tests\TestCase;
+use Saloon\Http\Faking\MockClient;
+use Saloon\Http\Faking\MockResponse;
+use Illuminate\Support\Facades\File;
+use Saloon\Config;
 
-uses(TestCase::class)->in(__DIR__);
+Config::preventStrayRequests();
+
+uses(TestCase::class)
+    ->in(__DIR__);
+
+function mockRequest(string $request, string $jsonFile, int $status = 200, array $headers = []): MockClient
+{
+    return MockClient::global([
+        $request => MockResponse::make(
+            body: File::json('tests/fixtures/'.$jsonFile),
+            status: $status,
+            headers: $headers
+        ),
+    ]);
+}

tests/TestCase.php

@@ -5,13 +5,16 @@
 use Illuminate\Database\Eloquent\Factories\Factory;
 use Orchestra\Testbench\TestCase as Orchestra;
 use NjoguAmos\CashApp\CashAppServiceProvider;
+use Saloon\MockConfig;
 
 class TestCase extends Orchestra
 {
     protected function setUp(): void
     {
         parent::setUp();
 
+        MockConfig::setFixturePath('fixtures');
+
         Factory::guessFactoryNamesUsing(
             fn (string $modelName) => 'Njogu Amos\\CashApp\\Database\\Factories\\'.class_basename($modelName).'Factory'
         );

tests/Unit/Connectors/CashAppBaseConnectorTest.php

@@ -2,15 +2,15 @@
 
 namespace Njoguamos\CashApp\Tests;
 
-use NjoguAmos\CashApp\Connectors\CashAppBaseConnector;
+use NjoguAmos\CashApp\Connectors\CashAppConnector;
 
 it(description: 'resolves to the correct base url', closure: function (bool $isProduction, string $baseUrl) {
     config()->set(
         key: 'cashapp.production',
         value: $isProduction
     );
 
-    $connector = new CashAppBaseConnector();
+    $connector = new CashAppConnector();
 
     expect(value: $connector->resolveBaseUrl())
         ->toBe(expected: $baseUrl);

tests/fixtures/network/list-brands.json

@@ -0,0 +1,17 @@
+{
+  "brands": [
+    {
+      "id": "string",
+      "name": "string",
+      "created_at": "2021-01-01T00:00:00Z",
+      "updated_at": "2021-01-01T00:00:00Z",
+      "reference_id": "example-id",
+      "color": "#ffffff",
+      "profile_image_url": "https://franklin-assets.s3.amazonaws.com/merchants/assets/v3/generic/m_category_business.png",
+      "metadata": {
+        "my-meta": "meta-value"
+      }
+    }
+  ],
+  "cursor": "string"
+}