Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
0.00%
0 / 1
n/a
0 / 0
 CRAP
n/a
0 / 0
1<?php
2
3declare(strict_types=1);
4
5/** @license For full copyright and license information, please see the LICENSE.md file. */
6
7namespace App\Core\Instance\Application\Service;
8
9defined('AMMONLY_APP') || exit('Direct script access is forbidden.');
10
11use App\Core\Grid\GridRequest;
12use App\Core\Instance\Domain\Model\ClientInstance;
13
14/**
15 * Remote Instance Engine Gateway Interface.
16 *
17 * Facade contract for querying and modifying module records on remote client instances via REST API.
18 *
19 * @package App\Core\Instance\Application\Service
20 */
21interface RemoteInstanceEngineGatewayInterface
22{
23    /**
24     * Fetches complete module schema (module metadata, fields, filters, picklists) from remote instance.
25     *
26     * @param ClientInstance $instance   Target client instance.
27     * @param string         $moduleName Module machine name.
28     * @return array<string, mixed> Module schema data array.
29     */
30    public function fetchSchema(ClientInstance $instance, string $moduleName): array;
31
32    /**
33     * Fetches field definitions for a module from remote instance.
34     *
35     * @param ClientInstance $instance       Target client instance.
36     * @param string|int     $moduleNameOrId Module machine name or numeric ID.
37     * @return array<string, mixed> Fields response data array.
38     */
39    public function fetchFields(ClientInstance $instance, string|int $moduleNameOrId): array;
40
41    /**
42     * Fetches paginated DataGrid list rows and total counts from remote instance.
43     *
44     * @param ClientInstance $instance   Target client instance.
45     * @param string         $moduleName Module machine name.
46     * @param GridRequest    $request    Grid pagination, sorting, and search request.
47     * @param int|null       $filterId   Optional active filter ID.
48     * @return array<string, mixed> List data array with rows and totals.
49     */
50    public function fetchList(
51        ClientInstance $instance,
52        string $moduleName,
53        GridRequest $request,
54        ?int $filterId = null
55    ): array;
56
57    /**
58     * Fetches a single record by ID from remote instance.
59     *
60     * @param ClientInstance $instance   Target client instance.
61     * @param string         $moduleName Module machine name.
62     * @param int            $id         Record ID.
63     * @return array<string, mixed> Record data array.
64     */
65    public function fetchRecord(ClientInstance $instance, string $moduleName, int $id): array;
66
67    /**
68     * Creates a new record on remote instance.
69     *
70     * @param ClientInstance       $instance   Target client instance.
71     * @param string               $moduleName Module machine name.
72     * @param array<string, mixed> $payload    Record fields data.
73     * @return array<string, mixed> Created record response array.
74     */
75    public function createRecord(ClientInstance $instance, string $moduleName, array $payload): array;
76
77    /**
78     * Updates an existing record on remote instance.
79     *
80     * @param ClientInstance       $instance   Target client instance.
81     * @param string               $moduleName Module machine name.
82     * @param int                  $id         Record ID.
83     * @param array<string, mixed> $payload    Record fields data to update.
84     * @return array<string, mixed> Updated record response array.
85     */
86    public function updateRecord(
87        ClientInstance $instance,
88        string $moduleName,
89        int $id,
90        array $payload
91    ): array;
92
93    /**
94     * Deletes a record on remote instance.
95     *
96     * @param ClientInstance $instance   Target client instance.
97     * @param string         $moduleName Module machine name.
98     * @param int            $id         Record ID.
99     * @return array<string, mixed> Deletion result response array.
100     */
101    public function deleteRecord(ClientInstance $instance, string $moduleName, int $id): array;
102
103    /**
104     * Fetches audit log timeline for a record from remote instance.
105     *
106     * @param ClientInstance $instance   Target client instance.
107     * @param string         $moduleName Module machine name.
108     * @param int            $id         Record ID.
109     * @return array<string, mixed> Timeline data array.
110     */
111    public function fetchTimeline(ClientInstance $instance, string $moduleName, int $id): array;
112
113    /**
114     * Resolves record navigation metadata (prev/next/position) within active filter from remote instance.
115     *
116     * @param ClientInstance $instance   Target client instance.
117     * @param string         $moduleName Module machine name.
118     * @param int            $id         Record primary key.
119     * @param GridRequest    $request    Grid pagination and filter parameters.
120     * @param int|null       $filterId   Optional active filter ID.
121     * @return array<string, mixed> Navigation data array.
122     */
123    public function fetchNavigation(
124        ClientInstance $instance,
125        string $moduleName,
126        int $id,
127        GridRequest $request,
128        ?int $filterId = null
129    ): array;
130
131    /**
132     * Updates record lifecycle status code on remote instance.
133     *
134     * @param ClientInstance $instance   Target client instance.
135     * @param string         $moduleName Module machine name.
136     * @param int            $id         Record primary key.
137     * @param int            $status     Target status code (1=Available, 2=Archived, 3=Trash).
138     * @return array<string, mixed> Status update result response array.
139     */
140    public function updateStatus(ClientInstance $instance, string $moduleName, int $id, int $status): array;
141
142    /**
143     * Fetches active user options for assignment picklists from remote instance.
144     *
145     * @param ClientInstance $instance Target client instance.
146     * @return array<int, array{id: int, label: string, name: string}> List of active client users.
147     */
148    public function fetchClientUsers(ClientInstance $instance): array;
149
150    /**
151     * Fetches inventory line items for a document record from remote instance.
152     *
153     * @param ClientInstance $instance   Target client instance.
154     * @param string         $moduleName Module machine name.
155     * @param int            $recordId   Document record identifier.
156     * @return array<string, mixed> Inventory items response array.
157     */
158    public function fetchInventoryItems(ClientInstance $instance, string $moduleName, int $recordId): array;
159
160    /**
161     * Saves inventory line items for a document record on remote instance.
162     *
163     * @param ClientInstance                   $instance   Target client instance.
164     * @param string                           $moduleName Module machine name.
165     * @param int                              $recordId   Document record identifier.
166     * @param array<int, array<string, mixed>> $items      Line items array.
167     * @return array<string, mixed> Save result response array.
168     */
169    public function saveInventoryItems(
170        ClientInstance $instance,
171        string $moduleName,
172        int $recordId,
173        array $items
174    ): array;
175
176    /**
177     * Recalculates inventory line items, taxes, discounts, and currency conversion on remote instance.
178     *
179     * @param ClientInstance       $instance   Target client instance.
180     * @param string               $moduleName Module machine name.
181     * @param int                  $recordId   Document record identifier.
182     * @param array<string, mixed> $payload    Calculation payload with raw items and currency.
183     * @return array<string, mixed> Calculation result with updated items and summary.
184     */
185    public function calculateInventoryItems(
186        ClientInstance $instance,
187        string $moduleName,
188        int $recordId,
189        array $payload
190    ): array;
191}
192