@feelflow/ffid-sdk 0.1.0 → 0.2.0

package/dist/webhooks/index.d.cts

@@ -0,0 +1,298 @@
+/**
+ * FFID Webhook SDK Constants
+ *
+ * Header names, signature version, and default configuration values.
+ * These must match the server-side constants in src/lib/webhooks/types.ts.
+ */
+/** HTTP header for webhook signature: "t={timestamp},v1={hex_hmac}" */
+declare const FFID_WEBHOOK_SIGNATURE_HEADER = "X-FFID-Signature";
+/** HTTP header for webhook timestamp (Unix seconds) */
+declare const FFID_WEBHOOK_TIMESTAMP_HEADER = "X-FFID-Timestamp";
+/** HTTP header for webhook event ID (UUID) */
+declare const FFID_WEBHOOK_EVENT_ID_HEADER = "X-FFID-Event-ID";
+/** Signature algorithm version prefix */
+declare const FFID_WEBHOOK_SIGNATURE_VERSION = "v1";
+/** Default timestamp tolerance in seconds (5 minutes) */
+declare const DEFAULT_TOLERANCE_SECONDS = 300;
+
+/**
+ * FFID Webhook SDK Error Classes
+ *
+ * Structured errors for signature verification failures.
+ */
+/** Base error for all webhook SDK errors */
+declare class FFIDWebhookError extends Error {
+    constructor(message: string);
+}
+/** Thrown when the webhook signature does not match */
+declare class FFIDWebhookSignatureError extends FFIDWebhookError {
+    constructor(message?: string);
+}
+/** Thrown when the webhook timestamp is outside the tolerance window */
+declare class FFIDWebhookTimestampError extends FFIDWebhookError {
+    constructor(message?: string);
+}
+/** Thrown when the webhook payload cannot be parsed as JSON */
+declare class FFIDWebhookPayloadError extends FFIDWebhookError {
+    constructor(message?: string);
+}
+
+/**
+ * FFID Webhook SDK Type Definitions
+ *
+ * Types for receiving and verifying FeelFlow ID webhook events.
+ * Used by external services to handle real-time event notifications.
+ */
+/** All supported webhook event types */
+type FFIDWebhookEventType = 'subscription.created' | 'subscription.updated' | 'subscription.canceled' | 'subscription.trial_ending' | 'subscription.payment_failed' | 'user.created' | 'user.updated' | 'user.deleted' | 'user.deletion_requested' | 'organization.created' | 'organization.updated' | 'organization.member.added' | 'organization.member.removed' | 'organization.member.role_changed' | 'legal.document.updated' | 'legal.agreement.required' | 'system.maintenance.scheduled' | 'system.maintenance.started' | 'system.maintenance.completed' | 'announcement.published' | 'test.ping';
+interface FFIDSubscriptionCreatedPayload {
+    subscriptionId: string;
+    organizationId?: string;
+    plan?: string;
+    status?: string;
+}
+interface FFIDSubscriptionUpdatedPayload {
+    subscriptionId: string;
+    organizationId?: string;
+    plan?: string;
+    previousPlan?: string;
+    status?: string;
+}
+interface FFIDSubscriptionCanceledPayload {
+    subscriptionId: string;
+    organizationId?: string;
+    reason?: string;
+    cancelAt?: string;
+}
+interface FFIDSubscriptionTrialEndingPayload {
+    subscriptionId: string;
+    organizationId?: string;
+    trialEndDate: string;
+}
+interface FFIDSubscriptionPaymentFailedPayload {
+    subscriptionId: string;
+    organizationId?: string;
+    failureReason?: string;
+    attemptCount?: number;
+}
+interface FFIDUserCreatedPayload {
+    userId: string;
+    email?: string;
+    displayName?: string;
+}
+interface FFIDUserUpdatedPayload {
+    userId: string;
+    displayName?: string;
+    updatedFields?: string[];
+}
+interface FFIDUserDeletedPayload {
+    userId: string;
+}
+interface FFIDUserDeletionRequestedPayload {
+    userId: string;
+    requestId?: string;
+    scheduledDeletionDate?: string;
+}
+interface FFIDOrganizationCreatedPayload {
+    organizationId: string;
+    name?: string;
+    slug?: string;
+}
+interface FFIDOrganizationUpdatedPayload {
+    organizationId: string;
+    slug?: string;
+    updatedFields?: string[];
+}
+interface FFIDOrganizationMemberAddedPayload {
+    organizationId: string;
+    userId: string;
+    role?: string;
+}
+interface FFIDOrganizationMemberRemovedPayload {
+    organizationId: string;
+    userId: string;
+}
+interface FFIDOrganizationMemberRoleChangedPayload {
+    organizationId: string;
+    userId: string;
+    previousRole?: string;
+    newRole?: string;
+}
+interface FFIDLegalDocumentUpdatedPayload {
+    documentId: string;
+    documentType?: string;
+    version?: string;
+}
+interface FFIDLegalAgreementRequiredPayload {
+    documentId: string;
+    documentType?: string;
+    documentTitle?: string;
+}
+interface FFIDSystemMaintenancePayload {
+    maintenanceId?: string;
+    scheduledAt?: string;
+    estimatedDuration?: string;
+    description?: string;
+}
+interface FFIDAnnouncementPublishedPayload {
+    announcementId: string;
+    type: string;
+    title: string;
+    content: string;
+    scheduledAt?: string | null;
+    durationMinutes?: number | null;
+    affectedServices?: string[];
+    channels?: string[];
+    publishedAt?: string | null;
+}
+interface FFIDTestPingPayload {
+    message?: string;
+}
+/** Maps event type strings to their typed payloads */
+interface FFIDWebhookEventMap {
+    'subscription.created': FFIDSubscriptionCreatedPayload;
+    'subscription.updated': FFIDSubscriptionUpdatedPayload;
+    'subscription.canceled': FFIDSubscriptionCanceledPayload;
+    'subscription.trial_ending': FFIDSubscriptionTrialEndingPayload;
+    'subscription.payment_failed': FFIDSubscriptionPaymentFailedPayload;
+    'user.created': FFIDUserCreatedPayload;
+    'user.updated': FFIDUserUpdatedPayload;
+    'user.deleted': FFIDUserDeletedPayload;
+    'user.deletion_requested': FFIDUserDeletionRequestedPayload;
+    'organization.created': FFIDOrganizationCreatedPayload;
+    'organization.updated': FFIDOrganizationUpdatedPayload;
+    'organization.member.added': FFIDOrganizationMemberAddedPayload;
+    'organization.member.removed': FFIDOrganizationMemberRemovedPayload;
+    'organization.member.role_changed': FFIDOrganizationMemberRoleChangedPayload;
+    'legal.document.updated': FFIDLegalDocumentUpdatedPayload;
+    'legal.agreement.required': FFIDLegalAgreementRequiredPayload;
+    'system.maintenance.scheduled': FFIDSystemMaintenancePayload;
+    'system.maintenance.started': FFIDSystemMaintenancePayload;
+    'system.maintenance.completed': FFIDSystemMaintenancePayload;
+    'announcement.published': FFIDAnnouncementPublishedPayload;
+    'test.ping': FFIDTestPingPayload;
+}
+/** A webhook event envelope with typed payload */
+interface FFIDWebhookEvent<T extends FFIDWebhookEventType = FFIDWebhookEventType> {
+    id: string;
+    type: T;
+    createdAt: string;
+    data: T extends keyof FFIDWebhookEventMap ? FFIDWebhookEventMap[T] : Record<string, unknown>;
+}
+/** Configuration for the webhook handler */
+interface FFIDWebhookHandlerConfig {
+    /** Webhook endpoint secret used for signature verification */
+    secret: string;
+    /** Maximum age of webhook timestamp in seconds (default: 300) */
+    toleranceSeconds?: number;
+    /** Custom logger */
+    logger?: FFIDWebhookLogger;
+}
+/** Logger interface for webhook SDK */
+interface FFIDWebhookLogger {
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}
+/** Event handler callback type */
+type FFIDWebhookEventHandler<T extends FFIDWebhookEventType = FFIDWebhookEventType> = (event: FFIDWebhookEvent<T>) => void | Promise<void>;
+
+/**
+ * FFID Webhook Signature Verification
+ *
+ * HMAC-SHA256 signature parsing and verification for incoming webhook events.
+ * Compatible with the server-side signing implementation (src/lib/webhooks/signing.ts).
+ *
+ * Signature format: t={timestamp},v1={hex_hmac}
+ * Signed content:   {timestamp}.{body}
+ */
+
+/**
+ * Parse a signature header into timestamp and signature components.
+ *
+ * @param header - Raw signature header value (e.g. "t=1234567890,v1=abcdef...")
+ * @returns Parsed components, or null if the header is malformed
+ */
+declare function parseSignatureHeader(header: string): {
+    timestamp: number;
+    signature: string;
+} | null;
+/**
+ * Compute HMAC-SHA256 for a webhook payload.
+ *
+ * @param secret - Webhook endpoint secret
+ * @param timestamp - Unix timestamp in seconds
+ * @param body - Raw request body string
+ * @returns Hex-encoded HMAC-SHA256 signature
+ */
+declare function computeSignature(secret: string, timestamp: number, body: string): string;
+/**
+ * Verify a webhook signature and timestamp, then parse the event body.
+ *
+ * @param rawBody - Raw request body string
+ * @param signatureHeader - Value of the X-FFID-Signature header
+ * @param secret - Webhook endpoint secret
+ * @param toleranceSeconds - Maximum age of timestamp (default: 300s)
+ * @returns Parsed webhook event
+ * @throws {FFIDWebhookSignatureError} If the header is malformed or signature is invalid
+ * @throws {FFIDWebhookTimestampError} If the timestamp is outside the tolerance window
+ */
+declare function verifyWebhookSignature(rawBody: string, signatureHeader: string, secret: string, toleranceSeconds?: number): FFIDWebhookEvent;
+
+/**
+ * FFID Webhook Handler
+ *
+ * Factory function for creating a webhook event handler with typed event
+ * registration, signature verification, and framework integrations.
+ *
+ * @example
+ * ```typescript
+ * import { createFFIDWebhookHandler } from '@feelflow/ffid-sdk/webhooks'
+ *
+ * const webhooks = createFFIDWebhookHandler({
+ *   secret: process.env.FFID_WEBHOOK_SECRET!,
+ * })
+ *
+ * webhooks.on('subscription.created', (event) => {
+ *   console.log('New subscription:', event.data.subscriptionId)
+ * })
+ *
+ * // Next.js App Router
+ * export const POST = webhooks.nextHandler()
+ * ```
+ */
+
+/**
+ * Creates an FFID webhook event handler.
+ *
+ * @param config - Handler configuration (secret is required)
+ * @returns Webhook handler instance with event registration and framework helpers
+ */
+declare function createFFIDWebhookHandler(config: FFIDWebhookHandlerConfig): {
+    /** Register a handler for a specific event type */
+    on: <T extends FFIDWebhookEventType>(eventType: T, handler: FFIDWebhookEventHandler<T>) => void;
+    /** Register a handler that receives all events */
+    onAll: (handler: FFIDWebhookEventHandler) => void;
+    /** Unregister a handler for a specific event type */
+    off: <T extends FFIDWebhookEventType>(eventType: T, handler: FFIDWebhookEventHandler<T>) => void;
+    /** Verify signature and dispatch event (core method) */
+    handleEvent: (rawBody: string, signatureHeader: string) => Promise<FFIDWebhookEvent>;
+    /** Process webhook from raw body + headers object */
+    handleRaw: (rawBody: string, headers: Record<string, string | undefined>) => Promise<FFIDWebhookEvent>;
+    /** Express/Connect middleware */
+    expressMiddleware: () => (req: {
+        body: unknown;
+        headers: Record<string, string | string[] | undefined>;
+    }, res: {
+        status: (code: number) => {
+            json: (body: unknown) => void;
+        };
+    }, next: () => void) => void;
+    /** Next.js App Router route handler */
+    nextHandler: () => (request: Request) => Promise<Response>;
+};
+/** Type of the FFID Webhook handler */
+type FFIDWebhookHandler = ReturnType<typeof createFFIDWebhookHandler>;
+
+export { DEFAULT_TOLERANCE_SECONDS, type FFIDLegalAgreementRequiredPayload, type FFIDLegalDocumentUpdatedPayload, type FFIDOrganizationCreatedPayload, type FFIDOrganizationMemberAddedPayload, type FFIDOrganizationMemberRemovedPayload, type FFIDOrganizationMemberRoleChangedPayload, type FFIDOrganizationUpdatedPayload, type FFIDSubscriptionCanceledPayload, type FFIDSubscriptionCreatedPayload, type FFIDSubscriptionPaymentFailedPayload, type FFIDSubscriptionTrialEndingPayload, type FFIDSubscriptionUpdatedPayload, type FFIDSystemMaintenancePayload, type FFIDTestPingPayload, type FFIDUserCreatedPayload, type FFIDUserDeletedPayload, type FFIDUserDeletionRequestedPayload, type FFIDUserUpdatedPayload, FFIDWebhookError, type FFIDWebhookEvent, type FFIDWebhookEventHandler, type FFIDWebhookEventMap, type FFIDWebhookEventType, type FFIDWebhookHandler, type FFIDWebhookHandlerConfig, type FFIDWebhookLogger, FFIDWebhookPayloadError, FFIDWebhookSignatureError, FFIDWebhookTimestampError, FFID_WEBHOOK_EVENT_ID_HEADER, FFID_WEBHOOK_SIGNATURE_HEADER, FFID_WEBHOOK_SIGNATURE_VERSION, FFID_WEBHOOK_TIMESTAMP_HEADER, computeSignature, createFFIDWebhookHandler, parseSignatureHeader, verifyWebhookSignature };

