@hookflo/tern 4.1.1 → 4.2.3-beta

package/README.md

@@ -481,6 +481,39 @@ interface WebhookConfig {
 }
 ```
 
+
+## Alerting (Slack + Discord)
+
+For the simplest DX, configure webhooks once in `createTernControls` and call `controls.alert(...)`.
+
+```ts
+import { createTernControls } from '@hookflo/tern/upstash';
+
+const controls = createTernControls({
+  token: process.env.QSTASH_TOKEN!,
+  notifications: {
+    slackWebhookUrl: process.env.SLACK_WEBHOOK_URL,
+    discordWebhookUrl: process.env.DISCORD_WEBHOOK_URL,
+  },
+});
+
+// Non-DLQ event alert with defaults
+await controls.alert();
+
+// DLQ alert + replay flow
+await controls.alert({
+  dlq: true,
+  dlqId: 'dlq_xxx',
+});
+```
+
+### Behavior
+
+- `controls.alert()` with no params sends a normal (non-DLQ) alert with internal defaults.
+- `controls.alert({ dlq: true, dlqId })` sends a DLQ alert and attempts replay internally via `controls.replay(dlqId)`.
+- `eventId` is auto-filled from `dlqId` for DLQ alerts.
+- Optional overrides like `message`, `metadata`, `source`, or `branding` can still be passed.
+
 ## Testing
 
 ### Run All Tests

package/dist/alerts.d.ts

@@ -0,0 +1,7 @@
+export * from './notifications';
+export declare const __alertInternals: {
+    resolveDestinations: typeof import("./notifications/utils").resolveDestinations;
+    normalizeAlertOptions: typeof import("./notifications/utils").normalizeAlertOptions;
+    buildSlackPayload: typeof import("./notifications/channels/slack").buildSlackPayload;
+    buildDiscordPayload: typeof import("./notifications/channels/discord").buildDiscordPayload;
+};

package/dist/alerts.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.__alertInternals = void 0;
+__exportStar(require("./notifications"), exports);
+const notifications_1 = require("./notifications");
+// Backward-compatible alias used by previous version internals.
+exports.__alertInternals = notifications_1.__notificationInternals;

package/dist/index.d.ts

@@ -31,4 +31,5 @@ export { createAlgorithmVerifier } from './verifiers/algorithms';
 export { createCustomVerifier } from './verifiers/custom-algorithms';
 export { normalizePayload, getPlatformNormalizationCategory, getPlatformsByCategory, } from './normalization/simple';
 export * from './adapters';
+export * from './alerts';
 export default WebhookVerificationService;

package/dist/index.js

@@ -352,4 +352,5 @@ Object.defineProperty(exports, "normalizePayload", { enumerable: true, get: func
 Object.defineProperty(exports, "getPlatformNormalizationCategory", { enumerable: true, get: function () { return simple_2.getPlatformNormalizationCategory; } });
 Object.defineProperty(exports, "getPlatformsByCategory", { enumerable: true, get: function () { return simple_2.getPlatformsByCategory; } });
 __exportStar(require("./adapters"), exports);
+__exportStar(require("./alerts"), exports);
 exports.default = WebhookVerificationService;

package/dist/notifications/channels/discord/build-payload.d.ts

@@ -0,0 +1,17 @@
+import type { AlertPayloadBuilderInput } from "../../types";
+export declare function buildDiscordPayload(input: AlertPayloadBuilderInput): {
+    embeds: {
+        title: string;
+        description: string;
+        color: number;
+        fields: {
+            name: string;
+            value: string;
+            inline?: boolean;
+        }[];
+        footer: {
+            text: string;
+        } | undefined;
+        timestamp: string;
+    }[];
+};

package/dist/notifications/channels/discord/build-payload.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildDiscordPayload = buildDiscordPayload;
+const utils_1 = require("../../utils");
+const constants_1 = require("../../constants");
+function buildDiscordPayload(input) {
+    const isDLQ = input.dlq;
+    const title = isDLQ ? "Dead Letter Queue — Event Failed" : "Webhook Received";
+    const description = isDLQ
+        ? "Event exhausted all retries. Manual replay required."
+        : "Event verified and queued for processing.";
+    const fields = [];
+    if (input.source) {
+        fields.push({ name: "Platform", value: input.source, inline: true });
+    }
+    fields.push({
+        name: "Severity",
+        value: input.severity.toLowerCase(),
+        inline: true,
+    });
+    if (isDLQ) {
+        fields.push({ name: "Queue", value: "dlq", inline: true });
+    }
+    if (input.eventId) {
+        fields.push({
+            name: isDLQ ? "DLQ ID" : "Event ID",
+            value: `\`${input.eventId}\``,
+            inline: false,
+        });
+    }
+    const metadataString = (0, utils_1.compactMetadata)(input.metadata);
+    if (metadataString) {
+        fields.push({ name: "Details", value: `\`\`\`${metadataString}\`\`\`` });
+    }
+    const replayLine = input.replayUrl
+        ? `\n\n[${input.replayLabel ?? "Replay Event"}](${input.replayUrl})`
+        : "";
+    const footerText = input.branding === false ? undefined : "Alert from Tern · tern.hookflo.com";
+    return {
+        embeds: [
+            {
+                title,
+                description: `${description}${replayLine}`,
+                color: parseInt(constants_1.severityColorMap[input.severity].replace("#", ""), 16),
+                fields,
+                footer: footerText ? { text: footerText } : undefined,
+                timestamp: new Date().toISOString(),
+            },
+        ],
+    };
+}

