/**
 * @name premium/webhook-engine
 * @description Signed webhook delivery engine for premium event callbacks.
 *
 * After a session is activated, the webhook engine registers a buyer-owned
 * HTTPS endpoint, subscribes to the provider for matching events, signs each
 * delivery with HMAC-SHA256, and dispatches it via HTTP POST.
 *
 * The engine enforces:
 *   - Event filtering: only delivers event ids listed in the subscription.
 *   - URL validation: rejects localhost, private networks, and non-HTTPS URLs.
 *   - Signing: HMAC-SHA256 over `{deliveryId, deliveredAt, payload}` using
 *     the `SAP_MCP_PREMIUM_WEBHOOK_SIGNER` env var.
 *   - Retry: up to 3 attempts with exponential backoff for non-2xx responses.
 *   - Unit quota: decrements after each successful delivery.
 *   - Idempotency: deduplicates via `eventId` in the event store.
 *
 * @flow
 *   1. Buyer calls `POST /premium/webhook/register` with targetUrl + events.
 *   2. → `registerWebhook()` validates URL, creates subscription.
 *   3. Engine subscribes to provider, receives events matching the subscription.
 *   4. For each matching event: sign, POST to targetUrl, record delivery.
 *   5. Buyer can check delivery status via `getWebhookDeliveryStatus()`.
 *
 * @module premium/webhook-engine
 */
import type { PremiumWebhookDelivery, PremiumWebhookSubscription } from './types.js';
/**
 * @name registerWebhook
 * @description Register a webhook subscription for an active premium session.
 *
 * @param sessionId       - The activated premium session id.
 * @param targetUrl       - HTTPS endpoint owned by the buyer.
 * @param events          - Exact event ids to deliver.
 * @param signingPublicKey - Optional buyer public key for signature verification.
 * @returns The `PremiumWebhookSubscription`, or `null` if the session is not
 *   active or the URL is invalid.
 *
 * @usedBy `premium-tools.ts` → MCP tool `sap_premium_webhook_register`,
 *   `remote/server.ts` → `POST /premium/webhook/register`
 */
export declare function registerWebhook(sessionId: string, targetUrl: string, events: string[], signingPublicKey?: string): Promise<PremiumWebhookSubscription | null>;
/**
 * @name RELAY_TARGET_URL_EXPORT
 * @description Exported relay sentinel so premium-tools and tests can reference it
 *   without duplicating the literal.
 */
export declare const PREMIUM_WEBHOOK_RELAY_TARGET_URL = "relay://buffer";
/**
 * @name registerWebhookRelay
 * @description Register a buffer-only (relay) webhook subscription for an active
 *   premium session.
 *
 * Unlike `registerWebhook`, this does not require a public HTTPS endpoint.
 * Events matching the subscription are appended to the event store by the
 * delivery loop and the agent consumes them via `sap_premium_stream_poll` or
 * `sap_premium_stream_flush`. This solves the core problem for agents running
 * locally without a publicly reachable HTTPS callback URL.
 *
 * @param sessionId - The activated premium session id.
 * @param events    - Exact event ids to buffer.
 * @returns The `PremiumWebhookSubscription`, or `null` if the session is not
 *   active or no events were provided.
 *
 * @usedBy `premium-tools.ts` → MCP tool `sap_premium_webhook_relay`
 */
export declare function registerWebhookRelay(sessionId: string, events: string[]): Promise<PremiumWebhookSubscription | null>;
/**
 * @name getRelaySubscriptionsForSession
 * @description Return all active relay (buffer-only) webhook subscriptions for a
 *   session id. Used by the relay status tool to report buffered event counts.
 *
 * @param sessionId - The premium session id.
 * @returns Array of relay subscriptions for the session.
 *
 * @usedBy `premium-tools.ts` → MCP tool `sap_premium_webhook_relay_status`
 */
export declare function getRelaySubscriptionsForSession(sessionId: string): PremiumWebhookSubscription[];
/**
 * @name startWebhookDelivery
 * @description Start the webhook delivery loop for a subscription.
 *
 * Subscribes to the provider, receives events, filters by the subscription's
 * event list, signs and delivers each matching event, and decrements the
 * session quota. Stops when the quota reaches zero or the subscription is
 * deactivated.
 *
 * @param subscription - The webhook subscription to deliver for.
 *
 * @usedBy `remote/server.ts` → webhook delivery worker
 */
export declare function startWebhookDelivery(subscription: PremiumWebhookSubscription): Promise<void>;
/**
 * @name unregisterWebhook
 * @description Deactivate and remove a webhook subscription.
 *
 * @param subscriptionId - The webhook subscription id.
 * @returns True if the subscription was found and removed.
 *
 * @usedBy `premium-tools.ts` → MCP tool `sap_premium_webhook_unregister`
 */
export declare function unregisterWebhook(subscriptionId: string): boolean;
/**
 * @name getWebhookSubscription
 * @description Retrieve a webhook subscription by id.
 *
 * @param subscriptionId - The webhook subscription id.
 * @returns The subscription, or `null` if not found.
 *
 * @usedBy `premium-tools.ts` → MCP tool `sap_premium_webhook_status`
 */
export declare function getWebhookSubscription(subscriptionId: string): PremiumWebhookSubscription | null;
/**
 * @name getWebhookDeliveries
 * @description Retrieve delivery records for a subscription.
 *
 * @param subscriptionId - The webhook subscription id.
 * @param limit          - Maximum records to return (default 50).
 * @returns Array of `PremiumWebhookDelivery` records.
 *
 * @usedBy `premium-tools.ts` → MCP tool `sap_premium_webhook_status`
 */
export declare function getWebhookDeliveries(subscriptionId: string, limit?: number): PremiumWebhookDelivery[];
/**
 * @name getActiveWebhookCount
 * @description Return the number of currently active webhook subscriptions.
 *
 * @usedBy `metrics.ts`
 */
export declare function getActiveWebhookCount(): number;
/**
 * @name stopAllWebhooks
 * @description Deactivate all webhook subscriptions. Called during graceful shutdown.
 *
 * @usedBy `remote/server.ts` shutdown handler
 */
export declare function stopAllWebhooks(): void;
//# sourceMappingURL=webhook-engine.d.ts.map