@gravito/echo 3.0.1 → 3.1.1

package/dist/echo/src/observability/tracing/Tracer.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Represents a single unit of work in a trace.
+ * Compatible with OpenTelemetry Span interface to allow seamless integration.
+ */
+export interface Span {
+    /**
+     * Sets a single attribute on the span.
+     * Attributes provide additional metadata for the operation.
+     */
+    setAttribute(key: string, value: string | number | boolean): this;
+    /**
+     * Sets multiple attributes on the span at once.
+     */
+    setAttributes(attributes: Record<string, string | number | boolean>): this;
+    /**
+     * Records a specific event that occurred during the span's lifetime.
+     */
+    addEvent(name: string, attributes?: Record<string, string | number>): this;
+    /**
+     * Sets the final status of the span.
+     */
+    setStatus(status: {
+        code: SpanStatusCode;
+        message?: string;
+    }): this;
+    /**
+     * Marks the end of the span, making it ready for export.
+     */
+    end(): void;
+}
+/**
+ * Standard status codes for a {@link Span}.
+ */
+export declare enum SpanStatusCode {
+    /** Default status. */
+    UNSET = 0,
+    /** Operation completed successfully. */
+    OK = 1,
+    /** Operation failed. */
+    ERROR = 2
+}
+/**
+ * Defines the tracing interface for the Echo module.
+ * Used to track the lifecycle of webhook requests and deliveries.
+ *
+ * @example
+ * ```typescript
+ * const tracer: Tracer = getTracer();
+ * await tracer.withSpan('process-webhook', async (span) => {
+ *   span.setAttribute('provider', 'stripe');
+ *   // ... logic
+ * });
+ * ```
+ */
+export interface Tracer {
+    /**
+     * Starts a new span without making it active.
+     * The caller is responsible for ending the span.
+     */
+    startSpan(name: string, options?: SpanOptions): Span;
+    /**
+     * Executes a function within the context of a new span.
+     * Automatically ends the span when the function completes.
+     */
+    withSpan<T>(name: string, fn: (span: Span) => T | Promise<T>): Promise<T>;
+}
+/**
+ * Configuration options for starting a new {@link Span}.
+ */
+export interface SpanOptions {
+    /** The relationship between the span and its neighbors. */
+    kind?: 'client' | 'server' | 'producer' | 'consumer' | 'internal';
+    /** Initial attributes to set on the span. */
+    attributes?: Record<string, string | number | boolean>;
+}

package/dist/echo/src/observability/tracing/index.d.ts

@@ -0,0 +1,2 @@
+export * from './NoopTracer';
+export * from './Tracer';

package/dist/echo/src/providers/GenericProvider.d.ts

@@ -1,34 +1,53 @@
 /**
- * @fileoverview Generic webhook provider
- *
- * Simple HMAC-SHA256 signature verification.
- *
+ * Generic webhook provider.
  * @module @gravito/echo/providers
  */
-import type { WebhookProvider, WebhookVerificationResult } from '../types';
+import type { WebhookVerificationResult } from '../types';
+import { BaseProvider, type ProviderOptions } from './base/BaseProvider';
+/**
+ * Configuration options for the generic provider.
+ */
+export interface GenericProviderOptions extends ProviderOptions {
+    /**
+     * Custom header name for the signature.
+     * @defaultValue 'x-webhook-signature'
+     */
+    signatureHeader?: string;
+    /**
+     * Custom header name for the timestamp.
+     * @defaultValue 'x-webhook-timestamp'
+     */
+    timestampHeader?: string;
+}
 /**
- * Generic webhook provider using HMAC-SHA256
+ * Generic webhook provider using HMAC-SHA256 for signature verification.
  *
  * Expected headers:
- * - X-Webhook-Signature: HMAC-SHA256 hex signature
- * - X-Webhook-Timestamp: Unix timestamp (optional)
+ * - X-Webhook-Signature: HMAC-SHA256 hex signature.
+ * - X-Webhook-Timestamp: Unix timestamp (optional, used for replay protection).
  *
  * @example
  * ```typescript
- * const provider = new GenericProvider()
- * const result = await provider.verify(body, headers, secret)
+ * const provider = new GenericProvider({
+ *   signatureHeader: 'X-Custom-Sig',
+ *   tolerance: 600
+ * });
+ * const result = await provider.verify(body, headers, secret);
  * ```
  */
