@tritonium/api-client 2.1.0

package/dist/webhooks.d.mts

@@ -0,0 +1,191 @@
+/**
+ * Webhook verification utilities for Tritonium.
+ *
+ * This module provides functions for verifying webhook signatures and handling
+ * incoming webhook events from Tritonium.
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhook, WebhookEvent } from './webhooks';
+ *
+ * const event = verifyWebhook({
+ *   payload: requestBody,
+ *   signature: headers['x-tritonium-signature'],
+ *   timestamp: headers['x-tritonium-timestamp'],
+ *   secret: 'whsec_your_secret',
+ * });
+ * ```
+ */
+/**
+ * Error thrown when webhook verification fails.
+ */
+declare class WebhookVerificationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when webhook timestamp is too old.
+ */
+declare class WebhookExpiredError extends WebhookVerificationError {
+    constructor(message: string);
+}
+/**
+ * Error thrown when webhook signature is invalid.
+ */
+declare class WebhookSignatureError extends WebhookVerificationError {
+    constructor(message: string);
+}
+/**
+ * Parsed webhook event from Tritonium.
+ */
+interface WebhookEvent<T = Record<string, unknown>> {
+    /** Unique identifier for this event */
+    eventId: string;
+    /** Type of event (e.g., 'review.received', 'alert.triggered') */
+    eventType: string;
+    /** When the event occurred */
+    timestamp: Date;
+    /** Tenant that owns this event */
+    tenantId: string;
+    /** Optional app UUID related to the event */
+    appUuid?: string;
+    /** Event-specific payload data */
+    data: T;
+    /** Original JSON payload */
+    rawPayload: Record<string, unknown>;
+}
+/**
+ * Tritonium webhook event types.
+ */
+declare const EventTypes: {
+    readonly CRISIS_DETECTED: "crisis.detected";
+    readonly INSIGHT_GENERATED: "insight.generated";
+    readonly REVIEW_RECEIVED: "review.received";
+    readonly ANALYSIS_COMPLETED: "analysis.completed";
+    readonly ALERT_TRIGGERED: "alert.triggered";
+    readonly TEST_PING: "test.ping";
+};
+type EventType = (typeof EventTypes)[keyof typeof EventTypes];
+/**
+ * Options for webhook verification.
+ */
+interface VerifyWebhookOptions {
+    /** Raw request body (string or Buffer) */
+    payload: string | Buffer;
+    /** Value of X-Tritonium-Signature header */
+    signature: string;
+    /** Value of X-Tritonium-Timestamp header */
+    timestamp: string;
+    /** Your webhook signing secret */
+    secret: string;
+    /** Maximum age in seconds (default: 300 = 5 minutes) */
+    toleranceSeconds?: number;
+}
+/**
+ * Verify a webhook signature without parsing the payload.
+ *
+ * @param payload - Raw request body
+ * @param signature - Value of X-Tritonium-Signature header
+ * @param secret - Your webhook signing secret
+ * @returns true if signature is valid
+ */
+declare function verifySignature(payload: string | Buffer, signature: string, secret: string): boolean;
+/**
+ * Verify that a webhook timestamp is within acceptable range.
+ *
+ * @param timestamp - ISO 8601 timestamp string
+ * @param toleranceSeconds - Maximum age in seconds (default: 300)
+ * @returns true if timestamp is valid
+ */
+declare function verifyTimestamp(timestamp: string, toleranceSeconds?: number): boolean;
+/**
+ * Verify a webhook and parse the event.
+ *
+ * This is the main function for processing incoming webhooks. It:
+ * 1. Verifies the timestamp is not too old (replay protection)
+ * 2. Verifies the HMAC signature
+ * 3. Parses and returns the event
+ *
+ * @param options - Verification options
+ * @returns Parsed and verified webhook event
+ * @throws WebhookExpiredError if timestamp is too old
+ * @throws WebhookSignatureError if signature is invalid
+ * @throws WebhookVerificationError if payload cannot be parsed
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { verifyWebhook, WebhookVerificationError } from '@tritonium/api-client/webhooks';
+ *
+ * const app = express();
+ * const WEBHOOK_SECRET = 'whsec_your_secret';
+ *
+ * app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+ *   try {
+ *     const event = verifyWebhook({
+ *       payload: req.body,
+ *       signature: req.headers['x-tritonium-signature'] as string,
+ *       timestamp: req.headers['x-tritonium-timestamp'] as string,
+ *       secret: WEBHOOK_SECRET,
+ *     });
+ *
+ *     switch (event.eventType) {
+ *       case 'review.received':
+ *         handleReview(event.data);
+ *         break;
+ *       case 'alert.triggered':
+ *         handleAlert(event.data);
+ *         break;
+ *     }
+ *
+ *     res.json({ status: 'ok' });
+ *   } catch (e) {
+ *     if (e instanceof WebhookVerificationError) {
+ *       res.status(401).json({ error: e.message });
+ *     } else {
+ *       throw e;
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare function verifyWebhook<T = Record<string, unknown>>(options: VerifyWebhookOptions): WebhookEvent<T>;
+/**
+ * Alias for verifyWebhook for compatibility with other webhook libraries.
+ */
+declare const constructEvent: typeof verifyWebhook;
+/**
+ * Type guard to check if an error is a WebhookVerificationError.
+ */
+declare function isWebhookError(error: unknown): error is WebhookVerificationError;
+/**
+ * Type definitions for specific event payloads.
+ */
+interface ReviewReceivedData {
+    review_id: string;
+    platform: string;
+    rating: number;
+    title?: string;
+    text: string;
+    author?: string;
+    review_date: string;
+    country?: string;
+    version?: string;
+}
+interface AlertTriggeredData {
+    alert_id: string;
+    rule_id: string;
+    rule_name: string;
+    severity: 'low' | 'medium' | 'high' | 'critical';
+    message: string;
+    current_value?: number;
+    threshold?: number;
+}
+interface CrisisDetectedData {
+    severity: 'low' | 'medium' | 'high' | 'critical';
+    type: string;
+    message: string;
+    affected_period?: string;
+    metrics?: Record<string, unknown>;
+}
+
+export { type AlertTriggeredData, type CrisisDetectedData, type EventType, EventTypes, type ReviewReceivedData, type VerifyWebhookOptions, type WebhookEvent, WebhookExpiredError, WebhookSignatureError, WebhookVerificationError, constructEvent, isWebhookError, verifySignature, verifyTimestamp, verifyWebhook };

