@secondlayer/sdk 12.0.0 → 12.2.0

package/dist/webhooks/doctor.d.ts

@@ -0,0 +1,42 @@
+import { SubgraphDetail } from "@secondlayer/shared/schemas/subgraphs";
+import { DeadRow, DeliveryRow, WebhookDetail } 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.
+*/
+declare function isSuccessDelivery(row: DeliveryRow): boolean;
+type DoctorIssueCode = "warning" | "paused" | "last_error" | "circuit" | "dead_letters" | "subgraph_gaps" | "subgraph_catching_up" | "no_deliveries";
+interface DoctorIssue {
+	code: DoctorIssueCode;
+	detail?: string;
+}
+interface DoctorReport {
+	webhook: WebhookDetail;
+	deliverySummary: {
+		total: number;
+		successful: number;
+		failed: number;
+		last: DeliveryRow | null;
+	};
+	deadCount: number;
+	subgraph: {
+		name: string;
+		status: string;
+		syncStatus: string;
+		lastProcessedBlock: number;
+		chainTip: number;
+		gapCount: number;
+		integrity: string;
+	} | null;
+	/** CLI-facing next steps, one per issue, in the same order as `issues`. */
+	hints: string[];
+	issues: DoctorIssue[];
+}
+declare function buildDoctorReport(input: {
+	webhook: WebhookDetail;
+	deliveries: DeliveryRow[];
+	dead: DeadRow[];
+	subgraph?: SubgraphDetail | null;
+}): DoctorReport;
+export { DoctorIssue, DoctorIssueCode, DoctorReport, buildDoctorReport, isSuccessDelivery };

package/dist/webhooks/doctor.js

@@ -0,0 +1,74 @@
+// src/webhooks/doctor.ts
+function isSuccessDelivery(row) {
+  return row.statusCode !== null && row.statusCode >= 200 && row.statusCode < 300;
+}
+function buildDoctorReport(input) {
+  const successful = input.deliveries.filter(isSuccessDelivery).length;
+  const failed = input.deliveries.length - successful;
+  const subgraph = input.subgraph ? {
+    name: input.subgraph.name,
+    status: input.subgraph.status,
+    syncStatus: input.subgraph.sync.status,
+    lastProcessedBlock: input.subgraph.sync.lastProcessedBlock,
+    chainTip: input.subgraph.sync.chainTip,
+    gapCount: input.subgraph.sync.gaps.count,
+    integrity: input.subgraph.sync.integrity
+  } : null;
+  const hints = [];
+  const issues = [];
+  if (input.webhook.warning) {
+    hints.push(input.webhook.warning);
+    issues.push({ code: "warning", detail: input.webhook.warning });
+  }
+  if (input.webhook.status === "paused") {
+    hints.push(`Resume when the receiver is healthy: secondlayer webhooks resume ${input.webhook.id}`);
+    issues.push({ code: "paused" });
+  }
+  if (input.webhook.lastError) {
+    hints.push("Run secondlayer webhooks test to reproduce the receiver request.");
+    issues.push({ code: "last_error", detail: input.webhook.lastError });
+  }
+  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" });
+  }
+  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" });
+  }
+  if (subgraph?.gapCount && subgraph.gapCount > 0) {
+    hints.push(`Linked subgraph has gaps; run secondlayer subgraphs gaps ${input.webhook.subgraphName}.`);
+    issues.push({ code: "subgraph_gaps" });
+  }
+  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" });
+  }
+  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" });
+  }
+  if (hints.length === 0) {
+    hints.push("No immediate action needed.");
+  }
+  return {
+    webhook: input.webhook,
+    deliverySummary: {
+      total: input.deliveries.length,
+      successful,
+      failed,
+      last: input.deliveries[0] ?? null
+    },
+    deadCount: input.dead.length,
+    subgraph,
+    hints,
+    issues
+  };
+}
+export {
+  buildDoctorReport,
+  isSuccessDelivery
+};
+
+//# debugId=2B12BAB34B7CE6B164756E2164756E21
+//# sourceMappingURL=doctor.js.map

