idosell 0.4.41 → 0.4.45

package/changelog.md

@@ -5,6 +5,18 @@ 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.45] - 2025-06-07
+### Added
+- Added handleRaw to pass raw data instead of request
+- Added test to webhooks
+
+
+## [0.4.43] - 2025-06-07
+### Changed
+- Webhook now supports HMAC checking and groups of webhooks
+- Added raw data to webhook headers and handlers
+
+
 ## [0.4.41] - 2025-06-07
 ### Added
 - Added webook support

package/dist/app.d.ts

@@ -1,5 +1,5 @@
 import type {
-    GetProductsResponse,
+    SearchProductsResponse,
     GetRmaResponse,
     GetReturnsResponse,
     GetOrdersResponse,
@@ -7,109 +7,109 @@ import type {
 } from "./responses.d.ts";
 
 export interface ExecutableDumpParams {
-	url: string;
-	method: string;
-	params: Record<string,any>;
+    url: string;
+    method: string;
+    params: Record<string, any>;
 }
 
 export interface ExecutableOptions {
-	log?: boolean | ((obj: ExecutableDumpParams) => void),
+    log?: boolean | ((obj: ExecutableDumpParams) => void),
     dump?: boolean | ((obj: ExecutableDumpParams) => void),
     logPage?: boolean | ((text: string) => void),
-	skipCheck?: boolean
+    skipCheck?: boolean
 }
 
 export type DateLike = string | number | Date;
 
-export type JSObject = Record<string,any>;
+export type JSObject = Record<string, any>;
 
 export type RequestProxyObject = {
-	auth: {
-		url: string, 
-		apiKey: string, 
-		version: number|string
-	},
-	params: Record<string, any>,
+    auth: {
+        url: string,
+        apiKey: string,
+        version: number | string
+    },
+    params: Record<string, any>,
 }
 
 export type RequirementType = {
-	any: string[]|true
-} | string | ((arg: RequestProxyObject | Record<string,any>) => string|false);
+    any: string[] | true
+} | string | ((arg: RequestProxyObject | Record<string, any>) => string | false);
 
 export type GatewayRequestProxyObject = {
-	gate: {
-		method: 'get'|'post'|'put'|'delete',
-		node: string
-	},
-	appendable?: {
-		index: number,
-		arrayNode: string,
-		except: string[]
-	},
-	custom?: Record<string,(..._: any) => false|Record<string,any>>,
-	snakeCase?: boolean,
-	paginationObject?: boolean,
-	next?: boolean,
-	rootparams?: string|boolean,
-	arrays?: string[],
-	req?: RequirementType[],
-	n?: Record<string,number>
+    gate: {
+        method: 'get' | 'post' | 'put' | 'delete',
+        node: string
+    },
+    appendable?: {
+        index: number,
+        arrayNode: string,
+        except: string[]
+    },
+    custom?: Record<string, (..._: any) => false | Record<string, any>>,
+    snakeCase?: boolean,
+    paginationObject?: boolean,
+    next?: boolean,
+    rootparams?: string | boolean,
+    arrays?: string[],
+    req?: RequirementType[],
+    n?: Record<string, number>
 } & RequestProxyObject;
 
 export interface Gateway<R = JSObject, P = JSObject> {
-	/**
-	 * Executes the query to designated API endpoint
-	 * @param options Use options: log - to console log params, url and method, logPage - to console log current page in a loop
-	 * @returns Idosell response
-	 */
-	exec: (options?: ExecutableOptions) => Promise<R>,
-
-	/**
-	 * @returns Object with currently mapped parameters
-	 */
-	getParams: () => P,
-
-	/**
-	 * @description Set object as params
-	 */
-	setParams: (params: P) => this
-
-	/**
-	 * @description Checks if minimal parameters are provided. If not, throws an error.
-	 */
-	checkParams: () => void
+    /**
+     * Executes the query to designated API endpoint
+     * @param options Use options: log - to console log params, url and method, logPage - to console log current page in a loop
+     * @returns Idosell response
+     */
+    exec: (options?: ExecutableOptions) => Promise<R>,
+
+    /**
+     * @returns Object with currently mapped parameters
+     */
+    getParams: () => P,
+
+    /**
+     * @description Set object as params
+     */
+    setParams: (params: P) => this
+
+    /**
+     * @description Checks if minimal parameters are provided. If not, throws an error.
+     */
+    checkParams: () => void
 }
 
