@hookflo/tern 2.0.0 → 2.0.2

package/README.md

@@ -3,6 +3,10 @@
 A robust, algorithm-agnostic webhook verification framework that supports multiple platforms with accurate signature verification and payload retrieval.
 The same framework that secures webhook verification at [Hookflo](https://hookflo.com).
 
+⭐ Star this repo to support the project and help others discover it!  
+
+💬 Join the discussion & contribute in our Discord: [Hookflo Community](https://discord.com/invite/SNmCjU97nr)
+
 ```bash
 npm install @hookflo/tern
 ```
@@ -24,6 +28,12 @@ Supports HMAC-SHA256, HMAC-SHA1, HMAC-SHA512, and custom algorithms
 - **Flexible Configuration**: Custom signature configurations for any webhook format
 - **Type Safe**: Full TypeScript support with comprehensive type definitions
 - **Framework Agnostic**: Works with Express.js, Next.js, Cloudflare Workers, and more
+- **Body-Parser Safe Adapters**: Read raw request bodies correctly to avoid signature mismatch issues
+- **Multi-Provider Verification**: Verify and auto-detect across multiple providers with one API
+- **Payload Normalization**: Opt-in normalized event shape to reduce provider lock-in
+- **Category-aware Migration**: Normalize within provider categories (payment/auth/infrastructure) for safe platform switching
+- **Strong Typed Normalized Schemas**: Category types like `PaymentWebhookNormalized` and `AuthWebhookNormalized` for safe migrations
+- **Foundational Error Taxonomy**: Stable `errorCode` values (`INVALID_SIGNATURE`, `MISSING_SIGNATURE`, etc.)
 
 ## Why Tern?
 
@@ -65,6 +75,78 @@ if (result.isValid) {
 }
 ```
 
+### Universal Verification (auto-detect platform)
+
+```typescript
+import { WebhookVerificationService } from '@hookflo/tern';
+
+const result = await WebhookVerificationService.verifyAny(request, {
+  stripe: process.env.STRIPE_WEBHOOK_SECRET,
+  github: process.env.GITHUB_WEBHOOK_SECRET,
+  clerk: process.env.CLERK_WEBHOOK_SECRET,
+});
+
+if (result.isValid) {
+  console.log(`Verified ${result.platform} webhook`);
+}
+```
+
+### Category-aware Payload Normalization
+
+### Strongly-Typed Normalized Payloads
+
+```typescript
+import {
+  WebhookVerificationService,
+  PaymentWebhookNormalized,
+} from '@hookflo/tern';
+
+const result = await WebhookVerificationService.verifyWithPlatformConfig<PaymentWebhookNormalized>(
+  request,
+  'stripe',
+  process.env.STRIPE_WEBHOOK_SECRET!,
+  300,
+  { enabled: true, category: 'payment' },
+);
+
+if (result.isValid && result.payload?.event === 'payment.succeeded') {
+  // result.payload is strongly typed
+  console.log(result.payload.amount, result.payload.customer_id);
+}
+```
+
+```typescript
+import { WebhookVerificationService, getPlatformsByCategory } from '@hookflo/tern';
+
+// Discover migration-compatible providers in the same category
+const paymentPlatforms = getPlatformsByCategory('payment');
+// ['stripe', 'polar', ...]
+
+const result = await WebhookVerificationService.verifyWithPlatformConfig(
+  request,
+  'stripe',
+  process.env.STRIPE_WEBHOOK_SECRET!,
+  300,
+  {
+    enabled: true,
+    category: 'payment',
+    includeRaw: true,
+  },
+);
+
+console.log(result.payload);
+// {
+//   event: 'payment.succeeded',
+//   amount: 5000,
+//   currency: 'USD',
+//   customer_id: 'cus_123',
+//   transaction_id: 'pi_123',
+//   provider: 'stripe',
+//   category: 'payment',
+//   _raw: {...}
+// }
+```
+
 ### Platform-Specific Usage
 
 ```typescript
@@ -132,6 +214,7 @@ const result = await WebhookVerificationService.verify(request, stripeConfig);
 - **Vercel**: HMAC-SHA256
 - **Polar**: HMAC-SHA256
 - **Supabase**: Token-based authentication
+- **GitLab**: Token-based authentication 
 
 ## Custom Platform Configuration
 
@@ -231,80 +314,59 @@ const timestampedConfig = {
 
 ## Framework Integration
 
-### Express.js
+### Express.js middleware (body-parser safe)
 
 ```typescript
-app.post('/webhooks/stripe', async (req, res) => {
-  const result = await WebhookVerificationService.verifyWithPlatformConfig(
-    req,
-    'stripe',
-    process.env.STRIPE_WEBHOOK_SECRET
-  );
-
-  if (!result.isValid) {
-    return res.status(400).json({ error: result.error });
-  }
-
-  // Process the webhook
-  console.log('Stripe event:', result.payload.type);
-  res.json({ received: true });
-});
+import express from 'express';
+import { createWebhookMiddleware } from '@hookflo/tern/express';
+
+const app = express();
+
+app.post(
+  '/webhooks/stripe',
+  createWebhookMiddleware({
+    platform: 'stripe',
+    secret: process.env.STRIPE_WEBHOOK_SECRET!,
+    normalize: true,
+  }),
+  (req, res) => {
+    const event = (req as any).webhook.payload;
+    res.json({ received: true, event: event.event });
+  },
+);
 ```
 
-### Next.js API Route
+### Next.js App Router
 
 ```typescript
-// pages/api/webhooks/github.js
-export default async function handler(req, res) {
-  if (req.method !== 'POST') {
-    return res.status(405).json({ error: 'Method not allowed' });
-  }
-
-  const result = await WebhookVerificationService.verifyWithPlatformConfig(
-    req,
-    'github',
-    process.env.GITHUB_WEBHOOK_SECRET
-  );
+import { createWebhookHandler } from '@hookflo/tern/nextjs';
 
-  if (!result.isValid) {
-    return res.status(400).json({ error: result.error });
-  }
-
-  // Handle GitHub webhook
-  const event = req.headers['x-github-event'];
-  console.log('GitHub event:', event);
-  
-  res.json({ received: true });
-}
+export const POST = createWebhookHandler({
+  platform: 'github',
+  secret: process.env.GITHUB_WEBHOOK_SECRET!,
+  handler: async (payload) => ({ received: true, event: payload.event ?? payload.type }),
+});
 ```
 
 ### Cloudflare Workers
 
 ```typescript
-addEventListener('fetch', event => {
-  event.respondWith(handleRequest(event.request));
+import { createWebhookHandler } from '@hookflo/tern/cloudflare';
+
+const handleStripe = createWebhookHandler({
+  platform: 'stripe',
+  secretEnv: 'STRIPE_WEBHOOK_SECRET',
+  handler: async (payload) => ({ received: true, event: payload.event ?? payload.type }),
 });
 
-async function handleRequest(request) {
-  if (request.url.includes('/webhooks/clerk')) {
-    const result = await WebhookVerificationService.verifyWithPlatformConfig(
-      request,
-      'clerk',
-      CLERK_WEBHOOK_SECRET
-    );
-
-    if (!result.isValid) {
-      return new Response(JSON.stringify({ error: result.error }), {
-        status: 400,
-        headers: { 'Content-Type': 'application/json' }
-      });
+export default {
+  async fetch(request: Request, env: Record<string, string>) {
+    if (new URL(request.url).pathname === '/webhooks/stripe') {
+      return handleStripe(request, env);
     }
-
-    // Process Clerk webhook
-    console.log('Clerk event:', result.payload.type);
-    return new Response(JSON.stringify({ received: true }));
-  }
-}
+    return new Response('Not Found', { status: 404 });
+  },
+};
 ```
 
 ## API Reference
@@ -315,14 +377,22 @@ async function handleRequest(request) {
 
 Verifies a webhook using the provided configuration.
 
-#### `verifyWithPlatformConfig(request: Request, platform: WebhookPlatform, secret: string, toleranceInSeconds?: number): Promise<WebhookVerificationResult>`
+#### `verifyWithPlatformConfig(request: Request, platform: WebhookPlatform, secret: string, toleranceInSeconds?: number, normalize?: boolean | NormalizeOptions): Promise<WebhookVerificationResult>`
+
+Simplified verification using platform-specific configurations with optional payload normalization.
+
+#### `verifyAny(request: Request, secrets: Record<string, string>, toleranceInSeconds?: number, normalize?: boolean | NormalizeOptions): Promise<WebhookVerificationResult>`
 
-Simplified verification using platform-specific configurations.
+Auto-detects platform from headers and verifies against one or more provider secrets.
 
 #### `verifyTokenBased(request: Request, webhookId: string, webhookToken: string): Promise<WebhookVerificationResult>`
 
 Verifies token-based webhooks (like Supabase).
 
+#### `getPlatformsByCategory(category: 'payment' | 'auth' | 'ecommerce' | 'infrastructure'): WebhookPlatform[]`
+
+Returns built-in providers that normalize into a shared schema for the given migration category.
+
 ### Types
 
 #### `WebhookVerificationResult`
@@ -331,6 +401,7 @@ Verifies token-based webhooks (like Supabase).
 interface WebhookVerificationResult {
   isValid: boolean;
   error?: string;
+  errorCode?: WebhookErrorCode;
   platform: WebhookPlatform;
   payload?: any;
   metadata?: {
@@ -349,6 +420,7 @@ interface WebhookConfig {
   secret: string;
   toleranceInSeconds?: number;
   signatureConfig?: SignatureConfig;
+  normalize?: boolean | NormalizeOptions;
 }
 ```
 
@@ -422,4 +494,55 @@ MIT License - see [LICENSE](./LICENSE) for details.
 
 - [Documentation](./USAGE.md)
 - [Framework Summary](./FRAMEWORK_SUMMARY.md)
+- [Architecture Guide](./ARCHITECTURE.md)
 - [Issues](https://github.com/Hookflo/tern/issues)
+
+
+## Troubleshooting
+
+### `Module not found: Can't resolve "@hookflo/tern/nextjs"`
+
+If this happens in a Next.js project, it usually means one of these:
+
+1. You installed an older published package version that does not include subpath exports yet.
+2. Lockfile still points to an old tarball/version.
+3. `node_modules` cache is stale after upgrading.
+
+Fix steps:
+
+```bash
+# in your Next.js app
+npm i @hookflo/tern@latest
+rm -rf node_modules package-lock.json .next
+npm i
+```
+
+Then verify resolution:
+
+```bash
+node -e "console.log(require.resolve('@hookflo/tern/nextjs'))"
+```
+
+If you are testing this repo locally before publish:
+
+```bash
+# inside /workspace/tern
+npm run build
+npm pack
+
+# inside your other project
+npm i /path/to/hookflo-tern-<version>.tgz
+```
+
+Minimal Next.js App Router usage:
+
+```ts
+import { createWebhookHandler } from '@hookflo/tern/nextjs';
+
+export const POST = createWebhookHandler({
+  platform: 'stripe',
+  secret: process.env.STRIPE_WEBHOOK_SECRET!,
+  handler: async (payload) => ({ received: true, event: payload.event ?? payload.type }),
+});
+```
+

package/dist/adapters/cloudflare.d.ts

@@ -0,0 +1,11 @@
+import { WebhookPlatform, NormalizeOptions } from '../types';
+export interface CloudflareWebhookHandlerOptions<TEnv = Record<string, unknown>, TResponse = unknown> {
+    platform: WebhookPlatform;
+    secret?: string;
+    secretEnv?: string;
+    toleranceInSeconds?: number;
+    normalize?: boolean | NormalizeOptions;
+    onError?: (error: Error) => void;
+    handler: (payload: any, env: TEnv, metadata: Record<string, any>) => Promise<TResponse> | TResponse;
+}
+export declare function createWebhookHandler<TEnv = Record<string, unknown>, TResponse = unknown>(options: CloudflareWebhookHandlerOptions<TEnv, TResponse>): (request: Request, env: TEnv) => Promise<Response>;

package/dist/adapters/cloudflare.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWebhookHandler = createWebhookHandler;
+const index_1 = require("../index");
+function createWebhookHandler(options) {
+    return async (request, env) => {
+        try {
+            const secret = options.secret
+                || (options.secretEnv ? env[options.secretEnv] : undefined);
+            if (!secret) {
+                return Response.json({ error: 'Webhook secret is not configured' }, { status: 500 });
+            }
+            const result = await index_1.WebhookVerificationService.verifyWithPlatformConfig(request, options.platform, secret, options.toleranceInSeconds, options.normalize);
+            if (!result.isValid) {
+                return Response.json({ error: result.error, platform: result.platform }, { status: 400 });
+            }
+            const data = await options.handler(result.payload, env, result.metadata || {});
+            return Response.json(data);
+        }
+        catch (error) {
+            options.onError?.(error);
+            return Response.json({ error: error.message }, { status: 500 });
+        }
+    };
+}

package/dist/adapters/express.d.ts

@@ -0,0 +1,18 @@
+import { WebhookPlatform, WebhookVerificationResult, NormalizeOptions } from '../types';
+import { MinimalNodeRequest } from './shared';
+export interface ExpressLikeResponse {
+    status: (code: number) => ExpressLikeResponse;
+    json: (payload: unknown) => unknown;
+}
+export interface ExpressLikeRequest extends MinimalNodeRequest {
+    webhook?: WebhookVerificationResult;
+}
+export type ExpressLikeNext = () => void;
+export interface ExpressWebhookMiddlewareOptions {
+    platform: WebhookPlatform;
+    secret: string;
+    toleranceInSeconds?: number;
+    normalize?: boolean | NormalizeOptions;
+    onError?: (error: Error) => void;
+}
+export declare function createWebhookMiddleware(options: ExpressWebhookMiddlewareOptions): (req: ExpressLikeRequest, res: ExpressLikeResponse, next: ExpressLikeNext) => Promise<void>;

package/dist/adapters/express.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWebhookMiddleware = createWebhookMiddleware;
+const index_1 = require("../index");
+const shared_1 = require("./shared");
+function createWebhookMiddleware(options) {
+    return async (req, res, next) => {
+        try {
+            const webRequest = await (0, shared_1.toWebRequest)(req);
+            const result = await index_1.WebhookVerificationService.verifyWithPlatformConfig(webRequest, options.platform, options.secret, options.toleranceInSeconds, options.normalize);
+            if (!result.isValid) {
+                res.status(400).json({ error: result.error, platform: result.platform });
+                return;
+            }
+            req.webhook = result;
+            next();
+        }
+        catch (error) {
+            options.onError?.(error);
+            res.status(500).json({ error: error.message });
+        }
+    };
+}

package/dist/adapters/index.d.ts

@@ -0,0 +1,4 @@
+export { createWebhookMiddleware, ExpressWebhookMiddlewareOptions, ExpressLikeRequest, ExpressLikeResponse, } from './express';
+export { createWebhookHandler as createNextjsWebhookHandler, NextWebhookHandlerOptions, } from './nextjs';
+export { createWebhookHandler as createCloudflareWebhookHandler, CloudflareWebhookHandlerOptions, } from './cloudflare';
+export { toWebRequest, extractRawBody } from './shared';

package/dist/adapters/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractRawBody = exports.toWebRequest = exports.createCloudflareWebhookHandler = exports.createNextjsWebhookHandler = exports.createWebhookMiddleware = void 0;
+var express_1 = require("./express");
+Object.defineProperty(exports, "createWebhookMiddleware", { enumerable: true, get: function () { return express_1.createWebhookMiddleware; } });
+var nextjs_1 = require("./nextjs");
+Object.defineProperty(exports, "createNextjsWebhookHandler", { enumerable: true, get: function () { return nextjs_1.createWebhookHandler; } });
+var cloudflare_1 = require("./cloudflare");
+Object.defineProperty(exports, "createCloudflareWebhookHandler", { enumerable: true, get: function () { return cloudflare_1.createWebhookHandler; } });
+var shared_1 = require("./shared");
+Object.defineProperty(exports, "toWebRequest", { enumerable: true, get: function () { return shared_1.toWebRequest; } });
+Object.defineProperty(exports, "extractRawBody", { enumerable: true, get: function () { return shared_1.extractRawBody; } });

package/dist/adapters/nextjs.d.ts

@@ -0,0 +1,10 @@
+import { WebhookPlatform, NormalizeOptions } from '../types';
+export interface NextWebhookHandlerOptions<TResponse = unknown> {
+    platform: WebhookPlatform;
+    secret: string;
+    toleranceInSeconds?: number;
+    normalize?: boolean | NormalizeOptions;
+    onError?: (error: Error) => void;
+    handler: (payload: any, metadata: Record<string, any>) => Promise<TResponse> | TResponse;
+}
+export declare function createWebhookHandler<TResponse = unknown>(options: NextWebhookHandlerOptions<TResponse>): (request: Request) => Promise<Response>;

package/dist/adapters/nextjs.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWebhookHandler = createWebhookHandler;
+const index_1 = require("../index");
+function createWebhookHandler(options) {
+    return async (request) => {
+        try {
+            const result = await index_1.WebhookVerificationService.verifyWithPlatformConfig(request, options.platform, options.secret, options.toleranceInSeconds, options.normalize);
+            if (!result.isValid) {
+                return Response.json({ error: result.error, platform: result.platform }, { status: 400 });
+            }
+            const data = await options.handler(result.payload, result.metadata || {});
+            return Response.json(data);
+        }
+        catch (error) {
+            options.onError?.(error);
+            return Response.json({ error: error.message }, { status: 500 });
+        }
+    };
+}

package/dist/adapters/shared.d.ts

@@ -0,0 +1,13 @@
+export interface MinimalNodeRequest {
+    method?: string;
+    headers: Record<string, string | string[] | undefined>;
+    body?: unknown;
+    protocol?: string;
+    get?: (name: string) => string | undefined;
+    originalUrl?: string;
+    url?: string;
+    on?: (event: string, cb: (chunk?: any) => void) => void;
+}
+export declare function extractRawBody(request: MinimalNodeRequest): Promise<string>;
+export declare function toHeadersInit(headers: Record<string, string | string[] | undefined>): HeadersInit;
+export declare function toWebRequest(request: MinimalNodeRequest): Promise<Request>;

package/dist/adapters/shared.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractRawBody = extractRawBody;
+exports.toHeadersInit = toHeadersInit;
+exports.toWebRequest = toWebRequest;
+function getHeaderValue(headers, name) {
+    const value = headers[name.toLowerCase()] ?? headers[name];
+    if (Array.isArray(value)) {
+        return value.join(',');
+    }
+    return value;
+}
+async function readIncomingMessageBody(request) {
+    if (!request.on) {
+        return '';
+    }
+    const chunks = [];
+    return new Promise((resolve, reject) => {
+        request.on?.('data', (chunk) => {
+            if (typeof chunk === 'string') {
+                chunks.push(chunk);
+                return;
+            }
+            chunks.push(Buffer.from(chunk ?? '').toString('utf8'));
+        });
+        request.on?.('end', () => resolve(chunks.join('')));
+        request.on?.('error', reject);
+    });
+}
+async function extractRawBody(request) {
+    const body = request.body;
+    if (typeof body === 'string') {
+        return body;
+    }
+    if (Buffer.isBuffer(body)) {
+        return body.toString('utf8');
+    }
+    if (body && typeof body === 'object') {
+        return JSON.stringify(body);
+    }
+    return readIncomingMessageBody(request);
+}
+function toHeadersInit(headers) {
+    const normalized = new Headers();
+    for (const [key, value] of Object.entries(headers)) {
+        if (!value) {
+            continue;
+        }
+        if (Array.isArray(value)) {
+            normalized.set(key, value.join(','));
+            continue;
+        }
+        normalized.set(key, value);
+    }
+    return normalized;
+}
+async function toWebRequest(request) {
+    const protocol = request.protocol || 'https';
+    const host = request.get?.('host') || getHeaderValue(request.headers, 'host') || 'localhost';
+    const path = request.originalUrl || request.url || '/';
+    const rawBody = await extractRawBody(request);
+    return new Request(`${protocol}://${host}${path}`, {
+        method: request.method || 'POST',
+        headers: toHeadersInit(request.headers),
+        body: rawBody,
+    });
+}

package/dist/cloudflare.d.ts

@@ -0,0 +1,2 @@
+export { createWebhookHandler } from './adapters/cloudflare';
+export type { CloudflareWebhookHandlerOptions } from './adapters/cloudflare';

package/dist/cloudflare.js

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

package/dist/express.d.ts

@@ -0,0 +1,2 @@
+export { createWebhookMiddleware } from './adapters/express';
+export type { ExpressWebhookMiddlewareOptions, ExpressLikeRequest, ExpressLikeResponse, } from './adapters/express';

package/dist/express.js

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

package/dist/index.d.ts

@@ -1,17 +1,21 @@
-import { WebhookConfig, WebhookVerificationResult, WebhookPlatform, SignatureConfig } from './types';
+import { WebhookConfig, WebhookVerificationResult, WebhookPlatform, SignatureConfig, MultiPlatformSecrets, NormalizeOptions } from './types';
 export declare class WebhookVerificationService {
-    static verify(request: Request, config: WebhookConfig): Promise<WebhookVerificationResult>;
+    static verify<TPayload = unknown>(request: Request, config: WebhookConfig): Promise<WebhookVerificationResult<TPayload>>;
     private static getVerifier;
     private static createAlgorithmBasedVerifier;
     private static getLegacyVerifier;
-    static verifyWithPlatformConfig(request: Request, platform: WebhookPlatform, secret: string, toleranceInSeconds?: number): Promise<WebhookVerificationResult>;
+    static verifyWithPlatformConfig<TPayload = unknown>(request: Request, platform: WebhookPlatform, secret: string, toleranceInSeconds?: number, normalize?: boolean | NormalizeOptions): Promise<WebhookVerificationResult<TPayload>>;
+    static verifyAny<TPayload = unknown>(request: Request, secrets: MultiPlatformSecrets, toleranceInSeconds?: number, normalize?: boolean | NormalizeOptions): Promise<WebhookVerificationResult<TPayload>>;
+    static detectPlatform(request: Request): WebhookPlatform;
     static getPlatformsUsingAlgorithm(algorithm: string): WebhookPlatform[];
     static platformUsesAlgorithm(platform: WebhookPlatform, algorithm: string): boolean;
     static validateSignatureConfig(config: SignatureConfig): boolean;
-    static verifyTokenBased(request: Request, webhookId: string, webhookToken: string): Promise<WebhookVerificationResult>;
+    static verifyTokenBased<TPayload = unknown>(request: Request, webhookId: string, webhookToken: string): Promise<WebhookVerificationResult<TPayload>>;
 }
 export * from './types';
 export { getPlatformAlgorithmConfig, platformUsesAlgorithm, getPlatformsUsingAlgorithm, validateSignatureConfig, } from './platforms/algorithms';
 export { createAlgorithmVerifier } from './verifiers/algorithms';
 export { createCustomVerifier } from './verifiers/custom-algorithms';
+export { normalizePayload, getPlatformNormalizationCategory, getPlatformsByCategory, } from './normalization/simple';
+export * from './adapters';
 export default WebhookVerificationService;