@wolpertingerlabs/drawlatch 1.0.0-alpha.2 → 1.0.0-alpha.29

package/dist/remote/ingestors/registry.d.ts

@@ -9,7 +9,7 @@
 import type { BaseIngestor } from './base-ingestor.js';
 import type { IngestorConfig } from './types.js';
 /** Signature for a factory that creates an ingestor from its config. */
-export type IngestorFactory = (connectionAlias: string, config: IngestorConfig, secrets: Record<string, string>, bufferSize?: number) => BaseIngestor | null;
+export type IngestorFactory = (connectionAlias: string, config: IngestorConfig, secrets: Record<string, string>, bufferSize?: number, instanceId?: string) => BaseIngestor | null;
 /**
  * Register a factory for a given ingestor key.
  *
@@ -28,5 +28,5 @@ export declare function registerIngestorFactory(key: string, factory: IngestorFa
  *
  * Returns `null` if no factory is registered or if the factory declines to create.
  */
-export declare function createIngestor(connectionAlias: string, config: IngestorConfig, secrets: Record<string, string>, bufferSize?: number): BaseIngestor | null;
+export declare function createIngestor(connectionAlias: string, config: IngestorConfig, secrets: Record<string, string>, bufferSize?: number, instanceId?: string): BaseIngestor | null;
 //# sourceMappingURL=registry.d.ts.map

package/dist/remote/ingestors/registry.js

