1	<?php
2	/**
3	* The core plugin settings that may preferably be set by supplying another instance conforming to this interface.
4	*
5	* @package    brianhenryie/bh-wp-bitcoin-gateway
6	*/
7
8	namespace BrianHenryIE\WP_Bitcoin_Gateway;
9
10	use BrianHenryIE\WP_Bitcoin_Gateway\API\Model\Bitcoin_Order;
11	use BrianHenryIE\WP_Bitcoin_Gateway\API\Model\Bitcoin_Order_Interface;
12	use BrianHenryIE\WP_Bitcoin_Gateway\API\Model\Transaction_Interface;
13	use Exception;
14	use BrianHenryIE\WP_Bitcoin_Gateway\Action_Scheduler\Background_Jobs;
15	use BrianHenryIE\WP_Bitcoin_Gateway\API\Addresses\Bitcoin_Address;
16	use BrianHenryIE\WP_Bitcoin_Gateway\API\Addresses\Bitcoin_Wallet;
17	use BrianHenryIE\WP_Bitcoin_Gateway\WooCommerce\Bitcoin_Gateway;
18	use WC_Order;
19
20	/**
21	* Methods in API class that are used by other classes, primarily Bitcoin_Gateway, Background_Jobs and CLI.
22	*/
23	interface API_Interface {
24
25	/**
26	* Given an order id, determine is the order's gateway an instance of this Bitcoin gateway.
27	*
28	* @see https://github.com/BrianHenryIE/bh-wc-duplicate-payment-gateways
29	*
30	* @param int $order_id A WooCommerce order id (presumably).
31	*
32	* @return bool
33	*/
34	public function is_order_has_bitcoin_gateway( int $order_id ): bool;
35
36	/**
37	* Given a gateway id as a string, determine is it an instance of this Bitcoin gateway.
38	*
39	* @see https://github.com/BrianHenryIE/bh-wc-duplicate-payment-gateways
40	*
41	* @param string $gateway_id The WC_Payment_Gateway id to be checked.
42	*
43	* @return bool
44	*/
45	public function is_bitcoin_gateway( string $gateway_id ): bool;
46
47	/**
48	* Get a list of payment gateways registered with WooCommerce which are instances of Bitcoin_Gateway.
49	*
50	* @return Bitcoin_Gateway[]
51	*/
52	public function get_bitcoin_gateways(): array;
53
54	/**
55	* Find what the value of 1 BTC is in the specified currency.
56	*
57	* @used-by Bitcoin_Gateway::process_payment()
58	*
59	* @param string $currency E.g. USD|EUR|GBP.
60	*
61	* @return string
62	*/
63	public function get_exchange_rate( string $currency ): string;
64
65	/**
66	* Get the Bitcoin value of a local currency amount.
67	*
68	* @used-by Bitcoin_Gateway::process_payment()
69	*
70	* @param string $currency From which currency.
71	* @param float  $fiat_amount The amount to convert.
72	*
73	* @return string
74	*/
75	public function convert_fiat_to_btc( string $currency, float $fiat_amount = 1.0 ): string;
76
77	/**
78	* Return an unused address for use in an order.
79	*
80	* Adds the address as metadata to the order.
81	*
82	* @param WC_Order $order The (newly placed) WooCommerce order.
83	*
84	* @return Bitcoin_Address
85	* @throws Exception When no address is available.
86	*/
87	public function get_fresh_address_for_order( WC_Order $order ): Bitcoin_Address;
88
89	/**
90	* Return the current Bitcoin details for an order, optionally refresh.
91	*
92	* @param WC_Order $wc_order   WooCommerce order object.
93	* @param bool     $refresh Query remote APIs to refresh the details, or just return cached data.
94	*
95	* @return array{btc_address:string, bitcoin_total:string, btc_total_formatted:string, btc_price_at_at_order_time:string, last_checked_time_formatted:string, btc_amount_received_formatted:string, transactions:array<string, Transaction_Interface>, btc_exchange_rate:string}
96	*/
97	public function get_order_details( WC_Order $wc_order, bool $refresh = true ): Bitcoin_Order_Interface;
98
99	/**
100	* Returns the array from `get_order_details()` with additional keys for printing in HTML/email.
101	*
102	* @param WC_Order $order The WooCommerce order.
103	* @param bool     $refresh Should an API request be made to check for new transactions, or just use existing data.
104	*
105	* @return array{btc_total_formatted:string, btc_exchange_rate_formatted:string, order_status_before_formatted:string, order_status_formatted:string, btc_amount_received_formatted:string, last_checked_time_formatted:string}
106	* @throws Exception When the order has no Bitcoin address.
107	*/
108	public function get_formatted_order_details( WC_Order $order, bool $refresh = true ): array;
109
110	/**
111	* When a new wallet address is saved in the gateway settings, generate a Wallet custom post for it, and prepare
112	* fresh addresses for use.
113	*
114	* @used-by Bitcoin_Gateway::process_admin_options()
115	*
116	* @param string  $master_public_key The wallet address to save as a wallet object cpt.
117	* @param ?string $gateway_id The Bitcoin gateway (it is presumably linked to one).
118	*
119	* @return array{wallet:Bitcoin_Wallet, wallet_post_id:int, existing_fresh_addresses:array<Bitcoin_Address>, generated_addresses:array<Bitcoin_Address>}
120	*/
121	public function generate_new_wallet( string $master_public_key, string $gateway_id = null ): array;
122
123	/**
124	* For each Bitcoin gateway, calls `generate_new_addresses_for_wallet()`.
125	*
126	* @return array<string, array{}|array{wallet_post_id:int, new_addresses: array{gateway_id:string, xpub:string, generated_addresses:array<Bitcoin_Address>, generated_addresses_count:int, generated_addresses_post_ids:array<int>, address_index:int}}>
127	*/
128	public function generate_new_addresses(): array;
129
130	/**
131	* Generate fresh addresses for a wallet.
132	*
133	* Gets the wallet object (CPT), get the last address index generated, derives the following 25 addresses for
134	* that wallet, checks the new addresses for transactions, queues a new background job to generate more if
135	* total is still below threshold.
136	*
137	* @param string $master_public_key The main wallet address (xpub/ypub/zpub).
138	* @param int    $generate_count The number of sub-addresses to derive.
139	*
140	* @return array{xpub:string, generated_addresses:array<Bitcoin_Address>, generated_addresses_count:int, generated_addresses_post_ids:array<int>, address_index:int}
141	*/
142	public function generate_new_addresses_for_wallet( string $master_public_key, int $generate_count = 25 ): array;
143
144	/**
145	* Get transactions for an address object, with number of confirmations for each, and show which are new or updated.
146	*
147	* @used-by CLI::check_transactions()
148	*
149	* @param Bitcoin_Address $address Address object for existing saved address (i.e. this doesn't work for arbitrary addresses).
150	*
151	* @return array{address:Bitcoin_Address, transactions:array<string, Transaction_Interface>, updated:bool, updates:array{new_transactions:array<string, TransactionArray>, new_confirmations:array<string, TransactionArray>}, previous_transactions:array<string, TransactionArray>|null}
152	*/
153	public function update_address_transactions( Bitcoin_Address $address ): array;
154
155	/**
156	* Determine do we have any fresh address available for this gateway.
157	* Used so the gateway is not displayed at checkout if there are no addresses ready.
158	*
159	* @used-by Bitcoin_Gateway::is_available()
160	*
161	* @param Bitcoin_Gateway $gateway The WooCommerce payment gateway which should have addresses generated.
162	*
163	* @return bool
164	*/
165	public function is_fresh_address_available_for_gateway( Bitcoin_Gateway $gateway ): bool;
166
167	/**
168	* Validate addresses have not been used before by checking for transactions.
169	*
170	* @used-by Background_Jobs::check_new_addresses_for_transactions()
171	* @used-by API::generate_new_addresses()
172	* @used-by API::generate_new_addresses_for_wallet()
173	* @used-by API::generate_new_wallet()
174	* @used-by CLI::generate_new_addresses()
175	*
176	* @param ?Bitcoin_Address[] $addresses Array of Bitcoin address objects, or omit the parameter to check generated addresses whose status is "unknown".
177	*
178	* @return array<string, array{address:Bitcoin_Address, transactions:array<string, Transaction_Interface>}>
179	*/
180	public function check_new_addresses_for_transactions(): array;
181
182	/**
183	* Check does the server have the required GMP extension installed.
184	*/
185	public function is_server_has_dependencies(): bool;
186	}