1	<?php
2	/**
3	* Functions implemented by API class, which will be used by {@see Background_Jobs_Actions_Handler} class
4	*
5	* @package brianhenryie/bh-wp-bitcoin-gateway
6	*/
7
8	namespace BrianHenryIE\WP_Bitcoin_Gateway\Action_Scheduler;
9
10	use BrianHenryIE\WP_Bitcoin_Gateway\API\Model\Results\Update_Exchange_Rate_Result;
11	use BrianHenryIE\WP_Bitcoin_Gateway\API\Model\Wallet\Bitcoin_Wallet;
12	use BrianHenryIE\WP_Bitcoin_Gateway\API\Model\Exceptions\Rate_Limit_Exception;
13	use BrianHenryIE\WP_Bitcoin_Gateway\API\Model\Results\Addresses_Generation_Result;
14	use BrianHenryIE\WP_Bitcoin_Gateway\API\Model\Results\Check_Assigned_Addresses_For_Transactions_Result;
15	use BrianHenryIE\WP_Bitcoin_Gateway\API\Model\Results\Ensure_Unused_Addresses_Result;
16
17	interface API_Background_Jobs_Interface {
18
19	/**
20	* Do the maths to generate new addresses for a wallet.
21	*
22	* @return Addresses_Generation_Result[]
23	*/
24	public function generate_new_addresses(): array;
25
26	/**
27	* Make sure newly generated addresses have no existing transactions, so we only use unused addresses for orders.
28	*
29	* This is different from {@see self::check_assigned_addresses_for_payment} in that the post status will go from
30	* new to used rather than from assigned to completed.
31	*
32	* @throws Rate_Limit_Exception When the remote API refuses too many requests.
33	*/
34	public function check_new_addresses_for_transactions(): Check_Assigned_Addresses_For_Transactions_Result;
35
36	/**
37	* Check the list of assigned addresses for new transactions and mark them as complete as appropriate, which
38	* will also mark related orders as paid.
39	*
40	* @throws Rate_Limit_Exception When the remote API refuses too many requests.
41	*/
42	public function check_assigned_addresses_for_payment(): Check_Assigned_Addresses_For_Transactions_Result;
43
44	/**
45	* Make sure each wallet has payment addresses generated and that they have no previous transactions.
46	*
47	* This is used hourly to check the next prepared addresses have also not been sent transactions (used) for any
48	* reason outside WordPress.
49	*
50	* @see Background_Jobs_Actions_Handler::ensure_unused_addresses()
51	* @see Background_Jobs_Scheduler::schedule_recurring_ensure_unused_addresses()
52	*
53	* TODO: change the return type to an object that communicates did we run into rate limiting or other handled exceptions.
54	*
55	* @param int $required_count How many unused addresses to make available.
56	*
57	* @return array<string, Ensure_Unused_Addresses_Result> array<wallet_xpub: Ensure_Unused_Addresses_Result>
58	*/
59	public function ensure_unused_addresses( int $required_count = 2 ): array;
60
61	/**
62	* Fetch the wallet's unused addresses from the db, check they still have no transactions, if they do, mark those
63	* as used and generate new addresses until we find one without transactions.
64	*
65	* @param Bitcoin_Wallet $wallet  The wallet to check / find unused addresses for.
66	* @param int            $required_count The number of available addresses we should have.
67	*/
68	public function ensure_unused_addresses_for_wallet_synchronously( Bitcoin_Wallet $wallet, int $required_count = 2 ): Ensure_Unused_Addresses_Result;
69
70	/**
71	* Update the exchange rate for the WooCommerce store currency.
72	*
73	* Fetches and caches the current BTC exchange rate.
74	*/
75	public function update_exchange_rate(): Update_Exchange_Rate_Result;
76	}