package/dist/webhooks.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Webhook verification utilities for Tritonium.
+ *
+ * This module provides functions for verifying webhook signatures and handling
+ * incoming webhook events from Tritonium.
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhook, WebhookEvent } from './webhooks';
+ *
+ * const event = verifyWebhook({
+ *   payload: requestBody,
+ *   signature: headers['x-tritonium-signature'],
+ *   timestamp: headers['x-tritonium-timestamp'],
+ *   secret: 'whsec_your_secret',
+ * });
+ * ```
+ */
+/**
+ * Error thrown when webhook verification fails.
+ */
+declare class WebhookVerificationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when webhook timestamp is too old.
+ */
+declare class WebhookExpiredError extends WebhookVerificationError {
+    constructor(message: string);
+}
+/**
+ * Error thrown when webhook signature is invalid.
+ */
+declare class WebhookSignatureError extends WebhookVerificationError {
+    constructor(message: string);
+}
+/**
+ * Parsed webhook event from Tritonium.
+ */
+interface WebhookEvent<T = Record<string, unknown>> {
+    /** Unique identifier for this event */
+    eventId: string;
+    /** Type of event (e.g., 'review.received', 'alert.triggered') */
+    eventType: string;
+    /** When the event occurred */
+    timestamp: Date;
+    /** Tenant that owns this event */
+    tenantId: string;
+    /** Optional app UUID related to the event */
+    appUuid?: string;
+    /** Event-specific payload data */
+    data: T;
+    /** Original JSON payload */
+    rawPayload: Record<string, unknown>;
+}
+/**
+ * Tritonium webhook event types.
+ */
+declare const EventTypes: {
+    readonly CRISIS_DETECTED: "crisis.detected";
+    readonly INSIGHT_GENERATED: "insight.generated";
+    readonly REVIEW_RECEIVED: "review.received";
+    readonly ANALYSIS_COMPLETED: "analysis.completed";
+    readonly ALERT_TRIGGERED: "alert.triggered";
+    readonly TEST_PING: "test.ping";
+};
+type EventType = (typeof EventTypes)[keyof typeof EventTypes];
+/**
+ * Options for webhook verification.
+ */
+interface VerifyWebhookOptions {
+    /** Raw request body (string or Buffer) */
+    payload: string | Buffer;
+    /** Value of X-Tritonium-Signature header */
+    signature: string;
+    /** Value of X-Tritonium-Timestamp header */
+    timestamp: string;
+    /** Your webhook signing secret */
+    secret: string;
+    /** Maximum age in seconds (default: 300 = 5 minutes) */
+    toleranceSeconds?: number;
+}
+/**
+ * Verify a webhook signature without parsing the payload.
+ *
+ * @param payload - Raw request body
+ * @param signature - Value of X-Tritonium-Signature header
+ * @param secret - Your webhook signing secret
+ * @returns true if signature is valid
+ */
+declare function verifySignature(payload: string | Buffer, signature: string, secret: string): boolean;
+/**
+ * Verify that a webhook timestamp is within acceptable range.
+ *
+ * @param timestamp - ISO 8601 timestamp string
+ * @param toleranceSeconds - Maximum age in seconds (default: 300)
+ * @returns true if timestamp is valid
+ */
+declare function verifyTimestamp(timestamp: string, toleranceSeconds?: number): boolean;
+/**
+ * Verify a webhook and parse the event.
+ *
+ * This is the main function for processing incoming webhooks. It:
+ * 1. Verifies the timestamp is not too old (replay protection)
+ * 2. Verifies the HMAC signature
+ * 3. Parses and returns the event
+ *
+ * @param options - Verification options
+ * @returns Parsed and verified webhook event
+ * @throws WebhookExpiredError if timestamp is too old
+ * @throws WebhookSignatureError if signature is invalid
+ * @throws WebhookVerificationError if payload cannot be parsed
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { verifyWebhook, WebhookVerificationError } from '@tritonium/api-client/webhooks';
+ *
+ * const app = express();
+ * const WEBHOOK_SECRET = 'whsec_your_secret';
+ *
+ * app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+ *   try {
+ *     const event = verifyWebhook({
+ *       payload: req.body,
+ *       signature: req.headers['x-tritonium-signature'] as string,
+ *       timestamp: req.headers['x-tritonium-timestamp'] as string,
+ *       secret: WEBHOOK_SECRET,
+ *     });
+ *
+ *     switch (event.eventType) {
+ *       case 'review.received':
+ *         handleReview(event.data);
+ *         break;
+ *       case 'alert.triggered':
+ *         handleAlert(event.data);
+ *         break;
+ *     }
+ *
+ *     res.json({ status: 'ok' });
+ *   } catch (e) {
+ *     if (e instanceof WebhookVerificationError) {
+ *       res.status(401).json({ error: e.message });
+ *     } else {
+ *       throw e;
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare function verifyWebhook<T = Record<string, unknown>>(options: VerifyWebhookOptions): WebhookEvent<T>;
+/**
+ * Alias for verifyWebhook for compatibility with other webhook libraries.
+ */
+declare const constructEvent: typeof verifyWebhook;
+/**
+ * Type guard to check if an error is a WebhookVerificationError.
+ */
+declare function isWebhookError(error: unknown): error is WebhookVerificationError;
+/**
+ * Type definitions for specific event payloads.
+ */
+interface ReviewReceivedData {
+    review_id: string;
+    platform: string;
+    rating: number;
+    title?: string;
+    text: string;
+    author?: string;
+    review_date: string;
+    country?: string;
+    version?: string;
+}
+interface AlertTriggeredData {
+    alert_id: string;
+    rule_id: string;
+    rule_name: string;
+    severity: 'low' | 'medium' | 'high' | 'critical';
+    message: string;
+    current_value?: number;
+    threshold?: number;
+}
+interface CrisisDetectedData {
+    severity: 'low' | 'medium' | 'high' | 'critical';
+    type: string;
+    message: string;
+    affected_period?: string;
+    metrics?: Record<string, unknown>;
+}
+
+export { type AlertTriggeredData, type CrisisDetectedData, type EventType, EventTypes, type ReviewReceivedData, type VerifyWebhookOptions, type WebhookEvent, WebhookExpiredError, WebhookSignatureError, WebhookVerificationError, constructEvent, isWebhookError, verifySignature, verifyTimestamp, verifyWebhook };

package/dist/webhooks.js

@@ -0,0 +1,125 @@
+'use strict';
+
+var crypto = require('crypto');
+
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
+var crypto__namespace = /*#__PURE__*/_interopNamespace(crypto);
+
+// webhooks.ts
+var WebhookVerificationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "WebhookVerificationError";
+  }
+};
+var WebhookExpiredError = class extends WebhookVerificationError {
+  constructor(message) {
+    super(message);
+    this.name = "WebhookExpiredError";
+  }
+};
+var WebhookSignatureError = class extends WebhookVerificationError {
+  constructor(message) {
+    super(message);
+    this.name = "WebhookSignatureError";
+  }
+};
+var EventTypes = {
+  CRISIS_DETECTED: "crisis.detected",
+  INSIGHT_GENERATED: "insight.generated",
+  REVIEW_RECEIVED: "review.received",
+  ANALYSIS_COMPLETED: "analysis.completed",
+  ALERT_TRIGGERED: "alert.triggered",
+  TEST_PING: "test.ping"
+};
+function verifySignature(payload, signature, secret) {
+  const payloadBuffer = typeof payload === "string" ? Buffer.from(payload) : payload;
+  const receivedSig = signature.startsWith("sha256=") ? signature.slice(7) : signature;
+  const expectedSig = crypto__namespace.createHmac("sha256", secret).update(payloadBuffer).digest("hex");
+  try {
+    return crypto__namespace.timingSafeEqual(
+      Buffer.from(receivedSig),
+      Buffer.from(expectedSig)
+    );
+  } catch {
+    return false;
+  }
+}
+function verifyTimestamp(timestamp, toleranceSeconds = 300) {
+  try {
+    const webhookTime = new Date(timestamp).getTime();
+    const now = Date.now();
+    const ageMs = Math.abs(now - webhookTime);
+    return ageMs <= toleranceSeconds * 1e3;
+  } catch {
+    return false;
+  }
+}
+function verifyWebhook(options) {
+  const { payload, signature, timestamp, secret, toleranceSeconds = 300 } = options;
+  if (!verifyTimestamp(timestamp, toleranceSeconds)) {
+    throw new WebhookExpiredError(
+      `Webhook timestamp is too old or invalid: ${timestamp}`
+    );
+  }
+  if (!verifySignature(payload, signature, secret)) {
+    throw new WebhookSignatureError("Invalid webhook signature");
+  }
+  let data;
+  try {
+    const payloadStr = typeof payload === "string" ? payload : payload.toString("utf-8");
+    data = JSON.parse(payloadStr);
+  } catch (e) {
+    throw new WebhookVerificationError(`Invalid webhook payload: ${e}`);
+  }
+  let eventTimestamp;
+  try {
+    eventTimestamp = new Date(
+      data.timestamp || timestamp
+    );
+  } catch {
+    eventTimestamp = /* @__PURE__ */ new Date();
+  }
+  return {
+    eventId: data.event_id || "",
+    eventType: data.event_type || "",
+    timestamp: eventTimestamp,
+    tenantId: data.tenant_id || "",
+    appUuid: data.app_uuid,
+    data: data.data || {},
+    rawPayload: data
+  };
+}
+var constructEvent = verifyWebhook;
+function isWebhookError(error) {
+  return error instanceof WebhookVerificationError;
+}
+
+exports.EventTypes = EventTypes;
+exports.WebhookExpiredError = WebhookExpiredError;
+exports.WebhookSignatureError = WebhookSignatureError;
+exports.WebhookVerificationError = WebhookVerificationError;
+exports.constructEvent = constructEvent;
+exports.isWebhookError = isWebhookError;
+exports.verifySignature = verifySignature;
+exports.verifyTimestamp = verifyTimestamp;
+exports.verifyWebhook = verifyWebhook;
+//# sourceMappingURL=webhooks.js.map
+//# sourceMappingURL=webhooks.js.map

package/dist/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../webhooks.ts"],"names":["crypto"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAwBO,IAAM,wBAAA,GAAN,cAAuC,KAAA,CAAM;AAAA,EAClD,YAAY,OAAA,EAAiB;AAC3B,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,IAAA,GAAO,0BAAA;AAAA,EACd;AACF;AAKO,IAAM,mBAAA,GAAN,cAAkC,wBAAA,CAAyB;AAAA,EAChE,YAAY,OAAA,EAAiB;AAC3B,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,IAAA,GAAO,qBAAA;AAAA,EACd;AACF;AAKO,IAAM,qBAAA,GAAN,cAAoC,wBAAA,CAAyB;AAAA,EAClE,YAAY,OAAA,EAAiB;AAC3B,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,IAAA,GAAO,uBAAA;AAAA,EACd;AACF;AAyBO,IAAM,UAAA,GAAa;AAAA,EACxB,eAAA,EAAiB,iBAAA;AAAA,EACjB,iBAAA,EAAmB,mBAAA;AAAA,EACnB,eAAA,EAAiB,iBAAA;AAAA,EACjB,kBAAA,EAAoB,oBAAA;AAAA,EACpB,eAAA,EAAiB,iBAAA;AAAA,EACjB,SAAA,EAAW;AACb;AA4BO,SAAS,eAAA,CACd,OAAA,EACA,SAAA,EACA,MAAA,EACS;AACT,EAAA,MAAM,gBACJ,OAAO,OAAA,KAAY,WAAW,MAAA,CAAO,IAAA,CAAK,OAAO,CAAA,GAAI,OAAA;AAGvD,EAAA,MAAM,WAAA,GAAc,UAAU,UAAA,CAAW,SAAS,IAC9C,SAAA,CAAU,KAAA,CAAM,CAAC,CAAA,GACjB,SAAA;AAGJ,EAAA,MAAM,WAAA,GACHA,6BAAW,QAAA,EAAU,MAAM,EAC3B,MAAA,CAAO,aAAa,CAAA,CACpB,MAAA,CAAO,KAAK,CAAA;AAGf,EAAA,IAAI;AACF,IAAA,OAAcA,iBAAA,CAAA,eAAA;AAAA,MACZ,MAAA,CAAO,KAAK,WAAW,CAAA;AAAA,MACvB,MAAA,CAAO,KAAK,WAAW;AAAA,KACzB;AAAA,EACF,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,KAAA;AAAA,EACT;AACF;AASO,SAAS,eAAA,CACd,SAAA,EACA,gBAAA,GAA2B,GAAA,EAClB;AACT,EAAA,IAAI;AACF,IAAA,MAAM,WAAA,GAAc,IAAI,IAAA,CAAK,SAAS,EAAE,OAAA,EAAQ;AAChD,IAAA,MAAM,GAAA,GAAM,KAAK,GAAA,EAAI;AACrB,IAAA,MAAM,KAAA,GAAQ,IAAA,CAAK,GAAA,CAAI,GAAA,GAAM,WAAW,CAAA;AACxC,IAAA,OAAO,SAAS,gBAAA,GAAmB,GAAA;AAAA,EACrC,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,KAAA;AAAA,EACT;AACF;AAqDO,SAAS,cACd,OAAA,EACiB;AACjB,EAAA,MAAM,EAAE,OAAA,EAAS,SAAA,EAAW,WAAW,MAAA,EAAQ,gBAAA,GAAmB,KAAI,GAAI,OAAA;AAG1E,EAAA,IAAI,CAAC,eAAA,CAAgB,SAAA,EAAW,gBAAgB,CAAA,EAAG;AACjD,IAAA,MAAM,IAAI,mBAAA;AAAA,MACR,4CAA4C,SAAS,CAAA;AAAA,KACvD;AAAA,EACF;AAGA,EAAA,IAAI,CAAC,eAAA,CAAgB,OAAA,EAAS,SAAA,EAAW,MAAM,CAAA,EAAG;AAChD,IAAA,MAAM,IAAI,sBAAsB,2BAA2B,CAAA;AAAA,EAC7D;AAGA,EAAA,IAAI,IAAA;AACJ,EAAA,IAAI;AACF,IAAA,MAAM,aACJ,OAAO,OAAA,KAAY,WAAW,OAAA,GAAU,OAAA,CAAQ,SAAS,OAAO,CAAA;AAClE,IAAA,IAAA,GAAO,IAAA,CAAK,MAAM,UAAU,CAAA;AAAA,EAC9B,SAAS,CAAA,EAAG;AACV,IAAA,MAAM,IAAI,wBAAA,CAAyB,CAAA,yBAAA,EAA4B,CAAC,CAAA,CAAE,CAAA;AAAA,EACpE;AAGA,EAAA,IAAI,cAAA;AACJ,EAAA,IAAI;AACF,IAAA,cAAA,GAAiB,IAAI,IAAA;AAAA,MAClB,KAAK,SAAA,IAAwB;AAAA,KAChC;AAAA,EACF,CAAA,CAAA,MAAQ;AACN,IAAA,cAAA,uBAAqB,IAAA,EAAK;AAAA,EAC5B;AAEA,EAAA,OAAO;AAAA,IACL,OAAA,EAAS,KAAK,QAAA,IAAsB,EAAA;AAAA,IACpC,SAAA,EAAW,KAAK,UAAA,IAAwB,EAAA;AAAA,IACxC,SAAA,EAAW,cAAA;AAAA,IACX,QAAA,EAAU,KAAK,SAAA,IAAuB,EAAA;AAAA,IACtC,SAAS,IAAA,CAAK,QAAA;AAAA,IACd,IAAA,EAAO,IAAA,CAAK,IAAA,IAAQ,EAAC;AAAA,IACrB,UAAA,EAAY;AAAA,GACd;AACF;AAKO,IAAM,cAAA,GAAiB;AAKvB,SAAS,eAAe,KAAA,EAAmD;AAChF,EAAA,OAAO,KAAA,YAAiB,wBAAA;AAC1B","file":"webhooks.js","sourcesContent":["/**\n * Webhook verification utilities for Tritonium.\n *\n * This module provides functions for verifying webhook signatures and handling\n * incoming webhook events from Tritonium.\n *\n * @example\n * ```typescript\n * import { verifyWebhook, WebhookEvent } from './webhooks';\n *\n * const event = verifyWebhook({\n *   payload: requestBody,\n *   signature: headers['x-tritonium-signature'],\n *   timestamp: headers['x-tritonium-timestamp'],\n *   secret: 'whsec_your_secret',\n * });\n * ```\n */\n\nimport * as crypto from 'crypto';\n\n/**\n * Error thrown when webhook verification fails.\n */\nexport class WebhookVerificationError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'WebhookVerificationError';\n  }\n}\n\n/**\n * Error thrown when webhook timestamp is too old.\n */\nexport class WebhookExpiredError extends WebhookVerificationError {\n  constructor(message: string) {\n    super(message);\n    this.name = 'WebhookExpiredError';\n  }\n}\n\n/**\n * Error thrown when webhook signature is invalid.\n */\nexport class WebhookSignatureError extends WebhookVerificationError {\n  constructor(message: string) {\n    super(message);\n    this.name = 'WebhookSignatureError';\n  }\n}\n\n/**\n * Parsed webhook event from Tritonium.\n */\nexport interface WebhookEvent<T = Record<string, unknown>> {\n  /** Unique identifier for this event */\n  eventId: string;\n  /** Type of event (e.g., 'review.received', 'alert.triggered') */\n  eventType: string;\n  /** When the event occurred */\n  timestamp: Date;\n  /** Tenant that owns this event */\n  tenantId: string;\n  /** Optional app UUID related to the event */\n  appUuid?: string;\n  /** Event-specific payload data */\n  data: T;\n  /** Original JSON payload */\n  rawPayload: Record<string, unknown>;\n}\n\n/**\n * Tritonium webhook event types.\n */\nexport const EventTypes = {\n  CRISIS_DETECTED: 'crisis.detected',\n  INSIGHT_GENERATED: 'insight.generated',\n  REVIEW_RECEIVED: 'review.received',\n  ANALYSIS_COMPLETED: 'analysis.completed',\n  ALERT_TRIGGERED: 'alert.triggered',\n  TEST_PING: 'test.ping',\n} as const;\n\nexport type EventType = (typeof EventTypes)[keyof typeof EventTypes];\n\n/**\n * Options for webhook verification.\n */\nexport interface VerifyWebhookOptions {\n  /** Raw request body (string or Buffer) */\n  payload: string | Buffer;\n  /** Value of X-Tritonium-Signature header */\n  signature: string;\n  /** Value of X-Tritonium-Timestamp header */\n  timestamp: string;\n  /** Your webhook signing secret */\n  secret: string;\n  /** Maximum age in seconds (default: 300 = 5 minutes) */\n  toleranceSeconds?: number;\n}\n\n/**\n * Verify a webhook signature without parsing the payload.\n *\n * @param payload - Raw request body\n * @param signature - Value of X-Tritonium-Signature header\n * @param secret - Your webhook signing secret\n * @returns true if signature is valid\n */\nexport function verifySignature(\n  payload: string | Buffer,\n  signature: string,\n  secret: string\n): boolean {\n  const payloadBuffer =\n    typeof payload === 'string' ? Buffer.from(payload) : payload;\n\n  // Extract the hex signature (remove 'sha256=' prefix)\n  const receivedSig = signature.startsWith('sha256=')\n    ? signature.slice(7)\n    : signature;\n\n  // Compute expected signature\n  const expectedSig = crypto\n    .createHmac('sha256', secret)\n    .update(payloadBuffer)\n    .digest('hex');\n\n  // Constant-time comparison\n  try {\n    return crypto.timingSafeEqual(\n      Buffer.from(receivedSig),\n      Buffer.from(expectedSig)\n    );\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Verify that a webhook timestamp is within acceptable range.\n *\n * @param timestamp - ISO 8601 timestamp string\n * @param toleranceSeconds - Maximum age in seconds (default: 300)\n * @returns true if timestamp is valid\n */\nexport function verifyTimestamp(\n  timestamp: string,\n  toleranceSeconds: number = 300\n): boolean {\n  try {\n    const webhookTime = new Date(timestamp).getTime();\n    const now = Date.now();\n    const ageMs = Math.abs(now - webhookTime);\n    return ageMs <= toleranceSeconds * 1000;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Verify a webhook and parse the event.\n *\n * This is the main function for processing incoming webhooks. It:\n * 1. Verifies the timestamp is not too old (replay protection)\n * 2. Verifies the HMAC signature\n * 3. Parses and returns the event\n *\n * @param options - Verification options\n * @returns Parsed and verified webhook event\n * @throws WebhookExpiredError if timestamp is too old\n * @throws WebhookSignatureError if signature is invalid\n * @throws WebhookVerificationError if payload cannot be parsed\n *\n * @example\n * ```typescript\n * import express from 'express';\n * import { verifyWebhook, WebhookVerificationError } from '@tritonium/api-client/webhooks';\n *\n * const app = express();\n * const WEBHOOK_SECRET = 'whsec_your_secret';\n *\n * app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {\n *   try {\n *     const event = verifyWebhook({\n *       payload: req.body,\n *       signature: req.headers['x-tritonium-signature'] as string,\n *       timestamp: req.headers['x-tritonium-timestamp'] as string,\n *       secret: WEBHOOK_SECRET,\n *     });\n *\n *     switch (event.eventType) {\n *       case 'review.received':\n *         handleReview(event.data);\n *         break;\n *       case 'alert.triggered':\n *         handleAlert(event.data);\n *         break;\n *     }\n *\n *     res.json({ status: 'ok' });\n *   } catch (e) {\n *     if (e instanceof WebhookVerificationError) {\n *       res.status(401).json({ error: e.message });\n *     } else {\n *       throw e;\n *     }\n *   }\n * });\n * ```\n */\nexport function verifyWebhook<T = Record<string, unknown>>(\n  options: VerifyWebhookOptions\n): WebhookEvent<T> {\n  const { payload, signature, timestamp, secret, toleranceSeconds = 300 } = options;\n\n  // Check timestamp first (replay protection)\n  if (!verifyTimestamp(timestamp, toleranceSeconds)) {\n    throw new WebhookExpiredError(\n      `Webhook timestamp is too old or invalid: ${timestamp}`\n    );\n  }\n\n  // Verify signature\n  if (!verifySignature(payload, signature, secret)) {\n    throw new WebhookSignatureError('Invalid webhook signature');\n  }\n\n  // Parse payload\n  let data: Record<string, unknown>;\n  try {\n    const payloadStr =\n      typeof payload === 'string' ? payload : payload.toString('utf-8');\n    data = JSON.parse(payloadStr);\n  } catch (e) {\n    throw new WebhookVerificationError(`Invalid webhook payload: ${e}`);\n  }\n\n  // Parse timestamp\n  let eventTimestamp: Date;\n  try {\n    eventTimestamp = new Date(\n      (data.timestamp as string) || timestamp\n    );\n  } catch {\n    eventTimestamp = new Date();\n  }\n\n  return {\n    eventId: data.event_id as string || '',\n    eventType: data.event_type as string || '',\n    timestamp: eventTimestamp,\n    tenantId: data.tenant_id as string || '',\n    appUuid: data.app_uuid as string | undefined,\n    data: (data.data || {}) as T,\n    rawPayload: data,\n  };\n}\n\n/**\n * Alias for verifyWebhook for compatibility with other webhook libraries.\n */\nexport const constructEvent = verifyWebhook;\n\n/**\n * Type guard to check if an error is a WebhookVerificationError.\n */\nexport function isWebhookError(error: unknown): error is WebhookVerificationError {\n  return error instanceof WebhookVerificationError;\n}\n\n/**\n * Type definitions for specific event payloads.\n */\nexport interface ReviewReceivedData {\n  review_id: string;\n  platform: string;\n  rating: number;\n  title?: string;\n  text: string;\n  author?: string;\n  review_date: string;\n  country?: string;\n  version?: string;\n}\n\nexport interface AlertTriggeredData {\n  alert_id: string;\n  rule_id: string;\n  rule_name: string;\n  severity: 'low' | 'medium' | 'high' | 'critical';\n  message: string;\n  current_value?: number;\n  threshold?: number;\n}\n\nexport interface CrisisDetectedData {\n  severity: 'low' | 'medium' | 'high' | 'critical';\n  type: string;\n  message: string;\n  affected_period?: string;\n  metrics?: Record<string, unknown>;\n}\n"]}

package/dist/webhooks.mjs

@@ -0,0 +1,95 @@
+import * as crypto from 'crypto';
+
+// webhooks.ts
+var WebhookVerificationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "WebhookVerificationError";
+  }
+};
+var WebhookExpiredError = class extends WebhookVerificationError {
+  constructor(message) {
+    super(message);
+    this.name = "WebhookExpiredError";
+  }
+};
+var WebhookSignatureError = class extends WebhookVerificationError {
+  constructor(message) {
+    super(message);
+    this.name = "WebhookSignatureError";
+  }
+};
+var EventTypes = {
+  CRISIS_DETECTED: "crisis.detected",
+  INSIGHT_GENERATED: "insight.generated",
+  REVIEW_RECEIVED: "review.received",
+  ANALYSIS_COMPLETED: "analysis.completed",
+  ALERT_TRIGGERED: "alert.triggered",
+  TEST_PING: "test.ping"
+};
+function verifySignature(payload, signature, secret) {
+  const payloadBuffer = typeof payload === "string" ? Buffer.from(payload) : payload;
+  const receivedSig = signature.startsWith("sha256=") ? signature.slice(7) : signature;
+  const expectedSig = crypto.createHmac("sha256", secret).update(payloadBuffer).digest("hex");
+  try {
+    return crypto.timingSafeEqual(
+      Buffer.from(receivedSig),
+      Buffer.from(expectedSig)
+    );
+  } catch {
+    return false;
+  }
+}
+function verifyTimestamp(timestamp, toleranceSeconds = 300) {
+  try {
+    const webhookTime = new Date(timestamp).getTime();
+    const now = Date.now();
+    const ageMs = Math.abs(now - webhookTime);
+    return ageMs <= toleranceSeconds * 1e3;
+  } catch {
+    return false;
+  }
+}
+function verifyWebhook(options) {
+  const { payload, signature, timestamp, secret, toleranceSeconds = 300 } = options;
+  if (!verifyTimestamp(timestamp, toleranceSeconds)) {
+    throw new WebhookExpiredError(
+      `Webhook timestamp is too old or invalid: ${timestamp}`
+    );
+  }
+  if (!verifySignature(payload, signature, secret)) {
+    throw new WebhookSignatureError("Invalid webhook signature");
+  }
+  let data;
+  try {
+    const payloadStr = typeof payload === "string" ? payload : payload.toString("utf-8");
+    data = JSON.parse(payloadStr);
+  } catch (e) {
+    throw new WebhookVerificationError(`Invalid webhook payload: ${e}`);
+  }
+  let eventTimestamp;
+  try {
+    eventTimestamp = new Date(
+      data.timestamp || timestamp
+    );
+  } catch {
+    eventTimestamp = /* @__PURE__ */ new Date();
+  }
+  return {
+    eventId: data.event_id || "",
+    eventType: data.event_type || "",
+    timestamp: eventTimestamp,
+    tenantId: data.tenant_id || "",
+    appUuid: data.app_uuid,
+    data: data.data || {},
+    rawPayload: data
+  };
+}
+var constructEvent = verifyWebhook;
+function isWebhookError(error) {
+  return error instanceof WebhookVerificationError;
+}
+
+export { EventTypes, WebhookExpiredError, WebhookSignatureError, WebhookVerificationError, constructEvent, isWebhookError, verifySignature, verifyTimestamp, verifyWebhook };
+//# sourceMappingURL=webhooks.mjs.map
+//# sourceMappingURL=webhooks.mjs.map

package/dist/webhooks.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../webhooks.ts"],"names":[],"mappings":"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","file":"webhooks.mjs","sourcesContent":["/**\n * Webhook verification utilities for Tritonium.\n *\n * This module provides functions for verifying webhook signatures and handling\n * incoming webhook events from Tritonium.\n *\n * @example\n * ```typescript\n * import { verifyWebhook, WebhookEvent } from './webhooks';\n *\n * const event = verifyWebhook({\n *   payload: requestBody,\n *   signature: headers['x-tritonium-signature'],\n *   timestamp: headers['x-tritonium-timestamp'],\n *   secret: 'whsec_your_secret',\n * });\n * ```\n */\n\nimport * as crypto from 'crypto';\n\n/**\n * Error thrown when webhook verification fails.\n */\nexport class WebhookVerificationError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'WebhookVerificationError';\n  }\n}\n\n/**\n * Error thrown when webhook timestamp is too old.\n */\nexport class WebhookExpiredError extends WebhookVerificationError {\n  constructor(message: string) {\n    super(message);\n    this.name = 'WebhookExpiredError';\n  }\n}\n\n/**\n * Error thrown when webhook signature is invalid.\n */\nexport class WebhookSignatureError extends WebhookVerificationError {\n  constructor(message: string) {\n    super(message);\n    this.name = 'WebhookSignatureError';\n  }\n}\n\n/**\n * Parsed webhook event from Tritonium.\n */\nexport interface WebhookEvent<T = Record<string, unknown>> {\n  /** Unique identifier for this event */\n  eventId: string;\n  /** Type of event (e.g., 'review.received', 'alert.triggered') */\n  eventType: string;\n  /** When the event occurred */\n  timestamp: Date;\n  /** Tenant that owns this event */\n  tenantId: string;\n  /** Optional app UUID related to the event */\n  appUuid?: string;\n  /** Event-specific payload data */\n  data: T;\n  /** Original JSON payload */\n  rawPayload: Record<string, unknown>;\n}\n\n/**\n * Tritonium webhook event types.\n */\nexport const EventTypes = {\n  CRISIS_DETECTED: 'crisis.detected',\n  INSIGHT_GENERATED: 'insight.generated',\n  REVIEW_RECEIVED: 'review.received',\n  ANALYSIS_COMPLETED: 'analysis.completed',\n  ALERT_TRIGGERED: 'alert.triggered',\n  TEST_PING: 'test.ping',\n} as const;\n\nexport type EventType = (typeof EventTypes)[keyof typeof EventTypes];\n\n/**\n * Options for webhook verification.\n */\nexport interface VerifyWebhookOptions {\n  /** Raw request body (string or Buffer) */\n  payload: string | Buffer;\n  /** Value of X-Tritonium-Signature header */\n  signature: string;\n  /** Value of X-Tritonium-Timestamp header */\n  timestamp: string;\n  /** Your webhook signing secret */\n  secret: string;\n  /** Maximum age in seconds (default: 300 = 5 minutes) */\n  toleranceSeconds?: number;\n}\n\n/**\n * Verify a webhook signature without parsing the payload.\n *\n * @param payload - Raw request body\n * @param signature - Value of X-Tritonium-Signature header\n * @param secret - Your webhook signing secret\n * @returns true if signature is valid\n */\nexport function verifySignature(\n  payload: string | Buffer,\n  signature: string,\n  secret: string\n): boolean {\n  const payloadBuffer =\n    typeof payload === 'string' ? Buffer.from(payload) : payload;\n\n  // Extract the hex signature (remove 'sha256=' prefix)\n  const receivedSig = signature.startsWith('sha256=')\n    ? signature.slice(7)\n    : signature;\n\n  // Compute expected signature\n  const expectedSig = crypto\n    .createHmac('sha256', secret)\n    .update(payloadBuffer)\n    .digest('hex');\n\n  // Constant-time comparison\n  try {\n    return crypto.timingSafeEqual(\n      Buffer.from(receivedSig),\n      Buffer.from(expectedSig)\n    );\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Verify that a webhook timestamp is within acceptable range.\n *\n * @param timestamp - ISO 8601 timestamp string\n * @param toleranceSeconds - Maximum age in seconds (default: 300)\n * @returns true if timestamp is valid\n */\nexport function verifyTimestamp(\n  timestamp: string,\n  toleranceSeconds: number = 300\n): boolean {\n  try {\n    const webhookTime = new Date(timestamp).getTime();\n    const now = Date.now();\n    const ageMs = Math.abs(now - webhookTime);\n    return ageMs <= toleranceSeconds * 1000;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Verify a webhook and parse the event.\n *\n * This is the main function for processing incoming webhooks. It:\n * 1. Verifies the timestamp is not too old (replay protection)\n * 2. Verifies the HMAC signature\n * 3. Parses and returns the event\n *\n * @param options - Verification options\n * @returns Parsed and verified webhook event\n * @throws WebhookExpiredError if timestamp is too old\n * @throws WebhookSignatureError if signature is invalid\n * @throws WebhookVerificationError if payload cannot be parsed\n *\n * @example\n * ```typescript\n * import express from 'express';\n * import { verifyWebhook, WebhookVerificationError } from '@tritonium/api-client/webhooks';\n *\n * const app = express();\n * const WEBHOOK_SECRET = 'whsec_your_secret';\n *\n * app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {\n *   try {\n *     const event = verifyWebhook({\n *       payload: req.body,\n *       signature: req.headers['x-tritonium-signature'] as string,\n *       timestamp: req.headers['x-tritonium-timestamp'] as string,\n *       secret: WEBHOOK_SECRET,\n *     });\n *\n *     switch (event.eventType) {\n *       case 'review.received':\n *         handleReview(event.data);\n *         break;\n *       case 'alert.triggered':\n *         handleAlert(event.data);\n *         break;\n *     }\n *\n *     res.json({ status: 'ok' });\n *   } catch (e) {\n *     if (e instanceof WebhookVerificationError) {\n *       res.status(401).json({ error: e.message });\n *     } else {\n *       throw e;\n *     }\n *   }\n * });\n * ```\n */\nexport function verifyWebhook<T = Record<string, unknown>>(\n  options: VerifyWebhookOptions\n): WebhookEvent<T> {\n  const { payload, signature, timestamp, secret, toleranceSeconds = 300 } = options;\n\n  // Check timestamp first (replay protection)\n  if (!verifyTimestamp(timestamp, toleranceSeconds)) {\n    throw new WebhookExpiredError(\n      `Webhook timestamp is too old or invalid: ${timestamp}`\n    );\n  }\n\n  // Verify signature\n  if (!verifySignature(payload, signature, secret)) {\n    throw new WebhookSignatureError('Invalid webhook signature');\n  }\n\n  // Parse payload\n  let data: Record<string, unknown>;\n  try {\n    const payloadStr =\n      typeof payload === 'string' ? payload : payload.toString('utf-8');\n    data = JSON.parse(payloadStr);\n  } catch (e) {\n    throw new WebhookVerificationError(`Invalid webhook payload: ${e}`);\n  }\n\n  // Parse timestamp\n  let eventTimestamp: Date;\n  try {\n    eventTimestamp = new Date(\n      (data.timestamp as string) || timestamp\n    );\n  } catch {\n    eventTimestamp = new Date();\n  }\n\n  return {\n    eventId: data.event_id as string || '',\n    eventType: data.event_type as string || '',\n    timestamp: eventTimestamp,\n    tenantId: data.tenant_id as string || '',\n    appUuid: data.app_uuid as string | undefined,\n    data: (data.data || {}) as T,\n    rawPayload: data,\n  };\n}\n\n/**\n * Alias for verifyWebhook for compatibility with other webhook libraries.\n */\nexport const constructEvent = verifyWebhook;\n\n/**\n * Type guard to check if an error is a WebhookVerificationError.\n */\nexport function isWebhookError(error: unknown): error is WebhookVerificationError {\n  return error instanceof WebhookVerificationError;\n}\n\n/**\n * Type definitions for specific event payloads.\n */\nexport interface ReviewReceivedData {\n  review_id: string;\n  platform: string;\n  rating: number;\n  title?: string;\n  text: string;\n  author?: string;\n  review_date: string;\n  country?: string;\n  version?: string;\n}\n\nexport interface AlertTriggeredData {\n  alert_id: string;\n  rule_id: string;\n  rule_name: string;\n  severity: 'low' | 'medium' | 'high' | 'critical';\n  message: string;\n  current_value?: number;\n  threshold?: number;\n}\n\nexport interface CrisisDetectedData {\n  severity: 'low' | 'medium' | 'high' | 'critical';\n  type: string;\n  message: string;\n  affected_period?: string;\n  metrics?: Record<string, unknown>;\n}\n"]}