1	<?php
2
3	declare(strict_types=1);
4
5	namespace AqwSocketClient\Interfaces;
6
7	use AqwSocketClient\Enums\ScriptResult;
8	use AqwSocketClient\Scripts\ClientContext;
9
10	/**
11	* Represents a single unit of logic to be executed against a {@see AqwSocketClient\Interfaces\ClientInterface}.
12	*
13	* Scripts are composable — a script can be a single atomic step or a
14	* sequence of other scripts. The client drives the execution loop,
15	* advancing to the next script only when the current one is done.
16	*/
17	interface ScriptInterface
18	{
19	/**
20	* Called once by the client before the event loop begins.
21	*
22	* Returns the first command to send, or null if no immediate action is needed.
23	* Default implementation in AbstractScript returns null.
24	*
25	* @param ClientContext $context Shared session state.
26	*/
27	public function start(ClientContext $context): ?CommandInterface;
28
29	/**
30	* Handles an incoming event.
31	*
32	* Returns at most one command to send. The client queues it and sends it
33	* on the next available tick.
34	*
35	* @param EventInterface $event The incoming event.
36	* @param ClientContext  $context Shared session state.
37	*
38	* @return ?CommandInterface A command to dispatch, or null.
39	*/
40	public function handle(EventInterface $event, ClientContext $context): ?CommandInterface;
41
42	/**
43	* Returns the list of event types this script is interested in.
44	*
45	* @return array<class-string<EventInterface>>
46	*/
47	public function handles(): array;
48
49	/**
50	* Signals whether this script has completed its work.
51	*
52	* Checked by the client after every {@see AqwSocketClient\Interfaces\ScriptInterface::handle()} call.
53	* When true, the client stops driving this script and moves on.
54	*/
55	public function isDone(): bool;
56
57	/**
58	* Returns the final execution result of the script.
59	*
60	* Should only be relied upon once {@see AqwSocketClient\Interfaces\ScriptInterface::isDone()} returns true.
61	*/
62	public function result(): ScriptResult;
63
64	/**
65	* Marks the script as failed.
66	*/
67	public function failed(): void;
68
69	/**
70	* Marks the script as disconnected.
71	*/
72	public function disconnected(): void;
73
74	/**
75	* Marks the script as successfully completed.
76	*/
77	public function success(): void;
78	}