feat: improved typings for OrdersCreateRequest

.changeset/warm-tables-fry.md

@@ -0,0 +1,5 @@
+---
+"@hyperse/paypal-node-sdk": patch
+---
+
+improved typings for OrdersCreateRequest

package.json

@@ -79,10 +79,10 @@
   "devDependencies": {
     "@changesets/changelog-git": "0.2.0",
     "@changesets/changelog-github": "0.5.0",
-    "@changesets/cli": "2.27.1",
+    "@changesets/cli": "2.27.5",
     "@commitlint/cli": "19.3.0",
     "@commitlint/config-conventional": "19.2.2",
-    "@hyperse/eslint-config-hyperse": "^1.0.4",
+    "@hyperse/eslint-config-hyperse": "^1.0.7",
     "@swc/core": "1.5.25",
     "@types/node": "20.14.2",
     "commitizen": "4.3.0",

src/orders/ordersCreateRequest.ts

@@ -3,14 +3,24 @@ import {
   type BaseOrderHeaders,
   type CheckoutPaymentIntent,
   type OrderApplicationContext,
-  type Payer,
+  PaymentSourceRequest,
   type PurchaseUnitRequest,
 } from '../types/type-order.js';
 
 export type OrdersCreateRequestBody = {
   intent: CheckoutPaymentIntent;
-  payer?: Payer;
+  /**
+   * The payment source definition.
+   */
+  payment_source?: PaymentSourceRequest;
+  /**
+   * An array of purchase units. Each purchase unit establishes a contract between a payer and the payee.
+   * Each purchase unit represents either a full or partial order that the payer intends to purchase from the payee.
+   */
   purchase_units: PurchaseUnitRequest[];
+  /**
+   * Customizes the payer experience during the approval process for the payment with PayPal.
+   */
   application_context?: OrderApplicationContext;
 };
 

src/types/type-order.ts

@@ -398,6 +398,110 @@ export interface PurchaseUnit {
   soft_descriptor: string;
 }
 
+// https://developer.paypal.com/docs/api/orders/v2/#definition-customized_payment_source_2
+export interface PaymentSourceRequest {
+  /**
+   * The tokenized payment source to fund a payment.
+   */
+  token?: {
+    /**
+     * The PayPal-generated ID for the token.
+     */
+    id: string;
+    /**
+     * The tokenization method that generated the ID.
+     */
+    type: string;
+  };
+
+  /**
+   * Indicates that PayPal Wallet is the payment source.
+   * Main use of this selection is to provide additional instructions associated with this choice like vaulting.
+   */
+  paypal?: {
+    /**
+     * Additional attributes associated with the use of this wallet.
+     */
+    attributes?: {
+      /**
+       * Attributes used to provide the instructions during vaulting of the PayPal Wallet.
+       */
+      vault?: {
+        /**
+         * Defines how and when the payment source gets vaulted.
+         * 'ON_SUCCESS'
+         */
+        store_in_vault?: string;
+        /**
+         * The usage type associated with the PayPal payment token.
+         */
+        usage_type: string;
+      };
+      /**
+       * The details about a customer in PayPal's system of record.
+       */
+      customer?: {
+        /**
+         * The unique ID for a customer generated by PayPal.
+         */
+        id?: string;
+        /**
+         * Email address of the buyer as provided to the merchant or on file with the merchant. Email Address is required if you are processing the transaction using PayPal Guest Processing which is offered to select partners and merchants.
+         * For all other use cases we do not expect partners/merchant to send email_address of their customer.
+         */
+        email_address?: string;
+        /**
+         * Merchants and partners may already have a data-store where their customer information is persisted.
+         * Use merchant_customer_id to associate the PayPal-generated customer.id to your representation of a customer.
+         */
+        merchant_customer_id?: string;
+      };
+    };
+    /**
+     * Customizes the payer experience during the approval process for payment with PayPal.
+     */
+    experience_context?: {
+      /**
+       * The label that overrides the business name in the PayPal account on the PayPal site. The pattern is defined by an external party and supports Unicode
+       */
+      brand_name?: string;
+      /**
+       * The BCP 47-formatted locale of pages that the PayPal payment experience shows. PayPal supports a five-character code.
+       * For example, da-DK, he-IL, id-ID, ja-JP, no-NO, pt-BR, ru-RU, sv-SE, th-TH, zh-CN, zh-HK, or zh-TW.
+       */
+      locale?: string;
+      /**
+       * The type of landing page to show on the PayPal site for customer checkout.
+       * @default "NO_PREFERENCE"
+       */
+      landing_page?: 'LOGIN' | 'GUEST_CHECKOUT' | 'NO_PREFERENCE';
+      /**
+       * The location from which the shipping address is derived.
+       * @default "GET_FROM_FILE"
+       */
+      shipping_preference?: ShippingPreference;
+      /**
+       * Configures a Continue or Pay Now checkout flow.
+       * @default `CONTINUE`
+       */
+      user_action?: UserAction;
+      /**
+       * The merchant-preferred payment methods.
+       * @default 'UNRESTRICTED'
+       */
+      payment_method_preference?: 'UNRESTRICTED' | 'IMMEDIATE_PAYMENT_REQUIRED';
+      /**
+       * The URL where the customer will be redirected upon approving a payment.
+       */
+      return_url?: string;
+      /**
+       * The URL where the customer will be redirected upon cancelling the payment approval.
+       */
+      cancel_url?: string;
+    };
+  };
+}
+
 // https://developer.paypal.com/docs/api/orders/v2/#definition-purchase_unit_request
 export interface PurchaseUnitRequest {
   amount: AmountWithBreakdown;
@@ -463,21 +567,22 @@ export interface PaymentSourceResponse {
   card: CardResponse;
 }
 
-// https://developer.paypal.com/docs/api/orders/v2/#definition-order_application_context
+/**
+ * Customize the payer experience during the approval process for the payment with PayPal.
+ * @see {@link https://developer.paypal.com/docs/api/orders/v2/#definition-application_context}
+ */
 export interface OrderApplicationContext {
-  brand_name?: string;
-  locale?: string;
-  landing_page?: LandingPage;
-  shipping_preference?: ShippingPreference;
-  user_action?: UserAction;
-  payment_method?: PaymentMethod;
-  return_url?: string;
-  cancel_url?: string;
+  /**
+   * Provides additional details to process a payment using a payment_source that has been stored or is intended to be stored (also referred to as stored_credential or card-on-file).
+   * Parameter compatibility:
+   * payment_type=ONE_TIME is compatible only with payment_initiator=CUSTOMER.
+   * usage=FIRST is compatible only with payment_initiator=CUSTOMER.
+   * previous_transaction_reference or previous_network_transaction_reference is compatible only with payment_initiator=MERCHANT.
+   * Only one of the parameters - previous_transaction_reference and previous_network_transaction_reference - can be present in the request.
+   */
   stored_payment_source?: StoredPaymentSource;
 }
 
-export type LandingPage = 'LOGIN' | 'BILLING' | 'NO_PREFERENCE';
-
 export type ShippingPreference =
   | 'GET_FROM_FILE'
   | 'NO_SHIPPING'