@hookflo/tern 4.1.1 → 4.2.0

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,80 @@
+"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 asNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value : undefined;
+}
+function asObject(value) {
+    return value && typeof value === 'object' ? value : undefined;
+}
+function pickNonEmptyString(...values) {
+    for (const value of values) {
+        const normalized = asNonEmptyString(value);
+        if (normalized)
+            return normalized;
+    }
+    return undefined;
+}
+function resolveSourceFromObject(value) {
+    const object = asObject(value);
+    if (!object)
+        return undefined;
+    return pickNonEmptyString(object.platform, object.provider, object.source, object.service, object.origin, object.type);
+}
+function resolveEventIdFromObject(value) {
+    const object = asObject(value);
+    if (!object)
+        return undefined;
+    return pickNonEmptyString(object.eventId, object.event_id, object.id, object.request_id, object.webhook_id, object.messageId, object.message_id);
+}
+function resolveSource(options) {
+    const metadata = options.metadata || {};
+    const metadataPayload = asObject(metadata.payload);
+    const metadataEvent = asObject(metadata.event);
+    const metadataData = asObject(metadata.data);
+    const metadataBody = asObject(metadata.body);
+    return pickNonEmptyString(options.source, metadata.source, metadata.platform, metadata.provider, metadata.eventSource, resolveSourceFromObject(metadataPayload), resolveSourceFromObject(metadataEvent), resolveSourceFromObject(metadataData), resolveSourceFromObject(metadataBody));
+}
+function resolveEventId(options) {
+    const metadata = options.metadata || {};
+    const metadataPayload = asObject(metadata.payload);
+    const metadataEvent = asObject(metadata.event);
+    const metadataData = asObject(metadata.data);
+    return pickNonEmptyString(options.eventId, options.dlqId, metadata.eventId, metadata.event_id, metadata.messageId, metadata.message_id, metadata.webhookId, metadata.webhook_id, metadata.id, resolveEventIdFromObject(metadataPayload), resolveEventIdFromObject(metadataEvent), resolveEventIdFromObject(metadataData));
+}
+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,
+        source: resolveSource(options) || 'unknown',
+        title,
+        message,
+        severity,
+        replayLabel,
+        eventId: resolveEventId(options),
+    };
+}

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)
@@ -51,6 +52,9 @@ function deriveStatus(value) {
         return 'failed';
     return 'retrying';
 }
+function withoutUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entryValue]) => entryValue !== undefined));
+}
 function createTernControls(config) {
     return {
         async dlq() {
@@ -114,5 +118,64 @@ function createTernControls(config) {
                 : mapped;
             return statusFiltered.slice(0, filter.limit ?? 20);
         },
+        async alert(options = {}) {
+            let replayMeta = {};
+            let resolvedSource = options.source;
+            let resolvedEventId = options.eventId;
+            if (options.dlq && (!resolvedSource || !resolvedEventId)) {
+                try {
+                    const dlqMessages = await this.dlq();
+                    const matchingMessage = dlqMessages.find((message) => message.dlqId === options.dlqId);
+                    resolvedSource = resolvedSource || matchingMessage?.platform;
+                    resolvedEventId = resolvedEventId || matchingMessage?.id;
+                }
+                catch (error) {
+                    replayMeta = {
+                        ...replayMeta,
+                        dlqLookupError: error.message,
+                    };
+                }
+            }
+            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,
+                source: resolvedSource,
+                eventId: resolvedEventId || options.dlqId,
+                metadata: withoutUndefined({
+                    ...(options.metadata || {}),
+                    source: resolvedSource || options.metadata?.source,
+                    eventId: resolvedEventId || options.metadata?.eventId,
+                    ...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/queue.js

@@ -194,7 +194,11 @@ async function handleReceive(request, platform, secret, queueConfig, toleranceIn
     }
     try {
         await client.publishJSON(publishPayload);
-        return new Response(JSON.stringify({ queued: true }), {
+        return new Response(JSON.stringify({
+            queued: true,
+            platform,
+            eventId: verificationResult.eventId,
+        }), {
             status: 200,
             headers: { 'Content-Type': 'application/json' },
         });

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.0",
   "description": "A robust, scalable webhook verification framework supporting multiple platforms and signature algorithms",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",