1:   2:   3:   4:   5:   6:   7:   8:   9:  10:  11:  12:  13:  14:  15:  16:  17:  18:  19:  20:  21:  22:  23:  24:  25:  26:  27:  28:  29:  30:  31:  32:  33:  34:  35:  36:  37:  38:  39:  40:  41:  42:  43:  44:  45:  46:  47:  48:  49:  50:  51:  52:  53:  54:  55:  56:  57:  58:  59:  60:  61:  62:  63:  64:  65:  66:  67:  68:  69:  70:  71:  72:  73:  74:  75:  76:  77:  78:  79:  80:  81:  82:  83:  84:  85:  86:  87:  88:  89:  90:  91:  92:  93:  94:  95:  96:  97:  98:  99: 100: 101: 102: 103: 104: 105: 106: 107: 108: 109: 110: 111: 112: 113: 114: 115: 116: 117: 118: 119: 120: 121: 122: 123: 124: 125: 126: 127: 128: 129: 130: 131: 132: 133: 134: 135: 136: 137: 138: 139: 140: 141: 142: 143: 144: 145: 146: 147: 148: 149: 150: 151: 152: 153: 154: 155: 156: 157: 158: 159: 160: 161: 162: 163: 164: 165: 166: 167: 168: 169: 170: 171: 172: 173: 174: 175: 176: 177: 178: 179: 180: 181: 182: 183: 184: 185: 186: 187: 188: 189: 190: 191: 192: 193: 194: 195: 196: 197: 198: 199: 200: 201: 202: 203: 204: 205: 206: 207: 208: 209: 210: 211: 212: 213: 214: 215: 216: 217: 218: 219: 220: 221: 222: 223: 224: 225: 226: 227: 228: 229: 230: 231: 232: 233: 234: 235: 236: 237: 238: 239: 240: 241: 242: 243: 244: 245: 246: 247: 248: 249: 250: 251: 252: 253: 254: 255: 256: 257: 258: 259: 260: 261: 262: 263: 264: 265: 266: 267: 268: 269: 270: 271: 272: 273: 274: 275: 276: 277: 278: 279: 280: 281: 282: 283: 284: 285: 286: 287: 288: 289: 290: 291: 292: 293: 294: 295: 296: 297: 298: 299: 300: 301: 302: 303: 304: 305: 306: 307: 308: 309: 310: 311: 312: 313: 314: 315: 316: 317: 318: 319: 320: 321: 322: 323: 324: 325: 326: 327: 328: 329: 330: 331: 332: 333: 334: 335: 336: 337: 338: 339: 340: 341: 342: 343: 344: 345: 346: 347: 348: 349: 350: 351: 352: 353: 354: 355: 356: 357: 358: 359: 360: 361: 362: 363: 364: 365: 366: 367: 368: 369: 370: 371: 372: 373: 374: 375: 376: 377: 378: 379: 380: 381: 382: 383: 384: 385: 386: 387: 388: 389: 390: 391: 392: 393: 394: 395: 396: 397: 398: 399: 400: 401: 402: 403: 404: 405: 406: 407: 408: 409: 410: 411: 412: 413: 414: 415: 416: 417: 418: 

<?php

namespace MaxMind;

use MaxMind\Exception\AuthenticationException;
use MaxMind\Exception\HttpException;
use MaxMind\Exception\InsufficientFundsException;
use MaxMind\Exception\InvalidInputException;
use MaxMind\Exception\InvalidRequestException;
use MaxMind\Exception\WebServiceException;
use MaxMind\MinFraud\Validation;
use MaxMind\WebService\Client;
use Respect\Validation\Exceptions\ValidationException;

