pingram 1.0.10-alpha.1159 → 1.0.10-alpha.1160

package/dist/generate-client.js

@@ -93,7 +93,7 @@ function extractApisFromOpenAPI(openapiPath) {
         .map((tag) => ({
         name: tag,
         className: `${toPascalCase(tag)}Api`, // e.g., "UsersApi"
-        propertyName: toCamelCase(tag) // e.g., "users"
+        propertyName: toCamelCase(tag)
     }));
 }
 /**

package/dist/generated/src/models/EventsWebhookResponse.d.ts

@@ -33,6 +33,12 @@ export interface EventsWebhookResponse {
      * @memberof EventsWebhookResponse
      */
     events: Array<EventsWebhookResponseEventsEnum>;
+    /**
+     * HMAC secret for verifying webhook signatures. Use this with your X-Pingram-Signature verification.
+     * @type {string}
+     * @memberof EventsWebhookResponse
+     */
+    secret: string;
 }
 /**
  * @export
@@ -50,6 +56,7 @@ export declare enum EventsWebhookResponseEventsEnum {
     SMS_DELIVERED = "SMS_DELIVERED",
     SMS_FAILED = "SMS_FAILED",
     SMS_UNSUBSCRIBE = "SMS_UNSUBSCRIBE",
+    SMS_SUBSCRIBE = "SMS_SUBSCRIBE",
     SMS_INBOUND = "SMS_INBOUND",
     PUSH_FAILED = "PUSH_FAILED",
     PUSH_UNSUBSCRIBE = "PUSH_UNSUBSCRIBE",

package/dist/generated/src/models/EventsWebhookResponse.js

@@ -36,6 +36,7 @@ var EventsWebhookResponseEventsEnum;
     EventsWebhookResponseEventsEnum["SMS_DELIVERED"] = "SMS_DELIVERED";
     EventsWebhookResponseEventsEnum["SMS_FAILED"] = "SMS_FAILED";
     EventsWebhookResponseEventsEnum["SMS_UNSUBSCRIBE"] = "SMS_UNSUBSCRIBE";
+    EventsWebhookResponseEventsEnum["SMS_SUBSCRIBE"] = "SMS_SUBSCRIBE";
     EventsWebhookResponseEventsEnum["SMS_INBOUND"] = "SMS_INBOUND";
     EventsWebhookResponseEventsEnum["PUSH_FAILED"] = "PUSH_FAILED";
     EventsWebhookResponseEventsEnum["PUSH_UNSUBSCRIBE"] = "PUSH_UNSUBSCRIBE";
@@ -57,6 +58,8 @@ function instanceOfEventsWebhookResponse(value) {
         return false;
     if (!('events' in value) || value['events'] === undefined)
         return false;
+    if (!('secret' in value) || value['secret'] === undefined)
+        return false;
     return true;
 }
 function EventsWebhookResponseFromJSON(json) {
@@ -69,7 +72,8 @@ function EventsWebhookResponseFromJSONTyped(json, ignoreDiscriminator) {
     return {
         webhookId: json['webhookId'],
         webhook: json['webhook'],
-        events: json['events']
+        events: json['events'],
+        secret: json['secret']
     };
 }
 function EventsWebhookResponseToJSON(json) {
@@ -82,6 +86,7 @@ function EventsWebhookResponseToJSONTyped(value, ignoreDiscriminator = false) {
     return {
         webhookId: value['webhookId'],
         webhook: value['webhook'],
-        events: value['events']
+        events: value['events'],
+        secret: value['secret']
     };
 }

package/dist/generated/src/models/EventsWebhookUpsertRequest.d.ts

@@ -44,6 +44,7 @@ export declare enum EventsWebhookUpsertRequestEventsEnum {
     SMS_DELIVERED = "SMS_DELIVERED",
     SMS_FAILED = "SMS_FAILED",
     SMS_UNSUBSCRIBE = "SMS_UNSUBSCRIBE",
+    SMS_SUBSCRIBE = "SMS_SUBSCRIBE",
     SMS_INBOUND = "SMS_INBOUND",
     PUSH_FAILED = "PUSH_FAILED",
     PUSH_UNSUBSCRIBE = "PUSH_UNSUBSCRIBE",

package/dist/generated/src/models/EventsWebhookUpsertRequest.js

@@ -36,6 +36,7 @@ var EventsWebhookUpsertRequestEventsEnum;
     EventsWebhookUpsertRequestEventsEnum["SMS_DELIVERED"] = "SMS_DELIVERED";
     EventsWebhookUpsertRequestEventsEnum["SMS_FAILED"] = "SMS_FAILED";
     EventsWebhookUpsertRequestEventsEnum["SMS_UNSUBSCRIBE"] = "SMS_UNSUBSCRIBE";
+    EventsWebhookUpsertRequestEventsEnum["SMS_SUBSCRIBE"] = "SMS_SUBSCRIBE";
     EventsWebhookUpsertRequestEventsEnum["SMS_INBOUND"] = "SMS_INBOUND";
     EventsWebhookUpsertRequestEventsEnum["PUSH_FAILED"] = "PUSH_FAILED";
     EventsWebhookUpsertRequestEventsEnum["PUSH_UNSUBSCRIBE"] = "PUSH_UNSUBSCRIBE";

package/dist/generated/src/models/LogsGetResponseLogsInner.d.ts

@@ -519,6 +519,66 @@ export interface LogsGetResponseLogsInner {
      * @memberof LogsGetResponseLogsInner
      */
     sms_replied_encoding?: string;