@@ -30,7 +30,7 @@ export function registerIngestorFactory(key, factory) {
  *
  * Returns `null` if no factory is registered or if the factory declines to create.
  */
-export function createIngestor(connectionAlias, config, secrets, bufferSize) {
+export function createIngestor(connectionAlias, config, secrets, bufferSize, instanceId) {
     const key = config.type === 'websocket'
         ? `websocket:${config.websocket?.protocol ?? 'generic'}`
         : config.type === 'webhook'
@@ -41,6 +41,6 @@ export function createIngestor(connectionAlias, config, secrets, bufferSize) {
         log.error(`No factory registered for "${key}" (${connectionAlias})`);
         return null;
     }
-    return factory(connectionAlias, config, secrets, bufferSize);
+    return factory(connectionAlias, config, secrets, bufferSize, instanceId);
 }
 //# sourceMappingURL=registry.js.map

package/dist/remote/ingestors/slack/socket-mode.d.ts

@@ -27,9 +27,9 @@ export declare class SlackSocketModeIngestor extends BaseIngestor {
     private readonly eventFilter;
     private readonly channelIds;
     private readonly userIds;
-    constructor(connectionAlias: string, secrets: Record<string, string>, wsConfig: WebSocketIngestorConfig, bufferSize?: number);
+    constructor(connectionAlias: string, secrets: Record<string, string>, wsConfig: WebSocketIngestorConfig, bufferSize?: number, instanceId?: string);
     start(): Promise<void>;
-    stop(): Promise<void>;
+    stop(_permanent?: boolean): Promise<void>;
     /**
      * Call apps.connections.open to get a dynamic WebSocket URL, then connect.
      */

package/dist/remote/ingestors/slack/socket-mode.js

@@ -31,8 +31,8 @@ export class SlackSocketModeIngestor extends BaseIngestor {
     eventFilter;
     channelIds;
     userIds;
-    constructor(connectionAlias, secrets, wsConfig, bufferSize) {
-        super(connectionAlias, 'websocket', secrets, bufferSize);
+    constructor(connectionAlias, secrets, wsConfig, bufferSize, instanceId) {
+        super(connectionAlias, 'websocket', secrets, bufferSize, instanceId);
         this.wsConfig = wsConfig;
         this.connectUrl = wsConfig.gatewayUrl;
         this.eventFilter = wsConfig.eventFilter ?? [];
@@ -43,12 +43,34 @@ export class SlackSocketModeIngestor extends BaseIngestor {
         this.state = 'starting';
         await this.openConnection();
     }
-    stop() {
+    stop(_permanent) {
         this.state = 'stopped';
         this.clearReconnectTimer();
         if (this.ws) {
-            this.ws.close(1000, 'Shutting down');
+            const ws = this.ws;
             this.ws = null;
+            // Wait for the WebSocket to fully close before resolving.
+            // This prevents a race where the old connection is still alive when a new
+            // ingestor starts, causing Slack to distribute events to the dying
+            // connection (where nobody processes them).
+            return new Promise((resolve) => {
+                const onClose = () => {
+                    ws.removeEventListener('close', onClose);
+                    resolve();
+                };
+                if (ws.readyState === WebSocket.CLOSED) {
+                    resolve();
+                }
+                else {
+                    ws.addEventListener('close', onClose);
+                    ws.close(1000, 'Shutting down');
+                    // Safety timeout — don't block forever if close event never fires
+                    setTimeout(() => {
+                        ws.removeEventListener('close', onClose);
+                        resolve();
+                    }, 5000);
+                }
+            });
         }
         return Promise.resolve();
     }
@@ -257,11 +279,11 @@ export class SlackSocketModeIngestor extends BaseIngestor {
     }
 }
 // ── Self-registration ────────────────────────────────────────────────────
-registerIngestorFactory('websocket:slack', (connectionAlias, config, secrets, bufferSize) => {
+registerIngestorFactory('websocket:slack', (connectionAlias, config, secrets, bufferSize, instanceId) => {
     if (!config.websocket) {
         log.error(`Missing websocket config for ${connectionAlias}`);
         return null;
     }
-    return new SlackSocketModeIngestor(connectionAlias, secrets, config.websocket, bufferSize);
+    return new SlackSocketModeIngestor(connectionAlias, secrets, config.websocket, bufferSize, instanceId);
 });
 //# sourceMappingURL=socket-mode.js.map

package/dist/remote/ingestors/types.d.ts

@@ -5,6 +5,7 @@
  * pulling real-time events from external services (Discord Gateway, webhooks,
  * polling) and buffering them for the MCP proxy to retrieve via `poll_events`.
  */
+import type { WebhookLifecycleConfig } from './webhook/lifecycle-types.js';
 /** Top-level ingestor configuration attached to a connection template. */
 export interface IngestorConfig {
     /** Type of ingestor — determines which runtime class is used. */
@@ -56,6 +57,10 @@ export interface WebhookIngestorConfig {
      *  Required for services like Trello that include the callback URL in their
      *  signature computation. May contain ${VAR} placeholders resolved from secrets. */
     callbackUrl?: string;
+    /** Declarative webhook lifecycle configuration for auto-registration and cleanup.
+     *  When present, the ingestor will automatically list, register, and unregister
+     *  webhooks with the external service at the appropriate lifecycle moments. */
+    lifecycle?: WebhookLifecycleConfig;
 }
 /** Configuration for polling-based ingestors (e.g., Notion search). */
 export interface PollIngestorConfig {
@@ -81,6 +86,12 @@ export interface PollIngestorConfig {
      *  Values may contain ${VAR} placeholders.
      *  These are merged UNDER the connection's route headers (route headers take precedence). */
     headers?: Record<string, string>;
+    /** Enable ETag-based conditional requests.
+     *  When true, the poller stores the ETag from each successful response and sends
+     *  `If-None-Match` on subsequent requests. HTTP 304 responses are treated as a
+     *  successful no-op (no items, no error). Useful for APIs like GitHub Events
+     *  where 304s do not count against rate limits. */
+    etag?: boolean;
 }
 /** A single event received by an ingestor, stored in the ring buffer. */
 export interface IngestedEvent {
@@ -105,8 +116,13 @@ export interface IngestedEvent {
     receivedAt: string;
     /** Unix timestamp (milliseconds) when the event was received by the ingestor. */
     receivedAtMs: number;
+    /** Caller alias that owns this event (e.g., 'default', 'alice'). */
+    callerAlias: string;
     /** Source connection alias (e.g., 'discord-bot', 'github'). */
     source: string;
+    /** Instance identifier for multi-instance listeners (e.g., "project-board").
+     *  Omitted for single-instance connections (the default). */
+    instanceId?: string;
     /** Event type/name (e.g., 'MESSAGE_CREATE', 'push'). */
     eventType: string;
     /** The raw event payload from the external service. */
@@ -118,6 +134,9 @@ export type IngestorState = 'starting' | 'connected' | 'reconnecting' | 'stopped
 export interface IngestorStatus {
     /** Connection alias this ingestor belongs to. */
     connection: string;
+    /** Instance identifier for multi-instance listeners.
+     *  Omitted for single-instance connections (the default). */
+    instanceId?: string;
     /** Ingestor type. */
     type: 'websocket' | 'webhook' | 'poll';
     /** Current lifecycle state. */
@@ -130,6 +149,12 @@ export interface IngestorStatus {
     lastEventAt: string | null;
     /** Error message when state is 'error'. */
     error?: string;
+    /** Webhook registration status (only present for webhook ingestors with lifecycle config). */
+    webhookRegistration?: {
+        registered: boolean;
+        webhookId?: string;
+        error?: string;
+    };
 }
 /** Default ring buffer capacity per ingestor. */
 export declare const DEFAULT_BUFFER_SIZE = 200;

package/dist/remote/ingestors/webhook/base-webhook-ingestor.d.ts

@@ -12,11 +12,17 @@
  * 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 } from '../types.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;
@@ -26,19 +32,42 @@ export declare abstract class WebhookIngestor extends BaseIngestor {
     protected readonly signatureHeader: string | undefined;
     /** Event type filter (empty = capture all). */
     protected readonly eventFilter: string[];
-    constructor(connectionAlias: string, secrets: Record<string, string>, webhookConfig: WebhookIngestorConfig, bufferSize?: number);
+    /** 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.
      *
-     * Unlike WebSocket ingestors, there's nothing to "connect" to — the ingestor
-     * is passive and waits for `handleWebhook()` calls from the Express route.
-     * We set the state to 'connected' immediately.
+     * 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. Nothing to clean up — just set state.
+     * 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).
      */
-    stop(): Promise<void>;
+    protected getModelId(): string | undefined;
+    /** Return status including webhook registration state. */
+    getStatus(): IngestorStatus;
     /**
      * Verify the webhook signature.
      *
@@ -78,6 +107,16 @@ export declare abstract class WebhookIngestor extends BaseIngestor {
      * @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.
      *

package/dist/remote/ingestors/webhook/base-webhook-ingestor.js

@@ -12,10 +12,17 @@
  * 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 { WebhookLifecycleManager } from './webhook-lifecycle-manager.js';
+import { resolvePlaceholders } from '../../../shared/config.js';
 import { createLogger } from '../../../shared/logger.js';
 const log = createLogger('webhook');
 // ── Abstract Webhook Ingestor ──────────────────────────────────────────
@@ -28,32 +35,126 @@ export class WebhookIngestor extends BaseIngestor {
     signatureHeader;
     /** Event type filter (empty = capture all). */
     eventFilter;
-    constructor(connectionAlias, secrets, webhookConfig, bufferSize) {
-        super(connectionAlias, 'webhook', secrets, bufferSize);
+    /** Resolved callback URL (with ${VAR} placeholders replaced). */
+    resolvedCallbackUrl;
+    /** Lifecycle manager for auto-registration (null if no lifecycle config). */
+    lifecycleManager;
+    /** Runtime state of the webhook registration. */
+    registrationState = null;
+    constructor(connectionAlias, secrets, webhookConfig, bufferSize, instanceId) {
+        super(connectionAlias, 'webhook', secrets, bufferSize, instanceId);
         this.webhookPath = webhookConfig.path;
         this.signatureHeader = webhookConfig.signatureHeader;
         this.signatureSecretName = webhookConfig.signatureSecret;
         this.eventFilter = [];
+        // Resolve callbackUrl from secrets if it contains ${VAR} placeholders
+        if (webhookConfig.callbackUrl) {
+            this.resolvedCallbackUrl = resolvePlaceholders(webhookConfig.callbackUrl, secrets);
+        }
+        // Initialize lifecycle manager if lifecycle config is present
+        if (webhookConfig.lifecycle) {
+            this.lifecycleManager = new WebhookLifecycleManager(webhookConfig.lifecycle, secrets);
+        }
+        else {
+            this.lifecycleManager = null;
+        }
     }
     /**
      * Start the webhook ingestor.
      *
-     * Unlike WebSocket ingestors, there's nothing to "connect" to — the ingestor
-     * is passive and waits for `handleWebhook()` calls from the Express route.
-     * We set the state to 'connected' immediately.
+     * 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() {
+    async start() {
+        // Attempt lifecycle registration if configured
+        if (this.lifecycleManager && this.resolvedCallbackUrl) {
+            try {
+                this.registrationState = await this.lifecycleManager.ensureRegistered(this.resolvedCallbackUrl, this.getModelId());
+                if (this.registrationState.registered) {
+                    log.info(`Webhook auto-registered for ${this.connectionAlias} ` +
+                        `(ID: ${this.registrationState.webhookId})`);
+                }
+                else if (this.registrationState.error) {
+                    log.warn(`Webhook auto-registration failed for ${this.connectionAlias}: ` +
+                        this.registrationState.error);
+                }
+            }
+            catch (err) {
+                log.warn(`Webhook lifecycle error for ${this.connectionAlias}:`, err);
+                this.registrationState = {
+                    registered: false,
+                    error: err instanceof Error ? err.message : String(err),
+                    lastAttempt: new Date().toISOString(),
+                };
+            }
+        }
+        // Always proceed to connected state (graceful degradation)
         this.state = 'connected';
         log.info(`Webhook ingestor ready for ${this.connectionAlias} ` +
             `(path: /webhooks/${this.webhookPath})`);
-        return Promise.resolve();
     }
     /**
-     * Stop the webhook ingestor. Nothing to clean up — just set state.
+     * 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() {
+    async stop(permanent) {
+        // Unregister webhook on permanent stop if we have a registered webhook
+        if (permanent &&
+            this.lifecycleManager &&
+            this.registrationState?.registered &&
+            this.registrationState.webhookId) {
+            try {
+                await this.lifecycleManager.unregister(this.registrationState.webhookId);
+                log.info(`Webhook unregistered for ${this.connectionAlias}`);
+            }
+            catch (err) {
+                log.warn(`Webhook unregistration failed for ${this.connectionAlias}:`, err);
+            }
+        }
         this.state = 'stopped';
-        return Promise.resolve();
+    }
+    // ── Lifecycle hooks for subclasses ───────────────────────────────────
+    /**
+     * 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).
+     */
+    getModelId() {
+        return undefined;
+    }
+    // ── Status ─────────────────────────────────────────────────────────────
+    /** Return status including webhook registration state. */
+    getStatus() {
+        const status = super.getStatus();
+        if (this.registrationState) {
+            status.webhookRegistration = {
+                registered: this.registrationState.registered,
+                ...(this.registrationState.webhookId && { webhookId: this.registrationState.webhookId }),
+                ...(this.registrationState.error && { error: this.registrationState.error }),
+            };
+        }
+        return status;
+    }
+    /**
+     * 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.
+     */
+    shouldAcceptPayload(_body) {
+        return true;
     }
     /**
      * Extract a service-specific idempotency key from the webhook request.
@@ -100,6 +201,10 @@ export class WebhookIngestor extends BaseIngestor {
         catch {
             return { accepted: false, reason: 'Invalid JSON body' };
         }
+        // 2.5. Instance-level content filter (for multi-instance discrimination)
+        if (!this.shouldAcceptPayload(body)) {
+            return { accepted: true, reason: 'Not for this instance' };
+        }
         // 3. Determine event type (delegated to subclass)
         const eventType = this.extractEventType(headers, body);
         // 4. Apply event filter (if any — reserved for future caller overrides)

package/dist/remote/ingestors/webhook/github-webhook-ingestor.d.ts

@@ -10,8 +10,38 @@
  *
  * @see https://docs.github.com/en/webhooks
  */
+import type { WebhookIngestorConfig } from '../types.js';
 import { WebhookIngestor } from './base-webhook-ingestor.js';
 export declare class GitHubWebhookIngestor extends WebhookIngestor {
+    /**
+     * Repository filter for multi-instance support.
+     * When set, only webhooks from these repositories (owner/repo format) are accepted.
+     * Set via `_repoFilter` on the webhook config (injected by IngestorManager).
+     */
+    private readonly repoFilter;
+    /**
+     * Organization filter for org-level webhook registration.
+     * When set, lifecycle URLs target the org API instead of the repo API.
+     * Set via `_orgFilter` on the webhook config (injected by IngestorManager).
+     */
+    private readonly orgFilter;
+    constructor(connectionAlias: string, secrets: Record<string, string>, webhookConfig: WebhookIngestorConfig, bufferSize?: number, instanceId?: string);
+    /**
+     * Return the model ID for multi-instance webhook lifecycle management.
+     * For org-level: the org name. For repo-level: the single repo name.
+     */
+    protected getModelId(): string | undefined;
+    /**
+     * Clone webhookConfig with lifecycle URLs rewritten for org-level endpoints.
+     * Replaces `repos/${repoFilter}` with `orgs/${orgFilter}` in all lifecycle URLs.
+     */
+    private static withOrgLifecycle;
+    /**
+     * Filter webhooks by repository for multi-instance support.
+     * When repoFilter is set, only events from those repos are accepted.
+     * The repo is found in `body.repository.full_name` of GitHub webhook payloads.
+     */
+    protected shouldAcceptPayload(body: unknown): boolean;
     /**
      * Verify the GitHub webhook signature (HMAC-SHA256).
      *

package/dist/remote/ingestors/webhook/github-webhook-ingestor.js

@@ -17,6 +17,77 @@ import { createLogger } from '../../../shared/logger.js';
 const log = createLogger('webhook');
 // ── GitHub Webhook Ingestor ──────────────────────────────────────────────
 export class GitHubWebhookIngestor extends WebhookIngestor {
+    /**
+     * Repository filter for multi-instance support.
+     * When set, only webhooks from these repositories (owner/repo format) are accepted.
+     * Set via `_repoFilter` on the webhook config (injected by IngestorManager).
+     */
+    repoFilter;
+    /**
+     * Organization filter for org-level webhook registration.
+     * When set, lifecycle URLs target the org API instead of the repo API.
+     * Set via `_orgFilter` on the webhook config (injected by IngestorManager).
+     */
+    orgFilter;
+    constructor(connectionAlias, secrets, webhookConfig, bufferSize, instanceId) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any -- injected by IngestorManager for multi-instance support
+        const orgFilter = webhookConfig._orgFilter;
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
+        const repoFilterArr = webhookConfig._repoFilter;
+        // When orgFilter is set, swap lifecycle URLs to use org endpoints
+        if (orgFilter && webhookConfig.lifecycle) {
+            webhookConfig = GitHubWebhookIngestor.withOrgLifecycle(webhookConfig);
+        }
+        else if (!repoFilterArr?.length && !orgFilter && webhookConfig.lifecycle) {
+            // Neither filter set — lifecycle registration can't determine the target
+            log.warn(`${connectionAlias}: No repoFilter or orgFilter set — webhook auto-registration disabled. ` +
+                'Set repoFilter (owner/repo) or orgFilter (org name) to enable.');
+            webhookConfig = { ...webhookConfig, lifecycle: undefined };
+        }
+        super(connectionAlias, secrets, webhookConfig, bufferSize, instanceId);
+        this.repoFilter = repoFilterArr ?? [];
+        this.orgFilter = orgFilter;
+    }
+    /**
+     * Return the model ID for multi-instance webhook lifecycle management.
+     * For org-level: the org name. For repo-level: the single repo name.
+     */
+    getModelId() {
+        if (this.orgFilter)
+            return this.orgFilter;
+        return this.repoFilter.length === 1 ? this.repoFilter[0] : undefined;
+    }
+    /**
+     * Clone webhookConfig with lifecycle URLs rewritten for org-level endpoints.
+     * Replaces `repos/${repoFilter}` with `orgs/${orgFilter}` in all lifecycle URLs.
+     */
+    static withOrgLifecycle(config) {
+        if (!config.lifecycle)
+            return config;
+        const lc = config.lifecycle;
+        const swap = (url) => url.replace('repos/${repoFilter}', 'orgs/${orgFilter}');
+        return {
+            ...config,
+            lifecycle: {
+                list: lc.list ? { ...lc.list, url: swap(lc.list.url) } : undefined,
+                register: lc.register ? { ...lc.register, url: swap(lc.register.url) } : undefined,
+                unregister: lc.unregister ? { ...lc.unregister, url: swap(lc.unregister.url) } : undefined,
+            },
+        };
+    }
+    /**
+     * Filter webhooks by repository for multi-instance support.
+     * When repoFilter is set, only events from those repos are accepted.
+     * The repo is found in `body.repository.full_name` of GitHub webhook payloads.
+     */
+    shouldAcceptPayload(body) {
+        if (this.repoFilter.length === 0)
+            return true;
+        const payload = body;
+        const repo = payload.repository?.full_name;
+        // Events without a repository (e.g., org-level events) pass through when no filter
+        return repo ? this.repoFilter.includes(repo) : true;
+    }
     /**
      * Verify the GitHub webhook signature (HMAC-SHA256).
      *
@@ -76,11 +147,11 @@ export class GitHubWebhookIngestor extends WebhookIngestor {
     }
 }
 // ── Self-registration ────────────────────────────────────────────────────
-registerIngestorFactory('webhook:generic', (connectionAlias, config, secrets, bufferSize) => {
+registerIngestorFactory('webhook:generic', (connectionAlias, config, secrets, bufferSize, instanceId) => {
     if (!config.webhook) {
         log.error(`Missing webhook config for ${connectionAlias}`);
         return null;
     }
-    return new GitHubWebhookIngestor(connectionAlias, secrets, config.webhook, bufferSize);
+    return new GitHubWebhookIngestor(connectionAlias, secrets, config.webhook, bufferSize, instanceId);
 });
 //# sourceMappingURL=github-webhook-ingestor.js.map

package/dist/remote/ingestors/webhook/lifecycle-types.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Type definitions for webhook lifecycle management.
+ *
+ * Webhook lifecycle configs are declared in connection JSON templates and
+ * describe how to list, register, and unregister webhooks with external
+ * services (Trello, GitHub, Stripe, etc.).
+ *
+ * All URL and body values support `${VAR}` placeholder resolution against
+ * resolved secrets and instance params.
+ */
+/** Lifecycle configuration for a webhook ingestor. */
+export interface WebhookLifecycleConfig {
+    /**
+     * List existing webhooks from the external service.
+     * Used to find existing registrations and detect stale ones.
+     */
+    list?: {
+        method: string;
+        url: string;
+        headers?: Record<string, string>;
+        /** Dot-path to the array in the response (omit if top-level array). */
+        responsePath?: string;
+        /** Field name in each webhook object containing the callback URL. */
+        callbackUrlField: string;
+        /** Field name in each webhook object containing the webhook ID. */
+        idField: string;
+        /** Field name in each webhook object containing the model/resource ID. */
+        modelIdField?: string;
+    };
+    /**
+     * Register a new webhook with the external service.
+     */
+    register?: {
+        method: string;
+        url: string;
+        headers?: Record<string, string>;
+        /** Request body (supports ${VAR} and ${instanceParam} placeholders). */
+        body?: Record<string, unknown>;
+        /** Field name in the response containing the new webhook ID. */
+        idField: string;
+    };
+    /**
+     * Unregister (delete) a webhook from the external service.
+     * The URL supports ${_webhookId} which is replaced at call time.
+     */
+    unregister?: {
+        method: string;
+        url: string;
+        headers?: Record<string, string>;
+    };
+}
+/** Runtime state of a webhook registration. */
+export interface WebhookRegistrationState {
+    /** Whether the webhook is currently registered with the external service. */
+    registered: boolean;
+    /** The ID of the registered webhook (from the external service). */
+    webhookId?: string;
+    /** Error message if registration failed. */
+    error?: string;
+    /** ISO-8601 timestamp of the last registration attempt. */
+    lastAttempt?: string;
+}
+//# sourceMappingURL=lifecycle-types.d.ts.map

package/dist/remote/ingestors/webhook/lifecycle-types.js

@@ -0,0 +1,12 @@
+/**
+ * Type definitions for webhook lifecycle management.
+ *
+ * Webhook lifecycle configs are declared in connection JSON templates and
+ * describe how to list, register, and unregister webhooks with external
+ * services (Trello, GitHub, Stripe, etc.).
+ *
+ * All URL and body values support `${VAR}` placeholder resolution against
+ * resolved secrets and instance params.
+ */
+export {};
+//# sourceMappingURL=lifecycle-types.js.map

package/dist/remote/ingestors/webhook/stripe-webhook-ingestor.js

@@ -80,11 +80,11 @@ export class StripeWebhookIngestor extends WebhookIngestor {
     }
 }
 // ── Self-registration ────────────────────────────────────────────────────
-registerIngestorFactory('webhook:stripe', (connectionAlias, config, secrets, bufferSize) => {
+registerIngestorFactory('webhook:stripe', (connectionAlias, config, secrets, bufferSize, instanceId) => {
     if (!config.webhook) {
         log.error(`Missing webhook config for ${connectionAlias}`);
         return null;
     }
-    return new StripeWebhookIngestor(connectionAlias, secrets, config.webhook, bufferSize);
+    return new StripeWebhookIngestor(connectionAlias, secrets, config.webhook, bufferSize, instanceId);
 });
 //# sourceMappingURL=stripe-webhook-ingestor.js.map