/**
 * Class MinFraud
 * @package MaxMind
 *
 * This class provides a client API for accessing MaxMind minFraud Score
 * and Insights.
 *
 * ## Usage ##
 *
 * The constructor takes your MaxMind user ID and license key. The object
 * returned is immutable. To build up a request, call the `->with*()` methods.
 * Each of these returns a new object (a clone of the original) with the
 * additional data. These can be chained together:
 *
 * ```
 * $client = new MinFraud(6, 'LICENSE_KEY');
 *
 * $score = $client->withDevice(['ip_address' => '1.1.1.1',
 *                               'accept_language' => 'en-US'])
 *                 ->withEmail(['domain' => 'maxmind.com'])
 *                 ->score();
 * ```
 *
 * If the request fails, an exception is thrown.
 */
class MinFraud
{
    const VERSION = 'v0.5.0';

    private $client;
    private static $host = 'minfraud.maxmind.com';

    private static $basePath = '/minfraud/v2.0/';
    private $content;
    private $locales;
    private $validateInput = true;

    /**
     * @param int $userId Your MaxMind user ID
     * @param string $licenseKey Your MaxMind license key
     * @param array $options An array of options. Possible keys:
     *
     * * `host` - The host to use when connecting to the web service.
     * * `userAgent` - The prefix for the User-Agent header to use in the
     *   request.
     * * `caBundle` - The bundle of CA root certificates to use in the request.
     * * `connectTimeout` - The connect timeout to use for the request.
     * * `timeout` - The timeout to use for the request.
     * * `locales` - An array of locale codes to use for the location name
     *   properties.
     * * `validateInput` - Default is `true`. Determines whether values passed
     *   to the `with*()` methods are validated. It is recommended that you
     *   leave validation on while developing and only (optionally) disable it
     *   before deployment.
     */
    public function __construct(
        $userId,
        $licenseKey,
        $options = []
    ) {
        if (isset($options['locales'])) {
            $this->locales = $options['locales'];
        } else {
            $this->locales = ['en'];
        }

        if (isset($options['validateInput'])) {
            $this->validateInput = $options['validateInput'];
        }

        if (!isset($options['host'])) {
            $options['host'] = self::$host;
        }
        $options['userAgent'] = $this->userAgent();
        $this->client = new Client($userId, $licenseKey, $options);
    }

    /**
     * This returns a `MinFraud` object with the array to be sent to the web
     * service set to `$values`. Existing values will be replaced.
     * @link http://dev.maxmind.com/minfraud-score-and-insights-api-documentation/ minFraud API docs
     *
     * @param $values
     * @return MinFraud
     */
    public function with($values)
    {
        $values = $this->cleanAndValidate('Transaction', $values);

        $new = clone $this;
        $new->content = $values;

        return $new;
    }

    /**
     * This returns a `MinFraud` object with the `device` array set to
     * `$values`. Existing `device` data will be replaced.
     * @link http://dev.maxmind.com/minfraud-score-and-insights-api-documentation/#Device_device
     *     minFraud device API docs
     *
     * @param $values
     * @return MinFraud
     */
    public function withDevice($values)
    {
        return $this->validateAndAdd('Device', 'device', $values);
    }

    /**
     * This returns a `MinFraud` object with the `events` array set to
     * `$values`. Existing `event` data will be replaced.
     * @link http://dev.maxmind.com/minfraud-score-and-insights-api-documentation/#Event_event
     *     minFraud event API docs
     *
     * @param $values
     * @return MinFraud
     */
    public function withEvent($values)
    {
        return $this->validateAndAdd('Event', 'event', $values);
    }

    /**
     * This returns a `MinFraud` object with the `account` array set to
     * `$values`. Existing `account` data will be replaced.
     * @link http://dev.maxmind.com/minfraud-score-and-insights-api-documentation/#Account_account
     *     minFraud account API docs
     *
     * @param $values
     * @return MinFraud
     */
    public function withAccount($values)
    {
        return $this->validateAndAdd('Account', 'account', $values);
    }

