/**
 * Generic webhook ingestor base class.
 *
 * A passive ingestor that receives HTTP POST requests from webhook providers
 * and buffers them in the ring buffer for retrieval via `poll_events`.
 *
 * Unlike WebSocket ingestors (which maintain outbound connections), webhook
 * ingestors are receivers — the Express server dispatches incoming webhook
 * requests to matching ingestor instances via `handleWebhook()`.
 *
 * Subclasses implement service-specific signature verification and event
 * extraction by overriding `verifySignature()`, `extractEventType()`, and
 * `extractEventData()`.
 *
 * When a `lifecycle` config is present on the webhook config, this class
 * automatically manages webhook registration with the external service:
 * - On `start()`: lists existing webhooks, cleans up stale ones, registers new
 * - On `stop(permanent=true)`: unregisters the webhook (deletion/shutdown only)
 *
 * @see GitHubWebhookIngestor
 * @see StripeWebhookIngestor
 */
import { BaseIngestor } from '../base-ingestor.js';
import type { WebhookIngestorConfig, IngestorStatus } from '../types.js';
import type { WebhookRegistrationState } from './lifecycle-types.js';
export declare abstract class WebhookIngestor extends BaseIngestor {
    /** The path segment this ingestor listens on (e.g., 'github' → /webhooks/github). */
    readonly webhookPath: string;
    /** The name of the secret key in the resolved secrets used for signature verification. */
    protected readonly signatureSecretName: string | undefined;
    /** The header name containing the webhook signature. */
    protected readonly signatureHeader: string | undefined;
    /** Event type filter (empty = capture all). */
    protected readonly eventFilter: string[];
    /** Resolved callback URL (with ${VAR} placeholders replaced). */
    protected readonly resolvedCallbackUrl: string | undefined;
    /** Lifecycle manager for auto-registration (null if no lifecycle config). */
    private readonly lifecycleManager;
    /** Runtime state of the webhook registration. */
    protected registrationState: WebhookRegistrationState | null;
    constructor(connectionAlias: string, secrets: Record<string, string>, webhookConfig: WebhookIngestorConfig, bufferSize?: number, instanceId?: string);
    /**
     * Start the webhook ingestor.
     *
     * If a lifecycle config is present, attempts to auto-register the webhook
     * with the external service before setting state to 'connected'.
     * Registration failures are logged but never prevent the ingestor from starting
     * (graceful degradation).
     */
    start(): Promise<void>;
    /**
     * Stop the webhook ingestor.
     *
     * When `permanent` is true (server shutdown or instance deletion), unregisters
     * the webhook from the external service if one was registered.
     * Regular stops (pause/restart) leave the webhook intact.
     */
    stop(permanent?: boolean): Promise<void>;
    /**
     * Return the model/resource ID for multi-instance webhook registration.
     *
     * Override in subclasses that support multi-instance webhooks (e.g., Trello
     * board ID, GitHub repo name). Used by the lifecycle manager to match
     * existing webhooks and clean up stale registrations.
     *
     * Default: undefined (single-instance).
     */
    protected getModelId(): string | undefined;
    /** Return status including webhook registration state. */
    getStatus(): IngestorStatus;
    /**
     * Verify the webhook signature.
     *
     * Called before any body parsing. Subclasses implement service-specific
     * signature verification logic (e.g., HMAC-SHA256 for GitHub, timestamp
     * + HMAC for Stripe).
     *
     * @param headers - The raw HTTP request headers.
     * @param rawBody - The raw request body as a Buffer.
     * @returns An object with `valid: true` if verification passed or was skipped,
     *          or `valid: false` with a `reason` string if verification failed.
     */
    protected abstract verifySignature(headers: Record<string, string | string[] | undefined>, rawBody: Buffer): {
        valid: boolean;
        reason?: string;
    };
    /**
     * Extract the event type from the webhook request.
     *
     * Some providers encode the event type in a header (GitHub: `X-GitHub-Event`),
     * others in the JSON body (Stripe: `body.type`).
     *
     * @param headers - The raw HTTP request headers.
     * @param body - The parsed JSON body.
     * @returns The event type string (e.g., 'push', 'payment_intent.succeeded').
     */
    protected abstract extractEventType(headers: Record<string, string | string[] | undefined>, body: unknown): string;
    /**
     * Extract the event data to push into the ring buffer.
     *
     * Subclasses determine the shape of the data stored for each event.
     * For example, GitHub stores `{ deliveryId, event, payload }` while
     * Stripe stores `{ eventId, type, payload }`.
     *
     * @param headers - The raw HTTP request headers.
     * @param body - The parsed JSON body.
     * @returns The data object to store in the ring buffer.
     */
    protected abstract extractEventData(headers: Record<string, string | string[] | undefined>, body: unknown): unknown;
    /**
     * Instance-level content filter for multi-instance webhook discrimination.
     *
     * Called after signature verification and body parsing. Override in subclasses
     * to filter webhooks by resource (e.g., Trello board ID, GitHub repo name).
     * Return false to silently skip the webhook for this instance.
     *
     * Default: accept all webhooks.
     */
    protected shouldAcceptPayload(_body: unknown): boolean;
    /**
     * Extract a service-specific idempotency key from the webhook request.
     *
     * Subclasses override this to return a unique key for deduplication
     * (e.g., GitHub's `X-GitHub-Delivery` header, Stripe's `body.id`).
     *
     * When a key is returned, duplicate events with the same key are silently
     * dropped by the base ingestor's ring buffer.
     *
     * @param headers - The raw HTTP request headers.
     * @param body - The parsed JSON body.
     * @returns A unique idempotency key string, or `undefined` to use a fallback.
     */
    protected extractIdempotencyKey(_headers: Record<string, string | string[] | undefined>, _body: unknown): string | undefined;
    /**
     * Handle an incoming webhook request.
     *
     * Called by the Express route handler when a POST arrives at
     * `/webhooks/:path` that matches this ingestor's `webhookPath`.
     *
     * Orchestrates the full pipeline: verify → parse → extract → filter → buffer.
     *
     * @param headers - The raw HTTP request headers.
     * @param rawBody - The raw request body as a Buffer (needed for signature verification).
     * @returns An object indicating whether the webhook was accepted or rejected.
     */
    handleWebhook(headers: Record<string, string | string[] | undefined>, rawBody: Buffer): {
        accepted: boolean;
        reason?: string;
    };
}
//# sourceMappingURL=base-webhook-ingestor.d.ts.map