@secondlayer/sdk 12.1.0 → 12.3.0

package/dist/index.d.ts

@@ -871,6 +871,17 @@ type StreamsEventsConsumeParams<
 	maxPages?: number;
 	maxEmptyPolls?: number;
 	signal?: AbortSignal;
+	/**
+	* Cuts the empty-poll backoff short: on an empty page, the loop races
+	* `emptyBackoffMs` against this promise instead of sleeping the full
+	* amount. Pass a function that resolves once when new data MIGHT be
+	* available (e.g. a Postgres NOTIFY listener) — it is called fresh on
+	* every empty page, never awaited more than once concurrently per page.
+	* The backoff timer still runs underneath, so a wake source that never
+	* resolves (or a `wake` this call omits) degrades to the same polling
+	* behavior as before.
+	*/
+	wake?: () => Promise<void>;
 };
 /**
 * One yielded page from {@link StreamsClient.consume} — the
@@ -2789,17 +2800,40 @@ declare function getSubgraph<T extends {
 }>(def: T, options?: Partial<SecondLayerOptions> | SecondLayer | Subgraphs): InferSubgraphClient2<T>;
 import { SubgraphAgentSchema as SubgraphAgentSchema3, SubgraphSpecFormat as SubgraphSpecFormat2, SubgraphSpecOptions as SubgraphSpecOptions3 } from "@secondlayer/shared/subgraphs/spec";
 import { SubgraphDetail as SubgraphDetail2 } from "@secondlayer/shared/schemas/subgraphs";
-import { DeadRow as DeadRow3, DeliveryRow as DeliveryRow3, WebhookDetail as WebhookDetail3 } from "@secondlayer/shared/schemas/webhooks";
+import { DeadRow as DeadRow3, DeliveryRow as DeliveryRow3, WebhookDetail as WebhookDetail3, WebhookSummary as WebhookSummary3 } from "@secondlayer/shared/schemas/webhooks";
 /**
 * Webhook diagnosis, shared by `secondlayer webhooks doctor` and the
 * dashboard's webhook detail page. Moved out of the CLI (unchanged behavior)
 * so the web can build the same judgment without printing CLI-command text.
+*
+* Plan 068 adds five deterministic, numbers-only detectors on top of the
+* existing flag checks: no model, no history beyond the deliveries window
+* already fetched. Thresholds are named constants below, conservative on
+* purpose — a wrong insight costs more trust than a missed one.
 */
 declare function isSuccessDelivery(row: DeliveryRow3): boolean;
