@ooky/sdk 0.1.0 → 0.6.0

package/src/referrals.js

@@ -0,0 +1,73 @@
+/**
+ * AI referrer detection — identifies humans arriving from AI platforms by
+ * Referer header or utm_source. Mirrors worker/src/referrals.js so the SDK
+ * and Worker tiers attribute the same visits; when you add a platform to
+ * one, add it to the other.
+ */
+
+export const AI_REFERRERS = [
+  { pattern: "chatgpt.com", source: "chatgpt" },
+  { pattern: "chat.openai.com", source: "chatgpt" },
+  { pattern: "perplexity.ai", source: "perplexity" },
+  { pattern: "gemini.google.com", source: "gemini" },
+  { pattern: "bard.google.com", source: "gemini" },
+  { pattern: "copilot.microsoft.com", source: "copilot" },
+  { pattern: "bing.com/chat", source: "copilot" },
+  { pattern: "claude.ai", source: "claude" },
+  { pattern: "meta.ai", source: "meta_ai" },
+  { pattern: "grok.x.ai", source: "grok" },
+  { pattern: "you.com", source: "you" },
+  { pattern: "phind.com", source: "phind" },
+  { pattern: "deepseek.com", source: "deepseek" },
+];
+
+export const UTM_SOURCES = [
+  { value: "chatgpt", source: "chatgpt" },
+  { value: "openai", source: "chatgpt" },
+  { value: "perplexity", source: "perplexity" },
+  { value: "gemini", source: "gemini" },
+  { value: "copilot", source: "copilot" },
+  { value: "claude", source: "claude" },
+  { value: "meta_ai", source: "meta_ai" },
+  { value: "grok", source: "grok" },
+  { value: "you", source: "you" },
+  { value: "phind", source: "phind" },
+  { value: "deepseek", source: "deepseek" },
+];
+
+/**
+ * Detect an AI-platform referral from a Referer header and/or utm_source.
+ *
+ * @param {string|null|undefined} referer  The request's Referer header.
+ * @param {string|null|undefined} utmSource  The utm_source query param value.
+ * @returns {{ source: string, referrerUrl: string|null, method: string } | null}
+ */
+export function detectAIReferral(referer, utmSource) {
+  if (referer && typeof referer === "string") {
+    const refererLower = referer.toLowerCase();
+    for (const entry of AI_REFERRERS) {
+      if (refererLower.includes(entry.pattern)) {
+        return {
+          source: entry.source,
+          referrerUrl: referer,
+          method: "referer_header",
+        };
+      }
+    }
+  }
+
+  if (utmSource && typeof utmSource === "string") {
+    const value = utmSource.toLowerCase();
+    for (const entry of UTM_SOURCES) {
+      if (value === entry.value) {
+        return {
+          source: entry.source,
+          referrerUrl: null,
+          method: "utm_param",
+        };
+      }
+    }
+  }
+
+  return null;
+}