From 8292eef5404aebef90d844bd845cb41f7452dcfc Mon Sep 17 00:00:00 2001 From: autobot Date: Mon, 3 Jun 2024 17:05:52 +0000 Subject: [PATCH] Generated PR for Release: 37.1.0 --- doc/api/events.md | 169 ++++++++++++++++++++++++ doc/client.md | 7 +- doc/models/disable-events-response.md | 40 ++++++ doc/models/enable-events-response.md | 34 +++++ doc/models/event-data.md | 8 +- doc/models/event-metadata.md | 25 ++++ doc/models/event.md | 2 +- doc/models/list-event-types-request.md | 23 ++++ doc/models/list-event-types-response.md | 52 ++++++++ doc/models/quantity-ratio.md | 2 +- doc/models/search-events-filter.md | 43 ++++++ doc/models/search-events-query.md | 44 ++++++ doc/models/search-events-request.md | 49 +++++++ doc/models/search-events-response.md | 85 ++++++++++++ doc/models/search-events-sort-field.md | 15 +++ doc/models/search-events-sort.md | 25 ++++ package.json | 2 +- src/api/eventsApi.ts | 94 +++++++++++++ src/client.ts | 7 +- src/defaultConfiguration.ts | 2 +- src/index.ts | 11 ++ src/models/disableEventsResponse.ts | 17 +++ src/models/enableEventsResponse.ts | 17 +++ src/models/event.ts | 2 +- src/models/eventData.ts | 8 +- src/models/eventMetadata.ts | 14 ++ src/models/listEventTypesRequest.ts | 11 ++ src/models/listEventTypesResponse.ts | 29 ++++ src/models/quantityRatio.ts | 4 +- src/models/searchEventsFilter.ts | 35 +++++ src/models/searchEventsQuery.ts | 19 +++ src/models/searchEventsRequest.ts | 25 ++++ src/models/searchEventsResponse.ts | 31 +++++ src/models/searchEventsSort.ts | 14 ++ 34 files changed, 945 insertions(+), 20 deletions(-) create mode 100644 doc/api/events.md create mode 100644 doc/models/disable-events-response.md create mode 100644 doc/models/enable-events-response.md create mode 100644 doc/models/event-metadata.md create mode 100644 doc/models/list-event-types-request.md create mode 100644 doc/models/list-event-types-response.md create mode 100644 doc/models/search-events-filter.md create mode 100644 doc/models/search-events-query.md create mode 100644 doc/models/search-events-request.md create mode 100644 doc/models/search-events-response.md create mode 100644 doc/models/search-events-sort-field.md create mode 100644 doc/models/search-events-sort.md create mode 100644 src/api/eventsApi.ts create mode 100644 src/models/disableEventsResponse.ts create mode 100644 src/models/enableEventsResponse.ts create mode 100644 src/models/eventMetadata.ts create mode 100644 src/models/listEventTypesRequest.ts create mode 100644 src/models/listEventTypesResponse.ts create mode 100644 src/models/searchEventsFilter.ts create mode 100644 src/models/searchEventsQuery.ts create mode 100644 src/models/searchEventsRequest.ts create mode 100644 src/models/searchEventsResponse.ts create mode 100644 src/models/searchEventsSort.ts diff --git a/doc/api/events.md b/doc/api/events.md new file mode 100644 index 00000000..a644fb39 --- /dev/null +++ b/doc/api/events.md @@ -0,0 +1,169 @@ +# Events + +```ts +const eventsApi = client.eventsApi; +``` + +## 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. + +```ts +async searchEvents( + body: SearchEventsRequest, + requestOptions?: RequestOptions +): Promise> +``` + +## 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. | +| `requestOptions` | `RequestOptions \| undefined` | Optional | Pass additional request options. | + +## Response Type + +[`SearchEventsResponse`](../../doc/models/search-events-response.md) + +## Example Usage + +```ts +const body: SearchEventsRequest = {}; + +try { + const { result, ...httpResponse } = await eventsApi.searchEvents(body); + // Get more response info... + // const { statusCode, headers } = httpResponse; +} catch (error) { + if (error instanceof ApiError) { + const errors = error.result; + // const { statusCode, headers } = error; + } +} +``` + + +# 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. + +```ts +async disableEvents( + requestOptions?: RequestOptions +): Promise> +``` + +## Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `requestOptions` | `RequestOptions \| undefined` | Optional | Pass additional request options. | + +## Response Type + +[`DisableEventsResponse`](../../doc/models/disable-events-response.md) + +## Example Usage + +```ts +try { + const { result, ...httpResponse } = await eventsApi.disableEvents(); + // Get more response info... + // const { statusCode, headers } = httpResponse; +} catch (error) { + if (error instanceof ApiError) { + const errors = error.result; + // const { statusCode, headers } = error; + } +} +``` + + +# Enable Events + +Enables events to make them searchable. Only events that occur while in the enabled state are searchable. + +```ts +async enableEvents( + requestOptions?: RequestOptions +): Promise> +``` + +## Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `requestOptions` | `RequestOptions \| undefined` | Optional | Pass additional request options. | + +## Response Type + +[`EnableEventsResponse`](../../doc/models/enable-events-response.md) + +## Example Usage + +```ts +try { + const { result, ...httpResponse } = await eventsApi.enableEvents(); + // Get more response info... + // const { statusCode, headers } = httpResponse; +} catch (error) { + if (error instanceof ApiError) { + const errors = error.result; + // const { statusCode, headers } = error; + } +} +``` + + +# List Event Types + +Lists all event types that you can subscribe to as webhooks or query using the Events API. + +```ts +async listEventTypes( + apiVersion?: string, + requestOptions?: RequestOptions +): Promise> +``` + +## Parameters + +| Parameter | Type | Tags | Description | +| --- | --- | --- | --- | +| `apiVersion` | `string \| undefined` | Query, Optional | The API version for which to list event types. Setting this field overrides the default version used by the application. | +| `requestOptions` | `RequestOptions \| undefined` | Optional | Pass additional request options. | + +## Response Type + +[`ListEventTypesResponse`](../../doc/models/list-event-types-response.md) + +## Example Usage + +```ts +try { + const { result, ...httpResponse } = await eventsApi.listEventTypes(); + // Get more response info... + // const { statusCode, headers } = httpResponse; +} catch (error) { + if (error instanceof ApiError) { + const errors = error.result; + // const { statusCode, headers } = error; + } +} +``` + diff --git a/doc/client.md b/doc/client.md index 6a9af3e9..7f649ea9 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`** | | `additionalHeaders` | `Readonly>` | Additional headers to add to each API call
*Default*: `{}` | @@ -43,7 +43,7 @@ const client = new Client({ bearerAuthCredentials: { accessToken: 'AccessToken' }, - squareVersion: '2024-05-15', + squareVersion: '2024-06-04', timeout: 60000, additionalHeaders: {}, userAgentDetail: '', @@ -60,7 +60,7 @@ const client = new Client({ bearerAuthCredentials: { accessToken: 'AccessToken' }, - squareVersion: '2024-05-15', + squareVersion: '2024-06-04', timeout: 60000, additionalHeaders: {}, userAgentDetail: '', @@ -105,6 +105,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 | | giftCards | Gets GiftCardsApi | | giftCardActivities | Gets GiftCardActivitiesApi | | inventory | Gets InventoryApi | diff --git a/doc/models/disable-events-response.md b/doc/models/disable-events-response.md new file mode 100644 index 00000000..5146759c --- /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/api/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 | +| --- | --- | --- | --- | +| `errors` | [`Error[] \| undefined`](../../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" + } + ] +} +``` + diff --git a/doc/models/enable-events-response.md b/doc/models/enable-events-response.md new file mode 100644 index 00000000..1694929e --- /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/api/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 | +| --- | --- | --- | --- | +| `errors` | [`Error[] \| undefined`](../../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" + } + ] +} +``` + diff --git a/doc/models/event-data.md b/doc/models/event-data.md index 77e413bf..ac00fcfe 100644 --- a/doc/models/event-data.md +++ b/doc/models/event-data.md @@ -9,10 +9,10 @@ | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `type` | `string \| null \| undefined` | Optional | Name of the affected object’s type. | -| `id` | `string \| undefined` | Optional | ID of the affected object. | -| `deleted` | `boolean \| null \| undefined` | Optional | Is true if the affected object was deleted. Otherwise absent. | -| `object` | `Record \| null \| undefined` | Optional | An object containing fields and values relevant to the event. Is absent if affected object was deleted. | +| `type` | `string \| null \| undefined` | Optional | The name of the affected object’s type. | +| `id` | `string \| undefined` | Optional | The ID of the affected object. | +| `deleted` | `boolean \| null \| undefined` | Optional | This is true if the affected object has been deleted; otherwise, it's absent. | +| `object` | `Record \| null \| undefined` | Optional | An object containing fields and values relevant to the event. It is absent if the affected object has been deleted. | ## Example (as JSON) diff --git a/doc/models/event-metadata.md b/doc/models/event-metadata.md new file mode 100644 index 00000000..9f3be7fa --- /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 | +| --- | --- | --- | --- | +| `eventId` | `string \| null \| undefined` | Optional | A unique ID for the event. | +| `apiVersion` | `string \| null \| undefined` | 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" +} +``` + diff --git a/doc/models/event.md b/doc/models/event.md index cc309412..ef55c60f 100644 --- a/doc/models/event.md +++ b/doc/models/event.md @@ -10,7 +10,7 @@ | Name | Type | Tags | Description | | --- | --- | --- | --- | | `merchantId` | `string \| null \| undefined` | Optional | The ID of the target merchant associated with the event. | -| `locationId` | `string \| null \| undefined` | Optional | The ID of the location associated with the event. | +| `locationId` | `string \| null \| undefined` | Optional | The ID of the target location associated with the event. | | `type` | `string \| null \| undefined` | Optional | The type of event this represents. | | `eventId` | `string \| null \| undefined` | Optional | A unique ID for the event. | | `createdAt` | `string \| undefined` | Optional | Timestamp of when the event was created, in RFC 3339 format. | diff --git a/doc/models/list-event-types-request.md b/doc/models/list-event-types-request.md new file mode 100644 index 00000000..435dd32a --- /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 | +| --- | --- | --- | --- | +| `apiVersion` | `string \| null \| undefined` | 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" +} +``` + diff --git a/doc/models/list-event-types-response.md b/doc/models/list-event-types-response.md new file mode 100644 index 00000000..fa4f77af --- /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/api/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 | +| --- | --- | --- | --- | +| `errors` | [`Error[] \| undefined`](../../doc/models/error.md) | Optional | Information on errors encountered during the request. | +| `eventTypes` | `string[] \| undefined` | Optional | The list of event types. | +| `metadata` | [`EventTypeMetadata[] \| undefined`](../../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" + } + ] +} +``` + diff --git a/doc/models/quantity-ratio.md b/doc/models/quantity-ratio.md index 4b856a05..47f21440 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 | | --- | --- | --- | --- | | `quantity` | `number \| null \| undefined` | Optional | The whole or fractional quantity as the numerator. | -| `quantityDenominator` | `number \| null \| undefined` | 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`. | +| `quantityDenominator` | `number \| null \| undefined` | 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`. | ## 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..a0138321 --- /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 | +| --- | --- | --- | --- | +| `eventTypes` | `string[] \| null \| undefined` | Optional | Filter events by event types. | +| `merchantIds` | `string[] \| null \| undefined` | Optional | Filter events by merchant. | +| `locationIds` | `string[] \| null \| undefined` | Optional | Filter events by location. | +| `createdAt` | [`TimeRange \| undefined`](../../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. | + +## 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..a37f2ff0 --- /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 | +| --- | --- | --- | --- | +| `filter` | [`SearchEventsFilter \| undefined`](../../doc/models/search-events-filter.md) | Optional | Criteria to filter events by. | +| `sort` | [`SearchEventsSort \| undefined`](../../doc/models/search-events-sort.md) | Optional | Criteria to sort events by. | + +## 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..d4f2d71a --- /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 | +| --- | --- | --- | --- | +| `cursor` | `string \| undefined` | 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` | +| `limit` | `number \| undefined` | 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` | +| `query` | [`SearchEventsQuery \| undefined`](../../doc/models/search-events-query.md) | Optional | Contains query criteria for the search. | + +## 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..19df9c61 --- /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/api/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 | +| --- | --- | --- | --- | +| `errors` | [`Error[] \| undefined`](../../doc/models/error.md) | Optional | Information on errors encountered during the request. | +| `events` | [`Event[] \| undefined`](../../doc/models/event.md) | Optional | The list of [Event](entity:Event)s returned by the search. | +| `metadata` | [`EventMetadata[] \| undefined`](../../doc/models/event-metadata.md) | Optional | Contains the metadata of an event. For more information, see [Event](entity:Event). | +| `cursor` | `string \| undefined` | 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). | + +## 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..6394e9c8 --- /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 | +| --- | --- | --- | --- | +| `field` | [`string \| undefined`](../../doc/models/search-events-sort-field.md) | Optional | Specifies the sort key for events returned from a search. | +| `order` | [`string \| undefined`](../../doc/models/sort-order.md) | Optional | The order (e.g., chronological or alphabetical) in which results from a request are returned. | + +## Example (as JSON) + +```json +{ + "field": "DEFAULT", + "order": "DESC" +} +``` + diff --git a/package.json b/package.json index 87c7206b..1327b10f 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,5 @@ { - "version": "37.0.0", + "version": "37.1.0", "license": "MIT", "sideEffects": false, "main": "dist/cjs/index.js", diff --git a/src/api/eventsApi.ts b/src/api/eventsApi.ts new file mode 100644 index 00000000..a1688622 --- /dev/null +++ b/src/api/eventsApi.ts @@ -0,0 +1,94 @@ +import { ApiResponse, RequestOptions } from '../core'; +import { + DisableEventsResponse, + disableEventsResponseSchema, +} from '../models/disableEventsResponse'; +import { + EnableEventsResponse, + enableEventsResponseSchema, +} from '../models/enableEventsResponse'; +import { + ListEventTypesResponse, + listEventTypesResponseSchema, +} from '../models/listEventTypesResponse'; +import { + SearchEventsRequest, + searchEventsRequestSchema, +} from '../models/searchEventsRequest'; +import { + SearchEventsResponse, + searchEventsResponseSchema, +} from '../models/searchEventsResponse'; +import { optional, string } from '../schema'; +import { BaseApi } from './baseApi'; + +export class EventsApi extends BaseApi { + /** + * Search for Square API events that occur within a 28-day timeframe. + * + * @param body An object containing the fields to POST for the request. See + * the corresponding object definition for field details. + * @return Response from the API call + */ + async searchEvents( + body: SearchEventsRequest, + requestOptions?: RequestOptions + ): Promise> { + const req = this.createRequest('POST', '/v2/events'); + const mapped = req.prepareArgs({ body: [body, searchEventsRequestSchema] }); + req.header('Content-Type', 'application/json'); + req.json(mapped.body); + req.authenticate([{ global: true }]); + return req.callAsJson(searchEventsResponseSchema, requestOptions); + } + + /** + * 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 Response from the API call + */ + async disableEvents( + requestOptions?: RequestOptions + ): Promise> { + const req = this.createRequest('PUT', '/v2/events/disable'); + req.authenticate([{ global: true }]); + return req.callAsJson(disableEventsResponseSchema, requestOptions); + } + + /** + * Enables events to make them searchable. Only events that occur while in the enabled state are + * searchable. + * + * @return Response from the API call + */ + async enableEvents( + requestOptions?: RequestOptions + ): Promise> { + const req = this.createRequest('PUT', '/v2/events/enable'); + req.authenticate([{ global: true }]); + return req.callAsJson(enableEventsResponseSchema, requestOptions); + } + + /** + * Lists all event types that you can subscribe to as webhooks or query using the Events API. + * + * @param apiVersion The API version for which to list event types. Setting this field overrides the + * default version used by the application. + * @return Response from the API call + */ + async listEventTypes( + apiVersion?: string, + requestOptions?: RequestOptions + ): Promise> { + const req = this.createRequest('GET', '/v2/events/types'); + const mapped = req.prepareArgs({ + apiVersion: [apiVersion, optional(string())], + }); + req.query('api_version', mapped.apiVersion); + req.authenticate([{ global: true }]); + return req.callAsJson(listEventTypesResponseSchema, requestOptions); + } +} diff --git a/src/client.ts b/src/client.ts index 0cff969b..a97c8c7a 100644 --- a/src/client.ts +++ b/src/client.ts @@ -13,6 +13,7 @@ import { CustomerSegmentsApi } from './api/customerSegmentsApi'; import { DevicesApi } from './api/devicesApi'; import { DisputesApi } from './api/disputesApi'; import { EmployeesApi } from './api/employeesApi'; +import { EventsApi } from './api/eventsApi'; import { GiftCardActivitiesApi } from './api/giftCardActivitiesApi'; import { GiftCardsApi } from './api/giftCardsApi'; import { InventoryApi } from './api/inventoryApi'; @@ -67,7 +68,7 @@ import { import { HttpClient } from './clientAdapter'; /** Current SDK version */ -export const SDK_VERSION = '37.0.0'; +export const SDK_VERSION = '37.1.0'; export class Client implements ClientInterface { private _config: Readonly; private _timeout: number; @@ -90,6 +91,7 @@ export class Client implements ClientInterface { public readonly devicesApi: DevicesApi; public readonly disputesApi: DisputesApi; public readonly employeesApi: EmployeesApi; + public readonly eventsApi: EventsApi; public readonly giftCardActivitiesApi: GiftCardActivitiesApi; public readonly giftCardsApi: GiftCardsApi; public readonly inventoryApi: InventoryApi; @@ -138,7 +140,7 @@ export class Client implements ClientInterface { } this._userAgent = updateUserAgent( - 'Square-TypeScript-SDK/37.0.0 ({api-version}) {engine}/{engine-version} ({os-info}) {detail}', + 'Square-TypeScript-SDK/37.1.0 ({api-version}) {engine}/{engine-version} ({os-info}) {detail}', this._config.squareVersion, this._config.userAgentDetail ); @@ -176,6 +178,7 @@ export class Client implements ClientInterface { this.devicesApi = new DevicesApi(this); this.disputesApi = new DisputesApi(this); this.employeesApi = new EmployeesApi(this); + this.eventsApi = new EventsApi(this); this.giftCardActivitiesApi = new GiftCardActivitiesApi(this); this.giftCardsApi = new GiftCardsApi(this); this.inventoryApi = new InventoryApi(this); diff --git a/src/defaultConfiguration.ts b/src/defaultConfiguration.ts index 7a1a0f22..b9d2c1c8 100644 --- a/src/defaultConfiguration.ts +++ b/src/defaultConfiguration.ts @@ -4,7 +4,7 @@ import { RetryConfiguration } from './core'; /** Default values for the configuration parameters of the client. */ export const DEFAULT_CONFIGURATION: Configuration = { timeout: 60000, - squareVersion: '2024-05-15', + squareVersion: '2024-06-04', additionalHeaders: {}, userAgentDetail: '', environment: Environment.Production, diff --git a/src/index.ts b/src/index.ts index d7c592ae..c078a074 100644 --- a/src/index.ts +++ b/src/index.ts @@ -25,6 +25,7 @@ export * from './api/customerSegmentsApi'; export * from './api/devicesApi'; export * from './api/disputesApi'; export * from './api/employeesApi'; +export * from './api/eventsApi'; export * from './api/giftCardActivitiesApi'; export * from './api/giftCardsApi'; export * from './api/inventoryApi'; @@ -402,6 +403,7 @@ export type { DeviceMetadata } from './models/deviceMetadata'; export type { DeviceStatus } from './models/deviceStatus'; export type { DigitalWalletDetails } from './models/digitalWalletDetails'; export type { DisableCardResponse } from './models/disableCardResponse'; +export type { DisableEventsResponse } from './models/disableEventsResponse'; export type { DismissTerminalActionResponse } from './models/dismissTerminalActionResponse'; export type { DismissTerminalCheckoutResponse } from './models/dismissTerminalCheckoutResponse'; export type { DismissTerminalRefundResponse } from './models/dismissTerminalRefundResponse'; @@ -411,9 +413,11 @@ export type { DisputeEvidence } from './models/disputeEvidence'; export type { DisputeEvidenceFile } from './models/disputeEvidenceFile'; export type { Employee } from './models/employee'; export type { EmployeeWage } from './models/employeeWage'; +export type { EnableEventsResponse } from './models/enableEventsResponse'; export type { Error } from './models/error'; export type { Event } from './models/event'; export type { EventData } from './models/eventData'; +export type { EventMetadata } from './models/eventMetadata'; export type { EventTypeMetadata } from './models/eventTypeMetadata'; export type { ExternalPaymentDetails } from './models/externalPaymentDetails'; export type { FilterValue } from './models/filterValue'; @@ -518,6 +522,8 @@ export type { ListEmployeesRequest } from './models/listEmployeesRequest'; export type { ListEmployeesResponse } from './models/listEmployeesResponse'; export type { ListEmployeeWagesRequest } from './models/listEmployeeWagesRequest'; export type { ListEmployeeWagesResponse } from './models/listEmployeeWagesResponse'; +export type { ListEventTypesRequest } from './models/listEventTypesRequest'; +export type { ListEventTypesResponse } from './models/listEventTypesResponse'; export type { ListGiftCardActivitiesRequest } from './models/listGiftCardActivitiesRequest'; export type { ListGiftCardActivitiesResponse } from './models/listGiftCardActivitiesResponse'; export type { ListGiftCardsRequest } from './models/listGiftCardsRequest'; @@ -792,6 +798,11 @@ export type { SearchCatalogObjectsRequest } from './models/searchCatalogObjectsR export type { SearchCatalogObjectsResponse } from './models/searchCatalogObjectsResponse'; export type { SearchCustomersRequest } from './models/searchCustomersRequest'; export type { SearchCustomersResponse } from './models/searchCustomersResponse'; +export type { SearchEventsFilter } from './models/searchEventsFilter'; +export type { SearchEventsQuery } from './models/searchEventsQuery'; +export type { SearchEventsRequest } from './models/searchEventsRequest'; +export type { SearchEventsResponse } from './models/searchEventsResponse'; +export type { SearchEventsSort } from './models/searchEventsSort'; export type { SearchInvoicesRequest } from './models/searchInvoicesRequest'; export type { SearchInvoicesResponse } from './models/searchInvoicesResponse'; export type { SearchLoyaltyAccountsRequest } from './models/searchLoyaltyAccountsRequest'; diff --git a/src/models/disableEventsResponse.ts b/src/models/disableEventsResponse.ts new file mode 100644 index 00000000..66893236 --- /dev/null +++ b/src/models/disableEventsResponse.ts @@ -0,0 +1,17 @@ +import { array, lazy, object, optional, Schema } from '../schema'; +import { Error, errorSchema } from './error'; + +/** + * Defines the fields that are included in the response body of + * a request to the [DisableEvents]($e/Events/DisableEvents) endpoint. + * Note: if there are errors processing the request, the events field will not be + * present. + */ +export interface DisableEventsResponse { + /** Information on errors encountered during the request. */ + errors?: Error[]; +} + +export const disableEventsResponseSchema: Schema = object( + { errors: ['errors', optional(array(lazy(() => errorSchema)))] } +); diff --git a/src/models/enableEventsResponse.ts b/src/models/enableEventsResponse.ts new file mode 100644 index 00000000..782d3ad4 --- /dev/null +++ b/src/models/enableEventsResponse.ts @@ -0,0 +1,17 @@ +import { array, lazy, object, optional, Schema } from '../schema'; +import { Error, errorSchema } from './error'; + +/** + * Defines the fields that are included in the response body of + * a request to the [EnableEvents]($e/Events/EnableEvents) endpoint. + * Note: if there are errors processing the request, the events field will not be + * present. + */ +export interface EnableEventsResponse { + /** Information on errors encountered during the request. */ + errors?: Error[]; +} + +export const enableEventsResponseSchema: Schema = object({ + errors: ['errors', optional(array(lazy(() => errorSchema)))], +}); diff --git a/src/models/event.ts b/src/models/event.ts index b1b3b3bc..03657e60 100644 --- a/src/models/event.ts +++ b/src/models/event.ts @@ -4,7 +4,7 @@ import { EventData, eventDataSchema } from './eventData'; export interface Event { /** The ID of the target merchant associated with the event. */ merchantId?: string | null; - /** The ID of the location associated with the event. */ + /** The ID of the target location associated with the event. */ locationId?: string | null; /** The type of event this represents. */ type?: string | null; diff --git a/src/models/eventData.ts b/src/models/eventData.ts index 98f31f07..50b772b1 100644 --- a/src/models/eventData.ts +++ b/src/models/eventData.ts @@ -10,13 +10,13 @@ import { } from '../schema'; export interface EventData { - /** Name of the affected object’s type. */ + /** The name of the affected object’s type. */ type?: string | null; - /** ID of the affected object. */ + /** The ID of the affected object. */ id?: string; - /** Is true if the affected object was deleted. Otherwise absent. */ + /** This is true if the affected object has been deleted; otherwise, it's absent. */ deleted?: boolean | null; - /** 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. */ object?: Record | null; } diff --git a/src/models/eventMetadata.ts b/src/models/eventMetadata.ts new file mode 100644 index 00000000..e1d2beb0 --- /dev/null +++ b/src/models/eventMetadata.ts @@ -0,0 +1,14 @@ +import { nullable, object, optional, Schema, string } from '../schema'; + +/** Contains metadata about a particular [Event]($m/Event). */ +export interface EventMetadata { + /** A unique ID for the event. */ + eventId?: string | null; + /** 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. */ + apiVersion?: string | null; +} + +export const eventMetadataSchema: Schema = object({ + eventId: ['event_id', optional(nullable(string()))], + apiVersion: ['api_version', optional(nullable(string()))], +}); diff --git a/src/models/listEventTypesRequest.ts b/src/models/listEventTypesRequest.ts new file mode 100644 index 00000000..fa2fc89a --- /dev/null +++ b/src/models/listEventTypesRequest.ts @@ -0,0 +1,11 @@ +import { nullable, object, optional, Schema, string } from '../schema'; + +/** Lists all event types that can be subscribed to. */ +export interface ListEventTypesRequest { + /** The API version for which to list event types. Setting this field overrides the default version used by the application. */ + apiVersion?: string | null; +} + +export const listEventTypesRequestSchema: Schema = object( + { apiVersion: ['api_version', optional(nullable(string()))] } +); diff --git a/src/models/listEventTypesResponse.ts b/src/models/listEventTypesResponse.ts new file mode 100644 index 00000000..c15409dc --- /dev/null +++ b/src/models/listEventTypesResponse.ts @@ -0,0 +1,29 @@ +import { array, lazy, object, optional, Schema, string } from '../schema'; +import { Error, errorSchema } from './error'; +import { EventTypeMetadata, eventTypeMetadataSchema } from './eventTypeMetadata'; + +/** + * Defines the fields that are included in the response body of + * a request to the [ListEventTypes]($e/Events/ListEventTypes) endpoint. + * Note: if there are errors processing the request, the event types field will not be + * present. + */ +export interface ListEventTypesResponse { + /** Information on errors encountered during the request. */ + errors?: Error[]; + /** The list of event types. */ + eventTypes?: string[]; + /** Contains the metadata of an event type. For more information, see [EventTypeMetadata](entity:EventTypeMetadata). */ + metadata?: EventTypeMetadata[]; +} + +export const listEventTypesResponseSchema: Schema = object( + { + errors: ['errors', optional(array(lazy(() => errorSchema)))], + eventTypes: ['event_types', optional(array(string()))], + metadata: [ + 'metadata', + optional(array(lazy(() => eventTypeMetadataSchema))), + ], + } +); diff --git a/src/models/quantityRatio.ts b/src/models/quantityRatio.ts index 61724e28..28021f77 100644 --- a/src/models/quantityRatio.ts +++ b/src/models/quantityRatio.ts @@ -6,8 +6,8 @@ export interface QuantityRatio { quantity?: number | null; /** * 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`. */ quantityDenominator?: number | null; diff --git a/src/models/searchEventsFilter.ts b/src/models/searchEventsFilter.ts new file mode 100644 index 00000000..758a7066 --- /dev/null +++ b/src/models/searchEventsFilter.ts @@ -0,0 +1,35 @@ +import { + array, + lazy, + nullable, + object, + optional, + Schema, + string, +} from '../schema'; +import { TimeRange, timeRangeSchema } from './timeRange'; + +/** Criteria to filter events by. */ +export interface SearchEventsFilter { + /** Filter events by event types. */ + eventTypes?: string[] | null; + /** Filter events by merchant. */ + merchantIds?: string[] | null; + /** Filter events by location. */ + locationIds?: string[] | null; + /** + * 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. + */ + createdAt?: TimeRange; +} + +export const searchEventsFilterSchema: Schema = object({ + eventTypes: ['event_types', optional(nullable(array(string())))], + merchantIds: ['merchant_ids', optional(nullable(array(string())))], + locationIds: ['location_ids', optional(nullable(array(string())))], + createdAt: ['created_at', optional(lazy(() => timeRangeSchema))], +}); diff --git a/src/models/searchEventsQuery.ts b/src/models/searchEventsQuery.ts new file mode 100644 index 00000000..30c12ae1 --- /dev/null +++ b/src/models/searchEventsQuery.ts @@ -0,0 +1,19 @@ +import { lazy, object, optional, Schema } from '../schema'; +import { + SearchEventsFilter, + searchEventsFilterSchema, +} from './searchEventsFilter'; +import { SearchEventsSort, searchEventsSortSchema } from './searchEventsSort'; + +/** Contains query criteria for the search. */ +export interface SearchEventsQuery { + /** Criteria to filter events by. */ + filter?: SearchEventsFilter; + /** Criteria to sort events by. */ + sort?: SearchEventsSort; +} + +export const searchEventsQuerySchema: Schema = object({ + filter: ['filter', optional(lazy(() => searchEventsFilterSchema))], + sort: ['sort', optional(lazy(() => searchEventsSortSchema))], +}); diff --git a/src/models/searchEventsRequest.ts b/src/models/searchEventsRequest.ts new file mode 100644 index 00000000..7657461f --- /dev/null +++ b/src/models/searchEventsRequest.ts @@ -0,0 +1,25 @@ +import { lazy, number, object, optional, Schema, string } from '../schema'; +import { SearchEventsQuery, searchEventsQuerySchema } from './searchEventsQuery'; + +/** Searches [Event]($m/Event)s for your application. */ +export interface SearchEventsRequest { + /** + * 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). + */ + cursor?: string; + /** + * 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 + */ + limit?: number; + /** Contains query criteria for the search. */ + query?: SearchEventsQuery; +} + +export const searchEventsRequestSchema: Schema = object({ + cursor: ['cursor', optional(string())], + limit: ['limit', optional(number())], + query: ['query', optional(lazy(() => searchEventsQuerySchema))], +}); diff --git a/src/models/searchEventsResponse.ts b/src/models/searchEventsResponse.ts new file mode 100644 index 00000000..1afed649 --- /dev/null +++ b/src/models/searchEventsResponse.ts @@ -0,0 +1,31 @@ +import { array, lazy, object, optional, Schema, string } from '../schema'; +import { Error, errorSchema } from './error'; +import { Event, eventSchema } from './event'; +import { EventMetadata, eventMetadataSchema } from './eventMetadata'; + +/** + * Defines the fields that are included in the response body of + * a request to the [SearchEvents]($e/Events/SearchEvents) endpoint. + * Note: if there are errors processing the request, the events field will not be + * present. + */ +export interface SearchEventsResponse { + /** Information on errors encountered during the request. */ + errors?: Error[]; + /** The list of [Event](entity:Event)s returned by the search. */ + events?: Event[]; + /** Contains the metadata of an event. For more information, see [Event](entity:Event). */ + metadata?: EventMetadata[]; + /** + * 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). + */ + cursor?: string; +} + +export const searchEventsResponseSchema: Schema = object({ + errors: ['errors', optional(array(lazy(() => errorSchema)))], + events: ['events', optional(array(lazy(() => eventSchema)))], + metadata: ['metadata', optional(array(lazy(() => eventMetadataSchema)))], + cursor: ['cursor', optional(string())], +}); diff --git a/src/models/searchEventsSort.ts b/src/models/searchEventsSort.ts new file mode 100644 index 00000000..c47c3d4d --- /dev/null +++ b/src/models/searchEventsSort.ts @@ -0,0 +1,14 @@ +import { object, optional, Schema, string } from '../schema'; + +/** Criteria to sort events by. */ +export interface SearchEventsSort { + /** Specifies the sort key for events returned from a search. */ + field?: string; + /** The order (e.g., chronological or alphabetical) in which results from a request are returned. */ + order?: string; +} + +export const searchEventsSortSchema: Schema = object({ + field: ['field', optional(string())], + order: ['order', optional(string())], +});