go-scheduler-node-sdk 1.0.0

package/dist/utils/http.d.ts

@@ -0,0 +1,14 @@
+import { AxiosRequestConfig } from "axios";
+export declare class HttpClient {
+    private client;
+    constructor(baseURL: string, timeout?: number, headers?: Record<string, string>);
+    get<T>(url: string, config?: AxiosRequestConfig): Promise<T>;
+    post<T>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T>;
+    postForm<T>(url: string, formData: FormData, config?: AxiosRequestConfig): Promise<T>;
+    put<T>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T>;
+    patch<T>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T>;
+    delete<T>(url: string, config?: AxiosRequestConfig): Promise<T>;
+    private handleError;
+    setHeader(key: string, value: string): void;
+    removeHeader(key: string): void;
+}

package/dist/utils/http.js

@@ -0,0 +1,99 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpClient = void 0;
+const axios_1 = __importDefault(require("axios"));
+class HttpClient {
+    constructor(baseURL, timeout = 30000, headers) {
+        this.client = axios_1.default.create({
+            baseURL,
+            timeout,
+            headers: {
+                "Content-Type": "application/json",
+                ...headers,
+            },
+        });
+    }
+    async get(url, config) {
+        try {
+            const response = await this.client.get(url, config);
+            return response.data;
+        }
+        catch (error) {
+            throw this.handleError(error);
+        }
+    }
+    async post(url, data, config) {
+        try {
+            const response = await this.client.post(url, data, config);
+            return response.data;
+        }
+        catch (error) {
+            throw this.handleError(error);
+        }
+    }
+    async postForm(url, formData, config) {
+        try {
+            const response = await this.client.post(url, formData, {
+                ...config,
+                headers: {
+                    ...config?.headers,
+                    "Content-Type": "multipart/form-data",
+                },
+            });
+            return response.data;
+        }
+        catch (error) {
+            throw this.handleError(error);
+        }
+    }
+    async put(url, data, config) {
+        try {
+            const response = await this.client.put(url, data, config);
+            return response.data;
+        }
+        catch (error) {
+            throw this.handleError(error);
+        }
+    }
+    async patch(url, data, config) {
+        try {
+            const response = await this.client.patch(url, data, config);
+            return response.data;
+        }
+        catch (error) {
+            throw this.handleError(error);
+        }
+    }
+    async delete(url, config) {
+        try {
+            const response = await this.client.delete(url, config);
+            return response.data;
+        }
+        catch (error) {
+            throw this.handleError(error);
+        }
+    }
+    handleError(error) {
+        if (axios_1.default.isAxiosError(error)) {
+            const errorData = error.response?.data;
+            const message = errorData?.error || error.message;
+            const details = errorData?.details;
+            const errorMessage = details ? `${message}: ${details}` : message;
+            const customError = new Error(errorMessage);
+            customError.status = error.response?.status;
+            customError.response = error.response;
+            return customError;
+        }
+        return error instanceof Error ? error : new Error(String(error));
+    }
+    setHeader(key, value) {
+        this.client.defaults.headers.common[key] = value;
+    }
+    removeHeader(key) {
+        delete this.client.defaults.headers.common[key];
+    }
+}
+exports.HttpClient = HttpClient;

package/dist/utils/webhook.d.ts

