feat: better ux

README.md

@@ -5,22 +5,25 @@
 
 declare(strict_types=1);
 
+use IPay\Enum\TransactionType;
 use IPay\IPayClient;
 
 require __DIR__.'/vendor/autoload.php';
 
 $ipay = IPayClient::create();
 
 try {
-    $session = $ipay->guest()->login([
-        'userName' => 'yourUsername',
-        'accessCode' => 'yourPassword'
-    ]);
-
-    foreach ($session->historyTransactions([
-        'accountNumber' => $session->customer->accountNumber,
-        'startDate' => new \DateTimeImmutable('-5 days'),
-    ]) as $transaction) {
+    $session = $ipay->login(
+        userName: 'username',
+        accessCode: 'password',
+    );
+
+    $transactions = $session->transactions()
+        ->type(TransactionType::CREDIT)
+        ->today()
+        ->getIterator();
+
+    foreach ($transactions as $transaction) {
         echo $transaction->remark.PHP_EOL;
     }
 } catch (Throwable $e) {

src/Api/AuthenticatedApi.php

@@ -2,6 +2,7 @@
 
 namespace IPay\Api;
 
+use IPay\Builder\TransactionBuilder;
 use IPay\Entity\Account;
 use IPay\Entity\Customer;
 use IPay\Entity\Transaction;
@@ -11,6 +12,8 @@
 use Symfony\Component\VarExporter\LazyGhostTrait;
 
 /**
+ * @psalm-import-type ParametersType from TransactionBuilder
+ *
  * @extends AbstractApi<AuthenticatedSession>
  */
 final class AuthenticatedApi extends AbstractApi
@@ -63,19 +66,24 @@ private function accounts(): array
         )->toArray();
     }
 
+    public function transactions(?string $accountNumber = null): TransactionBuilder
+    {
+        return new TransactionBuilder(
+            ['accountNumber' => $accountNumber ?? $this->customer->accountNumber],
+            $this,
+        );
+    }
+
     /**
-     * @param array{
-     *      accountNumber?: string,
-     *      tranType?: 'Credit'|'Debit'|'',
-     *      startDate?: \DateTimeInterface,
-     *      endDate?: \DateTimeInterface,
-     * } $parameters
+     * @internal
+     *
+     * @param ParametersType $parameters
      *
-     * @return iterable<int, Transaction>
+     * @return \Traversable<int, Transaction>
      *
      * @throws \IPay\Exception\SessionException
      */