package/dist/webhooks/index.d.ts

@@ -0,0 +1,298 @@
+/**
+ * FFID Webhook SDK Constants
+ *
+ * Header names, signature version, and default configuration values.
+ * These must match the server-side constants in src/lib/webhooks/types.ts.
+ */
+/** HTTP header for webhook signature: "t={timestamp},v1={hex_hmac}" */
+declare const FFID_WEBHOOK_SIGNATURE_HEADER = "X-FFID-Signature";
+/** HTTP header for webhook timestamp (Unix seconds) */
+declare const FFID_WEBHOOK_TIMESTAMP_HEADER = "X-FFID-Timestamp";
+/** HTTP header for webhook event ID (UUID) */
+declare const FFID_WEBHOOK_EVENT_ID_HEADER = "X-FFID-Event-ID";
+/** Signature algorithm version prefix */
+declare const FFID_WEBHOOK_SIGNATURE_VERSION = "v1";
+/** Default timestamp tolerance in seconds (5 minutes) */
+declare const DEFAULT_TOLERANCE_SECONDS = 300;
+
+/**
+ * FFID Webhook SDK Error Classes
+ *
+ * Structured errors for signature verification failures.
+ */
+/** Base error for all webhook SDK errors */
+declare class FFIDWebhookError extends Error {
+    constructor(message: string);
+}
+/** Thrown when the webhook signature does not match */
+declare class FFIDWebhookSignatureError extends FFIDWebhookError {
+    constructor(message?: string);
+}
+/** Thrown when the webhook timestamp is outside the tolerance window */
+declare class FFIDWebhookTimestampError extends FFIDWebhookError {
+    constructor(message?: string);
+}
+/** Thrown when the webhook payload cannot be parsed as JSON */
+declare class FFIDWebhookPayloadError extends FFIDWebhookError {
+    constructor(message?: string);
+}
+
+/**
+ * FFID Webhook SDK Type Definitions
+ *
+ * Types for receiving and verifying FeelFlow ID webhook events.
+ * Used by external services to handle real-time event notifications.
+ */
+/** All supported webhook event types */
+type FFIDWebhookEventType = 'subscription.created' | 'subscription.updated' | 'subscription.canceled' | 'subscription.trial_ending' | 'subscription.payment_failed' | 'user.created' | 'user.updated' | 'user.deleted' | 'user.deletion_requested' | 'organization.created' | 'organization.updated' | 'organization.member.added' | 'organization.member.removed' | 'organization.member.role_changed' | 'legal.document.updated' | 'legal.agreement.required' | 'system.maintenance.scheduled' | 'system.maintenance.started' | 'system.maintenance.completed' | 'announcement.published' | 'test.ping';
+interface FFIDSubscriptionCreatedPayload {
+    subscriptionId: string;
+    organizationId?: string;
+    plan?: string;
+    status?: string;
+}
+interface FFIDSubscriptionUpdatedPayload {
+    subscriptionId: string;
+    organizationId?: string;
+    plan?: string;
+    previousPlan?: string;
+    status?: string;
+}
+interface FFIDSubscriptionCanceledPayload {
+    subscriptionId: string;
+    organizationId?: string;
+    reason?: string;
+    cancelAt?: string;
+}
+interface FFIDSubscriptionTrialEndingPayload {
+    subscriptionId: string;
+    organizationId?: string;
+    trialEndDate: string;
+}
+interface FFIDSubscriptionPaymentFailedPayload {
+    subscriptionId: string;
+    organizationId?: string;
+    failureReason?: string;
+    attemptCount?: number;
+}
+interface FFIDUserCreatedPayload {
+    userId: string;
+    email?: string;
+    displayName?: string;
+}
+interface FFIDUserUpdatedPayload {
+    userId: string;
+    displayName?: string;
+    updatedFields?: string[];
+}
+interface FFIDUserDeletedPayload {
+    userId: string;
+}
+interface FFIDUserDeletionRequestedPayload {
+    userId: string;
+    requestId?: string;
+    scheduledDeletionDate?: string;
+}
+interface FFIDOrganizationCreatedPayload {
+    organizationId: string;
+    name?: string;
+    slug?: string;
+}
+interface FFIDOrganizationUpdatedPayload {
+    organizationId: string;
+    slug?: string;
+    updatedFields?: string[];
+}
+interface FFIDOrganizationMemberAddedPayload {
+    organizationId: string;
+    userId: string;
+    role?: string;
+}
+interface FFIDOrganizationMemberRemovedPayload {
+    organizationId: string;
+    userId: string;
+}
+interface FFIDOrganizationMemberRoleChangedPayload {
+    organizationId: string;
+    userId: string;
+    previousRole?: string;
+    newRole?: string;
+}
+interface FFIDLegalDocumentUpdatedPayload {
+    documentId: string;
+    documentType?: string;
+    version?: string;
+}
+interface FFIDLegalAgreementRequiredPayload {
+    documentId: string;
+    documentType?: string;
+    documentTitle?: string;
+}
+interface FFIDSystemMaintenancePayload {
+    maintenanceId?: string;
+    scheduledAt?: string;
+    estimatedDuration?: string;
+    description?: string;
+}
+interface FFIDAnnouncementPublishedPayload {
+    announcementId: string;
+    type: string;
+    title: string;
+    content: string;
+    scheduledAt?: string | null;
+    durationMinutes?: number | null;
+    affectedServices?: string[];
+    channels?: string[];
+    publishedAt?: string | null;
+}
+interface FFIDTestPingPayload {
+    message?: string;
+}
+/** Maps event type strings to their typed payloads */
+interface FFIDWebhookEventMap {
+    'subscription.created': FFIDSubscriptionCreatedPayload;
+    'subscription.updated': FFIDSubscriptionUpdatedPayload;
+    'subscription.canceled': FFIDSubscriptionCanceledPayload;
+    'subscription.trial_ending': FFIDSubscriptionTrialEndingPayload;
+    'subscription.payment_failed': FFIDSubscriptionPaymentFailedPayload;
+    'user.created': FFIDUserCreatedPayload;
+    'user.updated': FFIDUserUpdatedPayload;
+    'user.deleted': FFIDUserDeletedPayload;
+    'user.deletion_requested': FFIDUserDeletionRequestedPayload;
+    'organization.created': FFIDOrganizationCreatedPayload;
+    'organization.updated': FFIDOrganizationUpdatedPayload;
+    'organization.member.added': FFIDOrganizationMemberAddedPayload;
+    'organization.member.removed': FFIDOrganizationMemberRemovedPayload;
+    'organization.member.role_changed': FFIDOrganizationMemberRoleChangedPayload;
+    'legal.document.updated': FFIDLegalDocumentUpdatedPayload;
+    'legal.agreement.required': FFIDLegalAgreementRequiredPayload;
+    'system.maintenance.scheduled': FFIDSystemMaintenancePayload;
+    'system.maintenance.started': FFIDSystemMaintenancePayload;
+    'system.maintenance.completed': FFIDSystemMaintenancePayload;
+    'announcement.published': FFIDAnnouncementPublishedPayload;
+    'test.ping': FFIDTestPingPayload;
+}
+/** A webhook event envelope with typed payload */
+interface FFIDWebhookEvent<T extends FFIDWebhookEventType = FFIDWebhookEventType> {
+    id: string;
+    type: T;
+    createdAt: string;
+    data: T extends keyof FFIDWebhookEventMap ? FFIDWebhookEventMap[T] : Record<string, unknown>;
+}
+/** Configuration for the webhook handler */
+interface FFIDWebhookHandlerConfig {
+    /** Webhook endpoint secret used for signature verification */
+    secret: string;
+    /** Maximum age of webhook timestamp in seconds (default: 300) */
+    toleranceSeconds?: number;
+    /** Custom logger */
+    logger?: FFIDWebhookLogger;
+}
+/** Logger interface for webhook SDK */
+interface FFIDWebhookLogger {
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}
+/** Event handler callback type */
+type FFIDWebhookEventHandler<T extends FFIDWebhookEventType = FFIDWebhookEventType> = (event: FFIDWebhookEvent<T>) => void | Promise<void>;
+
+/**
+ * FFID Webhook Signature Verification
+ *
+ * HMAC-SHA256 signature parsing and verification for incoming webhook events.
+ * Compatible with the server-side signing implementation (src/lib/webhooks/signing.ts).
+ *
+ * Signature format: t={timestamp},v1={hex_hmac}
+ * Signed content:   {timestamp}.{body}
+ */
+
+/**
+ * Parse a signature header into timestamp and signature components.
+ *
+ * @param header - Raw signature header value (e.g. "t=1234567890,v1=abcdef...")
+ * @returns Parsed components, or null if the header is malformed
+ */
+declare function parseSignatureHeader(header: string): {
+    timestamp: number;
+    signature: string;
+} | null;
+/**
+ * Compute HMAC-SHA256 for a webhook payload.
+ *
+ * @param secret - Webhook endpoint secret
+ * @param timestamp - Unix timestamp in seconds
+ * @param body - Raw request body string
+ * @returns Hex-encoded HMAC-SHA256 signature
+ */
+declare function computeSignature(secret: string, timestamp: number, body: string): string;
+/**
+ * Verify a webhook signature and timestamp, then parse the event body.
+ *
+ * @param rawBody - Raw request body string
+ * @param signatureHeader - Value of the X-FFID-Signature header
+ * @param secret - Webhook endpoint secret
+ * @param toleranceSeconds - Maximum age of timestamp (default: 300s)
+ * @returns Parsed webhook event
+ * @throws {FFIDWebhookSignatureError} If the header is malformed or signature is invalid
+ * @throws {FFIDWebhookTimestampError} If the timestamp is outside the tolerance window
+ */
+declare function verifyWebhookSignature(rawBody: string, signatureHeader: string, secret: string, toleranceSeconds?: number): FFIDWebhookEvent;
+
+/**
+ * FFID Webhook Handler
+ *
+ * Factory function for creating a webhook event handler with typed event
+ * registration, signature verification, and framework integrations.
+ *
+ * @example
+ * ```typescript
+ * import { createFFIDWebhookHandler } from '@feelflow/ffid-sdk/webhooks'
+ *
+ * const webhooks = createFFIDWebhookHandler({
+ *   secret: process.env.FFID_WEBHOOK_SECRET!,
+ * })
+ *
+ * webhooks.on('subscription.created', (event) => {
+ *   console.log('New subscription:', event.data.subscriptionId)
+ * })
+ *
+ * // Next.js App Router
+ * export const POST = webhooks.nextHandler()
+ * ```
+ */
+
+/**
+ * Creates an FFID webhook event handler.
+ *
+ * @param config - Handler configuration (secret is required)
+ * @returns Webhook handler instance with event registration and framework helpers
+ */
+declare function createFFIDWebhookHandler(config: FFIDWebhookHandlerConfig): {
+    /** Register a handler for a specific event type */
+    on: <T extends FFIDWebhookEventType>(eventType: T, handler: FFIDWebhookEventHandler<T>) => void;
+    /** Register a handler that receives all events */
+    onAll: (handler: FFIDWebhookEventHandler) => void;
+    /** Unregister a handler for a specific event type */
+    off: <T extends FFIDWebhookEventType>(eventType: T, handler: FFIDWebhookEventHandler<T>) => void;
+    /** Verify signature and dispatch event (core method) */
+    handleEvent: (rawBody: string, signatureHeader: string) => Promise<FFIDWebhookEvent>;
+    /** Process webhook from raw body + headers object */
+    handleRaw: (rawBody: string, headers: Record<string, string | undefined>) => Promise<FFIDWebhookEvent>;
+    /** Express/Connect middleware */
+    expressMiddleware: () => (req: {
+        body: unknown;
+        headers: Record<string, string | string[] | undefined>;
+    }, res: {
+        status: (code: number) => {
+            json: (body: unknown) => void;
+        };
+    }, next: () => void) => void;
+    /** Next.js App Router route handler */
+    nextHandler: () => (request: Request) => Promise<Response>;
+};
+/** Type of the FFID Webhook handler */
+type FFIDWebhookHandler = ReturnType<typeof createFFIDWebhookHandler>;
+
+export { DEFAULT_TOLERANCE_SECONDS, type FFIDLegalAgreementRequiredPayload, type FFIDLegalDocumentUpdatedPayload, type FFIDOrganizationCreatedPayload, type FFIDOrganizationMemberAddedPayload, type FFIDOrganizationMemberRemovedPayload, type FFIDOrganizationMemberRoleChangedPayload, type FFIDOrganizationUpdatedPayload, type FFIDSubscriptionCanceledPayload, type FFIDSubscriptionCreatedPayload, type FFIDSubscriptionPaymentFailedPayload, type FFIDSubscriptionTrialEndingPayload, type FFIDSubscriptionUpdatedPayload, type FFIDSystemMaintenancePayload, type FFIDTestPingPayload, type FFIDUserCreatedPayload, type FFIDUserDeletedPayload, type FFIDUserDeletionRequestedPayload, type FFIDUserUpdatedPayload, FFIDWebhookError, type FFIDWebhookEvent, type FFIDWebhookEventHandler, type FFIDWebhookEventMap, type FFIDWebhookEventType, type FFIDWebhookHandler, type FFIDWebhookHandlerConfig, type FFIDWebhookLogger, FFIDWebhookPayloadError, FFIDWebhookSignatureError, FFIDWebhookTimestampError, FFID_WEBHOOK_EVENT_ID_HEADER, FFID_WEBHOOK_SIGNATURE_HEADER, FFID_WEBHOOK_SIGNATURE_VERSION, FFID_WEBHOOK_TIMESTAMP_HEADER, computeSignature, createFFIDWebhookHandler, parseSignatureHeader, verifyWebhookSignature };