package/dist/notifications/channels/discord/index.d.ts

@@ -0,0 +1 @@
+export { buildDiscordPayload } from './build-payload';

package/dist/notifications/channels/discord/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildDiscordPayload = void 0;
+var build_payload_1 = require("./build-payload");
+Object.defineProperty(exports, "buildDiscordPayload", { enumerable: true, get: function () { return build_payload_1.buildDiscordPayload; } });

package/dist/notifications/channels/slack/build-payload.d.ts

@@ -0,0 +1,5 @@
+import type { AlertPayloadBuilderInput } from "../../types";
+export declare function buildSlackPayload(input: AlertPayloadBuilderInput): {
+    text: string;
+    blocks: Record<string, unknown>[];
+};

package/dist/notifications/channels/slack/build-payload.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSlackPayload = buildSlackPayload;
+const utils_1 = require("../../utils");
+const constants_1 = require("../../constants");
+function buildSlackPayload(input) {
+    const isDLQ = input.dlq;
+    const title = isDLQ ? "Dead Letter Queue — Event Failed" : "Webhook Received";
+    const message = isDLQ
+        ? "Event exhausted all retries. Manual replay required."
+        : "Event verified and queued for processing.";
+    const fields = [
+        input.source
+            ? { type: "mrkdwn", text: `*Platform*\n${input.source}` }
+            : null,
+        {
+            type: "mrkdwn",
+            text: `*Severity*\n${input.severity.toLowerCase()}`,
+        },
+        isDLQ ? { type: "mrkdwn", text: "*Queue*\ndlq" } : null,
+        input.eventId
+            ? {
+                type: "mrkdwn",
+                text: `*${isDLQ ? "DLQ ID" : "Event ID"}*\n\`${input.eventId}\``,
+            }
+            : null,
+    ].filter(Boolean);
+    const blocks = [
+        {
+            type: "section",
+            text: {
+                type: "mrkdwn",
+                text: `*${title}*\n${message}`,
+            },
+            fields,
+        },
+    ];
+    const metadataString = (0, utils_1.compactMetadata)(input.metadata);
+    if (metadataString) {
+        blocks.push({
+            type: "section",
+            text: {
+                type: "mrkdwn",
+                text: `\`\`\`${metadataString}\`\`\``,
+            },
+        });
+    }
+    if (input.replayUrl) {
+        blocks.push({
+            type: "actions",
+            elements: [
+                {
+                    type: "button",
+                    text: {
+                        type: "plain_text",
+                        text: input.replayLabel ?? "Replay Event",
+                        emoji: false,
+                    },
+                    url: input.replayUrl,
+                    style: "danger",
+                },
+            ],
+        });
+    }
+    if (input.branding !== false) {
+        blocks.push({
+            type: "context",
+            elements: [
+                {
+                    type: "mrkdwn",
+                    text: `Alert from <${constants_1.TERN_BRAND_URL}|Tern>`,
+                },
+            ],
+        });
+    }
+    return {
+        text: title,
+        blocks,
+    };
+}

package/dist/notifications/channels/slack/index.d.ts

@@ -0,0 +1 @@
+export { buildSlackPayload } from './build-payload';

