feat: add UTM tracking for agent hosting and IronClaw URLs (#351)

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: italic-jinxin

src/api/constants.ts

@@ -1,3 +1,5 @@
+import { withUtm } from "@/lib/utm";
+
 export const APP_NAME = "NEAR AI Private Chat";
 // TODO: remove DEPRECATED_API_BASE_URL from the project as there's no dependency on the legacy Private Chat any more
 export const DEPRECATED_API_BASE_URL = (import.meta.env.VITE_DEPRECATED_API_URL || "https://private-chat-legacy.near.ai").replace(
@@ -40,5 +42,6 @@ export const NEAR_RPC_URL = import.meta.env.VITE_NEAR_RPC_URL || "https://free.r
 export const NEAR_AI_CLOUD_MODELS_URL = "https://cloud.near.ai/models";
 
 export const AGENT_HOST = "agent.near.ai";
-export const AGENT_URL = `https://${AGENT_HOST}`;
-export const AGENT_BILLING_URL = `https://${AGENT_HOST}/billing`;
+
+export const AGENT_URL = withUtm(`https://${AGENT_HOST}`);
+export const AGENT_BILLING_URL = withUtm(`https://${AGENT_HOST}/billing`);

src/lib/constants.ts

@@ -1,3 +1,5 @@
+import { withUtm } from "@/lib/utm";
+
 export const LOCAL_STORAGE_KEYS = {
   TOKEN: "sessionToken",
   SESSION: "sessionId",
@@ -58,4 +60,4 @@ export const SUPPORTED_TEXT_EXTENSIONS = [
 export const ACCEPTED_FILE_TYPES = SUPPORTED_TEXT_EXTENSIONS.join(",");
 // export const ACCEPTED_FILE_TYPES = [".pdf", ...SUPPORTED_TEXT_EXTENSIONS].join(",");
 
-export const IRONCLAW_URL = "https://www.ironclaw.com";
+export const IRONCLAW_URL = withUtm("https://www.ironclaw.com/");

src/lib/utm.ts

@@ -0,0 +1,31 @@
+export const UTM_SOURCE = "private_chat";
+export const UTM_MEDIUM = "web";
+
+/**
+ * Adds default UTM parameters to a URL string.
+ *
+ * - Sets `utm_source` and `utm_medium` only when the corresponding query
+ *   parameters are missing (e.g. `?utm_source=` is considered "present" and
+ *   will not be overwritten).
+ * - If the value cannot be parsed as a URL, the original `url` string is
+ *   returned unchanged.
+ *
+ * @param url - A URL (absolute or relative) to augment.
+ * @param base - Optional base used to resolve `url` when it's relative.
+ * @returns The augmented URL as a string, or the original input on parse failure.
+ */
+export function withUtm(url: string, base?: string) {
+  let u: URL;
+  try {
+    u = base ? new URL(url, base) : new URL(url);
+  } catch (error) {
+    console.error(
+      `[withUtm] Failed to construct URL from value: "${url}". Returning original string.`,
+      error
+    );
+    return url;
+  }
+  if (!u.searchParams.has("utm_source")) u.searchParams.set("utm_source", UTM_SOURCE);
+  if (!u.searchParams.has("utm_medium")) u.searchParams.set("utm_medium", UTM_MEDIUM);
+  return u.toString();
+}