    /**
     * This returns a `MinFraud` object with the `email` array set to
     * `$values`. Existing `email` data will be replaced.
     * @link http://dev.maxmind.com/minfraud-score-and-insights-api-documentation/#Email_email
     *     minFraud email API docs
     *
     * @param $values
     * @return MinFraud
     */
    public function withEmail($values)
    {
        return $this->validateAndAdd('Email', 'email', $values);
    }

    /**
     * This returns a `MinFraud` object with the `billing` array set to
     * `$values`. Existing `billing` data will be replaced.
     * @link http://dev.maxmind.com/minfraud-score-and-insights-api-documentation/#Billing_billing
     *     minFraud billing API docs
     *
     * @param $values
     * @return MinFraud
     */
    public function withBilling($values)
    {
        return $this->validateAndAdd('Billing', 'billing', $values);
    }

    /**
     * This returns a `MinFraud` object with the `shipping` array set to
     * `$values`. Existing `shipping` data will be replaced.
     * @link http://dev.maxmind.com/minfraud-score-and-insights-api-documentation/#Shipping_shipping
     *     minFraud shipping API docs
     *
     * @param $values
     * @return MinFraud
     */
    public function withShipping($values)
    {
        return $this->validateAndAdd('Shipping', 'shipping', $values);
    }

    /**
     * This returns a `MinFraud` object with the `payment` array set to
     * `$values`. Existing `payment` data will be replaced.
     * @link http://dev.maxmind.com/minfraud-score-and-insights-api-documentation/#Payment_payment
     *     minFraud payment API docs
     *
     * @param $values
     * @return MinFraud
     */
    public function withPayment($values)
    {
        return $this->validateAndAdd('Payment', 'payment', $values);
    }

    /**
     * This returns a `MinFraud` object with the `credit_card` array set to
     * `$values`. Existing `credit_card` data will be replaced.
     * @link http://dev.maxmind.com/minfraud-score-and-insights-api-documentation/#Credit_Card_credit_card
     *     minFraud credit_card API docs
     *
     * @param $values
     * @return MinFraud
     */
    public function withCreditCard($values)
    {
        return $this->validateAndAdd('CreditCard', 'credit_card', $values);
    }

    /**
     * This returns a `MinFraud` object with the `order` array set to
     * `$values`. Existing `order` data will be replaced.
     * @link http://dev.maxmind.com/minfraud-score-and-insights-api-documentation/#Order_order
     *     minFraud order API docs
     *
     * @param $values
     * @return MinFraud
     */
    public function withOrder($values)
    {
        return $this->validateAndAdd('Order', 'order', $values);
    }

    /**
     * This returns a `MinFraud` object with `$values` added to the shopping
     * cart array.
     * @link http://dev.maxmind.com/minfraud-score-and-insights-api-documentation/#Shopping_Cart_Item
     *     minFraud shopping cart item API docs
     *
     * @param $values
     * @return MinFraud
     */
    public function withShoppingCartItem($values)
    {
        $values = $this->cleanAndValidate('ShoppingCartItem', $values);

        $new = clone $this;
        if (!isset($new->content['shopping_cart'])) {
            $new->content['shopping_cart'] = [];
        }
        array_push($new->content['shopping_cart'], $values);

        return $new;
    }

    /**
     * This method performs a minFraud Score lookup using the request data in
     * the current object and returns a model object for minFraud Score.
     *
     * @return MinFraud\Model\Score minFraud Score model object.
     * @throws InvalidInputException when the request has missing or invalid
     * data.
     * @throws AuthenticationException when there is an issue authenticating
     * the request.
     * @throws InsufficientFundsException when your account is out of funds.
     * @throws InvalidRequestException when the request is invalid for some
     * other reason, e.g., invalid JSON in the POST.
     * @throws HttpException when an unexpected HTTP error occurs.
     * @throws WebServiceException when some other error occurs. This also
     * serves as the base class for the above exceptions.
     */
    public function score()
    {
        return $this->post('Score');
    }

