firecrawl 4.47.0 → 4.48.0

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   version
-} from "./chunk-H75FJ6LW.js";
+} from "./chunk-GD463K4D.js";
 
 // src/v2/utils/httpClient.ts
 import axios from "axios";
@@ -32,11 +32,13 @@ var HttpClient = class {
   apiUrl;
   maxRetries;
   backoffFactor;
+  origin;
   constructor(options) {
     this.apiKey = options.apiKey;
     this.apiUrl = options.apiUrl.replace(/\/$/, "");
     this.maxRetries = options.maxRetries ?? 3;
     this.backoffFactor = options.backoffFactor ?? 0.5;
+    this.origin = options.origin || `js-sdk@${getVersion()}`;
     this.instance = axios.create({
       baseURL: this.apiUrl,
       timeout: options.timeoutMs ?? 3e5,
@@ -55,13 +57,16 @@ var HttpClient = class {
   getApiKey() {
     return this.apiKey;
   }
+  /** The attribution origin stamped into requests that do not set their own. */
+  getOrigin() {
+    return this.origin;
+  }
   /** The client-wide default request timeout, for callers that need to
    * extend a specific request beyond it (e.g. scrape auto-resume). */
   getTimeoutMs() {
     return this.instance.defaults.timeout ?? 3e5;
   }
   async request(config) {
-    const version2 = getVersion();
     config.headers = {
       ...config.headers || {}
     };
@@ -76,7 +81,7 @@ var HttpClient = class {
           const data = cfg.data ?? {};
           cfg.data = {
             ...data,
-            origin: typeof data.origin === "string" && data.origin.includes("mcp") ? data.origin : `js-sdk@${version2}`
+            origin: typeof data.origin === "string" && data.origin ? data.origin : this.origin
           };
         }
         if (isFormDataBody) {
@@ -659,10 +664,9 @@ async function parse(http, file, options) {
     throw new Error("file data cannot be empty");
   }
   if (options) ensureValidParseOptions(options);
-  const version2 = getVersion();
   const normalizedOptions = {
     ...options ?? {},
-    origin: typeof options?.origin === "string" && options.origin.includes("mcp") ? options.origin : options?.origin ?? `js-sdk@${version2}`
+    origin: options?.origin || http.getOrigin()
   };
   const formData = new FormData();
   formData.append("options", JSON.stringify(normalizedOptions));
@@ -1780,8 +1784,8 @@ function appendParam(params, key, value) {
     params.append(key, String(value));
   }
 }
-function withQuery(path, params) {
-  params.append("origin", `js-sdk@${getVersion()}`);
+function withQuery(origin, path, params) {
+  params.append("origin", origin);
   const qs = params.toString();
   return qs ? `${path}?${qs}` : path;
 }
@@ -1836,7 +1840,7 @@ var ResearchClient = class {
     appendParam(params, "to", options.to);
     try {
       const res = await this.http.get(
-        withQuery(`${BASE}/papers`, params)
+        withQuery(this.http.getOrigin(), `${BASE}/papers`, params)
       );
       if (res.status !== 200) throwForBadResponse(res, "search papers");
       return res.data;
@@ -1854,7 +1858,13 @@ var ResearchClient = class {
     appendParam(params, "query", options.query);
     appendParam(params, "k", options.k);
     try {
-      const res = await this.http.get(withQuery(`${BASE}/papers/${encodeURIComponent(id)}`, params));
+      const res = await this.http.get(
+        withQuery(
+          this.http.getOrigin(),
+          `${BASE}/papers/${encodeURIComponent(id)}`,
+          params
+        )
+      );
       if (res.status !== 200) throwForBadResponse(res, "get paper");
       return res.data;
     } catch (err) {
@@ -1880,7 +1890,11 @@ var ResearchClient = class {
     appendParam(params, "anchor", options.anchor);
     try {
       const res = await this.http.get(
-        withQuery(`${BASE}/papers/${encodeURIComponent(id)}/similar`, params)
+        withQuery(
+          this.http.getOrigin(),
+          `${BASE}/papers/${encodeURIComponent(id)}/similar`,
+          params
+        )
       );
       if (res.status !== 200) throwForBadResponse(res, "find similar papers");
       return res.data;
@@ -1911,7 +1925,7 @@ var ResearchClient = class {
     appendParam(params, "k", options.k);
     try {
       const res = await this.http.get(
-        withQuery(`${BASE}/github`, params)
+        withQuery(this.http.getOrigin(), `${BASE}/github`, params)
       );
       if (res.status !== 200) throwForBadResponse(res, "search github");
       return res.data;
@@ -2041,6 +2055,67 @@ async function getMonitorCheck(http, monitorId, checkId, options) {
   }
 }
 
+// src/utils/callerOrigin.ts
+var NODE_MODULES = "/node_modules/";
+function packageOf(file) {
+  let path = file.replace(/^file:\/\//, "").replace(/\\/g, "/");
+  try {
+    path = decodeURIComponent(path);
+  } catch {
+  }
+  const at = path.lastIndexOf(NODE_MODULES);
+  if (at < 0) return null;
+  const [first, second] = path.slice(at + NODE_MODULES.length).split("/");
+  const name = first?.startsWith("@") ? second ? `${first}/${second}` : "" : first;
+  return name && !name.startsWith(".") ? name : null;
+}
+function frameFile(line) {
+  const text = line.trim().replace(/^at /, "");
+  const open = text.indexOf(" (");
+  const location = open >= 0 && text.endsWith(")") ? text.slice(open + 2, -1) : text;
+  const match = /^(.*):\d+:\d+$/.exec(location);
+  return match && !match[1].startsWith("node:") ? match[1] : null;
+}
+function slugify(name) {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 48).replace(/-+$/, "");
+}
+function detectCallerPackage(stack) {
+  try {
+    if (process.env.FIRECRAWL_DISABLE_CALLER_ORIGIN === "1") return null;
+    if (stack === void 0) {
+      const limit = Error.stackTraceLimit;
+      Error.stackTraceLimit = 50;
+      try {
+        stack = new Error().stack ?? "";
+      } finally {
+        Error.stackTraceLimit = limit;
+      }
+    }
+    let ownFile = null;
+    let ownPackage = null;
+    for (const line of stack.split("\n")) {
+      if (!/^\s*at /.test(line)) continue;
+      const file = frameFile(line);
+      if (!file) continue;
+      if (ownFile === null) {
+        ownFile = file;
+        ownPackage = packageOf(file);
+      }
+      if (file === ownFile) continue;
+      const name = packageOf(file);
+      if (name && name === ownPackage) continue;
+      const slug = name ? slugify(name) : "";
+      return slug && !slug.includes("playground") ? slug : null;
+    }
+  } catch {
+  }
+  return null;
+}
+function defaultOrigin(version2) {
+  const caller = detectCallerPackage();
+  return caller ? `js-sdk.${caller}@${version2}` : `js-sdk@${version2}`;
+}
+
 // src/v2/watcher.ts
 import { EventEmitter } from "events";
 var hasGlobalWebSocket = () => {
@@ -2303,7 +2378,8 @@ var FirecrawlClient = class {
       apiUrl,
       timeoutMs: opts.timeoutMs,
       maxRetries: opts.maxRetries,
-      backoffFactor: opts.backoffFactor
+      backoffFactor: opts.backoffFactor,
+      origin: opts.origin || defaultOrigin(getVersion())
     });
   }
   async scrape(url, options) {
@@ -2829,6 +2905,8 @@ var FirecrawlApp = class {
   apiKey;
   apiUrl;
   version = "1.25.1";
+  clientOrigin;
+  callerPackage;
   isCloudService(url) {
     return url.includes("api.firecrawl.dev");
   }
@@ -2837,7 +2915,7 @@ var FirecrawlApp = class {
       if (typeof process !== "undefined" && process.env && process.env.npm_package_version) {
         return process.env.npm_package_version;
       }
-      const packageJson = await import("./package-NZI5TDUV.js");
+      const packageJson = await import("./package-WONXBIJS.js");
       return packageJson.default.version;
     } catch (error) {
       const isTest = typeof process !== "undefined" && false;
@@ -2854,15 +2932,22 @@ var FirecrawlApp = class {
    * Initializes a new instance of the FirecrawlApp class.
    * @param config - Configuration options for the FirecrawlApp instance.
    */
-  constructor({ apiKey = null, apiUrl = null }) {
+  constructor({ apiKey = null, apiUrl = null, origin }) {
     const baseUrl = apiUrl || "https://api.firecrawl.dev";
     if (this.isCloudService(baseUrl) && typeof apiKey !== "string") {
       throw new FirecrawlError("No API key provided", 401);
     }
     this.apiKey = apiKey || "";
     this.apiUrl = baseUrl;
+    this.clientOrigin = origin || void 0;
+    this.callerPackage = this.clientOrigin ? null : detectCallerPackage();
     this.init();
   }
+  resolveOrigin(params) {
+    if (typeof params?.origin === "string" && params.origin) return params.origin;
+    if (this.clientOrigin) return this.clientOrigin;
+    return this.callerPackage ? `js-sdk.${this.callerPackage}@${this.version}` : `js-sdk@${this.version}`;
+  }
   /**
    * Scrapes a URL using the Firecrawl API.
    * @param url - The URL to scrape.
@@ -2874,7 +2959,7 @@ var FirecrawlApp = class {
       "Content-Type": "application/json",
       Authorization: `Bearer ${this.apiKey}`
     };
-    let jsonData = { url, ...params, origin: typeof params?.origin === "string" && params.origin.includes("mcp") ? params.origin : `js-sdk@${this.version}` };
+    let jsonData = { url, ...params, origin: this.resolveOrigin(params) };
     if (jsonData?.extract?.schema) {
       jsonData = {
         ...jsonData,
@@ -2938,7 +3023,7 @@ var FirecrawlApp = class {
       lang: params?.lang ?? "en",
       country: params?.country ?? "us",
       location: params?.location,
-      origin: typeof params?.origin === "string" && params.origin.includes("mcp") ? params.origin : `js-sdk@${this.version}`,
+      origin: this.resolveOrigin(params),
       timeout: params?.timeout ?? 6e4,
       scrapeOptions: params?.scrapeOptions ?? { formats: [] }
     };
@@ -2993,7 +3078,7 @@ var FirecrawlApp = class {
    */
   async crawlUrl(url, params, pollInterval = 2, idempotencyKey) {
     const headers = this.prepareHeaders(idempotencyKey);
-    let jsonData = { url, ...params, origin: typeof params?.origin === "string" && params.origin.includes("mcp") ? params.origin : `js-sdk@${this.version}` };
+    let jsonData = { url, ...params, origin: this.resolveOrigin(params) };
     try {
       const response = await this.postRequest(
         this.apiUrl + `/v1/crawl`,
@@ -3017,7 +3102,7 @@ var FirecrawlApp = class {
   }
   async asyncCrawlUrl(url, params, idempotencyKey) {
     const headers = this.prepareHeaders(idempotencyKey);
-    let jsonData = { url, ...params, origin: typeof params?.origin === "string" && params.origin.includes("mcp") ? params.origin : `js-sdk@${this.version}` };
+    let jsonData = { url, ...params, origin: this.resolveOrigin(params) };
     try {
       const response = await this.postRequest(
         this.apiUrl + `/v1/crawl`,
@@ -3176,7 +3261,7 @@ var FirecrawlApp = class {
    */
   async mapUrl(url, params) {
     const headers = this.prepareHeaders();
-    let jsonData = { url, ...params, origin: typeof params?.origin === "string" && params.origin.includes("mcp") ? params.origin : `js-sdk@${this.version}` };
+    let jsonData = { url, ...params, origin: this.resolveOrigin(params) };
     try {
       const response = await this.postRequest(
         this.apiUrl + `/v1/map`,
@@ -3205,7 +3290,7 @@ var FirecrawlApp = class {
    */
   async batchScrapeUrls(urls, params, pollInterval = 2, idempotencyKey, webhook, ignoreInvalidURLs, maxConcurrency) {
     const headers = this.prepareHeaders(idempotencyKey);
-    let jsonData = { urls, webhook, ignoreInvalidURLs, maxConcurrency, ...params, origin: typeof params?.origin === "string" && params.origin.includes("mcp") ? params.origin : `js-sdk@${this.version}` };
+    let jsonData = { urls, webhook, ignoreInvalidURLs, maxConcurrency, ...params, origin: this.resolveOrigin(params) };
     if (jsonData?.extract?.schema) {
       jsonData = {
         ...jsonData,
@@ -3247,7 +3332,7 @@ var FirecrawlApp = class {
   }
   async asyncBatchScrapeUrls(urls, params, idempotencyKey, webhook, ignoreInvalidURLs) {
     const headers = this.prepareHeaders(idempotencyKey);
-    let jsonData = { urls, webhook, ignoreInvalidURLs, ...params, origin: typeof params?.origin === "string" && params.origin.includes("mcp") ? params.origin : `js-sdk@${this.version}` };
+    let jsonData = { urls, webhook, ignoreInvalidURLs, ...params, origin: this.resolveOrigin(params) };
     try {
       const response = await this.postRequest(
         this.apiUrl + `/v1/batch/scrape`,
@@ -3391,7 +3476,7 @@ var FirecrawlApp = class {
     try {
       const response = await this.postRequest(
         this.apiUrl + `/v1/extract`,
-        { ...jsonData, schema: jsonSchema, origin: typeof params?.origin === "string" && params.origin.includes("mcp") ? params.origin : `js-sdk@${this.version}` },
+        { ...jsonData, schema: jsonSchema, origin: this.resolveOrigin(params) },
         headers
       );
       if (response.status === 200) {
@@ -3444,7 +3529,7 @@ var FirecrawlApp = class {
     try {
       const response = await this.postRequest(
         this.apiUrl + `/v1/extract`,
-        { ...jsonData, schema: jsonSchema, origin: typeof params?.origin === "string" && params.origin.includes("mcp") ? params.origin : `js-sdk@${this.version}` },
+        { ...jsonData, schema: jsonSchema, origin: this.resolveOrigin(params) },
         headers
       );
       if (response.status === 200) {
@@ -3726,7 +3811,7 @@ var FirecrawlApp = class {
    */
   async asyncDeepResearch(query, params) {
     const headers = this.prepareHeaders();
-    let jsonData = { query, ...params, origin: typeof params?.origin === "string" && params.origin.includes("mcp") ? params.origin : `js-sdk@${this.version}` };
+    let jsonData = { query, ...params, origin: this.resolveOrigin(params) };
     if (jsonData?.jsonOptions?.schema) {
       jsonData = {
         ...jsonData,
@@ -3845,7 +3930,7 @@ var FirecrawlApp = class {
   async __asyncDeepResearch(topic, params) {
     const headers = this.prepareHeaders();
     try {
-      let jsonData = { topic, ...params, origin: typeof params?.origin === "string" && params.origin.includes("mcp") ? params.origin : `js-sdk@${this.version}` };
+      let jsonData = { topic, ...params, origin: this.resolveOrigin(params) };
       const response = await this.postRequest(
         `${this.apiUrl}/v1/deep-research`,
         jsonData,
@@ -3945,7 +4030,7 @@ var FirecrawlApp = class {
    */
   async asyncGenerateLLMsText(url, params) {
     const headers = this.prepareHeaders();
-    let jsonData = { url, ...params, origin: typeof params?.origin === "string" && params.origin.includes("mcp") ? params.origin : `js-sdk@${this.version}` };
+    let jsonData = { url, ...params, origin: this.resolveOrigin(params) };
     try {
       const response = await this.postRequest(
         `${this.apiUrl}/v1/llmstxt`,
@@ -4213,7 +4298,8 @@ var Firecrawl = class extends FirecrawlClient {
     super(resolved);
     this._v1Opts = {
       apiKey: resolved.apiKey,
-      apiUrl: resolved.apiUrl
+      apiUrl: resolved.apiUrl,
+      origin: this.http.getOrigin()
     };
   }
   /** Access the legacy v1 client (instantiated on first access). */

package/dist/{package-NZI5TDUV.js → package-WONXBIJS.js}

@@ -17,7 +17,7 @@ import {
   type,
   types,
   version
-} from "./chunk-H75FJ6LW.js";
+} from "./chunk-GD463K4D.js";
 export {
   author,
   bugs,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firecrawl",
-  "version": "4.47.0",
+  "version": "4.48.0",
   "description": "JavaScript SDK for the Firecrawl API: web scraping, crawling, web search, and scientific literature search over a research paper index of PubMed, bioRxiv, medRxiv and arXiv abstracts",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/__tests__/unit/v2/agent-hints.test.ts

@@ -14,6 +14,7 @@ const hints = [
 ];
 function httpFor(body: object) {
   return {
+    getOrigin: () => "js-sdk@test",
     post: vi.fn<any>().mockResolvedValue({ status: 200, data: body }),
     postMultipart: vi
       .fn<any>()

package/src/__tests__/unit/v2/origin.test.ts

@@ -0,0 +1,132 @@
+import { afterEach, beforeEach, describe, test, expect } from "vitest";
+import type { AxiosAdapter } from "axios";
+import { FirecrawlClient } from "../../../v2/client";
+import { Firecrawl } from "../../../index";
+import { getVersion } from "../../../v2/utils/getVersion";
+import { detectCallerPackage } from "../../../utils/callerOrigin";
+
+function withCapture<T extends { http: any }>(client: T) {
+  const bodies: Array<Record<string, unknown>> = [];
+  const adapter: AxiosAdapter = async config => {
+    bodies.push(JSON.parse(config.data));
+    return {
+      data: { success: true, data: { markdown: "# hello" } },
+      status: 200,
+      statusText: "OK",
+      headers: {},
+      config,
+    };
+  };
+  client.http.instance.defaults.adapter = adapter;
+  return { client, bodies };
+}
+
+describe("v2 request origin", () => {
+  const previousOptOut = process.env.FIRECRAWL_DISABLE_CALLER_ORIGIN;
+  afterEach(() => {
+    if (previousOptOut === undefined) {
+      delete process.env.FIRECRAWL_DISABLE_CALLER_ORIGIN;
+    } else {
+      process.env.FIRECRAWL_DISABLE_CALLER_ORIGIN = previousOptOut;
+    }
+  });
+
+  test("defaults to the plain SDK origin when application code creates the client", async () => {
+    const { client, bodies } = withCapture(new FirecrawlClient({ apiKey: "fc-test" }));
+    await client.scrape("https://example.com");
+    expect(bodies[0]!.origin).toBe(`js-sdk@${getVersion()}`);
+  });
+
+  test("the origin client option is stamped into request bodies", async () => {
+    const { client, bodies } = withCapture(
+      new FirecrawlClient({ apiKey: "fc-test", origin: "js-sdk.example@1.0.0" }),
+    );
+    await client.scrape("https://example.com");
+    expect(bodies[0]!.origin).toBe("js-sdk.example@1.0.0");
+  });
+
+  test("a per-call origin wins over the client origin", async () => {
+    const { client, bodies } = withCapture(
+      new FirecrawlClient({ apiKey: "fc-test", origin: "js-sdk.example@1.0.0" }),
+    );
+    await client.scrape("https://example.com", { origin: "per-call" } as any);
+    await client.scrape("https://example.com", { origin: "mcp-server" } as any);
+    expect(bodies.map(b => b.origin)).toEqual(["per-call", "mcp-server"]);
+  });
+
+  test("the unified client forwards the origin option to v1", () => {
+    const app = new Firecrawl({ apiKey: "fc-test", origin: "js-sdk.example@1.0.0" });
+    expect((app.v1 as any).clientOrigin).toBe("js-sdk.example@1.0.0");
+  });
+
+});
+
+describe("detectCallerPackage", () => {
+  const sdkFrames = [
+    "Error",
+    "    at detectCallerPackage (file:///srv/app/node_modules/@mendable/firecrawl-js/dist/index.js:10:5)",
+    "    at new FirecrawlClient (file:///srv/app/node_modules/@mendable/firecrawl-js/dist/index.js:20:9)",
+  ];
+  const stackFrom = (...callers: string[]) =>
+    [...sdkFrames, ...callers.map(c => `    at ${c}`)].join("\n");
+  const previousOptOut = process.env.FIRECRAWL_DISABLE_CALLER_ORIGIN;
+
+  beforeEach(() => {
+    delete process.env.FIRECRAWL_DISABLE_CALLER_ORIGIN;
+  });
+
+  afterEach(() => {
+    if (previousOptOut === undefined) {
+      delete process.env.FIRECRAWL_DISABLE_CALLER_ORIGIN;
+    } else {
+      process.env.FIRECRAWL_DISABLE_CALLER_ORIGIN = previousOptOut;
+    }
+  });
+
+  test("names the scoped package that created the client", () => {
+    const stack = stackFrom(
+      "make (file:///srv/app/node_modules/@Scope/Some_Agent/dist/index.js:3:12)",
+      "main (file:///srv/app/src/main.js:1:1)",
+    );
+    expect(detectCallerPackage(stack)).toBe("scope-some-agent");
+  });
+
+  test("uses the last node_modules segment of a nested install", () => {
+    const stack = stackFrom(
+      "make (/srv/app/node_modules/.pnpm/outer@1.0.0/node_modules/inner-pkg/lib/index.cjs:3:12)",
+    );
+    expect(detectCallerPackage(stack)).toBe("inner-pkg");
+  });
+
+  test("handles windows paths with parentheses and anonymous frames", () => {
+    const stack = stackFrom(
+      "Array.map (<anonymous>)",
+      "C:\\Program Files (x86)\\app\\node_modules\\wrapper\\index.js:4:2",
+    );
+    expect(detectCallerPackage(stack)).toBe("wrapper");
+  });
+
+  test("returns null when application code created the client", () => {
+    const stack = stackFrom(
+      "main (file:///srv/app/src/main.js:1:1)",
+      "make (file:///srv/app/node_modules/wrapper/index.js:3:12)",
+    );
+    expect(detectCallerPackage(stack)).toBeNull();
+  });
+
+  test("returns null for a package whose slug would read as another traffic class", () => {
+    const stack = stackFrom("make (/srv/app/node_modules/my-playground-kit/index.js:3:12)");
+    expect(detectCallerPackage(stack)).toBeNull();
+  });
+
+  test("returns null for a bundle without node_modules in its path", () => {
+    expect(detectCallerPackage(stackFrom("make (/srv/app/dist/bundle.js:1:1)"))).toBeNull();
+  });
+
+  test("FIRECRAWL_DISABLE_CALLER_ORIGIN turns detection off", () => {
+    const stack = stackFrom("make (/srv/app/node_modules/wrapper/index.js:3:12)");
+    expect(detectCallerPackage(stack)).toBe("wrapper");
+    process.env.FIRECRAWL_DISABLE_CALLER_ORIGIN = "1";
+    expect(detectCallerPackage(stack)).toBeNull();
+  });
+});

package/src/__tests__/unit/v2/research.test.ts

@@ -12,6 +12,7 @@ function makeClient(
 ) {
   const calls: string[] = [];
   const http = {
+    getOrigin: () => "js-sdk@test",
     get: async (url: string) => {
       calls.push(url);
       return responder(url);

package/src/index.ts

@@ -37,6 +37,7 @@ export class Firecrawl extends V2 {
     this._v1Opts = {
       apiKey: resolved.apiKey,
       apiUrl: resolved.apiUrl,
+      origin: this.http.getOrigin(),
     };
   }
 

package/src/utils/callerOrigin.ts

@@ -0,0 +1,74 @@
+const NODE_MODULES = "/node_modules/";
+
+function packageOf(file: string): string | null {
+  let path = file.replace(/^file:\/\//, "").replace(/\\/g, "/");
+  try {
+    path = decodeURIComponent(path);
+  } catch {}
+  const at = path.lastIndexOf(NODE_MODULES);
+  if (at < 0) return null;
+  const [first, second] = path.slice(at + NODE_MODULES.length).split("/");
+  const name = first?.startsWith("@") ? (second ? `${first}/${second}` : "") : first;
+  return name && !name.startsWith(".") ? name : null;
+}
+
+/** File of a V8 stack line, or null for frames without one (native, anonymous, runtime internals). */
+function frameFile(line: string): string | null {
+  const text = line.trim().replace(/^at /, "");
+  const open = text.indexOf(" (");
+  const location = open >= 0 && text.endsWith(")") ? text.slice(open + 2, -1) : text;
+  const match = /^(.*):\d+:\d+$/.exec(location);
+  return match && !match[1]!.startsWith("node:") ? match[1]! : null;
+}
+
+// Downstream surface classification matches "playground" anywhere in an origin.
+function slugify(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48)
+    .replace(/-+$/, "");
+}
+
+/**
+ * Slug of the installed package that created the client, or null when the
+ * caller is application code or detection is disabled. Never throws.
+ */
+export function detectCallerPackage(stack?: string): string | null {
+  try {
+    if (process.env.FIRECRAWL_DISABLE_CALLER_ORIGIN === "1") return null;
+    if (stack === undefined) {
+      const limit = Error.stackTraceLimit;
+      Error.stackTraceLimit = 50;
+      try {
+        stack = new Error().stack ?? "";
+      } finally {
+        Error.stackTraceLimit = limit;
+      }
+    }
+    let ownFile: string | null = null;
+    let ownPackage: string | null = null;
+    for (const line of stack.split("\n")) {
+      if (!/^\s*at /.test(line)) continue;
+      const file = frameFile(line);
+      if (!file) continue;
+      if (ownFile === null) {
+        ownFile = file;
+        ownPackage = packageOf(file);
+      }
+      if (file === ownFile) continue;
+      const name = packageOf(file);
+      if (name && name === ownPackage) continue;
+      const slug = name ? slugify(name) : "";
+      return slug && !slug.includes("playground") ? slug : null;
+    }
+  } catch {}
+  return null;
+}
+
+/** Origin sent with requests: `js-sdk@<version>`, or `js-sdk.<package>@<version>` for wrapper libraries. */
+export function defaultOrigin(version: string): string {
+  const caller = detectCallerPackage();
+  return caller ? `js-sdk.${caller}@${version}` : `js-sdk@${version}`;
+}