1	<?php
2
3	namespace BuyerKiosk\EventManagement\Adapters;
4
5	use BuyerKiosk\EventManagement\Models\Event;
6	use BuyerKiosk\EventManagement\Models\EventIntegration;
7
8	/**
9	* IntegrationAdapterInterface - Contract for all integration adapters
10	*
11	* Each adapter translates Event operations to target system operations.
12	* All adapters MUST set eventId on target records for traceability.
13	*
14	* This enables:
15	* - UI indicators showing "Created by {eventName}"
16	* - Delete warnings when user tries to remove event-managed records
17	* - Reverse lookup from any record to its parent event
18	*
19	* @package BuyerKiosk\EventManagement\Adapters
20	*/
21	interface IntegrationAdapterInterface
22	{
23	/**
24	* Get the integration type this adapter handles
25	*
26	* @return string One of EventIntegration::TYPE_* constants
27	*/
28	public function getType(): string;
29
30	/**
31	* Create a linked record in the target system
32	*
33	* The adapter MUST:
34	* 1. Create the record in the target system
35	* 2. Set eventId on the target record for traceability
36	* 3. Return the foreign ID of the created record
37	*
38	* @param Event $event The unified event
39	* @param array $config Integration-specific configuration
40	* @return int The foreign ID of the created record
41	* @throws IntegrationException On failure
42	*/
43	public function create(Event $event, array $config): int;
44
45	/**
46	* Update the linked record when event dates change
47	*
48	* Called when event dates are modified. The adapter should:
49	* 1. Recalculate dates based on relativeDays configuration
50	* 2. Update the target system record accordingly
51	*
52	* @param Event $event The updated event with new dates
53	* @param EventIntegration $integration The integration record with foreignId
54	* @throws IntegrationException On failure
55	*/
56	public function syncDates(Event $event, EventIntegration $integration): void;
57
58	/**
59	* Activate the integration (start/schedule in target system)
60	*
61	* Called when event transitions to active status or when
62	* phase processor determines integration should activate.
63	*
64	* @param Event $event The event being activated
65	* @param EventIntegration $integration The integration to activate
66	* @throws IntegrationException On failure
67	*/
68	public function activate(Event $event, EventIntegration $integration): void;
69
70	/**
71	* Deactivate/cancel the integration in target system
72	*
73	* Called when event is cancelled or integration needs to be stopped.
74	* Should gracefully handle active state in target system.
75	*
76	* @param Event $event The event being deactivated
77	* @param EventIntegration $integration The integration to deactivate
78	* @throws IntegrationException On failure
79	*/
80	public function deactivate(Event $event, EventIntegration $integration): void;
81
82	/**
83	* Delete the linked record (cascade from event deletion)
84	*
85	* Called when event is permanently deleted. Should:
86	* 1. Remove the target system record
87	* 2. Handle any cleanup required
88	*
89	* @param EventIntegration $integration The integration to delete
90	* @throws IntegrationException On failure
91	*/
92	public function delete(EventIntegration $integration): void;
93
94	/**
95	* Get status information from the target system
96	*
97	* Returns current status and metrics for dashboard display.
98	* Status information varies by integration type.
99	*
100	* @param EventIntegration $integration The integration to check
101	* @return array Status details including:
102	*   - 'status': string (pending, active, completed, failed)
103	*   - 'details': array of type-specific metrics
104	*   - 'lastUpdated': string timestamp
105	*/
106	public function getStatus(EventIntegration $integration): array;
107
108	/**
109	* Validate configuration before creating integration
110	*
111	* @param array $config Configuration to validate
112	* @return array Array of validation errors (empty if valid)
113	*/
114	public function validateConfig(array $config): array;
115
116	/**
117	* Get the default configuration for this integration type
118	*
119	* Used when creating integrations from templates or UI.
120	*
121	* @return array Default configuration values
122	*/
123	public function getDefaultConfig(): array;
124	}