Merge pull request #135 from square/release/37.1.0.20240604

Generated PR for Release: 37.1.0.20240604

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",

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.<br><br>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());
+```
+

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<br>*Default*: `'2024-05-15'` |
+| `squareVersion` | `string` | Square Connect API versions<br>*Default*: `'2024-06-04'` |
 | `customUrl` | `string` | Sets the base URL requests are made to. Defaults to `https://connect.squareup.com`<br>*Default*: `'https://connect.squareup.com'` |
 | `environment` | `string` | The API environment. <br> **Default: `production`** |
 | `timeout` | `int` | Timeout for API calls in seconds.<br>*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 |

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"
+    }
+  ]
+}
+```
+

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"
+    }
+  ]
+}
+```
+

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)
 

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"
+}
+```
+

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 |

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"
+}
+```
+

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"
+    }
+  ]
+}
+```
+