package/dist/notifications/channels/slack/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSlackPayload = void 0;
+var build_payload_1 = require("./build-payload");
+Object.defineProperty(exports, "buildSlackPayload", { enumerable: true, get: function () { return build_payload_1.buildSlackPayload; } });

package/dist/notifications/constants.d.ts

@@ -0,0 +1,8 @@
+import type { AlertSeverity } from './types';
+export declare const TERN_BRAND_URL = "https://tern.hookflo.com";
+export declare const DEFAULT_DLQ_TITLE = "DLQ Event Alert";
+export declare const DEFAULT_ALERT_TITLE = "Webhook Event Alert";
+export declare const DEFAULT_REPLAY_LABEL = "Replay DLQ Event";
+export declare const DEFAULT_DLQ_MESSAGE = "Webhook event moved to DLQ after retry attempts.";
+export declare const DEFAULT_ALERT_MESSAGE = "Webhook event received.";
+export declare const severityColorMap: Record<AlertSeverity, string>;

package/dist/notifications/constants.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.severityColorMap = exports.DEFAULT_ALERT_MESSAGE = exports.DEFAULT_DLQ_MESSAGE = exports.DEFAULT_REPLAY_LABEL = exports.DEFAULT_ALERT_TITLE = exports.DEFAULT_DLQ_TITLE = exports.TERN_BRAND_URL = void 0;
+exports.TERN_BRAND_URL = 'https://tern.hookflo.com';
+exports.DEFAULT_DLQ_TITLE = 'DLQ Event Alert';
+exports.DEFAULT_ALERT_TITLE = 'Webhook Event Alert';
+exports.DEFAULT_REPLAY_LABEL = 'Replay DLQ Event';
+exports.DEFAULT_DLQ_MESSAGE = 'Webhook event moved to DLQ after retry attempts.';
+exports.DEFAULT_ALERT_MESSAGE = 'Webhook event received.';
+exports.severityColorMap = {
+    info: '#3B82F6',
+    warning: '#F59E0B',
+    error: '#EF4444',
+    critical: '#7C3AED',
+};

package/dist/notifications/index.d.ts

@@ -0,0 +1,10 @@
+export * from './types';
+import { normalizeAlertOptions, resolveDestinations } from './utils';
+import { buildSlackPayload } from './channels/slack';
+import { buildDiscordPayload } from './channels/discord';
+export declare const __notificationInternals: {
+    resolveDestinations: typeof resolveDestinations;
+    normalizeAlertOptions: typeof normalizeAlertOptions;
+    buildSlackPayload: typeof buildSlackPayload;
+    buildDiscordPayload: typeof buildDiscordPayload;
+};

package/dist/notifications/index.js

@@ -0,0 +1,27 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.__notificationInternals = void 0;
+__exportStar(require("./types"), exports);
+const utils_1 = require("./utils");
+const slack_1 = require("./channels/slack");
+const discord_1 = require("./channels/discord");
+exports.__notificationInternals = {
+    resolveDestinations: utils_1.resolveDestinations,
+    normalizeAlertOptions: utils_1.normalizeAlertOptions,
+    buildSlackPayload: slack_1.buildSlackPayload,
+    buildDiscordPayload: discord_1.buildDiscordPayload,
+};

package/dist/notifications/send-alert.d.ts

@@ -0,0 +1,2 @@
+import type { AlertConfig, SendAlertOptions, SendAlertSummary } from './types';
+export declare function sendAlert(config: AlertConfig, options: SendAlertOptions): Promise<SendAlertSummary>;

package/dist/notifications/send-alert.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sendAlert = sendAlert;
+const utils_1 = require("./utils");
+const slack_1 = require("./channels/slack");
+const discord_1 = require("./channels/discord");
+async function postWebhook(webhookUrl, body) {
+    try {
+        const response = await fetch(webhookUrl, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            return {
+                ok: false,
+                status: response.status,
+                error: `Webhook call failed with ${response.status}`,
+            };
+        }
+        return { ok: true, status: response.status };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error: error.message,
+        };
+    }
+}
+function buildPayload(channel, options) {
+    const normalized = (0, utils_1.normalizeAlertOptions)(options);
+    return channel === 'slack' ? (0, slack_1.buildSlackPayload)(normalized) : (0, discord_1.buildDiscordPayload)(normalized);
+}
+async function sendAlert(config, options) {
+    const destinations = (0, utils_1.resolveDestinations)(config);
+    if (destinations.length === 0) {
+        return {
+            success: false,
+            total: 0,
+            delivered: 0,
+            results: [{
+                    channel: 'slack',
+                    webhookUrl: '',
+                    ok: false,
+                    error: 'No valid alert webhook destinations configured',
+                }],
+        };
+    }
+    const results = await Promise.all(destinations.map(async (destination) => {
+        const payload = buildPayload(destination.channel, options);
+        const response = await postWebhook(destination.webhookUrl, payload);
+        return {
+            channel: destination.channel,
+            webhookUrl: destination.webhookUrl,
+            ok: response.ok,
+            status: response.status,
+            error: response.error,
+        };
+    }));
+    const delivered = results.filter((result) => result.ok).length;
+    return {
+        success: delivered === results.length,
+        total: results.length,
+        delivered,
+        results,
+    };
+}

