diff --git a/composer.json b/composer.json index 47c3206e..1654452d 100644 --- a/composer.json +++ b/composer.json @@ -1,7 +1,7 @@ { "name": "square/square", "description": "Use Square APIs to manage and run business including payment, customer, product, inventory, and employee management.", - "version": "37.0.0.20240515", + "version": "37.1.0.20240604", "type": "library", "keywords": [ "Square", diff --git a/doc/apis/events.md b/doc/apis/events.md new file mode 100644 index 00000000..2f497258 --- /dev/null +++ b/doc/apis/events.md @@ -0,0 +1,149 @@ +# Events + +```php +$eventsApi = $client->getEventsApi(); +``` + +## Class Name + +`EventsApi` + +## Methods + +* [Search Events](../../doc/apis/events.md#search-events) +* [Disable Events](../../doc/apis/events.md#disable-events) +* [Enable Events](../../doc/apis/events.md#enable-events) +* [List Event Types](../../doc/apis/events.md#list-event-types) + + +# Search Events + +Search for Square API events that occur within a 28-day timeframe. + +```php +function searchEvents(SearchEventsRequest $body): ApiResponse +``` + +## Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `body` | [`SearchEventsRequest`](../../doc/models/search-events-request.md) | Body, Required | An object containing the fields to POST for the request.

See the corresponding object definition for field details. | + +## Response Type + +This method returns a `Square\Utils\ApiResponse` instance. The `getResult()` method on this instance returns the response data which is of type [`SearchEventsResponse`](../../doc/models/search-events-response.md). + +## Example Usage + +```php +$body = SearchEventsRequestBuilder::init()->build(); + +$apiResponse = $eventsApi->searchEvents($body); + +if ($apiResponse->isSuccess()) { + $searchEventsResponse = $apiResponse->getResult(); +} else { + $errors = $apiResponse->getErrors(); +} + +// Getting more response information +var_dump($apiResponse->getStatusCode()); +var_dump($apiResponse->getHeaders()); +``` + + +# Disable Events + +Disables events to prevent them from being searchable. +All events are disabled by default. You must enable events to make them searchable. +Disabling events for a specific time period prevents them from being searchable, even if you re-enable them later. + +```php +function disableEvents(): ApiResponse +``` + +## Response Type + +This method returns a `Square\Utils\ApiResponse` instance. The `getResult()` method on this instance returns the response data which is of type [`DisableEventsResponse`](../../doc/models/disable-events-response.md). + +## Example Usage + +```php +$apiResponse = $eventsApi->disableEvents(); + +if ($apiResponse->isSuccess()) { + $disableEventsResponse = $apiResponse->getResult(); +} else { + $errors = $apiResponse->getErrors(); +} + +// Getting more response information +var_dump($apiResponse->getStatusCode()); +var_dump($apiResponse->getHeaders()); +``` + + +# Enable Events + +Enables events to make them searchable. Only events that occur while in the enabled state are searchable. + +```php +function enableEvents(): ApiResponse +``` + +## Response Type + +This method returns a `Square\Utils\ApiResponse` instance. The `getResult()` method on this instance returns the response data which is of type [`EnableEventsResponse`](../../doc/models/enable-events-response.md). + +## Example Usage + +```php +$apiResponse = $eventsApi->enableEvents(); + +if ($apiResponse->isSuccess()) { + $enableEventsResponse = $apiResponse->getResult(); +} else { + $errors = $apiResponse->getErrors(); +} + +// Getting more response information +var_dump($apiResponse->getStatusCode()); +var_dump($apiResponse->getHeaders()); +``` + + +# List Event Types + +Lists all event types that you can subscribe to as webhooks or query using the Events API. + +```php +function listEventTypes(?string $apiVersion = null): ApiResponse +``` + +## Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `apiVersion` | `?string` | Query, Optional | The API version for which to list event types. Setting this field overrides the default version used by the application. | + +## Response Type + +This method returns a `Square\Utils\ApiResponse` instance. The `getResult()` method on this instance returns the response data which is of type [`ListEventTypesResponse`](../../doc/models/list-event-types-response.md). + +## Example Usage + +```php +$apiResponse = $eventsApi->listEventTypes(); + +if ($apiResponse->isSuccess()) { + $listEventTypesResponse = $apiResponse->getResult(); +} else { + $errors = $apiResponse->getErrors(); +} + +// Getting more response information +var_dump($apiResponse->getStatusCode()); +var_dump($apiResponse->getHeaders()); +``` + diff --git a/doc/client.md b/doc/client.md index 39746375..58e35b02 100644 --- a/doc/client.md +++ b/doc/client.md @@ -5,7 +5,7 @@ The following parameters are configurable for the API Client: | Parameter | Type | Description | | --- | --- | --- | -| `squareVersion` | `string` | Square Connect API versions
*Default*: `'2024-05-15'` | +| `squareVersion` | `string` | Square Connect API versions
*Default*: `'2024-06-04'` | | `customUrl` | `string` | Sets the base URL requests are made to. Defaults to `https://connect.squareup.com`
*Default*: `'https://connect.squareup.com'` | | `environment` | `string` | The API environment.
**Default: `production`** | | `timeout` | `int` | Timeout for API calls in seconds.
*Default*: `60` | @@ -30,7 +30,7 @@ $client = SquareClientBuilder::init() 'AccessToken' ) ) - ->squareVersion('2024-05-15') + ->squareVersion('2024-06-04') ->environment('production') ->customUrl('https://connect.squareup.com') ->build(); @@ -60,7 +60,7 @@ $client = SquareClientBuilder::init() 'AccessToken' ) ) - ->squareVersion('2024-05-15') + ->squareVersion('2024-06-04') ->build(); $apiResponse = $client->getLocationsApi()->listLocations(); @@ -101,6 +101,7 @@ The gateway for the SDK. This class acts as a factory for the Apis and also hold | getDevicesApi() | Gets DevicesApi | | getDisputesApi() | Gets DisputesApi | | getEmployeesApi() | Gets EmployeesApi | +| getEventsApi() | Gets EventsApi | | getGiftCardsApi() | Gets GiftCardsApi | | getGiftCardActivitiesApi() | Gets GiftCardActivitiesApi | | getInventoryApi() | Gets InventoryApi | diff --git a/doc/models/disable-events-response.md b/doc/models/disable-events-response.md new file mode 100644 index 00000000..a571e08d --- /dev/null +++ b/doc/models/disable-events-response.md @@ -0,0 +1,40 @@ + +# Disable Events Response + +Defines the fields that are included in the response body of +a request to the [DisableEvents](../../doc/apis/events.md#disable-events) endpoint. + +Note: if there are errors processing the request, the events field will not be +present. + +## Structure + +`DisableEventsResponse` + +## Fields + +| Name | Type | Tags | Description | Getter | Setter | +| --- | --- | --- | --- | --- | --- | +| `errors` | [`?(Error[])`](../../doc/models/error.md) | Optional | Information on errors encountered during the request. | getErrors(): ?array | setErrors(?array errors): void | + +## Example (as JSON) + +```json +{ + "errors": [ + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + } + ] +} +``` + diff --git a/doc/models/enable-events-response.md b/doc/models/enable-events-response.md new file mode 100644 index 00000000..cf09e7a8 --- /dev/null +++ b/doc/models/enable-events-response.md @@ -0,0 +1,34 @@ + +# Enable Events Response + +Defines the fields that are included in the response body of +a request to the [EnableEvents](../../doc/apis/events.md#enable-events) endpoint. + +Note: if there are errors processing the request, the events field will not be +present. + +## Structure + +`EnableEventsResponse` + +## Fields + +| Name | Type | Tags | Description | Getter | Setter | +| --- | --- | --- | --- | --- | --- | +| `errors` | [`?(Error[])`](../../doc/models/error.md) | Optional | Information on errors encountered during the request. | getErrors(): ?array | setErrors(?array errors): void | + +## Example (as JSON) + +```json +{ + "errors": [ + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + } + ] +} +``` + diff --git a/doc/models/event-data.md b/doc/models/event-data.md index b401f01e..545af008 100644 --- a/doc/models/event-data.md +++ b/doc/models/event-data.md @@ -9,10 +9,10 @@ | Name | Type | Tags | Description | Getter | Setter | | --- | --- | --- | --- | --- | --- | -| `type` | `?string` | Optional | Name of the affected object’s type. | getType(): ?string | setType(?string type): void | -| `id` | `?string` | Optional | ID of the affected object. | getId(): ?string | setId(?string id): void | -| `deleted` | `?bool` | Optional | Is true if the affected object was deleted. Otherwise absent. | getDeleted(): ?bool | setDeleted(?bool deleted): void | -| `object` | `mixed` | Optional | An object containing fields and values relevant to the event. Is absent if affected object was deleted. | getObject(): | setObject( object): void | +| `type` | `?string` | Optional | The name of the affected object’s type. | getType(): ?string | setType(?string type): void | +| `id` | `?string` | Optional | The ID of the affected object. | getId(): ?string | setId(?string id): void | +| `deleted` | `?bool` | Optional | This is true if the affected object has been deleted; otherwise, it's absent. | getDeleted(): ?bool | setDeleted(?bool deleted): void | +| `object` | `mixed` | Optional | An object containing fields and values relevant to the event. It is absent if the affected object has been deleted. | getObject(): | setObject( object): void | ## Example (as JSON) diff --git a/doc/models/event-metadata.md b/doc/models/event-metadata.md new file mode 100644 index 00000000..bf9b88cc --- /dev/null +++ b/doc/models/event-metadata.md @@ -0,0 +1,25 @@ + +# Event Metadata + +Contains metadata about a particular [Event](../../doc/models/event.md). + +## Structure + +`EventMetadata` + +## Fields + +| Name | Type | Tags | Description | Getter | Setter | +| --- | --- | --- | --- | --- | --- | +| `eventId` | `?string` | Optional | A unique ID for the event. | getEventId(): ?string | setEventId(?string eventId): void | +| `apiVersion` | `?string` | Optional | The API version of the event. This corresponds to the default API version of the developer application at the time when the event was created. | getApiVersion(): ?string | setApiVersion(?string apiVersion): void | + +## Example (as JSON) + +```json +{ + "event_id": "event_id0", + "api_version": "api_version6" +} +``` + diff --git a/doc/models/event.md b/doc/models/event.md index 9a15e3ee..eaebb946 100644 --- a/doc/models/event.md +++ b/doc/models/event.md @@ -10,7 +10,7 @@ | Name | Type | Tags | Description | Getter | Setter | | --- | --- | --- | --- | --- | --- | | `merchantId` | `?string` | Optional | The ID of the target merchant associated with the event. | getMerchantId(): ?string | setMerchantId(?string merchantId): void | -| `locationId` | `?string` | Optional | The ID of the location associated with the event. | getLocationId(): ?string | setLocationId(?string locationId): void | +| `locationId` | `?string` | Optional | The ID of the target location associated with the event. | getLocationId(): ?string | setLocationId(?string locationId): void | | `type` | `?string` | Optional | The type of event this represents. | getType(): ?string | setType(?string type): void | | `eventId` | `?string` | Optional | A unique ID for the event. | getEventId(): ?string | setEventId(?string eventId): void | | `createdAt` | `?string` | Optional | Timestamp of when the event was created, in RFC 3339 format. | getCreatedAt(): ?string | setCreatedAt(?string createdAt): void | diff --git a/doc/models/list-event-types-request.md b/doc/models/list-event-types-request.md new file mode 100644 index 00000000..ba29874b --- /dev/null +++ b/doc/models/list-event-types-request.md @@ -0,0 +1,23 @@ + +# List Event Types Request + +Lists all event types that can be subscribed to. + +## Structure + +`ListEventTypesRequest` + +## Fields + +| Name | Type | Tags | Description | Getter | Setter | +| --- | --- | --- | --- | --- | --- | +| `apiVersion` | `?string` | Optional | The API version for which to list event types. Setting this field overrides the default version used by the application. | getApiVersion(): ?string | setApiVersion(?string apiVersion): void | + +## Example (as JSON) + +```json +{ + "api_version": "api_version0" +} +``` + diff --git a/doc/models/list-event-types-response.md b/doc/models/list-event-types-response.md new file mode 100644 index 00000000..10506698 --- /dev/null +++ b/doc/models/list-event-types-response.md @@ -0,0 +1,52 @@ + +# List Event Types Response + +Defines the fields that are included in the response body of +a request to the [ListEventTypes](../../doc/apis/events.md#list-event-types) endpoint. + +Note: if there are errors processing the request, the event types field will not be +present. + +## Structure + +`ListEventTypesResponse` + +## Fields + +| Name | Type | Tags | Description | Getter | Setter | +| --- | --- | --- | --- | --- | --- | +| `errors` | [`?(Error[])`](../../doc/models/error.md) | Optional | Information on errors encountered during the request. | getErrors(): ?array | setErrors(?array errors): void | +| `eventTypes` | `?(string[])` | Optional | The list of event types. | getEventTypes(): ?array | setEventTypes(?array eventTypes): void | +| `metadata` | [`?(EventTypeMetadata[])`](../../doc/models/event-type-metadata.md) | Optional | Contains the metadata of an event type. For more information, see [EventTypeMetadata](entity:EventTypeMetadata). | getMetadata(): ?array | setMetadata(?array metadata): void | + +## Example (as JSON) + +```json +{ + "event_types": [ + "inventory.count.updated" + ], + "metadata": [ + { + "api_version_introduced": "2018-07-12", + "event_type": "inventory.count.updated", + "release_status": "PUBLIC" + } + ], + "errors": [ + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + } + ] +} +``` + diff --git a/doc/models/quantity-ratio.md b/doc/models/quantity-ratio.md index 0fc4880c..02443bf3 100644 --- a/doc/models/quantity-ratio.md +++ b/doc/models/quantity-ratio.md @@ -12,7 +12,7 @@ A whole number or unreduced fractional ratio. | Name | Type | Tags | Description | Getter | Setter | | --- | --- | --- | --- | --- | --- | | `quantity` | `?int` | Optional | The whole or fractional quantity as the numerator. | getQuantity(): ?int | setQuantity(?int quantity): void | -| `quantityDenominator` | `?int` | Optional | The whole or fractional quantity as the denominator.
In the case of fractional quantity this field is the denominator and quantity is the numerator.
When unspecified, the value is `1`. For example, when `quantity=3` and `quantity_donominator` is unspecified,
the quantity ratio is `3` or `3/1`. | getQuantityDenominator(): ?int | setQuantityDenominator(?int quantityDenominator): void | +| `quantityDenominator` | `?int` | Optional | The whole or fractional quantity as the denominator.
With fractional quantity this field is the denominator and quantity is the numerator.
The default value is `1`. For example, when `quantity=3` and `quantity_denominator` is unspecified,
the quantity ratio is `3` or `3/1`. | getQuantityDenominator(): ?int | setQuantityDenominator(?int quantityDenominator): void | ## Example (as JSON) diff --git a/doc/models/search-events-filter.md b/doc/models/search-events-filter.md new file mode 100644 index 00000000..014ce762 --- /dev/null +++ b/doc/models/search-events-filter.md @@ -0,0 +1,43 @@ + +# Search Events Filter + +Criteria to filter events by. + +## Structure + +`SearchEventsFilter` + +## Fields + +| Name | Type | Tags | Description | Getter | Setter | +| --- | --- | --- | --- | --- | --- | +| `eventTypes` | `?(string[])` | Optional | Filter events by event types. | getEventTypes(): ?array | setEventTypes(?array eventTypes): void | +| `merchantIds` | `?(string[])` | Optional | Filter events by merchant. | getMerchantIds(): ?array | setMerchantIds(?array merchantIds): void | +| `locationIds` | `?(string[])` | Optional | Filter events by location. | getLocationIds(): ?array | setLocationIds(?array locationIds): void | +| `createdAt` | [`?TimeRange`](../../doc/models/time-range.md) | Optional | Represents a generic time range. The start and end values are
represented in RFC 3339 format. Time ranges are customized to be
inclusive or exclusive based on the needs of a particular endpoint.
Refer to the relevant endpoint-specific documentation to determine
how time ranges are handled. | getCreatedAt(): ?TimeRange | setCreatedAt(?TimeRange createdAt): void | + +## Example (as JSON) + +```json +{ + "event_types": [ + "event_types6", + "event_types7", + "event_types8" + ], + "merchant_ids": [ + "merchant_ids5", + "merchant_ids6", + "merchant_ids7" + ], + "location_ids": [ + "location_ids8", + "location_ids9" + ], + "created_at": { + "start_at": "start_at4", + "end_at": "end_at8" + } +} +``` + diff --git a/doc/models/search-events-query.md b/doc/models/search-events-query.md new file mode 100644 index 00000000..0c02688f --- /dev/null +++ b/doc/models/search-events-query.md @@ -0,0 +1,44 @@ + +# Search Events Query + +Contains query criteria for the search. + +## Structure + +`SearchEventsQuery` + +## Fields + +| Name | Type | Tags | Description | Getter | Setter | +| --- | --- | --- | --- | --- | --- | +| `filter` | [`?SearchEventsFilter`](../../doc/models/search-events-filter.md) | Optional | Criteria to filter events by. | getFilter(): ?SearchEventsFilter | setFilter(?SearchEventsFilter filter): void | +| `sort` | [`?SearchEventsSort`](../../doc/models/search-events-sort.md) | Optional | Criteria to sort events by. | getSort(): ?SearchEventsSort | setSort(?SearchEventsSort sort): void | + +## Example (as JSON) + +```json +{ + "filter": { + "event_types": [ + "event_types2", + "event_types3" + ], + "merchant_ids": [ + "merchant_ids1", + "merchant_ids2" + ], + "location_ids": [ + "location_ids4" + ], + "created_at": { + "start_at": "start_at4", + "end_at": "end_at8" + } + }, + "sort": { + "field": "DEFAULT", + "order": "DESC" + } +} +``` + diff --git a/doc/models/search-events-request.md b/doc/models/search-events-request.md new file mode 100644 index 00000000..249b72db --- /dev/null +++ b/doc/models/search-events-request.md @@ -0,0 +1,49 @@ + +# Search Events Request + +Searches [Event](../../doc/models/event.md)s for your application. + +## Structure + +`SearchEventsRequest` + +## Fields + +| Name | Type | Tags | Description | Getter | Setter | +| --- | --- | --- | --- | --- | --- | +| `cursor` | `?string` | Optional | A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of events for your original query.

