oneentry 1.0.159 → 1.0.161

package/esm/orders/ordersApi.js

@@ -0,0 +1,288 @@
+import AsyncModules from '../base/asyncModules.js';
+import createSchemaLoader from '../base/lazySchema.js';
+const schema = createSchemaLoader(() => import('./ordersSchemas.js'));
+/**
+ * Controllers for working with orders.
+ * @handle /api/content/orders-storage
+ * @module OrdersApi
+ * @description This module provides methods for working with orders, including retrieving, creating, and updating orders in the order storage.
+ */
+export default class OrdersApi extends AsyncModules {
+    /**
+     * Constructs an instance of the OrdersApi class.
+     * @param {StateModule} state - The state module containing the necessary information for making API calls.
+     * @description Constructor initializes the OrdersApi with a given state.
+     */
+    constructor(state) {
+        super(state);
+        this._url = state.url + '/api/content/orders-storage';
+        this._ordersUrl = state.url + '/api/content/orders';
+    }
+    /**
+     * Getting all the order storage objects.
+     * @handleName getAllOrdersStorage
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @param {number} [offset] - Optional parameter for pagination. Default: 0.
+     * @param {number} [limit] - Optional parameter for pagination. Default: 30.
+     * @returns {Promise<IOrdersEntity[] | IError>} Returns an array of order storage objects.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description This method requires user authorization.
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/orders/getAllOrdersStorage getAllOrdersStorage} documentation.
+     */
+    async getAllOrdersStorage(langCode = this.state.lang, offset = 0, limit = 30) {
+        const result = await this._fetchGet(`?langCode=${langCode}&limit=${limit}&offset=${offset}`);
+        return this._normalizeData(result);
+    }
+    /**
+     * Getting all orders from the orders storage object created by the user.
+     * @handleName getAllOrdersByMarker
+     * @param {string} marker - Textual identifier of the order storage object. Example: "order_storage_1".
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @param {number} [offset] - Offset parameter. Default: 0.
+     * @param {number} [limit] - Limit parameter. Default: 30.
+     * @returns {Promise<IOrdersByMarkerEntity | IError>} Returns an object with the orders.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description This method requires user authorization.
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/orders/getAllOrdersByMarker getAllOrdersByMarker} documentation.
+     */
+    async getAllOrdersByMarker(marker, langCode = this.state.lang, offset = 0, limit = 30) {
+        const result = await this._fetchGet(`/marker/${marker}/orders?langCode=${langCode}&limit=${limit}&offset=${offset}`);
+        // Validate response if validation is enabled
+        const validated = await this._validateResponse(result, schema('OrdersResponseSchema'));
+        return this._normalizeData(validated);
+    }
+    /**
+     * Retrieve one order storage object by marker.
+     * @handleName getOrdersStorageByMarker
+     * @param {string} marker - Marker of the order object. Example: "order_storage_1".
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {Promise<IOrdersEntity | IError>} Return object of order information.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description This method requires user authorization.
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/orders/getOrdersStorageByMarker getOrdersStorageByMarker} documentation.
+     */
+    async getOrdersStorageByMarker(marker, langCode = this.state.lang) {
+        const result = await this._fetchGet(`/marker/${marker}?langCode=${langCode}`);
+        return this._normalizeData(result);
+    }
+    /**
+     * Getting a single order from the order storage object created by the user.
+     * @handleName getOrderByMarkerAndId
+     * @param {string} marker - The text identifier of the order storage object. Example: "order_storage_1".
+     * @param {number} id - ID of the order object. Example: 12345.
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {Promise<IOrderByMarkerEntity | IError>} Returns an object with the order.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description This method requires user authorization.
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/orders/getOrderByMarkerAndId getOrderByMarkerAndId} documentation.
+     */
+    async getOrderByMarkerAndId(marker, id, langCode = this.state.lang) {
+        const result = await this._fetchGet(`/marker/${marker}/orders/${id}?langCode=${langCode}`);
+        // Validate response if validation is enabled
+        const validated = await this._validateResponse(result, schema('OrderEntitySchema'));
+        return this._normalizeData(validated);
+    }
+    /**
+     * Preview order calculation with discounts and coupons (without saving).
+     * @handleName previewOrder
+     * @param {ICreateOrderPreview} body - Order preview body.
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {Promise<IOrderPreviewResponse | IError>} Returns an object with the order preview.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description This method requires user authorization.
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/orders/previewOrder previewOrder} documentation.
+     */
+    async previewOrder(body, langCode = this.state.lang) {
+        const result = await this._fetchPost(`/orders/preview?langCode=${langCode}`, body);
+        return this._normalizeData(result);
+    }
+    /**
+     * Creation of an order in the order storage.
+     * @handleName createOrder
+     * @param {string} marker - Textual identifier of the order storage object. Example: "order_storage_1".
+     * @param {IOrderData} body - Object for creating an order.
+     * @example
+        {
+          "formIdentifier": "bar-orders-form",
+          "paymentAccountIdentifier": "usd-payment",
+          "formData": {
+            "marker": "name_1",
+            "value": "Name",
+            "type": "string"
+          },
+          "products": [
+            {
+            "productId": 1,
+            "quantity": 2
+            }
+          ]
+        }
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {Promise<IBaseOrdersEntity | IError>} Returns an object with the created order.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description This method requires user authorization.
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/orders/createOrder createOrder} documentation.
+     */
+    async createOrder(marker, body, langCode = this.state.lang) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const formData = {};
+        formData[langCode] = Array.isArray(body.formData)
+            ? body.formData
+            : [body.formData];
+        body.formData = formData;
+        const result = await this._fetchPost(`/marker/${marker}/orders`, body);
+        // Validate response if validation is enabled
+        const validated = await this._validateResponse(result, schema('CreateOrderResponseSchema'));
+        return this._normalizeData(validated);
+    }
+    /**
+     * Changing an order in the orders storage
+     * @handleName updateOrderByMarkerAndId
+     * @param {string} marker - The text identifier of the order storage object. Example: "order_storage_1".
+     * @param {number} id - ID of the order object. Example: 12345.
+     * @param {IOrderData} body - Object for updating an order.
+     * @example
+        {
+          "formIdentifier": "bar-orders-form",
+          "paymentAccountIdentifier": "usd-payment",
+          "formData": {
+            "marker": "name_1",
+            "value": "Name",
+            "type": "string"
+          },
+          "products": [
+            {
+            "productId": 1,
+            "quantity": 2
+            }
+          ],
+          "currency": "USD"
+        }
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {Promise<IBaseOrdersEntity | IError>} Returns an object with the updated order.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description This method requires user authorization.
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/orders/updateOrderByMarkerAndId updateOrderByMarkerAndId} documentation.
+     */
+    async updateOrderByMarkerAndId(marker, id, body, langCode = this.state.lang) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const formData = {};
+        formData[langCode] = Array.isArray(body.formData)
+            ? body.formData
+            : [body.formData];
+        body.formData = formData;
+        const result = await this._fetchPut(`/marker/${marker}/orders/${id}?langCode=${langCode}`, body);
+        // Validate response if validation is enabled
+        const validated = await this._validateResponse(result, schema('UpdateOrderResponseSchema'));
+        return this._normalizeData(validated);
+    }
+    /**
+     * Get all orders statuses by Storage marker
+     * @handleName getAllStatusesByStorageMarker
+     * @param {string} marker - Textual identifier of the order storage object. Example: "order_storage_1".
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @param {number} [offset] - Offset parameter. Default: 0.
+     * @param {number} [limit] - Limit parameter. Default: 30.
+     * @returns {Promise<IOrderStatus[] | IError>} Returns an object with the orders statuses.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/orders/getAllStatusesByStorageMarker getAllStatusesByStorageMarker} documentation.
+     */
+    async getAllStatusesByStorageMarker(marker, langCode = this.state.lang, offset = 0, limit = 30) {
+        const query = {
+            langCode,
+            offset,
+            limit,
+        };
+        const data = await this._fetchGet(`/marker/${marker}/order-statuses?` + this._queryParamsToString(query));
+        return this._normalizeData(data);
+    }
+    /**
+     * Get all refund requests for an order.
+     * @handleName getRefunds
+     * @param {number} id - Order id. Example: 1.
+     * @returns {Promise<IRefundRequest[] | IError>} Returns array of refund requests.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @see {@link https://js-sdk.oneentry.cloud/docs/orders/getRefunds getRefunds} documentation.
+     */
+    async getRefunds(id) {
+        const data = await this._withOrdersUrl(() => this._fetchGet(`/${id}/refund`));
+        return this._normalizeData(data);
+    }
+    /**
+     * Create a refund request for an order.
+     * @handleName createRefundRequest
+     * @param {number} id - Order id. Example: 1.
+     * @param {ICreateRefundRequest} body - Refund request body.
+     * @returns {Promise<boolean | IError>} Returns true if the refund request was created successfully.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @see {@link https://js-sdk.oneentry.cloud/docs/orders/createRefundRequest createRefundRequest} documentation.
+     */
+    async createRefundRequest(id, body) {
+        const data = await this._withOrdersUrl(() => this._fetchPost(`/${id}/refund`, body));
+        return this._normalizeData(data);
+    }
+    /**
+     * Cancel a refund request for an order.
+     * @handleName cancelRefundRequest
+     * @param {number} id - Order id. Example: 1.
+     * @returns {Promise<boolean | IError>} Returns true if the refund request was cancelled successfully.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @see {@link https://js-sdk.oneentry.cloud/docs/orders/cancelRefundRequest cancelRefundRequest} documentation.
+     */
+    async cancelRefundRequest(id) {
+        const data = await this._withOrdersUrl(() => this._fetchDelete(`/${id}/refund`));
+        return this._normalizeData(data);
+    }
+    /**
+     * Semantic (vector) search for the current user's orders.
+     * @handleName getOrdersByVectorSearch
+     * @param {IOrdersVectorSearch} body - Vector search body. Example: `{ queryText: "winter jacket" }`.
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @param {number} [offset] - Parameter for pagination. Default: 0.
+     * @param {number} [limit] - Parameter for pagination. Default: 30.
+     * @returns {Promise<IOrdersByMarkerEntity | IError>} Returns an object with an array of found orders and total count.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description This method performs a semantic (vector) search over the orders of the authorized user. It requires user authorization.
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/orders/getOrdersByVectorSearch getOrdersByVectorSearch} documentation.
+     */
+    async getOrdersByVectorSearch(body, langCode = this.state.lang, offset = 0, limit = 30) {
+        const query = {
+            langCode,
+            offset,
+            limit,
+        };
+        const data = await this._withOrdersUrl(() => this._fetchPost(`/vector/search?` + this._queryParamsToString(query), body));
+        return this._normalizeData(data, langCode);
+    }
+    /**
+     * Runs a fetch against the `/orders` base URL instead of the default
+     * `/orders-storage`, then restores the original URL.
+     *
+     * Refund endpoints live under `/api/content/orders`, while this class is based
+     * on `/api/content/orders-storage`. The helper swaps `_url` for the duration of
+     * the call and restores it in `finally`, so the base URL is restored even if
+     * the request throws.
+     * @param {() => Promise<T>} fetcher - Thunk performing the fetch call.
+     * @returns {Promise<T>} The fetcher result.
+     * @template T
+     */
+    async _withOrdersUrl(fetcher) {
+        const savedUrl = this._url;
+        this._url = this._ordersUrl;
+        try {
+            return await fetcher();
+        }
+        finally {
+            this._url = savedUrl;
+        }
+    }
+}