-    public function historyTransactions(array $parameters): iterable
+    public function historyTransactions(array $parameters): \Traversable
     {
         $datetimeNormalizer = static function (
             Options $resolver,
@@ -85,8 +93,8 @@ public function historyTransactions(array $parameters): iterable
         };
 
         $resolver = self::createOptionsResolver()
-            ->setRequired([
-                'accountNumber',
+            ->setRequired('accountNumber')
+            ->setDefined([
                 'tranType',
                 'startDate',
                 'endDate',
@@ -97,12 +105,6 @@ public function historyTransactions(array $parameters): iterable
             ->setAllowedTypes('endDate', \DateTimeInterface::class)
             ->setNormalizer('startDate', $datetimeNormalizer)
             ->setNormalizer('endDate', $datetimeNormalizer)
-            ->setDefaults([
-                'accountNumber' => $this->customer->accountNumber,
-                'tranType' => 'Credit',
-                'startDate' => new \DateTimeImmutable(),
-                'endDate' => new \DateTimeImmutable(),
-            ])
         ;
 
         $parameters = $resolver->resolve($parameters);

src/Api/UnauthenticatedApi.php

@@ -8,30 +8,15 @@
 use Nette\Utils\Random;
 
 /**
+ * @internal
+ *
  * @extends AbstractApi<UnauthenticatedSession>
  */
 final class UnauthenticatedApi extends AbstractApi
 {
-    /**
-     * @param array{
-     *      userName: string,
-     *      accessCode: string,
-     * } $credentials
-     *
-     * @throws \IPay\Exception\LoginException
-     */
-    public function login(array $credentials): AuthenticatedApi
+    public function login(string $userName, string $accessCode): AuthenticatedApi
     {
-        $resolver = self::createOptionsResolver()
-            ->setRequired([
-                'userName',
-                'accessCode',
-            ])
-            ->setAllowedTypes('userName', 'string')
-            ->setAllowedTypes('accessCode', 'string')
-        ;
-
-        $parameters = $resolver->resolve($credentials) + $this->bypassCaptcha();
+        $parameters = get_defined_vars() + $this->bypassCaptcha();
 
         /** @var array{sessionId: string, ...} */
         $result = $this->post('signIn', $parameters);

src/Builder/BodyBuilder.php

@@ -7,27 +7,29 @@
 
 /**
  * @extends \ArrayObject<string,string>
+ *
+ * @psalm-type ParametersType = string[]
  */
 final class BodyBuilder extends \ArrayObject implements \Stringable, \JsonSerializable
 {
     /**
-     * @param string[] $data
+     * @param ParametersType $array
      */
-    private function __construct(array $data)
+    private function __construct(array $array)
     {
-        parent::__construct($data);
+        parent::__construct($array);
     }
 
     /**
-     * @param string[] $data
+     * @param ParametersType $parameters
      */
-    public static function from(array $data): static
+    public static function from(array $parameters): static
     {
-        return new static($data);
+        return new static($parameters);
     }
 
     /**
-     * @param string[] $parameters
+     * @param ParametersType $parameters
      */
     public function enhance(array $parameters): static
     {

src/Builder/TransactionBuilder.php

@@ -0,0 +1,58 @@
+<?php
+
+namespace IPay\Builder;
+
+use IPay\Api\AuthenticatedApi;
+use IPay\Enum\TransactionType;
+
+/**
+ * @psalm-type ParametersType = array{
+ *      accountNumber: string,
+ *      tranType?: value-of<TransactionType>,
+ *      startDate?: \DateTimeInterface,
+ *      endDate?: \DateTimeInterface,
+ * }
+ *
+ * @implements \IteratorAggregate<int,\IPay\Entity\Transaction>
+ */
+final class TransactionBuilder implements \IteratorAggregate
+{
+    /**
+     * @param ParametersType $parameters
+     */
+    public function __construct(
+        private array $parameters,
+        private AuthenticatedApi $api,
+    ) {
+    }
+
+    public function between(
+        \DateTimeInterface $from,
+        \DateTimeInterface $to,
+    ): static {
+        $this->parameters['startDate'] = $from;
+        $this->parameters['endDate'] = $to;
+
+        return $this;
+    }
+
+    public function today(): static
+    {
+        $today = new \DateTimeImmutable();
+        $this->between($today, $today);
+
+        return $this;
+    }
+
+    public function type(TransactionType $type): static
+    {
+        $this->parameters['tranType'] = $type->value;
+
+        return $this;
+    }
+
+    public function getIterator(): \Traversable
+    {
+        return $this->api->historyTransactions($this->parameters);
+    }
+}

src/Enum/TransactionType.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace IPay\Enum;
+
+enum TransactionType: string
+{
+    case CREDIT = 'Credit';
+    case DEBIT = 'Debit';
+    case ALL = '';
+}

src/IPayClient.php

@@ -9,6 +9,7 @@
 use Http\Client\Common\PluginClient;
 use Http\Discovery\Psr17FactoryDiscovery;
 use Http\Discovery\Psr18ClientDiscovery;
+use IPay\Api\AuthenticatedApi;
 use IPay\Api\UnauthenticatedApi;
 use IPay\Http\Plugin\ExceptionThrower;
 use IPay\Session\UnauthenticatedSession;
@@ -42,8 +43,12 @@ public function getClient(): HttpMethodsClientInterface
         return $this->client;
     }
 
-    public function guest(): UnauthenticatedApi
+    /**
+     * @throws Exception\LoginException
+     */
+    public function login(string $userName, string $accessCode): AuthenticatedApi
     {
-        return new UnauthenticatedApi($this, new UnauthenticatedSession());
+        return (new UnauthenticatedApi($this, new UnauthenticatedSession()))
+            ->login($userName, $accessCode);
     }
 }