+    /**
+     *
+     * @type {string}
+     * @memberof LogsGetResponseLogsInner
+     */
+    sms_unsubscribe_at?: string;
+    /**
+     *
+     * @type {string}
+     * @memberof LogsGetResponseLogsInner
+     */
+    sms_unsubscribe_from?: string;
+    /**
+     *
+     * @type {string}
+     * @memberof LogsGetResponseLogsInner
+     */
+    sms_unsubscribe_keyword?: string;
+    /**
+     *
+     * @type {boolean}
+     * @memberof LogsGetResponseLogsInner
+     */
+    sms_unsubscribe_webhook_delivered?: boolean;
+    /**
+     *
+     * @type {string}
+     * @memberof LogsGetResponseLogsInner
+     */
+    sms_unsubscribe_webhook_res?: string;
+    /**
+     *
+     * @type {string}
+     * @memberof LogsGetResponseLogsInner
+     */
+    sms_subscribe_at?: string;
+    /**
+     *
+     * @type {string}
+     * @memberof LogsGetResponseLogsInner
+     */
+    sms_subscribe_from?: string;
+    /**
+     *
+     * @type {string}
+     * @memberof LogsGetResponseLogsInner
+     */
+    sms_subscribe_keyword?: string;
+    /**
+     *
+     * @type {boolean}
+     * @memberof LogsGetResponseLogsInner
+     */
+    sms_subscribe_webhook_delivered?: boolean;
+    /**
+     *
+     * @type {string}
+     * @memberof LogsGetResponseLogsInner
+     */
+    sms_subscribe_webhook_res?: string;
     /**
      *
      * @type {string}

package/dist/generated/src/models/LogsGetResponseLogsInner.js

@@ -581,6 +581,34 @@ function LogsGetResponseLogsInnerFromJSONTyped(json, ignoreDiscriminator) {
         sms_replied_encoding: json['sms_replied_encoding'] == null
             ? undefined
             : json['sms_replied_encoding'],
+        sms_unsubscribe_at: json['sms_unsubscribe_at'] == null
+            ? undefined
+            : json['sms_unsubscribe_at'],
+        sms_unsubscribe_from: json['sms_unsubscribe_from'] == null
+            ? undefined
+            : json['sms_unsubscribe_from'],
+        sms_unsubscribe_keyword: json['sms_unsubscribe_keyword'] == null
+            ? undefined
+            : json['sms_unsubscribe_keyword'],
+        sms_unsubscribe_webhook_delivered: json['sms_unsubscribe_webhook_delivered'] == null
+            ? undefined
+            : json['sms_unsubscribe_webhook_delivered'],
+        sms_unsubscribe_webhook_res: json['sms_unsubscribe_webhook_res'] == null
+            ? undefined
+            : json['sms_unsubscribe_webhook_res'],
+        sms_subscribe_at: json['sms_subscribe_at'] == null ? undefined : json['sms_subscribe_at'],
+        sms_subscribe_from: json['sms_subscribe_from'] == null
+            ? undefined
+            : json['sms_subscribe_from'],
+        sms_subscribe_keyword: json['sms_subscribe_keyword'] == null
+            ? undefined
+            : json['sms_subscribe_keyword'],
+        sms_subscribe_webhook_delivered: json['sms_subscribe_webhook_delivered'] == null
+            ? undefined
+            : json['sms_subscribe_webhook_delivered'],
+        sms_subscribe_webhook_res: json['sms_subscribe_webhook_res'] == null
+            ? undefined
+            : json['sms_subscribe_webhook_res'],
         web_push_sent_token: json['web_push_sent_token'] == null
             ? undefined
             : json['web_push_sent_token'],
@@ -831,6 +859,16 @@ function LogsGetResponseLogsInnerToJSONTyped(value, ignoreDiscriminator = false)
         sms_replied_text: value['sms_replied_text'],
         sms_replied_segments: value['sms_replied_segments'],
         sms_replied_encoding: value['sms_replied_encoding'],
+        sms_unsubscribe_at: value['sms_unsubscribe_at'],
+        sms_unsubscribe_from: value['sms_unsubscribe_from'],
+        sms_unsubscribe_keyword: value['sms_unsubscribe_keyword'],
+        sms_unsubscribe_webhook_delivered: value['sms_unsubscribe_webhook_delivered'],
+        sms_unsubscribe_webhook_res: value['sms_unsubscribe_webhook_res'],
+        sms_subscribe_at: value['sms_subscribe_at'],
+        sms_subscribe_from: value['sms_subscribe_from'],
+        sms_subscribe_keyword: value['sms_subscribe_keyword'],
+        sms_subscribe_webhook_delivered: value['sms_subscribe_webhook_delivered'],
+        sms_subscribe_webhook_res: value['sms_subscribe_webhook_res'],
         web_push_sent_token: value['web_push_sent_token'],
         web_push_sent_at: value['web_push_sent_at'],
         web_push_sent_after: value['web_push_sent_after'],

package/dist/generated/src/models/WebhookEvent.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Pingram
+ * Internal API for notification delivery and management
+ *
+ * The version of the OpenAPI document: 1.0.0
+ *
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+import type { ChannelsEnum } from './ChannelsEnum';
+/**
+ * Webhook event payload sent to customer endpoints. Use this type with SDK webhook verification methods (e.g., verify from 'pingram/webhooks').
+ * @export
+ * @interface WebhookEvent
+ */
+export interface WebhookEvent {
+    /**
+     *
+     * @type {string}
+     * @memberof WebhookEvent
+     */
+    eventType: WebhookEventEventTypeEnum;
+    /**
+     *
+     * @type {ChannelsEnum}
+     * @memberof WebhookEvent
+     */
+    channel: ChannelsEnum;
+    /**
+     * User ID the notification was sent to.
+     * @type {string}
+     * @memberof WebhookEvent
+     */
+    userId: string;
+    /**
+     * Notification type ID.
+     * @type {string}
+     * @memberof WebhookEvent
+     */
+    notificationId: string;
+    /**
+     * Unique tracking ID for this notification instance.
+     * @type {string}
+     * @memberof WebhookEvent
+     */
+    trackingId: string;
+    /**
+     * Failure code for *_FAILED events.
+     * @type {string}
+     * @memberof WebhookEvent
+     */
+    failureCode?: string;
+    /**
+     * Clicked URL for EMAIL_CLICK events.
+     * @type {string}
+     * @memberof WebhookEvent
+     */
+    clickedLink?: string;
+    /**
+     * Link tags for EMAIL_CLICK events.
+     * @type {{ [key: string]: Array<string>; }}
+     * @memberof WebhookEvent
+     */
+    clickedLinkTags?: {
+        [key: string]: Array<string>;
+    };
+}
+/**
+ * @export
+ * @enum {string}
+ */
+export declare enum WebhookEventEventTypeEnum {
+    EMAIL_OPEN = "EMAIL_OPEN",
+    EMAIL_CLICK = "EMAIL_CLICK",
+    EMAIL_FAILED = "EMAIL_FAILED",
+    EMAIL_DELIVERED = "EMAIL_DELIVERED",
+    EMAIL_UNSUBSCRIBE = "EMAIL_UNSUBSCRIBE",
+    EMAIL_INBOUND = "EMAIL_INBOUND",
+    INAPP_WEB_FAILED = "INAPP_WEB_FAILED",
+    INAPP_WEB_UNSUBSCRIBE = "INAPP_WEB_UNSUBSCRIBE",
+    SMS_DELIVERED = "SMS_DELIVERED",
+    SMS_FAILED = "SMS_FAILED",
+    SMS_UNSUBSCRIBE = "SMS_UNSUBSCRIBE",
+    SMS_SUBSCRIBE = "SMS_SUBSCRIBE",
+    SMS_INBOUND = "SMS_INBOUND",
+    PUSH_FAILED = "PUSH_FAILED",
+    PUSH_UNSUBSCRIBE = "PUSH_UNSUBSCRIBE",
+    CALL_FAILED = "CALL_FAILED",
+    CALL_UNSUBSCRIBE = "CALL_UNSUBSCRIBE",
+    WEB_PUSH_FAILED = "WEB_PUSH_FAILED",
+    WEB_PUSH_UNSUBSCRIBE = "WEB_PUSH_UNSUBSCRIBE",
+    SLACK_FAILED = "SLACK_FAILED",
+    SLACK_UNSUBSCRIBE = "SLACK_UNSUBSCRIBE",
+    VOICE_INBOUND = "VOICE_INBOUND"
+}
+/**
+ * Check if a given object implements the WebhookEvent interface.
+ */
+export declare function instanceOfWebhookEvent(value: object): value is WebhookEvent;
+export declare function WebhookEventFromJSON(json: any): WebhookEvent;
+export declare function WebhookEventFromJSONTyped(json: any, ignoreDiscriminator: boolean): WebhookEvent;
+export declare function WebhookEventToJSON(json: any): WebhookEvent;
+export declare function WebhookEventToJSONTyped(value?: WebhookEvent | null, ignoreDiscriminator?: boolean): any;