-export interface PagableGateway<T,R = JSObject, P = JSObject> extends Gateway<R, P> {
-	/**
+export interface PagableGateway<T, R = JSObject, P = JSObject> extends Gateway<R, P> {
+    /**
      * @returns number of items i.e. products, orders, documents, etc.
      */
-	count: () => Promise<number>,
+    count: () => Promise<number>,
 
-	/**
+    /**
      * Allows to change offset and number of records returned
      * @param pageNumber - The page number to navigate to.
      * @param pageSize - The size of page
      * @returns The updated instance for method chaining.
      */
-	page: (pageNumber: number, pageSize?: number) => T
+    page: (pageNumber: number, pageSize?: number) => T
 
-	/**
-	 * @returns If completed request has more pages
-	 */
-	hasNext: () => boolean
+    /**
+     * @returns If completed request has more pages
+     */
+    hasNext: () => boolean
 }
 
-export interface AppendableGateway<T,R = JSObject, P = JSObject> extends Gateway<R, P> {
-	/**
-	 * Start creating next item in list
-	 */
-	append: () => T
+export interface AppendableGateway<T, R = JSObject, P = JSObject> extends Gateway<R, P> {
+    /**
+     * Start creating next item in list
+     */
+    append: () => T
 }
 
 export interface IdosellErrorFaultStructure {
-	faultCode: number;
-	faultString: string;
+    faultCode: number;
+    faultString: string;
 }
 
 // ─── Final normalized shape ──────────────────────────────────────────────────
@@ -117,6 +117,7 @@ export interface IdosellErrorFaultStructure {
 export interface NormalizedIaiRequest<T = unknown> {
     headers: IaiWebhookHeaders;
     body: T;
+    rawBody: string
 }
 
 export declare const WEBHOOK_OBJECT_TYPE: {
@@ -162,9 +163,9 @@ export declare const WEBHOOK_EVENT_TYPE: {
 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 {
+export interface ObjectBodyMap {
     "client": GetClientsResponse;
-    "product": GetProductsResponse;
+    "product": SearchProductsResponse;
     "order": GetOrdersResponse;
     "return": GetReturnsResponse;
     "rma": GetRmaResponse;
@@ -214,16 +215,27 @@ export interface IaiWebhookHeaders {
     panelId: number;
     signature: string;
     webhookTime: Date;
+    raw: Record<string, string>
 }
 
 export interface WebhookContext<E extends WebhookEventType> {
     headers: IaiWebhookHeaders;
     body: ObjectBodyMap[EventObjectMap[E]];
+    rawBody: string;
+}
+
+export interface WebhookObjectContext<O extends WebhookObjectType> {
+    headers: IaiWebhookHeaders;
+    body: ObjectBodyMap[O];
+    rawBody: string;
 }
 
 export type WebhookHandler<E extends WebhookEventType> =
     (ctx: WebhookContext<E>) => Promise<void> | void;
 
+export type WebhookObjectHandler<O extends WebhookObjectType> =
+    (ctx: WebhookObjectContext<O>) => Promise<void> | void;
+
 export type HeaderValidator =
     (headers: IaiWebhookHeaders) => Promise<boolean> | boolean;
 
@@ -232,15 +244,27 @@ export type DispatchResult =
     | { matched: false; eventType: string }
     | { matched: false; eventType: null; reason: "validation_failed" };
 
+
+export interface RawWebhookInput {
+    headers: Record<string, string>;
+    rawBody: string;           // always string — pre-parse
+    body?: Record<string, unknown>; // optional — caller may pre-parse
+}
+
 export declare class WebhookChain {
     validateHeaders(validator: HeaderValidator): this;
+    validateSignature(hmacKey: string): this;
     on<E extends WebhookEventType>(eventType: E, handler: WebhookHandler<E>): this;
+    on<O extends WebhookObjectType>(objectType: O, handler: WebhookObjectHandler<O>): this;
     handle(req: import("node:http").IncomingMessage | Request): Promise<DispatchResult>;
+    handleRaw(req: RawWebhookInput): Promise<DispatchResult>;
 }
 
 export type Webhooks = {
     validateHeaders(validator: HeaderValidator): WebhookChain;
+    validateSignature(hmacKey: string): WebhookChain;
     on<E extends WebhookEventType>(eventType: E, handler: WebhookHandler<E>): WebhookChain;
+    on<O extends WebhookObjectType>(objectType: O, handler: WebhookObjectHandler<O>): WebhookChain;
 };
 
-export {};
+export { };

package/dist/webhooks.js

@@ -1,5 +1,6 @@
 /* eslint-disable no-unused-vars */
-import { normalizeIaiRequest, WebhookValidationError } from "./webhooks.normalizer.js";
+import { extractHeaders, normalizeIaiRequest, WebhookValidationError } from "./webhooks.normalizer.js";
+import { createHmac } from "node:crypto";
 // ─── Runtime constants ────────────────────────────────────────────────────────
 export const WEBHOOK_OBJECT_TYPE = {
     CLIENT: "client",
@@ -74,19 +75,45 @@ const EVENT_OBJECT_MAP = {
 export class WebhookChain {
     slots = [];
     validator = null;
+    hmacKey;
     validateHeaders(validator) {
         this.validator = validator;
         return this;
     }
-    on(eventType, handler) {
-        this.slots.push({
-            eventType,
-            fn: handler,
-        });
+    /**
+     * Validate the request signature using HMAC SHA256.
+     * @param hmacKey Secret key used to compute the HMAC.
+     * @throws WebhookValidationError if the computed signature does not match the header.
+     */
+    validateSignature(hmacKey) {
+        this.hmacKey = hmacKey;
+        return this;
+    }
+    on(eventTypeOrObject, handler) {
+        const isObjectType = Object.values(WEBHOOK_OBJECT_TYPE).includes(eventTypeOrObject);
+        if (isObjectType) {
+            const matchedEvents = Object.entries(EVENT_OBJECT_MAP)
+                .filter(([, obj]) => obj === eventTypeOrObject)
+                .map(([evt]) => evt);
+            for (const evt of matchedEvents) {
+                this.slots.push({ eventType: evt, fn: handler });
+            }
+        }
+        else {
+            this.slots.push({ eventType: eventTypeOrObject, fn: handler });
+        }
         return this;
     }
     async handle(req) {
-        const { headers, body } = await normalizeIaiRequest(req);
+        const { headers, body, rawBody } = await normalizeIaiRequest(req);
+        return this.dispatch(headers, body, rawBody);
+    }
+    async handleRaw({ headers: rawHeaders, rawBody, body }) {
+        const headers = extractHeaders(rawHeaders);
+        const parsedBody = body ?? JSON.parse(rawBody);
+        return this.dispatch(headers, parsedBody, rawBody);
+    }
+    async dispatch(headers, body, rawBody) {
         if (this.validator !== null) {
             let valid = false;
             try {
@@ -99,6 +126,12 @@ export class WebhookChain {
                 return { matched: false, eventType: null, reason: "validation_failed" };
             }
         }
+        if (this.hmacKey) {
+            const computed = createHmac("sha256", this.hmacKey).update(rawBody).digest("hex");
+            if (computed !== headers.signature) {
+                throw new WebhookValidationError("Invalid webhook signature", "x-iai-signature");
+            }
+        }
         const incomingEvent = headers.eventType;
         const expectedObject = EVENT_OBJECT_MAP[incomingEvent];
         if (expectedObject !== undefined && headers.objectType !== expectedObject) {
@@ -108,7 +141,7 @@ export class WebhookChain {
         if (!slot) {
             return { matched: false, eventType: incomingEvent };
         }
-        await slot.fn({ headers, body });
+        await slot.fn({ headers, body, rawBody });
         return { matched: true, eventType: slot.eventType };
     }
 }
@@ -117,8 +150,11 @@ export const webhooks = {
     validateHeaders(validator) {
         return new WebhookChain().validateHeaders(validator);
     },
-    on(eventType, handler) {
-        return new WebhookChain().on(eventType, handler);
+    validateSignature(hmacKey) {
+        return new WebhookChain().validateSignature(hmacKey);
     },
+    on: ((eventTypeOrObject, handler) => {
+        return new WebhookChain().on(eventTypeOrObject, handler);
+    }),
 };
 export default webhooks;

package/dist/webhooks.normalizer.js

@@ -39,7 +39,7 @@ function parseAuthHeader(headers) {
     }
     return token;
 }
-function extractHeaders(raw) {
+export function extractHeaders(raw) {
     return {
         token: parseAuthHeader(raw),
         apiVersion: parseIntHeader(raw, "x-iai-api-version"),
@@ -50,6 +50,7 @@ function extractHeaders(raw) {
         panelId: parseIntHeader(raw, "x-iai-panel-id"),
         signature: requireHeader(raw, "x-iai-signature"),
         webhookTime: parseDateHeader(raw, "x-iai-webhook-time"),
+        raw
     };
 }
 // ─── Type guard ──────────────────────────────────────────────────────────────
@@ -136,5 +137,5 @@ export async function normalizeIaiRequest(req) {
         throw new WebhookValidationError("Request body must be a JSON object", "body");
     }
     const headers = extractHeaders(flatHeaders);
-    return { headers, body };
+    return { headers, body, rawBody };
 }

package/package.json

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

package/tests/webhooks.test.ts

@@ -0,0 +1,158 @@
+// vitest tests for the webhook dispatcher
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createHmac } from 'node:crypto';
+import { webhooks } from '../dist/webhooks';
+import { normalizeIaiRequest } from '../dist/webhooks.normalizer';
+
+const API_VERSION = '8';
+const SIGNATURE_KEY = 'secret-hmac-key';
+const TOKEN = 'authentication-bearer-token'
+
+// Helper to build a Request with appropriate headers and body
+function buildRequest({
+    body,
+    eventType = 'productUpdated',
+    objectType = 'product',
+}: {
+    body: unknown;
+    eventType?: string;
+    objectType?: string;
+}) {
+    const rawBody = JSON.stringify(body);
+    const signature = createHmac('sha256', SIGNATURE_KEY).update(rawBody).digest('hex');
+    const headers = new Headers({
+        'Content-Type': 'application/json',
+        'x-iai-api-version': API_VERSION,
+        'x-iai-event-time': new Date().toISOString(),
+        'x-iai-event-type': eventType,
+        'x-iai-event-uid': 'uid-123',
+        'x-iai-object-type': objectType,
+        'x-iai-panel-id': '1',
+        'x-iai-signature': signature,
+        'x-iai-webhook-time': new Date().toISOString(),
+        'authorization': `Bearer ${TOKEN}`,
+    });
+    return new Request('https://api.example.com/webhook', {
+        method: 'POST',
+        headers,
+        body: rawBody,
+    });
+}
+
+describe('WebhookChain dispatcher', () => {
+    let mockHandler: ReturnType<typeof vi.fn>;
+
+    beforeEach(() => {
+        mockHandler = vi.fn();
+    });
+
+    it('routes a matching event to the registered handler', async () => {
+        const requestBody = {
+            results: [{ productDisplayedCode: 'ABC123' }],
+        };
+        const req = buildRequest({ body: requestBody });
+
+        const chain = webhooks
+            .validateHeaders((h) => h.token === TOKEN)
+            .validateSignature(SIGNATURE_KEY)
+            .on('productUpdated', mockHandler);
+
+        const result = await chain.handle(req);
+
+        expect(result).toEqual({ matched: true, eventType: 'productUpdated' });
+        expect(mockHandler).toHaveBeenCalledTimes(1);
+        const ctx = mockHandler.mock.calls[0][0];
+        expect(ctx.body).toEqual(requestBody);
+        expect(ctx.headers.eventType).toBe('productUpdated');
+        expect(ctx.headers.objectType).toBe('product');
+    });
+
+    it('returns unmatched when no handler is registered for the event', async () => {
+        const requestBody = { foo: 'bar' };
+        const req = buildRequest({ body: requestBody, eventType: 'orderCreated', objectType: 'order' });
+
+        const chain = webhooks
+            .validateHeaders((h) => h.token === TOKEN)
+            .validateSignature(SIGNATURE_KEY);
+
+        const result = await chain.handle(req);
+        expect(result).toEqual({ matched: false, eventType: 'orderCreated' });
+        expect(mockHandler).not.toHaveBeenCalled();
+    });
+
+    it('fails validateHeaders when token mismatched', async () => {
+        const requestBody = { foo: 'bar' };
+        const req = buildRequest({ body: requestBody });
+        const chain = webhooks
+            .validateHeaders(() => false)
+            .validateSignature(SIGNATURE_KEY)
+            .on('productUpdated', mockHandler);
+        const result = await chain.handle(req);
+        expect(result).toEqual({ matched: false, eventType: null, reason: 'validation_failed' });
+    });
+
+    it('fails validateSignature with wrong key', async () => {
+        const requestBody = { foo: 'bar' };
+        const req = buildRequest({ body: requestBody });
+        const chain = webhooks
+            .validateHeaders((h) => h.token === TOKEN)
+            .validateSignature('wrong-key')
+            .on('productUpdated', mockHandler);
+        await expect(chain.handle(req)).rejects.toThrow('Invalid webhook signature');
+    });
+
+    it('registers handler for object type "order" and matches order events', async () => {
+        const requestBody = { foo: 'bar' };
+        const req = buildRequest({ body: requestBody, eventType: 'orderCreated', objectType: 'order' });
+        const chain = webhooks
+            .validateHeaders((h) => h.token === TOKEN)
+            .validateSignature(SIGNATURE_KEY)
+            .on('order', mockHandler);
+        await expect(chain.handle(req)).resolves.not.toThrow();
+    });
+
+    it('normalizes request and verifies header shape', async () => {
+        const requestBody = { foo: 'bar' };
+        const req = buildRequest({ body: requestBody });
+        const { headers } = await normalizeIaiRequest(req);
+        // Basic shape checks
+        expect(headers).toMatchObject({
+            token: TOKEN,
+            apiVersion: Number(API_VERSION),
+            eventType: 'productUpdated',
+            objectType: 'product',
+            panelId: 1,
+            signature: expect.any(String),
+        });
+        // Type checks for dates
+        expect(headers.eventTime).toBeInstanceOf(Date);
+        expect(headers.webhookTime).toBeInstanceOf(Date);
+    });
+
+    it('handleRaw processes raw webhook input correctly', async () => {
+        const requestBody = { foo: 'bar' };
+        const rawBody = JSON.stringify(requestBody);
+        const rawHeaders = {
+            'content-type': 'application/json',
+            'x-iai-api-version': API_VERSION,
+            'x-iai-event-time': new Date().toISOString(),
+            'x-iai-event-type': 'productUpdated',
+            'x-iai-event-uid': 'uid-123',
+            'x-iai-object-type': 'product',
+            'x-iai-panel-id': '1',
+            'x-iai-signature': createHmac('sha256', SIGNATURE_KEY).update(rawBody).digest('hex'),
+            'x-iai-webhook-time': new Date().toISOString(),
+            'authorization': `Bearer ${TOKEN}`,
+        } as Record<string, string>;
+        const chain = webhooks
+            .validateHeaders((h) => h.token === TOKEN)
+            .validateSignature(SIGNATURE_KEY)
+            .on('productUpdated', mockHandler);
+        const result = await chain.handleRaw({ headers: rawHeaders, rawBody, body: requestBody });
+        expect(result).toEqual({ matched: true, eventType: 'productUpdated' });
+        expect(mockHandler).toHaveBeenCalledTimes(1);
+        const ctx = mockHandler.mock.calls[0][0];
+        expect(ctx.body).toEqual(requestBody);
+        expect(ctx.headers.objectType).toBe('product');
+    });
+});