import type { JsonObject } from './types.js';
/**
 * Generic webhook subscription primitive — wakes an agent on inbound events
 * from any external system (event bus, queue, scheduler, third-party SaaS
 * webhook, your own application's domain events). fabric-harness consumes a
 * JSON payload and dispatches to the user-provided handler. The host event
 * system decides which payloads land here; fabric-harness has no opinion on
 * event taxonomy or producer.
 */
export interface WebhookSubscriptionContext<TPayload> {
    /** Validated payload (or raw, if no schema was supplied). */
    payload: TPayload;
    /** Inbound HTTP headers (lowercased keys). */
    headers: Record<string, string>;
    /** Aborts when the request is cancelled (client disconnect, timeout). */
    signal: AbortSignal;
    /** Echoed event-pattern hint when supplied by the producer. */
    eventType?: string;
    /** Optional idempotency key from the inbound request. */
    idempotencyKey?: string;
}
export interface WebhookSubscriptionDefinition<TPayload> {
    id: string;
    events?: string[];
    schema?: unknown;
    description?: string;
    handler: (ctx: WebhookSubscriptionContext<TPayload>) => Promise<unknown>;
}
/**
 * Helper that returns the definition unchanged. Useful for type inference and
 * to keep agent files declarative.
 *
 * ```ts
 * import { defineAgent, defineWebhookSubscription } from '@fabric-harness/sdk';
 *
 * export default defineAgent({
 *   name: 'data-validator',
 *   triggers: { webhook: true },
 *   subscriptions: [
 *     defineWebhookSubscription<{ recordId: string }>({
 *       id: 'on-record-created',
 *       events: ['record.created'],
 *       schema: { type: 'object', properties: { recordId: { type: 'string' } }, required: ['recordId'] },
 *       handler: async ({ payload }) => {
 *         // ...invoke whatever your host application exposes.
 *       },
 *     }),
 *   ],
 *   async run() { ... },
 * });
 * ```
 */
export declare function defineWebhookSubscription<TPayload = JsonObject>(definition: WebhookSubscriptionDefinition<TPayload>): WebhookSubscriptionDefinition<TPayload>;
//# sourceMappingURL=webhook-subscription.d.ts.map