package/dist/webhooks/doctor.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["src/webhooks/doctor.ts"],
+  "sourcesContent": [
+    "import type { SubgraphDetail } from \"@secondlayer/shared/schemas/subgraphs\";\nimport type {\n\tDeadRow,\n\tDeliveryRow,\n\tWebhookDetail,\n} from \"@secondlayer/shared/schemas/webhooks\";\n\n/**\n * Webhook diagnosis, shared by `secondlayer webhooks doctor` and the\n * dashboard's webhook detail page. Moved out of the CLI (unchanged behavior)\n * so the web can build the same judgment without printing CLI-command text.\n */\n\nexport function isSuccessDelivery(row: DeliveryRow): boolean {\n\treturn (\n\t\trow.statusCode !== null && row.statusCode >= 200 && row.statusCode < 300\n\t);\n}\n\nexport type DoctorIssueCode =\n\t| \"warning\"\n\t| \"paused\"\n\t| \"last_error\"\n\t| \"circuit\"\n\t| \"dead_letters\"\n\t| \"subgraph_gaps\"\n\t| \"subgraph_catching_up\"\n\t| \"no_deliveries\";\n\nexport interface DoctorIssue {\n\tcode: DoctorIssueCode;\n\tdetail?: string;\n}\n\nexport interface DoctorReport {\n\twebhook: WebhookDetail;\n\tdeliverySummary: {\n\t\ttotal: number;\n\t\tsuccessful: number;\n\t\tfailed: number;\n\t\tlast: DeliveryRow | null;\n\t};\n\tdeadCount: number;\n\tsubgraph: {\n\t\tname: string;\n\t\tstatus: string;\n\t\tsyncStatus: string;\n\t\tlastProcessedBlock: number;\n\t\tchainTip: number;\n\t\tgapCount: number;\n\t\tintegrity: string;\n\t} | null;\n\t/** CLI-facing next steps, one per issue, in the same order as `issues`. */\n\thints: string[];\n\tissues: DoctorIssue[];\n}\n\nexport function buildDoctorReport(input: {\n\twebhook: WebhookDetail;\n\tdeliveries: DeliveryRow[];\n\tdead: DeadRow[];\n\tsubgraph?: SubgraphDetail | null;\n}): DoctorReport {\n\tconst successful = input.deliveries.filter(isSuccessDelivery).length;\n\tconst failed = input.deliveries.length - successful;\n\tconst subgraph = input.subgraph\n\t\t? {\n\t\t\t\tname: input.subgraph.name,\n\t\t\t\tstatus: input.subgraph.status,\n\t\t\t\tsyncStatus: input.subgraph.sync.status,\n\t\t\t\tlastProcessedBlock: input.subgraph.sync.lastProcessedBlock,\n\t\t\t\tchainTip: input.subgraph.sync.chainTip,\n\t\t\t\tgapCount: input.subgraph.sync.gaps.count,\n\t\t\t\tintegrity: input.subgraph.sync.integrity,\n\t\t\t}\n\t\t: null;\n\n\tconst hints: string[] = [];\n\tconst issues: DoctorIssue[] = [];\n\tif (input.webhook.warning) {\n\t\thints.push(input.webhook.warning);\n\t\tissues.push({ code: \"warning\", detail: input.webhook.warning });\n\t}\n\tif (input.webhook.status === \"paused\") {\n\t\thints.push(\n\t\t\t`Resume when the receiver is healthy: secondlayer webhooks resume ${input.webhook.id}`,\n\t\t);\n\t\tissues.push({ code: \"paused\" });\n\t}\n\tif (input.webhook.lastError) {\n\t\thints.push(\n\t\t\t\"Run secondlayer webhooks test to reproduce the receiver request.\",\n\t\t);\n\t\tissues.push({ code: \"last_error\", detail: input.webhook.lastError });\n\t}\n\tif (input.webhook.circuitOpenedAt || input.webhook.circuitFailures > 0) {\n\t\thints.push(\n\t\t\t\"Circuit breaker has failures; inspect receiver logs and delivery status codes.\",\n\t\t);\n\t\tissues.push({ code: \"circuit\" });\n\t}\n\tif (input.dead.length > 0) {\n\t\thints.push(\n\t\t\t`Dead-letter rows exist; inspect with secondlayer webhooks dead ${input.webhook.id} and requeue selected rows.`,\n\t\t);\n\t\tissues.push({ code: \"dead_letters\" });\n\t}\n\tif (subgraph?.gapCount && subgraph.gapCount > 0) {\n\t\thints.push(\n\t\t\t`Linked subgraph has gaps; run secondlayer subgraphs gaps ${input.webhook.subgraphName}.`,\n\t\t);\n\t\tissues.push({ code: \"subgraph_gaps\" });\n\t}\n\tif (subgraph?.syncStatus === \"catching_up\") {\n\t\thints.push(\n\t\t\t\"Linked subgraph is still catching up; new matching rows may arrive later.\",\n\t\t);\n\t\tissues.push({ code: \"subgraph_catching_up\" });\n\t}\n\tif (input.deliveries.length === 0) {\n\t\thints.push(\n\t\t\t\"No deliveries yet; confirm the table is receiving inserted rows that match the filter.\",\n\t\t);\n\t\tissues.push({ code: \"no_deliveries\" });\n\t}\n\tif (hints.length === 0) {\n\t\thints.push(\"No immediate action needed.\");\n\t}\n\n\treturn {\n\t\twebhook: input.webhook,\n\t\tdeliverySummary: {\n\t\t\ttotal: input.deliveries.length,\n\t\t\tsuccessful,\n\t\t\tfailed,\n\t\t\tlast: input.deliveries[0] ?? null,\n\t\t},\n\t\tdeadCount: input.dead.length,\n\t\tsubgraph,\n\t\thints,\n\t\tissues,\n\t};\n}\n"
+  ],
+  "mappings": ";AAaO,SAAS,iBAAiB,CAAC,KAA2B;AAAA,EAC5D,OACC,IAAI,eAAe,QAAQ,IAAI,cAAc,OAAO,IAAI,aAAa;AAAA;AA0ChE,SAAS,iBAAiB,CAAC,OAKjB;AAAA,EAChB,MAAM,aAAa,MAAM,WAAW,OAAO,iBAAiB,EAAE;AAAA,EAC9D,MAAM,SAAS,MAAM,WAAW,SAAS;AAAA,EACzC,MAAM,WAAW,MAAM,WACpB;AAAA,IACA,MAAM,MAAM,SAAS;AAAA,IACrB,QAAQ,MAAM,SAAS;AAAA,IACvB,YAAY,MAAM,SAAS,KAAK;AAAA,IAChC,oBAAoB,MAAM,SAAS,KAAK;AAAA,IACxC,UAAU,MAAM,SAAS,KAAK;AAAA,IAC9B,UAAU,MAAM,SAAS,KAAK,KAAK;AAAA,IACnC,WAAW,MAAM,SAAS,KAAK;AAAA,EAChC,IACC;AAAA,EAEH,MAAM,QAAkB,CAAC;AAAA,EACzB,MAAM,SAAwB,CAAC;AAAA,EAC/B,IAAI,MAAM,QAAQ,SAAS;AAAA,IAC1B,MAAM,KAAK,MAAM,QAAQ,OAAO;AAAA,IAChC,OAAO,KAAK,EAAE,MAAM,WAAW,QAAQ,MAAM,QAAQ,QAAQ,CAAC;AAAA,EAC/D;AAAA,EACA,IAAI,MAAM,QAAQ,WAAW,UAAU;AAAA,IACtC,MAAM,KACL,oEAAoE,MAAM,QAAQ,IACnF;AAAA,IACA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAAA,EAC/B;AAAA,EACA,IAAI,MAAM,QAAQ,WAAW;AAAA,IAC5B,MAAM,KACL,kEACD;AAAA,IACA,OAAO,KAAK,EAAE,MAAM,cAAc,QAAQ,MAAM,QAAQ,UAAU,CAAC;AAAA,EACpE;AAAA,EACA,IAAI,MAAM,QAAQ,mBAAmB,MAAM,QAAQ,kBAAkB,GAAG;AAAA,IACvE,MAAM,KACL,gFACD;AAAA,IACA,OAAO,KAAK,EAAE,MAAM,UAAU,CAAC;AAAA,EAChC;AAAA,EACA,IAAI,MAAM,KAAK,SAAS,GAAG;AAAA,IAC1B,MAAM,KACL,kEAAkE,MAAM,QAAQ,+BACjF;AAAA,IACA,OAAO,KAAK,EAAE,MAAM,eAAe,CAAC;AAAA,EACrC;AAAA,EACA,IAAI,UAAU,YAAY,SAAS,WAAW,GAAG;AAAA,IAChD,MAAM,KACL,4DAA4D,MAAM,QAAQ,eAC3E;AAAA,IACA,OAAO,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAAA,EACtC;AAAA,EACA,IAAI,UAAU,eAAe,eAAe;AAAA,IAC3C,MAAM,KACL,2EACD;AAAA,IACA,OAAO,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAAA,EAC7C;AAAA,EACA,IAAI,MAAM,WAAW,WAAW,GAAG;AAAA,IAClC,MAAM,KACL,wFACD;AAAA,IACA,OAAO,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAAA,EACtC;AAAA,EACA,IAAI,MAAM,WAAW,GAAG;AAAA,IACvB,MAAM,KAAK,6BAA6B;AAAA,EACzC;AAAA,EAEA,OAAO;AAAA,IACN,SAAS,MAAM;AAAA,IACf,iBAAiB;AAAA,MAChB,OAAO,MAAM,WAAW;AAAA,MACxB;AAAA,MACA;AAAA,MACA,MAAM,MAAM,WAAW,MAAM;AAAA,IAC9B;AAAA,IACA,WAAW,MAAM,KAAK;AAAA,IACtB;AAAA,IACA;AAAA,IACA;AAAA,EACD;AAAA;",
+  "debugId": "2B12BAB34B7CE6B164756E2164756E21",
+  "names": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@secondlayer/sdk",
-	"version": "12.0.0",
+	"version": "12.2.0",
 	"description": "Decoded Stacks data in your own database — stream rows into your schema, or query the tables you defined.",
 	"license": "MIT",
 	"repository": {
@@ -48,6 +48,10 @@
 		"./sinks/testing": {
 			"types": "./dist/sinks/testing.d.ts",
 			"import": "./dist/sinks/testing.js"
+		},
+		"./webhooks/doctor": {
+			"types": "./dist/webhooks/doctor.d.ts",
+			"import": "./dist/webhooks/doctor.js"
 		}
 	},
 	"files": ["dist", "AGENTS.md"],
@@ -60,9 +64,9 @@
 		"prepublishOnly": "bun run build"
 	},
 	"dependencies": {
-		"@secondlayer/shared": "^11.10.1",
+		"@secondlayer/shared": "^11.11.0",
 		"@secondlayer/stacks": "^6.1.0",
-		"@secondlayer/subgraphs": "^6.0.0"
+		"@secondlayer/subgraphs": "^6.2.0"
 	},
 	"devDependencies": {
 		"@openpkg-ts/cli": "^0.11.3",