package/dist/notifications/types.d.ts

@@ -0,0 +1,48 @@
+export type AlertSeverity = 'info' | 'warning' | 'error' | 'critical';
+export type AlertChannel = 'slack' | 'discord';
+export interface AlertChannelConfig {
+    webhookUrl: string;
+    enabled?: boolean;
+}
+export interface AlertConfig {
+    slack?: AlertChannelConfig;
+    discord?: AlertChannelConfig;
+}
+export interface SendAlertOptions {
+    dlq?: boolean;
+    dlqId?: string;
+    eventId?: string;
+    source?: string;
+    title?: string;
+    message?: string;
+    severity?: AlertSeverity;
+    replayUrl?: string;
+    replayLabel?: string;
+    metadata?: Record<string, unknown>;
+    branding?: boolean;
+}
+export interface SendAlertResult {
+    channel: AlertChannel;
+    webhookUrl: string;
+    ok: boolean;
+    status?: number;
+    error?: string;
+}
+export interface SendAlertSummary {
+    success: boolean;
+    total: number;
+    delivered: number;
+    results: SendAlertResult[];
+}
+export interface AlertDestination {
+    channel: AlertChannel;
+    webhookUrl: string;
+}
+export interface AlertPayloadBuilderInput extends SendAlertOptions {
+    title: string;
+    message: string;
+    severity: AlertSeverity;
+    replayLabel: string;
+    eventId?: string;
+    metadata?: Record<string, unknown>;
+}

package/dist/notifications/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/notifications/utils.d.ts

@@ -0,0 +1,4 @@
+import type { AlertConfig, AlertDestination, AlertPayloadBuilderInput, SendAlertOptions } from './types';
+export declare function compactMetadata(metadata?: Record<string, unknown>): string | undefined;
+export declare function resolveDestinations(config: AlertConfig): AlertDestination[];
+export declare function normalizeAlertOptions(options: SendAlertOptions): AlertPayloadBuilderInput;

package/dist/notifications/utils.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compactMetadata = compactMetadata;
+exports.resolveDestinations = resolveDestinations;
+exports.normalizeAlertOptions = normalizeAlertOptions;
+const constants_1 = require("./constants");
+function compactMetadata(metadata) {
+    if (!metadata || Object.keys(metadata).length === 0)
+        return undefined;
+    const entries = Object.entries(metadata).slice(0, 8);
+    return entries.map(([key, value]) => `${key}: ${String(value)}`).join('\n');
+}
+function resolveDestinations(config) {
+    const destinations = [];
+    if (config.slack?.enabled !== false && config.slack?.webhookUrl) {
+        destinations.push({ channel: 'slack', webhookUrl: config.slack.webhookUrl });
+    }
+    if (config.discord?.enabled !== false && config.discord?.webhookUrl) {
+        destinations.push({ channel: 'discord', webhookUrl: config.discord.webhookUrl });
+    }
+    return destinations;
+}
+function normalizeAlertOptions(options) {
+    const isDlq = options.dlq === true;
+    const severity = options.severity || (isDlq ? 'error' : 'info');
+    const title = options.title || (isDlq ? constants_1.DEFAULT_DLQ_TITLE : constants_1.DEFAULT_ALERT_TITLE);
+    const message = options.message || (isDlq ? constants_1.DEFAULT_DLQ_MESSAGE : constants_1.DEFAULT_ALERT_MESSAGE);
+    const replayLabel = options.replayLabel || constants_1.DEFAULT_REPLAY_LABEL;
+    return {
+        ...options,
+        dlq: isDlq,
+        title,
+        message,
+        severity,
+        replayLabel,
+        eventId: options.eventId || options.dlqId,
+    };
+}

