@sazito/client-sdk 1.2.10 → 1.2.12

package/README.md

@@ -261,7 +261,7 @@ The client instance exposes:
 | `orders` | `list`, `get` |
 | `invoices` | `get`, `create`, `refresh`, `addShippingAddress`, `addDiscountCode`, `assignShippingMethod`, `addDetails`, `addForm`, `addCredit`, `removeCredit`, `toggleCredit`, `getApplicableShippingMethods`, `clearInvoice` |
 | `shipping` | `createAddress`, `updateAddress` (legacy), `listAddresses`, `getAddress`, `getMethods`, `clearAddress` |
-| `payments` | `getMethods`, `create`, `initialize`, `verify`, `processStep`, `processStepForm`, `pollUntilSettled`, `clearPayment` |
+| `payments` | `getMethods`, `create`, `initialize`, `verify`, `verifyPaymentCallback`, `getPaymentStep`, `processStep`, `processStepForm`, `pollUntilSettled`, `clearPayment` |
 | `users` | `login`, `requestMobileOTP`, `verifyMobileOTP`, `requestEmailLogin`, `register`, `getCurrentUser`, `updateProfile`, `requestMobilePhoneUpdate`, `verifyMobilePhoneUpdate`, `forgotPassword`, `revivePassword`, `mergeUser` |
 | `search` | `query` |
 | `feedbacks` | `getSeed`, `createOrderRating`, `submitProductReview`, `getProductStatistics`, `getProductReviews`, `uploadReviewImages`, `list`, `create`, `get` |

package/dist/index.d.mts