For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
**Constraints**: *Maximum Length*: `256` | getCursor(): ?string | setCursor(?string cursor): void | +| `limit` | `?int` | Optional | The maximum number of events to return in a single page. The response might contain fewer events. The default value is 100, which is also the maximum allowed value.

For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).

Default: 100
**Constraints**: `>= 1`, `<= 100` | getLimit(): ?int | setLimit(?int limit): void | +| `query` | [`?SearchEventsQuery`](../../doc/models/search-events-query.md) | Optional | Contains query criteria for the search. | getQuery(): ?SearchEventsQuery | setQuery(?SearchEventsQuery query): void | + +## Example (as JSON) + +```json +{ + "cursor": "cursor8", + "limit": 176, + "query": { + "filter": { + "event_types": [ + "event_types2", + "event_types3" + ], + "merchant_ids": [ + "merchant_ids1", + "merchant_ids2" + ], + "location_ids": [ + "location_ids4" + ], + "created_at": { + "start_at": "start_at4", + "end_at": "end_at8" + } + }, + "sort": { + "field": "DEFAULT", + "order": "DESC" + } + } +} +``` + diff --git a/doc/models/search-events-response.md b/doc/models/search-events-response.md new file mode 100644 index 00000000..7bf382f6 --- /dev/null +++ b/doc/models/search-events-response.md @@ -0,0 +1,85 @@ + +# Search Events Response + +Defines the fields that are included in the response body of +a request to the [SearchEvents](../../doc/apis/events.md#search-events) endpoint. + +Note: if there are errors processing the request, the events field will not be +present. + +## Structure + +`SearchEventsResponse` + +## Fields + +| Name | Type | Tags | Description | Getter | Setter | +| --- | --- | --- | --- | --- | --- | +| `errors` | [`?(Error[])`](../../doc/models/error.md) | Optional | Information on errors encountered during the request. | getErrors(): ?array | setErrors(?array errors): void | +| `events` | [`?(Event[])`](../../doc/models/event.md) | Optional | The list of [Event](entity:Event)s returned by the search. | getEvents(): ?array | setEvents(?array events): void | +| `metadata` | [`?(EventMetadata[])`](../../doc/models/event-metadata.md) | Optional | Contains the metadata of an event. For more information, see [Event](entity:Event). | getMetadata(): ?array | setMetadata(?array metadata): void | +| `cursor` | `?string` | Optional | When a response is truncated, it includes a cursor that you can use in a subsequent request to fetch the next set of events. If empty, this is the final response.