package/dist/generated/src/models/WebhookEvent.js

@@ -0,0 +1,103 @@
+"use strict";
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Pingram
+ * Internal API for notification delivery and management
+ *
+ * The version of the OpenAPI document: 1.0.0
+ *
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookEventEventTypeEnum = void 0;
+exports.instanceOfWebhookEvent = instanceOfWebhookEvent;
+exports.WebhookEventFromJSON = WebhookEventFromJSON;
+exports.WebhookEventFromJSONTyped = WebhookEventFromJSONTyped;
+exports.WebhookEventToJSON = WebhookEventToJSON;
+exports.WebhookEventToJSONTyped = WebhookEventToJSONTyped;
+const ChannelsEnum_1 = require("./ChannelsEnum");
+/**
+ * @export
+ * @enum {string}
+ */
+var WebhookEventEventTypeEnum;
+(function (WebhookEventEventTypeEnum) {
+    WebhookEventEventTypeEnum["EMAIL_OPEN"] = "EMAIL_OPEN";
+    WebhookEventEventTypeEnum["EMAIL_CLICK"] = "EMAIL_CLICK";
+    WebhookEventEventTypeEnum["EMAIL_FAILED"] = "EMAIL_FAILED";
+    WebhookEventEventTypeEnum["EMAIL_DELIVERED"] = "EMAIL_DELIVERED";
+    WebhookEventEventTypeEnum["EMAIL_UNSUBSCRIBE"] = "EMAIL_UNSUBSCRIBE";
+    WebhookEventEventTypeEnum["EMAIL_INBOUND"] = "EMAIL_INBOUND";
+    WebhookEventEventTypeEnum["INAPP_WEB_FAILED"] = "INAPP_WEB_FAILED";
+    WebhookEventEventTypeEnum["INAPP_WEB_UNSUBSCRIBE"] = "INAPP_WEB_UNSUBSCRIBE";
+    WebhookEventEventTypeEnum["SMS_DELIVERED"] = "SMS_DELIVERED";
+    WebhookEventEventTypeEnum["SMS_FAILED"] = "SMS_FAILED";
+    WebhookEventEventTypeEnum["SMS_UNSUBSCRIBE"] = "SMS_UNSUBSCRIBE";
+    WebhookEventEventTypeEnum["SMS_SUBSCRIBE"] = "SMS_SUBSCRIBE";
+    WebhookEventEventTypeEnum["SMS_INBOUND"] = "SMS_INBOUND";
+    WebhookEventEventTypeEnum["PUSH_FAILED"] = "PUSH_FAILED";
+    WebhookEventEventTypeEnum["PUSH_UNSUBSCRIBE"] = "PUSH_UNSUBSCRIBE";
+    WebhookEventEventTypeEnum["CALL_FAILED"] = "CALL_FAILED";
+    WebhookEventEventTypeEnum["CALL_UNSUBSCRIBE"] = "CALL_UNSUBSCRIBE";
+    WebhookEventEventTypeEnum["WEB_PUSH_FAILED"] = "WEB_PUSH_FAILED";
+    WebhookEventEventTypeEnum["WEB_PUSH_UNSUBSCRIBE"] = "WEB_PUSH_UNSUBSCRIBE";
+    WebhookEventEventTypeEnum["SLACK_FAILED"] = "SLACK_FAILED";
+    WebhookEventEventTypeEnum["SLACK_UNSUBSCRIBE"] = "SLACK_UNSUBSCRIBE";
+    WebhookEventEventTypeEnum["VOICE_INBOUND"] = "VOICE_INBOUND";
+})(WebhookEventEventTypeEnum || (exports.WebhookEventEventTypeEnum = WebhookEventEventTypeEnum = {}));
+/**
+ * Check if a given object implements the WebhookEvent interface.
+ */
+function instanceOfWebhookEvent(value) {
+    if (!('eventType' in value) || value['eventType'] === undefined)
+        return false;
+    if (!('channel' in value) || value['channel'] === undefined)
+        return false;
+    if (!('userId' in value) || value['userId'] === undefined)
+        return false;
+    if (!('notificationId' in value) || value['notificationId'] === undefined)
+        return false;
+    if (!('trackingId' in value) || value['trackingId'] === undefined)
+        return false;
+    return true;
+}
+function WebhookEventFromJSON(json) {
+    return WebhookEventFromJSONTyped(json, false);
+}
+function WebhookEventFromJSONTyped(json, ignoreDiscriminator) {
+    if (json == null) {
+        return json;
+    }
+    return {
+        eventType: json['eventType'],
+        channel: (0, ChannelsEnum_1.ChannelsEnumFromJSON)(json['channel']),
+        userId: json['userId'],
+        notificationId: json['notificationId'],
+        trackingId: json['trackingId'],
+        failureCode: json['failureCode'] == null ? undefined : json['failureCode'],
+        clickedLink: json['clickedLink'] == null ? undefined : json['clickedLink'],
+        clickedLinkTags: json['clickedLinkTags'] == null ? undefined : json['clickedLinkTags']
+    };
+}
+function WebhookEventToJSON(json) {
+    return WebhookEventToJSONTyped(json, false);
+}
+function WebhookEventToJSONTyped(value, ignoreDiscriminator = false) {
+    if (value == null) {
+        return value;
+    }
+    return {
+        eventType: value['eventType'],
+        channel: (0, ChannelsEnum_1.ChannelsEnumToJSON)(value['channel']),
+        userId: value['userId'],
+        notificationId: value['notificationId'],
+        trackingId: value['trackingId'],
+        failureCode: value['failureCode'],
+        clickedLink: value['clickedLink'],
+        clickedLinkTags: value['clickedLinkTags']
+    };
+}

