1	<?php
2
3	namespace BuyerKiosk\SellerMarketing\Triggers;
4
5	/**
6	* TriggerInterface
7	*
8	* Defines the contract that all SMS marketing trigger types must implement.
9	* This interface ensures consistency across different trigger implementations
10	* and enables the trigger system to work with any trigger type polymorphically.
11	*
12	* @package BuyerKiosk\SellerMarketing\Triggers
13	*/
14	interface TriggerInterface
15	{
16	/**
17	* Find customers matching the trigger criteria
18	*
19	* This method queries the store database to find customers who meet the
20	* specific conditions defined by this trigger type. The implementation
21	* should handle all database queries and filtering logic.
22	*
23	* @param string $typeNum Store identifier (e.g., 'ou00', 'pc00')
24	* @param array $triggerConfig Configuration array containing trigger-specific settings
25	*                            Common keys: 'days', 'min_rating', 'customer_type', etc.
26	* @return array Array of customer data arrays, each containing:
27	*               - customerID: int Customer identifier
28	*               - firstName: string Customer first name
29	*               - lastName: string Customer last name
30	*               - phone: string Customer phone number (10 digits)
31	*               - email: string|null Customer email
32	*               - Additional fields specific to trigger type
33	* @throws \Exception When database connection fails or query errors occur
34	*/
35	public function findCustomers($typeNum, $triggerConfig);
36
37	/**
38	* Get the trigger type identifier
39	*
40	* Returns a unique string identifier for this trigger type.
41	* This identifier is used to map trigger configurations to their
42	* appropriate handler classes.
43	*
44	* @return string Trigger type identifier (e.g., 'days_since_sold', 'birthday')
45	*/
46	public function getTriggerType();
47
48	/**
49	* Validate trigger configuration
50	*
51	* Validates that the provided trigger configuration contains all required
52	* fields and that the values are within acceptable ranges. This method
53	* should be called before saving trigger configuration or processing triggers.
54	*
55	* @param array $config Trigger configuration to validate
56	* @return bool True if configuration is valid, false otherwise
57	*/
58	public function validateConfig($config);
59
60	/**
61	* Build personalized message for a customer
62	*
63	* Takes a message template and replaces all variable placeholders with
64	* actual customer and store data. Supports variables like:
65	* - %customer% or %firstname%: Customer's first name
66	* - %lastname%: Customer's last name
67	* - %company% or %coop%: Store/company name
68	* - %store%: Store city/location
69	* - %points%: Customer's loyalty points
70	* - %days%: Number of days (context-dependent)
71	*
72	* @param string $messageTemplate Message template with variable placeholders
73	* @param array $customerData Customer data array from findCustomers()
74	* @param array $storeData Store information array containing:
75	*                        - companyName: string Store company name
76	*                        - city: string Store city/location
77	*                        - typeNum: string Store identifier
78	* @return string Final message with all variables replaced
79	* @throws \InvalidArgumentException If required data is missing
80	*/
81	public function buildMessage($messageTemplate, $customerData, $storeData);
82	}