    /**
     * This method performs a minFraud Insights lookup using the request data
     * in the current object and returns a model object for minFraud Insights.
     *
     * @return MinFraud\Model\Insights minFraud Insights model object.
     * @throws InvalidInputException when the request has missing or invalid
     * data.
     * @throws AuthenticationException when there is an issue authenticating
     * the request.
     * @throws InsufficientFundsException when your account is out of funds.
     * @throws InvalidRequestException when the request is invalid for some
     * other reason, e.g., invalid JSON in the POST.
     * @throws HttpException when an unexpected HTTP error occurs.
     * @throws WebServiceException when some other error occurs. This also
     * serves as the base class for the above exceptions.
     */
    public function insights()
    {
        return $this->post('Insights');
    }

    /**
     * This method performs a minFraud Factors lookup using the request data
     * in the current object and returns a model object for minFraud Factors.
     *
     * @return MinFraud\Model\Factors minFraud Factors model object.
     * @throws InvalidInputException when the request has missing or invalid
     * data.
     * @throws AuthenticationException when there is an issue authenticating
     * the request.
     * @throws InsufficientFundsException when your account is out of funds.
     * @throws InvalidRequestException when the request is invalid for some
     * other reason, e.g., invalid JSON in the POST.
     * @throws HttpException when an unexpected HTTP error occurs.
     * @throws WebServiceException when some other error occurs. This also
     * serves as the base class for the above exceptions.
     */
    public function factors()
    {
        return $this->post('Factors');
    }

    /**
     * @param $service $service The name of the service to use.
     * @return mixed The model class for the service.
     * @throws InvalidInputException when the request has missing or invalid
     * data.
     * @throws AuthenticationException when there is an issue authenticating the
     * request.
     * @throws InsufficientFundsException when your account is out of funds.
     * @throws InvalidRequestException when the request is invalid for some
     * other reason, e.g., invalid JSON in the POST.
     * @throws HttpException when an unexpected HTTP error occurs.
     * @throws WebServiceException when some other error occurs. This also
     * serves as the base class for the above exceptions.
     */
    private function post($service)
    {
        if (!isset($this->content['device']['ip_address'])) {
            throw new InvalidInputException(
                'Key ip_address must be present in device'
            );
        }
        $url = self::$basePath . strtolower($service);
        $class = "MaxMind\\MinFraud\\Model\\" . $service;

        return new $class(
            $this->client->post($service, $url, $this->content),
            $this->locales
        );
    }

    /**
     * @return string The prefix for the User-Agent header.
     */
    private function userAgent()
    {
        return 'minFraud-API/' . MinFraud::VERSION;
    }

    /**
     * @param string $className The name of the class (but not the namespace)
     * @param string $key The key in the transaction array to set
     * @param array $values The values to validate
     * @return MinFraud
     * @throws InvalidInputException when $values does not validate
     */
    private function validateAndAdd($className, $key, $values)
    {
        $values = $this->cleanAndValidate($className, $values);
        $new = clone $this;
        $new->content[$key] = $values;

        return $new;
    }


    /**
     * @param string $className The name of the class (but not the namespace)
     * @param array $values The values to validate
     * @return array The cleaned values
     * @throws InvalidInputException when $values does not validate
     */
    private function cleanAndValidate($className, $values)
    {
        $values = $this->clean($values);

        if (!$this->validateInput) {
            return $values;
        }

        $class = '\\MaxMind\\MinFraud\\Validation\\Rules\\' . $className;
        $validator = new $class();
        try {
            $validator->check($values);
        } catch (ValidationException $exception) {
            throw new InvalidInputException(
                $exception->getMessage(),
                $exception->getCode()
            );
        }

        return $values;
    }

    private function clean($array)
    {
        $cleaned = [];
        foreach ($array as $key => $value) {
            if (is_array($value)) {
                $cleaned[$key] = $this->clean($array[$key]);
            } elseif ($array[$key] !== null) {
                $cleaned[$key] = $array[$key];
            }
        }

        return $cleaned;
    }
}