package/dist/generated/src/models/index.d.ts

@@ -198,4 +198,5 @@ export * from './TemplatePostRequest';
 export * from './UpdateAddressRequest';
 export * from './User';
 export * from './UserSuppressionDeleteResponse';
+export * from './WebhookEvent';
 export * from './WebhookResponse';

package/dist/generated/src/models/index.js

@@ -216,4 +216,5 @@ __exportStar(require("./TemplatePostRequest"), exports);
 __exportStar(require("./UpdateAddressRequest"), exports);
 __exportStar(require("./User"), exports);
 __exportStar(require("./UserSuppressionDeleteResponse"), exports);
+__exportStar(require("./WebhookEvent"), exports);
 __exportStar(require("./WebhookResponse"), exports);

package/dist/package.json

@@ -1,10 +1,20 @@
 {
     "name": "pingram",
-    "version": "1.0.10-alpha.1159",
+    "version": "1.0.10-alpha.1160",
     "description": "Official Node.js SDK for Pingram - Send notifications via Email, SMS, Push, In-App, and more",
     "main": "dist/index.js",
     "module": "dist/index.js",
     "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./webhooks": {
+            "types": "./dist/src/webhooks.d.ts",
+            "default": "./dist/src/webhooks.js"
+        }
+    },
     "scripts": {
         "build": "tsc",
         "clean": "rm -rf dist",

package/dist/src/webhooks.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Webhook verification utilities for Pingram webhooks.
+ *
+ * @example
+ * ```typescript
+ * import { verify } from 'pingram/webhooks';
+ * import type { WebhookEvent } from 'pingram';
+ *
+ * const event = verify({
+ *   payload: await req.text(),
+ *   headers: {
+ *     id: req.headers.get('X-Pingram-Id')!,
+ *     signature: req.headers.get('X-Pingram-Signature')!,
+ *     timestamp: req.headers.get('X-Pingram-Timestamp')!,
+ *   },
+ *   secret: process.env.PINGRAM_WEBHOOK_SECRET!,
+ * });
+ *
+ * if (event.eventType === 'EMAIL_CLICK') {
+ *   console.log('Clicked:', event.clickedLink);
+ * }
+ * ```
+ */
+import type { WebhookEvent } from '../generated/src/models/WebhookEvent';
+/**
+ * Error thrown when webhook signature verification fails.
+ */
+export declare class WebhookSignatureError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when webhook timestamp is outside tolerance.
+ */
+export declare class WebhookTimestampError extends Error {
+    constructor(message: string);
+}
+/**
+ * Options for verifying a webhook.
+ */
+export interface WebhookVerifyOptions {
+    /** Raw request body as string or Buffer */
+    payload: string | Buffer;
+    /** Headers from the webhook request */
+    headers: {
+        /** X-Pingram-Id header value */
+        id: string;
+        /** X-Pingram-Signature header value */
+        signature: string;
+        /** X-Pingram-Timestamp header value */
+        timestamp: string;
+    };
+    /** Webhook secret from your Pingram dashboard */
+    secret: string;
+    /** Maximum age of webhook in seconds (default: 300 = 5 minutes) */
+    tolerance?: number;
+}
+/**
+ * Verify webhook signature and return the parsed event.
+ *
+ * @param options - Verification options
+ * @returns Parsed webhook event
+ * @throws WebhookSignatureError if signature is invalid
+ * @throws WebhookTimestampError if timestamp is outside tolerance
+ *
+ * @example
+ * ```typescript
+ * const event = verify({
+ *   payload: await req.text(),
+ *   headers: {
+ *     id: req.headers.get('X-Pingram-Id')!,
+ *     signature: req.headers.get('X-Pingram-Signature')!,
+ *     timestamp: req.headers.get('X-Pingram-Timestamp')!,
+ *   },
+ *   secret: process.env.PINGRAM_WEBHOOK_SECRET!,
+ * });
+ * ```
+ */
+export declare function verify(options: WebhookVerifyOptions): WebhookEvent;
+/**
+ * Webhooks helper object exporting all verification utilities.
+ */
+export declare const webhooks: {
+    verify: typeof verify;
+    WebhookSignatureError: typeof WebhookSignatureError;
+    WebhookTimestampError: typeof WebhookTimestampError;
+};

package/dist/src/webhooks.js

@@ -0,0 +1,137 @@
+"use strict";
+/**
+ * Webhook verification utilities for Pingram webhooks.
+ *
+ * @example
+ * ```typescript
+ * import { verify } from 'pingram/webhooks';
+ * import type { WebhookEvent } from 'pingram';
+ *
+ * const event = verify({
+ *   payload: await req.text(),
+ *   headers: {
+ *     id: req.headers.get('X-Pingram-Id')!,
+ *     signature: req.headers.get('X-Pingram-Signature')!,
+ *     timestamp: req.headers.get('X-Pingram-Timestamp')!,
+ *   },
+ *   secret: process.env.PINGRAM_WEBHOOK_SECRET!,
+ * });
+ *
+ * if (event.eventType === 'EMAIL_CLICK') {
+ *   console.log('Clicked:', event.clickedLink);
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.webhooks = exports.WebhookTimestampError = exports.WebhookSignatureError = void 0;
+exports.verify = verify;
+const crypto_1 = require("crypto");
+/**
+ * Error thrown when webhook signature verification fails.
+ */
+class WebhookSignatureError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'WebhookSignatureError';
+    }
+}
+exports.WebhookSignatureError = WebhookSignatureError;
+/**
+ * Error thrown when webhook timestamp is outside tolerance.
+ */
+class WebhookTimestampError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'WebhookTimestampError';
+    }
+}
+exports.WebhookTimestampError = WebhookTimestampError;
+/**
+ * Default timestamp tolerance in seconds (5 minutes).
+ */
+const DEFAULT_TOLERANCE_SECONDS = 300;
+/**
+ * Parse version prefix and signature from the signature header.
+ * Format: v1,{hex-signature}
+ */
+function parseSignature(signature) {
+    const [version, sig] = signature.split(',', 2);
+    if (version !== 'v1' || !sig) {
+        throw new WebhookSignatureError('Invalid signature format');
+    }
+    return sig;
+}
+/**
+ * Compute HMAC-SHA256 signature for a payload.
+ * Format: HMAC-SHA256(id + "." + timestamp + "." + payload)
+ */
+function computeSignature(payload, secret, timestamp, messageId) {
+    const signedPayload = `${messageId}.${timestamp}.${payload}`;
+    return (0, crypto_1.createHmac)('sha256', secret).update(signedPayload).digest('hex');
+}
+/**
+ * Constant-time string comparison to prevent timing attacks.
+ */
+function secureCompare(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    return (0, crypto_1.timingSafeEqual)(Buffer.from(a), Buffer.from(b));
+}
+/**
+ * Verify webhook signature and return the parsed event.
+ *
+ * @param options - Verification options
+ * @returns Parsed webhook event
+ * @throws WebhookSignatureError if signature is invalid
+ * @throws WebhookTimestampError if timestamp is outside tolerance
+ *
+ * @example
+ * ```typescript
+ * const event = verify({
+ *   payload: await req.text(),
+ *   headers: {
+ *     id: req.headers.get('X-Pingram-Id')!,
+ *     signature: req.headers.get('X-Pingram-Signature')!,
+ *     timestamp: req.headers.get('X-Pingram-Timestamp')!,
+ *   },
+ *   secret: process.env.PINGRAM_WEBHOOK_SECRET!,
+ * });
+ * ```
+ */
+function verify(options) {
+    const tolerance = options.tolerance ?? DEFAULT_TOLERANCE_SECONDS;
+    const payloadString = typeof options.payload === 'string'
+        ? options.payload
+        : options.payload.toString('utf8');
+    const { id: messageId, signature, timestamp } = options.headers;
+    const { secret } = options;
+    const timestampMs = parseInt(timestamp, 10);
+    if (isNaN(timestampMs)) {
+        throw new WebhookTimestampError('Invalid timestamp format');
+    }
+    const now = Date.now();
+    const age = Math.abs(now - timestampMs) / 1000;
+    if (age > tolerance) {
+        throw new WebhookTimestampError(`Webhook timestamp is outside tolerance (${age.toFixed(0)}s > ${tolerance}s)`);
+    }
+    const rawSignature = parseSignature(signature);
+    const expectedSignature = computeSignature(payloadString, secret, timestamp, messageId);
+    if (!secureCompare(expectedSignature, rawSignature)) {
+        throw new WebhookSignatureError('Invalid webhook signature');
+    }
+    try {
+        return JSON.parse(payloadString);
+    }
+    catch {
+        throw new WebhookSignatureError('Invalid JSON payload');
+    }
+}
+/**
+ * Webhooks helper object exporting all verification utilities.
+ */
+exports.webhooks = {
+    verify,
+    WebhookSignatureError,
+    WebhookTimestampError
+};

package/package.json

@@ -1,10 +1,20 @@
 {
   "name": "pingram",
-  "version": "1.0.10-alpha.1159",
+  "version": "1.0.10-alpha.1160",
   "description": "Official Node.js SDK for Pingram - Send notifications via Email, SMS, Push, In-App, and more",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./webhooks": {
+      "types": "./dist/src/webhooks.d.ts",
+      "default": "./dist/src/webhooks.js"
+    }
+  },
   "scripts": {
     "build": "tsc",
     "clean": "rm -rf dist",