@@ -0,0 +1,112 @@
+import { WebhookPayload, WebhookVerificationResult } from "../types";
+/**
+ * Webhook utility class for verifying and handling webhook payloads
+ */
+export declare class WebhookUtils {
+    /**
+     * Verify a webhook signature using HMAC-SHA256
+     * @param payload - The raw webhook payload (as string or Buffer)
+     * @param signature - The signature from the X-Webhook-Signature header
+     * @param secret - The webhook secret
+     * @returns Verification result with validity and optional error message
+     */
+    static verifySignature(payload: string | Buffer, signature: string, secret: string): WebhookVerificationResult;
+    /**
+     * Compute the signature for a webhook payload
+     * Useful for testing webhook endpoints
+     * @param payload - The webhook payload object or string
+     * @param secret - The webhook secret
+     * @returns Signature in the format "sha256=<hex>"
+     */
+    static computeSignature(payload: WebhookPayload | string | Buffer, secret: string): string;
+    /**
+     * Parse and verify a webhook payload
+     * @param rawPayload - The raw webhook payload (as received from request)
+     * @param signature - The signature from the X-Webhook-Signature header
+     * @param secret - The webhook secret
+     * @returns Parsed payload if valid, null otherwise
+     */
+    static parseAndVerify<T = any>(rawPayload: string | Buffer, signature: string, secret: string): {
+        payload: WebhookPayload<T>;
+        error?: string;
+    } | null;
+    /**
+     * Validate webhook payload structure
+     * @param payload - The parsed webhook payload
+     * @returns True if payload has required fields
+     */
+    static validatePayloadStructure(payload: any): payload is WebhookPayload;
+    /**
+     * Check if a webhook timestamp is fresh (within acceptable time window)
+     * Helps prevent replay attacks
+     * @param timestamp - The webhook timestamp (Unix timestamp in seconds)
+     * @param toleranceSeconds - Maximum age of webhook in seconds (default: 300 = 5 minutes)
+     * @returns True if timestamp is within tolerance
+     */
+    static isTimestampFresh(timestamp: number, toleranceSeconds?: number): boolean;
+    /**
+     * Verify both signature and timestamp freshness
+     * @param rawPayload - The raw webhook payload
+     * @param signature - The signature from the X-Webhook-Signature header
+     * @param secret - The webhook secret
+     * @param toleranceSeconds - Maximum age of webhook in seconds (default: 300)
+     * @returns Verification result
+     */
+    static verifyWithTimestamp(rawPayload: string | Buffer, signature: string, secret: string, toleranceSeconds?: number): WebhookVerificationResult;
+    /**
+     * Extract webhook signature from request headers
+     * Supports multiple header formats
+     * @param headers - Request headers object
+     * @returns Signature string or null if not found
+     */
+    static extractSignature(headers: Record<string, string | string[] | undefined>): string | null;
+    /**
+     * Create a webhook response helper for Express/HTTP frameworks
+     * @param statusCode - HTTP status code to return
+     * @param message - Optional message
+     * @returns Response object
+     */
+    static createResponse(statusCode: number, message?: string): {
+        statusCode: number;
+        body: string | undefined;
+    };
+    /**
+     * Success response for webhook acknowledgment
+     */
+    static success(): {
+        statusCode: number;
+        body: string | undefined;
+    };
+    /**
+     * Error response for invalid signature
+     */
+    static invalidSignature(): {
+        statusCode: number;
+        body: string | undefined;
+    };
+    /**
+     * Error response for stale timestamp
+     */
+    static staleTimestamp(): {
+        statusCode: number;
+        body: string | undefined;
+    };
+    /**
+     * Error response for invalid payload
+     */
+    static invalidPayload(): {
+        statusCode: number;
+        body: string | undefined;
+    };
+}
+/**
+ * Express middleware factory for webhook verification
+ * @param secret - The webhook secret
+ * @param options - Optional configuration
+ * @returns Express middleware function
+ */
+export declare function createWebhookVerificationMiddleware(secret: string, options?: {
+    toleranceSeconds?: number;
+    rawBodyKey?: string;
+}): (req: any, res: any, next: any) => void;
+export declare const verifySignature: typeof WebhookUtils.verifySignature, computeSignature: typeof WebhookUtils.computeSignature, parseAndVerify: typeof WebhookUtils.parseAndVerify, validatePayloadStructure: typeof WebhookUtils.validatePayloadStructure, isTimestampFresh: typeof WebhookUtils.isTimestampFresh, verifyWithTimestamp: typeof WebhookUtils.verifyWithTimestamp, extractSignature: typeof WebhookUtils.extractSignature;

package/dist/utils/webhook.js

