idosell 0.4.38 → 0.4.41

package/README.md

@@ -2,8 +2,6 @@
 
 This package wraps around the Idosell REST Api to make it easier to use by implementing chainable options, more intuitive methods and helpers to format requests more easily. [Official Idosell documentation](https://idosell.readme.io/docs) is still applicable for the most part.
 
-Visit [This page](https://idosell-converter.vercel.app/) for more detailed usage and examples.
-
 [![npm version](https://img.shields.io/npm/v/idosell.svg)](https://www.npmjs.com/package/idosell)
 
 ## Basic use
@@ -17,7 +15,7 @@ const idosellRequest = idosell('SHOP_URL', 'API_KEY', API_VERSION)
 
 **API_KEY** can be obtained in your Idosell panel.
 **SHOP_URL** is the base URI of your shop. 
-**API_VERSION** version of the API to call, current default version is **v7**
+**API_VERSION** version of the API to call, current default version is **v8**
 Here are some examples:
 ```
 https://yourdomain.com
@@ -353,6 +351,26 @@ const orderRequest = idosellRequest.searchOrders.ordersSerialNumbers([123, 456,
 // Will return Object: { ordersSerialNumbers: [ 123, 456, 789 ] }
 ```
 
+## Webhooks
+
+The package provides a convenient `webhooks` helper to handle Idosell webhook events with full TypeScript typings.
+
+```javascript
+import { webhooks, type IaiWebhookHeaders } from "idosell";
+
+// Validate incoming webhook request headers and handle events
+webhooks
+  .validateHeaders((headers) => headers.token === TOKEN) // header validation
+  .on("productUpdated", ({ headers, body }) => {
+    console.log({ panelId: headers.panelId, code: body.results[0].productDisplayedCode });
+  })
+  .on("orderCreated", ({ headers, body }) => {
+    console.log({ panelId: headers.panelId, order: body.Results[0].orderSerialNumber });
+  })
+  .handle(request) // process the request
+  .catch(console.error); // standard error handling
+```
+
 ## Examples
 
-Read documentation from this package and more examples on [This page](https://idosell-converter.vercel.app/examples)
+Read documentation from this package and more examples on [This page](https://idosell-converter.vercel.app)

package/changelog.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.41] - 2025-06-07
+### Added
+- Added webook support
+- Added LANG_ID enumerator
+- Added mapProductParameters utils helper
+
 
 ## [0.4.38] - 2025-06-03
 ### Changed

package/dist/app.d.ts

@@ -1,3 +1,11 @@
+import type {
+    GetProductsResponse,
+    GetRmaResponse,
+    GetReturnsResponse,
+    GetOrdersResponse,
+    GetClientsResponse,
+} from "./responses.d.ts";
+
 export interface ExecutableDumpParams {
 	url: string;
 	method: string;
@@ -104,4 +112,135 @@ export interface IdosellErrorFaultStructure {
 	faultString: string;
 }
 
-export {};
+// ─── Final normalized shape ──────────────────────────────────────────────────
+
+export interface NormalizedIaiRequest<T = unknown> {
+    headers: IaiWebhookHeaders;
+    body: T;
+}
+
+export declare const WEBHOOK_OBJECT_TYPE: {
+    readonly CLIENT: "client";
+    readonly PRODUCT: "product";
+    readonly ORDER: "order";
+    readonly RETURN: "return";
+    readonly RMA: "rma";
+};
+
+export declare const WEBHOOK_EVENT_TYPE: {
+    readonly CLIENT_CREATED: "clientCreated";
+    readonly CLIENT_UPDATED: "clientUpdated";
+    readonly PRODUCT_CREATED: "productCreated";
+    readonly PRODUCT_UPDATED: "productUpdated";
+    readonly PRODUCT_PRICE_UPDATED: "productPriceUpdated";
+    readonly PRODUCT_STOCK_UPDATED: "productStockUpdated";
+    readonly PRODUCT_DISPOSITION_UPDATED: "productDispositionUpdated";
+    readonly ORDER_CREATED: "orderCreated";
+    readonly ORDER_UPDATED: "orderUpdated";
+    readonly ORDER_PAID: "orderPaid";
+    readonly ORDER_STATUS_UPDATED: "orderStatusUpdated";
+    readonly ORDER_PACKAGE_CREATED: "orderPackageCreated";
+    readonly ORDER_FILES_CREATED: "orderFilesCreated";
+    readonly ORDER_SALE_DOCUMENT_CREATED: "orderSaleDocumentCreated";
+    readonly ORDER_SALE_DOCUMENT_UPDATED: "orderSaleDocumentUpdated";
+    readonly ORDER_SENT: "orderSent";
+    readonly ORDER_DELIVERED: "orderDelivered";
+    readonly ORDER_CANCELED: "orderCanceled";
+    readonly RETURN_CREATED: "returnCreated";
+    readonly RETURN_UPDATED: "returnUpdated";
+    readonly RETURN_FUNDS_CONFIRMED: "returnFundsConfirmed";
+    readonly RETURN_PACKAGE_CREATED: "returnPackageCreated";
+    readonly RETURN_CONFIRMED: "returnConfirmed";
+    readonly RETURN_CANCELED: "returnCanceled";
+    readonly RMA_CREATED: "rmaCreated";
+    readonly RMA_UPDATED: "rmaUpdated";
+    readonly RMA_PACKAGE_CREATED: "rmaPackageCreated";
+    readonly RMA_APPROVED: "rmaApproved";
+    readonly RMA_REJECTED: "rmaRejected";
+};
+
+export type WebhookObjectType = typeof WEBHOOK_OBJECT_TYPE[keyof typeof WEBHOOK_OBJECT_TYPE];
+export type WebhookEventType = typeof WEBHOOK_EVENT_TYPE[keyof typeof WEBHOOK_EVENT_TYPE];
+
+interface ObjectBodyMap {
+    "client": GetClientsResponse;
+    "product": GetProductsResponse;
+    "order": GetOrdersResponse;
+    "return": GetReturnsResponse;
+    "rma": GetRmaResponse;
+}
+
+interface EventObjectMap {
+    "clientCreated": "client";
+    "clientUpdated": "client";
+    "productCreated": "product";
+    "productUpdated": "product";
+    "productPriceUpdated": "product";
+    "productStockUpdated": "product";
+    "productDispositionUpdated": "product";
+    "orderCreated": "order";
+    "orderUpdated": "order";
+    "orderPaid": "order";
+    "orderStatusUpdated": "order";
+    "orderPackageCreated": "order";
+    "orderFilesCreated": "order";
+    "orderSaleDocumentCreated": "order";
+    "orderSaleDocumentUpdated": "order";
+    "orderSent": "order";
+    "orderDelivered": "order";
+    "orderCanceled": "order";
+    "returnCreated": "return";
+    "returnUpdated": "return";
+    "returnFundsConfirmed": "return";
+    "returnPackageCreated": "return";
+    "returnConfirmed": "return";
+    "returnCanceled": "return";
+    "rmaCreated": "rma";
+    "rmaUpdated": "rma";
+    "rmaPackageCreated": "rma";
+    "rmaApproved": "rma";
+    "rmaRejected": "rma";
+}
+
+// ─── Parsed & renamed headers ────────────────────────────────────────────────
+
+export interface IaiWebhookHeaders {
+    token: string;
+    apiVersion: number;
+    eventTime: Date;
+    objectType: WebhookObjectType;
+    eventType: WebhookEventType;
+    eventUid: string;
+    panelId: number;
+    signature: string;
+    webhookTime: Date;
+}
+
+export interface WebhookContext<E extends WebhookEventType> {
+    headers: IaiWebhookHeaders;
+    body: ObjectBodyMap[EventObjectMap[E]];
+}
+
+export type WebhookHandler<E extends WebhookEventType> =
+    (ctx: WebhookContext<E>) => Promise<void> | void;
+
+export type HeaderValidator =
+    (headers: IaiWebhookHeaders) => Promise<boolean> | boolean;
+
+export type DispatchResult =
+    | { matched: true; eventType: WebhookEventType }
+    | { matched: false; eventType: string }
+    | { matched: false; eventType: null; reason: "validation_failed" };
+
+export declare class WebhookChain {
+    validateHeaders(validator: HeaderValidator): this;
+    on<E extends WebhookEventType>(eventType: E, handler: WebhookHandler<E>): this;
+    handle(req: import("node:http").IncomingMessage | Request): Promise<DispatchResult>;
+}
+
+export type Webhooks = {
+    validateHeaders(validator: HeaderValidator): WebhookChain;
+    on<E extends WebhookEventType>(eventType: E, handler: WebhookHandler<E>): WebhookChain;
+};
+
+export {};

package/dist/enums.d.ts

@@ -398,18 +398,44 @@ declare enum PRODUCE_SIZE_INDEX {
     ID = "sizeId",
     IAI_CODE = "iaiCode"
 }
-declare const ENUMS: {
-    PRODUCTS_RETURN_ELEMENTS: typeof PRODUCTS_RETURN_ELEMENTS;
-    ORDER_STATUS: typeof ORDER_STATUS;
-    STOCK_DOCUMENT_TYPE: typeof STOCK_DOCUMENT_TYPE;
-    RETURN_STATUS: typeof RETURN_STATUS;
-    RMA_STATUS: typeof RMA_STATUS;
-    PAYMENT_FORMS: typeof PAYMENT_FORMS;
-    PRODUCT_SIZE_COUNTABLE: typeof PRODUCT_SIZE_COUNTABLE;
-    PRODUCT_SIZE_CODES: typeof PRODUCT_SIZE_CODES;
-    PRODUCT_SIZE_LOCATIONS: typeof PRODUCT_SIZE_LOCATIONS;
-    PRODUCE_SIZE_INDEX: typeof PRODUCE_SIZE_INDEX;
-};
+declare enum WEBHOOK_OBJECT_TYPE {
+    CLIENT = "client",
+    PRODUCT = "product",
+    ORDER = "order",
+    RETURN = "return",
+    RMA = "rma"
+}
+declare enum WEBHOOK_EVENT_TYPE {
+    CLIENT_CREATED = "clientCreated",
+    CLIENT_UPDATED = "clientUpdated",
+    PRODUCT_CREATED = "productCreated",
+    PRODUCT_UPDATED = "productUpdated",
+    PRODUCT_PRICE_UPDATED = "productPriceUpdated",
+    PRODUCT_STOCK_UPDATED = "productStockUpdated",
+    PRODUCT_DISPOSITION_UPDATED = "productDispositionUpdated",
+    ORDER_CREATED = "orderCreated",
+    ORDER_UPDATED = "orderUpdated",
+    ORDER_PAID = "orderPaid",
+    ORDER_STATUS_UPDATED = "orderStatusUpdated",
+    ORDER_PACKAGE_CREATED = "orderPackageCreated",
+    ORDER_FILES_CREATED = "orderFilesCreated",
+    ORDER_SALE_DOCUMENT_CREATED = "orderSaleDocumentCreated",
+    ORDER_SALE_DOCUMENT_UPDATED = "orderSaleDocumentUpdated",
+    ORDER_SENT = "orderSent",
+    ORDER_DELIVERED = "orderDelivered",
+    ORDER_CANCELED = "orderCanceled",
+    RETURN_CREATED = "returnCreated",
+    RETURN_UPDATED = "returnUpdated",
+    RETURN_FUNDS_CONFIRMED = "returnFundsConfirmed",
+    RETURN_PACKAGE_CREATED = "returnPackageCreated",
+    RETURN_CONFIRMED = "returnConfirmed",
+    RETURN_CANCELED = "returnCanceled",
+    RMA_CREATED = "rmaCreated",
+    RMA_UPDATED = "rmaUpdated",
+    RMA_PACKAGE_CREATED = "rmaPackageCreated",
+    RMA_APPROVED = "rmaApproved",
+    RMA_REJECTED = "rmaRejected"
+}
 declare enum LANG_IDS {
     ABCHASKI = "abk",
     ACHINSKI = "ace",
@@ -584,6 +610,21 @@ declare enum LANG_IDS {
     ZULUS = "zul",
     ZUNI = "zun"
 }
+declare const ENUMS: {
+    PRODUCTS_RETURN_ELEMENTS: typeof PRODUCTS_RETURN_ELEMENTS;
+    ORDER_STATUS: typeof ORDER_STATUS;
+    STOCK_DOCUMENT_TYPE: typeof STOCK_DOCUMENT_TYPE;
+    RETURN_STATUS: typeof RETURN_STATUS;
+    RMA_STATUS: typeof RMA_STATUS;
+    PAYMENT_FORMS: typeof PAYMENT_FORMS;
+    PRODUCT_SIZE_COUNTABLE: typeof PRODUCT_SIZE_COUNTABLE;
+    PRODUCT_SIZE_CODES: typeof PRODUCT_SIZE_CODES;
+    PRODUCT_SIZE_LOCATIONS: typeof PRODUCT_SIZE_LOCATIONS;
+    PRODUCE_SIZE_INDEX: typeof PRODUCE_SIZE_INDEX;
+    LANG_IDS: typeof LANG_IDS;
+    WEBHOOK_OBJECT_TYPE: typeof WEBHOOK_OBJECT_TYPE;
+    WEBHOOK_EVENT_TYPE: typeof WEBHOOK_EVENT_TYPE;
+};
 export declare namespace ENUMS {
     type PRODUCTS_RETURN_ELEMENTS = typeof PRODUCTS_RETURN_ELEMENTS[keyof typeof PRODUCTS_RETURN_ELEMENTS];
     type ORDER_STATUS = typeof ORDER_STATUS[keyof typeof ORDER_STATUS];
@@ -596,6 +637,8 @@ export declare namespace ENUMS {
     type PRODUCT_SIZE_LOCATIONS = typeof PRODUCT_SIZE_LOCATIONS[keyof typeof PRODUCT_SIZE_LOCATIONS];
     type PRODUCE_SIZE_INDEX = typeof PRODUCE_SIZE_INDEX[keyof typeof PRODUCE_SIZE_INDEX];
     type LANG_IDS = typeof LANG_IDS[keyof typeof LANG_IDS];
+    type WEBHOOK_OBJECT_TYPE = typeof WEBHOOK_OBJECT_TYPE[keyof typeof WEBHOOK_OBJECT_TYPE];
+    type WEBHOOK_EVENT_TYPE = typeof WEBHOOK_EVENT_TYPE[keyof typeof WEBHOOK_EVENT_TYPE];
 }
 export { ENUMS };
 export default ENUMS;

package/dist/enums.js

@@ -409,18 +409,46 @@ var PRODUCE_SIZE_INDEX;
     PRODUCE_SIZE_INDEX["ID"] = "sizeId";
     PRODUCE_SIZE_INDEX["IAI_CODE"] = "iaiCode";
 })(PRODUCE_SIZE_INDEX || (PRODUCE_SIZE_INDEX = {}));
-const ENUMS = {
-    PRODUCTS_RETURN_ELEMENTS,
-    ORDER_STATUS,
-    STOCK_DOCUMENT_TYPE,
-    RETURN_STATUS,
-    RMA_STATUS,
-    PAYMENT_FORMS,
-    PRODUCT_SIZE_COUNTABLE,
-    PRODUCT_SIZE_CODES,
-    PRODUCT_SIZE_LOCATIONS,
-    PRODUCE_SIZE_INDEX
-};
+var WEBHOOK_OBJECT_TYPE;
+(function (WEBHOOK_OBJECT_TYPE) {
+    WEBHOOK_OBJECT_TYPE["CLIENT"] = "client";
+    WEBHOOK_OBJECT_TYPE["PRODUCT"] = "product";
+    WEBHOOK_OBJECT_TYPE["ORDER"] = "order";
+    WEBHOOK_OBJECT_TYPE["RETURN"] = "return";
+    WEBHOOK_OBJECT_TYPE["RMA"] = "rma";
+})(WEBHOOK_OBJECT_TYPE || (WEBHOOK_OBJECT_TYPE = {}));
+var WEBHOOK_EVENT_TYPE;
+(function (WEBHOOK_EVENT_TYPE) {
+    WEBHOOK_EVENT_TYPE["CLIENT_CREATED"] = "clientCreated";
+    WEBHOOK_EVENT_TYPE["CLIENT_UPDATED"] = "clientUpdated";
+    WEBHOOK_EVENT_TYPE["PRODUCT_CREATED"] = "productCreated";
+    WEBHOOK_EVENT_TYPE["PRODUCT_UPDATED"] = "productUpdated";
+    WEBHOOK_EVENT_TYPE["PRODUCT_PRICE_UPDATED"] = "productPriceUpdated";
+    WEBHOOK_EVENT_TYPE["PRODUCT_STOCK_UPDATED"] = "productStockUpdated";
+    WEBHOOK_EVENT_TYPE["PRODUCT_DISPOSITION_UPDATED"] = "productDispositionUpdated";
+    WEBHOOK_EVENT_TYPE["ORDER_CREATED"] = "orderCreated";
+    WEBHOOK_EVENT_TYPE["ORDER_UPDATED"] = "orderUpdated";
+    WEBHOOK_EVENT_TYPE["ORDER_PAID"] = "orderPaid";
+    WEBHOOK_EVENT_TYPE["ORDER_STATUS_UPDATED"] = "orderStatusUpdated";
+    WEBHOOK_EVENT_TYPE["ORDER_PACKAGE_CREATED"] = "orderPackageCreated";
+    WEBHOOK_EVENT_TYPE["ORDER_FILES_CREATED"] = "orderFilesCreated";
+    WEBHOOK_EVENT_TYPE["ORDER_SALE_DOCUMENT_CREATED"] = "orderSaleDocumentCreated";
+    WEBHOOK_EVENT_TYPE["ORDER_SALE_DOCUMENT_UPDATED"] = "orderSaleDocumentUpdated";
+    WEBHOOK_EVENT_TYPE["ORDER_SENT"] = "orderSent";
+    WEBHOOK_EVENT_TYPE["ORDER_DELIVERED"] = "orderDelivered";
+    WEBHOOK_EVENT_TYPE["ORDER_CANCELED"] = "orderCanceled";
+    WEBHOOK_EVENT_TYPE["RETURN_CREATED"] = "returnCreated";
+    WEBHOOK_EVENT_TYPE["RETURN_UPDATED"] = "returnUpdated";
+    WEBHOOK_EVENT_TYPE["RETURN_FUNDS_CONFIRMED"] = "returnFundsConfirmed";
+    WEBHOOK_EVENT_TYPE["RETURN_PACKAGE_CREATED"] = "returnPackageCreated";
+    WEBHOOK_EVENT_TYPE["RETURN_CONFIRMED"] = "returnConfirmed";
+    WEBHOOK_EVENT_TYPE["RETURN_CANCELED"] = "returnCanceled";
+    WEBHOOK_EVENT_TYPE["RMA_CREATED"] = "rmaCreated";
+    WEBHOOK_EVENT_TYPE["RMA_UPDATED"] = "rmaUpdated";
+    WEBHOOK_EVENT_TYPE["RMA_PACKAGE_CREATED"] = "rmaPackageCreated";
+    WEBHOOK_EVENT_TYPE["RMA_APPROVED"] = "rmaApproved";
+    WEBHOOK_EVENT_TYPE["RMA_REJECTED"] = "rmaRejected";
+})(WEBHOOK_EVENT_TYPE || (WEBHOOK_EVENT_TYPE = {}));
 var LANG_IDS;
 (function (LANG_IDS) {
     LANG_IDS["ABCHASKI"] = "abk";
@@ -596,5 +624,20 @@ var LANG_IDS;
     LANG_IDS["ZULUS"] = "zul";
     LANG_IDS["ZUNI"] = "zun";
 })(LANG_IDS || (LANG_IDS = {}));
+const ENUMS = {
+    PRODUCTS_RETURN_ELEMENTS,
+    ORDER_STATUS,
+    STOCK_DOCUMENT_TYPE,
+    RETURN_STATUS,
+    RMA_STATUS,
+    PAYMENT_FORMS,
+    PRODUCT_SIZE_COUNTABLE,
+    PRODUCT_SIZE_CODES,
+    PRODUCT_SIZE_LOCATIONS,
+    PRODUCE_SIZE_INDEX,
+    LANG_IDS,
+    WEBHOOK_OBJECT_TYPE,
+    WEBHOOK_EVENT_TYPE
+};
 export { ENUMS };
 export default ENUMS;

package/dist/gateways.d.ts

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/no-empty-object-type */
-import type { PagableGateway, AppendableGateway, Gateway, DateLike, JSObject, IdosellErrorFaultStructure } from "./app.d.ts"
+import type { PagableGateway, AppendableGateway, Gateway, DateLike, JSObject, IdosellErrorFaultStructure, Webhooks, IaiWebhookHeaders } from "./app.d.ts"
 import type { GetClientsBalanceResponse, BooleanStatusResponse, GetClientsResponse, PostClientsResponse, PutClientsResponse, SearchClientsCrmResponse, GetClientsDeliveryAddressResponse, PostClientsDeliveryAddressResponse, PutClientsDeliveryAddressResponse, VouchersResponse, PutVouchersResponse, SearchClientsGiftcardsResponse, GetClientsGiftcardsTypesResponse, GetClientsMembershipCardsResponse, PutClientsMembershipCardsResponse, SearchClientsNewsletterEmailResponse, SearchClientsNewsletterSmsResponse, GetClientsPayerAddressResponse, PostClientsPayerAddressResponse, PutClientsPayerAddressResponse, GetClientsPricelistsClientsResponse, PutClientsPricelistsClientsResponse, GetClientsPricelistsResponse, PostClientsPricelistsResponse, GetClientsPricelistsProductsResponse, PutClientsPricelistsProductsResponse, GetClientsPricesActiveCardResponse, GetClientsPricesDiscountGroupsResponse, GetClientsPricesDiscountsResponse, PutClientsPricesDiscountsResponse, GetClientsProfitPointsResponse, GetClientsProvinceListResponse, GetClientsTagsResponse, PostClientsTagsResponse, PutClientsTagsResponse, GetConfigVariablesResponse, PutConfigVariablesResponse, GetCouriersAssignedToShippingProfilesResponse, GetCouriersResponse, GetCouriersPickupPointsResponse, PutCouriersPickupPointsResponse, GetCpaCampaignResponse, CmsCampaignResponse, CmsResponse, GetCpaResponse, GetDeliveriesProfilesResponse, GetDeliveriesRegionsResponse, PostDeliveriesRegionsResponse, GetDiscountsGroupsClientsResponse, GetDiscountsGroupsResponse, PostDiscountsGroupsResponse, GetEntriesResponse, PostEntriesResponse, GetEntriesPagesToDisplayResponse, GetEntriesSourcesResponse, GetMenuResponse, PostMenuResponse, PutMenuResponse, PutMenuSortResponse, GetOrdersAnalyticsResponse, GetOrdersAuctionDetailsResponse, PutOrdersCourierResponse, PostOrdersDocumentsCreateResponse, GetOrdersDocumentsResponse, PostOrdersDocumentsResponse, GetOrdersHandlerResponse, GetOrdersHistoryResponse, GetOrdersImagesResponse, PostOrdersImagesResponse, GetOrdersLabelsResponse, SearchOrdersOpinionsResponse, GetOrdersOpinionsRateResponse, SearchOrdersResponse, PostOrdersResponse, PutOrdersResponse, GetOrdersPackagesResponse, PutOrdersPackagesResponse, PutOrdersProductsSerialNumbersResponse, PutOrdersProfitMarginResponse, GetOrdersProfitabilityResponse, GetOrdersStatusesResponse, GetOrdersWarehouseResponse, PostPackagesLabelsResponse, PutPackagesResponse, SearchPackagesResponse, GetPaymentsFormsResponse, GetPaymentsResponse, PostPaymentsResponse, GetPaymentsProfilesResponse, PostPaymentsRepaymentResponse, GetProductsSKUbyBarcodeResponse, GetProductsAttachmentsGetContentResponse, PutProductsAttachmentsResponse, GetProductsAuctionsResponse, GetProductsBrandsResponse, PutProductsBrandsResponse, GetProductsCategoriesResponse, PutProductsCategoriesResponse, SearchProductsCategoriesIdosellResponse, GetProductsCodeExistenceResponse, SearchProductsDeliveryTimeResponse, GetProductsDescriptionsResponse, ProductIdentResponse, PutProductsGroupsSettingsResponse, GetProductsIdBySizecodeResponse, PutProductsImagesResponse, GetProductsMarketingZonesResponse, PutProductsMarketingZonesResponse, GetProductsOmnibusPricesResponse, GetProductsOpinionsResponse, PostProductsOpinionsResponse, GetProductsOpinionsRateResponse, PutProductsParametersResponse, SearchProductsParametersResponse, SearchProductsResponse, PostProductsResponse, PutProductsResponse, PutProductsMarketingPromotionResponse, GetProductsQuestionsResponse, GetProductsReservationsResponse, GetProductsSeriesResponse, PutProductsSeriesResponse, GetProductsSizesResponse, PutProductsSizesResponse, PutProductsStockQuantityResponse, GetProductsStocksResponse, PutProductsStocksResponse, GetProductsStrikethroughPricesResponse, PutProductsSupplierCodeResponse, PutProductsSupplierProductDataResponse, PromotionBoolResponse, SearchPromotionsElementsResponse, SearchPromotionsHistoryResponse, PromotionIdResponse, GetPromotionsResponse, SearchPromotionsListViewResponse, GetPromotionsArchiveResponse, SearchPromotionsArchiveResponse, GetPromotionsSettingsResponse, GetRegulationsHistoryResponse, GetResponsibilityEntitiesResponse, PutResponsibilityEntitiesResponse, GetReturnsResponse, PostReturnsResponse, PutReturnsResponse, PutReturnsSerialNumberResponse, GetRmaResponse, PutRmaResponse, GetRmaStatusesResponse, GetShopsCurrenciesResponse, GetShopsLanguagesResponse, GetSizechartsResponse, PutSizechartsResponse, GetSizesResponse, PutSizesResponse, GetSnippetsCampaignResponse, GetSnippetsCookiesResponse, GetSnippetsResponse, GetSystemConfigResponse, GetSystemCurrenciesResponse, PutSystemCurrenciesResponse, GetSystemProcessesAutomationResponse, GetSystemServerLoadResponse, GetSystemServerTimeResponse, GetSystemShopsDataResponse, GetSystemUnitsResponse, PutSystemUnitsResponse, GetSystemUsersResponse, GetVouchersTypesResponse, GetVouchersResponse, GetWarrantiesCountTotalResponse, PutWarrantiesLanguageDataResponse, GetWarrantiesResponse, PutWarrantiesResponse, GetWmsLocationsResponse, GetWmsStocksdocumentsDocumentsResponse, PostWmsStocksdocumentsDocumentsResponse, PutWmsStocksdocumentsDocumentsResponse, GetWmsStocksdocumentsOpenedDocumentsResponse, GetWmsStocksdocumentsProductsResponse, PutWmsStocksdocumentsProductsResponse, GetWmsSuppliersResponse, PutWmsSuppliersResponse, GetProductsMarketingPromotionResponse, PostProductsMarketingPromotionResponse } from "./responses.d.ts"
 import type * as RequestParams from "./reqparams.d.ts";
 import { ENUMS } from "./enums";
@@ -5419,6 +5419,7 @@ export interface Gateways {
     deleteProductsProductsToPromotion: DeleteProductsToPromotionRequest,
 }
 
+declare const webhooks: Webhooks;
 declare const defaultExport: (url: string, apiKey: string, version?: number | string) => Gateways;
 export default defaultExport;
-export { ENUMS, RequestParams, utils }
+export { ENUMS, RequestParams, utils, webhooks, IaiWebhookHeaders }

package/dist/index.js

@@ -1,5 +1,6 @@
 import ENUMS from "./enums.js";
 import utils from "./utils.js";
+import webhooks from "./webhooks.js";
 import { gateProxy } from "./gates.js";
 import { IdosellFaultStringError, catchEmptyList } from "./errors.js";
 export const DEFAULT_VERSION = 8;
@@ -27,4 +28,4 @@ const idosell = (url, apiKey, version = DEFAULT_VERSION) => {
     return new Proxy(element, gateProxy);
 };
 export default idosell;
-export { ENUMS, utils, IdosellFaultStringError, catchEmptyList };
+export { ENUMS, utils, webhooks, IdosellFaultStringError, catchEmptyList };

package/dist/responses.d.ts

@@ -9055,7 +9055,6 @@ export type GetOrdersResponse = {
             clientPickupPointAddress?: {
                 /** @description Collection point ID. */
                 pickupPointId: number;
-                externalPickupPointId?: string;
                 /** @description External service collection point ID. */
                 externalPickupPointId: string;
                 /** @description Town / City. */

package/dist/webhooks.js

@@ -0,0 +1,124 @@
+/* eslint-disable no-unused-vars */
+import { normalizeIaiRequest, WebhookValidationError } from "./webhooks.normalizer.js";
+// ─── Runtime constants ────────────────────────────────────────────────────────
+export const WEBHOOK_OBJECT_TYPE = {
+    CLIENT: "client",
+    PRODUCT: "product",
+    ORDER: "order",
+    RETURN: "return",
+    RMA: "rma",
+};
+export const WEBHOOK_EVENT_TYPE = {
+    CLIENT_CREATED: "clientCreated",
+    CLIENT_UPDATED: "clientUpdated",
+    PRODUCT_CREATED: "productCreated",
+    PRODUCT_UPDATED: "productUpdated",
+    PRODUCT_PRICE_UPDATED: "productPriceUpdated",
+    PRODUCT_STOCK_UPDATED: "productStockUpdated",
+    PRODUCT_DISPOSITION_UPDATED: "productDispositionUpdated",
+    ORDER_CREATED: "orderCreated",
+    ORDER_UPDATED: "orderUpdated",
+    ORDER_PAID: "orderPaid",
+    ORDER_STATUS_UPDATED: "orderStatusUpdated",
+    ORDER_PACKAGE_CREATED: "orderPackageCreated",
+    ORDER_FILES_CREATED: "orderFilesCreated",
+    ORDER_SALE_DOCUMENT_CREATED: "orderSaleDocumentCreated",
+    ORDER_SALE_DOCUMENT_UPDATED: "orderSaleDocumentUpdated",
+    ORDER_SENT: "orderSent",
+    ORDER_DELIVERED: "orderDelivered",
+    ORDER_CANCELED: "orderCanceled",
+    RETURN_CREATED: "returnCreated",
+    RETURN_UPDATED: "returnUpdated",
+    RETURN_FUNDS_CONFIRMED: "returnFundsConfirmed",
+    RETURN_PACKAGE_CREATED: "returnPackageCreated",
+    RETURN_CONFIRMED: "returnConfirmed",
+    RETURN_CANCELED: "returnCanceled",
+    RMA_CREATED: "rmaCreated",
+    RMA_UPDATED: "rmaUpdated",
+    RMA_PACKAGE_CREATED: "rmaPackageCreated",
+    RMA_APPROVED: "rmaApproved",
+    RMA_REJECTED: "rmaRejected",
+};
+// ─── Runtime event → object map ───────────────────────────────────────────────
+const EVENT_OBJECT_MAP = {
+    clientCreated: "client",
+    clientUpdated: "client",
+    productCreated: "product",
+    productUpdated: "product",
+    productPriceUpdated: "product",
+    productStockUpdated: "product",
+    productDispositionUpdated: "product",
+    orderCreated: "order",
+    orderUpdated: "order",
+    orderPaid: "order",
+    orderStatusUpdated: "order",
+    orderPackageCreated: "order",
+    orderFilesCreated: "order",
+    orderSaleDocumentCreated: "order",
+    orderSaleDocumentUpdated: "order",
+    orderSent: "order",
+    orderDelivered: "order",
+    orderCanceled: "order",
+    returnCreated: "return",
+    returnUpdated: "return",
+    returnFundsConfirmed: "return",
+    returnPackageCreated: "return",
+    returnConfirmed: "return",
+    returnCanceled: "return",
+    rmaCreated: "rma",
+    rmaUpdated: "rma",
+    rmaPackageCreated: "rma",
+    rmaApproved: "rma",
+    rmaRejected: "rma",
+};
+export class WebhookChain {
+    slots = [];
+    validator = null;
+    validateHeaders(validator) {
+        this.validator = validator;
+        return this;
+    }
+    on(eventType, handler) {
+        this.slots.push({
+            eventType,
+            fn: handler,
+        });
+        return this;
+    }
+    async handle(req) {
+        const { headers, body } = await normalizeIaiRequest(req);
+        if (this.validator !== null) {
+            let valid = false;
+            try {
+                valid = await this.validator(headers);
+            }
+            catch {
+                valid = false;
+            }
+            if (!valid) {
+                return { matched: false, eventType: null, reason: "validation_failed" };
+            }
+        }
+        const incomingEvent = headers.eventType;
+        const expectedObject = EVENT_OBJECT_MAP[incomingEvent];
+        if (expectedObject !== undefined && headers.objectType !== expectedObject) {
+            throw new WebhookValidationError(`eventType "${incomingEvent}" expects objectType "${expectedObject}", got "${headers.objectType}"`, "x-iai-object-type");
+        }
+        const slot = this.slots.find(s => s.eventType === incomingEvent);
+        if (!slot) {
+            return { matched: false, eventType: incomingEvent };
+        }
+        await slot.fn({ headers, body });
+        return { matched: true, eventType: slot.eventType };
+    }
+}
+// ─── Entry point ──────────────────────────────────────────────────────────────
+export const webhooks = {
+    validateHeaders(validator) {
+        return new WebhookChain().validateHeaders(validator);
+    },
+    on(eventType, handler) {
+        return new WebhookChain().on(eventType, handler);
+    },
+};
+export default webhooks;

package/dist/webhooks.normalizer.js

@@ -0,0 +1,140 @@
+// ─── Errors ──────────────────────────────────────────────────────────────────
+export class WebhookValidationError extends Error {
+    field;
+    constructor(message, field) {
+        super(message);
+        this.field = field;
+        this.name = `WebhookValidationError ${field}`;
+    }
+}
+// ─── Internal helpers ────────────────────────────────────────────────────────
+function requireHeader(headers, key) {
+    const value = headers[key];
+    if (!value || value.trim() === "") {
+        throw new WebhookValidationError(`Missing or empty required header: ${key}`, key);
+    }
+    return value.trim();
+}
+function parseIntHeader(headers, key) {
+    const raw = requireHeader(headers, key);
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 0) {
+        throw new WebhookValidationError(`Header ${key} must be a positive integer, got: "${raw}"`, key);
+    }
+    return n;
+}
+function parseDateHeader(headers, key) {
+    const raw = requireHeader(headers, key);
+    const date = new Date(raw);
+    if (isNaN(date.getTime())) {
+        throw new WebhookValidationError(`Header ${key} is not a valid date string, got: "${raw}"`, key);
+    }
+    return date;
+}
+function parseAuthHeader(headers) {
+    const raw = requireHeader(headers, "authorization");
+    const [scheme, token] = raw.split(" ");
+    if (scheme?.toLowerCase() !== "bearer" || !token) {
+        throw new WebhookValidationError(`Authorization header must use Bearer scheme, got: "${raw}"`, "authorization");
+    }
+    return token;
+}
+function extractHeaders(raw) {
+    return {
+        token: parseAuthHeader(raw),
+        apiVersion: parseIntHeader(raw, "x-iai-api-version"),
+        eventTime: parseDateHeader(raw, "x-iai-event-time"),
+        eventType: requireHeader(raw, "x-iai-event-type"),
+        eventUid: requireHeader(raw, "x-iai-event-uid"),
+        objectType: requireHeader(raw, "x-iai-object-type"),
+        panelId: parseIntHeader(raw, "x-iai-panel-id"),
+        signature: requireHeader(raw, "x-iai-signature"),
+        webhookTime: parseDateHeader(raw, "x-iai-webhook-time"),
+    };
+}
+// ─── Type guard ──────────────────────────────────────────────────────────────
+function isWebRequest(req) {
+    return typeof req.json === "function";
+}
+// ─── Raw headers flattening ──────────────────────────────────────────────────
+function flattenNodeHeaders(headers) {
+    const out = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (value !== undefined) {
+            out[key.toLowerCase()] = Array.isArray(value) ? value.join(", ") : value;
+        }
+    }
+    return out;
+}
+function flattenWebHeaders(headers) {
+    const out = {};
+    headers.forEach((value, key) => { out[key.toLowerCase()] = value; });
+    return out;
+}
+function readNodeStream(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (chunk) => chunks.push(chunk));
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+        req.on("error", reject);
+    });
+}
+// ─── Main normalizer ─────────────────────────────────────────────────────────
+/**
+ * Parses and validates an incoming IAI webhook request from any of:
+ *   - Express          (pass req directly — do NOT attach express.json())
+ *   - Next.js Pages    (disable bodyParser in route config)
+ *   - Next.js App      (Web Fetch API Request)
+ *   - SvelteKit        (Web Fetch API Request — pass event.request)
+ *
+ * Throws WebhookValidationError for any missing/malformed header or empty body.
+ *
+ * @example Express
+ * app.post('/webhook', async (req, res) => {
+ *   const { headers, body } = await normalizeIaiRequest(req);
+ * });
+ *
+ * @example SvelteKit
+ * export async function POST({ request }) {
+ *   const { headers, body } = await normalizeIaiRequest(request);
+ * }
+ *
+ * @example Next.js App Router
+ * export async function POST(request: Request) {
+ *   const { headers, body } = await normalizeIaiRequest(request);
+ * }
+ *
+ * @example Next.js Pages Router (add export const config = { api: { bodyParser: false } })
+ * export default async function handler(req, res) {
+ *   const { headers, body } = await normalizeIaiRequest(req);
+ * }
+ */
+export async function normalizeIaiRequest(req) {
+    let flatHeaders;
+    let rawBody;
+    if (isWebRequest(req)) {
+        flatHeaders = flattenWebHeaders(req.headers);
+        rawBody = await req.text();
+    }
+    else {
+        flatHeaders = flattenNodeHeaders(req.headers);
+        rawBody = req.body !== undefined
+            ? JSON.stringify(req.body)
+            : await readNodeStream(req);
+    }
+    if (!rawBody || rawBody.trim() === "") {
+        throw new WebhookValidationError("Request body is empty", "body");
+    }
+    let body;
+    try {
+        body = JSON.parse(rawBody);
+    }
+    catch {
+        throw new WebhookValidationError("Request body is not valid JSON", "body");
+    }
+    if (typeof body !== "object" || body === null || Array.isArray(body)) {
+        throw new WebhookValidationError("Request body must be a JSON object", "body");
+    }
+    const headers = extractHeaders(flatHeaders);
+    return { headers, body };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "idosell",
-  "version": "0.4.38",
+  "version": "0.4.41",
   "description": "Idosell 3 REST connector",
   "main": "dist/index.js",
   "types": "dist/gateways.d.ts",