charitable / vendor / square / square / src / Loyalty / Rewards / RewardsClient.php

RewardsClient.php in Charitable – Donation & Fundraising Platform (Donation Forms, Recurring Donations & Fundraising Campaigns) 1.8.13.1, at vendor/square/square/src/Loyalty/Rewards/RewardsClient.php

371 lines 14.3 KB

Raw Download Zip

1	<?php
2
3	namespace Square\Loyalty\Rewards;
4
5	use GuzzleHttp\ClientInterface;
6	use Square\Core\Client\RawClient;
7	use Square\Loyalty\Rewards\Requests\CreateLoyaltyRewardRequest;
8	use Square\Types\CreateLoyaltyRewardResponse;
9	use Square\Exceptions\SquareException;
10	use Square\Exceptions\SquareApiException;
11	use Square\Core\Json\JsonApiRequest;
12	use Square\Environments;
13	use Square\Core\Client\HttpMethod;
14	use JsonException;
15	use GuzzleHttp\Exception\RequestException;
16	use Psr\Http\Client\ClientExceptionInterface;
17	use Square\Loyalty\Rewards\Requests\SearchLoyaltyRewardsRequest;
18	use Square\Types\SearchLoyaltyRewardsResponse;
19	use Square\Loyalty\Rewards\Requests\GetRewardsRequest;
20	use Square\Types\GetLoyaltyRewardResponse;
21	use Square\Loyalty\Rewards\Requests\DeleteRewardsRequest;
22	use Square\Types\DeleteLoyaltyRewardResponse;
23	use Square\Loyalty\Rewards\Requests\RedeemLoyaltyRewardRequest;
24	use Square\Types\RedeemLoyaltyRewardResponse;
25
26	class RewardsClient
27	{
28	/**
29	* @var array{
30	* baseUrl?: string,
31	* client?: ClientInterface,
32	* maxRetries?: int,
33	* timeout?: float,
34	* headers?: array<string, string>,
35	* } $options
36	*/
37	private array $options;
38
39	/**
40	* @var RawClient $client
41	*/
42	private RawClient $client;
43
44	/**
45	* @param RawClient $client
46	* @param ?array{
47	* baseUrl?: string,
48	* client?: ClientInterface,
49	* maxRetries?: int,
50	* timeout?: float,
51	* headers?: array<string, string>,
52	* } $options
53	*/
54	public function __construct(
55	RawClient $client,
56	?array $options = null,
57	) {
58	$this->client = $client;
59	$this->options = $options ?? [];
60	}
61
62	/**
63	* Creates a loyalty reward. In the process, the endpoint does following:
64	*
65	* - Uses the `reward_tier_id` in the request to determine the number of points
66	* to lock for this reward.
67	* - If the request includes `order_id`, it adds the reward and related discount to the order.
68	*
69	* After a reward is created, the points are locked and
70	* not available for the buyer to redeem another reward.
71	*
72	* @param CreateLoyaltyRewardRequest $request
73	* @param ?array{
74	* baseUrl?: string,
75	* maxRetries?: int,
76	* timeout?: float,
77	* headers?: array<string, string>,
78	* queryParameters?: array<string, mixed>,
79	* bodyProperties?: array<string, mixed>,
80	* } $options
81	* @return CreateLoyaltyRewardResponse
82	* @throws SquareException
83	* @throws SquareApiException
84	*/
85	public function create(CreateLoyaltyRewardRequest $request, ?array $options = null): CreateLoyaltyRewardResponse
86	{
87	$options = array_merge($this->options, $options ?? []);
88	try {
89	$response = $this->client->sendRequest(
90	new JsonApiRequest(
91	baseUrl: $options['baseUrl'] ?? $this->client->options['baseUrl'] ?? Environments::Production->value,
92	path: "v2/loyalty/rewards",
93	method: HttpMethod::POST,
94	body: $request,
95	),
96	$options,
97	);
98	$statusCode = $response->getStatusCode();
99	if ($statusCode >= 200 && $statusCode < 400) {
100	$json = $response->getBody()->getContents();
101	return CreateLoyaltyRewardResponse::fromJson($json);
102	}
103	} catch (JsonException $e) {
104	throw new SquareException(message: "Failed to deserialize response: {$e->getMessage()}", previous: $e);
105	} catch (RequestException $e) {
106	$response = $e->getResponse();
107	if ($response === null) {
108	throw new SquareException(message: $e->getMessage(), previous: $e);
109	}
110	throw new SquareApiException(
111	message: "API request failed",
112	statusCode: $response->getStatusCode(),
113	body: $response->getBody()->getContents(),
114	);
115	} catch (ClientExceptionInterface $e) {
116	throw new SquareException(message: $e->getMessage(), previous: $e);
117	}
118	throw new SquareApiException(
119	message: 'API request failed',
120	statusCode: $statusCode,
121	body: $response->getBody()->getContents(),
122	);
123	}
124
125	/**
126	* Searches for loyalty rewards. This endpoint accepts a request with no query filters and returns results for all loyalty accounts.
127	* If you include a `query` object, `loyalty_account_id` is required and `status` is optional.
128	*
129	* If you know a reward ID, use the
130	* [RetrieveLoyaltyReward](api-endpoint:Loyalty-RetrieveLoyaltyReward) endpoint.
131	*
132	* Search results are sorted by `updated_at` in descending order.
133	*
134	* @param SearchLoyaltyRewardsRequest $request
135	* @param ?array{
136	* baseUrl?: string,
137	* maxRetries?: int,
138	* timeout?: float,
139	* headers?: array<string, string>,
140	* queryParameters?: array<string, mixed>,
141	* bodyProperties?: array<string, mixed>,
142	* } $options
143	* @return SearchLoyaltyRewardsResponse
144	* @throws SquareException
145	* @throws SquareApiException
146	*/
147	public function search(SearchLoyaltyRewardsRequest $request = new SearchLoyaltyRewardsRequest(), ?array $options = null): SearchLoyaltyRewardsResponse
148	{
149	$options = array_merge($this->options, $options ?? []);
150	try {
151	$response = $this->client->sendRequest(
152	new JsonApiRequest(
153	baseUrl: $options['baseUrl'] ?? $this->client->options['baseUrl'] ?? Environments::Production->value,
154	path: "v2/loyalty/rewards/search",
155	method: HttpMethod::POST,
156	body: $request,
157	),
158	$options,
159	);
160	$statusCode = $response->getStatusCode();
161	if ($statusCode >= 200 && $statusCode < 400) {
162	$json = $response->getBody()->getContents();
163	return SearchLoyaltyRewardsResponse::fromJson($json);
164	}
165	} catch (JsonException $e) {
166	throw new SquareException(message: "Failed to deserialize response: {$e->getMessage()}", previous: $e);
167	} catch (RequestException $e) {
168	$response = $e->getResponse();
169	if ($response === null) {
170	throw new SquareException(message: $e->getMessage(), previous: $e);
171	}
172	throw new SquareApiException(
173	message: "API request failed",
174	statusCode: $response->getStatusCode(),
175	body: $response->getBody()->getContents(),
176	);
177	} catch (ClientExceptionInterface $e) {
178	throw new SquareException(message: $e->getMessage(), previous: $e);
179	}
180	throw new SquareApiException(
181	message: 'API request failed',
182	statusCode: $statusCode,
183	body: $response->getBody()->getContents(),
184	);
185	}
186
187	/**
188	* Retrieves a loyalty reward.
189	*
190	* @param GetRewardsRequest $request
191	* @param ?array{
192	* baseUrl?: string,
193	* maxRetries?: int,
194	* timeout?: float,
195	* headers?: array<string, string>,
196	* queryParameters?: array<string, mixed>,
197	* bodyProperties?: array<string, mixed>,
198	* } $options
199	* @return GetLoyaltyRewardResponse
200	* @throws SquareException
201	* @throws SquareApiException
202	*/
203	public function get(GetRewardsRequest $request, ?array $options = null): GetLoyaltyRewardResponse
204	{
205	$options = array_merge($this->options, $options ?? []);
206	try {
207	$response = $this->client->sendRequest(
208	new JsonApiRequest(
209	baseUrl: $options['baseUrl'] ?? $this->client->options['baseUrl'] ?? Environments::Production->value,
210	path: "v2/loyalty/rewards/{$request->getRewardId()}",
211	method: HttpMethod::GET,
212	),
213	$options,
214	);
215	$statusCode = $response->getStatusCode();
216	if ($statusCode >= 200 && $statusCode < 400) {
217	$json = $response->getBody()->getContents();
218	return GetLoyaltyRewardResponse::fromJson($json);
219	}
220	} catch (JsonException $e) {
221	throw new SquareException(message: "Failed to deserialize response: {$e->getMessage()}", previous: $e);
222	} catch (RequestException $e) {
223	$response = $e->getResponse();
224	if ($response === null) {
225	throw new SquareException(message: $e->getMessage(), previous: $e);
226	}
227	throw new SquareApiException(
228	message: "API request failed",
229	statusCode: $response->getStatusCode(),
230	body: $response->getBody()->getContents(),
231	);
232	} catch (ClientExceptionInterface $e) {
233	throw new SquareException(message: $e->getMessage(), previous: $e);
234	}
235	throw new SquareApiException(
236	message: 'API request failed',
237	statusCode: $statusCode,
238	body: $response->getBody()->getContents(),
239	);
240	}
241
242	/**
243	* Deletes a loyalty reward by doing the following:
244	*
245	* - Returns the loyalty points back to the loyalty account.
246	* - If an order ID was specified when the reward was created
247	* (see [CreateLoyaltyReward](api-endpoint:Loyalty-CreateLoyaltyReward)),
248	* it updates the order by removing the reward and related
249	* discounts.
250	*
251	* You cannot delete a reward that has reached the terminal state (REDEEMED).
252	*
253	* @param DeleteRewardsRequest $request
254	* @param ?array{
255	* baseUrl?: string,
256	* maxRetries?: int,
257	* timeout?: float,
258	* headers?: array<string, string>,
259	* queryParameters?: array<string, mixed>,
260	* bodyProperties?: array<string, mixed>,
261	* } $options
262	* @return DeleteLoyaltyRewardResponse
263	* @throws SquareException
264	* @throws SquareApiException
265	*/
266	public function delete(DeleteRewardsRequest $request, ?array $options = null): DeleteLoyaltyRewardResponse
267	{
268	$options = array_merge($this->options, $options ?? []);
269	try {
270	$response = $this->client->sendRequest(
271	new JsonApiRequest(
272	baseUrl: $options['baseUrl'] ?? $this->client->options['baseUrl'] ?? Environments::Production->value,
273	path: "v2/loyalty/rewards/{$request->getRewardId()}",
274	method: HttpMethod::DELETE,
275	),
276	$options,
277	);
278	$statusCode = $response->getStatusCode();
279	if ($statusCode >= 200 && $statusCode < 400) {
280	$json = $response->getBody()->getContents();
281	return DeleteLoyaltyRewardResponse::fromJson($json);
282	}
283	} catch (JsonException $e) {
284	throw new SquareException(message: "Failed to deserialize response: {$e->getMessage()}", previous: $e);
285	} catch (RequestException $e) {
286	$response = $e->getResponse();
287	if ($response === null) {
288	throw new SquareException(message: $e->getMessage(), previous: $e);
289	}
290	throw new SquareApiException(
291	message: "API request failed",
292	statusCode: $response->getStatusCode(),
293	body: $response->getBody()->getContents(),
294	);
295	} catch (ClientExceptionInterface $e) {
296	throw new SquareException(message: $e->getMessage(), previous: $e);
297	}
298	throw new SquareApiException(
299	message: 'API request failed',
300	statusCode: $statusCode,
301	body: $response->getBody()->getContents(),
302	);
303	}
304
305	/**
306	* Redeems a loyalty reward.
307	*
308	* The endpoint sets the reward to the `REDEEMED` terminal state.
309	*
310	* If you are using your own order processing system (not using the
311	* Orders API), you call this endpoint after the buyer paid for the
312	* purchase.
313	*
314	* After the reward reaches the terminal state, it cannot be deleted.
315	* In other words, points used for the reward cannot be returned
316	* to the account.
317	*
318	* @param RedeemLoyaltyRewardRequest $request
319	* @param ?array{
320	* baseUrl?: string,
321	* maxRetries?: int,
322	* timeout?: float,
323	* headers?: array<string, string>,
324	* queryParameters?: array<string, mixed>,
325	* bodyProperties?: array<string, mixed>,
326	* } $options
327	* @return RedeemLoyaltyRewardResponse
328	* @throws SquareException
329	* @throws SquareApiException
330	*/
331	public function redeem(RedeemLoyaltyRewardRequest $request, ?array $options = null): RedeemLoyaltyRewardResponse
332	{
333	$options = array_merge($this->options, $options ?? []);
334	try {
335	$response = $this->client->sendRequest(
336	new JsonApiRequest(
337	baseUrl: $options['baseUrl'] ?? $this->client->options['baseUrl'] ?? Environments::Production->value,
338	path: "v2/loyalty/rewards/{$request->getRewardId()}/redeem",
339	method: HttpMethod::POST,
340	body: $request,
341	),
342	$options,
343	);
344	$statusCode = $response->getStatusCode();
345	if ($statusCode >= 200 && $statusCode < 400) {
346	$json = $response->getBody()->getContents();
347	return RedeemLoyaltyRewardResponse::fromJson($json);
348	}
349	} catch (JsonException $e) {
350	throw new SquareException(message: "Failed to deserialize response: {$e->getMessage()}", previous: $e);
351	} catch (RequestException $e) {
352	$response = $e->getResponse();
353	if ($response === null) {
354	throw new SquareException(message: $e->getMessage(), previous: $e);
355	}
356	throw new SquareApiException(
357	message: "API request failed",
358	statusCode: $response->getStatusCode(),
359	body: $response->getBody()->getContents(),
360	);
361	} catch (ClientExceptionInterface $e) {
362	throw new SquareException(message: $e->getMessage(), previous: $e);
363	}
364	throw new SquareApiException(
365	message: 'API request failed',
366	statusCode: $statusCode,
367	body: $response->getBody()->getContents(),
368	);
369	}
370	}
371