feat: add monitor.activity endpoint and update examples

- Add ApiMonitorTickStatus, ApiMonitorTickEntry, ApiMonitorActivityResponse types
- Add monitor.activity(id, params?) method for paginated tick history
- Update monitor examples to poll activity and display diffs
- Track seen ticks to avoid duplicate output
- Use throw for proper TypeScript type narrowing

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: FrancescoSaverioZuppichini

examples/monitor/monitor_basic.ts

@@ -1,19 +1,62 @@
 import { ScrapeGraphAI } from "scrapegraph-js";
 
-// reads SGAI_API_KEY from env, or pass explicitly: ScrapeGraphAI({ apiKey: "..." })
 const sgai = ScrapeGraphAI();
 
 const res = await sgai.monitor.create({
-	url: "https://example.com",
-	name: "Example Monitor",
-	interval: "0 * * * *",
-	formats: [{ type: "markdown" }],
+	url: "https://time.is/",
+	name: "Time Monitor",
+	interval: "*/10 * * * *",
+	formats: [
+		{
+			type: "json",
+			prompt: "Extract the current time",
+			schema: {
+				type: "object",
+				properties: {
+					time: { type: "string" },
+				},
+				required: ["time"],
+			},
+		},
+	],
 });
 
-if (res.status === "success") {
-	console.log("Monitor created:", res.data?.cronId);
-	console.log("Status:", res.data?.status);
-	console.log("Interval:", res.data?.interval);
-} else {
-	console.error("Failed:", res.error);
+if (res.status !== "success" || !res.data) {
+	throw new Error(`Failed to create monitor: ${res.error}`);
+}
+
+const { cronId: monitorId, interval } = res.data;
+console.log(`Monitor created: ${monitorId}`);
+console.log(`Interval: ${interval}`);
+console.log("\nPolling for activity (Ctrl+C to stop)...\n");
+
+function cleanup() {
+	console.log("\nStopping monitor...");
+	sgai.monitor.delete(monitorId).then(() => {
+		console.log("Monitor deleted");
+		process.exit(0);
+	});
+}
+
+process.on("SIGINT", cleanup);
+
+const seenIds = new Set<string>();
+
+while (true) {
+	const activity = await sgai.monitor.activity(monitorId);
+	if (activity.status === "success" && activity.data) {
+		for (const tick of activity.data.ticks) {
+			if (seenIds.has(tick.id)) continue;
+			seenIds.add(tick.id);
+
+			const changes = tick.changed ? "CHANGED" : "no change";
+			console.log(`[${tick.createdAt}] ${tick.status} - ${changes} (${tick.elapsedMs}ms)`);
+			if (tick.diffs && Object.keys(tick.diffs).length > 0) {
+				console.log("  Diffs:", JSON.stringify(tick.diffs, null, 2));
+			} else if (tick.changed) {
+				console.log("  (no diffs data)");
+			}
+		}
+	}
+	await new Promise((r) => setTimeout(r, 30000));
 }

examples/monitor/monitor_with_webhook.ts

@@ -1,22 +1,66 @@
 import { ScrapeGraphAI } from "scrapegraph-js";
 
-// reads SGAI_API_KEY from env, or pass explicitly: ScrapeGraphAI({ apiKey: "..." })
 const sgai = ScrapeGraphAI();
 
 const res = await sgai.monitor.create({
-	url: "https://example.com/prices",
-	name: "Price Monitor",
-	interval: "0 */6 * * *",
+	url: "https://time.is/",
+	name: "Time Monitor with Webhook",
+	interval: "*/10 * * * *",
 	formats: [
 		{ type: "markdown" },
-		{ type: "json", prompt: "Extract all product prices" },
+		{
+			type: "json",
+			prompt: "Extract the current time and timezone",
+			schema: {
+				type: "object",
+				properties: {
+					time: { type: "string" },
+					timezone: { type: "string" },
+				},
+				required: ["time"],
+			},
+		},
 	],
 	webhookUrl: "https://your-server.com/webhook",
 });
 
-if (res.status === "success") {
-	console.log("Monitor created:", res.data?.cronId);
-	console.log("Will notify:", res.data?.config.webhookUrl);
-} else {
-	console.error("Failed:", res.error);
+if (res.status !== "success" || !res.data) {
+	throw new Error(`Failed to create monitor: ${res.error}`);
+}
+
+const { cronId: monitorId, interval, config } = res.data;
+console.log(`Monitor created: ${monitorId}`);
+console.log(`Interval: ${interval}`);
+console.log(`Webhook: ${config.webhookUrl}`);
+console.log("\nPolling for activity (Ctrl+C to stop)...\n");
+
+function cleanup() {
+	console.log("\nStopping monitor...");
+	sgai.monitor.delete(monitorId).then(() => {
+		console.log("Monitor deleted");
+		process.exit(0);
+	});
+}
+
+process.on("SIGINT", cleanup);
+
+const seenIds = new Set<string>();
+
+while (true) {
+	const activity = await sgai.monitor.activity(monitorId);
+	if (activity.status === "success" && activity.data) {
+		for (const tick of activity.data.ticks) {
+			if (seenIds.has(tick.id)) continue;
+			seenIds.add(tick.id);
+
+			const changes = tick.changed ? "CHANGED" : "no change";
+			console.log(`[${tick.createdAt}] ${tick.status} - ${changes} (${tick.elapsedMs}ms)`);
+			if (tick.diffs && Object.keys(tick.diffs).length > 0) {
+				console.log("  Diffs:", JSON.stringify(tick.diffs, null, 2));
+			} else if (tick.changed) {
+				console.log("  (no diffs data - first tick establishes baseline)");
+			}
+		}
+	}
+	await new Promise((r) => setTimeout(r, 30000));
 }

src/index.ts

@@ -37,6 +37,10 @@ export type {
 	ApiMonitorResponse,
 	ApiMonitorResult,
 	ApiMonitorDiffs,
+	ApiMonitorActivityParams,
+	ApiMonitorActivityResponse,
+	ApiMonitorTickEntry,
+	ApiMonitorTickStatus,
 	ApiHistoryFilter,
 	ApiHistoryEntry,
 	ApiHistoryPage,

src/scrapegraphai.ts

@@ -9,6 +9,8 @@ import type {
 	ApiHistoryEntry,
 	ApiHistoryFilter,
 	ApiHistoryPage,
+	ApiMonitorActivityParams,
+	ApiMonitorActivityResponse,
 	ApiMonitorCreateInput,
 	ApiMonitorResponse,
 	ApiMonitorUpdateInput,
@@ -342,6 +344,24 @@ export const monitor = {
 			return fail(err);
 		}
 	},
+
+	async activity(
+		apiKey: string,
+		id: string,
+		params?: ApiMonitorActivityParams,
+	): Promise<ApiResult<ApiMonitorActivityResponse>> {
+		try {
+			const qs = new URLSearchParams();
+			if (params?.limit) qs.set("limit", String(params.limit));
+			if (params?.cursor) qs.set("cursor", params.cursor);
+			const query = qs.toString();
+			const path = query ? `/monitor/${id}/activity?${query}` : `/monitor/${id}/activity`;
+			const { data, elapsedMs } = await request<ApiMonitorActivityResponse>("GET", path, apiKey);
+			return ok(data, elapsedMs);
+		} catch (err) {
+			return fail(err);
+		}
+	},
 };
 
 export interface ScrapeGraphAIInput {
@@ -381,6 +401,8 @@ export function ScrapeGraphAI(opts?: ScrapeGraphAIInput) {
 			delete: (id: string) => monitor.delete(key, id),
 			pause: (id: string) => monitor.pause(key, id),
 			resume: (id: string) => monitor.resume(key, id),
+			activity: (id: string, params?: ApiMonitorActivityParams) =>
+				monitor.activity(key, id, params),
 		},
 	};
 }

src/types.ts

@@ -298,6 +298,28 @@ export interface ApiMonitorResponse {
 	updatedAt: string;
 }
 
+export type ApiMonitorTickStatus = "completed" | "failed" | "paused" | "running";
+
+export interface ApiMonitorTickEntry {
+	id: string;
+	status: ApiMonitorTickStatus;
+	createdAt: string;
+	elapsedMs: number;
+	changed: boolean;
+	diffs: ApiMonitorDiffs;
+	error?: string;
+}
+
+export interface ApiMonitorActivityResponse {
+	ticks: ApiMonitorTickEntry[];
+	nextCursor: string | null;
+}
+
+export interface ApiMonitorActivityParams {
+	limit?: number;
+	cursor?: string;
+}
+
 export type ApiHistoryService = "scrape" | "extract" | "search" | "monitor" | "crawl";
 export type ApiHistoryStatus = "completed" | "failed" | "running" | "paused" | "deleted";