@@ -0,0 +1,262 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractSignature = exports.verifyWithTimestamp = exports.isTimestampFresh = exports.validatePayloadStructure = exports.parseAndVerify = exports.computeSignature = exports.verifySignature = exports.WebhookUtils = void 0;
+exports.createWebhookVerificationMiddleware = createWebhookVerificationMiddleware;
+const crypto_1 = require("crypto");
+/**
+ * Webhook utility class for verifying and handling webhook payloads
+ */
+class WebhookUtils {
+    /**
+     * Verify a webhook signature using HMAC-SHA256
+     * @param payload - The raw webhook payload (as string or Buffer)
+     * @param signature - The signature from the X-Webhook-Signature header
+     * @param secret - The webhook secret
+     * @returns Verification result with validity and optional error message
+     */
+    static verifySignature(payload, signature, secret) {
+        try {
+            // Normalize payload to string
+            const payloadString = typeof payload === "string" ? payload : payload.toString("utf8");
+            // Extract the signature value (format: "sha256=<hex>")
+            if (!signature || !signature.startsWith("sha256=")) {
+                return {
+                    valid: false,
+                    error: "Invalid signature format. Expected 'sha256=<hex>'",
+                };
+            }
+            const providedSignature = signature.substring(7); // Remove "sha256=" prefix
+            // Compute expected signature
+            const expectedSignature = (0, crypto_1.createHmac)("sha256", secret)
+                .update(payloadString)
+                .digest("hex");
+            // Use timing-safe comparison to prevent timing attacks
+            const providedBuffer = Buffer.from(providedSignature, "hex");
+            const expectedBuffer = Buffer.from(expectedSignature, "hex");
+            if (providedBuffer.length !== expectedBuffer.length) {
+                return {
+                    valid: false,
+                    error: "Signature length mismatch",
+                };
+            }
+            const isValid = (0, crypto_1.timingSafeEqual)(providedBuffer, expectedBuffer);
+            return {
+                valid: isValid,
+                error: isValid ? undefined : "Signature verification failed",
+            };
+        }
+        catch (error) {
+            return {
+                valid: false,
+                error: `Verification error: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    /**
+     * Compute the signature for a webhook payload
+     * Useful for testing webhook endpoints
+     * @param payload - The webhook payload object or string
+     * @param secret - The webhook secret
+     * @returns Signature in the format "sha256=<hex>"
+     */
+    static computeSignature(payload, secret) {
+        const payloadString = typeof payload === "string"
+            ? payload
+            : Buffer.isBuffer(payload)
+                ? payload.toString("utf8")
+                : JSON.stringify(payload);
+        const signature = (0, crypto_1.createHmac)("sha256", secret)
+            .update(payloadString)
+            .digest("hex");
+        return `sha256=${signature}`;
+    }
+    /**
+     * Parse and verify a webhook payload
+     * @param rawPayload - The raw webhook payload (as received from request)
+     * @param signature - The signature from the X-Webhook-Signature header
+     * @param secret - The webhook secret
+     * @returns Parsed payload if valid, null otherwise
+     */
+    static parseAndVerify(rawPayload, signature, secret) {
+        // Verify signature first
+        const verification = this.verifySignature(rawPayload, signature, secret);
+        if (!verification.valid) {
+            return null;
+        }
+        // Parse payload
+        try {
+            const payloadString = typeof rawPayload === "string"
+                ? rawPayload
+                : rawPayload.toString("utf8");
+            const payload = JSON.parse(payloadString);
+            return { payload };
+        }
+        catch (error) {
+            return null;
+        }
+    }
+    /**
+     * Validate webhook payload structure
+     * @param payload - The parsed webhook payload
+     * @returns True if payload has required fields
+     */
+    static validatePayloadStructure(payload) {
+        return (typeof payload === "object" &&
+            payload !== null &&
+            typeof payload.webhook_uid === "string" &&
+            typeof payload.event_type === "string" &&
+            typeof payload.delivery_id === "string" &&
+            typeof payload.timestamp === "number" &&
+            "data" in payload);
+    }
+    /**
+     * Check if a webhook timestamp is fresh (within acceptable time window)
+     * Helps prevent replay attacks
+     * @param timestamp - The webhook timestamp (Unix timestamp in seconds)
+     * @param toleranceSeconds - Maximum age of webhook in seconds (default: 300 = 5 minutes)
+     * @returns True if timestamp is within tolerance
+     */
+    static isTimestampFresh(timestamp, toleranceSeconds = 300) {
+        const now = Math.floor(Date.now() / 1000);
+        const age = Math.abs(now - timestamp);
+        return age <= toleranceSeconds;
+    }
+    /**
+     * Verify both signature and timestamp freshness
+     * @param rawPayload - The raw webhook payload
+     * @param signature - The signature from the X-Webhook-Signature header
+     * @param secret - The webhook secret
+     * @param toleranceSeconds - Maximum age of webhook in seconds (default: 300)
+     * @returns Verification result
+     */
+    static verifyWithTimestamp(rawPayload, signature, secret, toleranceSeconds = 300) {
+        // Verify signature
+        const signatureResult = this.verifySignature(rawPayload, signature, secret);
+        if (!signatureResult.valid) {
+            return signatureResult;
+        }
+        // Parse and check timestamp
+        try {
+            const payloadString = typeof rawPayload === "string"
+                ? rawPayload
+                : rawPayload.toString("utf8");
+            const payload = JSON.parse(payloadString);
+            if (!this.isTimestampFresh(payload.timestamp, toleranceSeconds)) {
+                return {
+                    valid: false,
+                    error: `Webhook timestamp is too old. Age exceeds ${toleranceSeconds} seconds.`,
+                };
+            }
+            return { valid: true };
+        }
+        catch (error) {
+            return {
+                valid: false,
+                error: "Failed to parse payload for timestamp verification",
+            };
+        }
+    }
+    /**
+     * Extract webhook signature from request headers
+     * Supports multiple header formats
+     * @param headers - Request headers object
+     * @returns Signature string or null if not found
+     */
+    static extractSignature(headers) {
+        // Try different header formats
+        const signature = headers["x-webhook-signature"] ||
+            headers["X-Webhook-Signature"] ||
+            headers["x-signature"] ||
+            headers["X-Signature"];
+        if (Array.isArray(signature)) {
+            return signature[0] || null;
+        }
+        return signature || null;
+    }
+    /**
+     * Create a webhook response helper for Express/HTTP frameworks
+     * @param statusCode - HTTP status code to return
+     * @param message - Optional message
+     * @returns Response object
+     */
+    static createResponse(statusCode, message) {
+        return {
+            statusCode,
+            body: message ? JSON.stringify({ message }) : undefined,
+        };
+    }
+    /**
+     * Success response for webhook acknowledgment
+     */
+    static success() {
+        return this.createResponse(200, "Webhook received");
+    }
+    /**
+     * Error response for invalid signature
+     */
+    static invalidSignature() {
+        return this.createResponse(401, "Invalid webhook signature");
+    }
+    /**
+     * Error response for stale timestamp
+     */
+    static staleTimestamp() {
+        return this.createResponse(400, "Webhook timestamp is too old");
+    }
+    /**
+     * Error response for invalid payload
+     */
+    static invalidPayload() {
+        return this.createResponse(400, "Invalid webhook payload");
+    }
+}
+exports.WebhookUtils = WebhookUtils;
+/**
+ * Express middleware factory for webhook verification
+ * @param secret - The webhook secret
+ * @param options - Optional configuration
+ * @returns Express middleware function
+ */
+function createWebhookVerificationMiddleware(secret, options = {}) {
+    const { toleranceSeconds = 300, rawBodyKey = "rawBody" } = options;
+    return (req, res, next) => {
+        try {
+            // Extract signature from headers
+            const signature = WebhookUtils.extractSignature(req.headers);
+            if (!signature) {
+                res.status(401).json({ error: "Missing webhook signature" });
+                return;
+            }
+            // Get raw body (must be preserved by body parser)
+            const rawBody = req[rawBodyKey] || req.body;
+            if (!rawBody) {
+                res.status(400).json({ error: "Missing request body" });
+                return;
+            }
+            // Verify signature and timestamp
+            const verification = WebhookUtils.verifyWithTimestamp(rawBody, signature, secret, toleranceSeconds);
+            if (!verification.valid) {
+                res.status(401).json({ error: verification.error });
+                return;
+            }
+            // Attach parsed payload to request
+            try {
+                const payloadString = typeof rawBody === "string" ? rawBody : rawBody.toString("utf8");
+                req.webhookPayload = JSON.parse(payloadString);
+            }
+            catch (error) {
+                res.status(400).json({ error: "Invalid JSON payload" });
+                return;
+            }
+            next();
+        }
+        catch (error) {
+            res.status(500).json({
+                error: "Webhook verification failed",
+                details: error instanceof Error ? error.message : String(error),
+            });
+        }
+    };
+}
+// Export both the class and individual functions for convenience
+exports.verifySignature = WebhookUtils.verifySignature, exports.computeSignature = WebhookUtils.computeSignature, exports.parseAndVerify = WebhookUtils.parseAndVerify, exports.validatePayloadStructure = WebhookUtils.validatePayloadStructure, exports.isTimestampFresh = WebhookUtils.isTimestampFresh, exports.verifyWithTimestamp = WebhookUtils.verifyWithTimestamp, exports.extractSignature = WebhookUtils.extractSignature;

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "go-scheduler-node-sdk",
+  "version": "1.0.0",
+  "description": "TypeScript SDK for interacting with go-scheduler REST API",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "yarn build",
+    "watch": "tsc --watch",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "scheduler",
+    "calendar",
+    "events",
+    "reminders",
+    "go-scheduler"
+  ],
+  "author": "jaysongiroux",
+  "license": "MIT",
+  "private": false,
+  "dependencies": {
+    "axios": "^1.13.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "typescript": "^5.9.3"
+  }
+}