diff --git a/doc/api/catalog.md b/doc/api/catalog.md index 4f6ced9a..496ac8a2 100644 --- a/doc/api/catalog.md +++ b/doc/api/catalog.md @@ -39,7 +39,7 @@ children. IDs can be deleted. The response will only include IDs that were actually deleted. -To ensure consistency, only one delete request is processed at a time per seller account. +To ensure consistency, only one delete request is processed at a time per seller account. While one (batch or non-batch) delete request is being processed, other (batched and non-batched) delete requests are rejected with the `429` error code. @@ -143,7 +143,7 @@ batches will be processed in order as long as the total object count for the request (items, variations, modifier lists, discounts, and taxes) is no more than 10,000. -To ensure consistency, only one update request is processed at a time per seller account. +To ensure consistency, only one update request is processed at a time per seller account. While one (batch or non-batch) update request is being processed, other (batched and non-batched) update requests are rejected with the `429` error code. @@ -483,7 +483,7 @@ try { Creates a new or updates the specified [CatalogObject](../../doc/models/catalog-object.md). -To ensure consistency, only one update request is processed at a time per seller account. +To ensure consistency, only one update request is processed at a time per seller account. While one (batch or non-batch) update request is being processed, other (batched and non-batched) update requests are rejected with the `429` error code. @@ -565,7 +565,7 @@ are also deleted. For example, deleting a [CatalogItem](../../doc/models/catalog will also delete all of its [CatalogItemVariation](../../doc/models/catalog-item-variation.md) children. -To ensure consistency, only one delete request is processed at a time per seller account. +To ensure consistency, only one delete request is processed at a time per seller account. While one (batch or non-batch) delete request is being processed, other (batched and non-batched) delete requests are rejected with the `429` error code. diff --git a/doc/api/gift-card-activities.md b/doc/api/gift-card-activities.md index f5e7705b..c4bf05cc 100644 --- a/doc/api/gift-card-activities.md +++ b/doc/api/gift-card-activities.md @@ -70,8 +70,7 @@ try { # Create Gift Card Activity Creates a gift card activity to manage the balance or state of a [gift card](../../doc/models/gift-card.md). -For example, you create an `ACTIVATE` activity to activate a gift card with an initial balance -before the gift card can be used. +For example, create an `ACTIVATE` activity to activate a gift card with an initial balance before first use. ```ts async createGiftCardActivity( body: CreateGiftCardActivityRequest, diff --git a/doc/api/gift-cards.md b/doc/api/gift-cards.md index c2ed0666..05bd77c5 100644 --- a/doc/api/gift-cards.md +++ b/doc/api/gift-cards.md @@ -66,9 +66,11 @@ try { # Create Gift Card -Creates a digital gift card or registers a physical (plastic) gift card. After the gift card -is created, you must call [CreateGiftCardActivity](../../doc/api/gift-card-activities.md#create-gift-card-activity) -to activate the card with an initial balance before it can be used for payment. +Creates a digital gift card or registers a physical (plastic) gift card. The resulting gift card +has a `PENDING` state. To activate a gift card so that it can be redeemed for purchases, call +[CreateGiftCardActivity](../../doc/api/gift-card-activities.md#create-gift-card-activity) and create an `ACTIVATE` +activity with the initial balance. Alternatively, you can use [RefundPayment](../../doc/api/refunds.md#refund-payment) +to refund a payment to the new gift card. ```ts async createGiftCard( body: CreateGiftCardRequest, diff --git a/doc/api/o-auth.md b/doc/api/o-auth.md index 20eac5ca..1aa7f0f1 100644 --- a/doc/api/o-auth.md +++ b/doc/api/o-auth.md @@ -156,18 +156,14 @@ where `ACCESS_TOKEN` is a If the access token is expired or not a valid access token, the endpoint returns an `UNAUTHORIZED` error. -:information_source: **Note** This endpoint does not require authentication. - ```ts -async retrieveTokenStatus( authorization: string, -requestOptions?: RequestOptions): Promise> +async retrieveTokenStatus(requestOptions?: RequestOptions): Promise> ``` ## Parameters | Parameter | Type | Tags | Description | | --- | --- | --- | --- | -| `authorization` | `string` | Header, Required | Client APPLICATION_SECRET | | `requestOptions` | `RequestOptions \| undefined` | Optional | Pass additional request options. | ## Response Type @@ -177,10 +173,8 @@ requestOptions?: RequestOptions): Promise> ``` @@ -54,6 +57,9 @@ requestOptions?: RequestOptions): Promise> | `last4` | `string \| undefined` | Query, Optional | The last four digits of a payment card. | | `cardBrand` | `string \| undefined` | Query, Optional | The brand of the payment card (for example, VISA). | | `limit` | `number \| undefined` | Query, Optional | The maximum number of results to be returned in a single page.
It is possible to receive fewer results than the specified limit on a given page.

The default value of 100 is also the maximum allowed value. If the provided value is
greater than 100, it is ignored and the default value is used instead.

Default: `100` | +| `isOfflinePayment` | `boolean \| undefined` | Query, Optional | Whether the payment was taken offline or not. | +| `offlineBeginTime` | `string \| undefined` | Query, Optional | Indicates the start of the time range for which to retrieve offline payments, in RFC 3339
format for timestamps. The range is determined using the
`offline_payment_details.client_created_at` field for each Payment. If set, payments without a
value set in `offline_payment_details.client_created_at` will not be returned.

Default: The current time. | +| `offlineEndTime` | `string \| undefined` | Query, Optional | Indicates the end of the time range for which to retrieve offline payments, in RFC 3339
format for timestamps. The range is determined using the
`offline_payment_details.client_created_at` field for each Payment. If set, payments without a
value set in `offline_payment_details.client_created_at` will not be returned.

Default: The current time. | | `requestOptions` | `RequestOptions \| undefined` | Optional | Pass additional request options. | ## Response Type @@ -63,8 +69,21 @@ requestOptions?: RequestOptions): Promise> ## Example Usage ```ts +const isOfflinePayment = false; + try { - const { result, ...httpResponse } = await paymentsApi.listPayments(); + const { result, ...httpResponse } = await paymentsApi.listPayments( + undefined, + undefined, + undefined, + undefined, + undefined, + undefined, + undefined, + undefined, + undefined, + isOfflinePayment +); // Get more response info... // const { statusCode, headers } = httpResponse; } catch (error) { diff --git a/doc/client.md b/doc/client.md index 328c0b18..2d68df19 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-07-17'` | +| `squareVersion` | `string` | Square Connect API versions
*Default*: `'2024-08-21'` | | `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-07-17', + squareVersion: '2024-08-21', timeout: 60000, additionalHeaders: {}, userAgentDetail: '', @@ -61,7 +61,7 @@ const client = new Client({ bearerAuthCredentials: { accessToken: 'AccessToken' }, - squareVersion: '2024-07-17', + squareVersion: '2024-08-21', timeout: 60000, additionalHeaders: {}, userAgentDetail: '', diff --git a/doc/models/create-payment-request.md b/doc/models/create-payment-request.md index 55783cce..4a9bcdf1 100644 --- a/doc/models/create-payment-request.md +++ b/doc/models/create-payment-request.md @@ -35,6 +35,7 @@ Describes a request to create a payment using | `cashDetails` | [`CashPaymentDetails \| undefined`](../../doc/models/cash-payment-details.md) | Optional | Stores details about a cash payment. Contains only non-confidential information. For more information, see
[Take Cash Payments](https://developer.squareup.com/docs/payments-api/take-payments/cash-payments). | | `externalDetails` | [`ExternalPaymentDetails \| undefined`](../../doc/models/external-payment-details.md) | Optional | Stores details about an external payment. Contains only non-confidential information.
For more information, see
[Take External Payments](https://developer.squareup.com/docs/payments-api/take-payments/external-payments). | | `customerDetails` | [`CustomerDetails \| undefined`](../../doc/models/customer-details.md) | Optional | Details about the customer making the payment. | +| `offlinePaymentDetails` | [`OfflinePaymentDetails \| undefined`](../../doc/models/offline-payment-details.md) | Optional | Details specific to offline payments. | ## Example (as JSON) diff --git a/doc/models/gift-card-activity-activate.md b/doc/models/gift-card-activity-activate.md index f24547f0..66d4c46c 100644 --- a/doc/models/gift-card-activity-activate.md +++ b/doc/models/gift-card-activity-activate.md @@ -15,7 +15,7 @@ Represents details about an `ACTIVATE` [gift card activity type](../../doc/model | `orderId` | `string \| null \| undefined` | Optional | The ID of the [order](entity:Order) that contains the `GIFT_CARD` line item.

Applications that use the Square Orders API to process orders must specify the order ID
[CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request. | | `lineItemUid` | `string \| null \| undefined` | Optional | The UID of the `GIFT_CARD` line item in the order that represents the gift card purchase.

Applications that use the Square Orders API to process orders must specify the line item UID
in the [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request. | | `referenceId` | `string \| null \| undefined` | Optional | A client-specified ID that associates the gift card activity with an entity in another system.

Applications that use a custom order processing system can use this field to track information
related to an order or payment. | -| `buyerPaymentInstrumentIds` | `string[] \| null \| undefined` | Optional | The payment instrument IDs used to process the gift card purchase, such as a credit card ID
or bank account ID.

Applications that use a custom order processing system must specify payment instrument IDs in
the [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request.
Square uses this information to perform compliance checks.

For applications that use the Square Orders API to process payments, Square has the necessary
instrument IDs to perform compliance checks. | +| `buyerPaymentInstrumentIds` | `string[] \| null \| undefined` | Optional | The payment instrument IDs used to process the gift card purchase, such as a credit card ID
or bank account ID.

Applications that use a custom order processing system must specify payment instrument IDs in
the [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request.
Square uses this information to perform compliance checks.

For applications that use the Square Orders API to process payments, Square has the necessary
instrument IDs to perform compliance checks.

Each buyer payment instrument ID can contain a maximum of 255 characters. | ## Example (as JSON) diff --git a/doc/models/gift-card-activity-load.md b/doc/models/gift-card-activity-load.md index be48aa89..2c50ef7e 100644 --- a/doc/models/gift-card-activity-load.md +++ b/doc/models/gift-card-activity-load.md @@ -15,7 +15,7 @@ Represents details about a `LOAD` [gift card activity type](../../doc/models/gif | `orderId` | `string \| null \| undefined` | Optional | The ID of the [order](entity:Order) that contains the `GIFT_CARD` line item.

Applications that use the Square Orders API to process orders must specify the order ID in the
[CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request. | | `lineItemUid` | `string \| null \| undefined` | Optional | The UID of the `GIFT_CARD` line item in the order that represents the additional funds for the gift card.

Applications that use the Square Orders API to process orders must specify the line item UID
in the [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request. | | `referenceId` | `string \| null \| undefined` | Optional | A client-specified ID that associates the gift card activity with an entity in another system.

Applications that use a custom order processing system can use this field to track information related to
an order or payment. | -| `buyerPaymentInstrumentIds` | `string[] \| null \| undefined` | Optional | The payment instrument IDs used to process the order for the additional funds, such as a credit card ID
or bank account ID.

Applications that use a custom order processing system must specify payment instrument IDs in
the [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request.
Square uses this information to perform compliance checks.

For applications that use the Square Orders API to process payments, Square has the necessary
instrument IDs to perform compliance checks. | +| `buyerPaymentInstrumentIds` | `string[] \| null \| undefined` | Optional | The payment instrument IDs used to process the order for the additional funds, such as a credit card ID
or bank account ID.

Applications that use a custom order processing system must specify payment instrument IDs in
the [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity) request.
Square uses this information to perform compliance checks.

For applications that use the Square Orders API to process payments, Square has the necessary
instrument IDs to perform compliance checks.

Each buyer payment instrument ID can contain a maximum of 255 characters. | ## Example (as JSON) diff --git a/doc/models/gift-card-activity-refund.md b/doc/models/gift-card-activity-refund.md index a9e0de64..202f0e4c 100644 --- a/doc/models/gift-card-activity-refund.md +++ b/doc/models/gift-card-activity-refund.md @@ -11,10 +11,10 @@ Represents details about a `REFUND` [gift card activity type](../../doc/models/g | Name | Type | Tags | Description | | --- | --- | --- | --- | -| `redeemActivityId` | `string \| null \| undefined` | Optional | The ID of the refunded `REDEEM` gift card activity. Square populates this field if the
`payment_id` in the corresponding [RefundPayment](api-endpoint:Refunds-RefundPayment) request
represents a redemption made by the same gift card. Note that you must use `RefundPayment`
to refund a gift card payment to the same gift card if the payment was processed by Square.

For applications that use a custom payment processing system, this field is required when creating
a `REFUND` activity. The provided `REDEEM` activity ID must be linked to the same gift card. | +| `redeemActivityId` | `string \| null \| undefined` | Optional | The ID of the refunded `REDEEM` gift card activity. Square populates this field if the
`payment_id` in the corresponding [RefundPayment](api-endpoint:Refunds-RefundPayment) request
represents a gift card redemption.

For applications that use a custom payment processing system, this field is required when creating
a `REFUND` activity. The provided `REDEEM` activity ID must be linked to the same gift card. | | `amountMoney` | [`Money \| undefined`](../../doc/models/money.md) | Optional | Represents an amount of money. `Money` fields can be signed or unsigned.
Fields that do not explicitly define whether they are signed or unsigned are
considered unsigned and can only hold positive amounts. For signed fields, the
sign of the value indicates the purpose of the money transfer. See
[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)
for more information. | | `referenceId` | `string \| null \| undefined` | Optional | A client-specified ID that associates the gift card activity with an entity in another system. | -| `paymentId` | `string \| undefined` | Optional | The ID of the refunded payment. Square populates this field if the refund is for a
payment processed by Square and one of the following conditions is true:

- The Refunds API is used to refund a gift card payment to the same gift card.
- A seller initiated the refund from Square Point of Sale or the Seller Dashboard. The payment source can be the
same gift card or a cross-tender payment from a credit card or a different gift card. | +| `paymentId` | `string \| undefined` | Optional | The ID of the refunded payment. Square populates this field if the refund is for a
payment processed by Square. This field matches the `payment_id` in the corresponding
[RefundPayment](api-endpoint:Refunds-RefundPayment) request. | ## Example (as JSON) diff --git a/doc/models/gift-card-activity-type.md b/doc/models/gift-card-activity-type.md index 637f73d2..53df15bc 100644 --- a/doc/models/gift-card-activity-type.md +++ b/doc/models/gift-card-activity-type.md @@ -18,7 +18,7 @@ Indicates the type of [gift card activity](../../doc/models/gift-card-activity.m | `DEACTIVATE` | Permanently blocked a gift card from balance-changing activities. | | `ADJUST_INCREMENT` | Added money to a gift card outside of a typical `ACTIVATE`, `LOAD`, or `REFUND` activity flow. | | `ADJUST_DECREMENT` | Deducted money from a gift card outside of a typical `REDEEM` activity flow. | -| `REFUND` | Added money to a gift card from a refunded transaction. A `REFUND` activity might be linked to
a Square payment, depending on how the payment and refund are processed. For example:

- A gift card payment processed by Square can be refunded to the same gift card using Square Point of Sale,
the Square Seller Dashboard, or the Refunds API.
- A cross-tender payment processed by Square can be refunded to a gift card using Square Point of Sale or the
Square Seller Dashboard. The payment source might be a credit card or different gift card.
- A payment processed using a custom payment processing system can be refunded to the same gift card. | +| `REFUND` | Added money to a gift card from a refunded transaction. A `REFUND` activity might be linked to
a Square payment, depending on how the payment and refund are processed. For example:

- A payment processed by Square can be refunded to a `PENDING` or `ACTIVE` gift card using the Square
Seller Dashboard, Square Point of Sale, or Refunds API.
- A payment processed using a custom processing system can be refunded to the same gift card. | | `UNLINKED_ACTIVITY_REFUND` | Added money to a gift card from a refunded transaction that was processed using a custom payment
processing system and not linked to the gift card. | | `IMPORT` | Imported a third-party gift card with a balance. `IMPORT` activities are managed
by Square and cannot be created using the Gift Card Activities API. | | `BLOCK` | Temporarily blocked a gift card from balance-changing activities. `BLOCK` activities
are managed by Square and cannot be created using the Gift Card Activities API. | diff --git a/doc/models/gift-card-status.md b/doc/models/gift-card-status.md index f66369cc..7a364e5a 100644 --- a/doc/models/gift-card-status.md +++ b/doc/models/gift-card-status.md @@ -14,5 +14,5 @@ Indicates the gift card state. | `ACTIVE` | The gift card is active and can be used as a payment source. | | `DEACTIVATED` | Any activity that changes the gift card balance is permanently forbidden. | | `BLOCKED` | Any activity that changes the gift card balance is temporarily forbidden. | -| `PENDING` | The gift card is pending activation.
This is the initial state when a gift card is created. You must activate the gift card
before it can be used. | +| `PENDING` | The gift card is pending activation.
This is the initial state when a gift card is created. Typically, you'll call
[CreateGiftCardActivity](../../doc/api/gift-card-activities.md#create-gift-card-activity) to create an
`ACTIVATE` activity that activates the gift card with an initial balance before first use. | diff --git a/doc/models/list-payments-request.md b/doc/models/list-payments-request.md index 4c9fc1be..ab4a61b2 100644 --- a/doc/models/list-payments-request.md +++ b/doc/models/list-payments-request.md @@ -23,6 +23,9 @@ The maximum results per page is 100. | `last4` | `string \| null \| undefined` | Optional | The last four digits of a payment card. | | `cardBrand` | `string \| null \| undefined` | Optional | The brand of the payment card (for example, VISA). | | `limit` | `number \| null \| undefined` | Optional | The maximum number of results to be returned in a single page.
It is possible to receive fewer results than the specified limit on a given page.

The default value of 100 is also the maximum allowed value. If the provided value is
greater than 100, it is ignored and the default value is used instead.

Default: `100` | +| `isOfflinePayment` | `boolean \| null \| undefined` | Optional | Whether the payment was taken offline or not. | +| `offlineBeginTime` | `string \| null \| undefined` | Optional | Indicates the start of the time range for which to retrieve offline payments, in RFC 3339
format for timestamps. The range is determined using the
`offline_payment_details.client_created_at` field for each Payment. If set, payments without a
value set in `offline_payment_details.client_created_at` will not be returned.

Default: The current time. | +| `offlineEndTime` | `string \| null \| undefined` | Optional | Indicates the end of the time range for which to retrieve offline payments, in RFC 3339
format for timestamps. The range is determined using the
`offline_payment_details.client_created_at` field for each Payment. If set, payments without a
value set in `offline_payment_details.client_created_at` will not be returned.

Default: The current time. | ## Example (as JSON) diff --git a/doc/models/offline-payment-details.md b/doc/models/offline-payment-details.md new file mode 100644 index 00000000..962a5bac --- /dev/null +++ b/doc/models/offline-payment-details.md @@ -0,0 +1,23 @@ + +# Offline Payment Details + +Details specific to offline payments. + +## Structure + +`OfflinePaymentDetails` + +## Fields + +| Name | Type | Tags | Description | +| --- | --- | --- | --- | +| `clientCreatedAt` | `string \| undefined` | Optional | The client-side timestamp of when the offline payment was created, in RFC 3339 format.
**Constraints**: *Maximum Length*: `32` | + +## Example (as JSON) + +```json +{ + "client_created_at": "client_created_at6" +} +``` + diff --git a/doc/models/payment.md b/doc/models/payment.md index 11651316..59e03d68 100644 --- a/doc/models/payment.md +++ b/doc/models/payment.md @@ -38,7 +38,7 @@ Represents a payment processed by the Square API. | `referenceId` | `string \| undefined` | Optional | An optional ID that associates the payment with an entity in
another system.
**Constraints**: *Maximum Length*: `40` | | `customerId` | `string \| undefined` | Optional | The ID of the customer associated with the payment. If the ID is
not provided in the `CreatePayment` request that was used to create the `Payment`,
Square may use information in the request
(such as the billing and shipping address, email address, and payment source)
to identify a matching customer profile in the Customer Directory.
If found, the profile ID is used. If a profile is not found, the
API attempts to create an
[instant profile](https://developer.squareup.com/docs/customers-api/what-it-does#instant-profiles).
If the API cannot create an
instant profile (either because the seller has disabled it or the
seller's region prevents creating it), this field remains unset. Note that
this process is asynchronous and it may take some time before a
customer ID is added to the payment.
**Constraints**: *Maximum Length*: `191` | | `employeeId` | `string \| undefined` | Optional | __Deprecated__: Use `Payment.team_member_id` instead.

An optional ID of the employee associated with taking the payment.
**Constraints**: *Maximum Length*: `192` | -| `teamMemberId` | `string \| undefined` | Optional | An optional ID of the [TeamMember](entity:TeamMember) associated with taking the payment.
**Constraints**: *Maximum Length*: `192` | +| `teamMemberId` | `string \| null \| undefined` | Optional | An optional ID of the [TeamMember](entity:TeamMember) associated with taking the payment.
**Constraints**: *Maximum Length*: `192` | | `refundIds` | `string[] \| undefined` | Optional | A list of `refund_id`s identifying refunds for the payment. | | `riskEvaluation` | [`RiskEvaluation \| undefined`](../../doc/models/risk-evaluation.md) | Optional | Represents fraud risk information for the associated payment.

When you take a payment through Square's Payments API (using the `CreatePayment`
endpoint), Square evaluates it and assigns a risk level to the payment. Sellers
can use this information to determine the course of action (for example,
provide the goods/services or refund the payment). | | `buyerEmailAddress` | `string \| undefined` | Optional | The buyer's email address.
**Constraints**: *Maximum Length*: `255` | @@ -52,6 +52,7 @@ Represents a payment processed by the Square API. | `deviceDetails` | [`DeviceDetails \| undefined`](../../doc/models/device-details.md) | Optional | Details about the device that took the payment. | | `applicationDetails` | [`ApplicationDetails \| undefined`](../../doc/models/application-details.md) | Optional | Details about the application that took the payment. | | `isOfflinePayment` | `boolean \| undefined` | Optional | Whether or not this payment was taken offline. | +| `offlinePaymentDetails` | [`OfflinePaymentDetails \| undefined`](../../doc/models/offline-payment-details.md) | Optional | Details specific to offline payments. | | `versionToken` | `string \| null \| undefined` | Optional | Used for optimistic concurrency. This opaque token identifies a specific version of the
`Payment` object. | ## Example (as JSON) diff --git a/jest.config.js b/jest.config.js index 45a2c189..091b875d 100644 --- a/jest.config.js +++ b/jest.config.js @@ -1,9 +1,7 @@ module.exports = { testEnvironment: 'node', preset: 'ts-jest', - globals: { - 'ts-jest': { - tsConfig: 'tsconfig.base.json', - }, + transform: { + '^.+\\.tsx?$': ['ts-jest', { tsconfig: 'tsconfig.base.json' }], }, }; diff --git a/package.json b/package.json index c2d6c0ad..b77809fd 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,5 @@ { - "version": "37.1.1", + "version": "38.0.0", "license": "MIT", "sideEffects": false, "main": "dist/cjs/index.js", @@ -7,16 +7,19 @@ "module": "dist/esm/index.js", "files": [ "dist", - "src" + "src", + "test" ], "engines": { "node": ">=14.17.0" }, "scripts": { "build": "rm -rf dist & tsc -p tsconfig.esm.json & tsc -p tsconfig.cjs.json", - "test": "jest --coverage --passWithNoTests", - "lint": "eslint --ignore-path .eslintignore --ext .js,.ts .", - "prepare": "rm -rf dist & tsc -p tsconfig.esm.json & tsc -p tsconfig.cjs.json" + "prepare": "rm -rf dist & tsc -p tsconfig.esm.json & tsc -p tsconfig.cjs.json", + "test": "jest --passWithNoTests", + "test:coverage": "jest --coverage --passWithNoTests", + "lint": "eslint **/*.ts --ignore-path .eslintignore", + "lint:fix": "eslint **/*.ts --ignore-path .eslintignore --fix" }, "peerDependencies": {}, "prettier": { @@ -34,6 +37,7 @@ "url": "https://squareup.com/developers" }, "devDependencies": { + "@apimatic/test-utilities": "^0.0.1", "@types/jest": "^29.4.0", "@types/uuid": "^8.3.0", "@typescript-eslint/eslint-plugin": "^5.52.0", @@ -46,11 +50,11 @@ "uuid": "^8.3.0" }, "dependencies": { - "@apimatic/authentication-adapters": "^0.5.3", - "@apimatic/axios-client-adapter": "^0.3.3", - "@apimatic/core": "^0.10.11", + "@apimatic/authentication-adapters": "^0.5.4", + "@apimatic/axios-client-adapter": "^0.3.4", + "@apimatic/core": "^0.10.12", "@apimatic/json-bigint": "^1.2.0", - "@apimatic/schema": "^0.7.11", + "@apimatic/schema": "^0.7.12", "@types/node": "^14.14.30" }, "bugs": { diff --git a/src/api/giftCardActivitiesApi.ts b/src/api/giftCardActivitiesApi.ts index e8d14704..61c1aeb8 100644 --- a/src/api/giftCardActivitiesApi.ts +++ b/src/api/giftCardActivitiesApi.ts @@ -83,8 +83,8 @@ export class GiftCardActivitiesApi extends BaseApi { /** * Creates a gift card activity to manage the balance or state of a [gift card]($m/GiftCard). - * For example, you create an `ACTIVATE` activity to activate a gift card with an initial balance - * before the gift card can be used. + * For example, create an `ACTIVATE` activity to activate a gift card with an initial balance before + * first use. * * @param body An object containing the fields to POST for the * request. See the corresponding object definition for diff --git a/src/api/giftCardsApi.ts b/src/api/giftCardsApi.ts index 7dbe83a6..86a67958 100644 --- a/src/api/giftCardsApi.ts +++ b/src/api/giftCardsApi.ts @@ -96,9 +96,12 @@ export class GiftCardsApi extends BaseApi { } /** - * Creates a digital gift card or registers a physical (plastic) gift card. After the gift card - * is created, you must call [CreateGiftCardActivity]($e/GiftCardActivities/CreateGiftCardActivity) - * to activate the card with an initial balance before it can be used for payment. + * Creates a digital gift card or registers a physical (plastic) gift card. The resulting gift card + * has a `PENDING` state. To activate a gift card so that it can be redeemed for purchases, call + * [CreateGiftCardActivity]($e/GiftCardActivities/CreateGiftCardActivity) and create an `ACTIVATE` + * activity with the initial balance. Alternatively, you can use + * [RefundPayment]($e/Refunds/RefundPayment) + * to refund a payment to the new gift card. * * @param body An object containing the fields to POST for the request. See * the corresponding object definition for field details. diff --git a/src/api/oAuthApi.ts b/src/api/oAuthApi.ts index 67944adf..309b6bcc 100644 --- a/src/api/oAuthApi.ts +++ b/src/api/oAuthApi.ts @@ -117,19 +117,13 @@ export class OAuthApi extends BaseApi { * If the access token is expired or not a valid access token, the endpoint returns an `UNAUTHORIZED` * error. * - * @param authorization Client APPLICATION_SECRET * @return Response from the API call */ async retrieveTokenStatus( - authorization: string, requestOptions?: RequestOptions ): Promise> { const req = this.createRequest('POST', '/oauth2/token/status'); - const mapped = req.prepareArgs({ - authorization: [authorization, string()], - }); - req.header('Authorization', mapped.authorization); - req.authenticate(false); + req.authenticate([{ global: true }]); return req.callAsJson(retrieveTokenStatusResponseSchema, requestOptions); } } diff --git a/src/api/paymentsApi.ts b/src/api/paymentsApi.ts index c49b0e46..03fc5c64 100644 --- a/src/api/paymentsApi.ts +++ b/src/api/paymentsApi.ts @@ -43,7 +43,7 @@ import { UpdatePaymentResponse, updatePaymentResponseSchema, } from '../models/updatePaymentResponse'; -import { bigint, number, optional, string } from '../schema'; +import { bigint, boolean, number, optional, string } from '../schema'; import { BaseApi } from './baseApi'; export class PaymentsApi extends BaseApi { @@ -55,27 +55,39 @@ export class PaymentsApi extends BaseApi { * * The maximum results per page is 100. * - * @param beginTime Indicates the start of the time range to retrieve payments for, in RFC 3339 format. - * The range is determined using the `created_at` field for each Payment. Inclusive. - * Default: The current time minus one year. - * @param endTime Indicates the end of the time range to retrieve payments for, in RFC 3339 format. - * The range is determined using the `created_at` field for each Payment. Default: The - * current time. - * @param sortOrder The order in which results are listed by `Payment.created_at`: - `ASC` - Oldest to - * newest. - `DESC` - Newest to oldest (default). - * @param cursor A pagination cursor returned by a previous call to this endpoint. Provide this - * cursor to retrieve the next set of results for the original query. For more - * information, see [Pagination](https://developer.squareup.com/docs/build-basics/common- - * api-patterns/pagination). - * @param locationId Limit results to the location supplied. By default, results are returned for the - * default (main) location associated with the seller. - * @param total The exact amount in the `total_money` for a payment. - * @param last4 The last four digits of a payment card. - * @param cardBrand The brand of the payment card (for example, VISA). - * @param limit The maximum number of results to be returned in a single page. It is possible to - * receive fewer results than the specified limit on a given page. The default value of - * 100 is also the maximum allowed value. If the provided value is greater than 100, it - * is ignored and the default value is used instead. Default: `100` + * @param beginTime Indicates the start of the time range to retrieve payments for, in RFC 3339 + * format. The range is determined using the `created_at` field for each + * Payment. Inclusive. Default: The current time minus one year. + * @param endTime Indicates the end of the time range to retrieve payments for, in RFC 3339 + * format. The range is determined using the `created_at` field for each + * Payment. Default: The current time. + * @param sortOrder The order in which results are listed by `Payment.created_at`: - `ASC` - + * Oldest to newest. - `DESC` - Newest to oldest (default). + * @param cursor A pagination cursor returned by a previous call to this endpoint. Provide + * this cursor to retrieve the next set of results for the original query. For + * more information, see [Pagination](https://developer.squareup.com/docs/build- + * basics/common-api-patterns/pagination). + * @param locationId Limit results to the location supplied. By default, results are returned for + * the default (main) location associated with the seller. + * @param total The exact amount in the `total_money` for a payment. + * @param last4 The last four digits of a payment card. + * @param cardBrand The brand of the payment card (for example, VISA). + * @param limit The maximum number of results to be returned in a single page. It is + * possible to receive fewer results than the specified limit on a given page. + * The default value of 100 is also the maximum allowed value. If the provided + * value is greater than 100, it is ignored and the default value is used + * instead. Default: `100` + * @param isOfflinePayment Whether the payment was taken offline or not. + * @param offlineBeginTime Indicates the start of the time range for which to retrieve offline payments, + * in RFC 3339 format for timestamps. The range is determined using the + * `offline_payment_details.client_created_at` field for each Payment. If set, + * payments without a value set in `offline_payment_details.client_created_at` + * will not be returned. Default: The current time. + * @param offlineEndTime Indicates the end of the time range for which to retrieve offline payments, + * in RFC 3339 format for timestamps. The range is determined using the + * `offline_payment_details.client_created_at` field for each Payment. If set, + * payments without a value set in `offline_payment_details.client_created_at` + * will not be returned. Default: The current time. * @return Response from the API call */ async listPayments( @@ -88,6 +100,9 @@ export class PaymentsApi extends BaseApi { last4?: string, cardBrand?: string, limit?: number, + isOfflinePayment?: boolean, + offlineBeginTime?: string, + offlineEndTime?: string, requestOptions?: RequestOptions ): Promise> { const req = this.createRequest('GET', '/v2/payments'); @@ -101,6 +116,9 @@ export class PaymentsApi extends BaseApi { last4: [last4, optional(string())], cardBrand: [cardBrand, optional(string())], limit: [limit, optional(number())], + isOfflinePayment: [isOfflinePayment, optional(boolean())], + offlineBeginTime: [offlineBeginTime, optional(string())], + offlineEndTime: [offlineEndTime, optional(string())], }); req.query('begin_time', mapped.beginTime); req.query('end_time', mapped.endTime); @@ -111,6 +129,9 @@ export class PaymentsApi extends BaseApi { req.query('last_4', mapped.last4); req.query('card_brand', mapped.cardBrand); req.query('limit', mapped.limit); + req.query('is_offline_payment', mapped.isOfflinePayment); + req.query('offline_begin_time', mapped.offlineBeginTime); + req.query('offline_end_time', mapped.offlineEndTime); req.authenticate([{ global: true }]); return req.callAsJson(listPaymentsResponseSchema, requestOptions); } diff --git a/src/client.ts b/src/client.ts index 277e9d91..6e33b8d4 100644 --- a/src/client.ts +++ b/src/client.ts @@ -68,7 +68,7 @@ import { import { HttpClient } from './clientAdapter'; /** Current SDK version */ -export const SDK_VERSION = '37.1.1'; +export const SDK_VERSION = '38.0.0'; export class Client implements ClientInterface { private _config: Readonly; private _timeout: number; @@ -140,7 +140,7 @@ export class Client implements ClientInterface { }; this._userAgent = updateUserAgent( - 'Square-TypeScript-SDK/37.1.1 ({api-version}) {engine}/{engine-version} ({os-info}) {detail}', + 'Square-TypeScript-SDK/38.0.0 ({api-version}) {engine}/{engine-version} ({os-info}) {detail}', this._config.squareVersion, this._config.userAgentDetail ); diff --git a/src/defaultConfiguration.ts b/src/defaultConfiguration.ts index 14679fb2..ea383734 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-07-17', + squareVersion: '2024-08-21', additionalHeaders: {}, userAgentDetail: '', environment: Environment.Production, diff --git a/src/errors/apiError.ts b/src/errors/apiError.ts index db6e6f87..6ff91f65 100644 --- a/src/errors/apiError.ts +++ b/src/errors/apiError.ts @@ -51,7 +51,7 @@ export class ApiError extends Error if (process.env.NODE_ENV !== 'production') { if (console) { console.warn( - `Unexpected error: Could not parse HTTP response body as JSON. ${error.message}` + `Unexpected error: Could not parse HTTP response body as JSON. ${error}` ); } } diff --git a/src/index.ts b/src/index.ts index 1d8b14b8..52235b02 100644 --- a/src/index.ts +++ b/src/index.ts @@ -622,6 +622,7 @@ export type { ModifierLocationOverrides } from './models/modifierLocationOverrid export type { Money } from './models/money'; export type { ObtainTokenRequest } from './models/obtainTokenRequest'; export type { ObtainTokenResponse } from './models/obtainTokenResponse'; +export type { OfflinePaymentDetails } from './models/offlinePaymentDetails'; export type { Order } from './models/order'; export type { OrderCreated } from './models/orderCreated'; export type { OrderCreatedObject } from './models/orderCreatedObject'; diff --git a/src/models/catalogCustomAttributeDefinitionSelectionConfig.ts b/src/models/catalogCustomAttributeDefinitionSelectionConfig.ts index 62ea1da2..f6bd1536 100644 --- a/src/models/catalogCustomAttributeDefinitionSelectionConfig.ts +++ b/src/models/catalogCustomAttributeDefinitionSelectionConfig.ts @@ -25,7 +25,9 @@ export interface CatalogCustomAttributeDefinitionSelectionConfig { * The set of valid `CatalogCustomAttributeSelections`. Up to a maximum of 100 * selections can be defined. Can be modified. */ - allowedSelections?: CatalogCustomAttributeDefinitionSelectionConfigCustomAttributeSelection[] | null; + allowedSelections?: + | CatalogCustomAttributeDefinitionSelectionConfigCustomAttributeSelection[] + | null; } export const catalogCustomAttributeDefinitionSelectionConfigSchema: Schema = object( diff --git a/src/models/catalogItemFoodAndBeverageDetails.ts b/src/models/catalogItemFoodAndBeverageDetails.ts index 4c56454a..f91a5e1e 100644 --- a/src/models/catalogItemFoodAndBeverageDetails.ts +++ b/src/models/catalogItemFoodAndBeverageDetails.ts @@ -21,7 +21,9 @@ export interface CatalogItemFoodAndBeverageDetails { /** The calorie count (in the unit of kcal) for the `FOOD_AND_BEV` type of items. */ calorieCount?: number | null; /** The dietary preferences for the `FOOD_AND_BEV` item. */ - dietaryPreferences?: CatalogItemFoodAndBeverageDetailsDietaryPreference[] | null; + dietaryPreferences?: + | CatalogItemFoodAndBeverageDetailsDietaryPreference[] + | null; /** The ingredients for the `FOOD_AND_BEV` type item. */ ingredients?: CatalogItemFoodAndBeverageDetailsIngredient[] | null; } diff --git a/src/models/createPaymentRequest.ts b/src/models/createPaymentRequest.ts index 73afaef9..0547726d 100644 --- a/src/models/createPaymentRequest.ts +++ b/src/models/createPaymentRequest.ts @@ -10,6 +10,10 @@ import { externalPaymentDetailsSchema, } from './externalPaymentDetails'; import { Money, moneySchema } from './money'; +import { + OfflinePaymentDetails, + offlinePaymentDetailsSchema, +} from './offlinePaymentDetails'; /** * Describes a request to create a payment using @@ -166,6 +170,8 @@ export interface CreatePaymentRequest { externalDetails?: ExternalPaymentDetails; /** Details about the customer making the payment. */ customerDetails?: CustomerDetails; + /** Details specific to offline payments. */ + offlinePaymentDetails?: OfflinePaymentDetails; } export const createPaymentRequestSchema: Schema = object({ @@ -204,4 +210,8 @@ export const createPaymentRequestSchema: Schema = object({ 'customer_details', optional(lazy(() => customerDetailsSchema)), ], + offlinePaymentDetails: [ + 'offline_payment_details', + optional(lazy(() => offlinePaymentDetailsSchema)), + ], }); diff --git a/src/models/giftCardActivityActivate.ts b/src/models/giftCardActivityActivate.ts index 01bf5505..6bf3ab16 100644 --- a/src/models/giftCardActivityActivate.ts +++ b/src/models/giftCardActivityActivate.ts @@ -46,6 +46,7 @@ export interface GiftCardActivityActivate { * Square uses this information to perform compliance checks. * For applications that use the Square Orders API to process payments, Square has the necessary * instrument IDs to perform compliance checks. + * Each buyer payment instrument ID can contain a maximum of 255 characters. */ buyerPaymentInstrumentIds?: string[] | null; } diff --git a/src/models/giftCardActivityLoad.ts b/src/models/giftCardActivityLoad.ts index 47808def..91308e88 100644 --- a/src/models/giftCardActivityLoad.ts +++ b/src/models/giftCardActivityLoad.ts @@ -46,6 +46,7 @@ export interface GiftCardActivityLoad { * Square uses this information to perform compliance checks. * For applications that use the Square Orders API to process payments, Square has the necessary * instrument IDs to perform compliance checks. + * Each buyer payment instrument ID can contain a maximum of 255 characters. */ buyerPaymentInstrumentIds?: string[] | null; } diff --git a/src/models/giftCardActivityRefund.ts b/src/models/giftCardActivityRefund.ts index 304c3b10..b40dc15b 100644 --- a/src/models/giftCardActivityRefund.ts +++ b/src/models/giftCardActivityRefund.ts @@ -6,8 +6,7 @@ export interface GiftCardActivityRefund { /** * The ID of the refunded `REDEEM` gift card activity. Square populates this field if the * `payment_id` in the corresponding [RefundPayment](api-endpoint:Refunds-RefundPayment) request - * represents a redemption made by the same gift card. Note that you must use `RefundPayment` - * to refund a gift card payment to the same gift card if the payment was processed by Square. + * represents a gift card redemption. * For applications that use a custom payment processing system, this field is required when creating * a `REFUND` activity. The provided `REDEEM` activity ID must be linked to the same gift card. */ @@ -25,10 +24,8 @@ export interface GiftCardActivityRefund { referenceId?: string | null; /** * The ID of the refunded payment. Square populates this field if the refund is for a - * payment processed by Square and one of the following conditions is true: - * - The Refunds API is used to refund a gift card payment to the same gift card. - * - A seller initiated the refund from Square Point of Sale or the Seller Dashboard. The payment source can be the - * same gift card or a cross-tender payment from a credit card or a different gift card. + * payment processed by Square. This field matches the `payment_id` in the corresponding + * [RefundPayment](api-endpoint:Refunds-RefundPayment) request. */ paymentId?: string; } diff --git a/src/models/listPaymentsRequest.ts b/src/models/listPaymentsRequest.ts index 70372ec2..23b3d331 100644 --- a/src/models/listPaymentsRequest.ts +++ b/src/models/listPaymentsRequest.ts @@ -1,5 +1,6 @@ import { bigint, + boolean, nullable, number, object, @@ -57,6 +58,24 @@ export interface ListPaymentsRequest { * Default: `100` */ limit?: number | null; + /** Whether the payment was taken offline or not. */ + isOfflinePayment?: boolean | null; + /** + * Indicates the start of the time range for which to retrieve offline payments, in RFC 3339 + * format for timestamps. The range is determined using the + * `offline_payment_details.client_created_at` field for each Payment. If set, payments without a + * value set in `offline_payment_details.client_created_at` will not be returned. + * Default: The current time. + */ + offlineBeginTime?: string | null; + /** + * Indicates the end of the time range for which to retrieve offline payments, in RFC 3339 + * format for timestamps. The range is determined using the + * `offline_payment_details.client_created_at` field for each Payment. If set, payments without a + * value set in `offline_payment_details.client_created_at` will not be returned. + * Default: The current time. + */ + offlineEndTime?: string | null; } export const listPaymentsRequestSchema: Schema = object({ @@ -69,4 +88,7 @@ export const listPaymentsRequestSchema: Schema = object({ last4: ['last_4', optional(nullable(string()))], cardBrand: ['card_brand', optional(nullable(string()))], limit: ['limit', optional(nullable(number()))], + isOfflinePayment: ['is_offline_payment', optional(nullable(boolean()))], + offlineBeginTime: ['offline_begin_time', optional(nullable(string()))], + offlineEndTime: ['offline_end_time', optional(nullable(string()))], }); diff --git a/src/models/obtainTokenRequest.ts b/src/models/obtainTokenRequest.ts index ac615834..0d69b6dd 100644 --- a/src/models/obtainTokenRequest.ts +++ b/src/models/obtainTokenRequest.ts @@ -19,7 +19,7 @@ export interface ObtainTokenRequest { * in the [Developer Dashboard](https://developer.squareup.com/apps). This parameter is only required when * you're not using the [OAuth PKCE (Proof Key for Code Exchange) flow](https://developer.squareup.com/docs/oauth-api/overview#pkce-flow). * The PKCE flow requires a `code_verifier` instead of a `client_secret` when `grant_type` is set to `authorization_code`. - * If `grant_type` is set to `refresh_token` and the `refresh_token` is obtained uaing PKCE, the PKCE flow only requires `client_id`,  + * If `grant_type` is set to `refresh_token` and the `refresh_token` is obtained uaing PKCE, the PKCE flow only requires `client_id`, * `grant_type`, and `refresh_token`. */ clientSecret?: string | null; diff --git a/src/models/offlinePaymentDetails.ts b/src/models/offlinePaymentDetails.ts new file mode 100644 index 00000000..846fa10d --- /dev/null +++ b/src/models/offlinePaymentDetails.ts @@ -0,0 +1,11 @@ +import { object, optional, Schema, string } from '../schema'; + +/** Details specific to offline payments. */ +export interface OfflinePaymentDetails { + /** The client-side timestamp of when the offline payment was created, in RFC 3339 format. */ + clientCreatedAt?: string; +} + +export const offlinePaymentDetailsSchema: Schema = object( + { clientCreatedAt: ['client_created_at', optional(string())] } +); diff --git a/src/models/payment.ts b/src/models/payment.ts index 9f109fb9..105cad50 100644 --- a/src/models/payment.ts +++ b/src/models/payment.ts @@ -39,6 +39,10 @@ import { externalPaymentDetailsSchema, } from './externalPaymentDetails'; import { Money, moneySchema } from './money'; +import { + OfflinePaymentDetails, + offlinePaymentDetailsSchema, +} from './offlinePaymentDetails'; import { ProcessingFee, processingFeeSchema } from './processingFee'; import { RiskEvaluation, riskEvaluationSchema } from './riskEvaluation'; import { @@ -197,7 +201,7 @@ export interface Payment { */ employeeId?: string; /** An optional ID of the [TeamMember](entity:TeamMember) associated with taking the payment. */ - teamMemberId?: string; + teamMemberId?: string | null; /** A list of `refund_id`s identifying refunds for the payment. */ refundIds?: string[]; /** @@ -255,6 +259,8 @@ export interface Payment { applicationDetails?: ApplicationDetails; /** Whether or not this payment was taken offline. */ isOfflinePayment?: boolean; + /** Details specific to offline payments. */ + offlinePaymentDetails?: OfflinePaymentDetails; /** * Used for optimistic concurrency. This opaque token identifies a specific version of the * `Payment` object. @@ -308,7 +314,7 @@ export const paymentSchema: Schema = object({ referenceId: ['reference_id', optional(string())], customerId: ['customer_id', optional(string())], employeeId: ['employee_id', optional(string())], - teamMemberId: ['team_member_id', optional(string())], + teamMemberId: ['team_member_id', optional(nullable(string()))], refundIds: ['refund_ids', optional(array(string()))], riskEvaluation: [ 'risk_evaluation', @@ -331,5 +337,9 @@ export const paymentSchema: Schema = object({ optional(lazy(() => applicationDetailsSchema)), ], isOfflinePayment: ['is_offline_payment', optional(boolean())], + offlinePaymentDetails: [ + 'offline_payment_details', + optional(lazy(() => offlinePaymentDetailsSchema)), + ], versionToken: ['version_token', optional(nullable(string()))], }); diff --git a/test/locationsApi.test.ts b/test/locationsApi.test.ts new file mode 100644 index 00000000..0be56c0c --- /dev/null +++ b/test/locationsApi.test.ts @@ -0,0 +1,19 @@ +import { LocationsApi } from '../src'; +import { testClient } from './testClient'; +import { makeApiCall } from './testHelper'; + +describe('LocationsApi', () => { + let controller : LocationsApi; + + beforeAll(() => { + controller = new LocationsApi(testClient); + }); + + it('should ListLocations', async () => { + const response = await makeApiCall( + () => controller.listLocations() + ); + + expect(response.statusCode).toBe(200); + }); +}); diff --git a/test/testHelper.ts b/test/testHelper.ts new file mode 100644 index 00000000..b130785e --- /dev/null +++ b/test/testHelper.ts @@ -0,0 +1,30 @@ +export * from '@apimatic/test-utilities'; + +import { HttpClient } from '../src/clientAdapter'; +import { HttpClientInterface } from '../src/core'; +import { ApiError, ApiResponse, AbortError } from '../src'; + +export function httpClientInterface(): HttpClientInterface { + return async (request, requestOptions) => { + return await new HttpClient(AbortError).executeRequest(request, requestOptions); + }; +} + +export async function makeApiCall( + caller: () => Promise> +): Promise> { + try { + return await caller(); + } catch (error) { + if (error instanceof ApiError) { + return { + request: error.request, + statusCode: error.statusCode, + headers: error.headers, + result: error.result, + body: error.body + }; + } + throw error; + } +}