For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). | getCursor(): ?string | setCursor(?string cursor): void | + +## Example (as JSON) + +```json +{ + "cursor": "6b571fc9773647f=", + "events": [ + { + "created_at": "2022-04-26T10:08:40.454726", + "data": { + "id": "ORSEVtZAJxb37RA1EiGw", + "object": { + "dispute": { + "amount_money": { + "amount": 8801, + "currency": "USD" + }, + "brand_dispute_id": "r9rKGSBBQbywBNnWWIiGFg", + "card_brand": "VISA", + "created_at": "2020-02-19T21:24:53.258Z", + "disputed_payment": { + "payment_id": "fbmsaEOpoARDKxiSGH1fqPuqoqFZY" + }, + "due_at": "2020-03-04T00:00:00.000Z", + "id": "ORSEVtZAJxb37RA1EiGw", + "location_id": "VJDQQP3CG14EY", + "reason": "AMOUNT_DIFFERS", + "reported_at": "2020-02-19T00:00:00.000Z", + "state": "WON", + "updated_at": "2020-02-19T21:34:41.851Z", + "version": 6 + } + }, + "type": "dispute" + }, + "event_id": "73ecd468-0aba-424f-b862-583d44efe7c8", + "location_id": "VJDQQP3CG14EY", + "merchant_id": "0HPGX5JYE6EE1", + "type": "dispute.state.updated" + } + ], + "metadata": [ + { + "api_version": "2022-12-13", + "event_id": "73ecd468-0aba-424f-b862-583d44efe7c8" + } + ], + "errors": [ + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + }, + { + "category": "MERCHANT_SUBSCRIPTION_ERROR", + "code": "MAP_KEY_LENGTH_TOO_LONG", + "detail": "detail6", + "field": "field4" + } + ] +} +``` + diff --git a/doc/models/search-events-sort-field.md b/doc/models/search-events-sort-field.md new file mode 100644 index 00000000..a342344b --- /dev/null +++ b/doc/models/search-events-sort-field.md @@ -0,0 +1,15 @@ + +# Search Events Sort Field + +Specifies the sort key for events returned from a search. + +## Enumeration + +`SearchEventsSortField` + +## Fields + +| Name | Description | +| --- | --- | +| `DEFAULT` | Use the default sort key. The default behavior is to sort events by when they were created (`created_at`). | + diff --git a/doc/models/search-events-sort.md b/doc/models/search-events-sort.md new file mode 100644 index 00000000..ea60bf8a --- /dev/null +++ b/doc/models/search-events-sort.md @@ -0,0 +1,25 @@ + +# Search Events Sort + +Criteria to sort events by. + +## Structure + +`SearchEventsSort` + +## Fields + +| Name | Type | Tags | Description | Getter | Setter | +| --- | --- | --- | --- | --- | --- | +| `field` | [`?string(SearchEventsSortField)`](../../doc/models/search-events-sort-field.md) | Optional | Specifies the sort key for events returned from a search. | getField(): ?string | setField(?string field): void | +| `order` | [`?string(SortOrder)`](../../doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | getOrder(): ?string | setOrder(?string order): void | + +## Example (as JSON) + +```json +{ + "field": "DEFAULT", + "order": "DESC" +} +``` + diff --git a/src/Apis/EventsApi.php b/src/Apis/EventsApi.php new file mode 100644 index 00000000..eefb48a0 --- /dev/null +++ b/src/Apis/EventsApi.php @@ -0,0 +1,89 @@ +requestBuilder(RequestMethod::POST, '/v2/events') + ->auth('global') + ->parameters(HeaderParam::init('Content-Type', 'application/json'), BodyParam::init($body)); + + $_resHandler = $this->responseHandler()->type(SearchEventsResponse::class)->returnApiResponse(); + + return $this->execute($_reqBuilder, $_resHandler); + } + + /** + * Disables events to prevent them from being searchable. + * All events are disabled by default. You must enable events to make them searchable. + * Disabling events for a specific time period prevents them from being searchable, even if you re- + * enable them later. + * + * @return ApiResponse Response from the API call + */ + public function disableEvents(): ApiResponse + { + $_reqBuilder = $this->requestBuilder(RequestMethod::PUT, '/v2/events/disable')->auth('global'); + + $_resHandler = $this->responseHandler()->type(DisableEventsResponse::class)->returnApiResponse(); + + return $this->execute($_reqBuilder, $_resHandler); + } + + /** + * Enables events to make them searchable. Only events that occur while in the enabled state are + * searchable. + * + * @return ApiResponse Response from the API call + */ + public function enableEvents(): ApiResponse + { + $_reqBuilder = $this->requestBuilder(RequestMethod::PUT, '/v2/events/enable')->auth('global'); + + $_resHandler = $this->responseHandler()->type(EnableEventsResponse::class)->returnApiResponse(); + + return $this->execute($_reqBuilder, $_resHandler); + } + + /** + * Lists all event types that you can subscribe to as webhooks or query using the Events API. + * + * @param string|null $apiVersion The API version for which to list event types. Setting this + * field overrides the default version used by the application. + * + * @return ApiResponse Response from the API call + */ + public function listEventTypes(?string $apiVersion = null): ApiResponse + { + $_reqBuilder = $this->requestBuilder(RequestMethod::GET, '/v2/events/types') + ->auth('global') + ->parameters(QueryParam::init('api_version', $apiVersion)); + + $_resHandler = $this->responseHandler()->type(ListEventTypesResponse::class)->returnApiResponse(); + + return $this->execute($_reqBuilder, $_resHandler); + } +} diff --git a/src/ConfigurationDefaults.php b/src/ConfigurationDefaults.php index 317fc2b6..e13834f0 100644 --- a/src/ConfigurationDefaults.php +++ b/src/ConfigurationDefaults.php @@ -27,7 +27,7 @@ class ConfigurationDefaults public const HTTP_METHODS_TO_RETRY = ['GET', 'PUT']; - public const SQUARE_VERSION = '2024-05-15'; + public const SQUARE_VERSION = '2024-06-04'; public const ADDITIONAL_HEADERS = []; diff --git a/src/Models/Builders/DisableEventsResponseBuilder.php b/src/Models/Builders/DisableEventsResponseBuilder.php new file mode 100644 index 00000000..bde524b4 --- /dev/null +++ b/src/Models/Builders/DisableEventsResponseBuilder.php @@ -0,0 +1,51 @@ +instance = $instance; + } + + /** + * Initializes a new disable events response Builder object. + */ + public static function init(): self + { + return new self(new DisableEventsResponse()); + } + + /** + * Sets errors field. + */ + public function errors(?array $value): self + { + $this->instance->setErrors($value); + return $this; + } + + /** + * Initializes a new disable events response object. + */ + public function build(): DisableEventsResponse + { + return CoreHelper::clone($this->instance); + } +} diff --git a/src/Models/Builders/EnableEventsResponseBuilder.php b/src/Models/Builders/EnableEventsResponseBuilder.php new file mode 100644 index 00000000..bcd3913a --- /dev/null +++ b/src/Models/Builders/EnableEventsResponseBuilder.php @@ -0,0 +1,51 @@ +instance = $instance; + } + + /** + * Initializes a new enable events response Builder object. + */ + public static function init(): self + { + return new self(new EnableEventsResponse()); + } + + /** + * Sets errors field. + */ + public function errors(?array $value): self + { + $this->instance->setErrors($value); + return $this; + } + + /** + * Initializes a new enable events response object. + */ + public function build(): EnableEventsResponse + { + return CoreHelper::clone($this->instance); + } +} diff --git a/src/Models/Builders/EventMetadataBuilder.php b/src/Models/Builders/EventMetadataBuilder.php new file mode 100644 index 00000000..bb39c6e1 --- /dev/null +++ b/src/Models/Builders/EventMetadataBuilder.php @@ -0,0 +1,78 @@ +instance = $instance; + } + + /** + * Initializes a new event metadata Builder object. + */ + public static function init(): self + { + return new self(new EventMetadata()); + } + + /** + * Sets event id field. + */ + public function eventId(?string $value): self + { + $this->instance->setEventId($value); + return $this; + } + + /** + * Unsets event id field. + */ + public function unsetEventId(): self + { + $this->instance->unsetEventId(); + return $this; + } + + /** + * Sets api version field. + */ + public function apiVersion(?string $value): self + { + $this->instance->setApiVersion($value); + return $this; + } + + /** + * Unsets api version field. + */ + public function unsetApiVersion(): self + { + $this->instance->unsetApiVersion(); + return $this; + } + + /** + * Initializes a new event metadata object. + */ + public function build(): EventMetadata + { + return CoreHelper::clone($this->instance); + } +} diff --git a/src/Models/Builders/ListEventTypesRequestBuilder.php b/src/Models/Builders/ListEventTypesRequestBuilder.php new file mode 100644 index 00000000..cdfd2351 --- /dev/null +++ b/src/Models/Builders/ListEventTypesRequestBuilder.php @@ -0,0 +1,60 @@ +instance = $instance; + } + + /** + * Initializes a new list event types request Builder object. + */ + public static function init(): self + { + return new self(new ListEventTypesRequest()); + } + + /** + * Sets api version field. + */ + public function apiVersion(?string $value): self + { + $this->instance->setApiVersion($value); + return $this; + } + + /** + * Unsets api version field. + */ + public function unsetApiVersion(): self + { + $this->instance->unsetApiVersion(); + return $this; + } + + /** + * Initializes a new list event types request object. + */ + public function build(): ListEventTypesRequest + { + return CoreHelper::clone($this->instance); + } +} diff --git a/src/Models/Builders/ListEventTypesResponseBuilder.php b/src/Models/Builders/ListEventTypesResponseBuilder.php new file mode 100644 index 00000000..6af11c52 --- /dev/null +++ b/src/Models/Builders/ListEventTypesResponseBuilder.php @@ -0,0 +1,69 @@ +instance = $instance; + } + + /** + * Initializes a new list event types response Builder object. + */ + public static function init(): self + { + return new self(new ListEventTypesResponse()); + } + + /** + * Sets errors field. + */ + public function errors(?array $value): self + { + $this->instance->setErrors($value); + return $this; + } + + /** + * Sets event types field. + */ + public function eventTypes(?array $value): self + { + $this->instance->setEventTypes($value); + return $this; + } + + /** + * Sets metadata field. + */ + public function metadata(?array $value): self + { + $this->instance->setMetadata($value); + return $this; + } + + /** + * Initializes a new list event types response object. + */ + public function build(): ListEventTypesResponse + { + return CoreHelper::clone($this->instance); + } +} diff --git a/src/Models/Builders/SearchEventsFilterBuilder.php b/src/Models/Builders/SearchEventsFilterBuilder.php new file mode 100644 index 00000000..64213a00 --- /dev/null +++ b/src/Models/Builders/SearchEventsFilterBuilder.php @@ -0,0 +1,106 @@ +instance = $instance; + } + + /** + * Initializes a new search events filter Builder object. + */ + public static function init(): self + { + return new self(new SearchEventsFilter()); + } + + /** + * Sets event types field. + */ + public function eventTypes(?array $value): self + { + $this->instance->setEventTypes($value); + return $this; + } + + /** + * Unsets event types field. + */ + public function unsetEventTypes(): self + { + $this->instance->unsetEventTypes(); + return $this; + } + + /** + * Sets merchant ids field. + */ + public function merchantIds(?array $value): self + { + $this->instance->setMerchantIds($value); + return $this; + } + + /** + * Unsets merchant ids field. + */ + public function unsetMerchantIds(): self + { + $this->instance->unsetMerchantIds(); + return $this; + } + + /** + * Sets location ids field. + */ + public function locationIds(?array $value): self + { + $this->instance->setLocationIds($value); + return $this; + } + + /** + * Unsets location ids field. + */ + public function unsetLocationIds(): self + { + $this->instance->unsetLocationIds(); + return $this; + } + + /** + * Sets created at field. + */ + public function createdAt(?TimeRange $value): self + { + $this->instance->setCreatedAt($value); + return $this; + } + + /** + * Initializes a new search events filter object. + */ + public function build(): SearchEventsFilter + { + return CoreHelper::clone($this->instance); + } +} diff --git a/src/Models/Builders/SearchEventsQueryBuilder.php b/src/Models/Builders/SearchEventsQueryBuilder.php new file mode 100644 index 00000000..a7c1d0bf --- /dev/null +++ b/src/Models/Builders/SearchEventsQueryBuilder.php @@ -0,0 +1,62 @@ +instance = $instance; + } + + /** + * Initializes a new search events query Builder object. + */ + public static function init(): self + { + return new self(new SearchEventsQuery()); + } + + /** + * Sets filter field. + */ + public function filter(?SearchEventsFilter $value): self + { + $this->instance->setFilter($value); + return $this; + } + + /** + * Sets sort field. + */ + public function sort(?SearchEventsSort $value): self + { + $this->instance->setSort($value); + return $this; + } + + /** + * Initializes a new search events query object. + */ + public function build(): SearchEventsQuery + { + return CoreHelper::clone($this->instance); + } +} diff --git a/src/Models/Builders/SearchEventsRequestBuilder.php b/src/Models/Builders/SearchEventsRequestBuilder.php new file mode 100644 index 00000000..79c5b01c --- /dev/null +++ b/src/Models/Builders/SearchEventsRequestBuilder.php @@ -0,0 +1,70 @@ +instance = $instance; + } + + /** + * Initializes a new search events request Builder object. + */ + public static function init(): self + { + return new self(new SearchEventsRequest()); + } + + /** + * Sets cursor field. + */ + public function cursor(?string $value): self + { + $this->instance->setCursor($value); + return $this; + } + + /** + * Sets limit field. + */ + public function limit(?int $value): self + { + $this->instance->setLimit($value); + return $this; + } + + /** + * Sets query field. + */ + public function query(?SearchEventsQuery $value): self + { + $this->instance->setQuery($value); + return $this; + } + + /** + * Initializes a new search events request object. + */ + public function build(): SearchEventsRequest + { + return CoreHelper::clone($this->instance); + } +} diff --git a/src/Models/Builders/SearchEventsResponseBuilder.php b/src/Models/Builders/SearchEventsResponseBuilder.php new file mode 100644 index 00000000..0785c9b8 --- /dev/null +++ b/src/Models/Builders/SearchEventsResponseBuilder.php @@ -0,0 +1,78 @@ +instance = $instance; + } + + /** + * Initializes a new search events response Builder object. + */ + public static function init(): self + { + return new self(new SearchEventsResponse()); + } + + /** + * Sets errors field. + */ + public function errors(?array $value): self + { + $this->instance->setErrors($value); + return $this; + } + + /** + * Sets events field. + */ + public function events(?array $value): self + { + $this->instance->setEvents($value); + return $this; + } + + /** + * Sets metadata field. + */ + public function metadata(?array $value): self + { + $this->instance->setMetadata($value); + return $this; + } + + /** + * Sets cursor field. + */ + public function cursor(?string $value): self + { + $this->instance->setCursor($value); + return $this; + } + + /** + * Initializes a new search events response object. + */ + public function build(): SearchEventsResponse + { + return CoreHelper::clone($this->instance); + } +} diff --git a/src/Models/Builders/SearchEventsSortBuilder.php b/src/Models/Builders/SearchEventsSortBuilder.php new file mode 100644 index 00000000..c35891b2 --- /dev/null +++ b/src/Models/Builders/SearchEventsSortBuilder.php @@ -0,0 +1,60 @@ +instance = $instance; + } + + /** + * Initializes a new search events sort Builder object. + */ + public static function init(): self + { + return new self(new SearchEventsSort()); + } + + /** + * Sets field field. + */ + public function field(?string $value): self + { + $this->instance->setField($value); + return $this; + } + + /** + * Sets order field. + */ + public function order(?string $value): self + { + $this->instance->setOrder($value); + return $this; + } + + /** + * Initializes a new search events sort object. + */ + public function build(): SearchEventsSort + { + return CoreHelper::clone($this->instance); + } +} diff --git a/src/Models/DisableEventsResponse.php b/src/Models/DisableEventsResponse.php new file mode 100644 index 00000000..d075b0b9 --- /dev/null +++ b/src/Models/DisableEventsResponse.php @@ -0,0 +1,68 @@ +errors; + } + + /** + * Sets Errors. + * Information on errors encountered during the request. + * + * @maps errors + * + * @param Error[]|null $errors + */ + public function setErrors(?array $errors): void + { + $this->errors = $errors; + } + + /** + * Encode this object to JSON + * + * @param bool $asArrayWhenEmpty Whether to serialize this model as an array whenever no fields + * are set. (default: false) + * + * @return array|stdClass + */ + #[\ReturnTypeWillChange] // @phan-suppress-current-line PhanUndeclaredClassAttribute for (php < 8.1) + public function jsonSerialize(bool $asArrayWhenEmpty = false) + { + $json = []; + if (isset($this->errors)) { + $json['errors'] = $this->errors; + } + $json = array_filter($json, function ($val) { + return $val !== null; + }); + + return (!$asArrayWhenEmpty && empty($json)) ? new stdClass() : $json; + } +} diff --git a/src/Models/EnableEventsResponse.php b/src/Models/EnableEventsResponse.php new file mode 100644 index 00000000..92d88421 --- /dev/null +++ b/src/Models/EnableEventsResponse.php @@ -0,0 +1,68 @@ +errors; + } + + /** + * Sets Errors. + * Information on errors encountered during the request. + * + * @maps errors + * + * @param Error[]|null $errors + */ + public function setErrors(?array $errors): void + { + $this->errors = $errors; + } + + /** + * Encode this object to JSON + * + * @param bool $asArrayWhenEmpty Whether to serialize this model as an array whenever no fields + * are set. (default: false) + * + * @return array|stdClass + */ + #[\ReturnTypeWillChange] // @phan-suppress-current-line PhanUndeclaredClassAttribute for (php < 8.1) + public function jsonSerialize(bool $asArrayWhenEmpty = false) + { + $json = []; + if (isset($this->errors)) { + $json['errors'] = $this->errors; + } + $json = array_filter($json, function ($val) { + return $val !== null; + }); + + return (!$asArrayWhenEmpty && empty($json)) ? new stdClass() : $json; + } +} diff --git a/src/Models/Event.php b/src/Models/Event.php index d1224e66..31374384 100644 --- a/src/Models/Event.php +++ b/src/Models/Event.php @@ -72,7 +72,7 @@ public function unsetMerchantId(): void /** * Returns Location Id. - * The ID of the location associated with the event. + * The ID of the target location associated with the event. */ public function getLocationId(): ?string { @@ -84,7 +84,7 @@ public function getLocationId(): ?string /** * Sets Location Id. - * The ID of the location associated with the event. + * The ID of the target location associated with the event. * * @maps location_id */ @@ -95,7 +95,7 @@ public function setLocationId(?string $locationId): void /** * Unsets Location Id. - * The ID of the location associated with the event. + * The ID of the target location associated with the event. */ public function unsetLocationId(): void { diff --git a/src/Models/EventData.php b/src/Models/EventData.php index be1c364e..fefe9116 100644 --- a/src/Models/EventData.php +++ b/src/Models/EventData.php @@ -31,7 +31,7 @@ class EventData implements \JsonSerializable /** * Returns Type. - * Name of the affected object’s type. + * The name of the affected object’s type. */ public function getType(): ?string { @@ -43,7 +43,7 @@ public function getType(): ?string /** * Sets Type. - * Name of the affected object’s type. + * The name of the affected object’s type. * * @maps type */ @@ -54,7 +54,7 @@ public function setType(?string $type): void /** * Unsets Type. - * Name of the affected object’s type. + * The name of the affected object’s type. */ public function unsetType(): void { @@ -63,7 +63,7 @@ public function unsetType(): void /** * Returns Id. - * ID of the affected object. + * The ID of the affected object. */ public function getId(): ?string { @@ -72,7 +72,7 @@ public function getId(): ?string /** * Sets Id. - * ID of the affected object. + * The ID of the affected object. * * @maps id */ @@ -83,7 +83,7 @@ public function setId(?string $id): void /** * Returns Deleted. - * Is true if the affected object was deleted. Otherwise absent. + * This is true if the affected object has been deleted; otherwise, it's absent. */ public function getDeleted(): ?bool { @@ -95,7 +95,7 @@ public function getDeleted(): ?bool /** * Sets Deleted. - * Is true if the affected object was deleted. Otherwise absent. + * This is true if the affected object has been deleted; otherwise, it's absent. * * @maps deleted */ @@ -106,7 +106,7 @@ public function setDeleted(?bool $deleted): void /** * Unsets Deleted. - * Is true if the affected object was deleted. Otherwise absent. + * This is true if the affected object has been deleted; otherwise, it's absent. */ public function unsetDeleted(): void { @@ -115,8 +115,8 @@ public function unsetDeleted(): void /** * Returns Object. - * An object containing fields and values relevant to the event. Is absent if affected object was - * deleted. + * An object containing fields and values relevant to the event. It is absent if the affected object + * has been deleted. * * @return mixed */ @@ -130,8 +130,8 @@ public function getObject() /** * Sets Object. - * An object containing fields and values relevant to the event. Is absent if affected object was - * deleted. + * An object containing fields and values relevant to the event. It is absent if the affected object + * has been deleted. * * @maps object * @@ -144,8 +144,8 @@ public function setObject($object): void /** * Unsets Object. - * An object containing fields and values relevant to the event. Is absent if affected object was - * deleted. + * An object containing fields and values relevant to the event. It is absent if the affected object + * has been deleted. */ public function unsetObject(): void { diff --git a/src/Models/EventMetadata.php b/src/Models/EventMetadata.php new file mode 100644 index 00000000..64a52702 --- /dev/null +++ b/src/Models/EventMetadata.php @@ -0,0 +1,115 @@ +eventId) == 0) { + return null; + } + return $this->eventId['value']; + } + + /** + * Sets Event Id. + * A unique ID for the event. + * + * @maps event_id + */ + public function setEventId(?string $eventId): void + { + $this->eventId['value'] = $eventId; + } + + /** + * Unsets Event Id. + * A unique ID for the event. + */ + public function unsetEventId(): void + { + $this->eventId = []; + } + + /** + * Returns Api Version. + * The API version of the event. This corresponds to the default API version of the developer + * application at the time when the event was created. + */ + public function getApiVersion(): ?string + { + if (count($this->apiVersion) == 0) { + return null; + } + return $this->apiVersion['value']; + } + + /** + * Sets Api Version. + * The API version of the event. This corresponds to the default API version of the developer + * application at the time when the event was created. + * + * @maps api_version + */ + public function setApiVersion(?string $apiVersion): void + { + $this->apiVersion['value'] = $apiVersion; + } + + /** + * Unsets Api Version. + * The API version of the event. This corresponds to the default API version of the developer + * application at the time when the event was created. + */ + public function unsetApiVersion(): void + { + $this->apiVersion = []; + } + + /** + * Encode this object to JSON + * + * @param bool $asArrayWhenEmpty Whether to serialize this model as an array whenever no fields + * are set. (default: false) + * + * @return array|stdClass + */ + #[\ReturnTypeWillChange] // @phan-suppress-current-line PhanUndeclaredClassAttribute for (php < 8.1) + public function jsonSerialize(bool $asArrayWhenEmpty = false) + { + $json = []; + if (!empty($this->eventId)) { + $json['event_id'] = $this->eventId['value']; + } + if (!empty($this->apiVersion)) { + $json['api_version'] = $this->apiVersion['value']; + } + $json = array_filter($json, function ($val) { + return $val !== null; + }); + + return (!$asArrayWhenEmpty && empty($json)) ? new stdClass() : $json; + } +} diff --git a/src/Models/ListEventTypesRequest.php b/src/Models/ListEventTypesRequest.php new file mode 100644 index 00000000..eb5fa8da --- /dev/null +++ b/src/Models/ListEventTypesRequest.php @@ -0,0 +1,75 @@ +apiVersion) == 0) { + return null; + } + return $this->apiVersion['value']; + } + + /** + * Sets Api Version. + * The API version for which to list event types. Setting this field overrides the default version used + * by the application. + * + * @maps api_version + */ + public function setApiVersion(?string $apiVersion): void + { + $this->apiVersion['value'] = $apiVersion; + } + + /** + * Unsets Api Version. + * The API version for which to list event types. Setting this field overrides the default version used + * by the application. + */ + public function unsetApiVersion(): void + { + $this->apiVersion = []; + } + + /** + * Encode this object to JSON + * + * @param bool $asArrayWhenEmpty Whether to serialize this model as an array whenever no fields + * are set. (default: false) + * + * @return array|stdClass + */ + #[\ReturnTypeWillChange] // @phan-suppress-current-line PhanUndeclaredClassAttribute for (php < 8.1) + public function jsonSerialize(bool $asArrayWhenEmpty = false) + { + $json = []; + if (!empty($this->apiVersion)) { + $json['api_version'] = $this->apiVersion['value']; + } + $json = array_filter($json, function ($val) { + return $val !== null; + }); + + return (!$asArrayWhenEmpty && empty($json)) ? new stdClass() : $json; + } +} diff --git a/src/Models/ListEventTypesResponse.php b/src/Models/ListEventTypesResponse.php new file mode 100644 index 00000000..137fc9a8 --- /dev/null +++ b/src/Models/ListEventTypesResponse.php @@ -0,0 +1,134 @@ +errors; + } + + /** + * Sets Errors. + * Information on errors encountered during the request. + * + * @maps errors + * + * @param Error[]|null $errors + */ + public function setErrors(?array $errors): void + { + $this->errors = $errors; + } + + /** + * Returns Event Types. + * The list of event types. + * + * @return string[]|null + */ + public function getEventTypes(): ?array + { + return $this->eventTypes; + } + + /** + * Sets Event Types. + * The list of event types. + * + * @maps event_types + * + * @param string[]|null $eventTypes + */ + public function setEventTypes(?array $eventTypes): void + { + $this->eventTypes = $eventTypes; + } + + /** + * Returns Metadata. + * Contains the metadata of an event type. For more information, see [EventTypeMetadata](entity: + * EventTypeMetadata). + * + * @return EventTypeMetadata[]|null + */ + public function getMetadata(): ?array + { + return $this->metadata; + } + + /** + * Sets Metadata. + * Contains the metadata of an event type. For more information, see [EventTypeMetadata](entity: + * EventTypeMetadata). + * + * @maps metadata + * + * @param EventTypeMetadata[]|null $metadata + */ + public function setMetadata(?array $metadata): void + { + $this->metadata = $metadata; + } + + /** + * Encode this object to JSON + * + * @param bool $asArrayWhenEmpty Whether to serialize this model as an array whenever no fields + * are set. (default: false) + * + * @return array|stdClass + */ + #[\ReturnTypeWillChange] // @phan-suppress-current-line PhanUndeclaredClassAttribute for (php < 8.1) + public function jsonSerialize(bool $asArrayWhenEmpty = false) + { + $json = []; + if (isset($this->errors)) { + $json['errors'] = $this->errors; + } + if (isset($this->eventTypes)) { + $json['event_types'] = $this->eventTypes; + } + if (isset($this->metadata)) { + $json['metadata'] = $this->metadata; + } + $json = array_filter($json, function ($val) { + return $val !== null; + }); + + return (!$asArrayWhenEmpty && empty($json)) ? new stdClass() : $json; + } +} diff --git a/src/Models/QuantityRatio.php b/src/Models/QuantityRatio.php index 7b7ecdfd..513c20b5 100644 --- a/src/Models/QuantityRatio.php +++ b/src/Models/QuantityRatio.php @@ -56,9 +56,8 @@ public function unsetQuantity(): void /** * Returns Quantity Denominator. * The whole or fractional quantity as the denominator. - * In the case of fractional quantity this field is the denominator and quantity is the numerator. - * When unspecified, the value is `1`. For example, when `quantity=3` and `quantity_donominator` is - * unspecified, + * With fractional quantity this field is the denominator and quantity is the numerator. + * The default value is `1`. For example, when `quantity=3` and `quantity_denominator` is unspecified, * the quantity ratio is `3` or `3/1`. */ public function getQuantityDenominator(): ?int @@ -72,9 +71,8 @@ public function getQuantityDenominator(): ?int /** * Sets Quantity Denominator. * The whole or fractional quantity as the denominator. - * In the case of fractional quantity this field is the denominator and quantity is the numerator. - * When unspecified, the value is `1`. For example, when `quantity=3` and `quantity_donominator` is - * unspecified, + * With fractional quantity this field is the denominator and quantity is the numerator. + * The default value is `1`. For example, when `quantity=3` and `quantity_denominator` is unspecified, * the quantity ratio is `3` or `3/1`. * * @maps quantity_denominator @@ -87,9 +85,8 @@ public function setQuantityDenominator(?int $quantityDenominator): void /** * Unsets Quantity Denominator. * The whole or fractional quantity as the denominator. - * In the case of fractional quantity this field is the denominator and quantity is the numerator. - * When unspecified, the value is `1`. For example, when `quantity=3` and `quantity_donominator` is - * unspecified, + * With fractional quantity this field is the denominator and quantity is the numerator. + * The default value is `1`. For example, when `quantity=3` and `quantity_denominator` is unspecified, * the quantity ratio is `3` or `3/1`. */ public function unsetQuantityDenominator(): void diff --git a/src/Models/SearchEventsFilter.php b/src/Models/SearchEventsFilter.php new file mode 100644 index 00000000..f48cfb6e --- /dev/null +++ b/src/Models/SearchEventsFilter.php @@ -0,0 +1,200 @@ +eventTypes) == 0) { + return null; + } + return $this->eventTypes['value']; + } + + /** + * Sets Event Types. + * Filter events by event types. + * + * @maps event_types + * + * @param string[]|null $eventTypes + */ + public function setEventTypes(?array $eventTypes): void + { + $this->eventTypes['value'] = $eventTypes; + } + + /** + * Unsets Event Types. + * Filter events by event types. + */ + public function unsetEventTypes(): void + { + $this->eventTypes = []; + } + + /** + * Returns Merchant Ids. + * Filter events by merchant. + * + * @return string[]|null + */ + public function getMerchantIds(): ?array + { + if (count($this->merchantIds) == 0) { + return null; + } + return $this->merchantIds['value']; + } + + /** + * Sets Merchant Ids. + * Filter events by merchant. + * + * @maps merchant_ids + * + * @param string[]|null $merchantIds + */ + public function setMerchantIds(?array $merchantIds): void + { + $this->merchantIds['value'] = $merchantIds; + } + + /** + * Unsets Merchant Ids. + * Filter events by merchant. + */ + public function unsetMerchantIds(): void + { + $this->merchantIds = []; + } + + /** + * Returns Location Ids. + * Filter events by location. + * + * @return string[]|null + */ + public function getLocationIds(): ?array + { + if (count($this->locationIds) == 0) { + return null; + } + return $this->locationIds['value']; + } + + /** + * Sets Location Ids. + * Filter events by location. + * + * @maps location_ids + * + * @param string[]|null $locationIds + */ + public function setLocationIds(?array $locationIds): void + { + $this->locationIds['value'] = $locationIds; + } + + /** + * Unsets Location Ids. + * Filter events by location. + */ + public function unsetLocationIds(): void + { + $this->locationIds = []; + } + + /** + * Returns Created At. + * Represents a generic time range. The start and end values are + * represented in RFC 3339 format. Time ranges are customized to be + * inclusive or exclusive based on the needs of a particular endpoint. + * Refer to the relevant endpoint-specific documentation to determine + * how time ranges are handled. + */ + public function getCreatedAt(): ?TimeRange + { + return $this->createdAt; + } + + /** + * Sets Created At. + * Represents a generic time range. The start and end values are + * represented in RFC 3339 format. Time ranges are customized to be + * inclusive or exclusive based on the needs of a particular endpoint. + * Refer to the relevant endpoint-specific documentation to determine + * how time ranges are handled. + * + * @maps created_at + */ + public function setCreatedAt(?TimeRange $createdAt): void + { + $this->createdAt = $createdAt; + } + + /** + * Encode this object to JSON + * + * @param bool $asArrayWhenEmpty Whether to serialize this model as an array whenever no fields + * are set. (default: false) + * + * @return array|stdClass + */ + #[\ReturnTypeWillChange] // @phan-suppress-current-line PhanUndeclaredClassAttribute for (php < 8.1) + public function jsonSerialize(bool $asArrayWhenEmpty = false) + { + $json = []; + if (!empty($this->eventTypes)) { + $json['event_types'] = $this->eventTypes['value']; + } + if (!empty($this->merchantIds)) { + $json['merchant_ids'] = $this->merchantIds['value']; + } + if (!empty($this->locationIds)) { + $json['location_ids'] = $this->locationIds['value']; + } + if (isset($this->createdAt)) { + $json['created_at'] = $this->createdAt; + } + $json = array_filter($json, function ($val) { + return $val !== null; + }); + + return (!$asArrayWhenEmpty && empty($json)) ? new stdClass() : $json; + } +} diff --git a/src/Models/SearchEventsQuery.php b/src/Models/SearchEventsQuery.php new file mode 100644 index 00000000..98625c14 --- /dev/null +++ b/src/Models/SearchEventsQuery.php @@ -0,0 +1,88 @@ +filter; + } + + /** + * Sets Filter. + * Criteria to filter events by. + * + * @maps filter + */ + public function setFilter(?SearchEventsFilter $filter): void + { + $this->filter = $filter; + } + + /** + * Returns Sort. + * Criteria to sort events by. + */ + public function getSort(): ?SearchEventsSort + { + return $this->sort; + } + + /** + * Sets Sort. + * Criteria to sort events by. + * + * @maps sort + */ + public function setSort(?SearchEventsSort $sort): void + { + $this->sort = $sort; + } + + /** + * Encode this object to JSON + * + * @param bool $asArrayWhenEmpty Whether to serialize this model as an array whenever no fields + * are set. (default: false) + * + * @return array|stdClass + */ + #[\ReturnTypeWillChange] // @phan-suppress-current-line PhanUndeclaredClassAttribute for (php < 8.1) + public function jsonSerialize(bool $asArrayWhenEmpty = false) + { + $json = []; + if (isset($this->filter)) { + $json['filter'] = $this->filter; + } + if (isset($this->sort)) { + $json['sort'] = $this->sort; + } + $json = array_filter($json, function ($val) { + return $val !== null; + }); + + return (!$asArrayWhenEmpty && empty($json)) ? new stdClass() : $json; + } +} diff --git a/src/Models/SearchEventsRequest.php b/src/Models/SearchEventsRequest.php new file mode 100644 index 00000000..d5cd0863 --- /dev/null +++ b/src/Models/SearchEventsRequest.php @@ -0,0 +1,136 @@ +cursor; + } + + /** + * Sets Cursor. + * A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve + * the next set of events for your original query. + * + * For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api- + * patterns/pagination). + * + * @maps cursor + */ + public function setCursor(?string $cursor): void + { + $this->cursor = $cursor; + } + + /** + * Returns Limit. + * The maximum number of events to return in a single page. The response might contain fewer events. + * The default value is 100, which is also the maximum allowed value. + * + * For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api- + * patterns/pagination). + * + * Default: 100 + */ + public function getLimit(): ?int + { + return $this->limit; + } + + /** + * Sets Limit. + * The maximum number of events to return in a single page. The response might contain fewer events. + * The default value is 100, which is also the maximum allowed value. + * + * For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api- + * patterns/pagination). + * + * Default: 100 + * + * @maps limit + */ + public function setLimit(?int $limit): void + { + $this->limit = $limit; + } + + /** + * Returns Query. + * Contains query criteria for the search. + */ + public function getQuery(): ?SearchEventsQuery + { + return $this->query; + } + + /** + * Sets Query. + * Contains query criteria for the search. + * + * @maps query + */ + public function setQuery(?SearchEventsQuery $query): void + { + $this->query = $query; + } + + /** + * Encode this object to JSON + * + * @param bool $asArrayWhenEmpty Whether to serialize this model as an array whenever no fields + * are set. (default: false) + * + * @return array|stdClass + */ + #[\ReturnTypeWillChange] // @phan-suppress-current-line PhanUndeclaredClassAttribute for (php < 8.1) + public function jsonSerialize(bool $asArrayWhenEmpty = false) + { + $json = []; + if (isset($this->cursor)) { + $json['cursor'] = $this->cursor; + } + if (isset($this->limit)) { + $json['limit'] = $this->limit; + } + if (isset($this->query)) { + $json['query'] = $this->query; + } + $json = array_filter($json, function ($val) { + return $val !== null; + }); + + return (!$asArrayWhenEmpty && empty($json)) ? new stdClass() : $json; + } +} diff --git a/src/Models/SearchEventsResponse.php b/src/Models/SearchEventsResponse.php new file mode 100644 index 00000000..18e8c695 --- /dev/null +++ b/src/Models/SearchEventsResponse.php @@ -0,0 +1,168 @@ +errors; + } + + /** + * Sets Errors. + * Information on errors encountered during the request. + * + * @maps errors + * + * @param Error[]|null $errors + */ + public function setErrors(?array $errors): void + { + $this->errors = $errors; + } + + /** + * Returns Events. + * The list of [Event](entity:Event)s returned by the search. + * + * @return Event[]|null + */ + public function getEvents(): ?array + { + return $this->events; + } + + /** + * Sets Events. + * The list of [Event](entity:Event)s returned by the search. + * + * @maps events + * + * @param Event[]|null $events + */ + public function setEvents(?array $events): void + { + $this->events = $events; + } + + /** + * Returns Metadata. + * Contains the metadata of an event. For more information, see [Event](entity:Event). + * + * @return EventMetadata[]|null + */ + public function getMetadata(): ?array + { + return $this->metadata; + } + + /** + * Sets Metadata. + * Contains the metadata of an event. For more information, see [Event](entity:Event). + * + * @maps metadata + * + * @param EventMetadata[]|null $metadata + */ + public function setMetadata(?array $metadata): void + { + $this->metadata = $metadata; + } + + /** + * Returns Cursor. + * When a response is truncated, it includes a cursor that you can use in a subsequent request to fetch + * the next set of events. If empty, this is the final response. + * + * For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api- + * patterns/pagination). + */ + public function getCursor(): ?string + { + return $this->cursor; + } + + /** + * Sets Cursor. + * When a response is truncated, it includes a cursor that you can use in a subsequent request to fetch + * the next set of events. If empty, this is the final response. + * + * For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api- + * patterns/pagination). + * + * @maps cursor + */ + public function setCursor(?string $cursor): void + { + $this->cursor = $cursor; + } + + /** + * Encode this object to JSON + * + * @param bool $asArrayWhenEmpty Whether to serialize this model as an array whenever no fields + * are set. (default: false) + * + * @return array|stdClass + */ + #[\ReturnTypeWillChange] // @phan-suppress-current-line PhanUndeclaredClassAttribute for (php < 8.1) + public function jsonSerialize(bool $asArrayWhenEmpty = false) + { + $json = []; + if (isset($this->errors)) { + $json['errors'] = $this->errors; + } + if (isset($this->events)) { + $json['events'] = $this->events; + } + if (isset($this->metadata)) { + $json['metadata'] = $this->metadata; + } + if (isset($this->cursor)) { + $json['cursor'] = $this->cursor; + } + $json = array_filter($json, function ($val) { + return $val !== null; + }); + + return (!$asArrayWhenEmpty && empty($json)) ? new stdClass() : $json; + } +} diff --git a/src/Models/SearchEventsSort.php b/src/Models/SearchEventsSort.php new file mode 100644 index 00000000..d2036f2c --- /dev/null +++ b/src/Models/SearchEventsSort.php @@ -0,0 +1,88 @@ +field; + } + + /** + * Sets Field. + * Specifies the sort key for events returned from a search. + * + * @maps field + */ + public function setField(?string $field): void + { + $this->field = $field; + } + + /** + * Returns Order. + * The order (e.g., chronological or alphabetical) in which results from a request are returned. + */ + public function getOrder(): ?string + { + return $this->order; + } + + /** + * Sets Order. + * The order (e.g., chronological or alphabetical) in which results from a request are returned. + * + * @maps order + */ + public function setOrder(?string $order): void + { + $this->order = $order; + } + + /** + * Encode this object to JSON + * + * @param bool $asArrayWhenEmpty Whether to serialize this model as an array whenever no fields + * are set. (default: false) + * + * @return array|stdClass + */ + #[\ReturnTypeWillChange] // @phan-suppress-current-line PhanUndeclaredClassAttribute for (php < 8.1) + public function jsonSerialize(bool $asArrayWhenEmpty = false) + { + $json = []; + if (isset($this->field)) { + $json['field'] = $this->field; + } + if (isset($this->order)) { + $json['order'] = $this->order; + } + $json = array_filter($json, function ($val) { + return $val !== null; + }); + + return (!$asArrayWhenEmpty && empty($json)) ? new stdClass() : $json; + } +} diff --git a/src/Models/SearchEventsSortField.php b/src/Models/SearchEventsSortField.php new file mode 100644 index 00000000..165e9f85 --- /dev/null +++ b/src/Models/SearchEventsSortField.php @@ -0,0 +1,17 @@ +jsonHelper(ApiHelper::getJsonHelper()) ->apiCallback($this->config['httpCallback'] ?? null) ->userAgent( - 'Square-PHP-SDK/37.0.0.20240515 ({api-version}) {engine}/{engine-version} ({os-' . + 'Square-PHP-SDK/37.1.0.20240604 ({api-version}) {engine}/{engine-version} ({os-' . 'info}) {detail}' ) ->userAgentConfig( @@ -319,7 +322,7 @@ public function withConfiguration(array $config): self */ public function getSdkVersion(): string { - return '37.0.0.20240515'; + return '37.1.0.20240604'; } /** @@ -531,6 +534,17 @@ public function getEmployeesApi(): EmployeesApi return $this->employees; } + /** + * Returns Events Api + */ + public function getEventsApi(): EventsApi + { + if ($this->events == null) { + $this->events = new EventsApi($this->client); + } + return $this->events; + } + /** * Returns Gift Cards Api */