Merge pull request #132 from square/release/38.1.0.20240604

Generated PR for Release: 38.1.0.20240604

doc/api/events.md

@@ -0,0 +1,134 @@
+# Events
+
+```ruby
+events_api = client.events
+```
+
+## Class Name
+
+`EventsApi`
+
+## Methods
+
+* [Search Events](../../doc/api/events.md#search-events)
+* [Disable Events](../../doc/api/events.md#disable-events)
+* [Enable Events](../../doc/api/events.md#enable-events)
+* [List Event Types](../../doc/api/events.md#list-event-types)
+
+
+# Search Events
+
+Search for Square API events that occur within a 28-day timeframe.
+
+```ruby
+def search_events(body:)
+```
+
+## Parameters
+
+| Parameter | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `body` | [`Search Events Request Hash`](../../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 `\ApiResponse` instance. The `data` property in this instance returns the response data which is of type [`Search Events Response Hash`](../../doc/models/search-events-response.md).
+
+## Example Usage
+
+```ruby
+body = {}
+
+
+result = events_api.search_events(body: body)
+
+if result.success?
+  puts result.data
+elsif result.error?
+  warn result.errors
+end
+```
+
+
+# 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.
+
+```ruby
+def disable_events
+```
+
+## Response Type
+
+This method returns a `\ApiResponse` instance. The `data` property in this instance returns the response data which is of type [`Disable Events Response Hash`](../../doc/models/disable-events-response.md).
+
+## Example Usage
+
+```ruby
+result = events_api.disable_events
+
+if result.success?
+  puts result.data
+elsif result.error?
+  warn result.errors
+end
+```
+
+
+# Enable Events
+
+Enables events to make them searchable. Only events that occur while in the enabled state are searchable.
+
+```ruby
+def enable_events
+```
+
+## Response Type
+
+This method returns a `\ApiResponse` instance. The `data` property in this instance returns the response data which is of type [`Enable Events Response Hash`](../../doc/models/enable-events-response.md).
+
+## Example Usage
+
+```ruby
+result = events_api.enable_events
+
+if result.success?
+  puts result.data
+elsif result.error?
+  warn result.errors
+end
+```
+
+
+# List Event Types
+
+Lists all event types that you can subscribe to as webhooks or query using the Events API.
+
+```ruby
+def list_event_types(api_version: nil)
+```
+
+## Parameters
+
+| Parameter | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `api_version` | `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 `\ApiResponse` instance. The `data` property in this instance returns the response data which is of type [`List Event Types Response Hash`](../../doc/models/list-event-types-response.md).
+
+## Example Usage
+
+```ruby
+result = events_api.list_event_types
+
+if result.success?
+  puts result.data
+elsif result.error?
+  warn result.errors
+end
+```
+

doc/client.md

@@ -5,7 +5,7 @@ The following parameters are configurable for the API Client:
 
 | Parameter | Type | Description |
 |  --- | --- | --- |
-| `square_version` | `String` | Square Connect API versions<br>*Default*: `'2024-05-15'` |
+| `square_version` | `String` | Square Connect API versions<br>*Default*: `'2024-06-04'` |
 | `custom_url` | `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`** |
 | `connection` | `Faraday::Connection` | The Faraday connection object passed by the SDK user for making requests |
@@ -25,7 +25,7 @@ The API client can be initialized as follows:
 
 ```ruby
 client = Square::Client.new(
-  square_version: '2024-05-15',
+  square_version: '2024-06-04',
   bearer_auth_credentials: BearerAuthCredentials.new(
     access_token: 'AccessToken'
   ),
@@ -94,6 +94,7 @@ The gateway for the SDK. This class acts as a factory for the Apis and also hold
 | devices | Gets DevicesApi |
 | disputes | Gets DisputesApi |
 | employees | Gets EmployeesApi |
+| events | Gets EventsApi |
 | gift_cards | Gets GiftCardsApi |
 | gift_card_activities | Gets GiftCardActivitiesApi |
 | inventory | 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/api/events.md#disable-events) endpoint.
+
+Note: if there are errors processing the request, the events field will not be
+present.
+
+## Structure
+
+`Disable Events Response`
+
+## Fields
+
+| Name | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `errors` | [`Array<Error Hash>`](../../doc/models/error.md) | Optional | Information on errors encountered during the request. |
+
+## 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/api/events.md#enable-events) endpoint.
+
+Note: if there are errors processing the request, the events field will not be
+present.
+
+## Structure
+
+`Enable Events Response`
+
+## Fields
+
+| Name | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `errors` | [`Array<Error Hash>`](../../doc/models/error.md) | Optional | Information on errors encountered during the request. |
+
+## 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 |
 |  --- | --- | --- | --- |
-| `type` | `String` | Optional | Name of the affected object’s type. |
-| `id` | `String` | Optional | ID of the affected object. |
-| `deleted` | `TrueClass \| FalseClass` | Optional | Is true if the affected object was deleted. Otherwise absent. |
-| `object` | `Hash` | Optional | An object containing fields and values relevant to the event. Is absent if affected object was deleted. |
+| `type` | `String` | Optional | The name of the affected object’s type. |
+| `id` | `String` | Optional | The ID of the affected object. |
+| `deleted` | `TrueClass \| FalseClass` | Optional | This is true if the affected object has been deleted; otherwise, it's absent. |
+| `object` | `Hash` | Optional | An object containing fields and values relevant to the event. It is absent if the affected object has been deleted. |
 
 ## 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
+
+`Event Metadata`
+
+## Fields
+
+| Name | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `event_id` | `String` | Optional | A unique ID for the event. |
+| `api_version` | `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. |
+
+## Example (as JSON)
+
+```json
+{
+  "event_id": "event_id0",
+  "api_version": "api_version6"
+}
+```
+

doc/models/event.md

@@ -10,7 +10,7 @@
 | Name | Type | Tags | Description |
 |  --- | --- | --- | --- |
 | `merchant_id` | `String` | Optional | The ID of the target merchant associated with the event. |
-| `location_id` | `String` | Optional | The ID of the location associated with the event. |
+| `location_id` | `String` | Optional | The ID of the target location associated with the event. |
 | `type` | `String` | Optional | The type of event this represents. |
 | `event_id` | `String` | Optional | A unique ID for the event. |
 | `created_at` | `String` | Optional | Timestamp of when the event was created, in RFC 3339 format. |

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
+
+`List Event Types Request`
+
+## Fields
+
+| Name | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `api_version` | `String` | Optional | The API version for which to list event types. Setting this field overrides the default version used by the application. |
+
+## 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/api/events.md#list-event-types) endpoint.
+
+Note: if there are errors processing the request, the event types field will not be
+present.
+
+## Structure
+
+`List Event Types Response`
+
+## Fields
+
+| Name | Type | Tags | Description |
+|  --- | --- | --- | --- |
+| `errors` | [`Array<Error Hash>`](../../doc/models/error.md) | Optional | Information on errors encountered during the request. |
+| `event_types` | `Array<String>` | Optional | The list of event types. |
+| `metadata` | [`Array<Event Type Metadata Hash>`](../../doc/models/event-type-metadata.md) | Optional | Contains the metadata of an event type. For more information, see [EventTypeMetadata](entity:EventTypeMetadata). |
+
+## 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"
+    }
+  ]
+}
+```
+

doc/models/quantity-ratio.md

@@ -12,7 +12,7 @@ A whole number or unreduced fractional ratio.
 | Name | Type | Tags | Description |
 |  --- | --- | --- | --- |
 | `quantity` | `Integer` | Optional | The whole or fractional quantity as the numerator. |
-| `quantity_denominator` | `Integer` | Optional | The whole or fractional quantity as the denominator.<br>In the case of fractional quantity this field is the denominator and quantity is the numerator.<br>When unspecified, the value is `1`. For example, when `quantity=3` and `quantity_donominator` is unspecified,<br>the quantity ratio is `3` or `3/1`. |
+| `quantity_denominator` | `Integer` | Optional | The whole or fractional quantity as the denominator.<br>With fractional quantity this field is the denominator and quantity is the numerator.<br>The default value is `1`. For example, when `quantity=3` and `quantity_denominator` is unspecified,<br>the quantity ratio is `3` or `3/1`. |
 
 ## Example (as JSON)