Merge pull request #38 from alexstewartja/v5

v5 Upgrade
vrajroham · Dec 9, 2021 · 92dc0fa · 92dc0fa
2 parents b156762 + 651416e
commit 92dc0fa
Show file tree

Hide file tree

Showing 32 changed files with 1,832 additions and 488 deletions.
diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml
@@ -1,4 +1,5 @@
 # These are supported funding model platforms
 
-github: vrajroham
+github: [vrajroham, alexstewartja]
 patreon: vrajroham
+custom: ["https://www.buymeacoffee.com/asja", "https://bit.ly/asja_paypal_lara_bitpay"]
diff --git a/MIGRATION.md b/MIGRATION.md
@@ -0,0 +1,48 @@
+# LaravelBitPay Migration Guide
+
+This guide will serve as a single source of truth, regarding breaking changes and necessary actions one must take when
+upgrading to major versions.
+
+## From v4 to v5
+
+### Configuration
+
+- Ensure `BITPAY_*` values inside your `.env` follows the updated naming conventions outlined
+  here: https://github.com/vrajroham/laravel-bitpay#add-configuration-values. Specifically:
+    + Removed:
+        - `BITPAY_PUBLIC_KEY_PATH`
+    + Changed:
+        - `BITPAY_TOKEN` renamed to `BITPAY_MERCHANT_TOKEN`
+    + Added:
+        - `BITPAY_ENABLE_MERCHANT`
+        - `BITPAY_ENABLE_PAYOUT`
+        - `BITPAY_PAYOUT_TOKEN`
+
+
+- Ensure the contents of your `laravel-bitpay.php` config file is on par with the updated one found
+  here: https://github.com/vrajroham/laravel-bitpay/blob/master/config/laravel-bitpay.php
+
+### API Tokens
+
+LaravelBitPay now supports the `payout` facade, along with generating a Payout API Token, which allows you to interact
+with [Recipients](https://bitpay.com/api/#rest-api-resources-recipients)
+and [Payouts](https://bitpay.com/api/#rest-api-resources-payouts) resources.
+
+It's as easy as setting `BITPAY_ENABLE_PAYOUT` to `true` inside your `.env` file then
+following: https://github.com/vrajroham/laravel-bitpay#generate-key-pair-and-api-tokens.
+
+### Webhooks
+
+Webhooks are now an optional feature. Your event listener should work the same, but to configure your webhook URL
+(notificationURL) please refer here: https://github.com/vrajroham/laravel-bitpay#configure-webhooks-optional.
+
+### Constants
+
++ Removed:
+  - `BitPayConstants::BILL_STATUS_*` in favor of core `BillStatus::*`
+  - `BitPayConstants::SUBSCRIPTION_STATUS_*` in favor of core `SubscriptionStatus::*`
++ Added:
+  - `BitPayConstants::INVOICE_EXCEPTION_*`
+  - `BitPayConstants::INVOICE_WEBHOOK_CODES`
+  - `BitPayConstants::RECIPIENT_WEBHOOK_CODES`
+  - `BitPayConstants::PAYOUT_WEBHOOK_CODES`
diff --git a/README.md b/README.md
diff --git a/composer.json b/composer.json
@@ -24,7 +24,8 @@
     ],
     "require": {
         "php": ">=7.3 || ^8.0",
-        "bitpay/sdk": "~v5.2"
+        "ext-json": "*",
+        "bitpay/sdk": "~6.0.2"
     },
     "require-dev": {
         "phpunit/phpunit": ">=9.5"

diff --git a/config/laravel-bitpay.php b/config/laravel-bitpay.php
@@ -3,38 +3,72 @@
 return [
     /*
      * This is the full path and name for the private key.
-     * The default value is /tmp/laravel-bitpay.pri
+     * The default value is /tmp/laravel-bitpay.pk
      */
-    'private_key'          => env('BITPAY_PRIVATE_KEY_PATH', '/tmp/laravel-bitpay.pri'),
-
-    /*
-     * This is the full path and name for the public key.
-     * The default value is /tmp/laravel-bitpay.pub
-     */
-    'public_key'           => env('BITPAY_PUBLIC_KEY_PATH', '/tmp/laravel-bitpay.pub'),
+    'private_key'             => env('BITPAY_PRIVATE_KEY_PATH', '/tmp/laravel-bitpay.pk'),
 
     /*
      * Specifies using the Live Bitcoin network or
      * Test Bitcoin network: livenet or testnet.
      *
      * The default is livenet
      */
-    'network'              => env('BITPAY_NETWORK', 'livenet'),
+    'network'                 => env('BITPAY_NETWORK', 'livenet'),
 
     /*
      * The key_storage option allows you to specify a class for persisting and retrieving keys.
      *
      * By default this uses the Bitpay\Storage\EncryptedFilesystemStorage class.
      */
-    'key_storage'          => \BitPayKeyUtils\Storage\EncryptedFilesystemStorage::class,
+    'key_storage'             => \BitPayKeyUtils\Storage\EncryptedFilesystemStorage::class,
 
     /*
      * This is the password used to encrypt and decrypt keys on the filesystem.
      */
-    'key_storage_password' => env('BITPAY_KEY_STORAGE_PASSWORD', 'RandomPasswordForEncryption'),
+    'key_storage_password'    => env('BITPAY_KEY_STORAGE_PASSWORD', 'RandomPasswordForEncryption'),
+
+    /*
+     * Generate/Enable use of BitPay token for 'merchant' facade?
+     *
+     * Default: true
+     */
+    'merchant_facade_enabled' => env('BITPAY_ENABLE_MERCHANT', true),
+
+    /*
+     * Generate/Enable use of BitPay token for 'payout' facade?
+     *
+     * Default: false
+     */
+    'payout_facade_enabled'   => env('BITPAY_ENABLE_PAYOUT', false),
 
     /*
-     * BitPay Token
+     * BitPay Merchant Token
+     *
+     * Default: null
+     */
+    'merchant_token'                   => env('BITPAY_MERCHANT_TOKEN'),
+
+    /*
+     * BitPay Payout Token
+     *
+     * Default: null
+     */
+    'payout_token'            => env('BITPAY_PAYOUT_TOKEN'),
+
+    /*
+     * Indicates if configured webhook (notificationURL) should automatically be set on:
+     * - Invoices
+     * - Recipients
+     * - Payouts/PayoutBatches
+     *
+     * This feature is overridden when a value is manually set on a respective resource
+     * before submitting it to the BitPay API.
+     *
+     * Uncomment an entry to enable its auto-population.
      */
-    'token'                => env('BITPAY_TOKEN', ''),
+    'auto_populate_webhook' => [
+//        \Vrajroham\LaravelBitpay\Constants\WebhookAutoPopulate::For_Invoices,
+//        \Vrajroham\LaravelBitpay\Constants\WebhookAutoPopulate::For_Recipients,
+//        \Vrajroham\LaravelBitpay\Constants\WebhookAutoPopulate::For_Payouts,
+    ],
 ];
diff --git a/src/Actions/ManageBills.php b/src/Actions/ManageBills.php
@@ -2,34 +2,41 @@
 
 namespace Vrajroham\LaravelBitpay\Actions;
 
+use BitPaySDK\Exceptions\BitPayException;
 use BitPaySDK\Model\Bill\Bill;
 use BitPaySDK\Model\Bill\Item;
 
 
+/**
+ * Bills are payment requests addressed to specific buyers.
+ * Bill line items have fixed prices, typically denominated in fiat currency.
+ *
+ * @link https://bitpay.com/api/#rest-api-resources-bills-resource
+ */
 trait ManageBills
 {
     /**
-     * Bills are payment requests addressed to specific buyers.
-     * Bill line items have fixed prices, typically denominated in fiat currency.
+     * Get BitPay Bill instance.
+     *
+     * @param string|null $number   A bill number for tracking purposes.
+     * @param string|null $currency The three digit currency code used to compute the bill's crypto amount.
+     * @param string|null $email    The email address of the receiver for this bill.
+     * @param Item[]|null $items    The list of BillItems to add to this bill.
      *
-     * @link https://bitpay.com/api/#rest-api-resources-bills-resource
      * @return Bill
      */
-    public static function Bill(): Bill
+    public static function Bill(
+        string $number = null,
+        string $currency = null,
+        string $email = null,
+        array  $items = null): Bill
     {
-        return new Bill();
-    }
-
-    /**
-     * @return Item  A BitPay Bill Item
-     * @deprecated Use <code>LaravelBitpay::BillItem()</code> instead.
-     */
-    public static function Item(): Item
-    {
-        return new Item();
+        return new Bill($number, $currency, $email, $items);
     }
 
     /**
+     * Get BitPay Bill Item instance.
+     *
      * @return Item  A BitPay Bill Item
      */
     public static function BillItem(): Item
@@ -45,7 +52,7 @@ public static function BillItem(): Item
      * @param $bill Bill A Bill object with request parameters defined.
      *
      * @return Bill A BitPay generated Bill object.
-     * @throws \BitPaySDK\Exceptions\BitPayException BitPayException class
+     * @throws BitPayException BitPayException class
      */
     public static function createBill(Bill $bill): Bill
     {
@@ -60,7 +67,7 @@ public static function createBill(Bill $bill): Bill
      * @param $billId      string The id of the bill to retrieve.
      *
      * @return Bill A BitPay Bill object.
-     * @throws \BitPaySDK\Exceptions\BitPayException BitPayException class
+     * @throws BitPayException BitPayException class
      */
     public static function getBill(string $billId): Bill
     {
@@ -74,8 +81,8 @@ public static function getBill(string $billId): Bill
      *
      * @param $status string|null The status to filter the bills.
      *
-     * @return array A list of BitPay Bill objects.
-     * @throws \BitPaySDK\Exceptions\BitPayException BitPayException class
+     * @return Bill[] A list of BitPay Bill objects.
+     * @throws BitPayException BitPayException class
      */
     public static function getBills(string $status = null): array
     {
@@ -91,7 +98,7 @@ public static function getBills(string $status = null): array
      * @param $billId string The ID of the Bill to update.
      *
      * @return Bill An updated Bill object.
-     * @throws \BitPaySDK\Exceptions\BitPayException BitPayException class
+     * @throws BitPayException BitPayException class
      */
     public static function updateBill(Bill $bill, string $billId): Bill
     {
@@ -106,11 +113,11 @@ public static function updateBill(Bill $bill, string $billId): Bill
      * @param $billId      string The id of the requested bill.
      * @param $billToken   string The token of the requested bill.
      *
-     * @return string A response status returned from the API.
-     * @throws \BitPaySDK\Exceptions\BitPayException BitPayException class
+     * @return bool True if the bill has been delivered, false otherwise.
+     * @throws BitPayException BitPayException class
      */
-    public static function deliverBill(string $billId, string $billToken): string
+    public static function deliverBill(string $billId, string $billToken): bool
     {
-        return (new self())->client->deliverBill($billId, $billToken);
+        return strtolower((new self())->client->deliverBill($billId, $billToken)) === "success";
     }
 }
diff --git a/src/Actions/ManageCurrencies.php b/src/Actions/ManageCurrencies.php
@@ -2,6 +2,7 @@
 
 namespace Vrajroham\LaravelBitpay\Actions;
 
+use BitPaySDK\Exceptions\BitPayException;
 use BitPaySDK\Model\Currency;
 
 
@@ -28,7 +29,7 @@ public static function Currency(string $code = null): Currency
      *
      * @link https://bitpay.com/api/#rest-api-resources-currencies-retrieve-the-supported-currencies
      * @return array     A list of supported BitPay Currency objects.
-     * @throws \BitPaySDK\Exceptions\BitPayException BitPayException class
+     * @throws BitPayException BitPayException class
      */
     public static function getCurrencies(): array
     {

diff --git a/src/Actions/ManageExchangeRates.php b/src/Actions/ManageExchangeRates.php
@@ -2,6 +2,8 @@
 
 namespace Vrajroham\LaravelBitpay\Actions;
 
+use BitPaySDK\Exceptions\BitPayException;
+use \BitPaySDK\Model\Rate\Rate;
 use BitPaySDK\Model\Rate\Rates;
 
 
@@ -13,44 +15,43 @@ trait ManageExchangeRates
      * @link https://bitpay.com/exchange-rates
      *
      * @return Rates A Rates object populated with the BitPay exchange rate table.
-     * @throws \BitPaySDK\Exceptions\BitPayException BitPayException class
+     * @throws BitPayException BitPayException class
      */
     public static function getRates(): Rates
     {
         return (new self())->client->getRates();
     }
 
-    //    TODO: Implement the following if/when upstream gets merged: https://github.com/bitpay/php-bitpay-client-v2/pull/67
-    //    /**
-    //     * Retrieve all the rates for a given cryptocurrency
-    //     *
-    //     * @link https://bitpay.com/api/#rest-api-resources-rates-retrieve-all-the-rates-for-a-given-cryptocurrency
-    //     *
-    //     * @param string $baseCurrency The cryptocurrency for which you want to fetch the rates.
-    //     *                             Current supported values are BTC, BCH, ETH, XRP, DOGE and LTC
-    //     *
-    //     * @return Rates A Rates object populated with the currency rates for the requested baseCurrency.
-    //     * @throws \BitPaySDK\Exceptions\BitPayException BitPayException class
-    //     */
-    //    public static function getCurrencyRates(string $baseCurrency): Rates
-    //    {
-    //        return (new self())->client->getCurrencyRates($baseCurrency);
-    //    }
-    //
-    //    /**
-    //     * Retrieve the rate for a cryptocurrency / fiat pair
-    //     *
-    //     * @link https://bitpay.com/api/#rest-api-resources-rates-retrieve-the-rates-for-a-cryptocurrency-fiat-pair
-    //     *
-    //     * @param string $baseCurrency The cryptocurrency for which you want to fetch the fiat-equivalent rate.
-    //     *                             Current supported values are BTC, BCH, ETH, XRP, DOGE and LTC
-    //     * @param string $currency The fiat currency for which you want to fetch the baseCurrency rate
-    //     *
-    //     * @return \BitPaySDK\Model\Rate\Rate A Rate object populated with the currency rate for the requested baseCurrency.
-    //     * @throws \BitPaySDK\Exceptions\BitPayException BitPayException class
-    //     */
-    //    public static function getCurrencyPairRate(string $baseCurrency, string $currency): Rate
-    //    {
-    //        return (new self())->client->getCurrencyPairRate($baseCurrency, $currency);
-    //    }
+    /**
+     * Retrieve all the rates for a given cryptocurrency
+     *
+     * @link https://bitpay.com/api/#rest-api-resources-rates-retrieve-all-the-rates-for-a-given-cryptocurrency
+     *
+     * @param string $baseCurrency The cryptocurrency for which you want to fetch the rates.
+     *                             Current supported values are BTC, BCH, ETH, XRP, DOGE and LTC
+     *
+     * @return Rates A Rates object populated with the currency rates for the requested baseCurrency.
+     * @throws BitPayException BitPayException class
+     */
+    public static function getCurrencyRates(string $baseCurrency): Rates
+    {
+        return (new self())->client->getCurrencyRates($baseCurrency);
+    }
+
+    /**
+     * Retrieve the rate for a cryptocurrency / fiat pair
+     *
+     * @link https://bitpay.com/api/#rest-api-resources-rates-retrieve-the-rates-for-a-cryptocurrency-fiat-pair
+     *
+     * @param string $baseCurrency The cryptocurrency for which you want to fetch the fiat-equivalent rate.
+     *                             Current supported values are BTC, BCH, ETH, XRP, DOGE and LTC
+     * @param string $currency     The fiat currency for which you want to fetch the baseCurrency rate
+     *
+     * @return Rate A Rate object populated with the currency rate for the requested baseCurrency.
+     * @throws BitPayException BitPayException class
+     */
+    public static function getCurrencyPairRate(string $baseCurrency, string $currency): Rate
+    {
+        return (new self())->client->getCurrencyPairRate($baseCurrency, $currency);
+    }
 }