feat: replace render/stealth booleans with unified fetch mode enum

Aligns fetchConfig with sgai-stack development branch contract:
- mode: "auto" | "fast" | "js" | "direct+stealth" | "js+stealth"
- Removes render and stealth boolean fields
- Updates timeout range to 1000-60000ms (default 30000)
- Adds SGAI-APIKEY header to all requests
- Fixes API URL paths (/v2 → /api/v2)
- Exports ApiFetchMode type

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: VinciGit00

src/client.ts

@@ -30,7 +30,7 @@ export function scrapegraphai(config: ClientConfig) {
 		async scrape(url: string, scrapeOptions?: ApiScrapeOptions, requestOptions?: RequestOptions) {
 			return request(
 				"POST",
-				buildUrl("/v2/scrape"),
+				buildUrl("/api/v2/scrape"),
 				key,
 				{ url, ...scrapeOptions },
 				mergeRequestOptions(requestOptions),
@@ -46,7 +46,7 @@ export function scrapegraphai(config: ClientConfig) {
 			if (extractOptions.fetchConfig) body.fetchConfig = extractOptions.fetchConfig;
 			return request(
 				"POST",
-				buildUrl("/v2/extract"),
+				buildUrl("/api/v2/extract"),
 				key,
 				body,
 				mergeRequestOptions(requestOptions),
@@ -56,7 +56,7 @@ export function scrapegraphai(config: ClientConfig) {
 		async search(query: string, searchOptions?: ApiSearchOptions, requestOptions?: RequestOptions) {
 			return request(
 				"POST",
-				buildUrl("/v2/search"),
+				buildUrl("/api/v2/search"),
 				key,
 				{ query, ...searchOptions },
 				mergeRequestOptions(requestOptions),
@@ -66,7 +66,7 @@ export function scrapegraphai(config: ClientConfig) {
 		async credits(requestOptions?: RequestOptions) {
 			return request(
 				"GET",
-				buildUrl("/v2/credits"),
+				buildUrl("/api/v2/credits"),
 				key,
 				undefined,
 				mergeRequestOptions(requestOptions),
@@ -81,7 +81,7 @@ export function scrapegraphai(config: ClientConfig) {
 			const query = qs.toString();
 			return request(
 				"GET",
-				buildUrl(`/v2/history${query ? `?${query}` : ""}`),
+				buildUrl(`/api/v2/history${query ? `?${query}` : ""}`),
 				key,
 				undefined,
 				mergeRequestOptions(requestOptions),
@@ -92,7 +92,7 @@ export function scrapegraphai(config: ClientConfig) {
 			async start(url: string, crawlOptions?: ApiCrawlOptions, requestOptions?: RequestOptions) {
 				return request(
 					"POST",
-					buildUrl("/v2/crawl"),
+					buildUrl("/api/v2/crawl"),
 					key,
 					{ url, ...crawlOptions },
 					mergeRequestOptions(requestOptions),
@@ -102,7 +102,7 @@ export function scrapegraphai(config: ClientConfig) {
 			async status(id: string, requestOptions?: RequestOptions) {
 				return request(
 					"GET",
-					buildUrl(`/v2/crawl/${id}`),
+					buildUrl(`/api/v2/crawl/${id}`),
 					key,
 					undefined,
 					mergeRequestOptions(requestOptions),
@@ -112,7 +112,7 @@ export function scrapegraphai(config: ClientConfig) {
 			async stop(id: string, requestOptions?: RequestOptions) {
 				return request(
 					"POST",
-					buildUrl(`/v2/crawl/${id}/stop`),
+					buildUrl(`/api/v2/crawl/${id}/stop`),
 					key,
 					{},
 					mergeRequestOptions(requestOptions),
@@ -122,7 +122,7 @@ export function scrapegraphai(config: ClientConfig) {
 			async resume(id: string, requestOptions?: RequestOptions) {
 				return request(
 					"POST",
-					buildUrl(`/v2/crawl/${id}/resume`),
+					buildUrl(`/api/v2/crawl/${id}/resume`),
 					key,
 					{},
 					mergeRequestOptions(requestOptions),
@@ -134,7 +134,7 @@ export function scrapegraphai(config: ClientConfig) {
 			async create(monitorCreateInput: ApiMonitorCreateInput, requestOptions?: RequestOptions) {
 				return request(
 					"POST",
-					buildUrl("/v2/monitor"),
+					buildUrl("/api/v2/monitor"),
 					key,
 					{ ...monitorCreateInput },
 					mergeRequestOptions(requestOptions),
@@ -144,7 +144,7 @@ export function scrapegraphai(config: ClientConfig) {
 			async list(requestOptions?: RequestOptions) {
 				return request(
 					"GET",
-					buildUrl("/v2/monitor"),
+					buildUrl("/api/v2/monitor"),
 					key,
 					undefined,
 					mergeRequestOptions(requestOptions),
@@ -154,7 +154,7 @@ export function scrapegraphai(config: ClientConfig) {
 			async get(id: string, requestOptions?: RequestOptions) {
 				return request(
 					"GET",
-					buildUrl(`/v2/monitor/${id}`),
+					buildUrl(`/api/v2/monitor/${id}`),
 					key,
 					undefined,
 					mergeRequestOptions(requestOptions),
@@ -164,7 +164,7 @@ export function scrapegraphai(config: ClientConfig) {
 			async pause(id: string, requestOptions?: RequestOptions) {
 				return request(
 					"POST",
-					buildUrl(`/v2/monitor/${id}/pause`),
+					buildUrl(`/api/v2/monitor/${id}/pause`),
 					key,
 					{},
 					mergeRequestOptions(requestOptions),
@@ -174,7 +174,7 @@ export function scrapegraphai(config: ClientConfig) {
 			async resume(id: string, requestOptions?: RequestOptions) {
 				return request(
 					"POST",
-					buildUrl(`/v2/monitor/${id}/resume`),
+					buildUrl(`/api/v2/monitor/${id}/resume`),
 					key,
 					{},
 					mergeRequestOptions(requestOptions),
@@ -184,7 +184,7 @@ export function scrapegraphai(config: ClientConfig) {
 			async delete(id: string, requestOptions?: RequestOptions) {
 				return request(
 					"DELETE",
-					buildUrl(`/v2/monitor/${id}`),
+					buildUrl(`/api/v2/monitor/${id}`),
 					key,
 					undefined,
 					mergeRequestOptions(requestOptions),

src/http.ts

@@ -22,6 +22,7 @@ export async function request<T = unknown>(
 		try {
 			const headers: Record<string, string> = {
 				Authorization: `Bearer ${apiKey}`,
+				"SGAI-APIKEY": apiKey,
 				"X-SDK-Version": `js@${VERSION}`,
 			};
 			if (body) headers["Content-Type"] = "application/json";

src/index.ts

@@ -6,6 +6,7 @@ export type {
 	ApiExtractOptions,
 	ApiExtractRequestBase,
 	ApiFetchConfig,
+	ApiFetchMode,
 	ApiHistoryFilterInput,
 	ApiHistoryService,
 	ApiHtmlMode,

src/schemas.ts

@@ -32,6 +32,7 @@ export const apiFetchContentTypeSchema = z.enum([
 	"text/plain",
 	"application/x-latex",
 ]);
+export const apiFetchModeSchema = z.enum(["auto", "fast", "js", "direct+stealth", "js+stealth"]);
 export const apiUserPromptSchema = z.string().min(1).max(10_000);
 
 export const apiUrlSchema = z.url().check(
@@ -56,16 +57,15 @@ export const apiUuidParamSchema = z.object({
 });
 
 export const FETCH_CONFIG_DEFAULTS = {
-	timeout: 15000,
-	render: false,
+	mode: "auto",
+	timeout: 30000,
 	wait: 0,
-	stealth: false,
 	scrolls: 0,
 } as const;
 
 export const apiFetchConfigSchema = z.object({
-	timeout: z.number().int().min(1000).max(30000).default(FETCH_CONFIG_DEFAULTS.timeout),
-	render: z.boolean().default(FETCH_CONFIG_DEFAULTS.render),
+	mode: apiFetchModeSchema.default(FETCH_CONFIG_DEFAULTS.mode),
+	timeout: z.number().int().min(1000).max(60000).default(FETCH_CONFIG_DEFAULTS.timeout),
 	wait: z.number().int().min(0).max(30000).default(FETCH_CONFIG_DEFAULTS.wait),
 	headers: z.record(z.string(), z.string()).optional(),
 	cookies: z.record(z.string(), z.string()).optional(),
@@ -74,7 +74,6 @@ export const apiFetchConfigSchema = z.object({
 		.length(2)
 		.transform((v) => v.toLowerCase())
 		.optional(),
-	stealth: z.boolean().default(FETCH_CONFIG_DEFAULTS.stealth),
 	scrolls: z.number().int().min(0).max(100).default(FETCH_CONFIG_DEFAULTS.scrolls),
 	mock: z
 		.union([

src/types/index.ts

@@ -3,6 +3,7 @@ import type {
 	apiCrawlRequestSchema,
 	apiExtractRequestBaseSchema,
 	apiFetchConfigSchema,
+	apiFetchModeSchema,
 	apiHistoryFilterSchema,
 	apiHtmlModeSchema,
 	apiLlmConfigSchema,
@@ -18,6 +19,7 @@ export const DEFAULT_BASE_URL = "https://api.scrapegraphai.com";
 export type { ApiModelName } from "../models.js";
 
 export type ApiHtmlMode = z.infer<typeof apiHtmlModeSchema>;
+export type ApiFetchMode = z.infer<typeof apiFetchModeSchema>;
 
 export interface ClientConfig {
 	apiKey: string;

tests/client.test.ts

@@ -17,7 +17,7 @@ function mockApi(routes: Record<string, (req: Request) => Response | Promise<Res
 describe("scrapegraphai", () => {
 	test("scrape returns markdown + requestId", async () => {
 		const api = mockApi({
-			"/v2/scrape": () =>
+			"/api/v2/scrape": () =>
 				Response.json({ markdown: "# Hello" }, { headers: { "x-request-id": "req-1" } }),
 		});
 		const sgai = scrapegraphai({ apiKey: "test", baseUrl: api.url });
@@ -30,7 +30,7 @@ describe("scrapegraphai", () => {
 	test("extract sends prompt + schema", async () => {
 		let body: any;
 		const api = mockApi({
-			"/v2/extract": async (req) => {
+			"/api/v2/extract": async (req) => {
 				body = await req.json();
 				return Response.json({ json: { name: "Test" } }, { headers: { "x-request-id": "req-2" } });
 			},
@@ -48,7 +48,7 @@ describe("scrapegraphai", () => {
 	test("search sends query", async () => {
 		let body: any;
 		const api = mockApi({
-			"/v2/search": async (req) => {
+			"/api/v2/search": async (req) => {
 				body = await req.json();
 				return Response.json(
 					{ results: [{ url: "https://a.com" }] },
@@ -65,7 +65,7 @@ describe("scrapegraphai", () => {
 
 	test("credits returns balance", async () => {
 		const api = mockApi({
-			"/v2/credits": () =>
+			"/api/v2/credits": () =>
 				Response.json(
 					{ remainingCredits: 5000, totalCreditsUsed: 200 },
 					{ headers: { "x-request-id": "req-4" } },
@@ -79,7 +79,7 @@ describe("scrapegraphai", () => {
 
 	test("crawl.start returns job id", async () => {
 		const api = mockApi({
-			"/v2/crawl": () =>
+			"/api/v2/crawl": () =>
 				Response.json(
 					{ id: "crawl-123", status: "running" },
 					{ headers: { "x-request-id": "req-5" } },
@@ -93,7 +93,7 @@ describe("scrapegraphai", () => {
 
 	test("crawl.status returns status", async () => {
 		const api = mockApi({
-			"/v2/crawl/crawl-123": () =>
+			"/api/v2/crawl/crawl-123": () =>
 				Response.json(
 					{ id: "crawl-123", status: "completed", pages: [] },
 					{ headers: { "x-request-id": "req-6" } },
@@ -108,7 +108,7 @@ describe("scrapegraphai", () => {
 	test("crawl.stop sends POST", async () => {
 		let called = false;
 		const api = mockApi({
-			"/v2/crawl/crawl-123/stop": () => {
+			"/api/v2/crawl/crawl-123/stop": () => {
 				called = true;
 				return Response.json({ ok: true }, { headers: { "x-request-id": "req-7" } });
 			},
@@ -122,7 +122,7 @@ describe("scrapegraphai", () => {
 	test("monitor.create sends body", async () => {
 		let body: any;
 		const api = mockApi({
-			"/v2/monitor": async (req) => {
+			"/api/v2/monitor": async (req) => {
 				body = await req.json();
 				return Response.json({ id: "mon-1" }, { headers: { "x-request-id": "req-8" } });
 			},
@@ -141,7 +141,7 @@ describe("scrapegraphai", () => {
 	test("monitor.delete sends DELETE", async () => {
 		let method: string | undefined;
 		const api = mockApi({
-			"/v2/monitor/mon-1": (req) => {
+			"/api/v2/monitor/mon-1": (req) => {
 				method = req.method;
 				return Response.json({}, { headers: { "x-request-id": "req-9" } });
 			},
@@ -152,6 +152,20 @@ describe("scrapegraphai", () => {
 		api.stop();
 	});
 
+	test("scrape forwards fetchConfig.mode", async () => {
+		let body: any;
+		const api = mockApi({
+			"/api/v2/scrape": async (req) => {
+				body = await req.json();
+				return Response.json({ markdown: "ok" }, { headers: { "x-request-id": "req-fm" } });
+			},
+		});
+		const sgai = scrapegraphai({ apiKey: "test", baseUrl: api.url });
+		await sgai.scrape("https://example.com", { fetchConfig: { mode: "js+stealth" } });
+		expect(body.fetchConfig.mode).toBe("js+stealth");
+		api.stop();
+	});
+
 	test("history appends query params", async () => {
 		let requestUrl: string | undefined;
 		const server = Bun.serve({

tests/http.test.ts

@@ -41,6 +41,7 @@ describe("request", () => {
 		await request("GET", `${server.url}/test`, "my-api-key");
 		expect(capturedHeaders).toBeDefined();
 		expect(capturedHeaders?.get("authorization")).toBe("Bearer my-api-key");
+		expect(capturedHeaders?.get("sgai-apikey")).toBe("my-api-key");
 		expect(capturedHeaders?.get("x-sdk-version")).toContain("js@");
 		server.stop();
 	});