1	<?php
2	/**
3	* API interface for WooCommerce integration.
4	*
5	* @see \BrianHenryIE\WP_Bitcoin_Gateway\API\API
6	*
7	* @package brianhenryie/bh-wp-bitcoin-gateway
8	*/
9
10	namespace BrianHenryIE\WP_Bitcoin_Gateway\Integrations\WooCommerce;
11
12	use BrianHenryIE\WP_Bitcoin_Gateway\API\Model\Payments\Bitcoin_Transaction;
13	use BrianHenryIE\WP_Bitcoin_Gateway\API\Model\Payments\Transaction_Interface;
14	use BrianHenryIE\WP_Bitcoin_Gateway\API\Model\Wallet\Bitcoin_Address;
15	use BrianHenryIE\WP_Bitcoin_Gateway\API\Model\Exceptions\BH_WP_Bitcoin_Gateway_Exception;
16	use BrianHenryIE\WP_Bitcoin_Gateway\API\Services\Results\Check_Address_For_Payment_Service_Result;
17	use BrianHenryIE\WP_Bitcoin_Gateway\Brick\Math\BigNumber;
18	use BrianHenryIE\WP_Bitcoin_Gateway\Brick\Money\Money;
19	use BrianHenryIE\WP_Bitcoin_Gateway\Integrations\WooCommerce\Model\WC_Bitcoin_Order;
20	use WC_Order;
21
22	interface API_WooCommerce_Interface {
23
24	/**
25	* Given an order id, determine is the order's gateway an instance of this Bitcoin gateway.
26	*
27	* @see https://github.com/BrianHenryIE/bh-wc-duplicate-payment-gateways
28	*
29	* @param int|numeric-string $order_id A WooCommerce order id (presumably).
30	*/
31	public function is_order_has_bitcoin_gateway( int|string $order_id ): bool;
32
33	/**
34	* Given a gateway id as a string, determine is it an instance of this Bitcoin gateway.
35	*
36	* @see https://github.com/BrianHenryIE/bh-wc-duplicate-payment-gateways
37	*
38	* @param string $gateway_id The WC_Payment_Gateway id to be checked.
39	*/
40	public function is_bitcoin_gateway( string $gateway_id ): bool;
41
42	/**
43	* Get a list of payment gateways registered with WooCommerce which are instances of Bitcoin_Gateway.
44	*
45	* @return Bitcoin_Gateway[]
46	*/
47	public function get_bitcoin_gateways(): array;
48
49	/**
50	* Gets an unused payment address, adds metadata on both the order and address linking them.
51	*
52	* @param WC_Order $order The (newly placed) WooCommerce order.
53	* @param Money    $btc_total The total order amount in Bitcoin.
54	*
55	* @return Bitcoin_Address
56	* @throws BH_WP_Bitcoin_Gateway_Exception When no address is available.
57	*/
58	public function assign_unused_address_to_order( WC_Order $order, Money $btc_total ): Bitcoin_Address;
59
60	/**
61	* Return the current Bitcoin details for an order, optionally refresh.
62	*
63	* @param WC_Order $wc_order   WooCommerce order object.
64	*
65	* @return WC_Bitcoin_Order
66	*/
67	public function get_order_details( WC_Order $wc_order ): WC_Bitcoin_Order;
68
69	/**
70	* Synchronously remotely query the blockchain for new payments.
71	*
72	* This should only be run on user interaction. There will be a cron job checking it regularly anyway. This is
73	* almost like a pedestrian crossing button, or an elevator button. It might make a tiny difference but the
74	* system should already be managing it.
75	*
76	* @param WC_Order $order The order, presumably with Bitcoin chosen at checkout, to look for payments for.
77	*/
78	public function check_order_for_payment( WC_Order $order ): void;
79
80	/**
81	* Determine do we have any fresh address available for this gateway.
82	* Used so the gateway is not displayed at checkout if there are no addresses ready.
83	*
84	* @used-by Bitcoin_Gateway::is_available()
85	*
86	* @param Bitcoin_Gateway $gateway The WooCommerce payment gateway which should have addresses generated.
87	*/
88	public function is_unused_address_available_for_gateway( Bitcoin_Gateway $gateway ): bool;
89
90	/**
91	* Get a single unused Bitcoin address for a given payment gateway's wallet.
92	*
93	* @param Bitcoin_Gateway $gateway The Bitcoin payment gateway.
94	*
95	* @throws BH_WP_Bitcoin_Gateway_Exception When the wallet cannot be created/retrieved or unused addresses cannot be generated.
96	*/
97	public function get_fresh_address_for_gateway( Bitcoin_Gateway $gateway ): ?Bitcoin_Address;
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	*
104	* @return array<string, string|null|Money|BigNumber|array<Bitcoin_Transaction>>
105	* @throws BH_WP_Bitcoin_Gateway_Exception When the order has no Bitcoin address.
106	*/
107	public function get_formatted_order_details( WC_Order $order ): array;
108
109	/**
110	* Record (log) newly seen transactions as order notes.
111	*
112	* The signature on this will probably change so we can pass the confirmed/unconfirmed amounts to the printer.
113	*
114	* @param WC_Order                     $order The order <- the payment address <- the new transactions.
115	* @param array<Transaction_Interface> $new_transactions List of transactions.
116	*/
117	public function add_order_note_for_transactions( WC_Order $order, array $new_transactions ): void;
118
119	/**
120	* Set a WooCommerce order paid with the data from the Payment_Service.
121	*
122	* @param WC_Order                                 $wc_order The order to mark paid (wc-completed).
123	* @param Check_Address_For_Payment_Service_Result $check_address_for_payment_service_result The payment details.
124	*/
125	public function mark_order_paid( WC_Order $wc_order, Check_Address_For_Payment_Service_Result $check_address_for_payment_service_result, ): void;
126	}