send session_id header on api requests

src/commands/monitor.ts

@@ -20,6 +20,7 @@ import * as fs from 'fs';
 import { Command } from 'commander';
 import { getConfig, validateConfig } from '../utils/config';
 import { writeOutput } from '../utils/output';
+import { getSessionHeaders } from '../utils/session-tracking';
 
 const DEFAULT_API_URL = 'https://api.firecrawl.dev';
 
@@ -63,6 +64,7 @@ async function monitorRequest(
   const headers: Record<string, string> = {
     Authorization: `Bearer ${apiKey}`,
     'X-Origin': 'cli',
+    ...getSessionHeaders(),
   };
   if (init.body !== undefined) headers['Content-Type'] = 'application/json';
 

src/commands/parse.ts

@@ -14,6 +14,7 @@ import type { ScrapeFormat } from '../types/scrape';
 import { getClient } from '../utils/client';
 import { getConfig, validateConfig } from '../utils/config';
 import { handleScrapeOutput } from '../utils/output';
+import { getSessionHeaders } from '../utils/session-tracking';
 
 const DEFAULT_API_URL = 'https://api.firecrawl.dev';
 
@@ -181,7 +182,10 @@ export async function executeParse(
   try {
     const response = await fetch(`${apiUrl}/v2/parse`, {
       method: 'POST',
-      headers: apiKey ? { Authorization: `Bearer ${apiKey}` } : undefined,
+      headers: {
+        ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+        ...getSessionHeaders(),
+      },
       body: form,
     });
 

src/utils/client.ts

@@ -11,9 +11,39 @@ import {
   updateConfig,
   type GlobalConfig,
 } from './config';
+import { getSessionHeaders } from './session-tracking';
 
 let clientInstance: Firecrawl | null = null;
 
+function attachSessionHeaders(client: Firecrawl): Firecrawl {
+  const headers = getSessionHeaders();
+  if (Object.keys(headers).length === 0) return client;
+
+  const httpClient = (
+    client as unknown as {
+      http?: {
+        instance?: {
+          defaults?: {
+            headers?: Record<string, unknown> & {
+              common?: Record<string, unknown>;
+            };
+          };
+        };
+      };
+    }
+  ).http;
+  const defaultHeaders = httpClient?.instance?.defaults?.headers;
+  if (!defaultHeaders) return client;
+
+  if (!defaultHeaders.common) {
+    defaultHeaders.common = {};
+  }
+  for (const [key, value] of Object.entries(headers)) {
+    (defaultHeaders.common as Record<string, unknown>)[key] = value;
+  }
+  return client;
+}
+
 /**
  * Get or create the Firecrawl client instance
  * Uses global configuration if available, otherwise creates with provided options
@@ -68,7 +98,7 @@ export function getClient(
       backoffFactor: options.backoffFactor ?? config.backoffFactor,
     };
 
-    return new Firecrawl(clientOptions);
+    return attachSessionHeaders(new Firecrawl(clientOptions));
   }
 
   // Return singleton instance or create one
@@ -84,7 +114,7 @@ export function getClient(
       backoffFactor: config.backoffFactor,
     };
 
-    clientInstance = new Firecrawl(clientOptions);
+    clientInstance = attachSessionHeaders(new Firecrawl(clientOptions));
   }
 
   return clientInstance;

src/utils/session-tracking.ts

@@ -0,0 +1,67 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { randomUUID } from 'crypto';
+import { getConfigDirectoryPath } from './credentials';
+
+const SESSION_FILE = 'session.json';
+const SESSION_TTL_MS = 30 * 60 * 1000;
+
+type StoredSession = { id: string; last_active_at: number };
+
+function sessionFilePath(): string {
+  return path.join(getConfigDirectoryPath(), SESSION_FILE);
+}
+
+function readSession(): StoredSession | null {
+  try {
+    const raw = fs.readFileSync(sessionFilePath(), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (
+      parsed &&
+      typeof parsed.id === 'string' &&
+      typeof parsed.last_active_at === 'number'
+    ) {
+      return parsed as StoredSession;
+    }
+  } catch {
+    // ignore
+  }
+  return null;
+}
+
+function writeSession(session: StoredSession): void {
+  try {
+    const dir = path.dirname(sessionFilePath());
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(sessionFilePath(), JSON.stringify(session));
+  } catch {
+    // best-effort
+  }
+}
+
+let cachedSessionId: string | null = null;
+
+export function getSessionId(): string {
+  if (cachedSessionId) return cachedSessionId;
+
+  const now = Date.now();
+  const existing = readSession();
+  const id =
+    existing && now - existing.last_active_at < SESSION_TTL_MS
+      ? existing.id
+      : randomUUID();
+
+  writeSession({ id, last_active_at: now });
+  cachedSessionId = id;
+  return id;
+}
+
+export type SessionHeaders = Record<string, string>;
+
+export function getSessionHeaders(): SessionHeaders {
+  return {
+    'x-firecrawl-session-id': getSessionId(),
+  };
+}