@@ -12,6 +12,10 @@ interface RetryConfig {
 }
 interface SazitoConfig {
     domain: string;
+    /** Sazito API origin. Keeps the legacy SDK origin when omitted. */
+    apiBaseUrl?: string;
+    /** Payments collection path for deployments with a custom API version map. */
+    paymentsBasePath?: string;
     timeout?: number;
     retry?: RetryConfig;
     cache?: {
@@ -581,8 +585,10 @@ interface CheckoutShippingItem {
 interface CheckoutInvoice {
     invoiceItems: CheckoutInvoiceItem[];
     shippingItems: CheckoutShippingItem[];
-    netTotal: number;
-    finalTotal: number;
+    /** May be omitted by the payment verification response. */
+    netTotal?: number;
+    /** May be omitted by the payment verification response. */
+    finalTotal?: number;
     shippingTotal?: number;
     discountTotal?: number;
     creditTotal?: number;
@@ -637,6 +643,8 @@ interface Payment {
 }
 interface PaymentActionBase {
     message?: string;
+    /** Complete backend result before SDK normalization. */
+    raw?: JsonObject;
 }
 type PaymentAction = PaymentActionBase & ({
     action: 'POST';
@@ -661,6 +669,10 @@ type PaymentAction = PaymentActionBase & ({
     action: 'payment_fail_error' | 'show_error' | 'FAIL';
 } | {
     action: 'StockViolated';
+} | {
+    action: 'unknown';
+    backendAction: string;
+    raw: JsonObject;
 });
 interface PaymentCredentials {
     id: number;
@@ -683,6 +695,28 @@ interface PaymentStepInput {
     imageUrl?: string;
     code?: string;
 }
+type PaymentCallbackFieldValue = JsonValue | undefined;
+type PaymentCallbackFields = Record<string, PaymentCallbackFieldValue>;
+/** Raw gateway callback accepted by the SSR-compatible verification request. */
+interface VerifyPaymentCallbackInput {
+    paymentId: string | number;
+    paymentIdentifier: string;
+    /** Form/body fields are added first. */
+    body?: PaymentCallbackFields;
+    /** Query fields are added second and win when a name is duplicated. */
+    query?: PaymentCallbackFields;
+}
+/** Controls the repeated JSON status check after a `pending` callback result. */
+interface PaymentPollingOptions extends RequestOptions {
+    /** Delay before each request, including the first one. Defaults to 15 seconds. */
+    intervalMs?: number;
+    /** Overall polling deadline. Defaults to five minutes. */
+    pollingTimeoutMs?: number;
+    /** Optional maximum number of status requests. */
+    maxAttempts?: number;
+    /** Skip the initial delay when an immediate status check is desired. */
+    immediate?: boolean;
+}
 type PaymentStepFormValue = string | number | boolean | null | undefined;
 type PaymentStepFormFields = Record<string, PaymentStepFormValue>;
 
@@ -1015,6 +1049,7 @@ declare class HttpClient {
      */
     private getHeaders;
     private isMultipartBody;
+    private isFormUrlEncodedBody;
     /**
      * Check if status code should trigger a retry
      */
@@ -1312,8 +1347,9 @@ declare class ShippingAPI {
 declare class PaymentsAPI {
     private http;
     private credentials;
+    private paymentsBasePath;
     private readonly pinchedPayments;
-    constructor(http: HttpClient, credentials: CredentialsManager);
+    constructor(http: HttpClient, credentials: CredentialsManager, paymentsBasePath?: string);
     /**
      * Get list of payment methods for invoice
      */
@@ -1336,6 +1372,14 @@ declare class PaymentsAPI {
      * or pending if the gateway has not reported back yet).
      */
     verify(input?: PaymentStepInput, options?: RequestOptions): Promise<SazitoResponse<PaymentAction>>;
+    /**
+     * Verify a gateway callback using Sazito's SSR form contract. Body fields
+     * are written first, query fields second, and every field is wrapped as
+     * `payload[name]`. The validated path identifier is always written last.
+     */
+    verifyPaymentCallback(input: VerifyPaymentCallbackInput, options?: RequestOptions): Promise<SazitoResponse<PaymentAction>>;
+    /** Send one JSON payment status request. Used by pending polling only. */
+    getPaymentStep(options?: RequestOptions): Promise<SazitoResponse<PaymentAction>>;
     /**
      * Process payment step (for card-to-card or multi-step payments).
      *
@@ -1343,10 +1387,10 @@ declare class PaymentsAPI {
      */
     processStep(input: PaymentStepInput, options?: RequestOptions): Promise<SazitoResponse<PaymentAction>>;
     /**
-     * Shared core for the `process_payment_step` endpoint used by
-     * {@link initialize}, {@link verify} and {@link processStep}.
+     * Shared JSON core for initialization, status checks and multi-step payment
+     * actions. Gateway callback verification intentionally uses form encoding.
      */
-    private submitPaymentStep;
+    private submitJsonPaymentStep;
     /**
      * Process payment step in form mode (non-JSON content-type).
      */
@@ -1354,7 +1398,7 @@ declare class PaymentsAPI {
     /**
      * Poll payment state every 15 seconds until action changes from pending.
      */
-    pollUntilSettled(options?: RequestOptions, intervalMs?: number): Promise<SazitoResponse<PaymentAction>>;
+    pollUntilSettled(options?: PaymentPollingOptions, intervalMs?: number): Promise<SazitoResponse<PaymentAction>>;
     /**
      * Clear payment credentials
      */
@@ -1363,6 +1407,12 @@ declare class PaymentsAPI {
     private buildProcessStepFormData;
     private buildProcessStepBody;
     private appendFormValue;
+    private resolvePaymentCredentials;
+    private normalizePaymentId;
+    private paymentStepInputToCallbackFields;
+    private appendCallbackValue;
+    private withContentType;
+    private waitForPoll;
     /**
      * Post-process a `process_payment_step` response. The exact-JSON endpoint
      * returns an envelope `{ result: PaymentAction, error, error_code, status }`;
@@ -2441,4 +2491,4 @@ declare function transformAddToCartInput(variantId: number, quantity: number, fo
 declare function transformCreateCartInput(input: TransformValue): TransformObject;
 
 export { CredentialsManager, HttpClient, MemoryStorage, SazitoClient, TokenStorage, createBookingAPI as booking, createCartAPI as cart, createCategoriesAPI as categories, createCMSAPI as cms, createBookingAPI, createCMSAPI, createCartAPI, createCategoriesAPI, createDynamicFormsAPI, createEntityRoutesAPI, createFeedbacksAPI, createGeneralAPI, createImagesAPI, createInvoicesAPI, createMenuAPI, createOrdersAPI, createPaymentsAPI, createProductsAPI, createRegionsAPI, createSazitoClient, createSearchAPI, createShippingAPI, createUsersAPI, createVisitsAPI, createWalletAPI, createDynamicFormsAPI as dynamicForms, createEntityRoutesAPI as entityRoutes, createFeedbacksAPI as feedbacks, createGeneralAPI as general, createImagesAPI as images, createInvoicesAPI as invoices, createMenuAPI as menu, createOrdersAPI as orders, createPaymentsAPI as payments, createProductsAPI as products, createRegionsAPI as regions, createSearchAPI as search, createShippingAPI as shipping, toEnglishDigits, transformAddToCartInput, transformApiResponse, transformCartResponse, transformCreateCartInput, transformInvoiceResponse, transformProductListResponse, transformRequestKeys, transformResponseKeys, transformShippingAddressInput, createUsersAPI as users, createVisitsAPI as visits, createWalletAPI as wallet };
-export type { AddToCartInput, ApplicableShippingMethods, BlogPage, BlogPageEntityRoute, CMSPageEntityRoute, CMSPageType, CacheConfig, Cart, CartCredentials, CartProduct, CheckoutInvoice, CheckoutInvoiceItem, CheckoutOrder, CheckoutProductSnapshot, CheckoutShippingItem, City$1 as City, CmsPage, CookieOptions, CreateCartInput, CreateInvoiceInput, CreatePaymentInput, EntityRoute, EntityRouteResponse, EntityType, FormAttributeValue, Image, Invoice, InvoiceCredentials, InvoiceItem, InvoiceItemFormAttributes, InvoiceShippingAddress, InvoiceShippingAddressRegion, ItemShippingRate, JsonArray, JsonObject, JsonPrimitive, JsonValue, MenuItem, MenuNode, MenuTree, Order, OrderFilters, OrderInvoice, OrderInvoiceItem, OrderPublicId, OrderShippingItem, OrdersListResponse, PaginatedResponse, Payment, PaymentAction, PaymentCredentials, PaymentGateway, PaymentMethod, PaymentStatus, PaymentStepFormFields, PaymentStepFormValue, PaymentStepInput, Product, ProductAttribute, ProductAttributeValueObject, ProductCategory, ProductCategoryEntityRoute, ProductEntityRoute, ProductFilters, ProductSort, ProductVariant, RefreshInvoiceInput, Region$1 as Region, RequestOptions, RetryConfig, SazitoConfig, SazitoError, SazitoResponse, SchedulerBookingAttributes, SearchFilters, SearchResponse, ShippingAddress, ShippingAddressCity, ShippingAddressCredentials, ShippingAddressInput, ShippingAddressRegion, ShippingAssignment, ShippingItem, ShippingMethod, ShippingRate, StorageAdapter, Tag, UnknownEntityRoute, UploadedFormFileAttribute, User };
+export type { AddToCartInput, ApplicableShippingMethods, BlogPage, BlogPageEntityRoute, CMSPageEntityRoute, CMSPageType, CacheConfig, Cart, CartCredentials, CartProduct, CheckoutInvoice, CheckoutInvoiceItem, CheckoutOrder, CheckoutProductSnapshot, CheckoutShippingItem, City$1 as City, CmsPage, CookieOptions, CreateCartInput, CreateInvoiceInput, CreatePaymentInput, EntityRoute, EntityRouteResponse, EntityType, FormAttributeValue, Image, Invoice, InvoiceCredentials, InvoiceItem, InvoiceItemFormAttributes, InvoiceShippingAddress, InvoiceShippingAddressRegion, ItemShippingRate, JsonArray, JsonObject, JsonPrimitive, JsonValue, MenuItem, MenuNode, MenuTree, Order, OrderFilters, OrderInvoice, OrderInvoiceItem, OrderPublicId, OrderShippingItem, OrdersListResponse, PaginatedResponse, Payment, PaymentAction, PaymentCallbackFieldValue, PaymentCallbackFields, PaymentCredentials, PaymentGateway, PaymentMethod, PaymentPollingOptions, PaymentStatus, PaymentStepFormFields, PaymentStepFormValue, PaymentStepInput, Product, ProductAttribute, ProductAttributeValueObject, ProductCategory, ProductCategoryEntityRoute, ProductEntityRoute, ProductFilters, ProductSort, ProductVariant, RefreshInvoiceInput, Region$1 as Region, RequestOptions, RetryConfig, SazitoConfig, SazitoError, SazitoResponse, SchedulerBookingAttributes, SearchFilters, SearchResponse, ShippingAddress, ShippingAddressCity, ShippingAddressCredentials, ShippingAddressInput, ShippingAddressRegion, ShippingAssignment, ShippingItem, ShippingMethod, ShippingRate, StorageAdapter, Tag, UnknownEntityRoute, UploadedFormFileAttribute, User, VerifyPaymentCallbackInput };

package/dist/index.d.ts

@@ -12,6 +12,10 @@ interface RetryConfig {
 }
 interface SazitoConfig {
     domain: string;
+    /** Sazito API origin. Keeps the legacy SDK origin when omitted. */
+    apiBaseUrl?: string;
+    /** Payments collection path for deployments with a custom API version map. */
+    paymentsBasePath?: string;
     timeout?: number;
     retry?: RetryConfig;
     cache?: {
@@ -581,8 +585,10 @@ interface CheckoutShippingItem {
 interface CheckoutInvoice {
     invoiceItems: CheckoutInvoiceItem[];
     shippingItems: CheckoutShippingItem[];
-    netTotal: number;
-    finalTotal: number;
+    /** May be omitted by the payment verification response. */
+    netTotal?: number;
+    /** May be omitted by the payment verification response. */
+    finalTotal?: number;
     shippingTotal?: number;
     discountTotal?: number;
     creditTotal?: number;
@@ -637,6 +643,8 @@ interface Payment {
 }
 interface PaymentActionBase {
     message?: string;
+    /** Complete backend result before SDK normalization. */
+    raw?: JsonObject;
 }
 type PaymentAction = PaymentActionBase & ({
     action: 'POST';
@@ -661,6 +669,10 @@ type PaymentAction = PaymentActionBase & ({
     action: 'payment_fail_error' | 'show_error' | 'FAIL';
 } | {
     action: 'StockViolated';
+} | {
+    action: 'unknown';
+    backendAction: string;
+    raw: JsonObject;
 });
 interface PaymentCredentials {
     id: number;
@@ -683,6 +695,28 @@ interface PaymentStepInput {
     imageUrl?: string;
     code?: string;
 }
+type PaymentCallbackFieldValue = JsonValue | undefined;
+type PaymentCallbackFields = Record<string, PaymentCallbackFieldValue>;
+/** Raw gateway callback accepted by the SSR-compatible verification request. */
+interface VerifyPaymentCallbackInput {
+    paymentId: string | number;
+    paymentIdentifier: string;
+    /** Form/body fields are added first. */
+    body?: PaymentCallbackFields;
+    /** Query fields are added second and win when a name is duplicated. */
+    query?: PaymentCallbackFields;
+}
+/** Controls the repeated JSON status check after a `pending` callback result. */
+interface PaymentPollingOptions extends RequestOptions {
+    /** Delay before each request, including the first one. Defaults to 15 seconds. */
+    intervalMs?: number;
+    /** Overall polling deadline. Defaults to five minutes. */
+    pollingTimeoutMs?: number;
+    /** Optional maximum number of status requests. */
+    maxAttempts?: number;
+    /** Skip the initial delay when an immediate status check is desired. */
+    immediate?: boolean;
+}
 type PaymentStepFormValue = string | number | boolean | null | undefined;
 type PaymentStepFormFields = Record<string, PaymentStepFormValue>;
 
@@ -1015,6 +1049,7 @@ declare class HttpClient {
      */
     private getHeaders;
     private isMultipartBody;
+    private isFormUrlEncodedBody;
     /**
      * Check if status code should trigger a retry
      */
@@ -1312,8 +1347,9 @@ declare class ShippingAPI {
 declare class PaymentsAPI {
     private http;
     private credentials;
+    private paymentsBasePath;
     private readonly pinchedPayments;
-    constructor(http: HttpClient, credentials: CredentialsManager);
+    constructor(http: HttpClient, credentials: CredentialsManager, paymentsBasePath?: string);
     /**
      * Get list of payment methods for invoice
      */
@@ -1336,6 +1372,14 @@ declare class PaymentsAPI {
      * or pending if the gateway has not reported back yet).
      */
     verify(input?: PaymentStepInput, options?: RequestOptions): Promise<SazitoResponse<PaymentAction>>;
+    /**
+     * Verify a gateway callback using Sazito's SSR form contract. Body fields
+     * are written first, query fields second, and every field is wrapped as
+     * `payload[name]`. The validated path identifier is always written last.
+     */
+    verifyPaymentCallback(input: VerifyPaymentCallbackInput, options?: RequestOptions): Promise<SazitoResponse<PaymentAction>>;
+    /** Send one JSON payment status request. Used by pending polling only. */
+    getPaymentStep(options?: RequestOptions): Promise<SazitoResponse<PaymentAction>>;
     /**
      * Process payment step (for card-to-card or multi-step payments).
      *
@@ -1343,10 +1387,10 @@ declare class PaymentsAPI {
      */
     processStep(input: PaymentStepInput, options?: RequestOptions): Promise<SazitoResponse<PaymentAction>>;
     /**
-     * Shared core for the `process_payment_step` endpoint used by
-     * {@link initialize}, {@link verify} and {@link processStep}.
+     * Shared JSON core for initialization, status checks and multi-step payment
+     * actions. Gateway callback verification intentionally uses form encoding.
      */
-    private submitPaymentStep;
+    private submitJsonPaymentStep;
     /**
      * Process payment step in form mode (non-JSON content-type).
      */
@@ -1354,7 +1398,7 @@ declare class PaymentsAPI {
     /**
      * Poll payment state every 15 seconds until action changes from pending.
      */
-    pollUntilSettled(options?: RequestOptions, intervalMs?: number): Promise<SazitoResponse<PaymentAction>>;
+    pollUntilSettled(options?: PaymentPollingOptions, intervalMs?: number): Promise<SazitoResponse<PaymentAction>>;
     /**
      * Clear payment credentials
      */
@@ -1363,6 +1407,12 @@ declare class PaymentsAPI {
     private buildProcessStepFormData;
     private buildProcessStepBody;
     private appendFormValue;
+    private resolvePaymentCredentials;
+    private normalizePaymentId;
+    private paymentStepInputToCallbackFields;
+    private appendCallbackValue;
+    private withContentType;
+    private waitForPoll;
     /**
      * Post-process a `process_payment_step` response. The exact-JSON endpoint
      * returns an envelope `{ result: PaymentAction, error, error_code, status }`;
@@ -2441,4 +2491,4 @@ declare function transformAddToCartInput(variantId: number, quantity: number, fo
 declare function transformCreateCartInput(input: TransformValue): TransformObject;
 
 export { CredentialsManager, HttpClient, MemoryStorage, SazitoClient, TokenStorage, createBookingAPI as booking, createCartAPI as cart, createCategoriesAPI as categories, createCMSAPI as cms, createBookingAPI, createCMSAPI, createCartAPI, createCategoriesAPI, createDynamicFormsAPI, createEntityRoutesAPI, createFeedbacksAPI, createGeneralAPI, createImagesAPI, createInvoicesAPI, createMenuAPI, createOrdersAPI, createPaymentsAPI, createProductsAPI, createRegionsAPI, createSazitoClient, createSearchAPI, createShippingAPI, createUsersAPI, createVisitsAPI, createWalletAPI, createDynamicFormsAPI as dynamicForms, createEntityRoutesAPI as entityRoutes, createFeedbacksAPI as feedbacks, createGeneralAPI as general, createImagesAPI as images, createInvoicesAPI as invoices, createMenuAPI as menu, createOrdersAPI as orders, createPaymentsAPI as payments, createProductsAPI as products, createRegionsAPI as regions, createSearchAPI as search, createShippingAPI as shipping, toEnglishDigits, transformAddToCartInput, transformApiResponse, transformCartResponse, transformCreateCartInput, transformInvoiceResponse, transformProductListResponse, transformRequestKeys, transformResponseKeys, transformShippingAddressInput, createUsersAPI as users, createVisitsAPI as visits, createWalletAPI as wallet };
-export type { AddToCartInput, ApplicableShippingMethods, BlogPage, BlogPageEntityRoute, CMSPageEntityRoute, CMSPageType, CacheConfig, Cart, CartCredentials, CartProduct, CheckoutInvoice, CheckoutInvoiceItem, CheckoutOrder, CheckoutProductSnapshot, CheckoutShippingItem, City$1 as City, CmsPage, CookieOptions, CreateCartInput, CreateInvoiceInput, CreatePaymentInput, EntityRoute, EntityRouteResponse, EntityType, FormAttributeValue, Image, Invoice, InvoiceCredentials, InvoiceItem, InvoiceItemFormAttributes, InvoiceShippingAddress, InvoiceShippingAddressRegion, ItemShippingRate, JsonArray, JsonObject, JsonPrimitive, JsonValue, MenuItem, MenuNode, MenuTree, Order, OrderFilters, OrderInvoice, OrderInvoiceItem, OrderPublicId, OrderShippingItem, OrdersListResponse, PaginatedResponse, Payment, PaymentAction, PaymentCredentials, PaymentGateway, PaymentMethod, PaymentStatus, PaymentStepFormFields, PaymentStepFormValue, PaymentStepInput, Product, ProductAttribute, ProductAttributeValueObject, ProductCategory, ProductCategoryEntityRoute, ProductEntityRoute, ProductFilters, ProductSort, ProductVariant, RefreshInvoiceInput, Region$1 as Region, RequestOptions, RetryConfig, SazitoConfig, SazitoError, SazitoResponse, SchedulerBookingAttributes, SearchFilters, SearchResponse, ShippingAddress, ShippingAddressCity, ShippingAddressCredentials, ShippingAddressInput, ShippingAddressRegion, ShippingAssignment, ShippingItem, ShippingMethod, ShippingRate, StorageAdapter, Tag, UnknownEntityRoute, UploadedFormFileAttribute, User };
+export type { AddToCartInput, ApplicableShippingMethods, BlogPage, BlogPageEntityRoute, CMSPageEntityRoute, CMSPageType, CacheConfig, Cart, CartCredentials, CartProduct, CheckoutInvoice, CheckoutInvoiceItem, CheckoutOrder, CheckoutProductSnapshot, CheckoutShippingItem, City$1 as City, CmsPage, CookieOptions, CreateCartInput, CreateInvoiceInput, CreatePaymentInput, EntityRoute, EntityRouteResponse, EntityType, FormAttributeValue, Image, Invoice, InvoiceCredentials, InvoiceItem, InvoiceItemFormAttributes, InvoiceShippingAddress, InvoiceShippingAddressRegion, ItemShippingRate, JsonArray, JsonObject, JsonPrimitive, JsonValue, MenuItem, MenuNode, MenuTree, Order, OrderFilters, OrderInvoice, OrderInvoiceItem, OrderPublicId, OrderShippingItem, OrdersListResponse, PaginatedResponse, Payment, PaymentAction, PaymentCallbackFieldValue, PaymentCallbackFields, PaymentCredentials, PaymentGateway, PaymentMethod, PaymentPollingOptions, PaymentStatus, PaymentStepFormFields, PaymentStepFormValue, PaymentStepInput, Product, ProductAttribute, ProductAttributeValueObject, ProductCategory, ProductCategoryEntityRoute, ProductEntityRoute, ProductFilters, ProductSort, ProductVariant, RefreshInvoiceInput, Region$1 as Region, RequestOptions, RetryConfig, SazitoConfig, SazitoError, SazitoResponse, SchedulerBookingAttributes, SearchFilters, SearchResponse, ShippingAddress, ShippingAddressCity, ShippingAddressCredentials, ShippingAddressInput, ShippingAddressRegion, ShippingAssignment, ShippingItem, ShippingMethod, ShippingRate, StorageAdapter, Tag, UnknownEntityRoute, UploadedFormFileAttribute, User, VerifyPaymentCallbackInput };