Make error handling consistent with general Authsignal SDK conventions

Author: stevenclouston

README.md

@@ -53,6 +53,21 @@ Authsignal's server side signal API has five main calls `track`, `getAction`, `g
 
 For more details on these api calls, refer to our [official PHP SDK docs](https://docs.authsignal.com/sdks/server/php#trackaction).
 
+### Response & Error handling
+
+Example:
+
+```php
+$result = Authsignal::updateAction(
+   userId: $userId,
+   action: $action,
+   idempotencyKey: "invalidKey",
+   attributes: ['state' => 'CHALLENGE_FAILED']
+);
+
+# PHP Fatal error: Uncaught AuthsignalNotFoundError: 404 - not_found
+```
+
 ## License
 
 The library is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

lib/Authsignal/AuthsignalClient.php

@@ -13,35 +13,39 @@ public static function apiUrl($path='')
     return $apiEndpoint.$path;
   }
 
-  public function handleApiError($response, $status)
+  public function handleApiError($response, $statusCode)
   {
-    $type = $response['error'] ?? null;
-    $msg  = $response['errorDescription'] ?? null;
-    switch ($status) {
+    $errorCode = $response['errorCode'] ?? null;
+    $errorDescription  = $response['errorDescription'] ?? null;
+    switch ($statusCode) {
       case 400:
-        throw new AuthsignalBadRequest($msg, $type, $status);
+        throw new AuthsignalBadRequest($statusCode, $errorCode, $errorDescription);
       case 401:
-        throw new AuthsignalUnauthorizedError($msg, $type, $status);
+        throw new AuthsignalUnauthorizedError($statusCode, $errorCode, $errorDescription);
       case 403:
-        throw new AuthsignalForbiddenError($msg, $type, $status);
+        throw new AuthsignalForbiddenError($statusCode, $errorCode, $errorDescription);
       case 404:
-        throw new AuthsignalNotFoundError($msg, $type, $status);
+        throw new AuthsignalNotFoundError($statusCode, $errorCode, $errorDescription);
       case 422:
         // Handle subtype errors
-        switch($type) {
+        switch($errorCode) {
           case 'invalid_request_token':
-            throw new AuthsignalInvalidRequestTokenError($msg, $type, $status);
+            throw new AuthsignalInvalidRequestTokenError($statusCode, $errorCode, $errorDescription);
           default:
-            throw new AuthsignalInvalidParametersError($msg, $type, $status);
+            throw new AuthsignalInvalidParametersError($statusCode, $errorCode, $errorDescription);
         }
       default:
-        throw new AuthsignalApiError($msg, $type, $status);
+        throw new AuthsignalApiError($statusCode, $errorCode, $errorDescription);
     }
   }
 
   public function handleRequestError($request)
   {
-    throw new AuthsignalRequestError("$request->rError: $request->rMessage");
+      $statusCode = $request->rStatus; // HTTP statusCode code
+      $errorCode = $request->rError; // Error code
+      $errorDescription = $request->rMessage; // Error message
+    
+      throw new AuthsignalRequestError($statusCode, $errorCode, $errorDescription);
   }
 
   public function handleResponse($request)

lib/Authsignal/Errors.php

@@ -2,7 +2,21 @@
 
 class AuthsignalError extends Exception
 {
-
+    public function __construct($statusCode, $errorCode, $errorDescription = null, $previous = null)
+    {
+        $message = $this->formatMessage($statusCode, $errorCode, $errorDescription);
+        parent::__construct($message, $statusCode, $previous);
+    }
+
+    private function formatMessage($statusCode, $errorCode, $errorDescription = null)
+    {
+        return "$statusCode - " . $this->formatDescription($errorCode, $errorDescription);
+    }
+
+    private function formatDescription($errorCode, $errorDescription = null)
+    {
+        return $errorDescription && strlen($errorDescription) > 0 ? $errorDescription : $errorCode;
+    }
 }
 
 class AuthsignalRequestError extends AuthsignalError
@@ -22,12 +36,7 @@ class AuthsignalCurlOptionError extends AuthsignalError
 
 class AuthsignalApiError extends AuthsignalError
 {
-  public function __construct($msg, $type = null, $status = null)
-  {
-    parent::__construct($msg);
-    $this->type = $type;
-    $this->httpStatus = $status;
-  }
+
 }
 
 class AuthsignalBadRequest extends AuthsignalApiError