package/dist/upstash/controls.d.ts

@@ -1,6 +1,2 @@
-import { DLQMessage, EventFilter, ReplayResult, TernControlsConfig, TernEvent } from './types';
-export declare function createTernControls(config: TernControlsConfig): {
-    dlq(): Promise<DLQMessage[]>;
-    replay(dlqId: string): Promise<ReplayResult>;
-    events(filter?: EventFilter): Promise<TernEvent[]>;
-};
+import { TernControls, TernControlsConfig } from './types';
+export declare function createTernControls(config: TernControlsConfig): TernControls;

package/dist/upstash/controls.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createTernControls = createTernControls;
+const send_alert_1 = require("../notifications/send-alert");
 const QSTASH_API_BASE = 'https://qstash.upstash.io/v2';
 function parseBody(body) {
     if (!body)
@@ -114,5 +115,45 @@ function createTernControls(config) {
                 : mapped;
             return statusFiltered.slice(0, filter.limit ?? 20);
         },
+        async alert(options = {}) {
+            let replayMeta = {};
+            if (options.dlq) {
+                if (!options.dlqId || options.dlqId.trim() === '') {
+                    throw new Error('[tern] controls.alert() with dlq: true requires dlqId.');
+                }
+                try {
+                    const replay = await this.replay(options.dlqId);
+                    replayMeta = {
+                        replayAttempted: true,
+                        replaySuccess: replay.success,
+                        replayedAt: replay.replayedAt,
+                        replayDlqId: options.dlqId,
+                    };
+                }
+                catch (error) {
+                    replayMeta = {
+                        replayAttempted: true,
+                        replaySuccess: false,
+                        replayDlqId: options.dlqId,
+                        replayError: error.message,
+                    };
+                }
+            }
+            return (0, send_alert_1.sendAlert)({
+                slack: config.notifications?.slackWebhookUrl
+                    ? { webhookUrl: config.notifications.slackWebhookUrl }
+                    : undefined,
+                discord: config.notifications?.discordWebhookUrl
+                    ? { webhookUrl: config.notifications.discordWebhookUrl }
+                    : undefined,
+            }, {
+                ...options,
+                eventId: options.eventId || options.dlqId,
+                metadata: {
+                    ...(options.metadata || {}),
+                    ...replayMeta,
+                },
+            });
+        },
     };
 }

package/dist/upstash/index.d.ts

@@ -1,3 +1,3 @@
 export { createTernControls } from './controls';
 export { handleQueuedRequest, handleProcess, handleReceive, resolveQueueConfig, } from './queue';
-export type { DLQMessage, EventFilter, QueueOption, QueuedMessage, ReplayResult, ResolvedQueueConfig, TernControlsConfig, TernEvent, } from './types';
+export type { ControlAlertOptions, DLQMessage, EventFilter, QueueOption, QueuedMessage, ReplayResult, ResolvedQueueConfig, TernControls, TernControlsConfig, TernEvent, } from './types';

package/dist/upstash/types.d.ts

@@ -1,4 +1,5 @@
 import { WebhookPlatform } from '../types';
+import type { SendAlertOptions, SendAlertSummary } from '../notifications/types';
 export type QueueOption = true | {
     token: string;
     signingKey: string;
@@ -13,6 +14,10 @@ export interface ResolvedQueueConfig {
 }
 export interface TernControlsConfig {
     token: string;
+    notifications?: {
+        slackWebhookUrl?: string;
+        discordWebhookUrl?: string;
+    };
 }
 export interface DLQMessage {
     id: string;
@@ -45,3 +50,16 @@ export interface QueuedMessage {
     payload: unknown;
     metadata: Record<string, unknown>;
 }
+export type ControlAlertOptions = (SendAlertOptions & {
+    dlq: true;
+    dlqId: string;
+}) | (SendAlertOptions & {
+    dlq?: false;
+    dlqId?: never;
+});
+export interface TernControls {
+    dlq: () => Promise<DLQMessage[]>;
+    replay: (dlqId: string) => Promise<ReplayResult>;
+    events: (filter?: EventFilter) => Promise<TernEvent[]>;
+    alert: (options?: ControlAlertOptions) => Promise<SendAlertSummary>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hookflo/tern",
-  "version": "4.1.1",
+  "version": "4.2.3-beta",
   "description": "A robust, scalable webhook verification framework supporting multiple platforms and signature algorithms",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",