-type DoctorIssueCode = "warning" | "paused" | "last_error" | "circuit" | "dead_letters" | "subgraph_gaps" | "subgraph_catching_up" | "no_deliveries";
+type DoctorSeverity = "bad" | "warn" | "calm";
+interface DoctorEvidence {
+	label: string;
+	value: string;
+}
+interface DoctorFix {
+	text: string;
+	/** A `secondlayer webhooks ...` command the reader can copy. */
+	command?: string;
+	/** Anchor into the docs' webhooks troubleshooting section. */
+	docsPath?: string;
+}
+type DoctorIssueCode = "warning" | "paused" | "last_error" | "circuit" | "dead_letters" | "subgraph_gaps" | "subgraph_catching_up" | "no_deliveries" | "receiver_rate_limited" | "receiver_down" | "receiver_rejects" | "receiver_slow" | "delivery_lag";
 interface DoctorIssue {
 	code: DoctorIssueCode;
 	detail?: string;
+	severity: DoctorSeverity;
+	/** 2-4 numbers-only facts backing the issue. Only the five new detectors
+	*  and the list-summary circuit issue carry this — the older flag checks
+	*  keep their plain `detail` string. */
+	evidence?: DoctorEvidence[];
+	fix?: DoctorFix;
 }
 interface DoctorReport {
 	webhook: WebhookDetail3;
@@ -2822,6 +2856,10 @@ interface DoctorReport {
 	/** CLI-facing next steps, one per issue, in the same order as `issues`. */
 	hints: string[];
 	issues: DoctorIssue[];
+	/** The single most severe issue (bad > warn > calm, then rule priority),
+	*  or `null` when there are none. The UI leads with this and collapses
+	*  the rest underneath. */
+	primary: DoctorIssue | null;
 }
 declare function buildDoctorReport(input: {
 	webhook: WebhookDetail3;
@@ -2830,6 +2868,15 @@ declare function buildDoctorReport(input: {
 	subgraph?: SubgraphDetail2 | null;
 }): DoctorReport;
 /**
+* The list page's own reduced detector: computed from `WebhookSummary` alone
+* (no deliveries, no dead-letter rows — the list endpoint returns neither,
+* and fetching per-row detail or deliveries here would fan out one request
+* per row). Only `status` and `circuitOpenedAt` distinguish a real problem
+* from a manual pause at this level; deliveries-based rules (rate limits,
+* downtime, rejects, slowness, lag) only ever show on the detail page.
+*/
+declare function buildListIssue(webhook: Pick<WebhookSummary3, "status" | "circuitOpenedAt" | "lastSuccessAt">): DoctorIssue | null;
+/**
 * The two pieces every "deploy a consumer" guide leaves out, packaged:
 * a liveness endpoint and a graceful-shutdown signal. Both are
 * runtime-agnostic — the SDK never binds a port or assumes Bun/Node.
@@ -3258,4 +3305,4 @@ declare const Cursor: {
 	};
 };
 import { decodeClarityValue, toJsonSafe } from "@secondlayer/shared/streams-rows";
-export { ACCOUNT_KEY_ENV, ActiveSubgraphOperation, ApiError, ArchiveAuthError, ArchiveClient, ArchiveCreditsBalance, ArchiveDataset, ArchiveFetchItem, ArchiveFetchResult, ArchiveFlow, ArchiveGateNotConfiguredError, ArchiveLoadOptions, ArchiveManifest, ArchivePartition, ArchiveQuote, ArchiveSignatureError, ArchiveStatus, ArchiveVerifyInput, ArchiveVerifyRangeStatus, ArchiveVerifyResult, AuthError, BlockEnvelope, BlocksEnvelope, BlocksListParams, BlocksWalkParams, CanonicalEnvelope, CanonicalListParams, CanonicalWalkParams, ChainApplyDeliveryOf, ChainApplyEnvelope, ChainApplyEnvelopeOf, ChainEventEnvelope, ChainFtBurnData, ChainFtMintData, ChainFtTransferData, ChainNftBurnData, ChainNftMintData, ChainNftTransferData, ChainPrintEventData, ChainReorgOrphanedEntry, ChainReorgRollbackDelivery, ChainReorgRollbackEnvelope, ChainStxBurnData, ChainStxLockData, ChainStxMintData, ChainStxTransferData, ChainTestDelivery, ChainTrigger, ChainTriggerType, ChainTxLevelEvent, ChainWebhookDelivery2 as ChainWebhookDelivery, ChainWebhookEnvelope, ConsumerBatchContext, ConsumerHealth, ConsumerSink, ContextAccount, ContextField, ContextFieldError, ContextSnapshot, ContractCallsConsumeParams, ContractCallsEnvelope, ContractCallsListParams, ContractCallsWalkParams, ContractConformance, ContractSummary, Contracts, ContractsEnvelope, ContractsListParams, CreateArchiveClientOptions, CreateWebhookRequest2 as CreateWebhookRequest, CreateWebhookResponse2 as CreateWebhookResponse, Cursor, DEFAULT_REQUEST_TIMEOUT_MS, DeadRow2 as DeadRow, DecodedEventColumns, DecodedEventRow, DecodedFtBurn, DecodedFtBurnPayload, DecodedFtMint, DecodedFtMintPayload, DecodedFtTransfer, DecodedFtTransferPayload, DecodedNftBurn, DecodedNftBurnPayload, DecodedNftMint, DecodedNftMintPayload, DecodedNftTransfer, DecodedNftTransferPayload, DecodedPrint, DecodedPrintPayload, DecodedPrintValue, DecodedStxBurn, DecodedStxBurnPayload, DecodedStxLock, DecodedStxLockPayload, DecodedStxMint, DecodedStxMintPayload, DecodedStxTransfer, DecodedStxTransferPayload, DeliveryRow2 as DeliveryRow, DoctorIssue, DoctorIssueCode, DoctorReport, EtagCache, EtagEntry, EventsConsumeParams, EventsEnvelope, EventsListParams, EventsWalkParams, FetchLike2 as FetchLike, FtTransfer, FtTransferEvent, FtTransferPayload2 as FtTransferPayload, FtTransfersEnvelope, FtTransfersListParams, FtTransfersResource, FtTransfersWalkParams, INDEX_MAX_PAGE_SIZE, INSTANCE_TOKEN_ENV, Index, IndexAlwaysFields, IndexBlock, IndexCanonicalBlock, IndexConsumeOptions, IndexContractCall, IndexDiscovery, IndexEvent, IndexEventFields, IndexEventOf, IndexEventType, IndexEventTypeFilters, IndexEventsResource, IndexFeedEnvelope, IndexFeedFetcher, IndexFeedItem, IndexFtBurn, IndexFtMint, IndexFtTransfer, IndexMapDelete, IndexMapInsert, IndexMapSet, IndexMempoolTransaction, IndexNestedContractCall, IndexNftBurn, IndexNftMint, IndexNftTransfer, IndexPostCondition, IndexPox5Event, IndexPox5EventTopic, IndexPoxCycle, IndexPoxFunctionCount, IndexPrint, IndexReorg, IndexSbtcDeposit, IndexSbtcDepositDetail, IndexSbtcEvent, IndexSbtcSummary, IndexSbtcWithdrawal, IndexSbtcWithdrawalDetail, IndexSbtcWithdrawalPhase, IndexStackingAction, IndexStxBurn, IndexStxLock, IndexStxMint, IndexStxTransfer, IndexTip, IndexTransaction, IndexVarSet, InstanceClient, InstanceDiagnosis3 as InstanceDiagnosis, InstanceIssue, InstanceState, InstanceStatus, InsufficientArchiveCreditsError, LOCAL_API_URL, LoadedArchive, MemoryEtagCache, MempoolEnvelope, MempoolListParams, MempoolTransactionEnvelope, MempoolWalkParams, NftTransfer, NftTransferEvent, NftTransferPayload2 as NftTransferPayload, NftTransfersEnvelope, NftTransfersListParams, NftTransfersResource, NftTransfersWalkParams, Pox5EventsEnvelope, Pox5EventsListParams, Pox5EventsWalkParams, Pox5Resource, PoxCycleEnvelope, PoxCyclesEnvelope, PoxCyclesListParams, PoxCyclesWalkParams, PoxResource, PrintSchemaResponse, PublicStatus2 as PublicStatus, RateLimitError, ReplayResult2 as ReplayResult, RequestOptions, RewardSet2 as RewardSet, RotateSecretResponse2 as RotateSecretResponse, SbtcDepositEnvelope, SbtcDepositEvent, SbtcDepositsConsumeParams, SbtcDepositsEnvelope, SbtcDepositsListParams, SbtcDepositsWalkParams, SbtcEventTopic2 as SbtcEventTopic, SbtcEventsConsumeParams, SbtcEventsEnvelope, SbtcEventsListParams, SbtcEventsWalkParams, SbtcResource, SbtcSummaryEnvelope, SbtcWithdrawalEnvelope, SbtcWithdrawalEvent, SbtcWithdrawalStatus, SbtcWithdrawalSweptConfirmedEvent, SbtcWithdrawalsEnvelope, SbtcWithdrawalsListParams, SbtcWithdrawalsWalkParams, SecondLayer, SecondLayerArchive, SecondLayerError, SecondLayerErrorOptions, SecondLayerOptions, SinkTx, StackingEnvelope, StackingListParams, StackingWalkParams, StandardWebhooksHeaders2 as StandardWebhooksHeaders, StreamsBatch, StreamsBatchContext, StreamsCanonicalBlock, StreamsClient, StreamsConsumeParams, StreamsDumpFile, StreamsDumps, StreamsDumpsManifest, StreamsEvent, StreamsEventPayload, StreamsEventType, StreamsEventsConsumeParams, StreamsEventsConsumeResult, StreamsEventsEnvelope, StreamsEventsListEnvelope, StreamsEventsListParams, StreamsEventsStreamParams, StreamsEventsSubscribeParams, StreamsReorg, StreamsReorgContext, StreamsReorgsListEnvelope, StreamsReorgsListParams, StreamsServerError, StreamsSignatureError, StreamsSubscription, StreamsTip, StreamsWireEvent2 as StreamsWireEvent, SubgraphAgentSchema3 as SubgraphAgentSchema, SubgraphOperationStatus, SubgraphSpecFormat2 as SubgraphSpecFormat, SubgraphSpecOptions3 as SubgraphSpecOptions, Subgraphs, TransactionEnvelope, TransactionProof, TransactionProofVerifyResult, TransactionsEnvelope, TransactionsListParams, TransactionsWalkParams, UpdateWebhookRequest2 as UpdateWebhookRequest, ValidationError, VmStreamsEvent, WalkOptions, WebhookDetail2 as WebhookDetail, WebhookFormat, WebhookHeaderInput, WebhookKind, WebhookRuntime, WebhookStatus, WebhookSummary2 as WebhookSummary, WebhookTestResult2 as WebhookTestResult, Webhooks, WithSinkTx, buildDoctorReport, consumeIndexFeed, consumerHealth, contextField, createArchiveClient, createStreamsClient, decode, decodeChainWebhook, decodeClarityValue, decodeFtBurn, decodeFtMint, decodeFtTransfer, decodeNftBurn, decodeNftMint, decodeNftTransfer, decodePrint, decodeStxBurn, decodeStxLock, decodeStxMint, decodeStxTransfer, fetchRewardSet, getSubgraph, isFtBurn, isFtMint, isFtTransfer, isNftBurn, isNftMint, isNftTransfer, isPrint, isStxBurn, isStxLock, isStxMint, isStxTransfer, isSuccessDelivery, parseRetryAfter, resolveAccountKey, resolveApiKey, resolveBaseUrl, shutdownSignal, toJsonSafe, trigger, verifySecondlayerSignature, verify as verifyStandardWebhooksHeaders, verifyTransactionProof, verifyWebhookSignature };
+export { ACCOUNT_KEY_ENV, ActiveSubgraphOperation, ApiError, ArchiveAuthError, ArchiveClient, ArchiveCreditsBalance, ArchiveDataset, ArchiveFetchItem, ArchiveFetchResult, ArchiveFlow, ArchiveGateNotConfiguredError, ArchiveLoadOptions, ArchiveManifest, ArchivePartition, ArchiveQuote, ArchiveSignatureError, ArchiveStatus, ArchiveVerifyInput, ArchiveVerifyRangeStatus, ArchiveVerifyResult, AuthError, BlockEnvelope, BlocksEnvelope, BlocksListParams, BlocksWalkParams, CanonicalEnvelope, CanonicalListParams, CanonicalWalkParams, ChainApplyDeliveryOf, ChainApplyEnvelope, ChainApplyEnvelopeOf, ChainEventEnvelope, ChainFtBurnData, ChainFtMintData, ChainFtTransferData, ChainNftBurnData, ChainNftMintData, ChainNftTransferData, ChainPrintEventData, ChainReorgOrphanedEntry, ChainReorgRollbackDelivery, ChainReorgRollbackEnvelope, ChainStxBurnData, ChainStxLockData, ChainStxMintData, ChainStxTransferData, ChainTestDelivery, ChainTrigger, ChainTriggerType, ChainTxLevelEvent, ChainWebhookDelivery2 as ChainWebhookDelivery, ChainWebhookEnvelope, ConsumerBatchContext, ConsumerHealth, ConsumerSink, ContextAccount, ContextField, ContextFieldError, ContextSnapshot, ContractCallsConsumeParams, ContractCallsEnvelope, ContractCallsListParams, ContractCallsWalkParams, ContractConformance, ContractSummary, Contracts, ContractsEnvelope, ContractsListParams, CreateArchiveClientOptions, CreateWebhookRequest2 as CreateWebhookRequest, CreateWebhookResponse2 as CreateWebhookResponse, Cursor, DEFAULT_REQUEST_TIMEOUT_MS, DeadRow2 as DeadRow, DecodedEventColumns, DecodedEventRow, DecodedFtBurn, DecodedFtBurnPayload, DecodedFtMint, DecodedFtMintPayload, DecodedFtTransfer, DecodedFtTransferPayload, DecodedNftBurn, DecodedNftBurnPayload, DecodedNftMint, DecodedNftMintPayload, DecodedNftTransfer, DecodedNftTransferPayload, DecodedPrint, DecodedPrintPayload, DecodedPrintValue, DecodedStxBurn, DecodedStxBurnPayload, DecodedStxLock, DecodedStxLockPayload, DecodedStxMint, DecodedStxMintPayload, DecodedStxTransfer, DecodedStxTransferPayload, DeliveryRow2 as DeliveryRow, DoctorEvidence, DoctorFix, DoctorIssue, DoctorIssueCode, DoctorReport, DoctorSeverity, EtagCache, EtagEntry, EventsConsumeParams, EventsEnvelope, EventsListParams, EventsWalkParams, FetchLike2 as FetchLike, FtTransfer, FtTransferEvent, FtTransferPayload2 as FtTransferPayload, FtTransfersEnvelope, FtTransfersListParams, FtTransfersResource, FtTransfersWalkParams, INDEX_MAX_PAGE_SIZE, INSTANCE_TOKEN_ENV, Index, IndexAlwaysFields, IndexBlock, IndexCanonicalBlock, IndexConsumeOptions, IndexContractCall, IndexDiscovery, IndexEvent, IndexEventFields, IndexEventOf, IndexEventType, IndexEventTypeFilters, IndexEventsResource, IndexFeedEnvelope, IndexFeedFetcher, IndexFeedItem, IndexFtBurn, IndexFtMint, IndexFtTransfer, IndexMapDelete, IndexMapInsert, IndexMapSet, IndexMempoolTransaction, IndexNestedContractCall, IndexNftBurn, IndexNftMint, IndexNftTransfer, IndexPostCondition, IndexPox5Event, IndexPox5EventTopic, IndexPoxCycle, IndexPoxFunctionCount, IndexPrint, IndexReorg, IndexSbtcDeposit, IndexSbtcDepositDetail, IndexSbtcEvent, IndexSbtcSummary, IndexSbtcWithdrawal, IndexSbtcWithdrawalDetail, IndexSbtcWithdrawalPhase, IndexStackingAction, IndexStxBurn, IndexStxLock, IndexStxMint, IndexStxTransfer, IndexTip, IndexTransaction, IndexVarSet, InstanceClient, InstanceDiagnosis3 as InstanceDiagnosis, InstanceIssue, InstanceState, InstanceStatus, InsufficientArchiveCreditsError, LOCAL_API_URL, LoadedArchive, MemoryEtagCache, MempoolEnvelope, MempoolListParams, MempoolTransactionEnvelope, MempoolWalkParams, NftTransfer, NftTransferEvent, NftTransferPayload2 as NftTransferPayload, NftTransfersEnvelope, NftTransfersListParams, NftTransfersResource, NftTransfersWalkParams, Pox5EventsEnvelope, Pox5EventsListParams, Pox5EventsWalkParams, Pox5Resource, PoxCycleEnvelope, PoxCyclesEnvelope, PoxCyclesListParams, PoxCyclesWalkParams, PoxResource, PrintSchemaResponse, PublicStatus2 as PublicStatus, RateLimitError, ReplayResult2 as ReplayResult, RequestOptions, RewardSet2 as RewardSet, RotateSecretResponse2 as RotateSecretResponse, SbtcDepositEnvelope, SbtcDepositEvent, SbtcDepositsConsumeParams, SbtcDepositsEnvelope, SbtcDepositsListParams, SbtcDepositsWalkParams, SbtcEventTopic2 as SbtcEventTopic, SbtcEventsConsumeParams, SbtcEventsEnvelope, SbtcEventsListParams, SbtcEventsWalkParams, SbtcResource, SbtcSummaryEnvelope, SbtcWithdrawalEnvelope, SbtcWithdrawalEvent, SbtcWithdrawalStatus, SbtcWithdrawalSweptConfirmedEvent, SbtcWithdrawalsEnvelope, SbtcWithdrawalsListParams, SbtcWithdrawalsWalkParams, SecondLayer, SecondLayerArchive, SecondLayerError, SecondLayerErrorOptions, SecondLayerOptions, SinkTx, StackingEnvelope, StackingListParams, StackingWalkParams, StandardWebhooksHeaders2 as StandardWebhooksHeaders, StreamsBatch, StreamsBatchContext, StreamsCanonicalBlock, StreamsClient, StreamsConsumeParams, StreamsDumpFile, StreamsDumps, StreamsDumpsManifest, StreamsEvent, StreamsEventPayload, StreamsEventType, StreamsEventsConsumeParams, StreamsEventsConsumeResult, StreamsEventsEnvelope, StreamsEventsListEnvelope, StreamsEventsListParams, StreamsEventsStreamParams, StreamsEventsSubscribeParams, StreamsReorg, StreamsReorgContext, StreamsReorgsListEnvelope, StreamsReorgsListParams, StreamsServerError, StreamsSignatureError, StreamsSubscription, StreamsTip, StreamsWireEvent2 as StreamsWireEvent, SubgraphAgentSchema3 as SubgraphAgentSchema, SubgraphOperationStatus, SubgraphSpecFormat2 as SubgraphSpecFormat, SubgraphSpecOptions3 as SubgraphSpecOptions, Subgraphs, TransactionEnvelope, TransactionProof, TransactionProofVerifyResult, TransactionsEnvelope, TransactionsListParams, TransactionsWalkParams, UpdateWebhookRequest2 as UpdateWebhookRequest, ValidationError, VmStreamsEvent, WalkOptions, WebhookDetail2 as WebhookDetail, WebhookFormat, WebhookHeaderInput, WebhookKind, WebhookRuntime, WebhookStatus, WebhookSummary2 as WebhookSummary, WebhookTestResult2 as WebhookTestResult, Webhooks, WithSinkTx, buildDoctorReport, buildListIssue, consumeIndexFeed, consumerHealth, contextField, createArchiveClient, createStreamsClient, decode, decodeChainWebhook, decodeClarityValue, decodeFtBurn, decodeFtMint, decodeFtTransfer, decodeNftBurn, decodeNftMint, decodeNftTransfer, decodePrint, decodeStxBurn, decodeStxLock, decodeStxMint, decodeStxTransfer, fetchRewardSet, getSubgraph, isFtBurn, isFtMint, isFtTransfer, isNftBurn, isNftMint, isNftTransfer, isPrint, isStxBurn, isStxLock, isStxMint, isStxTransfer, isSuccessDelivery, parseRetryAfter, resolveAccountKey, resolveApiKey, resolveBaseUrl, shutdownSignal, toJsonSafe, trigger, verifySecondlayerSignature, verify as verifyStandardWebhooksHeaders, verifyTransactionProof, verifyWebhookSignature };

package/dist/index.js

@@ -970,7 +970,10 @@ async function consumeStreamsEvents(opts) {
       if (mode === "bounded") {
         return { cursor, pages, emptyPolls };
       }
-      await sleep(emptyBackoffMs, opts.signal);
+      await (opts.wake ? Promise.race([
+        sleep(emptyBackoffMs, opts.signal),
+        opts.wake().catch(() => new Promise(() => {}))
+      ]) : sleep(emptyBackoffMs, opts.signal));
       continue;
     }
     return { cursor, pages, emptyPolls };
@@ -2117,7 +2120,8 @@ function createStreamsClient(options) {
       signal: params.signal,
       retryCount: params.retryCount,
       retryDelay: params.retryDelay,
-      onError: params.onError
+      onError: params.onError,
+      wake: params.wake
     });
   }
   return {
@@ -2670,6 +2674,229 @@ function getSubgraph(def, options = {}) {
 function isSuccessDelivery(row) {
   return row.statusCode !== null && row.statusCode >= 200 && row.statusCode < 300;
 }
+var RATE_LIMITED_MIN_ATTEMPTS = 10;
+var RATE_LIMITED_MIN_RATIO = 0.5;
+var DOWN_MIN_CONSECUTIVE = 5;
+var REJECTS_MIN_CONSECUTIVE = 5;
+var SLOW_WINDOW = 20;
+var SLOW_MIN_SAMPLES = 5;
+var SLOW_TIMEOUT_RATIO = 0.5;
+var LAG_WINDOW = 20;
+var LAG_MIN_SAMPLES = 5;
+var LAG_THRESHOLD_MS = 60000;
+var ERROR_SNIPPET_MAX = 200;
+function median(values) {
+  if (values.length === 0)
+    return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.floor(sorted.length / 2)] ?? 0;
+}
+function percentile(values, p) {
+  if (values.length === 0)
+    return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  const idx = Math.min(sorted.length - 1, Math.floor(p * sorted.length));
+  return sorted[idx] ?? 0;
+}
+function formatMs(ms) {
+  return ms >= 1000 ? `${(ms / 1000).toFixed(1)}s` : `${Math.round(ms)}ms`;
+}
+function formatShortDate(iso) {
+  return `${iso.slice(0, 10)} ${iso.slice(11, 16)} UTC`;
+}
+function consecutiveFromStart(rows, predicate) {
+  const out = [];
+  for (const row of rows) {
+    if (!predicate(row))
+      break;
+    out.push(row);
+  }
+  return out;
+}
+function summarizeStatusBreakdown(rows) {
+  const counts = new Map;
+  for (const row of rows) {
+    const key = row.statusCode === null ? "timeout/no response" : String(row.statusCode);
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  return [...counts.entries()].map(([key, n]) => `${n}× ${key}`).join(", ");
+}
+var RETRY_AFTER_RE = /retry-after:?\s*(\d+)/i;
+function extractRetryAfterSeconds(rows) {
+  for (const row of rows) {
+    if (row.statusCode !== 429 || !row.errorMessage)
+      continue;
+    const match = row.errorMessage.match(RETRY_AFTER_RE);
+    if (match?.[1])
+      return match[1];
+  }
+  return null;
+}
+function detectReceiverRateLimited(webhook, deliveries) {
+  if (deliveries.length < RATE_LIMITED_MIN_ATTEMPTS)
+    return null;
+  const count429 = deliveries.filter((d) => d.statusCode === 429).length;
+  if (count429 / deliveries.length < RATE_LIMITED_MIN_RATIO)
+    return null;
+  const oldest = deliveries[deliveries.length - 1];
+  const newest = deliveries[0];
+  const evidence = [
+    {
+      label: "429 responses",
+      value: `${count429} of ${deliveries.length} attempts`
+    },
+    {
+      label: "window",
+      value: oldest && newest ? `${formatShortDate(oldest.dispatchedAt)} → ${formatShortDate(newest.dispatchedAt)}` : "unknown"
+    }
+  ];
+  const retryAfter = extractRetryAfterSeconds(deliveries);
+  if (retryAfter) {
+    evidence.push({ label: "latest Retry-After", value: `${retryAfter}s` });
+  }
+  const suggestedConcurrency = Math.max(1, Math.floor(webhook.concurrency / 2));
+  return {
+    code: "receiver_rate_limited",
+    severity: "warn",
+    evidence,
+    fix: {
+      text: "Lower concurrency, or honor the Retry-After header on your receiver.",
+      command: `secondlayer webhooks update ${webhook.id} --concurrency ${suggestedConcurrency}`,
+      docsPath: "/docs/webhooks#receiver-rate-limited"
+    }
+  };
+}
+function detectReceiverDown(webhook, deliveries) {
+  const streak = consecutiveFromStart(deliveries, (d) => d.statusCode === null || d.statusCode >= 500);
+  if (streak.length < DOWN_MIN_CONSECUTIVE)
+    return null;
+  return {
+    code: "receiver_down",
+    severity: "bad",
+    evidence: [
+      { label: "consecutive failures", value: String(streak.length) },
+      { label: "breakdown", value: summarizeStatusBreakdown(streak) },
+      {
+        label: "last success",
+        value: webhook.lastSuccessAt ? formatShortDate(webhook.lastSuccessAt) : "never"
+      }
+    ],
+    fix: {
+      text: "Check your receiver's health and logs, then send a test event.",
+      command: `secondlayer webhooks test ${webhook.id}`,
+      docsPath: "/docs/webhooks#receiver-down"
+    }
+  };
+}
+function detectReceiverRejects(webhook, deliveries) {
+  const streak = consecutiveFromStart(deliveries, (d) => d.statusCode !== null && d.statusCode >= 400 && d.statusCode < 500 && d.statusCode !== 429);
+  if (streak.length < REJECTS_MIN_CONSECUTIVE)
+    return null;
+  const evidence = [
+    { label: "consecutive rejects", value: String(streak.length) },
+    { label: "breakdown", value: summarizeStatusBreakdown(streak) }
+  ];
+  const withText = streak.find((d) => d.errorMessage || d.responseBody);
+  const snippet = withText ? (withText.errorMessage ?? withText.responseBody ?? "").slice(0, ERROR_SNIPPET_MAX) : null;
+  if (snippet)
+    evidence.push({ label: "first error", value: snippet });
+  return {
+    code: "receiver_rejects",
+    severity: "bad",
+    evidence,
+    fix: {
+      text: "Check your receiver's auth config or signature verification.",
+      command: `secondlayer webhooks test ${webhook.id}`,
+      docsPath: "/docs/webhooks#receiver-rejects"
+    }
+  };
+}
+function detectReceiverSlow(webhook, deliveries) {
+  const durations = deliveries.slice(0, SLOW_WINDOW).map((d) => d.durationMs).filter((d) => d !== null);
+  if (durations.length < SLOW_MIN_SAMPLES)
+    return null;
+  const med = median(durations);
+  if (med < webhook.timeoutMs * SLOW_TIMEOUT_RATIO)
+    return null;
+  return {
+    code: "receiver_slow",
+    severity: "warn",
+    evidence: [
+      { label: "median response time", value: formatMs(med) },
+      {
+        label: "p95 response time",
+        value: formatMs(percentile(durations, 0.95))
+      },
+      { label: "timeout", value: formatMs(webhook.timeoutMs) }
+    ],
+    fix: {
+      text: "Speed up your receiver, or raise the timeout (up to 30s hosted).",
+      command: `secondlayer webhooks update ${webhook.id} --timeout-ms 30000`,
+      docsPath: "/docs/webhooks#receiver-slow"
+    }
+  };
+}
+function detectDeliveryLag(deliveries) {
+  const window = deliveries.slice(0, LAG_WINDOW).filter((d) => d.blockTime !== null);
+  if (window.length < LAG_MIN_SAMPLES)
+    return null;
+  const lags = window.map((d) => new Date(d.dispatchedAt).getTime() - new Date(d.blockTime).getTime());
+  const med = median(lags);
+  if (med <= LAG_THRESHOLD_MS)
+    return null;
+  const blockTimes = window.map((d) => d.blockTime).sort();
+  const oldest = blockTimes[0];
+  const newest = blockTimes[blockTimes.length - 1];
+  return {
+    code: "delivery_lag",
+    severity: "warn",
+    evidence: [
+      { label: "median lag", value: formatMs(med) },
+      {
+        label: "block time range",
+        value: oldest && newest ? `${formatShortDate(oldest)} → ${formatShortDate(newest)}` : "unknown"
+      }
+    ],
+    fix: {
+      text: "We're behind on delivery; no action needed on your end."
+    }
+  };
+}
+var SEVERITY_RANK = {
+  bad: 0,
+  warn: 1,
+  calm: 2
+};
+var CODE_PRIORITY = [
+  "circuit",
+  "receiver_down",
+  "receiver_rejects",
+  "dead_letters",
+  "paused",
+  "last_error",
+  "warning",
+  "receiver_rate_limited",
+  "receiver_slow",
+  "delivery_lag",
+  "no_deliveries",
+  "subgraph_gaps",
+  "subgraph_catching_up"
+];
+function pickPrimary(issues) {
+  if (issues.length === 0)
+    return null;
+  return [...issues].sort((a, b) => {
+    const sevDiff = SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity];
+    if (sevDiff !== 0)
+      return sevDiff;
+    return CODE_PRIORITY.indexOf(a.code) - CODE_PRIORITY.indexOf(b.code);
+  })[0] ?? null;
+}
+function hintFor(issue) {
+  if (!issue.fix)
+    return issue.detail ?? issue.code;
+  return issue.fix.command ? `${issue.fix.text} ${issue.fix.command}` : issue.fix.text;
+}
 function buildDoctorReport(input) {
   const successful = input.deliveries.filter(isSuccessDelivery).length;
   const failed = input.deliveries.length - successful;
@@ -2686,35 +2913,60 @@ function buildDoctorReport(input) {
   const issues = [];
   if (input.webhook.warning) {
     hints.push(input.webhook.warning);
-    issues.push({ code: "warning", detail: input.webhook.warning });
+    issues.push({
+      code: "warning",
+      detail: input.webhook.warning,
+      severity: "warn"
+    });
   }
   if (input.webhook.status === "paused") {
     hints.push(`Resume when the receiver is healthy: secondlayer webhooks resume ${input.webhook.id}`);
-    issues.push({ code: "paused" });
+    issues.push({ code: "paused", severity: "warn" });
   }
   if (input.webhook.lastError) {
     hints.push("Run secondlayer webhooks test to reproduce the receiver request.");
-    issues.push({ code: "last_error", detail: input.webhook.lastError });
+    issues.push({
+      code: "last_error",
+      detail: input.webhook.lastError,
+      severity: "warn"
+    });
   }
   if (input.webhook.circuitOpenedAt || input.webhook.circuitFailures > 0) {
     hints.push("Circuit breaker has failures; inspect receiver logs and delivery status codes.");
-    issues.push({ code: "circuit" });
+    issues.push({ code: "circuit", severity: "bad" });
   }
   if (input.dead.length > 0) {
     hints.push(`Dead-letter rows exist; inspect with secondlayer webhooks dead ${input.webhook.id} and requeue selected rows.`);
-    issues.push({ code: "dead_letters" });
+    issues.push({ code: "dead_letters", severity: "bad" });
   }
   if (subgraph?.gapCount && subgraph.gapCount > 0) {
     hints.push(`Linked subgraph has gaps; run secondlayer subgraphs gaps ${input.webhook.subgraphName}.`);
-    issues.push({ code: "subgraph_gaps" });
+    issues.push({ code: "subgraph_gaps", severity: "calm" });
   }
   if (subgraph?.syncStatus === "catching_up") {
     hints.push("Linked subgraph is still catching up; new matching rows may arrive later.");
-    issues.push({ code: "subgraph_catching_up" });
+    issues.push({ code: "subgraph_catching_up", severity: "calm" });
+  }
+  for (const detector of [
+    detectReceiverRateLimited,
+    detectReceiverDown,
+    detectReceiverRejects,
+    detectReceiverSlow
+  ]) {
+    const issue = detector(input.webhook, input.deliveries);
+    if (issue) {
+      issues.push(issue);
+      hints.push(hintFor(issue));
+    }
+  }
+  const lagIssue = detectDeliveryLag(input.deliveries);
+  if (lagIssue) {
+    issues.push(lagIssue);
+    hints.push(hintFor(lagIssue));
   }
   if (input.deliveries.length === 0) {
     hints.push("No deliveries yet; confirm the table is receiving inserted rows that match the filter.");
-    issues.push({ code: "no_deliveries" });
+    issues.push({ code: "no_deliveries", severity: "calm" });
   }
   if (hints.length === 0) {
     hints.push("No immediate action needed.");
@@ -2730,9 +2982,35 @@ function buildDoctorReport(input) {
     deadCount: input.dead.length,
     subgraph,
     hints,
-    issues
+    issues,
+    primary: pickPrimary(issues)
   };
 }
+function buildListIssue(webhook) {
+  if (webhook.status !== "paused")
+    return null;
+  if (webhook.circuitOpenedAt) {
+    return {
+      code: "circuit",
+      severity: "bad",
+      evidence: [
+        {
+          label: "circuit opened",
+          value: formatShortDate(webhook.circuitOpenedAt)
+        },
+        {
+          label: "last success",
+          value: webhook.lastSuccessAt ? formatShortDate(webhook.lastSuccessAt) : "never"
+        }
+      ],
+      fix: {
+        text: "Check your receiver's health and logs, then send a test event.",
+        docsPath: "/docs/webhooks#receiver-down"
+      }
+    };
+  }
+  return { code: "paused", severity: "warn" };
+}
 // src/consumer-ops.ts
 function consumerHealth(options = {}) {
   const staleAfterMs = options.staleAfterMs ?? 120000;
@@ -2986,6 +3264,7 @@ export {
   ValidationError,
   Webhooks,
   buildDoctorReport,
+  buildListIssue,
   consumeIndexFeed,
   consumerHealth,
   contextField,
@@ -3032,5 +3311,5 @@ export {
   verifyWebhookSignature
 };
 
-//# debugId=AE812DACE82FC03C64756E2164756E21
+//# debugId=17DA719CAEA1958964756E2164756E21
 //# sourceMappingURL=index.js.map