-export declare class GenericProvider implements WebhookProvider {
+export declare class GenericProvider extends BaseProvider {
     readonly name = "generic";
     private signatureHeader;
     private timestampHeader;
-    private tolerance;
-    constructor(options?: {
-        signatureHeader?: string;
-        timestampHeader?: string;
-        tolerance?: number;
-    });
+    constructor(options?: GenericProviderOptions);
+    /**
+     * Verifies the webhook using HMAC-SHA256.
+     *
+     * @param payload - Raw request body.
+     * @param headers - Request headers.
+     * @param secret - Secret key for HMAC computation.
+     * @returns Verification result.
+     * @throws Error if signature computation fails.
+     */
     verify(payload: string | Buffer, headers: Record<string, string | string[] | undefined>, secret: string): Promise<WebhookVerificationResult>;
-    private getHeader;
 }

package/dist/echo/src/providers/GitHubProvider.d.ts

@@ -1,26 +1,35 @@
 /**
- * @fileoverview GitHub webhook provider
- *
- * Implements GitHub's webhook signature verification.
- * @see https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries
- *
+ * GitHub webhook provider.
  * @module @gravito/echo/providers
  */
-import type { WebhookProvider, WebhookVerificationResult } from '../types';
+import type { WebhookVerificationResult } from '../types';
+import { BaseProvider } from './base/BaseProvider';
 /**
- * GitHub webhook provider
+ * GitHub webhook provider.
  *
- * Verifies GitHub webhook signatures using the X-Hub-Signature-256 header.
+ * Verifies GitHub webhook signatures using the `X-Hub-Signature-256` header.
+ * @see {@link https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries | GitHub Webhook Validation}
  *
  * @example
  * ```typescript
- * const provider = new GitHubProvider()
- * const result = await provider.verify(body, headers, process.env.GITHUB_WEBHOOK_SECRET)
+ * const provider = new GitHubProvider();
+ * const result = await provider.verify(body, headers, process.env.GITHUB_WEBHOOK_SECRET);
  * ```
  */
-export declare class GitHubProvider implements WebhookProvider {
+export declare class GitHubProvider extends BaseProvider {
     readonly name = "github";
+    /**
+     * Verifies the GitHub webhook signature.
+     *
+     * @param payload - Raw request body.
+     * @param headers - Request headers.
+     * @param secret - GitHub webhook secret.
+     * @returns Verification result.
+     * @throws Error if signature computation fails.
+     */
     verify(payload: string | Buffer, headers: Record<string, string | string[] | undefined>, secret: string): Promise<WebhookVerificationResult>;
+    /**
+     * Extracts the action from the GitHub payload if available.
+     */
     parseEventType(payload: unknown): string | undefined;
-    private getHeader;
 }

package/dist/echo/src/providers/LinearProvider.d.ts

@@ -0,0 +1,27 @@
+import type { WebhookVerificationResult } from '../types';
+import { BaseProvider } from './base/BaseProvider';
+/**
+ * Linear webhook provider.
+ *
+ * Verifies Linear webhook signatures using the `Linear-Signature` header.
+ * @see {@link https://developers.linear.app/docs/graphql/webhooks#signature-verification | Linear Webhook Verification}
+ *
+ * @example
+ * ```typescript
+ * const provider = new LinearProvider();
+ * const result = await provider.verify(body, headers, process.env.LINEAR_WEBHOOK_SECRET);
+ * ```
+ */
+export declare class LinearProvider extends BaseProvider {
+    readonly name = "linear";
+    /**
+     * Verifies the Linear webhook signature.
+     *
+     * @param payload - Raw request body.
+     * @param headers - Request headers.
+     * @param secret - Linear webhook secret.
+     * @returns Verification result.
+     * @throws Error if signature computation fails.
+     */
+    verify(payload: string | Buffer, headers: Record<string, string | string[] | undefined>, secret: string): Promise<WebhookVerificationResult>;
+}

package/dist/echo/src/providers/PaddleProvider.d.ts

@@ -0,0 +1,31 @@
+import type { WebhookVerificationResult } from '../types';
+import { BaseProvider } from './base/BaseProvider';
+/**
+ * Paddle webhook provider.
+ *
+ * Verifies Paddle webhook signatures using the `Paddle-Signature` header.
+ * @see {@link https://developer.paddle.com/webhooks/signature-verification | Paddle Signature Verification}
+ *
+ * @example
+ * ```typescript
+ * const provider = new PaddleProvider();
+ * const result = await provider.verify(body, headers, process.env.PADDLE_WEBHOOK_SECRET);
+ * ```
+ */
+export declare class PaddleProvider extends BaseProvider {
+    readonly name = "paddle";
+    /**
+     * Verifies the Paddle webhook signature.
+     *
+     * @param payload - Raw request body.
+     * @param headers - Request headers.
+     * @param secret - Paddle webhook secret.
+     * @returns Verification result.
+     * @throws Error if signature computation fails.
+     */
+    verify(payload: string | Buffer, headers: Record<string, string | string[] | undefined>, secret: string): Promise<WebhookVerificationResult>;
+    /**
+     * Parses the Paddle-Signature header into timestamp and signature components.
+     */
+    private parsePaddleSignature;
+}

package/dist/echo/src/providers/ShopifyProvider.d.ts

@@ -0,0 +1,27 @@
+import type { WebhookVerificationResult } from '../types';
+import { BaseProvider } from './base/BaseProvider';
+/**
+ * Shopify webhook provider.
+ *
+ * Verifies Shopify webhook signatures using the `X-Shopify-Hmac-Sha256` header.
+ * @see {@link https://shopify.dev/docs/apps/webhooks/configuration/https#verify-webhook | Shopify Webhook Verification}
+ *
+ * @example
+ * ```typescript
+ * const provider = new ShopifyProvider();
+ * const result = await provider.verify(body, headers, process.env.SHOPIFY_WEBHOOK_SECRET);
+ * ```
+ */
+export declare class ShopifyProvider extends BaseProvider {
+    readonly name = "shopify";
+    /**
+     * Verifies the Shopify webhook signature.
+     *
+     * @param payload - Raw request body.
+     * @param headers - Request headers.
+     * @param secret - Shopify webhook secret.
+     * @returns Verification result.
+     * @throws Error if signature computation fails.
+     */
+    verify(payload: string | Buffer, headers: Record<string, string | string[] | undefined>, secret: string): Promise<WebhookVerificationResult>;
+}

package/dist/echo/src/providers/SlackProvider.d.ts

@@ -0,0 +1,27 @@
+import type { WebhookVerificationResult } from '../types';
+import { BaseProvider } from './base/BaseProvider';
+/**
+ * Slack webhook provider.
+ *
+ * Verifies Slack webhook signatures using the `X-Slack-Signature` and `X-Slack-Request-Timestamp` headers.
+ * @see {@link https://api.slack.com/authentication/verifying-requests-from-slack | Slack Request Verification}
+ *
+ * @example
+ * ```typescript
+ * const provider = new SlackProvider();
+ * const result = await provider.verify(body, headers, process.env.SLACK_SIGNING_SECRET);
+ * ```
+ */
+export declare class SlackProvider extends BaseProvider {
+    readonly name = "slack";
+    /**
+     * Verifies the Slack webhook signature.
+     *
+     * @param payload - Raw request body.
+     * @param headers - Request headers.
+     * @param secret - Slack signing secret.
+     * @returns Verification result.
+     * @throws Error if signature computation fails.
+     */
+    verify(payload: string | Buffer, headers: Record<string, string | string[] | undefined>, secret: string): Promise<WebhookVerificationResult>;
+}

package/dist/echo/src/providers/StripeProvider.d.ts

@@ -1,30 +1,38 @@
 /**
- * @fileoverview Stripe webhook provider
- *
- * Implements Stripe's webhook signature verification.
- * @see https://stripe.com/docs/webhooks/signatures
- *
+ * Stripe webhook provider.
  * @module @gravito/echo/providers
  */
-import type { WebhookProvider, WebhookVerificationResult } from '../types';
+import type { WebhookVerificationResult } from '../types';
+import { BaseProvider } from './base/BaseProvider';
 /**
- * Stripe webhook provider
+ * Stripe webhook provider.
  *
  * Verifies Stripe webhook signatures using their standard format.
+ * @see {@link https://stripe.com/docs/webhooks/signatures | Stripe Webhook Signatures}
  *
  * @example
  * ```typescript
- * const provider = new StripeProvider()
- * const result = await provider.verify(body, headers, process.env.STRIPE_WEBHOOK_SECRET)
+ * const provider = new StripeProvider();
+ * const result = await provider.verify(body, headers, process.env.STRIPE_WEBHOOK_SECRET);
  * ```
  */
-export declare class StripeProvider implements WebhookProvider {
+export declare class StripeProvider extends BaseProvider {
     readonly name = "stripe";
-    private tolerance;
     constructor(options?: {
         tolerance?: number;
     });
+    /**
+     * Verifies the Stripe webhook signature.
+     *
+     * @param payload - Raw request body.
+     * @param headers - Request headers.
+     * @param secret - Stripe webhook secret (signing secret).
+     * @returns Verification result.
+     * @throws Error if signature computation fails.
+     */
     verify(payload: string | Buffer, headers: Record<string, string | string[] | undefined>, secret: string): Promise<WebhookVerificationResult>;
+    /**
+     * Extracts the event type from the Stripe payload.
+     */
     parseEventType(payload: unknown): string | undefined;
-    private getHeader;
 }

package/dist/echo/src/providers/TwilioProvider.d.ts

@@ -0,0 +1,31 @@
+import type { WebhookVerificationResult } from '../types';
+import { BaseProvider, type ProviderOptions } from './base/BaseProvider';
+/**
+ * Twilio webhook provider.
+ *
+ * Verifies Twilio webhook signatures using the `X-Twilio-Signature` header.
+ * @see {@link https://www.twilio.com/docs/usage/security#validating-requests | Twilio Request Validation}
+ *
+ * @example
+ * ```typescript
+ * const provider = new TwilioProvider({ baseUrl: 'https://api.example.com/webhooks/twilio' });
+ * const result = await provider.verify(body, headers, process.env.TWILIO_AUTH_TOKEN);
+ * ```
+ */
+export declare class TwilioProvider extends BaseProvider {
+    readonly name = "twilio";
+    private baseUrl?;
+    constructor(options?: ProviderOptions & {
+        baseUrl?: string;
+    });
+    /**
+     * Verifies the Twilio webhook signature.
+     *
+     * @param payload - Raw request body (URL-encoded).
+     * @param headers - Request headers.
+     * @param secret - Twilio Auth Token.
+     * @returns Verification result.
+     * @throws Error if signature computation fails.
+     */
+    verify(payload: string | Buffer, headers: Record<string, string | string[] | undefined>, secret: string): Promise<WebhookVerificationResult>;
+}

package/dist/echo/src/providers/base/BaseProvider.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Abstract base class for webhook providers.
+ * @module @gravito/echo/providers/base
+ */
+import type { WebhookProvider, WebhookVerificationResult } from '../../types';
+/**
+ * Configuration options for webhook providers.
+ */
+export interface ProviderOptions {
+    /**
+     * Maximum allowed age of the webhook request in seconds to prevent replay attacks.
+     * @defaultValue 300
+     */
+    tolerance?: number;
+}
+/**
+ * Base implementation for all webhook providers.
+ * Handles common header extraction, payload conversion, and result formatting.
+ *
+ * @example
+ * ```typescript
+ * class MyProvider extends BaseProvider {
+ *   readonly name = 'my-provider';
+ *   async verify(payload, headers, secret) {
+ *     // Implementation logic
+ *     return this.createSuccess(JSON.parse(payload));
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class BaseProvider implements WebhookProvider {
+    /** Unique identifier for the provider. */
+    abstract readonly name: string;
+    /** Time tolerance for timestamp validation. */
+    protected tolerance: number;
+    constructor(options?: ProviderOptions);
+    /**
+     * Verifies the authenticity of a webhook request.
+     *
+     * @param payload - Raw request body.
+     * @param headers - Request headers.
+     * @param secret - Provider-specific secret key.
+     * @returns Verification result containing the parsed payload or error message.
+     * @throws Error if verification logic encounters an unrecoverable failure.
+     */
+    abstract verify(payload: string | Buffer, headers: Record<string, string | string[] | undefined>, secret: string): Promise<WebhookVerificationResult>;
+    /**
+     * Extracts the event type from the verified payload.
+     *
+     * @param payload - The parsed webhook payload.
+     * @returns The event type string if found.
+     */
+    parseEventType?(payload: unknown): string | undefined;
+    /**
+     * Retrieves a header value in a case-insensitive manner.
+     */
+    protected getHeader(headers: Record<string, string | string[] | undefined>, name: string): string | undefined;
+    /**
+     * Checks if a specific header exists.
+     */
+    protected hasHeader(headers: Record<string, string | string[] | undefined>, name: string): boolean;
+    /**
+     * Creates a failed verification result.
+     */
+    protected createFailure(error: string): WebhookVerificationResult;
+    /**
+     * Creates a successful verification result.
+     */
+    protected createSuccess(payload: unknown, options?: {
+        eventType?: string;
+        webhookId?: string;
+    }): WebhookVerificationResult;
+    /**
+     * Ensures the payload is a string.
+     */
+    protected payloadToString(payload: string | Buffer): string;
+    /**
+     * Safely parses a JSON string without throwing.
+     */
+    protected safeParseJson(str: string): {
+        success: true;
+        data: unknown;
+    } | {
+        success: false;
+        error: string;
+    };
+}

package/dist/echo/src/providers/base/HeaderUtils.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Utilities for handling webhook headers.
+ * @module @gravito/echo/providers/base
+ */
+/**
+ * Retrieves a header value from a headers object.
+ * Supports case-insensitive lookup by checking the original name and its lowercase version.
+ *
+ * @param headers - The headers object from the request.
+ * @param name - The name of the header to retrieve.
+ * @returns The first value of the header if found, otherwise undefined.
+ *
+ * @example
+ * ```typescript
+ * const sig = getHeader(headers, 'X-Webhook-Signature');
+ * ```
+ */
+export declare function getHeader(headers: Record<string, string | string[] | undefined>, name: string): string | undefined;
+/**
+ * Retrieves multiple header values at once.
+ *
+ * @param headers - The headers object from the request.
+ * @param names - An array of header names to retrieve.
+ * @returns A record mapping each requested name to its value or undefined.
+ */
+export declare function getHeaders(headers: Record<string, string | string[] | undefined>, names: string[]): Record<string, string | undefined>;
+/**
+ * Checks if a specific header exists in the headers object.
+ *
+ * @param headers - The headers object from the request.
+ * @param name - The name of the header to check.
+ * @returns True if the header exists and is not undefined.
+ */
+export declare function hasHeader(headers: Record<string, string | string[] | undefined>, name: string): boolean;

package/dist/echo/src/providers/index.d.ts

@@ -1,3 +1,14 @@
-export * from './GenericProvider';
-export * from './GitHubProvider';
-export * from './StripeProvider';
+/**
+ * Webhook providers for various services.
+ * @module @gravito/echo/providers
+ */
+export { BaseProvider, type ProviderOptions } from './base/BaseProvider';
+export { getHeader, getHeaders, hasHeader } from './base/HeaderUtils';
+export { GenericProvider } from './GenericProvider';
+export { GitHubProvider } from './GitHubProvider';
+export { LinearProvider } from './LinearProvider';
+export { PaddleProvider } from './PaddleProvider';
+export { ShopifyProvider } from './ShopifyProvider';
+export { SlackProvider } from './SlackProvider';
+export { StripeProvider } from './StripeProvider';
+export { TwilioProvider } from './TwilioProvider';

package/dist/echo/src/receive/SignatureValidator.d.ts

@@ -9,10 +9,43 @@
  * Compute HMAC-SHA256 signature
  */
 export declare function computeHmacSha256(payload: string | Buffer, secret: string): Promise<string>;
+/**
+ * Computes an HMAC-SHA256 signature and returns it as a base64 encoded string.
+ *
+ * Used by providers that require base64 encoding for their signatures (e.g., Shopify).
+ *
+ * @param payload - The raw data to sign.
+ * @param secret - The shared secret key.
+ * @returns The base64 encoded HMAC-SHA256 signature.
+ * @throws Error if the crypto operations fail.
+ *
+ * @example
+ * ```typescript
+ * const sig = await computeHmacSha256Base64('data', 'secret');
+ * ```
+ */
+export declare function computeHmacSha256Base64(payload: string | Buffer, secret: string): Promise<string>;
 /**
  * Compute HMAC-SHA1 signature (for legacy providers)
  */
 export declare function computeHmacSha1(payload: string | Buffer, secret: string): Promise<string>;
+/**
+ * Computes an HMAC-SHA1 signature and returns it as a base64 encoded string.
+ *
+ * Primarily used for legacy services or specific providers like Twilio that
+ * still rely on SHA1-based HMAC for their webhook verification.
+ *
+ * @param payload - The raw data to sign.
+ * @param secret - The shared secret key.
+ * @returns The base64 encoded HMAC-SHA1 signature.
+ * @throws Error if the crypto operations fail.
+ *
+ * @example
+ * ```typescript
+ * const sig = await computeHmacSha1Base64('data', 'secret');
+ * ```
+ */
+export declare function computeHmacSha1Base64(payload: string | Buffer, secret: string): Promise<string>;
 /**
  * Timing-safe string comparison to prevent timing attacks
  */